Integration of first fmi-ls-bus demos

ls-bus-guide/4____network_abstraction.adoc

@@ -304,8 +304,13 @@ fmi3Status fmi3UpdateDiscreteStates(...)
 * FMI3_LS_BUS_BUFFER_INFO_RESET allows to reset the `fmi3LsBusUtilBufferInfo` instance after processing
 ====
 
-===== Examples
-#TODO#
+==== Demos [[low-cut-can-demos]]
+The following list contains demos, which illustrate both the Bus Simulation as such and Network FMUs of various designs:
+
+* link:./demos/can-bus-simulation[CAN Bus Simulation]: Represents an exemplary Bus Simulation FMU for CAN.
+This Bus Simulation can be used in combination with the other Network FMUs, listed behind this point. 
+
+* link:./demos/can-node-triggered-output[CAN Triggered Output]: This demo Network FMU shows sending and receiving multiple CAN Transmit operations using `triggered` output clocks.
 
 ==== Sequence Diagrams [[low-cut-can-sequence-diagrams]]
 This section contains sample sequences to clarify the facts in the CAN, CAN FD, CAN XL part.

ls-bus-guide/demos/.gitignore

@@ -0,0 +1,2 @@
+# Do not store FMU artifacts in here
+*.fmu

ls-bus-guide/demos/README.md

@@ -0,0 +1,12 @@
+# Demo FMUs for FMI-LS-BUS
+
+This directory contains demo FMUs implementing the FMI-LS-BUS.
+
+## Demos for CAN
+
+The following demos are provided for the CAN bus:
+
+- `can-bus-simulation`:
+    A bus simulation FMU for connection two CAN nodes.
+- `can-node-triggered-outputn`:
+    A CAN node sending a periodic frame using a triggered output clock.

ls-bus-guide/demos/can-bus-simulation/PackFmu.py

@@ -0,0 +1,46 @@
+import urllib.request
+import zipfile
+
+from pathlib import Path
+
+
+# Output FMU path
+FMU_PATH = Path('DemoCanBusSimulation.fmu')
+
+# Repository to fetch the LS-BUS headers from
+LS_BUS_REPO = 'modelica/fmi-ls-bus'
+LS_BUS_REV = '473bd5b80730c47373bf41f1c31d44f50de82dd0'
+LS_BUS_HEADERS = [ 'fmi3LsBus.h', 'fmi3LsBusCan.h' ]
+
+
+def main():
+    demo_dir = Path(__file__).parent
+    root_dir = Path(__file__).parent.parent.parent.parent
+
+    with zipfile.ZipFile(FMU_PATH, 'w') as fmu:
+        # Add LS-BUS headers from GitHub repository
+        for ls_bus_header in LS_BUS_HEADERS:
+            with urllib.request.urlopen(f'https://raw.githubusercontent.com/{LS_BUS_REPO}/{LS_BUS_REV}/headers/{ls_bus_header}') as f:
+                fmu.writestr(f'sources/{ls_bus_header}', f.read())
+
+        # Add LS-BUS utility headers
+        for file in (demo_dir.parent.parent / 'headers').iterdir():
+            fmu.write(file, f'sources/{file.name}')
+
+        # Add source files
+        for file in (demo_dir / 'src').iterdir():
+            fmu.write(file, f'sources/{file.name}')
+
+        # Add description files
+        fmu.write(demo_dir / 'description' / 'modelDescription.xml', 'modelDescription.xml')
+        fmu.write(demo_dir / 'description' / 'buildDescription.xml', 'sources/buildDescription.xml')
+        fmu.write(demo_dir / 'description' / 'terminalsAndIcons.xml', 'terminalsAndIcons/terminalsAndIcons.xml')
+        fmu.write(demo_dir / 'description' / 'fmi-ls-manifest.xml', 'extra/org.fmi-standard.fmi-ls-bus/fmi-ls-manifest.xml')
+
+        # Add additional documentation files
+        fmu.write(root_dir / 'LICENSE.txt', 'documentation/licenses/LICENSE.txt')
+        fmu.write(demo_dir / 'README.md', 'documentation/README.md')
+
+
+if __name__ == '__main__':
+    main()

ls-bus-guide/demos/can-bus-simulation/README.md

@@ -0,0 +1,28 @@
+# CAN Bus Simulation FMU
+
+This directory contains a demo FMU implementing a bus simulation FMU for CAN.
+The FMU provides terminals to connect exactly two nodes.
+
+Currently, the bus simulation provides the following capabilities:
+- Forwarding of CAN frames and sending confirmations
+- Basic timing simulation based on baud rate
+- Basic frame priorization
+
+The FMU requires a simulator with support for triggered and countdown clocks, event mode and variable step size.
+
+## Contents
+
+This directory contains the source and description files of the FMU:
+- `src`: Source code of the FMU
+- `description`: Description files of the FMU
+- `PackFmu.py`: Script to generate a source-code FMU
+
+## Building the FMU
+
+A script `PackFMU.py` is provided, which packages the demo source files, as well as all required FMI-LS-BUS headers, into a source code FMU.
+This FMU can then be loaded by an importer or precompiled using, e.g., FMPy.
+
+## Running the FMU
+
+To run the FMU, a supported simulator and two CAN node FMUs (e.g., from the demo `can-node-triggered-output`) are required.
+The node FMUs must be connected to the `Node1` and `Node2` terminals.

ls-bus-guide/demos/can-bus-simulation/description/buildDescription.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<fmiBuildDescription fmiVersion="3.0"
+                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                     xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/modelica/fmi-standard/v3.0.1/schema/fmi3BuildDescription.xsd">
+  <BuildConfiguration modelIdentifier="DemoCanBusSimulation">
+    <SourceFileSet language="C99">
+      <SourceFile name="App.c"/>
+      <SourceFile name="Fmu.c"/>
+      <SourceFile name="Logging.c"/>
+    </SourceFileSet>
+  </BuildConfiguration>
+</fmiBuildDescription>

ls-bus-guide/demos/can-bus-simulation/description/fmi-ls-manifest.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<fmiLayeredStandardManifest
+		xmlns:fmi-ls="http://fmi-standard.org/fmi-ls-manifest"
+		fmi-ls:fmi-ls-name="org.fmi-standard.fmi-ls-bus"
+		fmi-ls:fmi-ls-version="1.0.0"
+		fmi-ls:fmi-ls-description="Layered Standard for the simulation of bus communication on a signal or network abstraction based level."
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/modelica/fmi-ls-bus/473bd5b80730c47373bf41f1c31d44f50de82dd0/schema/fmi3LayeredStandardBusManifest.xsd"/>

ls-bus-guide/demos/can-bus-simulation/description/modelDescription.xml

@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<fmiModelDescription
+    fmiVersion="3.0"
+    modelName="DemoCanBusSimulation"
+    instantiationToken=""
+    variableNamingConvention="structured"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/modelica/fmi-standard/v3.0.1/schema/fmi3ModelDescription.xsd">
+
+  <CoSimulation
+      modelIdentifier="DemoCanBusSimulation"
+      needsExecutionTool="false"
+      canGetAndSetFMUState="false"
+      canSerializeFMUState="false"
+      canHandleVariableCommunicationStepSize="true"
+      canBeInstantiatedOnlyOncePerProcess="false"
+      providesIntermediateUpdate="false"
+      canReturnEarlyAfterIntermediateUpdate="false"
+      providesEvaluateDiscreteStates="true"
+      hasEventMode="true">
+  </CoSimulation>
+
+  <LogCategories>
+    <Category name="logStatusDiscard"
+              description="Log messages when returning fmi3Discard status from any function." />
+    <Category name="logStatusError"
+              description="Log messages when returning fmi3Error status from any function." />
+
+    <Category name="Trace"
+            description="Trace log messages." />
+    <Category name="Info"
+              description="Info log messages." />
+    <Category name="Warning"
+              description="Warning log messages." />
+    <Category name="Error"
+              description="Error log messages." />
+  </LogCategories>
+
+  <DefaultExperiment
+      startTime="0"
+      stepSize="0.001" />
+
+  <ModelVariables>
+    <Float64 name="time" valueReference="1024" causality="independent" variability="continuous" description="Simulation time" />
+
+    <Binary name="Node1::Rx_Data"
+        valueReference="0"
+        causality="input"
+        variability="discrete"
+        initial="exact"
+        maxSize="2048"
+        clocks="2"
+        mimeType="org.fmi-standard.fmi-ls-bus.v1.can">
+        <Dimension start="1" />
+        <Start value="" />
+    </Binary>
+
+    <Binary name="Node1::Tx_Data"
+        valueReference="1"
+        causality="output"
+        variability="discrete"
+        initial="calculated"
+        maxSize="2048"
+        clocks="3"
+        mimeType="org.fmi-standard.fmi-ls-bus.v1.can">
+    </Binary>
+
+    <Clock name="Node1::Rx_Clock" valueReference="2" causality="input" intervalVariability="triggered" />
+    <Clock name="Node1::Tx_Clock" valueReference="3" causality="input" intervalVariability="countdown" />
+
+    <Binary name="Node2::Rx_Data"
+            valueReference="4"
+            causality="input"
+            variability="discrete"
+            initial="exact"
+            maxSize="2048"
+            clocks="6"
+            mimeType="org.fmi-standard.fmi-ls-bus.v1.can">
+      <Dimension start="1" />
+      <Start value="" />
+    </Binary>
+
+    <Binary name="Node2::Tx_Data"
+            valueReference="5"
+            causality="output"
+            variability="discrete"
+            initial="calculated"
+            maxSize="2048"
+            clocks="7"
+            mimeType="org.fmi-standard.fmi-ls-bus.v1.can">
+    </Binary>
+
+    <Clock name="Node2::Rx_Clock" valueReference="6" causality="input" intervalVariability="triggered" />
+    <Clock name="Node2::Tx_Clock" valueReference="7" causality="input" intervalVariability="countdown" />
+  </ModelVariables>
+
+  <ModelStructure>
+    <Output valueReference="1" dependencies="3" />
+    <Output valueReference="5" dependencies="7" />
+  </ModelStructure>
+</fmiModelDescription>

ls-bus-guide/demos/can-bus-simulation/description/terminalsAndIcons.xml

@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<fmiTerminalsAndIcons fmiVersion="3.0"
+                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                      xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/modelica/fmi-standard/v3.0.1/schema/fmi3TerminalsAndIcons.xsd">
+  <Terminals>
+    <Terminal terminalKind="org.fmi-ls-bus.network-terminal"
+              matchingRule="org.fmi-ls-bus.transceiver"
+              name="Node1"
+              description="CAN bus terminal definition">
+      <TerminalMemberVariable variableKind="signal"
+                              variableName="Node1::Rx_Clock"
+                              memberName="Rx_Clock" />
+      <TerminalMemberVariable variableKind="signal"
+                              variableName="Node1::Rx_Data"
+                              memberName="Rx_Data" />
+      <TerminalMemberVariable variableKind="signal"
+                              variableName="Node1::Tx_Clock"
+                              memberName="Tx_Clock" />
+      <TerminalMemberVariable variableKind="signal"
+                              variableName="Node1::Tx_Data"
+                              memberName="Tx_Data" />
+    </Terminal>
+    <Terminal terminalKind="org.fmi-ls-bus.network-terminal"
+              matchingRule="org.fmi-ls-bus.transceiver"
+              name="Node2"
+              description="CAN bus terminal definition">
+      <TerminalMemberVariable variableKind="signal"
+                              variableName="Node2::Rx_Clock"
+                              memberName="Rx_Clock" />
+      <TerminalMemberVariable variableKind="signal"
+                              variableName="Node2::Rx_Data"
+                              memberName="Rx_Data" />
+      <TerminalMemberVariable variableKind="signal"
+                              variableName="Node2::Tx_Clock"
+                              memberName="Tx_Clock" />
+      <TerminalMemberVariable variableKind="signal"
+                              variableName="Node2::Tx_Data"
+                              memberName="Tx_Data" />
+    </Terminal>
+  </Terminals>
+</fmiTerminalsAndIcons>