DDL Mapping Filter
- Sources and Targets
- DDL Mapping Triggers

DDL Mapping Filter

Plugin Information

Plugin Filename	adtf_ddl_mapping_filter.adtfplugin
Plugin Description	adtf_ddl_mapping_filter.plugindescription
Plugin Name	DDL Mapping Filter Plugin
License	ADTF
Support Mail	support@digitalwerk.net
Homepage URL	support.digitalwerk.net

Plugin Versions

Plugin Version	3.99.99
Plugin File Version	1.0
adtf	3.99.99
adtf::ucom	3.1.0

Component Information

Name	DDL Mapping Filter
CID	ddl_mapping.filter.adtf.cid
Description	Use this Filter to convert the content of DDL based samples from one or more incoming structured memory or plain type values to one or more outgoing structured memory or plain type value.
Type	Filter

Properties

Name	Value	Type	Description	Subproperties
default_trigger_time	0	tUInt32	Minimal default trigger time in ms (for targets with no trigger)
mapping_file		cFilename	Filename for a *.map file that contains source and targets which can than be mapped to dynamic input/output pin.s	Filename Extension Filter: Map files (*.map)
output_sample_time	0	tUInt8	Option to use whether the current timestamp of the trigger or the current clock timestamp for the output sample time.	Value List: While writing the output use the time of the sources sample time. = 0 While writing the output use the current trigger time. = 1

Runner

Name	Activation Type	Data Triggered	Data Input	Thread Triggered	Thread Cyclic	Timer Triggered	Timer Interval	Description
periodic_trigger	1	0		0	0	1	100	Runner to periodically trigger the function which generates the output data for periodic triggers within mapping file.

Dynamic Pins

Dynamic Input Pins	true
Dynamic Output Pins	true
Dynamic Input Binding Pins	false
Dynamic Output Binding Pins	false

Sources and Targets

The DDL Mapping Filter is to convert the content of DDL based samples from one or more incoming structured memory or plain type values to one or more outgoing structured memory or plain type value.

To do so, the filter reads and interprets a DDL mapping file. The mapping file will describe a mapping prescription what content to read and where to write it. For a detailed description of the content please see https://digitalwerk.gitlab.io/solutions/adtf_content/adtf_base/adtf_core/dev_essential/doc/html/md_doc_html_ddl_mapping_specification.html.

The file contains so called sources with a name and a set DDL type or plain type. Also, it contains targets with a name and a set DDL type or plain type. Targets will transcribed into outpin, sources are corresponding input pins.

We recommend to use the delivered DDL Mapping Editor to create and edit mapping files.

Following names and types are possible for sources (inpins) and targets (outpins):

Sources and corresponding Inpins

example of mapping file content	resulting input pin	possible assignment
<source name="NestedStruct_in"> <properties> <property name="type">tNestedStruct</property> <property name="description"> <!-- ...here the ddl description of tNestedStruct... --></property> <property name="serialized">false</property> </properties> </source> ddl definition of the ddl namespace Definition: builds/digitalwerk/solutions/adtf_content/adtf_base/adtf_core/extern/pkg_ddl/include/adtfddl/codec/struct_element.h:14	Pin: input pin name: `NestedStruct_in` type: `adtf/default` with set `md_struct="tNestedStruct"` and `md_definition="...here the ddl description of tNestedStruct..."` Notice: The mapping file 2.0 is self contained and `tNestedStruct` must be described within the mapping file property `"type"` of the corresponding source.	On the targets following assignment example is possible: <assignment type="source"> <to>my_target_value_name</to> <source_name>NestedStruct_in</source_name> <value_name>sSimpleStruct.ui8Val</value_name> </assignment>
<source name="x"/> <property name="type">INT64</property> <property name="description"> <!-- ...here the ddl description of plain type INT64... --></property> <property name="serialized">false</property> </source>	Pin: input pin name: `x` type: `adtf/plaintype` with set `c-type="INT64"` and ddl type description set with `md_struct="INT64"` where only one element with the name `value` exists in the corresponding type. The corresponding ddl description will be automatically used. Notice: Following types are possible: `BOOL, INT8, UINT8, INT16, UINT16, INT32, UINT32, INT64, UINT64, FLOAT32, FLOAT64`.	<assignment type="source"> <to>my_target_value_name</to> <source_name>x</source_name> <value_name>value</value_name> </assignment>
<source name="my_source_pin/NestedStruct"> <properties> <property name="type">tNestedStruct</property> <property name="description"> <!-- ...here the ddl description of tNestedStruct... --></property> <property name="serialized">false</property> </properties> </source>	Pin: input pin name: `my_source_pin` type: `adtf/substreams` substream name: `NestedStruct` substream type: `adtf/default` with set `md_struct="tNestedStruct"` and `md_definition="...here the ddl description of tNestedStruct..."` Notice: To use ADTF Substreams a special behaviour and naming syntax is defined. Within DDL Mapping Filter only one pin will appear for `"my_source_pin"` and its substreams.	<assignment type="source"> <to>my_target_value_name</to> <source_name>my_source_pin/NestedStruct</source_name> <value_name>sSimpleStruct.ui8Val</value_name> </assignment>
<source name="my_source_pin/x"/> <property name="type">INT64</property> <property name="description"> <!-- ...here the ddl description of plain type INT64... --></property> <property name="serialized">false</property> </source>	Pin: input pin name: `my_source_pin` type: `adtf/substreams` substream name: `x` substream type: `adtf/plaintype` with set `c-type="INT64"` and ddl type description set with `md_struct="INT64"` where only one element with the name `value` exists in the corresponding type. Notice: Following substream types are possible: `BOOL, INT8, UINT8, INT16, UINT16, INT32, UINT32, INT64, UINT64, FLOAT32, FLOAT64`	<assignment type="source"> <to>my_target_value_name</to> <source_name>my_source_pin/x</source_name> <value_name>value</value_name> </assignment>

Targets and corrensponding Outpins

example of mapping file content	resulting output pin	possible assignment
<target name="NestedStruct_out"> <properties> <property name="type">tNestedStruct</property> <property name="description"> <!-- ...here the ddl description of tNestedStruct... --></property> <property name="serialized">false</property> </properties> </target>	Pin: output pin name: `NestedStruct_out` type: `adtf/default` with set `md_struct="tNestedStruct"` and `md_definition="...here the ddl description of tNestedStruct..."`	Assignment if the source contains substreams: <assignment type="source"> <to>sSimpleStruct.ui8Val</to> <source_name>my_source_pin/x</source_name> <value_name>value</value_name> </assignment> Assignment if the source does not contains substreams: <assignment type="source"> <to>sSimpleStruct.ui8Val</to> <source_name>NestedStruct_in</source_name> <value_name>sSimpleStruct.ui8Val</value_name> </assignment>
<target name="result"/> <property name="type">INT64</property> <property name="description"> <!-- ...here the ddl description of plain type INT64... --></property> <property name="serialized">false</property> </target>	Pin: output pin name: `result` type: `adtf/plaintype` with set `c-type="INT64"` and ddl type description set with `md_struct="INT64"` where only one element with the name `value` exists in the corresponding type. Notice: Following types are possible: `BOOL, INT8, UINT8, INT16, UINT16, INT32, UINT32, INT64, UINT64, FLOAT32, FLOAT64`.	Assignment if the source contains substreams: <assignment type="source"> <to>value</to> <source_name>my_source_pin/NestedStruct</source_name> <value_name>sSimpleStruct.ui8Val</value_name> </assignment> Assignment if the source does not contains substreams: <assignment type="source"> <to>sSimpleStruct.ui8Val</to> <source_name>NestedStruct_in</source_name> <value_name>sSimpleStruct.ui8Val</value_name> </assignment>
<target name="my_target_pin/NestedStruct"> <properties> <property name="type">tNestedStruct</property> <property name="description"> <!-- ...here the ddl description of tNestedStruct... --></property> <property name="serialized">false</property> </properties> </target>	Pin: input pin name: `my_target_pin` type: `adtf/substreams` substream name: `NestedStruct` substream type: `adtf/default` with a set `md_struct="tNestedStruct"` and `md_definition="...here the ddl description of tNestedStruct..."`	<assignment type="source"> <to>sSimpleStruct.ui8Val</to> <source_name>"my_source_pin/x</source_name> <value_name>value</value_name> </assignment> or <assignment type="source"> <to>sSimpleStruct.ui8Val</to> <source_name>NestedStruct_in</source_name> <value_name>sSimpleStruct.ui8Val</value_name> </assignment>
<target name="my_target_pin/x"/> <property name="type">INT64</property> <property name="description"> <!-- ...here the ddl description of plain type INT64... --></property> <property name="serialized">false</property> </target>	Pin: input pin name: `my_target_pin` type: `adtf/substreams` substream name: `x` substream type: `adtf/plaintype` with set `c-type="INT64"` and ddl type description set with `md_struct="INT64"` where only one element with the name `value` exists in the corresponding type. Notice: Following substream types are possible: `BOOL, INT8, UINT8, INT16, UINT16, INT32, UINT32, INT64, UINT64, FLOAT32, FLOAT64`	<assignment type="source"> <to>value</to> <source_name>"my_source_pin/x</source_name> <value_name>value</value_name> </assignment> or <assignment type="source"> <to>value</to> <source_name>NestedStruct_in</source_name> <value_name>sSimpleStruct.ui8Val</value_name> </assignment>

DDL Mapping Triggers

The DDL Mapping Filter will work either data triggered on each configured input pin or time triggered on the provided runner "periodic_trigger".

For each target within the mapping file it is possible to configure if it is data triggered or time triggered:

Data Triggered

Create sample on source updates: The targets sample is transmitted, if data were received on my_source_pin
<trigger type="source">

<source_name>my_source_pin</source_name>

</trigger>

adtf::streaming::ant::trigger
WRITER_TYPE & trigger(WRITER_TYPE &oWriter)
Global function template to trigger a writers sample stream manually.
Definition: streaming_functions.h:35

Create sample on source updates and a certain condition is set to true: The targets sample is transmitted, if data were received on NestedStruct_in AND the content of sSimpleStruct.ui8Val is equal than 3.
<trigger type="data">

<source_name>NestedStruct_in</source_name>

<value_name>sSimpleStruct.ui8Val</value_name>

<operator>equal</operator>

<value>3</value>

</trigger

Time Triggered

Create sample within a cyclic time: The targets sample is transmitted, if the time trigger on periodic_trigger is called and the last call time is more than 10 milliseconds ago.
<trigger type="periodic">

<time>10</time>

<unit>ms</unit>

</trigger>

ddl::dd::unit
@ unit
the unit is a unit (Unit)
Definition: dd_common_types.h:86

Time Strategies

To define which sample time is set to the resulting samples on outpin use the time_strategy of the trigger.

Additonally, it is possible to adjust "use sample time" or "use trigger time" on filters property "output_sample_time".

Trigger type	Time Strategy	output_sample_time	Used sample time on target
`source` or `data`	`trigger`	use sample time	target sample time is set to the sample time of the source sample this trigger belongs to
	`trigger`	use trigger time	target sample time is set to the trigger time of the trigger on inpin the sample was received
	`earliest` or `latest`	use sample time	target sample time is set to the earliest or latest sample time of the received source sample within all assignments
	`earliest` or `latest`	use trigger time	target sample time is set to the earliest or latest trigger time of the received source sample within all assignments
	`first_in_config`	use sample time	target sample time is always set to the sample time of the received source sample used at first position in the assignement list
	`first_in_config`	use trigger time	target sample time is always set to the trigger time of the received source sample used at first position in the assignement list
`periodic`	`trigger`	use sample time	target sample time is set to the trigger time of the trigger. A change to "use sample time" has no effect
	`trigger`	use trigger time	target sample time is set to the trigger time of the trigger.
	`earliest` or `latest`	use sample time	target sample time is set to the earliest or latest sample time of the received source sample within all assignments
	`earliest` or `latest`	use trigger time	target sample time is set to the earliest or latest trigger time of the received source sample within all assignments
	`first_in_config`	use sample time	target sample time is always set to the sample time of the received source sample used at first position in the assignement list
	`first_in_config`	use trigger time	target sample time is always set to the trigger time of the received source sample used at first position in the assignement list

See https://digitalwerk.gitlab.io/solutions/adtf_content/adtf_base/adtf_core/dev_essential/doc/html/md_doc_html_ddl_mapping_specification.html for a full specification on that.

Remarks: If no trigger is configured within a target, the corresponding targets sample is transmitted each time the connected Active Runner triggers.; It is not possible to set up the connections to the input pins of this filter as asynchronous connections.