Edge Data Routing (EventDefinition.xml)

The Senseforce Edge Solution implements a powerful data routing engine. Input data can be directed to one or many output plugins on a per data point level. The configuration file used to set up the data routing is the EventDefinition.xml and can be found here:

Console Application

[Edge Main Folder]/configs/configurations

These configs are only used for the Edge instance Luna.Console, executed directly from the [Edge Main Folder]. Click the "Service Application" tab above to check the location for Edge services.

Service Application

C:/ProgramData/Senseforce/Luna Data/[YourServiceName]/configurations

You can install several Luna service instances onto one device - for example to collect data of several machines from a local data collection device. Each service instance needs it's own set of configurations. When using the Senseforce Edge Service Installer, the default configurations are automatically installed for any service.

The EventDefinition.xml contains one or several Mapping-blocks. Each block defines one data routing, redirecting the defined input data points to the specified target output plugin. See the following example for further reference:

Sample configuration

The sample EventDefinition.xml defines two Mapping-blocks. The first block (line 6 to 41) redirects the defined datapoints Id, SawArea, and CutLength (see lines 29 to 31) to the plugin with the name Mqtt_senseforce (see line 13). Only data that are labelled with the IngressKey = OPCUA (see line 9) are processed. This is the default for the OPC UA plugin.

The second block (lines 38 to 66) processes the data points wind and oil, renames them to WindSpeed and OilTemperature (see lines 62 and 63), and directs them to an output-plugin called Sqlite_senseforce. Only data that are labelled with IngressKey = SIEMENS (see line 41) are processed. This is the default for the Siemens SINUMERIK plugin.

Both mapping-blocks are of type MDE10 (see lines 18 and 50). The type option has different meanings for different output plugins:

MQTT output plugin

The type-setting (see line 18) adds an additional type key to the transmitted JSON message. If the MQTT plugin is used to transmit data to the Senseforce cloud, the type value must match the "Key" of an Event Schema which is defined in the Senseforce platform Event Schema management tool.

Sqlite output plugin

The type setting is used to determine in which SQLITE table to insert the data. Setting the type to MDE10 requires a table called MDE10 to be present in the SQLITE table where the plugin is configured to insert into.

See the DataMappings.xml files of your input plugin configurations to check the IngressKey-labels of each plugin.

The name of the target plugin is defined in the appsettings.xml file. You can define one or several target plugins for each mapping block. This allows transmitting data to different data endpoints at the same time.

The notation $(someVariable) found in lines 29,30,31 and 62, 63 looks up incoming messages for keys someVariable and assigns the values of it to the name attribute of the mentioned line. Eg. line 62 looks for an incoming datapoint wind and assigns its value to a new key WindSpeed. This mechanism allows for effective data point renaming.

The latest versions of our SF Edge (V2.7.4.221+) additionally also have the posibility to define "dynamic topics". This feature allows to send data to multiple topics from one SF Edge instance. This is especially useful if you want to upload data from a central data source which includes information for multiple machines (like your ERP, or MES) but you want the data look like each of these machines has sent this information. This has several processing benefits on our plattform e.g. when filtering data for a specific machine.

To use this feature you have to specifiy the Topic attribute (see line 24). Here you can use a variable of your input data to define the topic (= the machine name) like shown in the example below. If this variable has missing values for some data in the input, the topic defined in the MQTT plugin is used as fallback. Please make sure that the "tenant/" is defined the same as in your MQTT plugin (see MQTT Plugin). If you need some pre- or postfix added to the names defined in the variable you are using as topic you can do this like shown in line 34.

TargetPlugin, IngressKey, Type, and Timestamp are mandatory fields of any mapping block. Note: The edge input plugins automatically creates a Timestamp-field for each message either from incoming data or from system time information.

<?xml version="1.0" encoding="utf-8" ?>
<MappingConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="https://senseforce.io/ Schemas/mappings.xsd" >
  <!-- The list of MQTT mappings below define the data routing and data mapping (renaming of variables)-->
  <Mappings>
    <Mapping>
	  <!-- Define for which input plugin this mapping should be applied -->
	  <!-- In your Input plugins "DataMappings.xml" a field "IngressKey" can be found. Match the Input plugins key with this key. -->
	  <IngressKey>OPCUA</IngressKey>
	  
	  <!-- Define, where this message should be directed to. You can also direct it to multiple output plugins -->
      <TargetPlugins>
        <TargetPlugin>Mqtt_senseforce</TargetPlugin>
      </TargetPlugins>
	  
	  <!-- Here you can define all message settings -->
      <Event>
        <Type>MDE10</Type> <!-- This is the name of this event. It has to match witch the event schema defined in Rocket. Otherwise the message will be categorised as invalid. -->
		    <Timestamp>$(Timestamp)</Timestamp> <!-- The timestamp which is added to the message (if you use $(Timestamp) the timestamp provided by the plugin will be used) -->
        <Id>$(GUID)</Id> <!-- Unique message ID -->

        <!-- Optionally you can override the Topic of your MQTT-Plugin by setting a topic-identifier as shown below. 
          If no Topic is defined, the default one from MqttSettings.xml is used -->
        <!-- <Topic>tenant/$(MachineNumber)</Topic> -->

        <!-- Place all your data information here. name="XXXX": XXXX must be defined in Senseforce Cloud (Event Schema Attribute Key); -->
        <!-- $(YYYY): YYYY are internal Edge variables which are directed from Input plugins. If you define a Variable Name in your Input plugins, these names must match with YYYY-->
        <Datas>
          <!--isMetaData: If set to true, messages which only contain isMetaData-objects are not transmitted-->
          <Data name="Id" isMetaData="true">$(Id)</Data>
          <Data name="SawArea">$(SawArea)</Data>
          <Data name="CutLength">$(cut)</Data>
          <!-- you can enter text before or after your variable, as demonstrated below -->
          <Data name="Material">my_$(Material)_in</Data>
          <!-- Wildcard notation for adding "any datapoint". Please use with caution-->
          <!-- <Data name="$(*)">$(*)</Data> --> 
        </Datas>
      </Event>
    </Mapping>
    
  </Mappings>
</MappingConfig>

Settings in detail

Setting	Description
IngressKey	Defines, which incoming data are relevant for this mapping block. Only data labelled with the specified IngressKey are processed as defined in the specific mapping. Check the DataMappings.xml file of each input plugin to look up the IngressKey-labels of each plugin. Defaults for the input plugins are: SQL-plugin: name of the table read from SQLITE-plugin: SQLITE OPC UA-plugin: OPCUA SIEMENS SINUMERIK-plugin: SIEMENS SIEMENS S7-plugin: S7Data REST-plugin: RestData
TargetPlugin	Set the name(s) of the plugin(s) the incoming data should be redirected. Check the appsettings.xml for how the plugins are named. Set one or more TargetPlugin-settings.
Type	For MQTT output plugin: adds an additional type key to the transmitted JSON message. If the MQTT plugin is used to transmit data to the Senseforce cloud, the type value must match the "Key" of an Event Schema which is defined in the Senseforce platform Event. For SQLITE output plugin: used to determine in which SQLITE table to insert the data. Setting the type to MDE10 requires a table called MDE10 to be present in the SQLITE table where the plugin is configured to insert into.
Timestamp	Required timestamp information. Each input plugin automatically creates a timestamp for incoming messages. Either from the data itself or from the system time information. The default setting is appropriated for most use cases.
Id	Optional parameter. Allows adding an additional key called Id to the resulting JSON message or SQLITE insert query. If this setting is set to $(GUID) a randomly generated GUID is set as Id, which is helpful for duplicate detection. The default value is appropriate for most use cases.
Metas	deprecated
Data	Each Data-tag consists of a name attribute and a value. Name defines, how the corresponding data point is named in the resulting message or SQLITE insert query. The value defines the value of the datapoint. The notation $(someVariable) found in lines 29,30,31 and 62, 63 looks up incoming messages for keys someVariable and assigns the values of it to the name attribute of the mentioned line. Eg. line 62 looks for an incoming datapoint wind and assigns its value to a new key WindSpeed. This mechanism allows for effective data point renaming. Note: If the mapping is used to redirect data to an MQTT plugin that connects to the Senseforce cloud, each name attribute's value must correlate with one attribute key of the Event Schema defined in a type.
isMetaData	One or more Data-tags might have an attribute isMetadata = true. If the attribute is set to true, incoming messages which only contain values marked with isMetaData = true are thrown away.
$(*) (Wildcard notation)	Use the wildcard notation in both a Data name attribute and the Data value to automatically add ALL datapoints of an incoming message to the mapping.

2KB

EventDefinition.xml