Skip to content

Commit ee71982

Browse files
author
Stefan Cyliax
authored
Merge pull request #77 from OpenSimulationInterface/migration
Migration to AsciiDoc
2 parents 97caa37 + e2ac263 commit ee71982

19 files changed

Lines changed: 522 additions & 604 deletions

‎.gitmodules‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,6 @@
22
path = examples/open-simulation-interface
33
url = https://github.com/OpenSimulationInterface/open-simulation-interface.git
44
branch = master
5+
[submodule "asciidoc-resources"]
6+
path = asciidoc-resources
7+
url = https://code.asam.net/simulation/asciidoc-resources.git

‎asciidoc-resources‎

Submodule asciidoc-resources added at e0bd505

‎doc/examples.rst‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎doc/misc/example.adoc‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
= Example: Simple sensor model FMU
2+
3+
Then following example shows the content of a `modelDescription.xml` file that satisfies the requirements of OSMP.
4+
The example describes a sensor model FMU with one input, one output, and no additional features:
5+
6+
[source,xml]
7+
----
8+
<?xml version="1.0" encoding="UTF-8"?>
9+
<fmiModelDescription
10+
fmiVersion="2.0"
11+
modelName="OSI Sensor Model Packaging Demo FMU"
12+
guid="aabc2174e20f08597cfae6947c96bf86"
13+
variableNamingConvention="structured">
14+
<CoSimulation
15+
modelIdentifier="OSMPDemoFMU"
16+
canNotUseMemoryManagementFunctions="true"/>
17+
<DefaultExperiment startTime="0.0" stepSize="0.020"/>
18+
<VendorAnnotations>
19+
<Tool name="net.pmsf.osmp" xmlns:osmp="http://xsd.pmsf.net/OSISensorModelPackaging"><osmp:osmp version="1.1.1" osi-version="3.3.1"/></Tool>
20+
</VendorAnnotations>
21+
<ModelVariables>
22+
<ScalarVariable name="OSMPSensorViewIn.base.lo" valueReference="0" causality="input" variability="discrete">
23+
<Integer start="0"/>
24+
<Annotations>
25+
<Tool name="net.pmsf.osmp" xmlns:osmp="http://xsd.pmsf.net/OSISensorModelPackaging"><osmp:osmp-binary-variable name="OSMPSensorViewIn" role="base.lo" mime-type="application/x-open-simulation-interface; type=SensorView; version=3.3.1"/></Tool>
26+
</Annotations>
27+
</ScalarVariable>
28+
<ScalarVariable name="OSMPSensorViewIn.base.hi" valueReference="1" causality="input" variability="discrete">
29+
<Integer start="0"/>
30+
<Annotations>
31+
<Tool name="net.pmsf.osmp" xmlns:osmp="http://xsd.pmsf.net/OSISensorModelPackaging"><osmp:osmp-binary-variable name="OSMPSensorViewIn" role="base.hi" mime-type="application/x-open-simulation-interface; type=SensorView; version=3.3.1"/></Tool>
32+
</Annotations>
33+
</ScalarVariable>
34+
<ScalarVariable name="OSMPSensorViewIn.size" valueReference="2" causality="input" variability="discrete">
35+
<Integer start="0"/>
36+
<Annotations>
37+
<Tool name="net.pmsf.osmp" xmlns:osmp="http://xsd.pmsf.net/OSISensorModelPackaging"><osmp:osmp-binary-variable name="OSMPSensorViewIn" role="size" mime-type="application/x-open-simulation-interface; type=SensorView; version=3.3.1"/></Tool>
38+
</Annotations>
39+
</ScalarVariable>
40+
<ScalarVariable name="OSMPSensorDataOut.base.lo" valueReference="3" causality="output" variability="discrete" initial="exact">
41+
<Integer start="0"/>
42+
<Annotations>
43+
<Tool name="net.pmsf.osmp" xmlns:osmp="http://xsd.pmsf.net/OSISensorModelPackaging"><osmp:osmp-binary-variable name="OSMPSensorDataOut" role="base.lo" mime-type="application/x-open-simulation-interface; type=SensorData; version=3.3.1"/></Tool>
44+
</Annotations>
45+
</ScalarVariable>
46+
<ScalarVariable name="OSMPSensorDataOut.base.hi" valueReference="4" causality="output" variability="discrete" initial="exact">
47+
<Integer start="0"/>
48+
<Annotations>
49+
<Tool name="net.pmsf.osmp" xmlns:osmp="http://xsd.pmsf.net/OSISensorModelPackaging"><osmp:osmp-binary-variable name="OSMPSensorDataOut" role="base.hi" mime-type="application/x-open-simulation-interface; type=SensorData; version=3.3.1"/></Tool>
50+
</Annotations>
51+
</ScalarVariable>
52+
<ScalarVariable name="OSMPSensorDataOut.size" valueReference="5" causality="output" variability="discrete" initial="exact">
53+
<Integer start="0"/>
54+
<Annotations>
55+
<Tool name="net.pmsf.osmp" xmlns:osmp="http://xsd.pmsf.net/OSISensorModelPackaging"><osmp:osmp-binary-variable name="OSMPSensorDataOut" role="size" mime-type="application/x-open-simulation-interface; type=SensorData; version=3.3.1"/></Tool>
56+
</Annotations>
57+
</ScalarVariable>
58+
</ModelVariables>
59+
<ModelStructure>
60+
<Outputs>
61+
<Unknown index="4"/>
62+
<Unknown index="5"/>
63+
<Unknown index="6"/>
64+
</Outputs>
65+
</ModelStructure>
66+
</fmiModelDescription>
67+
----

‎doc/misc/introduction.adoc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
= Introduction
2+
3+
_OSI Sensor Model Packaging_ (OSMP) is a package layer specification for the _Open Simulation Interface_ (OSI).
4+
It specifies how models that use OSI are packaged as _Functional Mock-up Units_ (FMUs) in accordance with the _Functional Mock-up Interface 2.0_ (FMI 2.0).
5+
6+
This is version 1.1.1 of this specification. The version number is to be
7+
interpreted according to the https://semver.org/spec/v2.0.0.html[_Semantic Versioning Specification 2.0.0_].

‎doc/osi-sensor-model-packaging_spec.adoc‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
ifndef::THIS_STANDARD[]
2+
3+
:asciidoc-resources: ../asciidoc-resources
4+
include::{asciidoc-resources}/preamble.adoc[]
5+
6+
:revnumber: --localbuild--
7+
:revdate: {docdate}
8+
9+
:topicdir: topics
10+
:reusedir: reuse
11+
12+
:imagesdir: .
13+
:images_open_simulation_interface: ./images
14+
15+
16+
endif::[]
17+
18+
= OSI Sensor Model Packaging
19+
20+
include::./misc/introduction.adoc[leveloffset=+1]
21+
22+
== OSMP specification
23+
24+
include::./spec/model_types.adoc[leveloffset=+2]
25+
26+
include::./spec/basic_conventions.adoc[leveloffset=+2]
27+
28+
include::./spec/binary_variables.adoc[leveloffset=+2]
29+
30+
include::./spec/sensor_view_inputs.adoc[leveloffset=+2]
31+
32+
include::./spec/sensor_view_input_configuration.adoc[leveloffset=+2]
33+
34+
include::./spec/sensor_view_outputs.adoc[leveloffset=+2]
35+
36+
include::./spec/sensor_data_inputs.adoc[leveloffset=+2]
37+
38+
include::./spec/sensor_data_outputs.adoc[leveloffset=+2]
39+
40+
include::./spec/ground_truth_init_parameters.adoc[leveloffset=+2]
41+
42+
include::./spec/traffic_command_inputs.adoc[leveloffset=+2]
43+
44+
include::./spec/traffic_update_outputs.adoc[leveloffset=+2]
45+
46+
== Examples
47+
48+
include::./setup/build_install_example.adoc[leveloffset=+2]
49+
50+
include::./misc/example.adoc[leveloffset=+2]
51+

‎doc/setup/build_install_example.adoc‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
= Building and installing examples
2+
3+
OSMP includes three examples located in `_osmp_/examples`:
4+
5+
`OSMPDummySensor/`::
6+
Can be used as a simple dummy sensor model, demonstrating the use of OSI for sensor models consuming sensor view data and generating sensor data output.
7+
8+
`OSMPDummySource/`::
9+
Can be used as a simple source of sensor view data and ground-truth data.
10+
It can be connected to the input of an `OSMPDummySensor` model, for simple testing and demonstration purposes.
11+
12+
`OSMPCNetworkProxy/`::
13+
Demonstrates a simple C network proxy that can send and receive OSI data via TCP sockets.
14+
15+
**Prerequisites**
16+
17+
* You have installed _cmake_ version 3.10.2 or higher.
18+
* You have installed _protobuf_ version 3.0.0 or higher.
19+
20+
**Steps**
21+
22+
. Clone the OSMP repository.
23+
+
24+
[source]
25+
----
26+
git clone https://github.com/OpenSimulationInterface/osi-sensor-model-packaging.git
27+
----
28+
+
29+
. Change into the OSMP repository.
30+
+
31+
[source]
32+
----
33+
cd osi-sensor-model-packaging
34+
----
35+
+
36+
. Update and initialize the OSI submodule.
37+
+
38+
[source]
39+
----
40+
git submodule update --init
41+
----
42+
+
43+
. Change into the `examples/` directory.
44+
+
45+
[source]
46+
----
47+
cd examples
48+
----
49+
+
50+
. Create a new directory called `build/`.
51+
+
52+
[source]
53+
----
54+
mkdir -p build
55+
----
56+
+
57+
. Change into the `build/` directory.
58+
+
59+
[source]
60+
----
61+
cd build
62+
----
63+
+
64+
. Run _cmake_ in the parent directory.
65+
+
66+
[source]
67+
----
68+
cmake ..
69+
----
70+
+
71+
. Run _cmake_ build.
72+
+
73+
[source]
74+
----
75+
cmake --build .
76+
----

‎doc/spec/basic_conventions.adoc‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
= Basic conventions
2+
3+
The model shall be packaged as a valid FMU for co-simulation, as specified in the FMI 2.0 standard.
4+
Unless otherwise noted, all specifications in the FMI 2.0 standard apply as-is.
5+
6+
The following annotation shall be placed into the `<VendorAnnotations>` element of the `modelDescription.xml` to mark the FMU as being conformant to this version of the specification:
7+
8+
[source,xml]
9+
----
10+
<Tool name="net.pmsf.osmp" xmlns:osmp="http://xsd.pmsf.net/OSISensorModelPackaging"><osmp:osmp version="1.1.1" osi-version="x.y.z"/></Tool>
11+
----
12+
13+
The `@osi-version` attribute should contain the major, minor, and patch version number of the OSI specification that this model was compiled against.
14+
Indicating the OSI version ensures that the importing environment can determine which OSI version to use prior to communicating with the FMU.
15+
16+
If OSMP is used without OSI data being transported across binary variables, `@osi-version` should not be specified.
17+
18+
The variable naming convention of the FMU shall be structured.
19+
20+
The default experiment step size should be defined.
21+
It should indicate the actual model refresh rate for the input side.
22+
A simulator can call the FMU `fmi2DoStep` routine at this implied rate.
23+
If the step size is not supplied, the model communication rate is determined from any input configuration data the model provides, or it must be configured manually.
24+
25+
The model may have inputs, outputs, and parameters that are not specified by OSMP if the model can be run correctly with all of those variables left unconnected and at their default values.

‎doc/spec/binary_variables.adoc‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
= Binary variables
2+
3+
FMI 2.0 does not directly support the efficient exchange of arbitrary binary data between FMUs.
4+
OSMP, therefore, introduces the concept of notional binary variables, which are mapped to actual integer variables for use with FMI 2.0.
5+
Future FMI versions will directly support binary variables compatible with this concept.
6+
7+
A notional binary variable named `<prefix>` is defined using the following conventions:
8+
9+
The name of the notional binary variable given by `<prefix>` shall be a valid structured name according to FMI 2.0.
10+
11+
The FMU shall not contain any other variable that is named `<prefix>`.
12+
This restriction ensures that there is no conflict between notional binary variables and actual variables.
13+
14+
For each notional binary variable, three actual FMU integer variables shall be defined:
15+
16+
`<prefix>.base.lo`::
17+
Lower, meaning least significant, 32-bit address part of the binary data buffer to be passed into or out of the model, cast into a signed 32-bit integer without changing the bit values.
18+
`<prefix>.base.hi`::
19+
Higher, meaning most significant, 32-bit address part of the binary data buffer to be passed into or out of the model, cast into a signed 32-bit integer without changing the bit values.
20+
Note that this variable is only used for 64-bit platforms.
21+
For 32-bit platforms, it shall still be present but will always be 0 to support FMUs with 32-bit and 64-bit implementations.
22+
`<prefix>.size`::
23+
Size of the binary data buffer to be passed into or out of the model as a signed 32-bit integer.
24+
This restricts the maximum size of binary data buffers being passed around to a size less than 2 GB.
25+
26+
The three actual variables shall have matching causality and variability, which will be the causality and variability of the notional binary variable.
27+
28+
The variables shall have a start value of 0, indicating that no valid binary data buffer is available.
29+
The variables may have a different or no start value if the combination of causality and variability precludes this, for example, for `@variability = fixed` or `@variability = tunable` and `@causality = calculatedParameter`.
30+
31+
Model FMUs shall interpret values of 0 for the merged base address or the size to indicate that no valid binary data buffer is available.
32+
Models FMUs shall handle this case safely.
33+
34+
The three actual variables shall contain an annotation of the following form in the `<Annotations>` child element of their `<ScalarVariable>` element of the `modelDescription.xml`:
35+
36+
[source,xml]
37+
----
38+
<Tool name="net.pmsf.osmp" xmlns:osmp="http://xsd.pmsf.net/OSISensorModelPackaging"><osmp:osmp-binary-variable name="<prefix>" role="<role>" mime-type="<mime-type>"/></Tool>
39+
----
40+
41+
`<prefix>` is the prefix as defined above, and `@role` is either `base.lo`, `base.hi`, or `size`, depending on the variable.
42+
43+
It is an error if there is not exactly one variable of each role for the same name.
44+
45+
The MIME type given in `@mime-type` shall be a valid MIME type specification.
46+
47+
It is an error if the MIME types specified in the annotations for one notional binary variable differ.
48+
49+
In the case of OSI-specified data, the MIME type shall have the following form to indicate that the binary content is conformant to the given OSI version and contains a message of the given type:
50+
51+
[source,xml]
52+
----
53+
application/x-open-simulation-interface; type=<type>; version=x.y.z
54+
----
55+
56+
`<type>` shall be the name of an OSI top-level message, excluding the `osi3::` prefix.
57+
58+
The version parameter of the MIME type `application/x-open-simulation-interface` will default to the version specified in the `@osi-version` attribute as part of the top-level `<osmp:osmp>` annotation.
59+
It is an error if a version number is specified neither as part of the MIME type nor using the `@osi-version` attribute.
60+
61+
The guaranteed lifetime of the binary data buffer pointer transported through the actual variables is defined for each kind of variable, as specified in the following sections.
62+
63+
Generally the lifetime for inputs is from the time they are set to the time the corresponding co-simulation step calculation finishes.
64+
For outputs the lifetime is extended from the point the output is provided at the end of a co-simulation step until the end of the next co-simulation step.
65+
66+
This convention allows the use of FMUs in simulation engines that have no special support for the protocol buffer pointers:
67+
The simulation engine can rely on the provided buffer to remain valid from the moment it is passed out of a model until the end of the next co-simulation calculation cycle.
68+
Thus, the simulation engine does not need to copy the contents in that case, corresponding to zero-copy output for the simulation engine at the cost of double buffering for the model providing the output data.
69+
It is possible to daisy-chain FMUs with protocol buffer inputs and outputs in a normal simulation engine supporting FMI, and get valid results.

‎doc/spec/ground_truth_init_parameters.adoc‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
= Ground truth initialization parameters
2+
3+
All models can optionally consume `osi3::GroundTruth` via an initialization parameter called `OSMPGroundTruthInit`.
4+
Its purpose is to provide the model with a view of the static environment, for example the map, in OSI format.
5+
6+
`OSMPGroundTruthInit` contains all static data encountered by the model during a simulation run, for example, roads.
7+
All data provided in this message can be assumed by the receiver to be static during the simulation run.
8+
9+
If the model is instantiated multiple times, all instantiations should receive the exact same content.
10+
This allows a model to do expensive map calculations only once during initialization, and to share the calculated data between multiple instantiations.
11+
12+
**Prefix**
13+
14+
Ground truth initialization paramters shall be named with the following prefix:
15+
16+
[source]
17+
----
18+
OSMPGroundTruthInit
19+
----
20+
21+
**Rules**
22+
23+
* If a model needs ground truth during initialization, it shall have a parameter named `OSMPGroundTruthInit`.
24+
* `OSMPGroundTruthInit` shall be defined as a notional discrete binary input parameter variable, with `@causality="parameter"`, `@variability="fixed"` and `@initial="exact"`.
25+
* The MIME type of the variable shall specify the `type=GroundTruth` as part of the MIME type parameters.
26+
* `OSMPGroundTruthInit` shall be encoded as `osi3::GroundTruth`.
27+
* `OSMPGroundTruthInit` shall contain all static data encountered by the model during a simulation run.
28+
* The IDs of objects in `OSMPGroundTruthInit` shall be identical to the IDs of the same objects contained in later `OSMPSensorViewIn` or other input data.
29+
* If the model is instantiated multiple times, then all instantiations should receive the exact same content stored in the `OSMPGroundTruthInit` parameter.
30+
* The guaranteed lifetime of the ground-truth protocol-buffer pointer provided as input to the FMU shall be from the time of the call to `fmi2SetInteger` that provides those values until the end of the following `fmi2ExitInitializationMode` call.

0 commit comments

Comments
 (0)