Disclaimer

This document is the copyrighted property of ASAM e.V. Any use is limited to the scope described in the license terms.

Foreword

The ASAM OSI® (Open Simulation Interface) is a specification for interfaces between models and components of a distributed simulation. OSI is strongly focused on the environmental perception of automated driving functions.

The complexity of automated driving functions is rapidly increasing, which means the requirements for testing and development methods are growing too. Testing in virtual environments makes it possible to control and reproduce environment conditions.

To enable the widespread use of driving simulators for developers of functions, generic and standardized interfaces are needed for the connection between the function-development framework and the simulation environment. OSI permits easy and straight-forward compatibility between automated driving functions and the variety of driving-simulation frameworks that are available. OSI addresses the emerging standard ISO 23150 [1] for a real sensors’ standardized communication interface. OSI defines generic interfaces to ensure the modularity, integrability, and interchangeability of the individual components.

The vision is to make it possible to connect any automated driving function to any driving simulator and emerging new hardware sensor generations using a standardized ISO 23150 [1] interface. This will simplify integration, significantly strengthening the accessibility and usefulness of virtual testing in the process.

1. Introduction

1.1. What has changed

Documentation Updates
  • Updated the documentation’s structure and migrated it to AsciiDoc.

  • Updated the description of OSI’s top level messages.

  • Updates on additional descriptions, like those for trace file formats, naming conventions and installation instructions for Linux/Windows.

Technical Updates
  • Extended SensorViewConfiguration message to allow the consumer to choose to not include static content in the SensorView ground truth information.

  • Updated StationaryObject classification enums to avoid "pylon" duplication.

  • Extended StationaryObject classification message to include speed bumps.

  • Extended StationaryObject to include emitting structures of electromagnetic waves (for example this can be used to define a streetlamp).

  • Extended the TrafficSign classification message, by adding attributes country, country_revision, code and sub_code, to better support internationalization and to align with ASAM OpenDRIVE.

  • Updated the color coding message description to better align with ASAM OpenDRIVE.

  • Update the color coding message description to include Grey, RGB, RGBIR, HSV, LUV and thus align with ISO-23150.

  • Added an enum for dashed lane boundaries to disambiguate start and end of those.

  • Extended HostVehcileData with more comprehensive on-board information, and promoted the message to a top-level message for exchange between simulation environments and (external) dynamic models.

  • Extended LidarDetection message under feature data to include echo pulse width information to better support several sensor outputs that are currently on the market.

  • Extended OSI to include a generic external reference message to enable traceability for data from other standards, including other ASAM OpenX standards.

  • Added support for using OSI with Flatbuffers encoding for OSI messages instead of ProtoBuffers, in preparation for a potential switch of default encoding in a future major release.

  • Extended LaneBoundary message to include additional types, to better align with ASAM OpenDRIVE.

1.2. Deliverables

The following deliverables are provided for ASAM OSI®:

  • User guide, that is, this document (partly normative)

  • .proto files (normative)

  • Doxygen reference documentation (not normative)

  • OSMP packaging (OSMP packaging has its own version number, but is compatible with the version of ASAM OSI®.)

Related topics

1.3. ASAM OSI® repositories

ASAM OSI® is an open-source standardization project. OSI and its supporting tools are developed publicly on GitHub.

The source code and documentation for OSI and OSI-related tools are spread over several repositories:

open-simulation-interface

Main repository containing the interface description based on Google’s Protocol Buffers, including helper scripts and test scripts. Hosts the .proto files as well as the Doxygen reference documentation.

osi-documentation

Source for the OSI user guide sources and hosts the ASAM OSI® user guide.

osi-sensor-model-packaging

Packaging specification for OSI models used in FMI 2.0 [2] simulation environments, including examples.

proto2cpp

Doxygen filter for creating the reference documentation from OSI .proto files.

1.4. Normative and non-normative statements

This specification uses a standard information structure. The following rules apply regarding normativity of the different sections:

  • Statements expressed as requirements, permissions, or prohibitions according to the use of modal verbs, as defined in Section 1.5.2, "Modal verbs", are normative.

  • Rules in "Rules" sections are normative.

  • .proto files are normative.

  • Examples, use case descriptions, and instructions are non-normative.

  • Doxygen reference documentation is non-normative.

1.5. Conventions

1.5.1. Units

Every field has its own unit that is defined in the proto files. For more information, see the example in the contribution guidelines.

1.5.2. Modal verbs

To ensure compliance with the ASAM OSI® standard, users need to be able to distinguish between mandatory requirements, recommendations, permissions, as well as possibilities and capabilities.

The following rules for using modal verbs apply:

Table 1. Rules for using modal verbs
Provision Verbal form

Requirements
Requirements shall be followed strictly in order to conform to the standard. Deviations are not allowed.

shall
shall not

Recommendations
Recommendations indicate that one possibility out of the several available is particularly suitable, without mentioning or excluding the other possibilities.

should
should not

Permissions
Permissions indicate a course of action permissible within the limits of ASAM OSI® deliverables.

may
need not

Possibilities and capabilities
Verbal forms used to state possibilities or capabilities, whether technical, material, physical, etc.

can
cannot

Obligations and necessities
Verbal forms used to describe legal, organizational, or technical obligations and necessities that are not regulated or enforced by the ASAM OSI® standard.

must
must not

1.5.3. Typographic conventions

This documentation uses the following typographical conventions:

Table 2. Typographical conventions
Mark-up Definition

Code elements

This format is used for code elements, such as technical names of classes and attributes, as well as attribute values.

Technical concepts

This format is used for technical concepts. Technical concepts as opposed to code elements do not have a special highlighting.

Code snippets

This format is used for excerpts of code that serve as an example for implementation.

Terms

This format is used to introduce glossary terms, new terms and to emphasize terms.

Mathematical elements

This format is used for calculations and mathematical elements.

<element>

This describes a tag for an XML element

@attribute

The "@" identifies an attribute of an XML element.

1.6. Versioning and compatibility

The version number is defined in InterfaceVersion::version_number in osi_version.proto as the field’s default value.

Major

A change in the major version makes the code and recorded proto messages incompatible.

Major changes include:

  • An existing field with a number changing its meaning. Example: optional double field = 1; changes to repeated double field = 1;.

  • Changing the definition of units or the interpretation of a field.

  • Deleting a field and reusing the field number.

  • Changing the technology from Protocol Buffers to FlatBuffers.

Minor

A change in the minor version indicates there is still compatibility with previously recorded files. However, the code needs fixing.

Minor changes include:

  • Renaming a field without changing the field number.

  • Changing the names of messages.

  • Adding a new field in a message without changing the numbering of other fields.

Patch

Both recorded files and code still have compatibility.

Patches include:

  • File or folder structure that does not affect integration of the code in other projects.

  • Changing or adding comments.

  • Clarifying text passages explaining the message content.

1.7. Relationships with other standards

1.7.1. Positioning of ASAM OSI® within ASAM activities

ASAM OSI® (Open Simulation Interface) is part of the ASAM simulation standards that focus on simulation data for the automotive environment. Next to ASAM OSI®, ASAM provides other standards for the simulation domain, like OpenDRIVE [3], OpenSCENARIO [4] and OpenCRG [5].

OpenDRIVE defines a storage format for the static description of road networks. In combination with OpenCRG it is possible to add very detailed road surface descriptions to the road network. OpenDRIVE and OpenCRG only contain static content. To add dynamic content, OpenSCENARIO is needed. Combining all three standards provides a scenario-driven description of traffic simulation that contains static and dynamic content.

1.7.2. References to other standards

2. Open Simulation Interface

2.1. Idea behind Open Simulation Interface

ASAM OSI® Open Simulation Interface is a specification for interfaces between models and components of a distributed simulation. OSI is strongly focused on the environmental perception of automated driving functions. However, OSI also specifies interfaces for modeling traffic participants.

2.2. The basic design of OSI

2.2.1. Overview of OSI architecture

OSI contains an object-based environment description that uses the message format of the Protocol Buffer library. Google developed and maintains the Protocol Buffer library. OSI defines top-level messages that are used to exchange data between separate models. Top-level messages define the GroundTruth interface, the SensorData interface, and – since OSI version 3.0.0 – the interfaces SensorView, SensorViewConfiguration, and FeatureData.

The following figure shows the interfaces and models involved in modeling a sensor.

1100
Figure 1. Open Simulation Interface overview

OSI also defines interfaces for traffic participant models. The TrafficCommand interface makes it possible to send commands to traffic participant models. The TrafficUpdate interface makes it possible to receive the updated state from traffic participant models. The following figure shows the interfaces of a generic traffic participant.

1100
Figure 2. Interface of a traffic participant

Traffic participant models may use other OSI interfaces internally, for example, to model autonomous vehicles. The following figure shows a more advanced use case for traffic participants.

1100
Figure 3. Traffic participant with sensor models, AD function, and dynamic model

The HostVehicleData interface describes the measured internal states of a traffic participant. OSI currently provides only limited support for data structures that describe measured internal states of traffic participants. One example would be the MotionRequest interface that can be used to communicate the results of the behavior planning to the dynamic model.

OSI uses singular instead of plural for repeated field names.
All fields in an interface are set to optional. required is not used.

This has been done to allow backward-compatible changes in the field. Additionally, this is the default behavior in Protocol Buffer version 3 that no longer has the required type. Setting all fields to optional thus ensures update compatibility. However, this does not mean that it is optional to fill the field. For the purpose of providing a complete interface, all existing fields should be set, unless not setting a field carries a specific meaning, as indicated in the accompanying comment.

All field numbers equal to or greater than 10000 are available for user-specific extensions via custom fields. No future evolution of OSI will therefore use field numbers equal to or greater than 10000.

2.2.2. Top-level interfaces

2.2.2.1. Ground truth

GroundTruth messages describe the simulated environment containing all simulated objects in the global coordinate system at consecutive time instances. They are based on data available to the simulation environment. GroundTruth messages are typically contained in Sensorview messages.

2.2.2.2. Feature data

FeatureData messages contain detected features in the reference frame of a sensor. FeatureData messages are generated from GroundTruth messages. They serve, for example, as an input to sensor models simulating object detection or feature fusion models.

2.2.2.3. Sensor view

The sensor view provides the input to OSI sensor models. SensorView messages are derived from GroundTruth messages. All information regarding the environment is given with respect to the virtual sensor coordinate system, with two exceptions:

  • Physical technology-specific data, given with respect to the physical sensor coordinate system specified in the corresponding physical sensor’s mounting position. One example of technology-specific data is: image_data of osi3::CameraSensorView

  • Ground truth given in the global coordinate system.

2.2.2.4. Sensor-view configuration

The sensor view is flexibly defined to provide different kinds of sensor models with an appropriate input. The sensor-view configuration defines the configuration of a particular sensor view.

The SensorViewConfiguration message is used in the initialization phase of a simulation to negotiate the sensor-view configuration for a particular SensorView input. It is also included as a sub-message in SensorView messages to indicate that the sensor-view configuration is valid for a particular SensorView message.

SensorViewConfiguration data has two main applications:

  • Enable the environment simulation to provide the necessary input to a sensor model.

  • Enable a sensor model to check whether the input matches its requirements. If the input does not match the requirements, the sensor model may terminate the simulation.

SensorViewConfiguration data is intended for the automatic configuration of the SensorView interface between an environment simulation and sensor model. The data is not intended to be a mechanism for parametrizing a generic sensor model.

During the initialization phase, there are two sources for SensorViewConfiguration data:

  1. SensorViewConfiguration data may be provided by the sensor model to the environment simulation. In this case, the data describes the input configuration that is requested by the sensor model. If the sensor model does not provide such data, then the environment simulation will fall back to manual configuration of the sensor view.

  2. SensorViewConfiguration data may be provided by the environment simulation. In response to the request by the sensor model, or based on manual configuration, the environment simulation configures the input and provides a new message that describes the actual configuration.

The configuration requested by the sensor model may differ from the configuration provided by the environment simulation. This happens when the environment simulation does not support a requested configuration or when the requested configuration is ambiguous.

In response to this difference, the sensor model can either accept this difference and adapt to it, or it can terminate the simulation to indicate that it is not able to accept the difference.

The packaging layer defines the specifics of this auto-negotiation mechanism.

After the initialization phase, the environment simulation provides the actual sensor-view configuration as part of each SensorView message.

2.2.2.5. Sensor data

SensorData messages imitate the output of real sensors. They can be generated from GroundTruth messages, SensorView messages, FeatureData messages, or SensorData messages. With the exception of feature data, all information regarding the environment is given with respect to the virtual sensor coordinate system. Feature data is given with respect to the physical sensor coordinate system. Sensor data can be used as input for an automated driving function, a sensor model simulating limited perception, or a sensor fusion model.

2.2.2.6. Traffic command

TrafficCommand messages contain control commands from the scenario engine to traffic participant models.

2.2.2.7. Motion Request

MotionRequest messages are traffic participant internal messages. They function as a interface between a motion/behavior planning model and a dynamics model including, for example, controllers and vehicle kinematics.

2.2.2.8. Traffic update

TrafficUpdate messages are provided by traffic participants. They provide updates on the position, state, and future trajectory of a traffic participant back to the simulation environment.

2.2.3. Model types

2.2.3.1. Environmental effect model

Environmental effect models consume SensorView messages and produce SensorView messages. Environmental effect models may, for example, alter SensorView messages to include effects and phenomena caused by:

  • Shadows and occlusions

  • Weather effects

  • Physics of a sensor

  • Pre-processing of raw sensor data

2.2.3.2. Sensor model

Sensor models consume SensorView messages and produce SensorData messages. Sensor-model output does not represent raw data but detected features or classified objects.

2.2.3.3. Logical model

Logical models consume SensorData messages and produce SensorData messages.

An example of a logical model is a sensor-fusion model, which combines the output of multiple sensor models to produce data with less uncertainty. Another use case is the fault-injection model which, contrary to a sensor-fusion model, may be used to increase uncertainties.

2.2.3.4. Traffic participant

A traffic participant is an element of the simulated world and can change its state during simulation time, for example, its position and orientation. A traffic participant represents one of the following:

  • Living being

  • Means of transportation for living beings

  • Means of transportation for goods

  • Any other movable object that may travel on the road network

Pedestrians and animals are examples of traffic participants that are living beings. Vehicles are examples of traffic participants that are a means of transportation. The ego vehicle is therefore also a traffic participant.

The following figure shows the interface of a traffic participant.

1100
Figure 4. Interface of a traffic participant

Traffic participant models may use other OSI interfaces, for example, the SensorData and MotionRequest message, internally. The following figure shows a more advanced use case for traffic participants, that can, for example, be used to model an autonomous vehicle.

1100
Figure 5. Traffic participant using other OSI interfaces internally

With every simulation step, an OSI traffic participant model receives ground-truth data from the environment around itself, the sensor view. A traffic participant can output its own perceivable state, the traffic update. Traffic commands influence the behavior of the traffic participant model. They allow event-based communication towards the traffic participant, that is, at certain simulation steps. Traffic commands do not necessarily need to come from the environment simulation. They may come from a separate source, such as a scenario engine.

Modeling a traffic participant

Different models may be involved in modeling a traffic participant. In all the use cases, a simulator loads and interprets a scenario and a map prior to execution. The scenario is, for example, provided by OpenSCENARIO. The map data is, for example, provided by OpenDRIVE. During runtime the simulator interacts with the traffic participants via OSI messages. There may be multiple instances of a traffic participant. The traffic participants are co-simulated.

The following figure shows a very simple use case.

1100
Figure 6. Simple traffic participant

The traffic participant bases its behavior only on an idealized view of the area around it. The traffic participant’s dynamics are included in the model if they exist.

The following figure shows a traffic participant with separately modeled behavior and dynamics.

1100
Figure 7. Traffic participants with separate dynamics

OSI currently provides only limited support for data structures that describe measured internal states of the traffic participant. An example for a traffic participant internal interface is the MotionRequest message that can be used to communicate planned behaviors from a behavior planning model to a dynamics model including, for example motion controllers and vehicle dynamics.

The following figure shows a more complex traffic participant.

1100
Figure 8. Traffic participant with sensor models, AD function, and dynamics model

This use case will probably be relevant for modeling the ego vehicle, which includes the system under test. The traffic participant includes an arbitrary number of sensor models. The sensor models consume sensor view and produce sensor data. The AD function consumes sensor data and produces input for the dynamics model. The loop to the environment simulation is closed via traffic update.

The following figure shows a cooperative use case with both an AD function and a human driver.

1100
Figure 9. Traffic participant with an AD function and human driver

It is possible to model a traffic participant with an AD function in the loop, but a human driver can still override the actuation command. This type of cooperative use case is, for example, relevant to studies on human-machine interaction. In this example, a virtual on-screen representation of the scenario, or mock-up, is added after the AD function. The driver-in-the-loop interacts with the dynamics model via this mock-up. OSI currently provides only limited interfaces for data flow between the driver and the dynamics model.

2.2.4. Coordinate systems and reference points

2.2.4.1. Coordinate systems, reference points and coordinate transformation

OSI uses DIN ISO 8855:2013-11 [6] for coordinate systems and transformations between coordinate systems. OSI uses the following coordinate systems:

Global coordinate system

Coordinate system for all entities that are part of ground truth. The global coordinate system is an inertial x/y/z-coordinate system. The origin is the global reference point that is determined by the environment simulation. This reference point may be derived from map data or other considerations. Global coordinates can be mapped to a geographic coordinate system via osi3::GroundTruth::proj_string.

Host vehicle coordinate system

The host vehicle coordinate system’s origin is defined to be at the center of the rear axle of the host vehicle.

Sensor coordinate system

Coordinate system for all entities that are part of sensor data. The origin is the mounting position of the physical sensor or a virtual mounting position, depending on the OSI message. Both physical and virtual sensor coordinate systems are relative to the host vehicle coordinate system.

Object coordinate system

Local object coordinate system. The origin of the corresponding coordinate system is not necessarily identical to the center of the object’s bounding box. If the origin of the corresponding coordinate system is not identical to the center of the object’s bounding box, the object documentation will provide the actual definition.

2.2.4.2. Coordinate transformations
Vehicle and sensor coordinate systems

When running simulations, it is frequently necessary to transform coordinates from the global coordinate system for a specific vehicle and its sensors.

This section provides an overview of the messages and fields involved and their relationship for this task. It demonstrates how a global coordinate system, vehicle coordinate system, and sensor coordinate system are related on the basis of a specific (ego) vehicle.

Mathematical Definitions of Coordinate Transformations

All vectors and matrices are noted with reference frame as a superscript index and the direction of translation as a subscript index. [7] The translation direction is from the first index to the second index (src: source coordinate system, trg: target coordinate system). The vector \(\boldsymbol{v}^x\) denotes the 3D position of an object in the coordinate frame \(x\). Vector \(\boldsymbol{t}\) is the translation vector between two coordinate systems with the described indices for reference frame and direction. The angles yaw \(\psi\) around the z-axis, pitch \(\theta\) around the y-axis and roll \(\phi\) around the x-axis are defined in a right handed coordinate system according to DIN ISO 8855:2013 [6]. The sign of the angles corresponds to the direction of the transformation.

Transformation from source \(src\) to target \(trg\) coordinates:

\[\boldsymbol{v}^{trg} = \boldsymbol{R}_{src}^{trg} (\boldsymbol{v}^{src} - \boldsymbol{t}_{src,trg}^{src})\]

Transformation back from target \(trg\) to source \(src\) coordinates

\[\boldsymbol{v}^{src} = (\boldsymbol{R}_{src}^{trg})^{-1} \boldsymbol{v}^{trg} + \boldsymbol{t}_{src,trg}^{src}\]

With the rotation matrix (from rotating the coordinate system) [8]:

\[\boldsymbol{R}_{src}^{trg}=\boldsymbol{R}_{yaw,pitch,roll} = \boldsymbol{R}_{z,y,x} = \boldsymbol{R}_{x}(\phi) \boldsymbol{R}_{y}(\theta) \boldsymbol{R}_{z}(\psi) \\ \boldsymbol{R}_{z,y,x} = \begin{pmatrix} 1 & 0 & 0\\ 0 & \cos(\phi) & \sin(\phi)\\ 0 & -\sin(\phi) & \cos(\phi) \end{pmatrix} \begin{pmatrix} \cos(\theta) & 0 & -\sin(\theta)\\ 0 & 1 & 0\\ \sin(\theta) & 0 & \cos(\theta) \end{pmatrix} \begin{pmatrix} \cos(\psi) & \sin(\psi) & 0\\ -\sin(\psi) & \cos(\psi) & 0\\ 0 & 0 &1 \end{pmatrix} \\ \boldsymbol{R}_{z,y,x} = \begin{pmatrix} \cos(\theta)\cos(\psi) & \cos(\theta)\sin(\psi) & -\sin(\theta)\\ \sin(\phi)\sin(\theta)\cos(\psi)-\cos(\phi)\sin(\psi) & \sin(\phi)\sin(\theta)\sin(\psi)+\cos(\phi)\cos(\psi) & \sin(\phi)\cos(\theta)\\ \cos(\phi)\sin(\theta)\cos(\psi)+\sin(\phi)\sin(\psi) & \cos(\phi)\sin(\theta)\sin(\psi)-\sin(\phi)\cos(\psi) & \cos(\phi)\cos(\theta) \end{pmatrix}\]

Get Tait–Bryan angles from rotation matrix [9]:

\[\theta = -\arcsin(R_{13}) \\ \psi = \arctan2(R_{12}/\cos(\theta),R_{11}/\cos(\theta)) \\ \phi = \arctan2(R_{23}/\cos(\theta),R_{33}/\cos(\theta))\]

Relative orientation:

Object rotation Matrix: \(\boldsymbol{R}_{object}^{src}\)
Host vehicle rotation Matrix: \(\boldsymbol{R}_{ego}^{src}\)
Resulting rotation matrix between object and host: \(\boldsymbol{R}_{object}^{src}(\boldsymbol{R}_{ego}^{src})^{T}\)

To transform from world coordinates into host vehicle coordinates and back use the formulas from above with the world coordinates frame \(w\) as source system \(src\) and host vehicle coordinates frame \(v\) as target system \(trg\). To transform from host vehicle coordinates into sensor coordinates and back use the formulas from above with the host vehicle coordinates frame \(v\) as source system \(src\) and sensor coordinates frame \(s\) as target system \(trg\).

Corresponding messages

GroundTruth::moving_object::base::position

This field defines the position of the vehicle’s reference point in global coordinates. In Open Simulation Interface, an object’s position is defined by the coordinates of the center of the object’s 3D bounding box.

GroundTruth::moving_object::base::orientation

This field defines the orientation of the vehicle’s reference point in global coordinates.

GroundTruth::moving_object::vehicle_attributes::bbcenter_to_rear

This field specifies the vector pointing from the vehicle’s reference point to the middle of the rear axle under neutral load conditions.

SensorData::mounting_position

This field defines the sensor’s virtual mounting position and orientation and thereby the origin of the virtual sensor coordinate system. The mounting position is given in the host vehicle coordinate system.

Example

The following image shows the relationship between the coordinate systems. The reference point of the vehicle is given by a vector in the global coordinate system. A vector pointing from the reference position of the vehicle to the center of the rear axle then yields the origin of the host vehicle coordinate system. The mounting positions of the sensors and therefore the origins of the corresponding sensor coordinate systems are given with respect to the host vehicle coordinate system.

Static
Figure 10. Schematic example of OSI coordinate systems and their relationship

2.2.5. Layering

2.2.5.1. Data layer

The OSI data layer is defined in the message specifications using the ProtoBuf IDL [10]. This defines the data that can be transmitted using OSI, including the structure and the semantics of the data.

Additionally, it specifies the encoding to be used when OSI data is transmitted. Currently, ProtoBuf encoding is used, but other encodings are possible with the ProtoBuf IDL. FlatBuffer encoding has been implemented as an experimental feature.

The data layer does not directly define components and transmission routes. These are defined in the OSI packaging layer. There may be different packaging layer implementations using the shared data layer definitions. The data that is exchanged remains compatible regardless of the packaging layer implementation. The use of a shared data layer ensures easy bridging between different packaging layer implementations.

2.2.5.2. Packaging layer

The OSI packaging layer specifies how components that use the OSI data layer, for example, sensor models, are packaged for exchange.

This specifies model types and their mandatory and optional OSI inputs, OSI outputs, and parameter interfaces. A model type may be, for example, a sensor model or a traffic participant model. The packaging layer also specifies component technology standards. This makes it possible to encapsulate model types in easily exchangeable component packages that can be used across platforms and implementations.

Multiple packaging layer implementations are possible within the OSI framework. The shared data layer ensures easy bridging between the different implementations. The currently defined central packaging layer is the OSI Sensor Model Packaging (OSMP) specification. It is based on FMI 2.0 [2] and uses certain additional conventions to allow packaging of OSI using models as FMUs.

2.2.6. OSI trace files

2.2.6.1. OSI trace file formats

There are multiple formats for storing multiple serialized OSI messages in one trace file.

*.osi

Binary trace file. Messages are separated by a length specification before each message. The length is represented by a four-byte, little-endian, unsigned integer. The length does not include the integer itself.

*.txt

Plain-text trace file. Messages are separated by __.

*.txth

Human-readable plain-text trace file. Messages are separated by newlines. These files may be used for manual checks.

2.2.6.2. OSI trace file naming conventions

Name format

The names of OSI trace files should have the following format:

<timestamp>_<type>_<osi-version>_<protobuf-version>_<number-of-frames>_<custom-trace-name>.osi

Types

sd

Trace file contains SensorData messages.

sv

Trace file contains SensorView messages.

gt

Trace file contains GroundTruth messages.

tu

Trace file contains TrafficUpdate messages.

tc

Trace file contains TrafficCommand messages.

Example

Given an OSI trace file with the following information:

Table 3. Example OSI trace file information

Timestamp (ISO 8601) [11]

20210818T150542Z

Type

SensorView

OSI version

3.1.2

Protobuf version

3.0.0

Number of frames

1523

Custom trace name

highway

The recommended file name is:

20210818T150542Z_sv_312_300_1523_highway.osi
2.2.6.3. OSI trace file example
# generate_osi_messages.py
from osi3.osi_sensorview_pb2 import SensorView
import struct

NANO_INCREMENT = 10000000
MOVING_OBJECT_LENGTH = 5
MOVING_OBJECT_WIDTH = 2
MOVING_OBJECT_HEIGHT = 1

def main():
    """Initialize SensorView"""
    f = open("sv_330_361_1000_movingobject.osi", "ab")
    sensorview = SensorView()

    sv_ground_truth = sensorview.global_ground_truth
    sv_ground_truth.version.version_major = 3
    sv_ground_truth.version.version_minor = 5
    sv_ground_truth.version.version_patch = 0

    sv_ground_truth.timestamp.seconds = 0
    sv_ground_truth.timestamp.nanos = 0

    moving_object = sv_ground_truth.moving_object.add()
    moving_object.id.value = 42

    # Generate 1000 OSI messages for a duration of 10 seconds
    for i in range(1000):

        # Increment the time
        if sv_ground_truth.timestamp.nanos > 1000000000:
            sv_ground_truth.timestamp.seconds += 1
            sv_ground_truth.timestamp.nanos = 0
        sv_ground_truth.timestamp.nanos += NANO_INCREMENT

        moving_object.vehicle_classification.type = 2

        moving_object.base.dimension.length = MOVING_OBJECT_LENGTH
        moving_object.base.dimension.width = MOVING_OBJECT_WIDTH
        moving_object.base.dimension.height = MOVING_OBJECT_HEIGHT

        moving_object.base.position.x += 0.5
        moving_object.base.position.y = 0.0
        moving_object.base.position.z = 0.0

        moving_object.base.orientation.roll = 0.0
        moving_object.base.orientation.pitch = 0.0
        moving_object.base.orientation.yaw = 0.0

        """Serialize"""
        bytes_buffer = sensorview.SerializeToString()
        f.write(struct.pack("<L", len(bytes_buffer)))
        f.write(bytes_buffer)

    f.close()

if __name__ == "__main__":
    main()

To run the script execute the following command in the terminal:

python3 generate_osi_messages.py

This will output an osi file (sv_330_361_1000_movingobject.osi) which can be visualized and played back by the osi-visualizer.

See Google’s documentation for more tutorials on how to use protocol buffers with Python or C++.

2.2.6.4. Trace-file formatting scripts

The OSI repository contains Python scripts for converting trace files from one format to another. The formatting scripts are stored in open-simulation-interface/format/

txt2osi.py

txt2osi.py converts plain-text trace files to binary .osi trace files. This script takes the following parameters:

--data, -d

String containing the path to the file with serialized data.

--type, -t

Optional string describing the message type used to serialize data. 'SensorView', 'GroundTruth', or 'SensorData' are permitted values. The default value is 'SensorView'.

--output, -o

Optional string containing the name of the output file. The default value is 'converted.osi'.

--compress, -c

Optional Boolean controlling whether to compress the output to an lzma file. True, or False are permitted values. The default value is False.

osi2read.py

osi2read.py converts trace files to human-readable .txth trace files. This script takes the following parameters:

--data, -d

String containing the path to the file with serialized data.

--type, -t

Optional string describing the message type used to serialize data. 'SensorView', 'GroundTruth', or 'SensorData' are permitted values. The default value is 'SensorView'.

--output, -o

Optional string containing the name of the output file. The default value is 'converted.txth'.

--format, -f

Optional string containing the format type of the trace file. 'separated', or None are permitted values. The default value is None.

Related topics

2.3. Setting up OSI

2.3.1. Installing protobuf for static / dynamic linking

2.3.1.1. Prerequisites
  • You have installed cmake (version 3.10.2 or higher)

  • You must have superuser privileges

Static linking is the recommended way to package OSI FMUs for sharing with others to be integrated in a co-simulation: They should have minimal external dependencies in order to ensure maximum portability. For other use cases like first trials to get started with OSI, dynamic linking could be an option as well.

2.3.1.2. Windows
Dynamic Linking (NOT RECOMMENDED)

Since on Windows symbols are not exported per default, it can be kind of annoying to deal with this during protobuf header generation (see for example https://groups.google.com/g/protobuf/c/PDR1bqRazts). That is an important reason to use static linking.

Static Linking

Static linking might require to manually build protobuf. It is important to notice that on Windows you can also specify how to link against the C runtime. Basically, this can be set in CMake, e.g. https://cmake.org/cmake/help/latest/prop_tgt/MSVC_RUNTIME_LIBRARY.html

Therefore, it could make sense to still dynamically link against the C Runtime when statically linking protobuf / OSI. (This is important e.g. when building shared libraries, since a static C runtime will create an isolated heap for your dll, which can lead to segfaults depending on what you expose on your public interfaces.)

The easiest way to achieve static linking on Windows without setting all the stuff manually in Cmake and building protobuf is to actually install static protobuf with dynamic c-runtime with vcpkg:

vcpkg install --triplet=x64-windows-static-md protobuf
Build

For the cmake configuration, we can directly specify our vcpkg installation:

cmake .. -DVCPKG_TARGET_TRIPLET=x64-windows-static-md -DCMAKE_TOOLCHAIN_FILE=C:/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake -A x64
cmake --build . --config Release
2.3.1.3. Linux
Dynamic linking (NOT RECOMMENDED)

As already mentioned, shared linking is possible on Linux, but NOT RECOMMENDED. However, for dynamic linking install protobuf (version 3.0.0 or higher) with apt:

sudo apt-get install libprotobuf-dev protobuf-compiler

In the CMakeLists of the OSI project, LINK_WITH_SHARED_OSI has to be enabled.

Static linking

A common error here is to just install protobuf with apt and link against it. This means that your OSI is build statically but still linking dynamically against protobuf. Here, again either protobuf has to build statically from source or some solution e.g. vcpkg needs to be utilized. We recommend the following (as in the README of the OSI project):

Install protobuf (version 3.0.0 or higher) from source with CXXFLAGS="-fPIC" to allow static linking of your OSI FMUs (replace <version> with preferred release):

wget https://github.com/protocolbuffers/protobuf/releases/download/<version>/protobuf-all-<version>.tar.gz
tar -xzf protobuf-all-<version>.tar.gz
cd protobuf-<version>/
./configure --disable-shared CXXFLAGS="-fPIC"
make
sudo make install
sudo ldconfig

2.3.2. Installing OSI for C++ on Linux

Prerequisites
Steps
  1. Open a terminal.

  2. Clone the Open Simulation repository.

    git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
  3. Switch to the repository directory.

    cd open-simulation-interface
  4. Create a new directory for the build.

    mkdir build
  5. Switch to the new directory.

    cd build
  6. Run cmake. To build a 32-bit target under 64-bit Linux, add -DCMAKE_CXX_FLAGS="-m32" to the cmake command. In this case, protobuf must be in 32-bit mode too.

    cmake ..
  7. Run make.

    make
  8. Install Open Simulation Interface.

    sudo make install

2.3.3. Installing OSI for Python on Linux

*Prerequisites
  • You have installed everything described in Section 2.3.1.

  • You have installed pip3.

  • You have installed python-setuptools.

  • For a local installation, you have installed virtualenv.

Steps
  1. Open a terminal.

  2. Clone the Open Simulation repository.

    git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
  3. Switch to the repository directory.

    cd open-simulation-interface
  4. Create a new virtual environment.

    virtualenv -p python3 venv
  5. Activate the virtual environment.

    source venv/bin/activate
  6. Install Open Simulation Interface.

    1. Local installation

      python3 -m pip install .
    2. Global installation

      sudo pip3 install .

2.3.4. Installing OSI for C++ on Windows

Prerequisites
Steps
  1. Open a terminal as administrator.

  2. Clone the Open Simulation repository.

    git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
  3. Switch to the repository directory.

    cd open-simulation-interface
  4. Create a new directory for the build.

    mkdir build
  5. Switch to the new directory.

    cd build
  6. Run cmake. To build a 64-bit target, add Win64 to the generator name. In this case, protobuf and protoc.exe must be in 64-bit mode too.

    cmake .. [-G <generator>] [-DCMAKE_INSTALL_PREFIX=<osi-install-directory>]
  7. Build and install OSI.

    cmake --build . [--config Release]
    cmake --build . --target install

2.3.5. Installing OSI for Python on Windows

Prerequisites
  • You have installed everything described in Section 2.3.1.

  • You have installed Python with administrator rights.

  • Make sure Python is added to PATH.

Steps
  1. Open a terminal.

  2. Clone the Open Simulation repository.

    git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
  3. Switch to the repository directory.

    cd open-simulation-interface
  4. Run the setup script.

    python setup.py install

3. OSI Sensor Model Packaging

3.1. 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 Semantic Versioning Specification 2.0.0.

3.2. OSMP specification

3.2.1. 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.

3.2.2. Basic conventions

The model shall be packaged as a valid FMU for co-simulation, as specified in the FMI 2.0 standard [2]. Unless otherwise noted, all specifications in the FMI 2.0 [2] standard apply as-is.

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:

<Tool name="net.pmsf.osmp" xmlns:osmp="http://xsd.pmsf.net/OSISensorModelPackaging"><osmp:osmp version="1.3.0" osi-version="x.y.z"/></Tool>

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.

3.2.3. Binary variables

FMI 2.0 [2] 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 [2]. Future FMI versions will directly support binary variables compatible with this concept.

A notional binary variable named <prefix> is defined using the following conventions:

The name of the notional binary variable given by <prefix> shall be a valid structured name according to FMI 2.0 [2].

The FMU shall not contain any other variable that is named <prefix>. 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:

<prefix>.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.

<prefix>.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.

<prefix>.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 <Annotations> child element of their <ScalarVariable> element of the modelDescription.xml:

<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>

<prefix> 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:

application/x-open-simulation-interface; type=<type>; version=x.y.z

<type> 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 <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.

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.

3.2.4. Sensor view inputs

Prefix

Sensor view inputs shall be named with the following prefix:

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.

3.2.5. 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:

OSMPSensorViewInConfig

Sensor view input configuration requests shall be named with the following prefix:

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.

3.2.6. Sensor view outputs

Prefix

Sensor view outputs shall be named with the following prefix:

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.

3.2.7. Sensor data inputs

Prefix

Sensor data inputs shall be named with the following prefix:

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.

3.2.8. Sensor data outputs

Prefix

Sensor data outputs shall be named with the following prefix:

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.

3.2.9. 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:

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.

3.2.10. 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:

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.

3.2.11. 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:

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.

3.2.12. Traffic update outputs

Traffic update outputs are present in traffic participant models.

Prefix

Traffic update outputs shall be named with the following prefix:

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.

3.3. Examples

3.3.1. 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 all prerequisites according to the way of linking of your choice, as described in Section 2.3.

Steps

  1. Clone the OSMP repository.

    git clone https://github.com/OpenSimulationInterface/osi-sensor-model-packaging.git
  2. Switch to the OSMP repository.

    cd osi-sensor-model-packaging
  3. Update and initialize the OSI submodule.

    git submodule update --init
  4. Switch to the examples/ directory.

    cd examples
  5. Create a new directory called build/.

    mkdir -p build
  6. Switch to the build/ directory.

    cd build
  7. Run cmake in the parent directory.

    cmake ..
  8. Run cmake build.

    cmake --build .

3.3.2. 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:

<?xml version="1.0" encoding="UTF-8"?>
<fmiModelDescription
  fmiVersion="2.0"
  modelName="OSI Sensor Model Packaging Demo FMU"
  guid="aabc2174e20f08597cfae6947c96bf86"
  variableNamingConvention="structured">
  <CoSimulation
    modelIdentifier="OSMPDemoFMU"
    canNotUseMemoryManagementFunctions="true"/>
  <DefaultExperiment startTime="0.0" stepSize="0.020"/>
  <VendorAnnotations>
    <Tool name="net.pmsf.osmp" xmlns:osmp="http://xsd.pmsf.net/OSISensorModelPackaging"><osmp:osmp version="1.3.0" osi-version="3.5.0"/></Tool>
  </VendorAnnotations>
  <ModelVariables>
    <ScalarVariable name="OSMPSensorViewIn.base.lo" valueReference="0" causality="input" variability="discrete">
      <Integer start="0"/>
      <Annotations>
        <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.5.0"/></Tool>
      </Annotations>
    </ScalarVariable>
    <ScalarVariable name="OSMPSensorViewIn.base.hi" valueReference="1" causality="input" variability="discrete">
      <Integer start="0"/>
      <Annotations>
        <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.5.0"/></Tool>
      </Annotations>
    </ScalarVariable>
    <ScalarVariable name="OSMPSensorViewIn.size" valueReference="2" causality="input" variability="discrete">
      <Integer start="0"/>
      <Annotations>
        <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.5.0"/></Tool>
      </Annotations>
    </ScalarVariable>
    <ScalarVariable name="OSMPSensorDataOut.base.lo" valueReference="3" causality="output" variability="discrete" initial="exact">
      <Integer start="0"/>
      <Annotations>
        <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.5.0"/></Tool>
      </Annotations>
    </ScalarVariable>
    <ScalarVariable name="OSMPSensorDataOut.base.hi" valueReference="4" causality="output" variability="discrete" initial="exact">
      <Integer start="0"/>
      <Annotations>
        <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.5.0"/></Tool>
      </Annotations>
    </ScalarVariable>
    <ScalarVariable name="OSMPSensorDataOut.size" valueReference="5" causality="output" variability="discrete" initial="exact">
      <Integer start="0"/>
      <Annotations>
        <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.5.0"/></Tool>
      </Annotations>
    </ScalarVariable>
  </ModelVariables>
  <ModelStructure>
    <Outputs>
      <Unknown index="4"/>
      <Unknown index="5"/>
      <Unknown index="6"/>
    </Outputs>
  </ModelStructure>
</fmiModelDescription>

4. Contributing to ASAM OSI

4.1. Getting started with contributing

Before you start, familiarize yourself with ASAM OSI® and how to contribute by reading this documentation and the reference documentation of ASAM OSI®.

You should also familiarize yourself with the following topics:

  • Google’s Protocol Buffers

  • Git

  • GitHub

4.2. Reporting issues

Reporting issues is a simple way of contributing to OSI.

Prerequisites

  • You have a GitHub account.

Steps

  1. Identify the repository that your issue relates to and open the repository on GitHub.

  2. Create a new issue.

  3. Select the correct issue type:

    Bug report

    Report an error.

    Feature request

    Suggest an idea for the project.

    Question

    Ask a question if you do not understand something or need clarification.

    Blank issue

    Use this issue type if no other type fits your issue.

  4. Fill out the title and description field. Follow the instructions in the template.

  5. Add suitable labels.

  6. When you are done editing the fields and labels, click Submit new issue.

Related topics

4.3. Contributing changes

4.3.1. License

OSI uses the Mozilla Public License, v. 2.0. All contributions are released under this license.

Before contributing to OSI repositories, read the LICENSE file in the corresponding repository.

4.3.2. Developer Certificate of Origin (DCO)

To make a good-faith effort to ensure licensing criteria are met, the Developer-Certificate-of-Origin (DCO) process shall be followed.

When contributing a change, the contributor must agree to the DCO. The DCO is a commitment that the contributor has the right to submit the change.

The text of the DCO is shown below or can be accessed at https://developercertificate.org/.

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

Contributors agree to the DCO by adding a Signed-off-by statement to the commit message.

4.3.3. Signing off commits

Contributing to OSI projects, it is necessary to agree to the Developer Certificate of Origin (DCO). Contributors agree to the DCO by adding a Signed-off-by statement to the commit message.

Signed-off-by: Firstname Lastname <email@address.com>

If a commit does not include the Signed-off-by statement, this commit cannot be merged into the master branch.

To add a sign-off statement to a commit add -s or --signoff to the commit command:

git commit -m "Commit message" -s

Related topics

4.3.4. Guidelines for writing commit messages

Apart from a sign-off message, ASAM OSI® requires commit messages to follow a specific format. This format enables other people to understand the motivation behind your commits more easily. OSI enforces these requirements only for commits to protected branches. However, you should always follow these guidelines to help other people understand your commits.

Commit messages shall have the following structure:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commits can have one of the following types:

fix

Change fixes an error. These changes usually correspond to a PATCH release.

feat

Change introduces a new feature. If the change is backward compatible, it corresponds to a MINOR release. If the change is not backward compatible, it corresponds to a MAJOR release.

style

Change affects only the style, not the meaning of the code. Examples include white-space changes or code formatting.

build

Change affects the building components. Examples include changes to the CI pipeline or the project version.

The scope indicates which part of OSI is affected by the commit. With OSI, commits can have one of the following scopes:

code

Change affects the OSI code.

inlinedocs

Change affects the inline documentation.

docs

Change affects the accompanying documentation.

The description gives a concise summary of the change. The description shall adhere to the following rules:

  • Use imperative mode and present tense to indicate what happens when the change is applied.

  • Do not capitalize the first letter.

  • Do not end the description with a full stop.

The optional body contains information on the motivation for the change. This includes references to GitHub issues by ID. GitHub uses these IDs to create links between the issues and the commit history.

The optional footer contains a note if the changes are breaking backwards compatibility. This note starts with BREAKING CHANGES: followed by a concise description of what this change breaks.

The following example shows a commit message meeting all requirements:

feat(model): Prevent empty StopTriggers

refers to #23

BREAKING CHANGES: StopTrigger can no longer be empty
Signed-off-by: Max Mustermann <max.mustermann@email.address>

4.3.5. Guidelines for contributions

Commit guidelines exist to ensure the transparency and intelligibility of the commit history. ASAM OSI® enforces the following commit guidelines:

  • Prefer small atomic commits over large ones that do many things.

  • Do not mix refactoring and new features.

  • Do not mix style changes, for example indentation changes, with actual code changes.

  • If you add new messages to a *.proto file, add appropriate documentation as well.

  • Run the unit tests for comment compliance to check if you followed the correct syntax guidelines for *.proto files.

  • Follow the guidelines for commit messages.

  • Sign off commit messages.

  • Name branches meaningfully and consistently.

  • If a commit contains work-in-progress, add the WIP label to the commit message.

Related topics

4.3.6. Interface conventions

OSI messages, enums, field messages, and field enums shall comply with OSI interface conventions. These conventions ensure that message definitions and the corresponding classes are consistently named and easy to read.

Message names shall use PascalCase.

message EnvironmentalConditions
{
}

Message field names shall use snake_case.

message EnvironmentalConditions
{
    optional double atmospheric_pressure = 1;
}

Enum names shall use PascalCase.

message EnvironmentalConditions
{
    optional double atmospheric_pressure = 1;

    enum AmbientIllumination
    {
    }
}

Enum field names shall use UPPER_SNAKE_CASE. Enum fields shall always be prefixed with the name of the corresponding enum. The first enum field shall always use the suffix UNKNOWN. The second enum field shall always use the suffix OTHER.

message EnvironmentalConditions
{
    optional double atmospheric_pressure = 1;

    enum AmbientIllumination
    {
        AMBIENT_ILLUMINATION_UNKNOWN = 0;

        AMBIENT_ILLUMINATION_OTHER = 1;

        AMBIENT_ILLUMINATION_LEVEL1 = 2;
    }
}

4.3.7. Branching workflow for member contributors

Members of the OSI project can contribute to the ASAM OSI repositories directly.

Prerequisites

  • You have a GitHub account.

  • You are a member of the ASAM OSI project.

Steps

  1. Create an issue describing the intended change.

  2. Clone the corresponding repository on your local machine.

  3. Create a branch with a meaningful name. Follow the branch-name conventions.

  4. Commit and push your changes to the branch. Follow the commit messages guidelines.

  5. When your changes are ready for review, create a pull request. If possible, add references to corresponding issues and appropriate labels.

  6. Ask reviewers to review your changes.

  7. When discussions about the changes are done, add the ReadyForCCBReview label. Pull request with this label will be discussed at the next meeting of the Change Control Board.

  8. When the Change Control Board approves the changes, the pull request is labelled as ReadyToMerge. This label indicates that the changes in the pull request can be merged.

  9. Merge the changes into the repository’s master branch.

Related topics

4.3.8. Forking for non-member contributors

External contributors must fork the OSI repositories and contribute their changes via a pull request.

Prerequisites

  • You have a GitHub account.

Steps

  1. Create an issue describing the intended change.

  2. Fork the corresponding OSI repository on GitHub.

  3. Clone the forked repository on your local machine.

  4. Create a branch with a meaningful name. Follow the branch-name conventions.

  5. Commit and push your changes to the branch. Follow the commit messages guidelines.

  6. When your changes are ready for review, create a pull request. If possible, add references to corresponding issues and appropriate labels.

  7. Ask reviewers to review your changes.

  8. When discussions about the changes are done, add the ReadyForCCBReview label. Pull request with this label will be discussed in the next meeting of the Change Control Board.

  9. When the Change Control Board approves of the changes, the pull request is labelled as ReadyToMerge. This label indicates that the changes in the pull request can be merged.

  10. Merge the changes into the master branch of the repository.

Related topics

4.3.9. Commenting on messages

The ASAM OSI® reference documentation is created using Doxygen. The content of the reference documentation is generated from comments in the .proto files. Follow these steps when creating comments on messages to keep the documentation style consistent.

Prerequisites

  • You have created a new message.

Steps

  1. Add a brief description using the \brief keyword followed by an empty comment line.

  2. Optionally, add an image using the \image html keyword followed by an empty comment line. The image must be stored at ./open-simulation-interface/docs/images

  3. Optionally, add a detailed description spanning multiple lines followed by an empty comment line.

  4. Optionally, add notes using the keyword \note.

Example

// \brief The conditions of the environment.
//
// \image html EnvironmentalConditions.svg
//
// Definition of light, weather conditions and other environmental conditions.
//
// \note These conditions apply locally around the host vehicle.
//
message EnvironmentalConditions
{
}

4.3.10. Commenting on fields and enums

The ASAM OSI® reference documentation is created using Doxygen. The reference documentation’s content is generated from comments in the .proto files. Follow these steps when creating comments on fields and enums to keep the documentation style consistent.

Prerequisites

  • You have created a field or enum.

Steps

  1. Add a description to the field or enum followed by an empty comment line.

  2. Add the unit of the field using the format Unit: UNIT followed by an empty comment line.

  3. Optionally, add notes using the keyword \note.

  4. Optionally, add literary references to the comments. The list of references starts with \par References: followed by the references. Every reference starts on a new line. Every reference begins with a reference number in the format [n]. Every reference ends with \n, except the last reference.

  5. Optionally, add rules encapsulated between \rules and \endrules.

Example

// \brief The conditions of the environment.
//
// \image html EnvironmentalConditions.svg
//
// Definition of light, weather conditions and other environmental conditions.
//
// \note These conditions apply locally around the host vehicle.
//
message EnvironmentalConditions
{
    // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa) [1, 2].
    //
    // Unit: Pa
    //
    // \note 100000 Pa = 1 bar
    //
    // \par References:
    // [1] DIN Deutsches Institut fuer Normung e. V. (1982). <em>DIN 5031-3 Strahlungsphysik im optischen Bereich und Lichttechnik - Groessen, Formelzeichen und Einheiten der Lichttechnik</em>. (DIN 5031-3:1982-03). Berlin, Germany. \n
    // [2] Rapp, C. (2017). Grundlagen der Physik. In <em>Hydraulik fuer Ingenieure und Naturwissenschaftler</em> (pp.23-36). Springer Vieweg. Wiesbaden, Germany. https://doi.org/10.1007/978-3-658-18619-7_3. p. 105.
    //
    // \rules
    // is_optional
    // is_greater_than_or_equal_to: 90000
    // is_less_than_or_equal_to: 200000
    // \endrules
    //
    optional double atmospheric_pressure = 1;
}

Related topics

4.3.11. Guidelines for creating literary references

When citing literature in the reference documentation, adhere to the following guidelines:

  • All sources shall be primary sources. Sources like Wikipedia are not allowed.

  • OSI uses APA style references from the American Psychological Association.

  • In the text, sources are cited using numbers in brackets.

  • In the references list, the number in brackets is resolved to a full citation.

  • Titles shall be written in italic, using <em>title</em>.

  • If the list contains more than one entry, add \n at the end of the line to create a line break within the list.

  • Author names shall be written as <surname>, <initial(s)>.

  • Editor names shall be written as <initial(s)> <surname>.

  • Page numbers are optional and may be used with long texts or for referencing specific sections.

Templates

Use the following templates for creating properly styled references:

Compilation
<author1>, <author2>, <author3> & <author4>. (<year>). Contribution in a compilation title. <em><Compilation Title></em>. <edition>. <page(s)>. <publisher>. <location>. <doi>. <page(s)>.
Book
<author1>, <author2> & <author3>. (<year>). <em><book (monograph) title></em>. <edition>. <publisher>. <doi>. <page(s)>.
Chapter in a book
<author1> & <author2>. (<year>). <book chapter title>. In <editor1> & <editor2> (Eds.), <em><book title></em> (<page(s)>). <publisher>. <doi>. <page(s)>.
Article in a journal
<author1> & <author2>. (<year>). <journal article title>. <em><journal title></em>. <page(s)>. <location>. <doi>. <page(s)>.
Phd thesis
<author>. (<year>). <em><Phd thesis title></em>. Phd. thesis. <location>. <university>. <doi or url>. <page(s)>.
Online article
<author>. (<year>, <month> <day>). <em><internet article title></em>. Retrieved <month> <day>, <year>, from <url>.
Standard
<standarding organisation>. (<year>). <em><title of the standard></em>. (<standard identifier>). <location>.
Patent
<author>. (<year>). <em><patent title and id></em>. <location>. <organisation>.

More sample templates are available at https://apastyle.apa.org.

Example

    // [...]
    // \par References:
    // [1] DIN Deutsches Institut fuer Normung e. V. (1982). <em>DIN 5031-3 Strahlungsphysik im optischen Bereich und Lichttechnik - Groessen, Formelzeichen und Einheiten der Lichttechnik</em>. (DIN 5031-3:1982-03). Berlin, Germany. \n
    // [2] Rapp, C. (2017). Grundlagen der Physik. In <em>Hydraulik fuer Ingenieure und Naturwissenschaftler</em> (pp.23-36). Springer Vieweg. Wiesbaden, Germany. https://doi.org/10.1007/978-3-658-18619-7_3. p. 105.
    //
    optional double atmospheric_pressure = 1;
}

4.4. Reviewing contributions

4.4.1. Review guidelines for authors

Code review enhances the quality of the code and reduces the likelihood of introducing new bugs in the code base. Reviewing code is a technical discussion, not an exam. It is a common effort to learn from each other.

Before asking for a review, make sure your changes meet the following requirements:

  • Code is readable and easy to understand.

  • Code does not contain commented-out lines and deprecated comments.

  • Code contains helpful comments to be used in the reference documentation.

  • Variable and function names follow the naming convention.

  • Commit messages are meaningful and follow the convention.

  • All commits are signed off.

Related topics

4.4.2. Review guidelines for reviewers

Code reviews can be challenging at times. Follow these suggestions when reviewing code to avoid common pitfalls:

Ask questions

What is the purpose of this change? If this requirement changes, what else would have to change? How could we make this more maintainable?

Discuss in person for more detailed points

Online comments are useful for focused technical questions. In the case of more detailed discussions, it will often be more productive to discuss the matter in person.

Explain your reasons

Sometimes it is best to both ask if there is a better alternative and at the same time justify why a problem in the code is worth fixing. Criticism with no explanation can appear confrontational.

Make it about the code

It is easy to take notes from code reviews personally, especially if we take pride in our work. It is better to have a discussion about the code than about the developer.

Indicate the importance of fixes

When offering many suggestions at once, highlight the point that not all of them need to be acted upon at once. Indicate the importance of your suggestions. This lets developers improve their work incrementally.

Take the developer’s opinion into consideration

Imposing a particular design choice based on personal preferences and with no real explanation will incentivize the developer to be passive instead of active and creative.

Do not re-write, remove, or re-do all the work

It sometimes appears easier to re-do the work yourself, which means discarding the developer’s work. This can give the impression that the developer’s work is worthless. It also creates additional work for the reviewer, who is effectively taking on responsibility for the code.

Consider the person you are reviewing

Developers are human beings. Consider their personality and experience when reviewing their code.

Avoid confrontational and authoritative language

The way we communicate has an impact on the receiver. Consider these two statements which communicate a problem in the code: The statement “This operation is wrong, please fix it.” is confrontational and authoritative. Instead, explain the specific error and ask the developer to review the code again.

Terms and definitions

Co-simulation

Type of Functional Mockup Unit (FMU).
Co-simulation FMUs contain their own numerical solver. This importing tool sets the FMU inputs, asks the FMU to step forward a given time, and reads the FMU output after the step is completed. With OSMP, models are packaged as valid FMI-2.0 FMU for co-simulation.

Ego vehicle

Externally controlled vehicle used for scenario descriptions.
For evaluation of automated driving systems, the ego vehicle is the vehicle that is controlled by the system-under-test. For human-driver experiments, the ego vehicle is the vehicle that is driven by the human driver.

Environmental effect model

Information set that deals with effects and phenomena caused by, for example, shadows and occlusions, weather effects, the physics of a sensor, or the pre-processing of raw sensor data. An environmental effect model has a SensorView message as input, which comes from the environment simulation, and a SensorView message as output. The output is sent to the sensor model.

FMI (Functional Mockup Interface)

Free standard that defines a container and an interface to exchange dynamic models using a combination of XML files, binaries, and C code zipped into a single file.

FMU (Functional Mockup Unit)

Simulation model that adheres to the FMI standard.

GroundTruth

Information set that describes the whole simulated environment around any simulated vehicle. It is based on data available to the simulation environment.

Logical model

Logical models consume SensorData messages and produce SensorData messages.

Examples: - Sensor-fusion model: Combines the output of multiple sensor models to produce data with less uncertainty - Fault-injection model which, contrary to a sensor-fusion model, may be used to increase uncertainties

Object coordinate system

Local coordinate system whose origin may be identical to the center of the object’s bounding box. If the origin is not identical to the center of the object’s bounding box, the object documentation provides the actual definition.

OSI (Open Simulation Interface)

Specification for interfaces between models and components of a distributed simulation. OSI has a strong focus on environmental perception of automated driving functions. It also specifies interfaces for modeling traffic participants.

OSMP (OSI Sensor Model Packaging)

Specifies how models that use Open Simulation Interface (OSI) in simulation environments are packaged in accordance with the Functional Mock-up Interface 2.0 (FMI 2.0).

Sensor coordinate system

Coordinate system for all entities that are part of SensorData. The origin is the mounting position of the physical sensor or a virtual mounting position, depending on the OSI message.

Sensor model

From OSI’s perspective, a sensor model refers to the part of a sensor system model that includes processing algorithms at an object detection level. Sensor models consume SensorView messages and produce SensorData messages. Sensor model output does not represent raw data but detected features or classified objects.

SensorView

Information set that is derived from ground truth and used as input to sensor models, environmental effect models, or traffic participant models.

Traffic participant model

Information set that models the dynamic behavior of moving objects by deciding how to change position, orientation, and other states of the dedicated moving object. To do this, it reacts on input given by SensorView and TrafficCommand resulting in TrafficUpdate as output.

Global coordinate system

Coordinate system for all entities that are part of ground truth. The global coordinate system is an inertial x/y/z-coordinate system. The origin is the global reference point that is determined by the environment simulation. This reference point may be derived from map data or other considerations.

Bibliography

[1] ISO 23150:2021 Road vehicles — Data communication between sensors and data fusion unit for automated driving functions — Logical interface. International Organization for Standardization, Geneva, Switzerland, 2021-05.

[2] FMI 2.0: Functional Mock-up Interface for Model Exchange and Co-Simulation. Modelica Association, Linköping, Sweden, 2014-07.

[3] OpenDRIVE. ASAM e.V., 2020.

[4] OpenSCENARIO. ASAM e.V., 2021.

[5] OpenCRG. ASAM e.V., 2020.

[6] DIN ISO 8855:2013-11 Road vehicles - Vehicle dynamics and road-holding ability - Vocabulary. Deutsches Institut für Normung e.V., Berlin, Germany, 2013-11.

[7] Multi-Frequency GNSS Sensor Fusion With Quality Assessment for Automotive Applications. Reuper, 2020.

[8] Rotation Matrix. https://en.wikipedia.org/wiki/Rotation_matrix, 2022-01.

[9] Euler Angles. https://en.wikipedia.org/wiki/Euler_angles, 2022-01.

[10] Protocol Buffers. https://developers.google.com/protocol-buffers/, 2008-07.

[11] ISO 8601:2019 Data elements and interchange formats — Information interchange — Representation of dates and times. International Organization for Standardization, Geneva, Switzerland, 2004-12.

Annex A: Release Notes

v3.5.0 - OSI "Hard-fighting Hunt"

L(OSI)ng is not an option!

This is an official ASAM release of OSI. The standard can also be downloaded on the ASAM website.

Purpose

In this minor release, several interface messages have been updated and extended to better ensure consistency within the standard itself and harmonization with other OpenX-Standards like ASAM OpenDRIVE or OpenScenario. In this context the extension of GroundTruth by logical lane information - to empower a better traffic participant modelling - was one of the key achievements for this release.

  • Added logical lane information (including st-representation) for traffic participant usage.

  • Added route message TrafficCommandUpdate to offer a backchannel for (un)executed TrafficCommands.

  • Extended EnvironmentalConditions regarding sun, wind and cloud state.

  • Added dash property to boundary points.

  • Extended HostVehicleData by automated driving function states and operating states.

  • Added friction coefficient to moving object.

  • Improved description of trucks in VehicleClassification.

  • Added Role to VehicleClassification.

  • Concretized LaneBoundary modelling.

  • Removed protobuf version recommendation.

  • CMake: Project usable via FetchContent.

  • Doxygen: Improved output.

  • CI: Moved to current protobuf release.

  • Updated documentation of coordinate systems and their transformations.

v3.4.0 - OSI "Gallant Glock"

Stay p(OSI)tive!

Purpose

In this minor release, several interface messages have been updated and extended to better ensure consistency within the standard itself and harmonization with other OpenX-Standards like ASAM OpenDRIVE. Moreover, this release provides a first glance on the on-going efforts for OSI’s documentation improvements and migration to AsciiDoc.

Documentation Updates
  • Updated the documentation’s structure and migrated it to AsciiDoc.

  • Updated the description of OSI’s top level messages.

  • Updates on additional descriptions, like those for trace file formats, naming conventions and installation instructions for Linux/Windows.

Technical Updates
  • Extended SensorViewConfiguration message to allow the consumer to choose to not include static content in the SensorView ground truth information.

  • Updated StationaryObject classification enums to avoid "pylon" duplication.

  • Extended StationaryObject classification message to include speed bumps.

  • Extended StationaryObject to include emitting structures of electromagnetic waves (for example this can be used to define a streetlamp).

  • Extended the TrafficSign classification message, by adding attributes country, country_revision, code and sub_code, to better support internationalization and to align with ASAM OpenDRIVE.

  • Updated the color coding message description to better align with ASAM OpenDRIVE.

  • Update the color coding message description to include Grey, RGB, RGBIR, HSV, LUV and thus align with ISO-23150.

  • Added an enum for dashed lane boundaries to disambiguate start and end of those.

  • Extended HostVehcileData with more comprehensive on-board information, and promoted the message to a top-level message for exchange between simulation environments and (external) dynamic models.

  • Extended LidarDetection message under feature data to include echo pulse width information to better support several sensor outputs that are currently on the market.

  • Extended OSI to include a generic external reference message to enable traceability for data from other standards, including other ASAM OpenX standards.

  • Added support for using OSI with Flatbuffers encoding for OSI messages instead of ProtoBuffers, in preparation for a potential switch of default encoding in a future major release.

  • Extended LaneBoundary message to include additional types, to better align with ASAM OpenDRIVE.

v3.3.1 - OSI "Fabulous Fangio", Update 1

  • Bug Fix: Fixed outdated version information in VERSION file in 3.3.0. This led to wrong versioning in proto definitions and Doxygen documentation.

  • Bug Fix: Removed outdated picture in README.md.

v3.3.0 - OSI "Fabulous Fangio"

Stay p(OSI)tive!

Purpose

As a part of the increasing adoption of OSI in the industry, and its movement to ASAM as its home, several new use cases and extensions for OSI have been identified. This minor release highlights the work that has been done on several working packages including the introduction of brand new top level messages which extend OSI’s scope beyond the specialized world of sensor modeling.

  • Introduced the TrafficCommand top-level message which enables event-based control of traffic participant models, e.g. with regard to a scenario specification.

  • Introduced the TrafficUpdate top-level message to send updated properties of traffic participant models.

  • Add new LogicalDetectionData message to SensorData, which provides detection data with respect to the reference frame of the logical/virtual sensor.

  • Added a new submessage to further specify wheel data.

  • Added a new field to support future trajectories of moving objects.

  • Added a new subtype message to osi_lane to better align with OpenDrive’s lane type information and enable traffic participant models to identify lanes on which they are supposed to move.

  • Extended traffic lights and signs messages to include the model_references attribute that can be used to point out to a 3D-model.

  • Add global model reference to ground truth that can be used to specify the 3D model representing the environment.

  • Extended the camera sensor view configuration to better support the configuration of the simulation environment.

  • Added a new field to describe the position of the steering wheel.

  • Added a message MovingObjectClassification for classify-able attributes that are shared between different moving object types. Introduced the assigned lane id and the assigned lane percentage of a moving object there.

  • Updated to checklist for pull requests to provide clearer orientation for all users.

  • Updated the documentation of centerline and lane boundaries (ordering of the points, describing those lines).

  • Updated the documentation of 3D bounding boxes.

  • Update the documentation of ground clearance.

  • Make handling of enums in rules check more robust, especially ones.

  • Set the default compiler to C++ 11 to support protobuf>3.6.

v3.2.0 - OSI "Editorial Eaton"

Purpose

The work on the OSI project was until now mainly organized by the BMW AG. In order to enable as many interested parties as possible to contribute to the success of the Open Simulation Interface the project has been transferred to the ASAM e.V. which has been made public in the ASAM press release. A new chapter in the development of OSI is now opened with the kickoff workshop leading to hopefully many project proposals streamlining the efficient future development of the interface. Due to this we decided to focus on the improvement of processes and documentation with this release.

  • Updated README according to K(eep) I(t) S(imply) S(tupid) principle

  • Added Issue and Pullrequest templates

  • Travis CI updated

    • Update to bionic 18.04

    • Added tests for building protobuf 2.6 and 3.0 in parallel

    • Bugfixed the display of doubled documentation

  • Fixed several typos in the comments

  • Added a centralized documentation in OSI-Documentation

    • Added contributors guidelines

    • Added commenting style guidelines

    • Added uniform citation style according to APA

    • Updated installation guides for osi in Linux and Windows

    • Added a reference in sphinx based on the generated doxygen documentation

  • Added rules to the comments in order to enforce osi message validation with the OSI-Validator

  • Added the rule definitions in the rules.yml

  • Modularized testing of commenting style into python unit tests

  • Defined a standardazied a file format for reading trace files (*.osi)

  • Defined naming conventions of osi files

  • Added a *.txt to *.osi file converter for backward compatibility

  • Added a script to make traces readable for plausibility checks

  • Corrected the citing style for OSI Bibtex

  • Corrected unit specifications and references according to DIN (e.g. removed Unit: [])

  • Added timestamp in osi_environment

  • Added is_out_of_service bool to traffic light / traffic sign

v3.1.2 - OSI "Dynamic Duncan", Update 2

  • Bugfix: The version number is now correct in the VERSION file.

v3.1.1 - OSI "Dynamic Duncan", Update 1

  • Bug Fix: Changed open_simulation_interface target back from being a static library to a shared library, as before (this reverts an inadvertent change in v3.1.0 from previous releases). v3.1.0 breaks all users of the shared library (i.e. everyone building on Linux/Unix systems, and even some using the DLL on Windows).

v3.1.0 - OSI "Dynamic Duncan"

Purpose

This time of the year Santa comes with presents and has also thought about the sensor modelers of this planet. We introduce the current state of the ISO 23150 [1]] discussions including Ultrasonic and Camera Detections. The traffic signs have been reworked and the documentation has been extended for a perfect user experience. Trust me - it’s amazing!

  • Complete rework of traffic signs including images in documentation.

  • Added Camera Detections in osi_featuredata.proto.

  • Added Ultrasonic Detections in osi_featuredata.proto.

  • Introduced light states for emergency and service vehicles.

  • Added orientation_acceleration and updated formulas.

  • Extended documentation with svg images.

  • Added model_reference for static and moving objects.

  • Added map_reference in ground truth.

  • Added proj4 string for coordinate transformations.

  • Introduced raster_lidar_proposal from innoviz.

  • Improved documentation with HTML tables and images for all traffic signs.

v3.0.1 - OSI "Cosmic Coulthard", Update 1

Purpose

This release is a patch reworking parts of the documentation in order to avoid ambiguities and improving the build/installation process of OSI.

  • Added script to automatically convert the messages from proto2 to proto3 with on the wire compatibility

  • cmake enhancements to enable multi-version support of OSI 2 and OSI 3

  • Added Python 3 support

  • Clarification of multiple comments

  • Added explanatory images in the documentation

  • centerline definition improved

  • signal_strength definition in LidarSensorView corrected

  • FeatureData::ambiguity_id definition clarified

  • RadarSensorViewConfiguration::AntennaDiagram::response definition clarified

v3.0.0 - OSI "Cosmic Coulthard"

Purpose

This release is a complete rework including the feedback from many OSI users. Thank you! We are aligned with the ongoing discussions for the upcoming ISO 23150 [1] standard for hardware sensor outputs in order to bring simulation and the hardware in the car closer together.

  • Added major version to package label (osi3), allowing concurrent use of OSI 2.x and OSI 3.x in one process.

  • Added new top-level messages (new concept SensorView (Configuration),etc.).

    • GroundTruth.

    • SensorView.

    • SensorData / FeatureData.

    • SensorViewConfiguration (used for auto-configuration of SensorView).

  • Added technology-specific SensorView sub-messages to aid physical models.

  • Introduced conceptual separation of “SensorModels” and “LogicModels”.

  • Extended enumerations (e.g. traffic sign Type according to StVO, vehicle Type, etc.).

  • Improved messages and definitions (additional RoadConditions, country code in GT, AmbientIllumination, etc.).

  • Use ISO 8855 [6] coordinate systems (incompatible with earlier OSI versions).

  • Redefined DetectedXXX messages.

  • Introduced DetectedStationaryObjects.

  • Merged MovingObjects and Vehicle messages.

  • Redefined Lane messages (with separated lane boundary messages and intersections).

  • Redefined TrafficLight messages.

  • Redefined TrafficSigns (1 x MainSign + n x SupplementarySign inclusive BaseStationary).

  • New FeatureData messages (rework of previous LowLevelData message) - aligned with an upcoming standard ISO 23150 [1].

  • FeatureData usable for fusion units.

  • Extension and clarification of the existing doxygen documentation.

  • Improved doxygen collaboration diagrams.

  • Build process improvements, added install targets.

  • Made proto definitions compatible with proto3 restrictions to allow concurrent use with proto3-only implementations in the future.

  • Fixed version-checking of transmitted data.

  • AND MUCH MORE ENJOY!!!

v2.2.1 - OSI "Brave Brabham", Update 1

Purpose

This release focuses on optimizing the build process and ensures the proper installation of different versions of OSI on a single system.

  • Allowing several OSI versions on the same computer.

  • Improves CI builds to also test the installation cmake targets for proper completion.

v2.2.0 - OSI "Brave Brabham"4

Purpose

This release focuses on optimizing the build process and documentation.

  • Added a shared library target to the CMake build script.

  • Generated a proper doxygen documentation.

  • Placed the version number in one file (VERSION).

  • Added unit testing mechanism including style guide checking.

  • Redefined precipitation and added a fog definition to the environmental conditions message.

  • Added layer id to low level point cloud data.

  • Reworked large parts of the build instructions in the WIKI.

v2.1.0 - OSI "Agile Andretti"

Purpose

This is the initial BASE VERSION for Tool Development.

Remarks

We will now release the versions using the name of a Formula 1 driver! Naming convention: "adjective + last name driver" → Alliteration necessary!

v2.0.0 - OSI Initial Commit

This is the initial version of the Open Simulation Interface (OSI).

Overview

OSI is a generic interface for the environmental perception of automated driving functions in virtual scenarios. It is primarily conceived to enable easy and straightforward compatibility between automated driving functions and the variety of driving simulation frameworks available. The data description has been derived from the perspective of sensor modeling for automated test and validation of highly automated driving functions.

Implementation

OSI primarily contains an object based environment description using the message format of the protocol buffers library developed and maintained by Google.

Detailed description

Top level interfaces

OSI consists of two individual top level interfaces for object data: The OSI::GroundTruth and the OSI::SensorData interface.

  • The OSI::GroundTruth interface provides an exact view on the simulated objects in a global coordinate system. This message is populated using the internally available data of the used (driving)-simulation framework and is afterwards published to external subscribers with an exporter plugin.

  • The OSI::SensorData interface describes the objects in the reference frame of a sensor for environmental perception. It is generated from a OSI::GroundTruth message and can either be used to directly connect to an automated driving function using ideal simulated data, or may serve as input for a sensor model simulating limited perception as a replication of real world sensor behavior.

Low level interfaces

Additionally to the two top level interfaces, OSI contains an OSI::LowLevelData message. This message describes the output of a (physical) model of the measurement process before tracking and object hypothesis. It does not deal with object data, but may comprise the geometrical influence of 3D simulations e.g. generating Lidar point clouds with a ray-tracer plugin. In addition this message supports generic radar reflection lists and will be extended to supporting low level camera data in the future.