boschresearch / fmi_adapter

Integrating functional mock-up units (FMUs) in ROS nodes

The fmi_adapter repository

This repository provides the fmi_adapter package for wrapping functional mockup units (FMUs) for co-simulation of physical models into ROS 2 nodes, i.e. for the version ROS 2. The implementation for the first generation of ROS can be found in the melodic_and_noetic branch.

FMUs are defined in the FMI standard and can be created with a variety of modeling and simulation tools, including Dymola, MATLAB/Simulink, OpenModelica, SimulationX, and Wolfram System Modeler.

fmi_adapter provides a library with convenience functions based on common ROS types to load an FMU during runtime, retrieve the input, output, and parameter names, set timestamped input values, run the FMU's numeric solver, and query the resulting output.

In detail, this repository contains two ROS 2 packages:

• fmi_adapter provides a generic library and node for loading and running FMUs in ROS-based applications.
• fmi_adapter_examples provides small examples for the use of fmi_adapter.

Technical information on the interfaces and use of these packages is given in the README.md files in the corresponding subfolders.

Purpose of the project

The software is not ready for production use. It has neither been developed nor tested for a specific use case. However, the license conditions of the applicable Open Source licenses allow you to adapt the software to your needs. Before using it in a safety relevant setting, make sure that the software fulfills your requirements and adjust it according to any applicable safety standards (e.g. ISO 26262).

Requirements, how to build, test, install, use, etc.

Clone the repository into a ROS workspace and build it using colcon.

License

fmi_adapter is open-sourced under the Apache-2.0 license. See the LICENSE file for details.

For a list of other open source components included in fmi_adapter, see the file 3rd-party-licenses.txt.

Quality assurance

The colcon_test tool is used for quality assurances, which includes cpplint, uncrustify, flake8, xmllint and various other tools.

Unit tests based on gtest are located in the fmi_adapter/test folder. The unit tests use an FMU created with the FMU SDK by QTronic GmbH, cf. 3rd-party-licenses.txt.

Known issues/limitations

Please notice the following issues/limitations:

• fmi_adapter only supports FMUs according to the FMI 2.0 standard.
• fmi_adapter treats all inputs, outputs and parameters of a given FMU as floating-point values (ROS message std_msgs::msg::Float64, C++ type double, FMI type fmi2fmi2_real_t).
• A possible end time specified in an FMU is not considered, i.e., the FMU is being evaluated constantly until the corresponding ROS node is shutdown.

Papers

If you want to cite this repository/package, please cite the following book chapter (PDF available at Springer Link) instead:

Ralph Lange, Silvio Traversaro, Oliver Lenord, and Christian Bertsch: Integrating the Functional Mock-Up Interface with ROS and Gazebo. In: Anis Koubaa (ed.) Robot Operating System (ROS): The Complete Reference (Volume 5), Springer, pp. 187–231, 2021.

@INBOOK{Lange_et_al_2021_Integrating_the_FMI_with_ROS_and_Gazebo,
  author = {Ralph Lange and Silvio Traversaro and Oliver Lenord and Christian Bertsch},
  title = {Integrating the Functional Mock-Up Interface with ROS and Gazebo},
  editor = {Anis Koubaa},
  booktitle = {Robot Operating System (ROS): The Complete Reference (Volume 5)},
  year = {2021},
  publisher = {Springer},
  pages = {187--231},
  doi = {10.1007/978-3-030-45956-7_7}
}

fmi_adapter's Issues

Using custom ROS messages

Hello Mr.Lange,

I would like to know if there is a python wrapper available for the C++ FMIAdapter class. I want to publish to inputs of the FMU and subscribe to FMU outputs through my python code. If I understand correctly, the FMIAdapter class creates individual subscribers and publishers from vectorized signals of FMU. If I use the FMIAdapter class, I can only create individual subscribers and publishers right? So, when you say that "It allows to map the inputs and outputs of an FMU to complex message types and gives more control on the execution" in #4 , do you mean, that I can provide timestamps to the inputs through the setInputValue method? If there are a large number of inputs and outputs, that many subscribers and publishers are unavoidable right? In LibraryUsage step 3, can the subscriber read data from other message types instead of Float64? (By other message types, I mean, a custom message consisting of timestamp and multiple Float64 data fields). I basically want to group the data and publish, subscribe to them synchronously at the same time. By using the FMI adapter node, I have to do it one by one without any control over their timestamps.

Sorry for the inconvenience, I am a beginner in ROS and have little knowledge of C++. I would really appreciate it if you can give hints about these things.

Thank you
Sandeep

End time in FMU is not considered

From https://stackoverflow.com/questions/72374492/one-time-fmu-execution-with-fmi-adapter:

An end time (t_end) specified in an FMU is not considered by the fmi_adapter but the FMU is being evaluated constantly, i.e., it never finishes.

Feature Request: Support Model Exchange FMUs

Currently, fmi_adapter supports Co-Simulation FMUs (CS FMUs) only. Is there a possibility to integrate an open-source solver in a generic way so that Model Exchange FMUs (ME FMUs) can be supported as well? Does the underlying fmi-library feature suitable solver algorithms as suggested by the unit test fmi2_import_me_test.c.

Given FMU file '' not found or cannot be read!

Hello again

I have trouble changing state of the fmi_adapter node from unconfigured to the configured (and later active).

yaml file with params :

fmi_adapter_node:
¨¨¨¨¨¨ros__parameters:
¨¨¨¨¨¨¨¨¨¨fmu_path: "/tmp/OpenModelica_ros123/OMEdit/DampedPendulum/DampedPendulum.fmu"

Steps I tried :

1. ros2 run fmi_adapter fmi_adapter_node __params:=my_params.yaml (my_params.yaml file is in the directory where I executed command, it is populated as explained in the paper cited in the README file and shown above [I tried with different quotes and without quotes])
2. Second terminal : ros2 lifecycle set /fmi_adapter_node configure

After step 2, in the second terminal I got the error Transitioning failed and in the first terminal I got errors :

[ERROR]... Caught exception in callback for transition 10
[ERROR]... Original error: Given FMU file '' not found or cannot be read!
[WARN].... Error occurred while doing error handling.

Based on the error, it seems like I didn't set correctly path to the FMU file but I don't know what is wrong

Alternatively, running through launch works :

ros2 launch fmi_adapter fmi_adapter_node.launch.py fmu_path:=/tmp/OpenModelica_ros123/OMEdit/DampedPendulum/DampedPendulum.fmu

This way, I can see output with ros2 topic echo /revolute1_angle

Using binary installation option failed

Thanks for taking time to maintain this repository. I am trying to reproduce results from the paper referred to in the Readme file and I have encountered error when I try to launch simple damped pendulum example.

OS: Ubuntu 20.04.2 LTS
ROS_VERSION=2
ROS_PYTHON_VERSION=3
ROS_DISTRO=foxy

I have installed fmi_adapter and fmi_adapter_examples packages using command :

sudo apt install ros-foxy-fmi-adapter ros-foxy-fmi-adapter-examples and then tried to launch example with :

ros2 launch fmi_adapter_examples simple_damped_pendulum.launch.py.

This fails with the error : Package 'fmi_adapter_examples' not found: "package 'fmi_adapter_examples' not found, searching: ['/home/ros123/ros2_foxy/ros2-linux']"

I can verify that packages fmi_adapter and fmi_adapter_examples are not present in my ~/ros123/ros2_foxy/ros2-linux/share directory. Also, running locate DampedPendulum.fmu gives me one result : /opt/ros/foxy/share/fmi_adapter_examples/share/DampedPendulum.fmu

How can I fix this? What did I miss? I tried to copy fmi_adapter and fmi_adapter_examples directories from /opt/... to my ros2 installation directory.../.../share but with no luck (I guess it's required to update one or more files to tell ROS about those packages)

Quick side note: I used apt install ros-foxy-turtlesim to install turtlesim package and that worked out of the box so I don't see why this package does not work

example launch files reference incorrect subdirectory

Great fmi_adapter, thanks so much!

Had to edit launch files to reference the /share subdirectory in order to execute their correct .fmu
for example,

fmi_adapter node crashes with new parameter API in Galactic

When running the fmi_adapter node, it crashes immediately during lifecycle transition CONFIGURE with the following error message:

[fmi_adapter_node] [ERROR] [..] []: Caught exception in callback for transition 10
[fmi_adapter_node] [ERROR] [..] []: Original error: parameter 'x' has invalid
     type: cannot declare a statically typed parameter with an uninitialized value

The reason is the recent change in the rclcpp parameter API, cf. https://github.com/ros2/rclcpp/blob/galactic/rclcpp/doc/notes_on_statically_typed_parameters.md.

A fix is on the the way ...

Remove (or reduce) warnings that simulation time is greater than timer's time

The FMIAdapterNode uses a standard ROS timer to advance the FMU simulation. If the timer's period is not much greater than the simulation step-size but close to it, the FMIAdapterNode frequently emits a warning "Simulation time [..] is greater than timer's time [..]. Is your step size to large?" as an info-level log message.

Explanation

Internally, the timer callback of FMIAdapterNode calls FMIAdapter::doStepsUntil(..) with the current ROS time obtained from Node::now(). Given this current ROS time, the function FMIAdapter::doStepsUntil(..) performs simulation steps until a time-point between now() - step_size/2 and now() + step_size/2 is reached, i.e., it rounds to the closest step-size.

If in the next invocation of the timer callback the current ROS time now() is still smaller than the time-point until the FMU simulation was advanced in the previous invocation, then the timer callback emits the warning stated above. This happens especially if the timer period is only slightly larger than the step-size and if the processing of the timer callback is preempted by other processes or threads.

Possible fixes

1. Remove the warning completely.
2. Reduce the number of warnings (e.g., only a first time and then only once per minute).

Notes

Independent of this warning: If FMIAdapter::doStepsUntil(..) is called with an older time-point that would cause a backward step, a runtime error is thrown.

Error instantiating complex CoSim FMU

When attempting to initialise a Co-Simulation FMU (with CVode solver) using the fmi_adapter an error occurs during the fmi2_import_instantiate() call (part of the FMIAdapter constructor). This FMU runs in other packages without error, but in this package it throws the error below which has been tracked to the sundials library relating to a missing Linear Solver:
[CVLS ERROR] CVodeSetLinearSolver: LS must be non-NULL

I propose that this is occurring because the fmuLocation in the FMIAdapter script is set to NULL and is causing the resource folder of the CoSim FMU to not be found:
jmStatus = fmi2_import_instantiate(fmu_, instanceName, fmi2_cosimulation, fmuLocation, visible);

Is it possible that the fmu passed into this function would not be fully unzipped and is therefore causing an error in the CVode library?

Simulating multiple FMU's in the loop

Hello Mr. Lange,

Thanks for this wonderful package. I am currently facing an issue. I am running 2 FMU(from Dymola) nodes in the loop and they are subscribed to each other's topics. Since the package creates separate topics for vectorized signals, I have many publishers and subscribers. I am running the simulation at the rate of 500 Hz. The simulation is not running as expected and I highly doubt that it's due to unsuccessful communication between the nodes. Since the float64 values don't have timestamps, I don't have any ways to sync the data while publishing. I guess, due to this asynchronous communication, this is leading to failure. I tested the FMU's in python (with Fmpy package) and they work perfectly well. Is there any way to address this issue? I have 4 inputs and I need to publish them at the same time and similarly read subscribed topics at the same time. I initially thought that this won't be a problem, but now I can think of only this reason. Any inputs from you will be helpful.

Thank you
Sandeep

Query simulation clock

Apologies Dr/Mr Lange,
I am only new to GitHub and unsure how to communicate best with you. This is more of a feature suggestion than an issue. I hope I am not being too presumptuous by making suggestions. Feel free to ignore me :-)
regards, Craig

Do your libraries include a facility to drive the /clock topic when the launch file sets the simulation parameter ?

If not, I can teach myself how to manually do this, but it would seem a natural extension to your library might be a modelica based facility that would allow this. This facility could allow one to execute the FMU's in faster/slower than real time for testing purposes, without the developer having to know how to construct an external ROS Clock Server.