FMI Library: part of JModelica.org
FMI Library: part of JModelica.org
Version
2.0.2
Date
30 September 2016

Summary

FMI library is intended as a foundation for applications interfacing FMUs (Functional Mockup Units) that follow FMI Standard. This version of the library supports FMI 1.0 and FMI2.0. See http://www.fmi-standard.org/

The test codes provided with the library can serve as starting point for the development of custom applications. See Section Automatic tests for details.

Configuring and building

CMake (see http://www.cmake.org/) is used to generate the native build scripts for the library. It is recommended to use "cmake-gui" on Windows or "ccmake <FMIL source dir>" to configure the build. All the required third party libraries are included into the distribution.

CMake 2.8.6 is required since this is the version used in development both on Windows and Linux. The build script is KNOWN NOT TO WORK WITH CMake 2.8.3 and below (due to ExternalProject interface changes). CMake 2.8.4 and 2.8.5 are not tested.

To build from a terminal command line on Linux or Mac with default settings use:

mkdir build-fmil; cd build-fmil
cmake -DFMILIB_INSTALL_PREFIX=<prefix> <path to FMIL source>
make install test

To build in MSYS terminal with g++/gcc on Windows:

mkdir build-fmil; cd build-fmil
cmake -DFMILIB_INSTALL_PREFIX=<prefix> -G "MSYS Makefiles" <path to FMIL source>
make install test

To build from command line with Microsoft Visual Studio compilers on Windows:

mkdir build-fmil; cd build-fmil
cmake -DFMILIB_INSTALL_PREFIX=<prefix> -G "Visual Studio 10" <path to FMIL source>
cmake --build . --config MinSizeRel --target install

The primary targets of the library build script are:

The following build configuration options are provided:

Automatic tests

The FMI library comes with a number of automatic tests. Building of the test is controlled by FMILIB_BUILD_TESTS configuration option. The test porgrams are also intended as examples of library usage.
The tests can be run in Visual Studio by building project RUN_TESTS. For Makefile based configurations (MSYS, Linux, Mac OSx) run 'make test'.
Output from the test programs and test logs can be found in the Testing folder in the build directory.

The supplied tests are:

Using logs

In the text below we consider an FMU importing application (referenced as an 'application') that uses the FMIL. The library is designed to send log messages to a logger callback function jm_logger_f provided as a part of jm_callbacks structure in the call to fmi_import_allocate_context(). The logging/error reporting functions within FMIL support following modes:

  1. An importing application relies on default logging functions provided by FMIL and only chooses the log-level
  2. An application provides a callback for reporting error messages according to jm_callbacks.h (jm_logger_f)
    • Only errors from FMIL can be propagated to this callback in a thread-safe manner for FMI1. Imported FMUs may still use the default callback provided by the library. This is since logger function in FMI 1.0 standard is context independent. The non-thread safe implementation on the FMI1 callback can be found in fmi1_import_convenience.h fmi1_log_forwarding().
      In FMI 2 the fmiComponentEnvironment can be utilized to forward messages from the default fmi2 logger function as provided by the library to the user defined jm_logger_f function. The fmi2_log_forwarding() function expects the context to be set to fmi2_import_t.
  3. An importing application provides logging function according to the specific FMI standard version.
    • Errors from FMIL may be forwarded to this callback. There is a function that translates calls according to jm_callbacks.h jm_logger_f into calls according to fmi_functions.h fmi_callbacks_logger_ft (see fmi1_import_init_logger() or fmi2_import_init_logger() that are used to setup 'forwarding').
      Setting of the callback can only be done at the stage where FMU standard is known.
  4. An importing application may choose not to use logging function but rely on return codes and jm_get_last_error()
    • jm_logger function should be set to NULL
    • Errors from a FMI 1.0 fmu1 cannot be handled this way in a thread-safe way (see point 2 above). It works fine with FMI 2.0.

License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Acknowledgements

The FMI Library utilizes contains code from third party tools and packages. The respective copyright information and licenses are listed with URL references to the full texts.