Skip to content
This repository has been archived by the owner on Aug 11, 2021. It is now read-only.

Latest commit

 

History

History
261 lines (190 loc) · 11.9 KB

mapping_specification.md

File metadata and controls

261 lines (190 loc) · 11.9 KB

Signal Mapping Format Specification {#page_signal_mapping_spec}

Configuration format

The actual mapping of signals is configured using a xml-based configuration format.

Overview

A mapping configuration file contains a header with meta information about the file, source signal declarations, target signal definitions and transformation definitions. A source signal consists of a name and a signal type. Target signals also consist of a name and a signal type. They define any number of signal element assignments as well as any trigger conditions.

Conceptionally, signal element assignments define how the target signal is assembled while triggers define when the target signal buffer is submitted to the user.

A target signal element can be assigned a constant numeric value or a source signal element. In the later case, a transformation can be used to alter the source signal element value during assignment. For details see \ref subsec_features_types. Trigger conditions are optional, since it is always possible to actively get the current target signal buffer. For now, only periodic triggers can be defined, using a period and a unit of time.

Specification

This specification contains the following parts:

  • Header
  • Sources
  • Targets
  • Transformations

These sections will be described in the following paragraphs, see the XSD specification for more details.

Header

The header section contains meta information about the document and version information. It is similar to the header informations in the DDL Definition File Format.

Tag Type Required Description
language_version Float mandatory Version number of the mapping format
author String mandatory Author
date_creation Date mandatory Creation date
date_change Date mandatory Last modification date
description Text mandatory Short description

Sources

This section defines the source signals that can be used in assignments to any target signal elements(s).

The tag <source> supports the following attributes:

Name Type Required Description
name String mandatory Name of the signal
type String mandatory DDL structured type of the signal

Targets

This section contains definitions of target signals, assignement to their target elements as well as any trigger definitions.

The tag <target> supports the following attributes:

Name Type Required Description
name String mandatory Name of the signal
type String mandatory DDL structured type of the signal

The tag <assignment> supports the following attributes:

Name Type Required Description
to String mandatory Name of the target signal element to be assign
constant String optional* Float value which will assigned during initialisation
function String optional* Macro to assign
from String optional* Source signal or source signal element to assign
transformation String optional Transformation to apply to the source element

*: The attributes constant, function and from are mutually exclusive but one of them is required. The attribute transformation can only be applied when the attribute from is defined.

The attribute function can have the values:

Function Parameter Description
simulation_time() None Evaluates to the current simulation time
trigger_counter() None Trigger counter, incremented whenever a trigger for the target fires
trigger_counter() Positive numeric value, modulo parameter Trigger counter with wrap-around
received() Name of the source signal Received indicator, evaluates to true if the source signal has been received

The tag <trigger> supports the following attributes:

Name Type Required Description
type String mandatory Trigger type
period String optional Float value defining the length of the period
unit String optional unit to interpret the given period
variable String optional For signal triggers: name of the source signal, for _data triggers: name of the source signal element
operator String optional Operator used for data triggers: less_than, greater_than, less_than_equal, greater_than_equal, equal or not_equal
value String optional Float value to compare with the source element

The attribute type has three acceptable values:

  • periodic
  • data
  • signal

For the periodic Trigger type, the attributes period and unit are mandatory. For the data Trigger type, the attributes variable, operator and value are mandatory. For the signal Trigger type, the attribute variable is mandatory.

Transformations

This section contains definitions of transformations that can be used in assignements. For the moment the only transformations available are polynomial tranformations and enum to enum transformations.

The tag <polynomial> supports the following attributes:

Name Type Required Description
name String mandatory Name of the transformation
a String optional parameter of the polynom for X^0
b String optional parameter of the polynom for X^1
c String optional parameter of the polynom for X^2
d String optional parameter of the polynom for X^3
e String optional parameter of the polynom for X^4

The tag <enum_table> supports the following attributes:

Name Type Required Description
name String mandatory Name of the transformation
from String mandatory Enumeration type used as transformation source
to String mandatory Enumeration type used as transformation target
default String mandatory Default value used when no conversion is defined. It must be an element of the target enumeration

The tag <conversion> supports the following attributes:

Name Type Required Description
from String mandatory Element from the enumeration type used as transformation source
to String mandatory Element from the enumeration type used as transformation target

Example

The following example shows the mapping of the target signals LightSource and Object. LightSource elements are mapped from two source signals, LightOrientation and LightPos, as well as some constants. Two of its assignments are also transformed during mapping. The entire target is triggered by a periodic trigger with a period of 5s, and when LightPos is received and LightPos.f64X is lesser than 2. Object element is an enumeration, mapped with transformation from SourceObject. The Enumeration Type tObjectType is mapped in an obsolete Enumeration created for the example. This Target is trigger when LightOrientation is received.

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<mapping>
    <header>
        <language_version>1.00</language_version>
        <author>AUDI Electronic Ventures GmbH</author>
        <date_creation>2016-Jun-08</date_creation>
        <date_change>2016-Jun-08</date_change>
        <description>Example mapping configuration</description>
    </header>
    <sources>
        <source name="LightOrientation" type="tFEP_VU_Coord" />
        <source name="LightPos" type="tFEP_VU_PointCartesian" />
        <source name="SourceObject" type="tObject" />
    </sources>
    <targets>
        <target name="LightSource" type="tFEP_VU_LightSource">
            <assignment to="f64SimTime" function="simulation_time()" />
            <assignment to="ui32Id" constant="1" />
            <assignment to="ui8State" function="trigger_counter(3)" />
            <assignment to="sPosIntertial.f64X" from="LightPos.f64X" transformation="cm_to_m" />
            <assignment to="sPosIntertial.f64Y" from="LightPos.f64Y" transformation="cm_to_m" />
            <assignment to="sPosIntertial.f64Z" constant="0" />
            <assignment to="sPosIntertial.f64H" from="LightOrientation.f64H" />
            <assignment to="sPosIntertial.f64P" from="LightOrientation.f64P" />
            <assignment to="sPosIntertial.f64R" from="LightOrientation.f64R" />
            <trigger type="periodic" period="5" unit="s"/>            
            <trigger type="data" variable="LightPos.f64X" operator="greater_than" value="2"/>
        </target>
        <target name="Object" type="tObjectObsolete">
            <assignment to="objectType" from="SourceObject.objectType" transformation="table1" />
            <trigger type="signal" variable="LightOrientation"/>
        </target>
    </targets>
    <transformations>
        <polynomial name="cm_to_m" a="0" b="0.01" />
        <enum_table name="table1" from="tObjectType" to="tObjectTypeObsolete" default="OT_Undefined" >
            <conversion from="OT_Car" to="OT_Vehicle"/>
            <conversion from="OT_Truck" to="OT_Vehicle"/>
            <conversion from="OT_Van" to="OT_Vehicle"/>
            <conversion from="OT_Motorbike" to="OT_Vehicle"/>
            <conversion from="OT_Bicycle" to="OT_Vehicle"/>
            <conversion from="OT_Pedestrian" to="OT_Human"/>
            <conversion from="OT_Animal" to="OT_Animal"/>
        </enum_table>
    </transformations>
</mapping>

Features

Constants and Macros

A target signal element can be assigned a constant numeric value. This value will be parsed as a floating point number and casted to the target element type.

A target signal element can also be assigned the simulation time, a trigger counter or a received flag.

Note:

Constants and Macros can only be used to initialize scalar as well as arrays of scalar elements Any unassigned target elements will be assigned the default value configured in the DDL definition of the target signal type

Transformations

Transformations can be used to alter the value of an assignment during runtime. Polynomial and enum to enum transformations are supported.

Polynomial transformations use the following polynomial to transform the assignments:

value = a*value^0 + b*value^1 + c*value^2 + d*value^3 + e*value^4

Any undefined coefficients are set to 0.

Note:

Transformations are only supported for scalar as well as arrays of scalar elements

Supported types and cross-type assignments

Assignments from one type to another are supported in the following way

Source Target Specification
Constant Scalar Datatype conversion using standard C++ casting methods
Simulation time Scalar Datatype conversion using standard C++ casting methods
Trigger counter Scalar Datatype conversion using standard C++ casting methods
Received Flag Scalar Only for boolean
Scalar Scalar Datatype conversion using standard C++ casting methods. Transformations allowed
Array Array Only for arrays of same size. Datatype conversion using standard C++ casting methods. Transformations allowed
Structure Structure Only for structures of same type
Array Array Only for arrays of same size and structures of same type
Enum Enum Datatype conversion to the underlying numerical datatype using standard C++ casting methods
Array Array Only for arrays of same size. Datatype conversion using standard C++ casting methods.

Scalar datatypes are enumerations, tBool, tChar, tUInt8, tInt8, tUInt16, tInt16, tUInt32, tInt32, tUInt64, tInt64, tFloat32 and tFloat64.

Array and structure elements can be used separately in assignments, for example:

<assignment to="structMinimal.i64Val" from="InSignal.structMinimal.ui32Val" />
<assignment to="structMinimalAry[0]" from="MinimalSignal" />

Note:

A target element can only be assigned once. For instance, if one element in a substructure is already assigned, the whole substructure can not be assigned and reciprocally.

Target and source signals may only use structured types