Builder - Simulation Development Platform

Tags:

Synopsis

Containerised simulation builder and supporting DSE Language (DSE Lang).

Describe a Simulation

simulation arch=linux-amd64
channel network

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

model fmu_CAN dse.fmi.network_model
    channel network network_channel

workflow generate-model
    var NETWORK_SIGNAL can_bus
    var MIME_TYPE "application/x-automotive-bus;interface=stream;type=frame;bus=can;schema=fbs;bus_id=1;node_id=2;interface_id=3"
    var MEASUREMENT measurement.txt
    var OUT_DIR {{.PATH}}/data

workflow generate-fmimodelc
    var FMU_NAME example
    var SIGNAL_GROUPS network

Use the Builder Tool

# Build a simulation.
$ cd examples/runnable
$ builder runnable.dse
$ task -y

Run the Simulation

# Run a simulation.
$ simer out/sim -stepsize 0.0005 -endtime 0.10

DSE Lang

Simulations using the Simulation Development Platform (SDP) are written in a custom DSL language: colloquially called ‘DSE Lang’. This language is used to describe the construction of a simulation and its constituent channels, models and workflows.

Simulation

simulation [arch=ARCH]
[channel CHANNEL_NAME] ...
  • ARCH: the architecture of the overall simulation. Select from supported platforms, including:
    • linux-amd64
    • linux-x86
    • linux-i386
    • windows-x64
    • windows-x86
  • CHANNEL_NAME: the name of a simulation channel. Repeat for each channel of the simulation.

Uses

uses
[USES_NAME URI [VERSION] [path=PATH] [user=USER] [token=TOKEN]] ...
  • USES_NAME: the name of the uses item.
  • URI: a URI for the uses item. May be a URL or file.
  • VERSION: the version of the uses item.
  • PATH: a sub-path of the uses item (incase the item should be extracted from a ZIP archive).
  • USER: authentication user needed for retrieving the _uses_item.
  • TOKEN: authentication token (or password) needed for retrieving the _uses_item.

Stack

stack STACK_NAME [arch=ARCH]
  • STACK_NAME: the name of the stack.
  • ARCH: the architecture of this stack and the models it contains.

Model

model MODEL_INST_NAME MODEL_NAME [arch=ARCH]
[channel CHANNEL_NAME CHANNEL_ALIAS] ...
  • MODEL_INST_NAME: the name of the model (used within the simulation).
  • MODEL_NAME: the name of the model as referenced by a uses item.
  • ARCH: the architecture of this model.
  • CHANNEL_NAME: the name of a simulation channel to be mapped to this model.
  • CHANNEL_ALIAS: the model alias for the channel being mapped.

Workflow

Workflow WORKFLOW_NAME
[var VAR_NAME VAR_VALUE] ...
[var VAR_NAME uses USES_NAME] ...
  • WORKFLOW_NAME: the name of the workflow.
  • VAR_NAME: the name of a variable used by this workflow.
  • VAR_VALUE: the variable value.
  • USES_NAME: sets the variable value to the path of this uses item.

Special Variables

DSE Lang uses a templating mechanism to introduce special variables to a DSE Script (in the form: {{ .SPECIAL_VAR }}). Those variables are used to influence how a simulation is constructed. Additionally, the templating mechanism can be used to introduce environment variables to a DSE Script (useful for authentication).

ENV_VAR
Expands to the named ENV_VAR.
MODEL
When used within the context of a model expands to the models name (i.e. MODEL_INST_NAME).
OUTDIR
The output directory of the SDP toolchains (typically out). Contains the simulation folder.
PATH
When used within the context of a model expands to the models path within the simulation filesystem (set to SIMDIR/MODEL_INST_NAME).
SIMDIR
The simulation folder (typically sim).

Builder Tool

Info: The Builder Tool is already setup and configured in both GitHub Codespaces and Dev Containers environments.

Setup

The SDP Builder is a containerized tool which can be configured and used in a Linux environment. The following container images are available.

# Latest Builder Container:
$ docker pull ghcr.io/boschglobal/dse-builder:latest

# Specific versions of the Builder Container
$ docker pull ghcr.io/boschglobal/dse-builder:1.0.4
$ docker pull ghcr.io/boschglobal/dse-builder:1.0

Shell Function

Info: The following shell function passes credentials to the Build Container which are used to fetch artifacts and repository metadata. Adjust as necessary for your environment (the -e parameters of the docker command).

# Define a shell function (or add to .profile file).
$ export BUILDER_IMAGE=ghcr.io/boschglobal/dse-builder:latest
$ builder() { ( if test -f "$1"; then cd $(dirname "$1"); fi && docker run -it --rm -e AR_USER -e AR_TOKEN -e GHE_USER -e GHE_TOKEN -e GHE_PAT -v $(pwd):/workdir $BUILDER_IMAGE "$@"; ) }

# Build the simulation.
$ cd examples/runnable
$ builder runnable.dse

# And then use Task to complete the simulation (according to the build plan).
export TASK_X_REMOTE_TASKFILES=1
$ task -y -v
ls -R out/sim

Authentication

Any uses items in your DSE Script which require authentication credentials need to be defined in your environment and passed to the builder container. For example the following DSE Script uses a private GitHub repository and Artifactory instance:

simulation arch=linux-amd64
channel signal

uses
fsil.runnable https://{{.GHE_TOKEN}}@github.boschdevcloud.com/fsil/fsil.runnable v1.1.2 user={{.AR_USER}} token={{.AR_TOKEN}}

and needs the following authentication setup:

# Define authentication tokens.
export AR_USER=foo
export AR_TOKEN=foo_token
export GHE_TOKEN=goo_token

# Specify the shell function.
$ builder() { ( if test -f "$1"; then cd $(dirname "$1"); fi && docker run -it --rm -e AR_USER -e AR_TOKEN -e GHE_TOKEN -v $(pwd):/workdir $BUILDER_IMAGE "$@"; ) }