Intel® Edge Controls Protocol Bridge Microservice#

The purpose of the Intel® Edge Controls Protocol Bridge is to provide a real-time deterministic data pipeline. This application uses a plug-in design and dynamically loads and configures the plug-in shared libraries. A configuration file is used to define the plug-ins that are loaded and their runtime parameters. This section will describe the top-level configuration parameters common to all plug-ins.

A configuration file uses the YAML format. All elements and attributes are case-sensitive; so, make sure that the files are properly formatted. For more details on YAML formatting, see the various guides on the Internet.

Attention

This plug-in assigns CPU affinity and requires elevated permissions to run correctly. Make sure that you have elevated permissions to execute the EC Protocol Bridge.

Note: Any unknown parameters in a configuration file will simply be ignored.

EC Bridge - Application Command-line Parameters#

The EC Bridge application takes a single command-line parameter - the name of the configuration file to load. Note that when executing the application using sudo, you might need to specify the LD_LIBRARY_PATH environment variable if it is not already set for root. Plug-ins (shared libraries) might not load, if this environment variable is not set.

Example:

sudo -E LD_LIBRARY_PATH=/usr/local/lib/ ./ec-bridge config.yaml

To redirect the console output to a file, modify the command as follows:

sudo -E LD_LIBRARY_PATH=/usr/local/lib/ ./ec-bridge config.yaml 2>&1 | tee ec-bridge.log

You can also specify an optional environment variable, which can be used for regression testing as it automatically terminates the application after a specified duration. Using the TIMEOUT feature combined with the output file redirection, a sequence of commands may be chained together to execute several use case configuration files one after the other.

The following example executes and automatically terminates the application after 8 seconds:

sudo su
export LD_LIBRARY_PATH=/usr/local/lib/
export EC_BRIDGE_TEST_TIMEOUT=8
./ec-bridge config1.yaml 2>&1 | tee ec-bridge.log
./ec-bridge config2.yaml 2>&1 | tee -a ec-bridge.log
./ec-bridge config3.yaml 2>&1 | tee -a ec-bridge.log

EC Bridge - Settings#

Every configuration file should start with a “settings” section. Three options available for this section: log-level, log-latency, and timeout-sec.

Example:

settings:
  -

settings: log-level#

This parameter controls the amount of logging information that is output to the console and log file. The possible values include:

  • LOG_ERROR

This level outputs the least amount of information; only errors are printed. It is not recommended to use this value as it outputs only error messages. Without any context information, it would be extremely difficult to diagnose problems that might occur.

  • LOG_WARNING

This level outputs errors and warnings. This level is also not recommended.

  • LOG_INFO

This level outputs errors, warnings, and informational messages. This is the least detailed output level that is recommended after you have confirmed that the operation in stable. However, it might still be difficult to diagnose any problems.

  • LOG_DEBUG

This level is recommended during development. This level outputs all previous levels and includes details that are very useful in diagnosing problems.

  • LOG_TRACE

This level outputs detailed information when compared with the previous levels. This level is very useful in diagnosing difficult problems. This level affects performance, so it is recommended to use this level only temporarily while actively diagnosing a problem.

  • LOG_VERBOSE

This level outputs detailed information and is only recommended for developers actively debugging a problem

Example:

log-level: LOG_DEBUG

settings: log-latency#

This parameter is used by the software development team and is not intended for general use. This parameter determines whether latency measurements are output to the console and controls what is being measured. The value must be a valid integer, either 0 or 1. Turning this option ON will affect performance; so use this parameter only when actively measuring latency. Only the Data Simulator and OPC UA plug-ins are enabled to participate in latency measurements.

  • 0 - This level turns OFF latency measurements

  • 1 - This level turns ON latency measurements

Example:

log-latency: 0

settings: log-threading#

This parameter determines whether the output logged to the console must use a separate non-RT thread. The value must be a valid boolean. Typically, this value should be turned ON, which instructs the logger to use a separate non-RT thread that buffers data before it is output to the console; this is the default behavior. Turning this option OFF may affect deterministic performance, so use this option only when actively debugging an issue and it is important to output the log to the console.

  • 0 - This level turns OFF threaded logging (all options: n|N|no|No|NO|0|f|F|false|False|FALSE)

  • 1 - This level turns ON threaded logging (all options: y|Y|yes|Yes|YES|1|t|T|true|True|TRUE)

Example:

log-threading: 1

settings: timeout-sec#

This section is for advanced configurations and is typically unnecessary. Each child parameter controls the duration (in seconds) that each of the specified startup and shutdown thread is allowed to run before terminating with an error. The value must be a valid integer between 1 and 600. The default for each is 30 seconds.

  • plg-initialize configures the duration (in seconds) allowed for the thread spawned to launch the plg_initialize() callback for each specified plug-in.

  • plg-stop-req configures the duration (in seconds) allowed for the thread spawned to launch the plg_stop() callback for each specified plug-in.

  • plg-stop-exec configures the duration (in seconds) allowed for the thread spawned to launch the plg_stop() callback for each specified plug-in.

  • plg-terminate configures the duration (in seconds) allowed for the thread spawned to launch the plg_terminate() callback for each specified plug-in.

Example:

timeout-sec:
  plg-initialize: 10
  plg-stop-req: 5
  plg-stop-exec: 5
  plg-terminate: 5

settings: sync-start-delay-ms#

This parameter is used to synchronize the timing loop of plug-ins by providing a single clock. The plug-ins will wait for this period before processing. The value must be a valid integer. By default, a synchronized clock is not used for starting a process.

Example:

sync-start-delay-ms: 3000

EC Bridge - Plug-in Configuration Parameters#

It is a YAML list and should include an entry for each plug-in that will be instantiated.

Example:

plugins:
  -

There are four mandatory parameters: plugin-id, filename, dataset, and configuration. The first three parameters contain standard content and are common for all plug-ins. The contents of the configuration parameter is unique for each plug-in and is documented separately.

ec-bridge: plugin-id#

This parameter is a unique name or identifier assigned to the plug-in. Do not use the same plugin-id repeatedly.

Example:

plugin-id: plg-sim

ec-bridge: filename#

This parameter is the name of the plug-in’s shared library file. Specify only the name of the library file (the libxxx.so file) and do not include any path.

Example:

filename: libplgsim.so

ec-bridge: dataset#

A dataset is a structured collection of data. It represents the data abstraction layer within the Protocol Bridge. It declares all attributes for the data and describes the exchange of data between plug-ins. Data is always exchanged as an entire dataset, and not as individual data fields.

A dataset should be configured to match with the input format of the data from a data source or application. The number of fields, their sequence, and their data types are important.

Consider the dataset as a storage unit similar to a database table. Similar to a database containing data fields, a dataset defines a set of fields and data types. The difference between a dataset and a database table is that there is no persistent storage of data in a dataset. A dataset defines the structure for a dynamically allocated memory that temporarily holds data values while they are passed between plug-ins.

The dataset parameters include dataset-id, listener-dataset-id, and dataset-fields. It is important to understand the dataset parameter for defining a proper configuration. The dataset parameter is a YAML list.

Example:

  dataset:
-

dataset: dataset-id#

This mandatory parameter represents a unique name or identifier assigned to the dataset. Do not use the same dataset-id repeatedly.

Example:

dataset-id: sim-ds

dataset: dataset-fields#

This mandatory parameter, within a dataset, defines the fields that the dataset contains. The dataset-fields parameter is a YAML list.

If you specify this parameter, then do not specify the listener-dataset-id parameter.

Example:

dataset-fields:
  -

There are two dataset-fields parameters: datafld-id and datatype.

dataset fields: datafld-id#

This mandatory parameter represents a unique name or identifier assigned to the dataset field. Do not use the same datafld-id repeatedly.

Example:

datafld-id: fld1
dataset fields: datatype#

This mandatory parameter represents the datatype of the dataset field.

Example:

datatype: float

The basic datatypes are:

  • bool (boolean)

  • int8 (sbyte, char)

  • uint8 (byte)

  • int16 (short)

  • uint16

  • int32 (int, integer, number)

  • uint32

  • int64 (long)

  • uint64

  • float32 (float, real)

  • float64 (double)

  • float128

  • string (cstring)

  • binary (blob)

The extended datatypes are:

  • array-bool

  • array-int8

  • array-uint8

  • array-int16

  • array-uint16

  • array-int32

  • array-uint32

  • array-int64

  • array-uint64

  • array-float32

  • array-float64

  • array-float128

  • array-string

  • array-binary

Attention

Only a few plug-ins support extended datatypes. Currently, only the MQTT and Data Simulator plug-ins support these array datatypes.

dataset fields: listener-dataset-id#

This optional parameter establishes a broadcast/listener relationship between two plug-ins. A plug-in that wants to consume or “listen” to the data produced by another plug-in will declare that it is “listening” to the dataset of the plug-in that is producing or “broadcasting” that data.

Any dataset that specifies this listener parameter should not specify its own set of dataset fields, as these fields will be inherited from the broadcaster dataset. Any dataset field specified for a listener will be ignored.

Example:

listener-dataset-id: sim-ds

A broadcast plug-in will make its data available to a listener plug-in through a pointer to its dataset in the listener’s real-time blocking read thread.

dataset fields: reference-dataset-id#

This optional parameter is used to avoid the need to repeat an exact dataset field definition that is already been specified in another plug-in. This can reduce the size of a configuration file and simplify maintenance when dataset field lists change.

Example:

reference-dataset-id: sim-ds

ec-bridge: configuration#

This mandatory parameter provides plug-in-specific configuration parameters. Two parameters are common to all plug-ins: dx-core-affinity and dx-sched-priority. The remaining parameters are unique for each plug-in and the details are not in the scope of this document. For more details on the parameters, see the plug-in-specific documentation.

Example:

configuration:

configuration: dx-core-affinity#

This optional parameter represents the CPU core to be assigned to the real-time blocking read thread for the listener. Some plug-ins also use this value for their real-time broadcast thread. This value should be an integer from 0 to <number of available cores> - 1. When designing a deterministic plug-in, use a core other than 0 for real-time threads.

By default, this value is set to 0.

Example:

dx-core-affinity: 1

configuration: dx-sched-priority#

This optional parameter represents the priority to be assigned to the real-time blocking read thread of the listener. Some plug-ins also use this value for their real-time broadcast thread.

Although this value can be an integer from 1 to 99, it is recommended to use priority values in the range between 50 and 75. All real-time thread priorities are relative to each other. A higher priority thread is able to preempt a thread with a lower value. All existing plug-ins have been designed to execute most effectively within this priority range.

By default, this value is set to 60.

Example:

dx-sched-priority: 60

EC Bridge - Putting it all together#

Here is an example of a simple configuration file that instantiates two plug-ins and exchanges data between the first plug-in that acts as a broadcaster and a second plug-in that acts as a listener and receives that data.

Note that all parameters in this example, except for the contents of the configuration parameter and its children which are plug-in specific, are explained in this section.

Note the structure of the file. Proper formatting is mandatory. Notice the consistent indentation and how each YAML list is specified. Invalid formatting will either confuse the parser or cause an error.

settings:
  log-level: LOG_DEBUG
plugins:
  -
    plugin-id: plg-sim
    filename: libplgsim.so
    dataset:
      -
        dataset-id: sim-ds
        dataset-fields:
          -
            datafld-id: fld-uint32
            datatype: uint32
          -
            datafld-id: fld-float
            datatype: float
          -
            datafld-id: fld-string
            datatype: string
    configuration:
      interval-us: 500000
  -
    plugin-id: plg-sim2
    filename: libplgsim.so
    dataset:
      -
        dataset-id: sim-ds2
        listener-dataset-id: sim-ds
    configuration: