EtherCAT Protocol Adapter
This section presents the capabilities and configuration options of the EtherCAT Protocol Adapter, which translates the EtherCAT communication protocol into objects understandable by the Gateway Agent.
For a step-by-step guide on how to install the EtherCAT Protocol Adapter, see the Installation Guide.
Configuring the EtherCAT Protocol Adapter
There are three types of configuration files of the EtherCAT Protocol Adapter:
Deployment configuration file - Configuration of the MQTT connection, PMQ connection and health monitoring.
Application configuration file - Configuration of the EtherCAT cycle time, network interface, reporting prefix, and devices.
Slave configuration file - Data mapping configuration of individual slaves.
When you modify the EtherCAT Protocol Adapter configuration, restart the adapter to apply the changes by means of the following command:
systemctl restart gwa-ethercat-adapter-cpp
The adapter configuration is then updated.
For an example of the EtherCAT Protocol Adapter configuration files, see here.
For more information on the EtherCat protocol, see the EtherCat documentation.
Deployment Configuration File
The deployment configuration file of the EtherCAT Protocol Adapter is located at:
/etc/relayr/gwa-ethercat-adapter-cpp/gwa-ethercat-adapter-config.json
To modify the file, edit it in a text editor.
The following configuration settings are available:
transport
- Communication channel used by the adapter. Available options:mqtt
orpmq
. By default,mqtt
.mqtt_connection
- Connection settings of the MQTT message broker:
Configuration Setting | Description | Default Value |
---|---|---|
host | IP address of the MQTT message broker. | localhost |
port | Port number for connecting to the MQTT broker. | 1883 |
keepalive | Keepalive value of the MQTT connection. | 20 |
max_inflight_messages | Maximum number of QoS 1 or 2 messages that can be in the process of being transmitted simultaneously. This includes messages currently going through handshakes and messages that are being retried. If set to 1 , it guarantees an in-order delivery of messages. | 100 |
qos_levels | Quality of Service level for each traffic type. | measurements: 0 , alerts: 1 . configuration: 1 , metadata: 1 |
health_monitor
- Health monitoring settings:
Configuration Setting | Description | Default Value |
---|---|---|
heartbeat_interval | Time interval at which the periodic heartbeat messages are sent, given in seconds. | 60 |
pmq_connection
- Configuration of the High Speed Bus (PMQ) connection. Configure this section to use thepmq
transport
:
Configuration Setting | Description | Default Value |
---|---|---|
output_queues | List of output PMQ queues, where the adapter reports all data, except for health monitoring messages, which are always reported via MQTT. Queue names must begin with / . | ["/ethercat_out_queue"] |
input_queues | List of PMQ queues to monitor for inbound messages, e.g. configuration update tasks. Queue names must begin with / . | ["/ethercat_in_queue"] |
message_size | Maximum size of a PMQ message, given in bytes. | 8192 |
message_count | Maximum number of messages in a PMQ queue. | 10 |
For an example of the deployment configuration file, see here.
Application Configuration File
The application configuration file of the EtherCAT Protocol Adapter is located at:
/etc/relayr/gwa-ethercat-adapter-cpp/gwa-ethercat-adapter-application-config.json
This file should contain a JSON object with the following properties:
Configuration Setting | Description | Example of Value |
---|---|---|
cycleTime_us | Integer. Target EtherCAT data exchange cycle interval in microseconds. | 4000 |
networkInterface | String. Ethernet interface of the EtherCAT network. | eth1 |
networkRescanDelay_s | Time interval, given in seconds, at which the adapter tries to re-initialize the network if no devices are connected to the gateway. This setting prevents the adapter from restarting or reporting an invalid configuration error when no devices are connected. By default, 60 seconds. To avoid unnecessary logs, unsuccessful re-initialization attempts are logged only once per 100 attempts, e.g. if set to 60 seconds, a log is produced every 100 minutes. | 60 |
custom_prefix | Optional. String. Prefix used to create reporting topics. By default, v1/sb . The custom_prefix enables publishing data either to a custom MQTT topic for a local data processing, or directly to the northbound interface. It is a global setting that refers to data retrieved from all devices. | v1/sb |
slave_configs_dir_path | Optional. String. Path to the directory with slave configuration files. By default, /slaveConfigs . | slaveConfigs |
internal_buffers.count | The internal_buffers JSON object defines a data exchange between the processing thread and the communication thread (real-time). The count setting defines how many buffers are created when the application starts. Note that if this value is too big, it may unnecessarily increase the memory usage and lower the performance. By default, 8192 . | 8192 |
stability_monitoring | JSON object configuring the system that monitors the stability of the communication thread (real-time). The available settings define when to log information about the thread stability. See below for more information. | |
devices | JSON array of objects specifying the configuration of devices with their DIDs, measurements, metadata, and slave configuration files. See below for more information. |
Configuring the Stability Monitoring
In the stability_monitoring
section of the application configuration file, you can configure when to log information about the communication thread stability.
The following settings are available:
Configuration Setting | Description |
---|---|
single_deviation_log_threshold | Deviation threshold for a single cycle. E.g. if set to 0.2 for a cycle that lasts 4000 microseconds, the deviation above 4800 or below 3200 is logged. |
average_deviation_log_threshold | Deviation threshold calculated as the average from a number of cycles specified in the average_calculation_span setting. If the standard deviation is greater than the threshold, the information is logged. |
average_calculation_span | Defines how many cycles are included in the average calculation. |
Example:
"stability_monitoring": {
"single_deviation_log_threshold": 0.2,
"average_deviation_log_threshold": 0.05,
"average_calculation_span": 1000
}
Configuring Devices
Objects in the devices
array should have the following properties:
Configuration Setting | Description |
---|---|
slave_id | Integer. Must be greater than 0. Slave number in the network. Alternatively, you can provide the device's serial_number or use the same_named_slaves_before option. See here for an example. |
serial_number | 32-bit unsigned integer. Must be greater than 0. Unique device serial number that can identify the device instead of its slave_id . If you provide both slave_id and serial_number , the adapter verifies if both values are correct. See here for an example. |
same_named_slaves_before | Optional. Value of the unsigned type, used to address devices, based on their type. The 0 value means that it is the first device of a given type. When you use this option, you must also provide the manufacturer_name , where you specify the device type. When you also configure the slave_id or the serial_number , the adapter ignores the same_named_slaves_before option. See here for an example. |
did | Optional. String. Device ID, used in the topic. It is required if the metadata doesn't contain an entry with "id":"did" . |
config_file | String. Name of the slave configuration file associated with the device. Leave it empty if no configuration is needed. |
measurements | JSON array of JSON objects specifying the device's measurements. See below for more information. |
custom_prefix | Optional. String. It overrides the global prefix in the topic creation for this device. It enables publishing data either to a custom MQTT topic for a local data processing, or directly to the Northbound Interface. |
manufacturer_name | Optional. String. Name of the device as given by its manufacturer, used to verify the configuration. You must configure this option if you want to address a device, based on the same_named_slaves_before option. |
metadata | Optional. JSON array of JSON objects specifying the device's metadata. See below for more information. |
Addressing Devices
The EtherCAT Protocol Adapter can identify slave devices in the network in several different ways. To address a device, you can use the following options in the devices
section of the application configuration file:
Option 1:
slave_id: 5
It means that it is the fifth slave device in the network.
Option 2:
"manufacturer_name": "EK1324,
"same_named_slaves_before": 2
It means that it is the third device in the network that has the EK1324
manufacturer name. If you also provide the slave_id
or serial_number
, the adapter ignores the same_named_slaves_before
option.
The picture below shows how to address devices, using the
slave_ID
option and thesame_named_slaves_before
option. The manufacturer names are given inside the rectangles.
Option 3:
"serial_number": 12324
It means that the adapter identifies a device, based on its serial number, instead of its slave_id
. If you provide both slave_id
and serial_number
, the adapter verifies if both values are correct.
Configuring Metadata
Objects in the metadata
array should have the following properties:
Configuration Setting | Description |
---|---|
id | String. Metadata identifier, used in the topic creation. |
value | Any JSON type. Value to report. |
custom_prefix | Optional. String. It overrides the global device prefix in the topic creation for this metadata. It enables publishing data either to a custom MQTT topic for a local data processing, or directly to the Northbound Interface. |
Example:
"metadata": [
{
"id": "did",
"value": "f33c6bah-b31e-4f5a-964h-13a935a8b25f"
}
]
Configuring Measurements
The
measurements
array must contain a matching entry for eachcomplexMeasurement
command given in the slave configuration files to be valid. Entries are matched based on theid
field value.
Objects in the measurements
array should have the following properties:
Configuration Setting | Description |
---|---|
id | String. ID of the measurement used to internally link with the input from the slave configuration file. |
reported_id | Optional. String. This ID is used when reporting the measurement. If not present, the value of id is used instead. |
reporting_interval | Integer. Used only in a simple measurement. It specifies a reporting interval as a number of master cycles. The value 1 means the adapter reports every cycle, the value 2 - every second cycle, and so on. |
complex | JSON object. It contains a complex measurement configuration. It specifies how many data samples a complex measurement contains and a collection_interval . For more information, see the Configuring Complex Measurements section. |
pre_send_processing | Optional. JSON object that contains parameters for processing prior to sending. Possible options described below. |
custom_prefix | Optional. String. It overrides the device prefix in the topic creation for this measurement. It enables publishing data either to a custom MQTT topic for a local data processing, or directly to the Northbound Interface. |
Configuring the Pre-processing of Measurements
In the optional pre_send_processing
section of the measurements configuration, you can configure the data processing that the adapter performs before sending the data.
Linear transformation is currently the only available data processing model (
y = x * a + b
).
The following configuration options are available:
Configuration Setting | Description |
---|---|
output_type | String. The value will be cast to this type before processing possible values. One of: float , integer , unsigned . |
gain | Optional. Number. The value of a in the transform model. By default, 1 (1.0 ). |
offset | Optional. Number. The value of b in the transform model. By default, 0 (0.0 ). |
A number
can be one of following types: integer
, unsiged
or floating point
.
Known issue: In the current version, either
gain
oroffset
must be present. You can use neutral values:1
or1.0
forgain
, or0
or0.0
foroffset
.
If the values of
gain
andoffset
are of different types, the one belonging to the subset domain is changed to the superset type` i.e. if one of the values is floating point, the other one is cast to floating point (R⊃Z⊃N).
Example:
"pre_send_processing": {
"output_type": "float",
"gain": 10.5,
"offset": -5
}
Configuring Complex Measurements
A complex measurement is a batch of measurement data, in which several samples of collected data values are published as a single message.
Complex measurements can be consumed by the Rule Engine and the GWA Analytics for further data processing and can be stored in the Storage Service. The Cloud Adapter supports publishing complex measurements to the relayr Cloud.
To configure a complex measurement, add the complex
section to the measurement configuration with the following settings:
Configuration Setting | Description |
---|---|
samples | Number of collected data samples in a complex measurement. |
collection_interval | Time interval, given in seconds, at which the adapter starts to acquire data for a complex measurement. It must be greater than 0 . |
Example:
"measurements": [
{
"id": "voltage_phase_1",
"reported_id": "Ch1VoltageExample",
"complex": {
"samples": 7500,
"collection_interval": 10
}
}
Slave Configuration Files
A slave configuration file contains settings specific to a given device. The adapter processes the file at runtime, after the slave is found in the network.
The adapter identifies configuration files by their filenames given in the application configuration and matches them using the
slave_id
. See theconfig_file
andslave_id
settings in thedevices
array.
The files are processed line by line. Each line should contain a single command.
The following commands are available:
- write - this command enables sending CAN over EtherCAT(COE) requests to the slave. Most importantly, it enables the configuration of synchronization managers, which are used to exchange data over the EtherCAT protocol.
Each write command requires 4 parameters:
- Target object index (16 bit hex).
- Sub-index (8 bit hex).
- Payload bit write size (decimal, the maximum payload size is 64 bits).
- Payload (hex size should match the previous argument) The payload size is determined by the target object. You can find it in the slave's documentation.
When you change the Sync Manager's (SM) configuration, you should include consecutive sub-indexes, without leaving any empty spaces, to map data correctly.
Example:
write 0x1C13 0x01 16 0x1A00
write 0x1C13 0x02 16 0x1A0F
write 0x1C13 0x03 16 0x1A21
- inputBitSize - used to double check the processing configuration. It is compared with the computed processing map size, composed based on other commands. It requires a single argument - the expected processing input map size (decimal).
Example:
inputBitSize 9760
- align - used to ignore parts of incoming data, requires a single argument - a number of ignored bits (hex).
Example:
align 0x02
- alert - specifies data that should trigger alerts, right now only reported in logs.
The alert command requires 4 arguments:
- Type (string). Currently, only
bool
is supported. - Bit size (hex).
- Alert ID - (string) currently used in logs. In the future, it will be used to link with the reporting details in the application configuration.
- Logic type - specifies if the alert is triggered when the value changes to
1
(positive
) or when the value changes to0
(negative
).
Example:
alert bool 0x01 Ch1CUnderRange positive
- measurement/complexMeasurement - used to create a measurement/complex measurement entry in the slave's input processing map.
- Data type (string) - specifies how data should be interpreted. Currently, the following types are supported:
integer
,unsigned
,float
. - Bit data size (hex) - a number of bits to load and interpret. Limitation: sizes that are not the multiple of a byte probably won't work correctly. In case of
float
, attempting to use sizes different from native will fail. - Reported ID (string) - used to link with an entry in the application configuration that specifies the reporting details.
The application configuration must contain an entry with a matching ID to be valid.
- Number of samples (decimal) - complex measurement only. It specifies how many samples are to be received. This value must match the configuration of oversampling on the slave side. It doesn't specify how many samples are put together in a single measurement message. The reporting details are specified in the application configuration.
Example:
measurement integer 0x10 surface_temperature
complexMeasurement integer 0x10 Ch1VoltageSamples 100
- Comments must start with
"//"
(C++ style line comments). They are allowed both at the end of a line, after a command, and in separate lines.
Example:
// Chanel 1 voltage
inputBitSize 9760 // Input data mapping for oversampling factor 100
Examples of Configuration Files
Deployment Configuration File
{
"transport": "mqtt",
"mqtt_connection": {
"host": "localhost",
"port": 1883,
"keepalive": 20,
"max_inflight_messages": 100,
"qos_levels": {
"measurements": 0,
"alerts": 1,
"configuration": 1,
"metadata": 1
}
},
"health_monitor": {
"heartbeat_interval": 60
},
"pmq_connection":
{
"output_queues": ["/ethercat_out_queue"],
"input_queues": ["/ethercat_in_queue"],
"message_size": 8192,
"message_count": 10
}
}
Application Configuration File
{
"cycleTime_us": 4000,
"networkInterface": "eth1",
"networkRescanDelay_s": 60,
"custom_prefix": "v1/sb",
"slave_configs_dir_path": "slaveConfigs",
"internal_buffers": {
"count": 8192
},
"stability_monitoring": {
"single_deviation_log_threshold": 0.2,
"average_deviation_log_threshold": 0.05,
"average_calculation_span": 1000
},
"devices": [
{
"slave_id": 3,
"config_file": "nope",
"manufacturer_name": "ELM3602-0002",
"measurements": [],
"metadata": [
{
"id": "did",
"value": "f33c6bah-b31e-4f5a-964h-13a935a8b25f"
}
]
},
{
"slave_id": 4,
"config_file": "blah.conf",
"manufacturer_name": "ELM3602-0000",
"did": "ELM3602-0000",
"measurements": []
},
{
"slave_id": 5,
"config_file": "EL3202.conf",
"manufacturer_name": "EL3202",
"did": "EL3202",
"measurements": [
{
"id": "stator_temperature",
"reporting_interval": 250,
"pre_send_processing": {
"output_type": "float",
"gain": 10.5,
"offset": -5
}
},
{
"id": "surface_temperature",
"reporting_interval": 500
}
]
},
{
"slave_id": 7,
"config_file": "EL3783.conf",
"manufacturer_name": "EL3783",
"did": "EL3783",
"custom_prefix": "v1/sb",
"measurements": [
{
"id": "voltage_phase_1",
"reported_id": "Ch1VoltageExample",
"complex": {
"samples": 7500,
"collection_interval": 10
},
"pre_send_processing": {
"output_type": "float",
"gain": 10.5,
"offset": -5
}
},
{
"id": "current_phase_1",
"object": {},
"complex": {
"samples": 7500,
"collection_interval": 300
}
},
{
"id": "voltage_phase_2",
"object": {},
"complex": {
"samples": 7500,
"collection_interval": 300
}
},
{
"id": "current_phase_2",
"complex": {
"samples": 7500,
"collection_interval": 300
}
},
{
"id": "voltage_phase_3",
"complex": {
"samples": 7500,
"collection_interval": 300
}
},
{
"id": "current_phase_3",
"complex": {
"samples": 7500,
"collection_interval": 300
}
}
]
}
]
}
Slave Configuration File
// Configure PDOs - description of data returned by slave
write 0x8000 0x01 16 0x0062 // IEPE +-5V
write 0x8000 0x03 16 0x0003 // 0.1Hz cutoff
write 0x8000 0x07 4 0x0002 // 4mA excitation
write 0x8010 0x01 16 0x0062
write 0x8010 0x03 16 0x0003
write 0x8010 0x07 4 0x0002
write 0x1C13 0x00 8 0x00
write 0x1C13 0x01 16 0x1A00
write 0x1C13 0x02 16 0x1A0F
write 0x1C13 0x03 16 0x1A21
write 0x1C13 0x04 16 0x1A30
write 0x1C13 0x05 16 0x1A10
write 0x1C13 0x00 8 0x05 // actual message to set number of objects
// Configure input data mapping
inputBitSize 6528 // needs to match the bits specified below, it is also returned from the slave
// GWAType DataType BitLen Name (type specific tokens)
// Chanel 1 voltage ---- zero index is not sent from table 5.6.3Input data pag. 142
align 0x10
align 0x10
complexMeasurement integer 0x20 vibration_axis_z 100
// Channel 1 current
align 0x10
align 0x10
complexMeasurement integer 0x20 vibration_empty_channel 100
// Sync
align 0x40 // syncTime unsigned 0x40 NextSyncTime