New FMI Gateway FMU.

Signed-off-by: Timothy Rule (VM/EMT3) <[email protected]>

.gitignore

@@ -11,6 +11,7 @@ extra/tools/*/bin
 !extra/tools/*/build
 extra/tools/*/build/stage
 .task/
+.vscode
 
 # Prerequisites
 *.d

README.md

@@ -94,6 +94,14 @@ task: Available tasks for this project:
 * generate-fmimcl:          Generate an FMI MCL from an existing FMU.
 * generate-fmimodelc:       Generate a FMI ModelC FMU from an existing (DSE/ModelC) Simer simulation.
 
+# FMI Gateway with the generate-fmigateway command:
+$ task generate-fmigateway \
+    FMI_VERSION=2 \
+    SIGNAL_GROUPS="extra/tools/fmi/test/testdata/fmigateway/SG1.yaml,extra/tools/fmi/test/testdata/fmigateway/SG2.yaml"
+Running FMI Toolset command: gen-gateway
+Adding SignalGroup Model_1 to out/fmu.yaml
+Adding SignalGroup Model_2 to out/fmu.yaml
+Creating Model YAML: gateway (out/model.yaml)
 
 # FMI MCL with the generate-fmimcl command:
 $ task generate-fmimcl \

Taskfile.yml

@@ -44,6 +44,14 @@ tasks:
     cmds:
       - task: gen-fmu
 
+  generate-fmigateway:
+    desc: Generate a FMI Gateway FMU from existing Signalgroups.
+    run: always
+    dir: '{{.USER_WORKING_DIR}}'
+    label: dse:fmi:generate-fmigateway
+    cmds:
+      - task: gen-gateway
+
   gen-mcl:
     internal: true
     run: always
@@ -112,6 +120,32 @@ tasks:
     requires:
       vars: [SIM, FMU_NAME]
 
+  gen-gateway:
+    internal: true
+    run: always
+    dir: '{{.USER_WORKING_DIR}}'
+    label: dse:fmi:gen-gateway
+    vars:
+      SIGNAL_GROUPS: '{{.SIGNAL_GROUPS | default "SIGNAL_GROUPS_NOT_SPECIFIED"}}'
+      OUT_DIR: '{{.OUT_DIR | default "out"}}'
+      SESSION: "{{if .SESSION}}--session '{{.SESSION}}'{{else}}{{end}}"
+      VERSION: "{{if .VERSION}}--version '{{.VERSION}}'{{else}}{{end}}"
+      FMI_VERSION: "{{if .FMIVERSION}}--fmiVersion '{{.FMIVERSION}}'{{else}}{{end}}"
+      UUID: "{{if .UUID}}--uuid '{{.UUID}}'{{else}}{{end}}"
+    cmds:
+      - docker run --rm
+          -v {{.ENTRYDIR}}:/sim
+          {{.FMI_IMAGE}}:{{.FMI_TAG}}
+          gen-gateway
+            --signalgroups {{.SIGNAL_GROUPS}}
+            --outdir {{.OUT_DIR}}
+            {{.SESSION}}
+            {{.VERSION}}
+            {{.FMI_VERSION}}
+            {{.UUID}}
+    requires:
+      vars: [SIGNAL_GROUPS]
+
   patch-signalgroup:
     run: always
     dir: '{{.USER_WORKING_DIR}}'

doc/Makefile

@@ -45,8 +45,15 @@ DOC_OUTPUT_fmu := doc/content/apis/fmi/fmu/index.md
 DOC_LINKTITLE_fmu := "FMU"
 DOC_TITLE_fmu := "FMU API Reference"
 
+# Module "fmu"
+DOC_INPUT_fmigateway := dse/fmigateway/fmigateway.h
+DOC_CDIR_fmigateway := dse/fmigateway/fmigateway.c,dse/fmigateway/parser.c,dse/fmigateway/index.c,dse/fmigateway/session.c,dse/fmigateway/session_win32.c
+DOC_OUTPUT_fmigateway := doc/content/apis/fmi/fmigateway/index.md
+DOC_LINKTITLE_fmigateway := "Gateway FMU"
+DOC_TITLE_fmigateway := "FMI Gateway FMU API Reference"
+
 # Targets
-DOC_C_MODULES := fmimcl fmimodelc fmu
+DOC_C_MODULES := fmimcl fmimodelc fmu fmigateway
 
 
 .PHONY: examples

doc/content/apis/fmi/fmigateway/index.md

@@ -0,0 +1,262 @@
+---
+title: FMI Gateway FMU API Reference
+linkTitle: Gateway FMU
+---
+## fmu_signals_reset
+
+
+Resets the binary signals of the gateway to a length of 0, if the signals have
+not been reseted yet.
+
+> Required by FMU.
+
+### Parameters
+
+fmu (FmuInstanceData*)
+: The FMU Descriptor object representing an instance of the FMU Model.
+
+
+
+## fmu_signals_setup
+
+
+Placeholder to signal the FMU to not use the default signal allocation.
+
+### Parameters
+
+fmu (FmuInstanceData*)
+: The FMU Descriptor object representing an instance of the FMU Model.
+
+
+
+## fmu_signals_remove
+
+
+This method frees the allocated binary signal indexes.
+
+### Parameters
+
+fmu (FmuInstanceData*)
+: The FMU Descriptor object representing an instance of the FMU Model.
+
+
+
+## FMI ModelC Gateway
+
+
+
+### Component Diagram
+
+<div hidden>
+
+```
+@startuml fmigateway-component
+
+title FMI Gateway FMU
+
+center footer Dynamic Simulation Environment
+
+@enduml
+```
+
+</div>
+
+![](fmigateway-component.png)
+
+
+### Example
+
+
+
+
+## fmu_create
+
+
+This method allocates the necessary gateway models. The location of the required
+yaml files is set and allocated.
+
+> Required by FMU.
+
+### Parameters
+
+fmu (FmuInstanceData*)
+: The FMU Descriptor object representing an instance of the FMU Model.
+
+### Returns
+
+0 (int32_t)
+: The FMU was created correctly.
+
+
+
+## fmu_init
+
+
+In this method the required yaml files are parsed and the session is configured,
+if required. The gateway is set up and connected to the simbus. After a
+sucessfull connection has been established, the fmu variables are indexed to
+their corresponding simbus signals.
+
+> Required by FMU.
+
+### Parameters
+
+fmu (FmuInstanceData*)
+: The FMU Descriptor object representing an instance of the FMU Model.
+
+### Returns
+
+0 (int32_t)
+: The FMU was created correctly.
+
+
+
+## fmu_step
+
+
+This method executes one step of the gateway model and signals are exchanged
+with the other simulation participants.
+
+> Required by FMU.
+
+### Parameters
+
+fmu (FmuInstanceData*)
+: The FMU Descriptor object representing an instance of the FMU Model.
+communication_point (double)
+: The current model time of the FMU in seconds.
+step_size (double)
+: The step size of the FMU in seconds.
+
+### Returns
+
+0 (int32_t)
+: The FMU step was performed correctly.
+
+
+
+
+## fmu_destroy
+
+
+Releases memory and system resources allocated by gateway.
+
+> Required by FMU.
+
+### Parameters
+
+fmu (FmuInstanceData*)
+: The FMU Descriptor object representing an instance of the FMU Model.
+
+### Returns
+
+0 (int32_t)
+: The FMU data was released correctly.
+
+
+
+## Typedefs
+
+### FmiGateway
+
+```c
+typedef struct FmiGateway {
+    int * model;
+    struct (anonymous struct at dse/fmigateway/fmigateway.h:75:5) settings;
+    int binary_signals_reset;
+}
+```
+
+### FmiGatewaySession
+
+```c
+typedef struct FmiGatewaySession {
+    WindowsModel * w_models;
+    struct (anonymous struct at dse/fmigateway/fmigateway.h:61:5) init;
+    struct (anonymous struct at dse/fmigateway/fmigateway.h:65:5) shutdown;
+    double last_step;
+}
+```
+
+### WindowsModel
+
+```c
+typedef struct WindowsModel {
+    const char * path;
+    const char * file;
+    int show_process;
+    const char * name;
+    double step_size;
+    double end_time;
+    int log_level;
+    const char * yaml;
+    double current_step;
+    double timeout;
+    void * w_process;
+}
+```
+
+## Functions
+
+### fmigateway_parse
+
+This method loads the required yaml files from the resource location of the fmu.
+The loaded yaml files are parsed into the fmu descriptor object.
+
+#### Parameters
+
+fmu (FmuInstanceData*)
+: The FMU Descriptor object representing an instance of the FMU Model.
+
+
+
+### fmigateway_session_configure
+
+If session parameters were parsed from the model description, this method
+configures and starts the additional models, or executes the given command.
+
+#### Parameters
+
+fmu (FmuInstanceData*)
+: The FMU Descriptor object representing an instance of the FMU Model.
+
+
+
+### fmigateway_session_end
+
+If session parameters were parsed from the model description, this method
+shuts down the additional models, or executes the given command.
+
+#### Parameters
+
+fmu (FmuInstanceData*)
+: The FMU Descriptor object representing an instance of the FMU Model.
+
+
+
+### fmigateway_session_windows_end
+
+Termiantes all previously started windows processes.
+After sending the termination signals, one additionally
+step is made by the gateway to close the simulation.
+
+#### Parameters
+
+fmu (FmuInstanceData*)
+: The FMU Descriptor object representing an instance of the FMU Model.
+
+
+
+### fmigateway_session_windows_start
+
+Creates windows processes based on the parameters
+configured in a yaml file. Process informations are
+stored for later termination.
+
+#### Parameters
+
+fmu (FmuInstanceData*)
+: The FMU Descriptor object representing an instance of the FMU Model.
+
+
+