Configuration Parameters¶
An ECI Protocol Bridge configuration file is used to define the plug-ins that are loaded and their runtime parameters. This document will describe the list of top-level configuration parameters that are common to all plug-ins.
A configuration files uses the YAML format. It is important that the file is properly formatted. Please be aware that all parameters are case-sensitive and proper formatting and indentation is critical. Further details of YAML formatting is outside the scope of this document. Many very good help guides can be found on the Internet which provide details about YAML file formatting.
Note: Any unknown parameters in a configuration file will simply be ignored.
Table of Contents
common: Top-Level Parameters¶
There are two top-level parameters, “settings” and “plugins”.
common: settings¶
Every configuration file should start with a “settings” section. There are three options available for this section, “log-level”, “log-latency” and “timeout-sec”.
common: log-level¶
Example:
settings:
log-level: LOG_DEBUG
The “log-level” 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. Although document here, it is not recommended that this value be used since it outputs only error messages. Without any context information diagnosing any problems that may occur would be extremely difficult.
LOG_WARNING
This level outputs errors and warnings. It is also not recommended.
LOG_INFO
This level outputs errors, warnings and informational messages. This is the least detailed output level that can be recommended after you have confirmed operation to be stable. Please keep in mind however that diagnosing any problems may still be difficult.
LOG_DEBUG
This is the recommended level. It outputs all the previous levels and includes details that are very useful in diagnosing problems.
LOG_TRACE
This level outputs much more detail information than all previous levels. This level is very useful in diagnosing difficult problems. It is recommended that this level be used only temporarily while actively diagnosing a problem since it will affect performance.
LOG_VERBOSE
This level outputs a very great deal of information and is only recommended for developers actively debugging a problem.
common: log-latency¶
Example:
settings:
log-latency: 0
The “log-latency” is a special parameter used by the software development team that is not intended for general use. It controls whether latency measurements are output to the console and what is measured. The value must be a valid integer between 0 and 3. Turning this option on will affect performance so only use it when actively measuring latency. Only the plg-sim and plg-opcua-rt plug-ins are enabled to participate in latency measurements.
0
This level turns off all latency measurements
1
This level turns on end-to-end latency measurements. It must be used with one instance of plg-sim as the originating data source and another instance of plg-sim to display the latency measurement.
2
This level turns on internal data movement latency measurements. It only works with the plg-opcua-rt plug-in.
3
This level turns on both end-to-end and internal data movement latency measurements.
common: timeout-sec¶
The “timeout-sec” section is for advanced configurations and is typically unnecessary. Each child parameter controls whether the number of seconds that each of the specified startup and shutdown thread is allowed before terminating with an error. The value must be a valid integer between 1 and 600.
plg-initialize - configures the number of seconds allowed for the thread spawned to launch the plg_initialize() callback for each specified plug-in
plg-connect - configures the number of seconds allowed for the thread spawned to launch the plg_connect() callback for each specified plug-in
plg-stop-req - configures the number of seconds allowed for the thread spawned to launch the plg_stop() callback for each specified plug-in
plg-stop-exec - configures the number of seconds allowed for the for each specified plug-in to actually stop executing
plg-disconnect - configures the number of seconds allowed for the thread spawned to launch the plg_disconnect() callback for each specified plug-in
plg-terminate - configures the number of seconds allowed for the thread spawned to launch the plg_terminate() callback for each specified plug-in
Example:
settings:
timeout-sec:
plg-initialize: 2
plg-connect: 6
plg-stop-req: 1
plg-stop-exec: 5
plg-disconnect: 5
plg-terminate: 2
common: plugins¶
The “plugins” section is the only other top-level setting. It is a YAML list and should include an entry for each plug-in that will be instantiated.
Example:
plugins:
-
common: Plug-in Parameters¶
There are four “plugins” parameters, “plugin-id”, “filename”, “dataset” and “configuration”, all of which are required. The first three parameters contain standard content and are common for all plug-ins. The contents of “configuration” parameter is unique for each plug-in and documented separately.
common: plugin-id¶
The “plugin-id” parameter is a unique name/identifier assigned to the plug-in. Do not use the same plugin-id more than once.
Example:
plugin-id: plg-sim
common: filename¶
The “filename” 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 information.
Example:
filename: libplgsim.so
common: dataset¶
Having a proper understanding the “dataset” parameter is crucial to defining a proper configuration. The “dataset” parameter is a YAML list.
Example:
dataset:
-
A dataset is a structured collection of data. It represents the data abstraction layer within the Protocol Bridge. It declares all the attributes for the data itself and how that data is exchanged between plug-ins. Data is always exchanged as an entire dataset, never as individual data fields.
A dataset should be configured to match the input format of the data from a data source or application. The number of fields, their sequence and their data type are all important.
It may be helpful to think of a dataset as a storage unit similar to a database table. Much like a database table contains data fields, a dataset defines a set of fields and datatypes.
Beyond that similarly however, recognize that a dataset is much different from a database table. A dataset defines the structure for dynamically allocated memory that temporary holds data values as they are passed between various components within the application, there is no persistent storage of that data.
There are several “dataset” parameters, “dataset-id”, “cache-entries”, “listener-dataset-id”, “direct-xmit” and “dataset-fields”.
common: dataset-id¶
The “dataset-id” parameter is required and represents a unique name/identifier assigned to the dataset. Do not use the same dataset-id more than once.
Example:
dataset-id: sim-ds
common: dataset-fields¶
The “dataset-fields” parameter is required within a dataset and defines the fields that it contains. The “dataset-fields” parameter is a YAML list.
If this parameter is specified the listener-dataset-id parameter should not be.
Example:
dataset-fields:
-
There are two “dataset-fields” parameters, “datafld-id” and “datatype”.
common: datafld-id¶
The “datafld-id” parameter is required within “dataset-fields” and represents a unique name/identifier assigned to the dataset field. Do not use the same datafld-id more than once.
Example:
datafld-id: fld1
common: datatype¶
The “datatype” parameter is required within “dataset-fields” and represents datatype of the dataset field.
Example:
datatype: float
The valid datatypes are:
bool (a.k.a. boolean)
int8 (a.k.a. sbyte, char)
uint8 (a.k.a. byte)
int16 (a.k.a. short)
uint16
int32 (a.k.a. int, integer, number)
uint32
int64 (a.k.a. long)
uint64
float (a.k.a. float32, real)
double (a.k.a. float64)
string (a.k.a. cstring)
binary
common: length¶
The “length” parameter is optionally used to specify a maximum field length when the “datatype” is either string or binary. Each plug-in individually decides whether or not it will use this length parameter.
Example:
length: 80
common: listener-dataset-id¶
The “listener-dataset-id” parameter is optional and 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 another plug-in that is producing or “broadcasting” that data.
Any dataset that specified this listener parameter should not specified its own set of dataset-fields since these will be inherited from the broadcaster dataset. Any dataset fields specified for a listener will be ignored.
Do not attempt to “chain” together dataset listeners. In other words, a dataset listener should not reference a dataset that is itself a listener. This is invalid and will result in the listener parameter being ignored. Listeners should always reference the original broadcast dataset source.
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.
common: configuration¶
The “configuration” parameter is required and provides plug-in specific configuration parameters. There are only two parameters available that are common to all plug-ins, “dx-core-affinity” and “dx-sched-priority”. All remaining parameters are unique for each individual plug-in and the details are out of scope for this document. Locate the documentation for each specific plug-in for further details about its parameters.
Example:
configuration:
common: dx-core-affinity¶
The “dx-core-affinity” parameter is optional and represents the CPU core to assign 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, 1.
Example:
dx-core-affinity: 1
common: dx-sched-priority¶
The “dx-sched-priority” parameter is optional and represents the priority assign to the real-time blocking read thread for the listener. Some plug-ins also use this value for their real-time broadcast thread.
Although this value can technically be an integer from 1 to 99, the guideline is that Protocol Bridge plug-in use priority values in the range between 50 and 75. All real-time threads priorities are relative to each other. A higher priority thread is able to preempt a thread with a lower value. All existing plug-in have been designed to execute most effectively within this priority range.
By default this value is set to, 60.
Example:
dx-sched-priority: 60
common: Complete Configuration File Example¶
Below is an example of a full configuration file that instantiates two plug-ins and exchanges data between first plugin which acts as a broadcaster and a second plug-in which acts as a listener and receives that data.
Every parameter in this example, except for the contents of the “configuration” parameter which is plug-in specific, has been covered in this document.
Make a note of how the file is structured. Proper formatting is an absolute requirement. 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
log-latency: 1
timeout-sec:
plg-initialize: 2
plg-connect: 6
plg-stop-req: 1
plg-stop-exec: 5
plg-disconnect: 5
plg-terminate: 2
plugins:
-
plugin-id: plg-sim
filename: libplgsim.so
dataset:
-
dataset-id: sim-ds
dataset-fields:
-
datafld-id: fld-int64
datatype: int64
-
datafld-id: fld-uint64
datatype: uint64
-
datafld-id: fld-uint32
datatype: uint32
configuration:
interval-us: 500000
dx-core-affinity: 1
dx-sched-priority: 60
-
plugin-id: plg-sim2
filename: libplgsim.so
dataset:
-
dataset-id: sim-ds2
listener-dataset-id: sim-ds
configuration:
dx-core-affinity: 1
dx-sched-priority: 60