Dynamic Simulation Environment - FMI Library

Introduction

FMI Libraries of the Dynamic Simulation Environment (DSE) Core Platform provide various solutions for working with FMUs and FMI based simulation environments. Included are:

• FMI MCL - for loading FMUs into a DSE simulation.
• ModelC FMU - for packaging a DSE simulation as an FMU.
• Gateway FMU - for bridging between a remote simulation and a DSE simulation.
• FMU API - a minimal API for implementing FMUs with support for Binary Variables and Virtual Networks.

The DSE FMI libraries operate in Co-simulation environments and support both scalar and binary variables. Virtual networks (e.g. CAN) are implemented using Network Codecs and supported via FMI Binary variables, or in the case of FMI 2, by using encoded FMI String variables.

FMI MCL

• Model Compatibility Library (MCL) for loading FMUs in a DSE simulation.
• Multi platform (Linux, Windows) and multi architecture (x64, x86, i386) simulation environment.
• Native FMU support for Co-simulation.
• Virtual Networks (CAN etc.) using Network Codecs and Binary Streams. Includes support for FMI 2 (via String variables).

ModelC FMU

• FMU with embedded Model Runtime and SimBus from the ModelC project.
• Packages DSE Simer simulation as an FMU.
• FMU interface supports Codec based Binary Streams (e.g. CAN Virtual Bus). Includes support for FMI 2 (via String variables).

Gateway FMU

• Bridge simulaiton environments using a Gateway FMU.
• Gateway FMU interface supports Codec based Binary Streams, including FMI 2 support.
• Manages the Co-simulation time-domain between the bridged simulation environments.
• Simple lifecycle which can be customised to support automation of simulation environments (e.g. session management).

FMU API

• Minimal API for implementing Co-simulation FMUs with methods:
  • fmu_create()
  • fmu_init()
  • fmu_step()
  • fmu_destroy()
• Automatic FMI Variable indexing and storage, including FMI 2 support for Binary Variables
• Build targets for FMI 2 and FMI 3.
• Virtual Networks (CAN etc.) using Network Codecs and Binary Streams. Includes support for FMI 2 (via String variables).

Project Structure

└── dse
    └── examples            <-- Examples
    └── fmigateway          <-- Gateway FMU source code
    └── fmimcl              <-- FMI MCL source code
    └── fmimodelc           <-- ModelC FMU source code
    └── fmu                 <-- FMI API source code
    └── importer            <-- Simple FMU Importer
└── extra                   <-- Build infrastructure
    └── tools/fmi           <-- Containerised tools
└── licenses                <-- Third Party Licenses
└── tests                   <-- Unit and E2E tests
└── Taskfile.yml            <-- Workflow automation via Task

Usage

ModelC FMU with DSE Script and Simulation Builder

Info: This usage example is derived from E2E Test - Direct Index.

Shell setup instructions

Info: Authentication settings for GHE_* environment variables are described here: Builder Authentication.

# Set environment.
$ export BUILDER_IMAGE=ghcr.io/boschglobal/dse-builder:latest
$ export FMI_IMAGE=ghcr.io/boschglobal/dse-fmi:latest
$ export TASK_X_REMOTE_TASKFILES=1

# Install shell functions.
function dse-builder() {
    (
        if [[ "$1" == */* ]]; then cd $(dirname "$1"); fi && \
        local dsefile=$(basename "$1"); shift && \
        docker run -it --rm \
            --user $(id -u):$(id -g) \
            -v $(pwd):/workdir \
            -e GHE_USER -e GHE_TOKEN -e GHE_PAT \
            $BUILDER_IMAGE "$dsefile" "$@"; \
    )
}

# Install Task (from DSE fork).
$ go install github.com/boschglobal/task/v3/cmd/task@latest

Simulation Definition

simulation.dse (DSE Script)

simulation
channel in
channel out

uses
dse.fmi https://github.com/boschglobal/dse.fmi v1.1.47

model direct dse.fmi.example.direct
    channel in in_vector
    channel out out_vector
    envar OFFSET 100
    envar FACTOR 4

workflow generate-modelcfmu
    var FMU_NAME direct
    var FMI_VERSION 2
    var INDEX direct

Build and Operate

# Build local artifacts.
$ make build package

# Create the simulation folder/file (copy content from simulation.dse, above).
$ mkdir example
$ vim example/simulation.dse

# Build the simulation.
$ cd example
$ dse-builder simulation.dse
$ task -y -v

# Operate the simulation with the Importer.
$ ../dse/build/_out/importer/fmuImporter --verbose out/fmu/direct

Examples

• ModelC FMU with Direct Indexing

Build

# Clone the repo.
$ git clone https://github.com/boschglobal/dse.fmi.git
$ cd dse.fmi

# Optionally set builder images.
$ export GCC_BUILDER_IMAGE=ghcr.io/boschglobal/dse-gcc-builder:latest

# Build.
$ make
$ make package

# Build containerised tools (more details in the extra/tools/fmi directory).
$ make build fmi tools

# Optionally use local container images.
$ export FMI_IMAGE=fmi:test
$ export SIMER_IMAGE=simer:test

# Run tests.
$ make test

# Generate documentation.
$ make generate

# Remove (clean) temporary build artifacts.
$ make clean
$ make cleanall

Additional Resources

The FMI Library is implemented using the following related repositories:

• DSE Model C Library
• DSE C Library
• DSE Network Codec
• DSE Standards Extensions
  • Binary Codec specification for FMI 2/3
  • String encoding for binary data, for FMI 2/3
  • Bus Topologies and Virtual Bus/Networks, for FMI 2/3

Contribute

Please refer to the CONTRIBUTING.md file.

License

Dynamic Simulation Environment FMI Library is open-sourced under the Apache-2.0 license. See the LICENSE and NOTICE files for details.

Third Party Licenses

Third Party Licenses