From 155cde9697c22cac90af95440526c5abb45143dd Mon Sep 17 00:00:00 2001 From: Daniel Becker Date: Mon, 30 Jan 2023 09:36:07 +0100 Subject: [PATCH] Use new documentation structure Signed-off-by: Daniel Becker --- .antora/antora.yml | 11 + .antora/modules/sensor-model/nav.adoc | 22 + .antora/modules/sensor-model/pages | 1 + .github/pull_request_template.md | 2 +- .github/workflows/antora-generator.yml | 28 ++ .github/workflows/protobuf.yml | 62 +++ .travis.yml | 44 -- README.md | 13 +- doc/_config.adoc | 52 ++ doc/examples.rst | 9 - doc/misc/example.adoc | 71 +++ doc/misc/introduction.adoc | 11 + doc/osi-sensor-model-packaging_spec.adoc | 42 ++ doc/setup/build_install_example.adoc | 72 +++ doc/spec/basic_conventions.adoc | 29 ++ doc/spec/binary_variables.adoc | 73 +++ doc/spec/ground_truth_init_parameters.adoc | 34 ++ doc/spec/model_types.adoc | 32 ++ doc/spec/motion_request_inputs.adoc | 29 ++ doc/spec/motion_request_outputs.adoc | 29 ++ doc/spec/sensor_data_inputs.adoc | 24 + doc/spec/sensor_data_outputs.adoc | 24 + doc/spec/sensor_view_input_configuration.adoc | 44 ++ doc/spec/sensor_view_inputs.adoc | 25 + doc/spec/sensor_view_outputs.adoc | 24 + doc/spec/traffic_command_inputs.adoc | 27 + doc/spec/traffic_command_update_outputs.adoc | 26 + doc/spec/traffic_update_outputs.adoc | 26 + doc/specification.rst | 471 ------------------ examples/CMakeLists.txt | 8 + examples/OSMPCNetworkProxy/CMakeLists.txt | 21 +- .../OSMPCNetworkProxy/OSMPCNetworkProxy.c | 2 +- .../OSMPCNetworkProxy/OSMPCNetworkProxy.h | 1 + .../OSMPCNetworkProxyConfig.in.h | 19 + .../OSMPCNetworkProxy/modelDescription.in.xml | 16 +- examples/OSMPDummySensor/CMakeLists.txt | 18 +- examples/OSMPDummySensor/OSMPDummySensor.cpp | 34 +- examples/OSMPDummySensor/OSMPDummySensor.h | 10 +- .../OSMPDummySensorConfig.in.h | 15 + .../OSMPDummySensor/modelDescription.in.xml | 28 +- examples/OSMPDummySource/CMakeLists.txt | 18 +- examples/OSMPDummySource/OSMPDummySource.cpp | 22 +- examples/OSMPDummySource/OSMPDummySource.h | 6 +- .../OSMPDummySourceConfig.in.h | 15 + .../OSMPDummySource/modelDescription.in.xml | 10 +- examples/open-simulation-interface | 2 +- local_build_tools/asciidoctor.bat | 3 + local_build_tools/compose.yml | 8 + .../windows_convert_symlinks(ADMIN).bat | 13 + osmp.xsd | 6 +- 50 files changed, 1005 insertions(+), 627 deletions(-) create mode 100644 .antora/antora.yml create mode 100644 .antora/modules/sensor-model/nav.adoc create mode 120000 .antora/modules/sensor-model/pages create mode 100644 .github/workflows/antora-generator.yml create mode 100644 .github/workflows/protobuf.yml delete mode 100644 .travis.yml create mode 100644 doc/_config.adoc delete mode 100644 doc/examples.rst create mode 100644 doc/misc/example.adoc create mode 100644 doc/misc/introduction.adoc create mode 100644 doc/osi-sensor-model-packaging_spec.adoc create mode 100644 doc/setup/build_install_example.adoc create mode 100644 doc/spec/basic_conventions.adoc create mode 100644 doc/spec/binary_variables.adoc create mode 100644 doc/spec/ground_truth_init_parameters.adoc create mode 100644 doc/spec/model_types.adoc create mode 100644 doc/spec/motion_request_inputs.adoc create mode 100644 doc/spec/motion_request_outputs.adoc create mode 100644 doc/spec/sensor_data_inputs.adoc create mode 100644 doc/spec/sensor_data_outputs.adoc create mode 100644 doc/spec/sensor_view_input_configuration.adoc create mode 100644 doc/spec/sensor_view_inputs.adoc create mode 100644 doc/spec/sensor_view_outputs.adoc create mode 100644 doc/spec/traffic_command_inputs.adoc create mode 100644 doc/spec/traffic_command_update_outputs.adoc create mode 100644 doc/spec/traffic_update_outputs.adoc delete mode 100644 doc/specification.rst create mode 100644 examples/OSMPCNetworkProxy/OSMPCNetworkProxyConfig.in.h create mode 100644 examples/OSMPDummySensor/OSMPDummySensorConfig.in.h create mode 100644 examples/OSMPDummySource/OSMPDummySourceConfig.in.h create mode 100644 local_build_tools/asciidoctor.bat create mode 100644 local_build_tools/compose.yml create mode 100644 local_build_tools/windows_convert_symlinks(ADMIN).bat diff --git a/.antora/antora.yml b/.antora/antora.yml new file mode 100644 index 0000000..009e10a --- /dev/null +++ b/.antora/antora.yml @@ -0,0 +1,11 @@ +# Component name (without spaces!). All content repositories with the same component name are merged in Antora. +name: asamosi +version: + # Update version number accordingly. This is the version for the main branch + main: 'current' + master: 'current' + v(*)-antora: V$1 + v(*): V$1 + V(*): V$1 + # Update version number accordingly. This is the version for any other activated branch (branch must be added in the generator site.yml!). Schema = 0.0.x- (only works for branches starting with "feature/") + (*): 'V3.6.0-$1' diff --git a/.antora/modules/sensor-model/nav.adoc b/.antora/modules/sensor-model/nav.adoc new file mode 100644 index 0000000..fe006b5 --- /dev/null +++ b/.antora/modules/sensor-model/nav.adoc @@ -0,0 +1,22 @@ +[preface] +* xref:00_preface/00_foreword.adoc[] +[preface] +* xref:00_preface/01_introduction.adoc[] +* xref:01_scope/01_scope.adoc[] +* xref:02_normative_references/01_normative_references.adoc[] +* xref:03_terms_and_definitions/01_terms_and_definitions.adoc[] +* xref:04_abbreviations/01_abbreviations.adoc[] +* xref:05_backward_compatibility/01_backward_compatibility.adoc[] + +[appendix] +* xref:xx_annexes/REPLACE_ME.adoc[] +[bibliography] +* xref:bibliography.adoc[] + +:sectnums!: +* xref:list_of_figures.adoc[] + +:sectnums!: +* xref:list_of_tables.adoc[] + +// TODO Replace with generator \ No newline at end of file diff --git a/.antora/modules/sensor-model/pages b/.antora/modules/sensor-model/pages new file mode 120000 index 0000000..b8f7789 --- /dev/null +++ b/.antora/modules/sensor-model/pages @@ -0,0 +1 @@ +../../../doc \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 576354b..99c3fa4 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -19,4 +19,4 @@ Add @mentions of the person or team responsible for reviewing proposed changes. - [ ] I have made corresponding changes to the [documentation](https://github.com/OpenSimulationInterface/osi-documentation) for osi-sensor-model-packaging. - [ ] My changes generate no new warnings. - [ ] I have added tests that prove my fix is effective or that my feature works. -- [ ] New and existing unit tests / travis ci pass locally with my changes. \ No newline at end of file +- [ ] New and existing unit tests / Github Actions pass locally with my changes. \ No newline at end of file diff --git a/.github/workflows/antora-generator.yml b/.github/workflows/antora-generator.yml new file mode 100644 index 0000000..6811b1d --- /dev/null +++ b/.github/workflows/antora-generator.yml @@ -0,0 +1,28 @@ + +name: Antora build trigger + +on: + push: + branches: [ master ] + pull_request: + branches: [ master ] + +jobs: + trigger_antora: + name: Trigger antora generator + + runs-on: Ubuntu-latest + + env: + MUP_KEY: ${{ secrets.MACHINE_USER_PAT }} + + steps: + - name: Trigger generator + if: ${{ env.MUP_KEY != '' }} + uses: peter-evans/repository-dispatch@v2 + with: + token: ${{ secrets.MACHINE_USER_PAT }} + event-type: antora-build-trigger + repository: OpenSimulationInterface/osi-antora-generator + client-payload: '{"src": "${{ github.repository }}", "ref": "${{ github.ref }}", "sha": "${{ github.sha }}", "head_ref": "${{ github.head_ref }}"}' + diff --git a/.github/workflows/protobuf.yml b/.github/workflows/protobuf.yml new file mode 100644 index 0000000..8b9f311 --- /dev/null +++ b/.github/workflows/protobuf.yml @@ -0,0 +1,62 @@ +name: ProtoBuf CI Builds + +on: + push: + pull_request: + branches: [ master ] + +# this is a test + +jobs: + build-osmp-examples: + name: Build OSMP examples + + runs-on: ubuntu-22.04 + + steps: + - name: Checkout OSI + uses: actions/checkout@v2 + with: + submodules: true + + - name: Setup Python + uses: actions/setup-python@v2 + with: + python-version: '3.7' + + # cache dependencies + - name: Cache Dependencies + id: cache-depends + uses: actions/cache@v3 + with: + path: protobuf-3.15.8 + key: ${{ runner.os }}-v2-depends + + # Download and build protobuf + - name: Download ProtoBuf + if: steps.cache-depends.outputs.cache-hit != 'true' + run: curl -OL https://github.com/protocolbuffers/protobuf/releases/download/v3.15.8/protobuf-all-3.15.8.tar.gz && tar xzvf protobuf-all-3.15.8.tar.gz + + - name: Build ProtoBuf + if: steps.cache-depends.outputs.cache-hit != 'true' + working-directory: protobuf-3.15.8 + run: ./configure DIST_LANG=cpp --prefix=/usr && make + + - name: Install ProtoBuf + working-directory: protobuf-3.15.8 + run: sudo make install && sudo ldconfig + + # prepare build + - name: Prepare C++ Build + working-directory: examples + run: mkdir build + + - name: cmake prepare + working-directory: examples/build + run: cmake -D CMAKE_PREFIX_PATH:PATH=${DEPS_DIR}/protobuf/install .. + + - name: Build C++ + working-directory: examples/build + run: cmake --build . + + diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 4b2e3bd..0000000 --- a/.travis.yml +++ /dev/null @@ -1,44 +0,0 @@ -# Source: https://github.com/boostorg/hana/blob/master/.travis.yml - -# Use C++ build environment -language: cpp - -# Protobuf requires g++ (see https://github.com/google/protobuf/blob/master/src/README.md) -compiler: - - gcc - -# Cache dependencies to speed up the build. -cache: - directories: - - ${TRAVIS_BUILD_DIR}/deps/cmake - - ${TRAVIS_BUILD_DIR}/deps/protobuf - -# Handle dependencies in separate directory -before_install: - - DEPS_DIR="${TRAVIS_BUILD_DIR}/deps" - - mkdir -p "${DEPS_DIR}" - - cd "${DEPS_DIR}" - -install: - # Install a recent version of CMake - - | - CMAKE_URL="https://cmake.org/files/v3.7/cmake-3.7.2-Linux-x86_64.tar.gz" - if [ ! -f ${DEPS_DIR}/cmake/bin/cmake ] ; then mkdir -p cmake ; travis_retry wget --no-check-certificate --quiet -O - ${CMAKE_URL} | tar --strip-components=1 -xz -C cmake ; fi - export PATH=${DEPS_DIR}/cmake/bin:${PATH} - - # Install a recent version of the Protobuf - - | - PROTOBUF_URL="https://github.com/google/protobuf/releases/download/v2.6.1/protobuf-2.6.1.tar.gz" - if [ ! -f ${DEPS_DIR}/protobuf/install/bin/protoc ] ; then mkdir -p protobuf ; travis_retry wget --no-check-certificate --quiet -O - ${PROTOBUF_URL} | tar --strip-components=1 -xz -C protobuf ; cd protobuf ; ./configure --prefix=${DEPS_DIR}/protobuf/install ; make ; make install ; fi - export PATH=${DEPS_DIR}/protobuf/install/bin:${PATH} - -# Change directory back to default build directory -before_script: - - cd "${TRAVIS_BUILD_DIR}/examples" - -# Run the build script -script: - - mkdir -p build - - cd build - - cmake -D CMAKE_PREFIX_PATH:PATH=${DEPS_DIR}/protobuf/install .. - - cmake --build . diff --git a/README.md b/README.md index 3eb51cb..132115d 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,13 @@ # OSI Sensor Model Packaging -[![Build Status](https://travis-ci.com/OpenSimulationInterface/osi-sensor-model-packaging.svg?branch=master)](https://travis-ci.com/OpenSimulationInterface/osi-sensor-model-packaging) +[![ProtoBuf CI Builds](https://github.com/OpenSimulationInterface/osi-sensor-model-packaging/actions/workflows/protobuf.yml/badge.svg)](https://github.com/OpenSimulationInterface/osi-sensor-model-packaging/actions/workflows/protobuf.yml) OSI Sensor Model Packaging specifies ways in which models (like e.g. environmental effect models, sensor models and logical models) using the [Open Simulation Interface (OSI)][] are to be packaged for their use in simulation environments using FMI 2.0. -The specification can be found in the [doc/specification.rst](doc/specification.rst) document in this repository. +The specification can be found in the [doc/osi-sensor-model-packaging_spec.adoc](doc/osi-sensor-model-packaging_spec.adoc) document in this repository. -For more detailed information see the [official documentation](https://opensimulationinterface.github.io/osi-documentation/osi-sensor-model-packaging/README.html). +For more detailed information see the [official documentation](https://opensimulationinterface.github.io/osi-documentation/#_osi_sensor_model_packaging). + + [Open Simulation Interface (OSI)]: https://github.com/OpenSimulationInterface/open-simulation-interface @@ -30,7 +32,7 @@ Install `protobuf` 3.0.0: $ sudo apt-get install libprotobuf-dev protobuf-compiler ``` -##### Build and install example +##### Build examples ```bash $ git clone https://github.com/OpenSimulationInterface/osi-sensor-model-packaging.git $ cd osi-sensor-model-packaging @@ -39,6 +41,5 @@ $ cd examples $ mkdir -p build $ cd build $ cmake .. -$ make -$ sudo make install +$ cmake --build . ``` diff --git a/doc/_config.adoc b/doc/_config.adoc new file mode 100644 index 0000000..4e8833a --- /dev/null +++ b/doc/_config.adoc @@ -0,0 +1,52 @@ + +// This file contains AsciiDoc attributes that shall be used in every AsciiDoc file. +// NOTE: Its content is only applied for Asciidoctor! +// If the same attribute is defined in the antora.yml (without @), the antora.yml definition takes precedence for Antora. + +ifndef::root-path[:root-path: ./] + +:partials-path: {root-path}../_additional_content +:appendix-caption: Annex + +// ifndef::use-antora-rules,include-only-once[] +ifndef::include-only-once[] +:GLO_VAR_STA_ASAM_OpenCRG: ASAM OpenCRG +:glo_var_sta_asam_opencrg: {GLO_VAR_STA_ASAM_OpenCRG} +:GLO_VAR_STA_ASAM_OpenDRIVE: ASAM OpenDRIVE +:GLO_VAR_STA_ASAM_OpenLABEL: ASAM OpenLABEL +:GLO_VAR_STA_ASAM_OpenODD: ASAM OpenODD +:GLO_VAR_STA_ASAM_OSI: ASAM OSI® +:GLO_VAR_STA_ASAM_OpenSCENARIO: ASAM OpenSCENARIO +:GLO_VAR_STA_ASAM_OpenXOntology: ASAM OpenXOntology +:GLO_VAR_STA_BSI_PAS_1883: BSI PAS 1883 +:revnumber: --localbuild-- +:revdate: {docdate} +:bibtex-file: ./content/general_docs/bibliography.bib +// Replace PLACEHOLDER with the name of your standard, e.g. OpenDRIVE +:THIS_STANDARD: {GLO_VAR_STA_ASAM_OSI} +:asam-terminology: https://code.asam.net/common/asam-terminology/-/raw/main/terms_and_definitions_opendrive.adoc +:imagesdir: {root-path}/images +:include-only-once: true +:topicdir: topics +:reusedir: reuse +:toclevels: 3 +:xrefstyle: full +:images_open_simulation_interface: ./open-simulation-interface/doc/images +// :images_osi-sensor-model-packaging: ./osi-sensor-model-packaging/doc/images +:doc_open_simulation_interface: ../../open-simulation-interface/doc/ +:doc_osi-sensor-model-packaging: ../../osi-sensor-model-packaging/doc/ +// Since a document spanning multiple repos is rendered here, the pathing regarding images is a bit involved. +// We create a variable for every repo that is included. It point to the repo in question. +// If the subrepo is rendered seperatly, then the variable is set to just "./images" with ifdef. +// Please note that this variable has to used in all image includes. Includes here have to use "image::./images..." +// :images_osi_sensor_model_packaging: ./osi-sensor-model-packaging/doc/images // example +:imagesoutdir: ./images/generated_images +:page-feedbackurl: https://github.com/OpenSimulationInterface/osi-sensor-model-packaging/issues/new + + +endif::[] + + +ifdef::env-gitlab[] +:relfilesuffix: .adoc +endif::[] diff --git a/doc/examples.rst b/doc/examples.rst deleted file mode 100644 index 95e753f..0000000 --- a/doc/examples.rst +++ /dev/null @@ -1,9 +0,0 @@ -Examples -========== -The examples in `this directory `_ can be built using CMake. They require that the open-simulation-interface submodule of the repository is populated. - -The OSMPDummySensor example can be used as a simple dummy sensor model, demonstrating the use of OSI for sensor models consuming SensorView data and generating SensorData output. - -The OSMPDummySource example can be used as a simplistic source of SensorView (including GroundTruth) data, that can be connected to the input of an OSMPDummySensor model, for simple testing and demonstration purposes. - -The OSMPCNetworkProxy example demonstrates a simple C network proxy that can send and receive OSI data via TCP sockets. \ No newline at end of file diff --git a/doc/misc/example.adoc b/doc/misc/example.adoc new file mode 100644 index 0000000..4803e8b --- /dev/null +++ b/doc/misc/example.adoc @@ -0,0 +1,71 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Example: Simple sensor model FMU + +The following example shows the content of a `modelDescription.xml` file that satisfies OSMP requirements. +The example describes a sensor model FMU with one input, one output, and no additional features: + +[source,xml,linenums] +---- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +---- diff --git a/doc/misc/introduction.adoc b/doc/misc/introduction.adoc new file mode 100644 index 0000000..45e8ae7 --- /dev/null +++ b/doc/misc/introduction.adoc @@ -0,0 +1,11 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Introduction + +_OSI Sensor Model Packaging_ (OSMP) is a package layer specification for the _Open Simulation Interface_ (OSI). +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). + +This is version 1.3.0 of this specification. The version number is to be +interpreted according to the https://semver.org/spec/v2.0.0.html[_Semantic Versioning Specification 2.0.0_]. diff --git a/doc/osi-sensor-model-packaging_spec.adoc b/doc/osi-sensor-model-packaging_spec.adoc new file mode 100644 index 0000000..9c446f8 --- /dev/null +++ b/doc/osi-sensor-model-packaging_spec.adoc @@ -0,0 +1,42 @@ +:root-path: ./ +include::{root-path}_config.adoc[] += OSI Sensor Model Packaging + +:antora_mapping: title;numbered +ifndef::use-antora-rules[] +include::./misc/introduction.adoc[leveloffset=+1] + +== OSMP specification + +include::./spec/model_types.adoc[leveloffset=+2] + +include::./spec/basic_conventions.adoc[leveloffset=+2] + +include::./spec/binary_variables.adoc[leveloffset=+2] + +include::./spec/sensor_view_inputs.adoc[leveloffset=+2] + +include::./spec/sensor_view_input_configuration.adoc[leveloffset=+2] + +include::./spec/sensor_view_outputs.adoc[leveloffset=+2] + +include::./spec/sensor_data_inputs.adoc[leveloffset=+2] + +include::./spec/sensor_data_outputs.adoc[leveloffset=+2] + +include::./spec/ground_truth_init_parameters.adoc[leveloffset=+2] + +include::./spec/traffic_command_inputs.adoc[leveloffset=+2] + +include::./spec/traffic_command_update_outputs.adoc[leveloffset=+2] + +include::./spec/traffic_update_outputs.adoc[leveloffset=+2] + +== Examples + +include::./setup/build_install_example.adoc[leveloffset=+2] + +include::./misc/example.adoc[leveloffset=+2] + +endif::[] +:!antora-mapping: \ No newline at end of file diff --git a/doc/setup/build_install_example.adoc b/doc/setup/build_install_example.adoc new file mode 100644 index 0000000..a5c3d83 --- /dev/null +++ b/doc/setup/build_install_example.adoc @@ -0,0 +1,72 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Building and installing examples + +OSMP includes three examples located in `_osmp_/examples`: + +`OSMPDummySensor/`:: +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. + +`OSMPDummySource/`:: +Can be used as a simple source of sensor view data and ground-truth data. +It can be connected to the input of an `OSMPDummySensor` model, for simple testing and demonstration purposes. + +`OSMPCNetworkProxy/`:: +Demonstrates a simple C network proxy that can send and receive OSI data via TCP sockets. + +**Prerequisites** + +* You have installed _cmake_ version 3.10.2 or higher. +* You have installed _protobuf_ version 3.0.0 or higher. + +**Steps** + +. Clone the OSMP repository. ++ +---- +git clone https://github.com/OpenSimulationInterface/osi-sensor-model-packaging.git +---- ++ +. Switch to the OSMP repository. ++ +---- +cd osi-sensor-model-packaging +---- ++ +. Update and initialize the OSI submodule. ++ +---- +git submodule update --init +---- ++ +. Switch to the `examples/` directory. ++ +---- +cd examples +---- ++ +. Create a new directory called `build/`. ++ +---- +mkdir -p build +---- ++ +. Switch to the `build/` directory. ++ +---- +cd build +---- ++ +. Run _cmake_ in the parent directory. ++ +---- +cmake .. +---- ++ +. Run _cmake_ build. ++ +---- +cmake --build . +---- diff --git a/doc/spec/basic_conventions.adoc b/doc/spec/basic_conventions.adoc new file mode 100644 index 0000000..ac1427b --- /dev/null +++ b/doc/spec/basic_conventions.adoc @@ -0,0 +1,29 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Basic conventions + +The model shall be packaged as a valid FMU for co-simulation, as specified in the FMI 2.0 standard cite:[fmi2.0]. +Unless otherwise noted, all specifications in the FMI 2.0 cite:[fmi2.0] standard apply as-is. + +The following annotation shall be placed into the `` element of the `modelDescription.xml` to mark the FMU as being conformant to this version of the specification: + +[source,xml] +---- + +---- + +The `@osi-version` attribute should contain the major, minor, and patch version number of the OSI specification that this model was compiled against. +Indicating the OSI version ensures that the importing environment can determine which OSI version to use prior to communicating with the FMU. + +If OSMP is used without OSI data being transported across binary variables, `@osi-version` should not be specified. + +The variable naming convention of the FMU shall be structured. + +The default experiment step size should be defined. +It should indicate the actual model refresh rate for the input side. +A simulator can call the FMU `fmi2DoStep` routine at this implied rate. +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. + +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. diff --git a/doc/spec/binary_variables.adoc b/doc/spec/binary_variables.adoc new file mode 100644 index 0000000..fa85c95 --- /dev/null +++ b/doc/spec/binary_variables.adoc @@ -0,0 +1,73 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Binary variables + +FMI 2.0 cite:[fmi2.0] does not directly support the efficient exchange of arbitrary binary data between FMUs. +OSMP therefore introduces the concept of notional binary variables that are mapped to actual integer variables for use with FMI 2.0 cite:[fmi2.0]. +Future FMI versions will directly support binary variables compatible with this concept. + +A notional binary variable named `` is defined using the following conventions: + +The name of the notional binary variable given by `` shall be a valid structured name according to FMI 2.0 cite:[fmi2.0]. + +The FMU shall not contain any other variable that is named ``. +This restriction ensures that there is no conflict between notional binary variables and actual variables. + +For each notional binary variable, three actual FMU integer variables shall be defined: + +`.base.lo`:: +Lower, meaning the 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. +`.base.hi`:: +Higher, meaning the 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. +Note that this variable is only used for 64-bit platforms. +For 32-bit platforms, it shall still be present but will always be 0 to support FMUs with 32-bit and 64-bit implementations. +`.size`:: +Size of the binary data buffer to be passed into or out of the model as a signed 32-bit integer. +This restricts the maximum size of binary data buffers being passed around to a size less than 2 GB. + +The three actual variables shall have matching causality and variability, which will be the causality and variability of the notional binary variable. + +The variables shall have a start value of 0, indicating that no valid binary data buffer is available. +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`. + +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. +Models FMUs shall handle this case safely. + +The three actual variables shall contain an annotation of the following form in the `` child element of their `` element of the `modelDescription.xml`: + +[source,xml] +---- + +---- + +`` is the prefix as defined above, and `@role` is either `base.lo`, `base.hi`, or `size`, depending on the variable. + +It is an error if there is not exactly one variable of each role for the same name. + +The MIME type given in `@mime-type` shall be a valid MIME type specification. + +It is an error if the MIME types specified in the annotations for one notional binary variable differ. + +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: + +[source,xml] +---- +application/x-open-simulation-interface; type=; version=x.y.z +---- + +`` shall be the name of an OSI top-level message, excluding the `osi3::` prefix. + +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 `` annotation. +It is an error if a version number is specified neither as part of the MIME type nor using the `@osi-version` attribute. + +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. + +Generally the lifetime for inputs is from the time they are set to the time the corresponding co-simulation step calculation finishes. +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. + +This convention allows the use of FMUs in simulation engines that have no special support for the protocol buffer pointers: +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. +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. +It is possible to daisy-chain FMUs with protocol buffer inputs and outputs in a normal simulation engine supporting FMI, and get valid results. diff --git a/doc/spec/ground_truth_init_parameters.adoc b/doc/spec/ground_truth_init_parameters.adoc new file mode 100644 index 0000000..5ebd704 --- /dev/null +++ b/doc/spec/ground_truth_init_parameters.adoc @@ -0,0 +1,34 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Ground truth initialization parameters + +All models can optionally consume `osi3::GroundTruth` via an initialization parameter called `OSMPGroundTruthInit`. +Its purpose is to provide the model with a view of the static environment, for example the map, in OSI format. + +`OSMPGroundTruthInit` contains all static data encountered by the model during a simulation run, for example, roads. +All data provided in this message can be assumed by the receiver to be static during the simulation run. + +If the model is instantiated multiple times, all instantiations should receive the exact same content. +This allows a model to do expensive map calculations only once during initialization, and to share the calculated data between multiple instantiations. + +**Prefix** + +Ground truth initialization paramters shall be named with the following prefix: + +[source,protobuf] +---- +OSMPGroundTruthInit +---- + +**Rules** + +* If a model needs ground truth during initialization, it shall have a parameter named `OSMPGroundTruthInit`. +* `OSMPGroundTruthInit` shall be defined as a notional discrete binary input parameter variable, with `@causality="parameter"`, `@variability="fixed"` and `@initial="exact"`. +* The MIME type of the variable shall specify the `type=GroundTruth` as part of the MIME type parameters. +* `OSMPGroundTruthInit` shall be encoded as `osi3::GroundTruth`. +* `OSMPGroundTruthInit` shall contain all static data encountered by the model during a simulation run. +* The IDs of objects in `OSMPGroundTruthInit` shall be identical to the IDs of the same objects contained in later `OSMPSensorViewIn` or other input data. +* If the model is instantiated multiple times, then all instantiations should receive the exact same content stored in the `OSMPGroundTruthInit` parameter. +* 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. diff --git a/doc/spec/model_types.adoc b/doc/spec/model_types.adoc new file mode 100644 index 0000000..2065daa --- /dev/null +++ b/doc/spec/model_types.adoc @@ -0,0 +1,32 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Model types + +The current specification supports packaging the following model types as _Functional Mock-up Units_ (FMUs): + +Environmental effect model:: +This model type can be used to model environmental effects or the physical parts of sensors. +It consumes `osi3::SensorView` as input and produces `osi3::SensorView` as output. + +Sensor models:: +This model type is used to model the perception function of sensors. +It consumes `osi3::SensorView` as input and produces `osi3::SensorData` as output. + +Logical models:: +This model type is used to model the further processing of sensor output, for example, sensor fusion. +It consumes `osi3::SensorData` as input and produces `osi3::SensorData` as output. + +Traffic participant models:: +This model type is used to model whole traffic participants, such as vehicles or pedestrians. +Traffic participant models may internally use environmental effect models, sensor models, or logical models as part of a modeled autonomous vehicle. +They may also be used to implement surrounding traffic in simplified ways. +Traffic participant models consume `osi3::SensorView` as input and produce `osi3::TrafficUpdate` as output. +They may also consume `osi3::TrafficCommand` as input to allow control by a scenario engine or other coordinating function. +They may also produce `osi3::TrafficCommandUpdate` as output to allow status responses to such control messages. + +All models may also consume a global `osi3::GroundTruth` parameter during initialization. + +Complex models may combine various aspects of the above model types. +Manual intervention is needed to configure and set up these FMUs. diff --git a/doc/spec/motion_request_inputs.adoc b/doc/spec/motion_request_inputs.adoc new file mode 100644 index 0000000..f8a19a4 --- /dev/null +++ b/doc/spec/motion_request_inputs.adoc @@ -0,0 +1,29 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Motion request inputs + +This message is intended as an interface between a behavior model (e.g. driver model or HAD function) and the actuator management. +Either a desired future trajectory or a desired future state may be sent. + +**Prefix** + +Motion request inputs shall be named with the following prefix: + +[source,protobuf] +---- +OSMPMotionRequestIn +---- + +**Rules** + +* If only one motion request input is configured, the prefix shall only be `OSMPMotionRequestIn`. +* If more than one motion request input is configured, the prefix shall be extended by an array index, for example, `OSMPMotionRequestIn[1]` and `OSMPMotionRequestIn[2]`. +* Array indices shall start at 1 and shall be consecutive. +* Each motion request input shall be defined as a notional discrete binary input variable with `@causality="input"` and `@variability="discrete"`. +* The MIME type of the variable shall specify the `type=MotionRequest` as part of the MIME type parameters. +* Motion request data shall be encoded as `osi3::MotionRequest`. +* The motion request passed to the FMU must contain one of the available ``OutputOptions`` (**rename**). In addition to the enumerator, the corresponding ``DesiredState`` or ``Trajectory`` has to be set, respectively. +* The guaranteed lifetime of the motion request 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 `fmi2DoStep` call. + diff --git a/doc/spec/motion_request_outputs.adoc b/doc/spec/motion_request_outputs.adoc new file mode 100644 index 0000000..07f8d1c --- /dev/null +++ b/doc/spec/motion_request_outputs.adoc @@ -0,0 +1,29 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Motion request outputs + +This message is intended as an interface between a behavior model (e.g. driver model or HAD function) and the actuator management. +Either a desired future trajectory or a desired future state may be sent. + +**Prefix** + +Motion request outputs shall be named with the following prefix: + +[source,protobuf] +---- +OSMPMotionRequestOut +---- + +**Rules** + +* If only one motion request output is configured, the prefix shall only be `OSMPMotionRequestOut`. +* If more than one motion request output is configured, the prefix shall be extended by an array index, for example, `OSMPMotionRequestOut[1]` and `OSMPMotionRequestOut[2]`. +* Array indices shall start at 1 and shall be consecutive. +* Each motion request output shall be defined as a notional discrete binary output variable with `@causality="output"` and `@variability="discrete"`. +* The MIME type of the variable shall specify the `type=MotionRequest` as part of the MIME type parameters. +* Motion request data shall be encoded as `osi3::MotionRequest`. +* The motion request passed to the FMU must contain one of the available ``OutputOptions`` (**rename**). In addition to the enumerator, the corresponding ``DesiredState`` or ``Trajectory`` has to be set, respectively. +* The guaranteed lifetime of the motion request protocol-buffer pointer provided as output to the FMU shall be from the time of the call to `fmi2SetInteger` that provides those values until the end of the following `fmi2DoStep` call. + diff --git a/doc/spec/sensor_data_inputs.adoc b/doc/spec/sensor_data_inputs.adoc new file mode 100644 index 0000000..d000378 --- /dev/null +++ b/doc/spec/sensor_data_inputs.adoc @@ -0,0 +1,24 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Sensor data inputs + +**Prefix** + +Sensor data inputs shall be named with the following prefix: + +[source,protobuf] +---- +OSMPSensorDataIn +---- + +**Rules** + +* If only one sensor data input is configured, the prefix shall only be `OSMPSensorDataIn`. +* If more than one sensor data input is configured, the prefix shall be extended by an array index, for example, `OSMPSensorDataIn[1]` and `OSMPSensorDataIn[2]`. +* Array indices shall start at 1 and shall be consecutive. +* Each sensor data input shall be defined as a notional discrete binary input variable with `@causality="input"` and `@variability="discrete"`. +* The MIME type of the variable shall specify the `type="SensorData"` as part of the MIME type parameters. +* Sensor data shall be encoded as `osi3::SensorData`. +* The guaranteed lifetime of the sensor data 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 `fmi2DoStep` call. \ No newline at end of file diff --git a/doc/spec/sensor_data_outputs.adoc b/doc/spec/sensor_data_outputs.adoc new file mode 100644 index 0000000..4d112ec --- /dev/null +++ b/doc/spec/sensor_data_outputs.adoc @@ -0,0 +1,24 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Sensor data outputs + +**Prefix** + +Sensor data outputs shall be named with the following prefix: + +[source,protobuf] +---- +OSMPSensorDataOut +---- + +**Rules** + +* If only one sensor data output is configured, the prefix shall only be `OSMPSensorDataOut`. +* If more than one sensor data output is configured, the prefix shall be extended by an array index, for example, `OSMPSensorDataOut[1]` and `OSMPSensorDataOut[2]`. +* Array indices shall start at 1 and shall be consecutive. +* Each sensor data output shall be defined as a notional discrete binary output variable with `@causality="output"` and `@variability="discrete"`. +* The MIME type of the variable shall specify `type="SensorData"` as part of the MIME type parameters. +* Sensor data shall be encoded as `osi3::SensorData`. +* The guaranteed lifetime of the sensor data protocol-buffer pointer provided as output by the FMU shall be from the end of the call to `fmi2DoStep` that calculated this buffer until the beginning of the second `fmi2DoStep` call after that. \ No newline at end of file diff --git a/doc/spec/sensor_view_input_configuration.adoc b/doc/spec/sensor_view_input_configuration.adoc new file mode 100644 index 0000000..c06b644 --- /dev/null +++ b/doc/spec/sensor_view_input_configuration.adoc @@ -0,0 +1,44 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Sensor view input configuration + +For each notional sensor view input variable with the base prefix `OSMPSensorViewIn`, a corresponding calculated parameter with the base prefix `OSMPSensorViewInConfigRequest` and a parameter with the base prefix `OSMPSensorViewInConfig` can exist. + +During FMI initialization mode, the simulation environment queries the value of `OSMPSensorViewInConfigRequest`. +Taking this value into account, a suitable and supported sensor view input configuration is determined. +Before exiting initialization mode, the simulation environment then sets this configuration using the corresponding `OSMPSensorViewInConfig` parameter. + +**Prefix** + +Sensor view input configurations shall be named with the following prefix: + +[source,protobuf] +---- +OSMPSensorViewInConfig +---- + +Sensor view input configuration requests shall be named with the following prefix: + +[source,protobuf] +---- +OSMPSensorViewInConfigRequest +---- + +**Rules** + +* If more than one sensor view input is to be configured, the prefix shall be extended by an array index, for example, `OSMPSensorViewInConfigRequest[1]`, `OSMPSensorViewInConfig[1]`, `OSMPSensorViewInConfigRequest[2]`, and `OSMPSensorViewInConfig[2]`. +* Array indices shall start at 1, shall be consecutive, and shall correspond between sensor view inputs and sensor view configuration parameters. +* If the calculated parameter `OSMPSensorViewInConfigRequest` exists, then the corresponding parameter `OSMPSensorViewInConfig` shall exist. +* `OSMPSensorViewInConfigRequest` shall have a `@causality = "calculatedParameter"` and a `@variability = "fixed"` or `@variability = "tunable"`. +* `OSMPSensorViewInConfig` shall have a `@causality = "parameter"` and a `@variability = "fixed"` or `@variability = "tunable"`. +* The `@variability` values of `OSMPSensorViewInConfigRequest` and `OSMPSensorViewInConfig` shall match. +* The MIME type of both variables shall specify `type="SensorViewConfiguration"` as part of the MIME type parameters. +* The variable values shall be encoded as `osi3::SensorViewConfiguration`. +* As long as no non-zero value has been assigned to `OSMPSensorViewInConfig`, the value of the corresponding `OSMPSensorViewInConfigRequest` shall be the desired sensor view configuration for the corresponding variable `OSMPSensorViewIn`. +This configuration is based on model-internal requirements or any other parameters on which this calculated parameter depends. +* Once a non-zero value has been assigned to `OSMPSensorViewInConfig`, the value of the corresponding `OSMPSensorViewInConfigRequest` shall be an encoded OSI protocol buffer containing the same data as the `OSMPSensorViewInConfig`. +* During FMI initialization mode, the simulation environment should query the value of `OSMPSensorViewInConfigRequest` and determine a suitable sensor view input configuration. +* Before exiting initialization mode, the simulation environment shall set the sensor view input configuration using the corresponding `OSMPSensorViewInConfig` parameter. +* The guaranteed lifetime of the sensor view configuration protocol-buffer pointers shall be from the time of the call to `fmi2SetInteger` that provides those values until the end of the FMI initialization mode, indicating by the return of the `fmi2ExitInitializationMode` call. \ No newline at end of file diff --git a/doc/spec/sensor_view_inputs.adoc b/doc/spec/sensor_view_inputs.adoc new file mode 100644 index 0000000..9b1f735 --- /dev/null +++ b/doc/spec/sensor_view_inputs.adoc @@ -0,0 +1,25 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Sensor view inputs + +**Prefix** + +Sensor view inputs shall be named with the following prefix: + +[source,protobuf] +---- +OSMPSensorViewIn +---- + +**Rules** + +* If only one sensor view input is configured, the prefix shall only be `OSMPSensorViewIn`. +* If more than one sensor view input is configured, the prefix shall be extended by an array index, for example, `OSMPSensorViewIn[1]` and `OSMPSensorViewIn[2]`. +* Array indices shall start at 1 and shall be consecutive. +* Each sensor view input shall be defined as a notional discrete binary input variable with `@causality="input"` and `@variability="discrete"`. +* The MIME type of the variable shall specify the `type=SensorView` as part of the MIME type parameters. +* Sensor view data shall be encoded as `osi3::SensorView`. +* The sensor view passed to the model shall contain data as specified by the parameter `OSMPSensorViewInConfiguration`. +* The guaranteed lifetime of the sensor view 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 `fmi2DoStep` call. diff --git a/doc/spec/sensor_view_outputs.adoc b/doc/spec/sensor_view_outputs.adoc new file mode 100644 index 0000000..3086b29 --- /dev/null +++ b/doc/spec/sensor_view_outputs.adoc @@ -0,0 +1,24 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Sensor view outputs + +**Prefix** + +Sensor view outputs shall be named with the following prefix: + +[source,protobuf] +---- +OSMPSensorViewOut +---- + +**Rules** + +* If only one sensor view output is configured, the prefix shall only be `OSMPSensorViewOut`. +* If more than one sensor view output is configured, the prefix shall be extended by an array index, for example, `OSMPSensorViewOut[1]` and `OSMPSensorViewOut[2]`. +* Array indices shall start at 1 and shall be consecutive. +* Each sensor view output shall be defined as a notional discrete binary output variable with `@causality="output"` and `@variability="discrete"`. +* The MIME type of the variable shall specify the `type="SensorView"` as part of the MIME type parameters. +* Sensor view data shall be encoded as `osi3::SensorView`. +* The guaranteed lifetime of the sensor view protocol-buffer pointer provided as output by the FMU shall be from the end of the call to `fmi2DoStep` that calculated this buffer until the beginning of the second `fmi2DoStep` call after that. \ No newline at end of file diff --git a/doc/spec/traffic_command_inputs.adoc b/doc/spec/traffic_command_inputs.adoc new file mode 100644 index 0000000..bc318fb --- /dev/null +++ b/doc/spec/traffic_command_inputs.adoc @@ -0,0 +1,27 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Traffic command inputs + +Traffic command inputs are present in traffic participant models. +This makes it possible to control the traffic participant behavior using scenario engines. + +**Prefix** + +Traffic command inputs shall be named with the following prefix: + +[source,protobuf] +---- +OSMPTrafficCommandIn +---- + +**Rules** + +* If only one traffic command input is configured, the prefix shall only be `OSMPTrafficCommandIn`. +* If more than one traffic command input is configured, the prefix shall be extended by an array index designator, for example `OSMPTrafficCommandIn[1]` and `OSMPTrafficCommandIn[2]`. +* Array indices shall start at 1 and shall be consecutive. +* Each traffic command input shall be defined as a notional discrete binary input variable with `@causality="input"` and `@variability="discrete"`. +* The MIME type of the variable shall specify the `type="TrafficCommand"` as part of the MIME type parameters. +* Traffic commands shall be encoded as `osi3::TrafficCommand`. +* The guaranteed lifetime of the traffic command 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 `fmi2DoStep` call. diff --git a/doc/spec/traffic_command_update_outputs.adoc b/doc/spec/traffic_command_update_outputs.adoc new file mode 100644 index 0000000..a50a883 --- /dev/null +++ b/doc/spec/traffic_command_update_outputs.adoc @@ -0,0 +1,26 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Traffic command update outputs + +Traffic command update outputs are present in traffic participant models. + +**Prefix** + +Traffic command update outputs shall be named with the following prefix: + +[source,protobuf] +---- +OSMPTrafficCommandUpdateOut +---- + +**Rules** + +* If only one traffic command update output is configured, the prefix shall only be `OSMPTrafficCommandUpdateOut`. +* If more than one traffic command update output is configured, the prefix shall be extended by an array index, for example `OSMPTrafficCommandUpdateOut[1]` and `OSMPTrafficCommandUpdateOut[2]`. +* Array indices shall start at 1 and shall be consecutive. +* Each traffic command update output shall be defined as a notional discrete binary output variable with a `@causality="output"` and a `@variability="discrete"`. +* The MIME type of the variable shall specify the `type=TrafficCommandUpdate` as part of the MIME type parameters. +* Traffic command updates shall be encoded as `osi3::TrafficCommandUpdate`. +* The guaranteed lifetime of the traffic command update protocol-buffer pointer provided as output by the FMU shall be from the end of the call to `fmi2DoStep` that calculated this buffer until the beginning of the second `fmi2DoStep` call after that. \ No newline at end of file diff --git a/doc/spec/traffic_update_outputs.adoc b/doc/spec/traffic_update_outputs.adoc new file mode 100644 index 0000000..c67f1a1 --- /dev/null +++ b/doc/spec/traffic_update_outputs.adoc @@ -0,0 +1,26 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Traffic update outputs + +Traffic update outputs are present in traffic participant models. + +**Prefix** + +Traffic update outputs shall be named with the following prefix: + +[source,protobuf] +---- +OSMPTrafficUpdateOut +---- + +**Rules** + +* If only one traffic update output is configured, the prefix shall only be `OSMPTrafficUpdateOut`. +* If more than one traffic update output is configured, the prefix shall be extended by an array index, for example `OSMPTrafficUpdateOut[1]` and `OSMPTrafficUpdateOut[2]`. +* Array indices shall start at 1 and shall be consecutive. +* Each traffic update output shall be defined as a notional discrete binary output variable with a `@causality="output"` and a `@variability="discrete"`. +* The MIME type of the variable shall specify the `type=TrafficUpdate` as part of the MIME type parameters. +* Traffic updates shall be encoded as `osi3::TrafficUpdate`. +* The guaranteed lifetime of the traffic update protocol-buffer pointer provided as output by the FMU shall be from the end of the call to `fmi2DoStep` that calculated this buffer until the beginning of the second `fmi2DoStep` call after that. \ No newline at end of file diff --git a/doc/specification.rst b/doc/specification.rst deleted file mode 100644 index 084f29f..0000000 --- a/doc/specification.rst +++ /dev/null @@ -1,471 +0,0 @@ -OSI Sensor Model Packaging Specification -======================================== - -This document specifies the ways in which environmental effect models, -sensor models and logical models using the `Open Simulation Interface`_ -are to be packaged for their use in simulation environments using FMI -2.0. - -This is version 1.0.0 of this document. The version number is to be -interpreted according to the `Semantic Versioning Specification (SemVer) -2.0.0`_. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -document are to be interpreted as described in `RFC 2119`_. - -Kinds of Models ---------------- - -The current specification supports the following kinds of models, that -can be packaged as FMUs: - -- Environmental effect models, which consume ``osi::SensorView`` as input - and produce ``osi::SensorView`` as output, - -- Sensor models, which consume ``osi::SensorView`` as input and generate - ``osi::SensorData`` as output, and - -- Logical models, like e.g. sensor fusion models, which consume - ``osi::SensorData`` as input and produce ``osi::SensorData`` as output. - -Additionally complex models that combine various aspects of the model -kinds above are possible, however configuration and setup of such FMUs -will require manual intervention in those cases. - -.. _fmi-20: - -FMI 2.0 -------- - -The model MUST be packaged as a valid `FMI`_ 2.0 FMU for Co-Simulation, -as specified in the `FMI 2.0 standard`_. Unless otherwise noted in this -document all specifications in the FMI 2.0 standard apply as-is. - -Basic Conventions ------------------ - -The following basic conventions apply: - -- In order to mark the FMU as being conformant to this version of the - specification the following annotation MUST be placed into the - ``VendorAnnotations`` element of the ``modelDescription.xml``: - - .. code:: XML - - - - where the ``osi-version`` attribute SHOULD contain the major, minor - and patch version number of the open simulation interface - specification that this model was compiled against. This is to ensure - that the importing environment can determine which OSI version to use - prior to communicating with the FMU, which might be impossible in - cases of major version changes. - - In case this specification is used without OSI data being transported - across binary variables, this attribute SHOULD be left unspecified. - -- The variable naming convention of the FMU MUST be ``structured``. - -- The default experiment step size SHOULD be supplied and SHOULD - indicate the actual model refresh rate (for the input side) in - seconds, i.e. it is OK for the simulation to only call the FMU - fmi2DoStep routine at this implied rate. If it is not supplied the - configuration of the model communication rate is determined from any - input configuration data the model provides (see below) or has to be - performed manually. - -- Besides the model parameters, inputs and outputs specified below the - model can have additional inputs, outputs, and parameters (i.e. all - kinds of variables as specified in the FMI 2.0 standard), as long as - the sensor model can be run correctly with all of those variables - left unconnected and at their default values. The sensor model MUST - NOT rely on other connections (beside the specified data connections) - being made. - -Definition of Binary Variables ------------------------------- - -In order to support the efficient exchange of binary data, especially -binary data as provided for by the OSI `Protocol Buffer `_ definitions, -the following convention is used to define such variables for FMI 2.0: - -- For a notional binary variable of a name given by ````, which - MUST be a valid structured name according to FMI 2.0, three actual - FMU integer variables MUST be defined: - - - ``.base.lo`` (Integer) - - This is the lower (i.e. least significant) 32bit address of the - binary data buffer to be passed into or out of the model, cast - into a signed 32bit integer (without changing bit values, i.e. as - by reinterpret_cast in C++). - - - ``.base.hi`` (Integer) - - This is the higher (i.e. most significant) 32bit address of the - binary data buffer to be passed into or out of the model, cast - into a signed 32bit integer (without changing bit values, i.e. as - by reinterpret_cast in C++). - - Note that this variable is only used for 64bit platforms, for - 32bit platforms it will always be 0, but MUST still be present (in - order to support FMUs including both 32bit and 64bit - implementations). - - - ``.size`` (Integer) - - This is the size of the binary data buffer to be passed into or - out of the model as a signed 32bit integer (restricting the - maximum size of binary data buffers being passed around to < 2GB - of size). - -- The three actual variables MUST have matching causality and - variability, which will be the causality and variability of the - notional binary variable. - -- Unless the causality and variability combination of the actual - variables precludes this (i.e. for fixed or tunable - calculatedParameter), the variables MUST have a start value of 0, - indicating that no valid binary data buffer is available. - - Model FMUs MUST interpret values of 0 for either the base address - (merged from lo and hi for 64bit) or the size to indicate that no - valid binary data buffer is available and must handle this case - safely. - -- The three actual variables MUST contain an annotation of the - following form in the ``Annotations`` child element of their - ``ScalarVariable`` element of the ``modelDescription.xml``: - - .. code:: XML - - - - where ```` is the prefix as defined above, and ```` is - either ``base.lo``, ``base.hi`` or ``size``, depending on the - variable. - - This annotation marks the variable as belonging to a notional binary - variable named ````, with the given variable having the - specified ````, and the transported binary content being - specified by the ``mime-type`` attribute, as given by - ````, which MUST be a valid MIME type specification. - - In the case of OSI-specified data, the MIME type MUST be of the form - ``application/x-open-simulation-interface; type=SensorView; version=3.0.0`` - indicating that the binary content is conformant to a given OSI - version (3.0.0 in this example), containing a message of the type - given in the ``type`` parameter (````osi::SensorView```` in this - example). - - The version parameter given for 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. It is an error if a version - number is specified neither as part of the MIME type nor using the - ``osi-version`` attribute. - - It is an error if the mime-type specified in the annotations for one - notional binary variable (i.e. with identical name attribute) differ, - or if there is not exactly one variable of each role for the same - name. - -- The FMU MUST NOT contain any variable that is named ````: - This restriction ensures that there is no conflict between the - notional binary variable defined and another variable. - -- The guaranteed lifetime of the binary data buffer pointer transported - through the actual variables is defined for each kind of variable - specified below. - -Sensor View Inputs ------------------- - -- Sensor view inputs MUST be named with the prefix - ``OSMPSensorViewIn``. If more than one sensor view input is to be - configured, the prefix MUST be extended by an array index designator, - i.e. two inputs will use the prefixes ``OSMPSensorViewIn[1]`` and - ``OSMPSensorViewIn[2]``. The indices MUST start at 1 and MUST be - consecutive. If only one sensor view input is needed the prefix MUST - be just ``OSMPSensorViewIn``. - -- Each sensor view input MUST be defined as a notional discrete binary - input variable, as specified above, with ``causality="input"`` and - ``variability="discrete"``. - -- The MIME type of the variable MUST specify the ``type=SensorView``, - e.g. - ``application/x-open-simulation-interface; type=SensorView; version=3.0.0``. - -- The sensor view MUST be encoded as ``osi::SensorView`` (see the OSI - specification documentation for more details). - -- The guaranteed lifetime of the sensor view protocol buffer pointer - provided as input to the FMU MUST be from the time of the call to - ``fmi2SetInteger`` that provides those values until the end of the - following ``fmi2DoStep`` call, i.e. the sensor model can rely on the - provided buffer remaining valid from the moment it is passed in until - the end of the corresponding calculation, and thus does not need to - copy the contents in that case (zero copy input). - -- The sensor view passed to the model must contain data as specified by - the corresponding ``OSMPSensorViewInConfiguration`` parameter. - -Sensor View Input Configuration -------------------------------- - -- For each notional sensor view input variable (named with the base - prefix ``OSMPSensorViewIn``) a corresponding calculatedParameter - (named with base prefix ``OSMPSensorViewInConfigRequest``) and a - parameter (named with base prefix ``OSMPSensorViewInConfig``) CAN - exist. If the calculatedParameter exists, then the corresponding - parameter MUST exist. - -- If the calculatedParameter exists it MUST be named with the prefix - ``OSMPSensorViewInConfigRequest``, and MUST have a ``causality`` of - ``calculatedParameter`` and a variability of either ``fixed`` or - ``tunable``. - -- If the parameter exists it MUST be named with the prefix - ``OSMPSensorViewInConfig``, and MUST have a ``causality`` of - ``parameter`` and a variability of either ``fixed`` or ``tunable``, - where the variability MUST match the variability of the corresponding - calculatedParameter. - -- The MIME type of both variables MUST specify the - ``type=SensorViewConfiguration``, e.g. - ``application/x-open-simulation-interface; type=SensorViewConfiguration; version=3.0.0``. - -- The variables values MUST be encoded as ``osi::SensorViewConfiguration`` - (see the OSI specification documentation for more details). - -- As long as no non-zero value has been assigned to the corresponding - ``OSMPSensorViewInConfig`` parameter, the calculated parameter value - MUST be the desired sensor view configuration for the corresponding - ``OSMPSensorViewIn`` variable, based on model internal requirements - and any other parameters on which this calculated parameter depends. - - Once a non-zero value has been assigned to the corresponding - ``OSMPSensorViewInConfig`` parameter, the value of this calculated - parameter MUST be an encoded OSI protocol buffer containing the same - data as the parameter. - -- The simulation environment SHOULD, during FMI initialization mode, - query the ``OSMPSensorViewInConfigRequest`` calculatedParameter - value, and, taking this value into account, determine a suitable and - supported SensorView configuration. The simulation environment MUST set this - configuration using the corresponding ``OSMPSensorViewInConfig`` parameter - before exiting initialization mode. - -Sensor View Outputs -------------------- - -- Sensor view outputs are present in environmental effect models. - -- Sensor view outputs MUST be named with the prefix - ``OSMPSensorViewOut``. If more than one sensor view output is to be - provided, the prefix MUST be extended by an array index designator, - i.e. two outputs will use the prefixes ``OSMPSensorViewOut[1]`` and - ``OSMPSensorViewOut[2]``. The indices MUST start at 1 and MUST be - consecutive. If only one sensor view output is needed the prefix MUST - be just ``OSMPSensorViewOut``. - -- Each sensor view output MUST be defined as a notional discrete binary - output variable, as specified above, with ``causality="output"`` and - ``variability="discrete"``. - -- The MIME type of the variable MUST specify the ``type=SensorView``, - e.g. - ``application/x-open-simulation-interface; type=SensorView; version=3.0.0``. - -- The sensor view MUST be encoded as ``osi::SensorView`` (see the OSI - specification documentation for more details). - -- The guaranteed lifetime of the sensor view protocol buffer pointer - provided as output by the FMU MUST be from the end of the call to - ``fmi2DoStep`` that calculated this buffer until the beginning of the - **second** ``fmi2DoStep`` call after that, i.e. the simulation engine - can rely on the provided buffer remaining valid from the moment it is - passed out until the end of the next Co-Simulation calculation cycle, - and thus does not need to copy the contents in that case (zero copy - output for the simulation engine, at the cost of double buffering for - the environmental effect model). - - This arrangement (and hence the need for double buffering) is - required to support use of the environmental effect model FMUs in - simulation engines that have no special support for the protocol - buffer pointers, i.e. using this convention it is possible to daisy - chain FMUs with protocol buffer inputs/outputs in a normal simulation - engine like e.g. MATLAB/Simulink, and get valid results. - - -Sensor Data Outputs -------------------- - -- Sensor data outputs MUST be named with the prefix - ``OSMPSensorDataOut``. If more than one sensor data output is to be - provided, the prefix MUST be extended by an array index designator, - i.e. two outputs will use the prefixes ``OSMPSensorDataOut[1]`` and - ``OSMPSensorDataOut[2]``. The indices MUST start at 1 and MUST be - consecutive. If only one sensor data output is needed the prefix MUST - be just ``OSMPSensorDataOut``. - -- Each sensor data output MUST be defined as a notional discrete binary - output variable, as specified above, with ``causality="output"`` and - ``variability="discrete"``. - -- The MIME type of the variable MUST specify the ``type=SensorData``, - e.g. - ``application/x-open-simulation-interface; type=SensorData; version=3.0.0``. - -- The sensor data MUST be encoded as ``osi::SensorData`` (see the OSI - specification documentation for more details). - -- The guaranteed lifetime of the sensor data protocol buffer pointer - provided as output by the FMU MUST be from the end of the call to - ``fmi2DoStep`` that calculated this buffer until the beginning of the - **second** ``fmi2DoStep`` call after that, i.e. the simulation engine - can rely on the provided buffer remaining valid from the moment it is - passed out until the end of the next Co-Simulation calculation cycle, - and thus does not need to copy the contents in that case (zero copy - output for the simulation engine, at the cost of double buffering for - the sensor model). - - This arrangement (and hence the need for double buffering) is - required to support use of the sensor model FMUs in simulation - engines that have no special support for the protocol buffer - pointers, i.e. using this convention it is possible to daisy chain - FMUs with protocol buffer inputs/outputs in a normal simulation - engine like e.g. MATLAB/Simulink, and get valid results. - -Sensor Data Inputs ------------------- - -- Sensor data inputs are present in logical models. - -- Sensor data inputs MUST be named with the prefix - ``OSMPSensorDataIn``. If more than one sensor data input is to be - configured, the prefix MUST be extended by an array index designator, - i.e. two inputs will use the prefixes ``OSMPSensorDataIn[1]`` and - ``OSMPSensorDataIn[2]``. The indices MUST start at 1 and MUST be - consecutive. If only one sensor data input is needed the prefix MUST - be just ``OSMPSensorDataIn``. - -- Each sensor data input MUST be defined as a notional discrete binary - input variable, as specified above, with ``causality="input"`` and - ``variability="discrete"``. - -- The MIME type of the variable MUST specify the ``type=SensorData``, - e.g. - ``application/x-open-simulation-interface; type=SensorData; version=3.0.0``. - -- The sensor data MUST be encoded as ``osi::SensorData`` (see the OSI - specification documentation for more details). - -- The guaranteed lifetime of the sensor data protocol buffer pointer - provided as input to the FMU MUST be from the time of the call to - ``fmi2SetInteger`` that provides those values until the end of the - following ``fmi2DoStep`` call, i.e. the logical model can rely on the - provided buffer remaining valid from the moment it is passed in until - the end of the corresponding calculation, and thus does not need to - copy the contents in that case (zero copy input). - -- The sensor data passed to the model depends on any prior models or - processes that generated the data, i.e. the exact details of the - contents will depend on the processing pipeline. - -Examples --------- - -An example dummy sensor model implementation is provided in the -OSMPDummySensor sub-directory of the examples directory of this -repository. Below you can find an example modelDescription.xml file that -would satisfy the requirements of this document for a sensor model FMU -with one input and output and no additional features: - -.. code:: XML - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Future Evolution ----------------- - -For FMI 3.0, which is currently in development, an opaque binary data -type (a binary data type that is defined in the same way as the current -string data type, but length terminated instead of zero-terminated) is -planned to be added. This will allow migration of sensor models using -the current convention to one where the relevant OSMP binary variables -will be directly mapped to such new binary variables, instead of relying -on the annotated trio of integer variables for each notional binary -variable as is currently specified. The life-time of the new FMI 3.0 -variables will be the standard life-time of all FMI variables, and thus -shorter than is currently specified, so copying on input and output is -going to be required. Other than that the current specification can be -mapped 1:1 onto this new mechanism, and once FMI 3.0 is released, an -updated OSMP specification including this option and mapping will be -released. - -.. _Open Simulation Interface: https://github.com/OpenSimulationInterface/open-simulation-interface -.. _Semantic Versioning Specification (SemVer) 2.0.0: http://semver.org/spec/v2.0.0.html -.. _RFC 2119: https://www.ietf.org/rfc/rfc2119.txt -.. _FMI: https://fmi-standard.org/ -.. _FMI 2.0 standard: https://svn.modelica.org/fmi/branches/public/specifications/v2.0/FMI_for_ModelExchange_and_CoSimulation_v2.0.pdf diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt index df037a2..982409b 100644 --- a/examples/CMakeLists.txt +++ b/examples/CMakeLists.txt @@ -16,7 +16,15 @@ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES) "Debug" "Release" "MinSizeRel" "RelWithDebInfo") endif() +set(OSMPVERSION "1.3.0" CACHE STRING "OSMP Version String") + add_subdirectory( open-simulation-interface ) + +get_directory_property(OSI_VERSION_MAJOR DIRECTORY open-simulation-interface DEFINITION VERSION_MAJOR) +get_directory_property(OSI_VERSION_MINOR DIRECTORY open-simulation-interface DEFINITION VERSION_MINOR) +get_directory_property(OSI_VERSION_PATCH DIRECTORY open-simulation-interface DEFINITION VERSION_PATCH) +set(OSIVERSION "${OSI_VERSION_MAJOR}.${OSI_VERSION_MINOR}.${OSI_VERSION_PATCH}") + include_directories( includes ) add_subdirectory( OSMPDummySensor ) add_subdirectory( OSMPDummySource ) diff --git a/examples/OSMPCNetworkProxy/CMakeLists.txt b/examples/OSMPCNetworkProxy/CMakeLists.txt index 68b44da..372bb56 100644 --- a/examples/OSMPCNetworkProxy/CMakeLists.txt +++ b/examples/OSMPCNetworkProxy/CMakeLists.txt @@ -8,6 +8,10 @@ if(WIN32) else() set(PRIVATE_LOG_PATH_CPROXY "/tmp/OSMPCNetworkProxyLog.log" CACHE FILEPATH "Path to write private log file to") endif() +if(PRIVATE_LOGGING) + file(TO_NATIVE_PATH ${PRIVATE_LOG_PATH_CPROXY} PRIVATE_LOG_PATH_CPROXY_NATIVE) + string(REPLACE "\\" "\\\\" PRIVATE_LOG_PATH ${PRIVATE_LOG_PATH_CPROXY_NATIVE}) +endif() set(VERBOSE_FMI_LOGGING OFF CACHE BOOL "Enable detailed FMI function logging") set(DEBUG_BREAKS OFF CACHE BOOL "Enable debugger traps for debug builds of FMU") set(FMU_DEFAULT_ADDRESS "127.0.0.1" CACHE STRING "Default address for connections") @@ -17,27 +21,15 @@ set(FMU_LISTEN OFF CACHE BOOL "Create FMU that passively listens (server mode)") string(TIMESTAMP FMUTIMESTAMP UTC) string(MD5 FMUGUID modelDescription.in.xml) configure_file(modelDescription.in.xml modelDescription.xml @ONLY) +configure_file(OSMPCNetworkProxyConfig.in.h OSMPCNetworkProxyConfig.h) add_library(OSMPCNetworkProxy SHARED OSMPCNetworkProxy.c) set_target_properties(OSMPCNetworkProxy PROPERTIES PREFIX "") target_compile_definitions(OSMPCNetworkProxy PRIVATE "FMU_SHARED_OBJECT") -target_compile_definitions(OSMPCNetworkProxy PRIVATE "FMU_GUID=\"${FMUGUID}\"") -target_compile_definitions(OSMPCNetworkProxy PRIVATE "FMU_DEFAULT_ADDRESS=\"${FMU_DEFAULT_ADDRESS}\"") -target_compile_definitions(OSMPCNetworkProxy PRIVATE "FMU_DEFAULT_PORT=\"${FMU_DEFAULT_PORT}\"") -if(PRIVATE_LOGGING) - file(TO_NATIVE_PATH ${PRIVATE_LOG_PATH_CPROXY} PRIVATE_LOG_PATH_CPROXY_NATIVE) - string(REPLACE "\\" "\\\\" PRIVATE_LOG_PATH_CPROXY_ESCAPED ${PRIVATE_LOG_PATH_CPROXY_NATIVE}) - target_compile_definitions(OSMPCNetworkProxy PRIVATE - "PRIVATE_LOG_PATH=\"${PRIVATE_LOG_PATH_CPROXY_ESCAPED}\"") -endif() -target_compile_definitions(OSMPCNetworkProxy PRIVATE - $<$:FMU_LISTEN> - $<$:PUBLIC_LOGGING> - $<$:VERBOSE_FMI_LOGGING> - $<$:DEBUG_BREAKS>) if(WIN32) target_link_libraries(OSMPCNetworkProxy wsock32 ws2_32) endif() +include_directories(${CMAKE_CURRENT_BINARY_DIR}) if(WIN32) if(${CMAKE_SIZEOF_VOID_P} EQUAL 8) @@ -67,5 +59,6 @@ add_custom_command(TARGET OSMPCNetworkProxy COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_BINARY_DIR}/modelDescription.xml" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/modelDescription.xml" COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_SOURCE_DIR}/OSMPCNetworkProxy.c" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/sources/OSMPCNetworkProxy.c" COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_SOURCE_DIR}/OSMPCNetworkProxy.h" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/sources/OSMPCNetworkProxy.h" + COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_BINARY_DIR}/OSMPCNetworkProxyConfig.h" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/sources/OSMPCNetworkProxyConfig.h" COMMAND ${CMAKE_COMMAND} -E copy $ "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/binaries/${FMI_BINARIES_PLATFORM}" COMMAND ${CMAKE_COMMAND} -E chdir "${CMAKE_CURRENT_BINARY_DIR}/buildfmu" ${CMAKE_COMMAND} -E tar "cfv" "../OSMPCNetworkProxy.fmu" --format=zip "modelDescription.xml" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/sources" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/binaries/${FMI_BINARIES_PLATFORM}") diff --git a/examples/OSMPCNetworkProxy/OSMPCNetworkProxy.c b/examples/OSMPCNetworkProxy/OSMPCNetworkProxy.c index 782e971..1de4e30 100644 --- a/examples/OSMPCNetworkProxy/OSMPCNetworkProxy.c +++ b/examples/OSMPCNetworkProxy/OSMPCNetworkProxy.c @@ -359,7 +359,7 @@ fmi2Status doExitInitializationMode(OSMPCNetworkProxy component) return fmi2OK; } -fmi2Status doCalc(OSMPCNetworkProxy component, fmi2Real currentCommunicationPoint, fmi2Real communicationStepSize, fmi2Boolean noSetFMUStatePriorToCurrentPointfmi2Component) +fmi2Status doCalc(OSMPCNetworkProxy component, fmi2Real currentCommunicationPoint, fmi2Real communicationStepSize, fmi2Boolean noSetFMUStatePriorToCurrentPoint) { void* buffer=NULL; int buffersize=0; diff --git a/examples/OSMPCNetworkProxy/OSMPCNetworkProxy.h b/examples/OSMPCNetworkProxy/OSMPCNetworkProxy.h index 49ed543..3c237e7 100644 --- a/examples/OSMPCNetworkProxy/OSMPCNetworkProxy.h +++ b/examples/OSMPCNetworkProxy/OSMPCNetworkProxy.h @@ -8,6 +8,7 @@ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ +#include "OSMPCNetworkProxyConfig.h" #include #include #include diff --git a/examples/OSMPCNetworkProxy/OSMPCNetworkProxyConfig.in.h b/examples/OSMPCNetworkProxy/OSMPCNetworkProxyConfig.in.h new file mode 100644 index 0000000..e63f2cc --- /dev/null +++ b/examples/OSMPCNetworkProxy/OSMPCNetworkProxyConfig.in.h @@ -0,0 +1,19 @@ +/* + * PMSF FMU Framework for FMI 2.0 Co-Simulation FMUs + * + * (C) 2016 -- 2018 PMSF IT Consulting Pierre R. Mai + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + */ + +#cmakedefine PUBLIC_LOGGING +#cmakedefine PRIVATE_LOG_PATH "@PRIVATE_LOG_PATH@" +#cmakedefine VERBOSE_FMI_LOGGING +#cmakedefine DEBUG_BREAKS +#define FMU_GUID "@FMUGUID@" + +#cmakedefine FMU_LISTEN +#define FMU_DEFAULT_ADDRESS "@FMU_DEFAULT_ADDRESS@" +#define FMU_DEFAULT_PORT "@FMU_DEFAULT_PORT@" diff --git a/examples/OSMPCNetworkProxy/modelDescription.in.xml b/examples/OSMPCNetworkProxy/modelDescription.in.xml index 4440d24..61bb1cd 100644 --- a/examples/OSMPCNetworkProxy/modelDescription.in.xml +++ b/examples/OSMPCNetworkProxy/modelDescription.in.xml @@ -5,7 +5,7 @@ guid="@FMUGUID@" description="OSMP Network Proxy FMU" author="PMSF" - version="1.3" + version="@OSMPVERSION@" generationTool="PMSF Manual FMU Framework" generationDateAndTime="@FMUTIMESTAMP@" variableNamingConvention="structured"> @@ -24,43 +24,43 @@ - + - + - + - + - + - + - + diff --git a/examples/OSMPDummySensor/CMakeLists.txt b/examples/OSMPDummySensor/CMakeLists.txt index 155a96c..625725d 100644 --- a/examples/OSMPDummySensor/CMakeLists.txt +++ b/examples/OSMPDummySensor/CMakeLists.txt @@ -11,33 +11,28 @@ if(WIN32) else() set(PRIVATE_LOG_PATH "/tmp/OSMPDummySensorLog.log" CACHE FILEPATH "Path to write private log file to") endif() +if(PRIVATE_LOGGING) + file(TO_NATIVE_PATH ${PRIVATE_LOG_PATH} PRIVATE_LOG_PATH_NATIVE) + string(REPLACE "\\" "\\\\" PRIVATE_LOG_PATH ${PRIVATE_LOG_PATH_NATIVE}) +endif() set(VERBOSE_FMI_LOGGING OFF CACHE BOOL "Enable detailed FMI function logging") set(DEBUG_BREAKS OFF CACHE BOOL "Enable debugger traps for debug builds of FMU") string(TIMESTAMP FMUTIMESTAMP UTC) string(MD5 FMUGUID modelDescription.in.xml) configure_file(modelDescription.in.xml modelDescription.xml @ONLY) +configure_file(OSMPDummySensorConfig.in.h OSMPDummySensorConfig.h) find_package(Protobuf 2.6.1 REQUIRED) add_library(OSMPDummySensor SHARED OSMPDummySensor.cpp) set_target_properties(OSMPDummySensor PROPERTIES PREFIX "") target_compile_definitions(OSMPDummySensor PRIVATE "FMU_SHARED_OBJECT") -target_compile_definitions(OSMPDummySensor PRIVATE "FMU_GUID=\"${FMUGUID}\"") if(LINK_WITH_SHARED_OSI) target_link_libraries(OSMPDummySensor open_simulation_interface) else() target_link_libraries(OSMPDummySensor open_simulation_interface_pic) endif() -if(PRIVATE_LOGGING) - file(TO_NATIVE_PATH ${PRIVATE_LOG_PATH} PRIVATE_LOG_PATH_NATIVE) - string(REPLACE "\\" "\\\\" PRIVATE_LOG_PATH_ESCAPED ${PRIVATE_LOG_PATH_NATIVE}) - target_compile_definitions(OSMPDummySensor PRIVATE - "PRIVATE_LOG_PATH=\"${PRIVATE_LOG_PATH_ESCAPED}\"") -endif() -target_compile_definitions(OSMPDummySensor PRIVATE - $<$:PUBLIC_LOGGING> - $<$:VERBOSE_FMI_LOGGING> - $<$:DEBUG_BREAKS>) +include_directories(${CMAKE_CURRENT_BINARY_DIR}) if(WIN32) if(CMAKE_SIZEOF_VOID_P EQUAL 8) @@ -67,5 +62,6 @@ add_custom_command(TARGET OSMPDummySensor COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_BINARY_DIR}/modelDescription.xml" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu" COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_SOURCE_DIR}/OSMPDummySensor.cpp" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/sources/" COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_SOURCE_DIR}/OSMPDummySensor.h" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/sources/" + COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_BINARY_DIR}/OSMPDummySensorConfig.h" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/sources/OSMPDummySensorConfig.h" COMMAND ${CMAKE_COMMAND} -E copy $ $<$:$<$:$>> "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/binaries/${FMI_BINARIES_PLATFORM}" COMMAND ${CMAKE_COMMAND} -E chdir "${CMAKE_CURRENT_BINARY_DIR}/buildfmu" ${CMAKE_COMMAND} -E tar "cfv" "../OSMPDummySensor.fmu" --format=zip "modelDescription.xml" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/sources" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/binaries/${FMI_BINARIES_PLATFORM}") diff --git a/examples/OSMPDummySensor/OSMPDummySensor.cpp b/examples/OSMPDummySensor/OSMPDummySensor.cpp index 50165fe..fe5f62b 100644 --- a/examples/OSMPDummySensor/OSMPDummySensor.cpp +++ b/examples/OSMPDummySensor/OSMPDummySensor.cpp @@ -114,10 +114,10 @@ bool COSMPDummySensor::get_fmi_sensor_view_config(osi3::SensorViewConfiguration& void COSMPDummySensor::set_fmi_sensor_view_config_request(const osi3::SensorViewConfiguration& data) { - data.SerializeToString(¤tConfigRequestBuffer); - encode_pointer_to_integer(currentConfigRequestBuffer.data(),integer_vars[FMI_INTEGER_SENSORVIEW_CONFIG_REQUEST_BASEHI_IDX],integer_vars[FMI_INTEGER_SENSORVIEW_CONFIG_REQUEST_BASELO_IDX]); - integer_vars[FMI_INTEGER_SENSORVIEW_CONFIG_REQUEST_SIZE_IDX]=(fmi2Integer)currentConfigRequestBuffer.length(); - normal_log("OSMP","Providing %08X %08X, writing from %p ...",integer_vars[FMI_INTEGER_SENSORVIEW_CONFIG_REQUEST_BASEHI_IDX],integer_vars[FMI_INTEGER_SENSORVIEW_CONFIG_REQUEST_BASELO_IDX],currentConfigRequestBuffer.data()); + data.SerializeToString(currentConfigRequestBuffer); + encode_pointer_to_integer(currentConfigRequestBuffer->data(),integer_vars[FMI_INTEGER_SENSORVIEW_CONFIG_REQUEST_BASEHI_IDX],integer_vars[FMI_INTEGER_SENSORVIEW_CONFIG_REQUEST_BASELO_IDX]); + integer_vars[FMI_INTEGER_SENSORVIEW_CONFIG_REQUEST_SIZE_IDX]=(fmi2Integer)currentConfigRequestBuffer->length(); + normal_log("OSMP","Providing %08X %08X, writing from %p ...",integer_vars[FMI_INTEGER_SENSORVIEW_CONFIG_REQUEST_BASEHI_IDX],integer_vars[FMI_INTEGER_SENSORVIEW_CONFIG_REQUEST_BASELO_IDX],currentConfigRequestBuffer->data()); swap(currentConfigRequestBuffer,lastConfigRequestBuffer); } @@ -142,10 +142,10 @@ bool COSMPDummySensor::get_fmi_sensor_view_in(osi3::SensorView& data) void COSMPDummySensor::set_fmi_sensor_data_out(const osi3::SensorData& data) { - data.SerializeToString(¤tOutputBuffer); - encode_pointer_to_integer(currentOutputBuffer.data(),integer_vars[FMI_INTEGER_SENSORDATA_OUT_BASEHI_IDX],integer_vars[FMI_INTEGER_SENSORDATA_OUT_BASELO_IDX]); - integer_vars[FMI_INTEGER_SENSORDATA_OUT_SIZE_IDX]=(fmi2Integer)currentOutputBuffer.length(); - normal_log("OSMP","Providing %08X %08X, writing from %p ...",integer_vars[FMI_INTEGER_SENSORDATA_OUT_BASEHI_IDX],integer_vars[FMI_INTEGER_SENSORDATA_OUT_BASELO_IDX],currentOutputBuffer.data()); + data.SerializeToString(currentOutputBuffer); + encode_pointer_to_integer(currentOutputBuffer->data(),integer_vars[FMI_INTEGER_SENSORDATA_OUT_BASEHI_IDX],integer_vars[FMI_INTEGER_SENSORDATA_OUT_BASELO_IDX]); + integer_vars[FMI_INTEGER_SENSORDATA_OUT_SIZE_IDX]=(fmi2Integer)currentOutputBuffer->length(); + normal_log("OSMP","Providing %08X %08X, writing from %p ...",integer_vars[FMI_INTEGER_SENSORDATA_OUT_BASEHI_IDX],integer_vars[FMI_INTEGER_SENSORDATA_OUT_BASELO_IDX],currentOutputBuffer->data()); swap(currentOutputBuffer,lastOutputBuffer); } @@ -255,7 +255,7 @@ void rotatePoint(double x, double y, double z,double yaw,double pitch,double rol rz = matrix[2][0] * x + matrix[2][1] * y + matrix[2][2] * z; } -fmi2Status COSMPDummySensor::doCalc(fmi2Real currentCommunicationPoint, fmi2Real communicationStepSize, fmi2Boolean noSetFMUStatePriorToCurrentPointfmi2Component) +fmi2Status COSMPDummySensor::doCalc(fmi2Real currentCommunicationPoint, fmi2Real communicationStepSize, fmi2Boolean noSetFMUStatePriorToCurrentPoint) { DEBUGBREAK(); @@ -373,6 +373,10 @@ COSMPDummySensor::COSMPDummySensor(fmi2String theinstanceName, fmi2Type thefmuTy loggingOn(!!theloggingOn), simulation_started(false) { + currentOutputBuffer=new string(); + lastOutputBuffer=new string(); + currentConfigRequestBuffer=new string(); + lastConfigRequestBuffer=new string(); loggingCategories.clear(); loggingCategories.insert("FMI"); loggingCategories.insert("OSMP"); @@ -381,10 +385,12 @@ COSMPDummySensor::COSMPDummySensor(fmi2String theinstanceName, fmi2Type thefmuTy COSMPDummySensor::~COSMPDummySensor() { - + delete currentOutputBuffer; + delete lastOutputBuffer; + delete currentConfigRequestBuffer; + delete lastConfigRequestBuffer; } - fmi2Status COSMPDummySensor::SetDebugLogging(fmi2Boolean theloggingOn, size_t nCategories, const fmi2String categories[]) { fmi_verbose_log("fmi2SetDebugLogging(%s)", theloggingOn ? "true" : "false"); @@ -392,11 +398,11 @@ fmi2Status COSMPDummySensor::SetDebugLogging(fmi2Boolean theloggingOn, size_t nC if (categories && (nCategories > 0)) { loggingCategories.clear(); for (size_t i=0;i @@ -24,79 +24,79 @@ - + - + - + - + - + - + - + - + - + - + - + - + - + diff --git a/examples/OSMPDummySource/CMakeLists.txt b/examples/OSMPDummySource/CMakeLists.txt index 503f02d..e7c2f48 100644 --- a/examples/OSMPDummySource/CMakeLists.txt +++ b/examples/OSMPDummySource/CMakeLists.txt @@ -11,33 +11,28 @@ if(WIN32) else() set(PRIVATE_LOG_PATH_SOURCE "/tmp/OSMPDummySourceLog.log" CACHE FILEPATH "Path to write private log file to") endif() +if(PRIVATE_LOGGING) + file(TO_NATIVE_PATH ${PRIVATE_LOG_PATH_SOURCE} PRIVATE_LOG_PATH_SOURCE_NATIVE) + string(REPLACE "\\" "\\\\" PRIVATE_LOG_PATH ${PRIVATE_LOG_PATH_SOURCE_NATIVE}) +endif() set(VERBOSE_FMI_LOGGING OFF CACHE BOOL "Enable detailed FMI function logging") set(DEBUG_BREAKS OFF CACHE BOOL "Enable debugger traps for debug builds of FMU") string(TIMESTAMP FMUTIMESTAMP UTC) string(MD5 FMUGUID modelDescription.in.xml) configure_file(modelDescription.in.xml modelDescription.xml @ONLY) +configure_file(OSMPDummySourceConfig.in.h OSMPDummySourceConfig.h) find_package(Protobuf 2.6.1 REQUIRED) add_library(OSMPDummySource SHARED OSMPDummySource.cpp) set_target_properties(OSMPDummySource PROPERTIES PREFIX "") target_compile_definitions(OSMPDummySource PRIVATE "FMU_SHARED_OBJECT") -target_compile_definitions(OSMPDummySource PRIVATE "FMU_GUID=\"${FMUGUID}\"") if(LINK_WITH_SHARED_OSI) target_link_libraries(OSMPDummySource open_simulation_interface) else() target_link_libraries(OSMPDummySource open_simulation_interface_pic) endif() -if(PRIVATE_LOGGING) - file(TO_NATIVE_PATH ${PRIVATE_LOG_PATH_SOURCE} PRIVATE_LOG_PATH_SOURCE_NATIVE) - string(REPLACE "\\" "\\\\" PRIVATE_LOG_PATH_SOURCE_ESCAPED ${PRIVATE_LOG_PATH_SOURCE_NATIVE}) - target_compile_definitions(OSMPDummySource PRIVATE - "PRIVATE_LOG_PATH=\"${PRIVATE_LOG_PATH_SOURCE_ESCAPED}\"") -endif() -target_compile_definitions(OSMPDummySource PRIVATE - $<$:PUBLIC_LOGGING> - $<$:VERBOSE_FMI_LOGGING> - $<$:DEBUG_BREAKS>) +include_directories(${CMAKE_CURRENT_BINARY_DIR}) if(WIN32) if(CMAKE_SIZEOF_VOID_P EQUAL 8) @@ -67,5 +62,6 @@ add_custom_command(TARGET OSMPDummySource COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_BINARY_DIR}/modelDescription.xml" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu" COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_SOURCE_DIR}/OSMPDummySource.cpp" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/sources/" COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_SOURCE_DIR}/OSMPDummySource.h" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/sources/" + COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_BINARY_DIR}/OSMPDummySourceConfig.h" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/sources/OSMPDummySourceConfig.h" COMMAND ${CMAKE_COMMAND} -E copy $ $<$:$<$:$>> "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/binaries/${FMI_BINARIES_PLATFORM}" COMMAND ${CMAKE_COMMAND} -E chdir "${CMAKE_CURRENT_BINARY_DIR}/buildfmu" ${CMAKE_COMMAND} -E tar "cfv" "../OSMPDummySource.fmu" --format=zip "modelDescription.xml" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/sources" "${CMAKE_CURRENT_BINARY_DIR}/buildfmu/binaries/${FMI_BINARIES_PLATFORM}") diff --git a/examples/OSMPDummySource/OSMPDummySource.cpp b/examples/OSMPDummySource/OSMPDummySource.cpp index 1860df6..b0e17e0 100644 --- a/examples/OSMPDummySource/OSMPDummySource.cpp +++ b/examples/OSMPDummySource/OSMPDummySource.cpp @@ -102,10 +102,10 @@ void encode_pointer_to_integer(const void* ptr,fmi2Integer& hi,fmi2Integer& lo) void COSMPDummySource::set_fmi_sensor_view_out(const osi3::SensorView& data) { - data.SerializeToString(¤tBuffer); - encode_pointer_to_integer(currentBuffer.data(),integer_vars[FMI_INTEGER_SENSORVIEW_OUT_BASEHI_IDX],integer_vars[FMI_INTEGER_SENSORVIEW_OUT_BASELO_IDX]); - integer_vars[FMI_INTEGER_SENSORVIEW_OUT_SIZE_IDX]=(fmi2Integer)currentBuffer.length(); - normal_log("OSMP","Providing %08X %08X, writing from %p ...",integer_vars[FMI_INTEGER_SENSORVIEW_OUT_BASEHI_IDX],integer_vars[FMI_INTEGER_SENSORVIEW_OUT_BASELO_IDX],currentBuffer.data()); + data.SerializeToString(currentBuffer); + encode_pointer_to_integer(currentBuffer->data(),integer_vars[FMI_INTEGER_SENSORVIEW_OUT_BASEHI_IDX],integer_vars[FMI_INTEGER_SENSORVIEW_OUT_BASELO_IDX]); + integer_vars[FMI_INTEGER_SENSORVIEW_OUT_SIZE_IDX]=(fmi2Integer)currentBuffer->length(); + normal_log("OSMP","Providing %08X %08X, writing from %p ...",integer_vars[FMI_INTEGER_SENSORVIEW_OUT_BASEHI_IDX],integer_vars[FMI_INTEGER_SENSORVIEW_OUT_BASELO_IDX],currentBuffer->data()); swap(currentBuffer,lastBuffer); } @@ -183,7 +183,7 @@ void rotatePoint(double x, double y, double z,double yaw,double pitch,double rol rz = matrix[2][0] * x + matrix[2][1] * y + matrix[2][2] * z; } -fmi2Status COSMPDummySource::doCalc(fmi2Real currentCommunicationPoint, fmi2Real communicationStepSize, fmi2Boolean noSetFMUStatePriorToCurrentPointfmi2Component) +fmi2Status COSMPDummySource::doCalc(fmi2Real currentCommunicationPoint, fmi2Real communicationStepSize, fmi2Boolean noSetFMUStatePriorToCurrentPoint) { DEBUGBREAK(); @@ -280,6 +280,8 @@ COSMPDummySource::COSMPDummySource(fmi2String theinstanceName, fmi2Type thefmuTy visible(!!thevisible), loggingOn(!!theloggingOn) { + currentBuffer = new string(); + lastBuffer = new string(); loggingCategories.clear(); loggingCategories.insert("FMI"); loggingCategories.insert("OSMP"); @@ -288,10 +290,10 @@ COSMPDummySource::COSMPDummySource(fmi2String theinstanceName, fmi2Type thefmuTy COSMPDummySource::~COSMPDummySource() { - + delete currentBuffer; + delete lastBuffer; } - fmi2Status COSMPDummySource::SetDebugLogging(fmi2Boolean theloggingOn, size_t nCategories, const fmi2String categories[]) { fmi_verbose_log("fmi2SetDebugLogging(%s)", theloggingOn ? "true" : "false"); @@ -299,11 +301,11 @@ fmi2Status COSMPDummySource::SetDebugLogging(fmi2Boolean theloggingOn, size_t nC if (categories && (nCategories > 0)) { loggingCategories.clear(); for (size_t i=0;i @@ -24,25 +24,25 @@ - + - + - + - + diff --git a/examples/open-simulation-interface b/examples/open-simulation-interface index 81e0db3..700133d 160000 --- a/examples/open-simulation-interface +++ b/examples/open-simulation-interface @@ -1 +1 @@ -Subproject commit 81e0db3001b9d84bf0aa1f76e47f55c99aea7ded +Subproject commit 700133d9fa2df6ba648958468a33af4dacb3f3f0 diff --git a/local_build_tools/asciidoctor.bat b/local_build_tools/asciidoctor.bat new file mode 100644 index 0000000..a5dd7d2 --- /dev/null +++ b/local_build_tools/asciidoctor.bat @@ -0,0 +1,3 @@ +@ECHO OFF +docker-compose up -d +PAUSE \ No newline at end of file diff --git a/local_build_tools/compose.yml b/local_build_tools/compose.yml new file mode 100644 index 0000000..a37849c --- /dev/null +++ b/local_build_tools/compose.yml @@ -0,0 +1,8 @@ +version: "2" + +services: + asciidoctor: + image: asciidoctor/docker-asciidoctor + volumes: + - ../:/documents + entrypoint: asciidoctor --failure-level WARN -r asciidoctor-kroki -a mathjax -r asciidoctor-bibtex --trace content/index.adoc -o local_build_tools/HTML_content_local_build.html \ No newline at end of file diff --git a/local_build_tools/windows_convert_symlinks(ADMIN).bat b/local_build_tools/windows_convert_symlinks(ADMIN).bat new file mode 100644 index 0000000..e75412f --- /dev/null +++ b/local_build_tools/windows_convert_symlinks(ADMIN).bat @@ -0,0 +1,13 @@ +@ECHO OFF +SET Targetpath=..\.antora\modules\sensor-model +SET Symlinkroot=..\..\.. + +@REM mklink /D %Targetpath%\images %Symlinkroot%\doc\images + +mklink /D %Targetpath%\pages %Symlinkroot%\doc + +@REM mklink /D %Targetpath%\partials %Symlinkroot%\_additional_content + +@REM mklink /D %Targetpath%\attachments %Symlinkroot%\_attachments + +PAUSE \ No newline at end of file diff --git a/osmp.xsd b/osmp.xsd index d2a42fb..fbf8961 100644 --- a/osmp.xsd +++ b/osmp.xsd @@ -5,7 +5,11 @@ vc:minVersion="1.0" vc:maxVersion="1.1"> - + + + + +