EMB Plug-in #

The Edge Insights for Industrial (EII) Message Bus (EMB) plug-in is designed to exchange data with EII via a publish and subscribe interface. This plug-in utilizes the EII Message Bus API interface for all communications. The underlying data protocol is ZMQ, but that is abstracted by the API. EMB is configured internally by converting the Protocol Bridge configuration parameters into a JSON configuration. Publishing data is completely abstracted by an EMB envelope, which is populated with field values and published via the API. Subscriber data is received through the API as a JSON payload. The format of the JSON data being received is defined in the Subscriber’s Configuration section. Communications may be configured to use either the IPC or TCP data transport. Security can be enabled for TCP by specifying the necessary public/private keys in the configuration. The ability to store these keys in HW will be provided in the future.

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 has elevated permissions.

Attention

This plug-in does not support the binary/blob datatype. Configuring a binary dataset field will result in a runtime error.

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

EMB - Plug-in Level Configuration Parameters #

Three configuration parameters are currently available at the plug-in level: RT thread core affinity, schedule priority, and an EMB log debug flag.

emb: dx-core-affinity #

This optional parameter defines the core to which the publisher, subscriber, or both real-time threads will be assigned.

By default, this value is set to 0.

Example:

dx-core-affinity: 1

emb: dx-sched-priority #

This optional parameter defines the core real-time thread priority assigned to the publisher, subscriber, or both.

By default, this value is set to 60.

Example:

dx-sched-priority: 60

emb: log-debug #

This optional parameter defines whether the EMB API outputs debug messages to the console.

By default, this value is set to false.

Example:

log-debug: true

EMB - Publisher Configuration Parameters #

EMB Publisher - Required Parameters #

The publisher configuration parameters must include a unique publisher ID, a dataset ID that defines the data fields to be published, a topic name, and the communication data transport - IPC or TCP. Additional parameters are available based on the communication transport and security requirements.

emb-publisher: publisher-id #

This mandatory parameter defines the publisher ID. You need to select the value of the publisher-id parameter, and make sure that the value is unique within the configuration file.

Example:

publisher-id: pub1

emb-publisher: dataset-id #

This parameter must reference a dataset defined for this plug-in.

Example:

dataset-id: emb-pub-ds

emb-publisher: topic #

This parameter defines the topic name for the publication being sent to EII. Subscribers will use this topic name to select the publisher data that they want to receive.

Example:

topic: publish_test

emb-publisher: type #

This parameter defines the data transport used by ZMQ, which is set to zmq_ipc and zmq_tcp for IPC and TCP, respectively.

Example:

type: zmq_ipc

EMB Publisher - IPC Parameters #

A file folder may be specified for the IPC socket to use.

emb-publisher: socket-dir #

This parameter defines the folder in which IPC stores temporary data.

Example:

socket-dir: "/tmp"

EMB Publisher - TCP Required Parameters #

When using TCP, host and port must be specified for the publisher to define the EII destination.

emb-publisher: host #

This parameter defines the IP Address of the EII destination.

Example:

socket-dir: "/tmp"

emb-publisher: port #

This parameter defines the port of the TCP destination.

Example:

port: 5569

EMB Publisher - TCP Security Parameters #

The server private key and a list of authorized clients may be specified for the publisher.

emb-publisher: server-private-key #

This parameter defines the key value, in clear text, in the configuration file. Eventually, this parameter will be stored securely in HW.

Example:

server-private-key: "qydUsM#PP4r<E*2]<]kbLRwk1IX:H^y{Gk56e:tc"

emb-publisher: authorized-clients #

This parameter list optionally defines an additional level of security by specifying the clients authorized to receive this publication. This key value is specified, in clear text, in the configuration file. Eventually, this parameter will be stored securely in HW.

Example:

    authorized-clients
-
  "y-G]27SC}{!mC4(]}=c=KH1M{x)Kd/{i%o]j7YT3"

EMB Subscriber Configuration Parameters #

EMB Subscriber - Required Parameters #

The subscriber configuration parameters must include a unique subscriber ID, a dataset ID that defines the data fields to be received, a topic name, the communication data transport - IPC or TCP, the read polling interval, and the JSON format of the incoming data. Additional parameters are available based on the communication transport and and security requirements.

emb-subscriber: subscriber-id #

Select the value of the subscriber-id parameter, and make sure that the value is unique within the configuration file.

Example:

subscriber-id: sub1

emb-subscriber: dataset-id #

This parameter references a dataset defined for this plug-in.

Example:

dataset-id: emb-sub-ds

emb-subscriber: topic #

This parameter defines the topic name for the publication received from EII. This should match the topic name of the publisher data.

Example:

topic: publish_test

emb-subscriber: type #

This parameter defines the data transport used by ZMQ, which is set to zmq_ipc or zmq_tcp for IPC and TCP, respectively.

Example:

type: zmq_ipc

emb-subscriber: polling-interval-us #

This parameter defines the frequency at which the subscriber polls for data and is specified in microseconds. Do not set this value too low or it will consume all CPU resources of the core on which it is executing and potentially lock the system.

Example:

polling-interval-us: 1000

emb-subscriber: json-format #

This parameter defines the format of the incoming JSON payload. The specified keys must match the name of the incoming JSON payload keys. See fld-int32 and fld-float in the following example. The specified key values must refer to a corresponding dataset field ID that receives the data. These field names are prefixed with a dollar symbol ($), see $fld1 and $fld2 in the following example. These names are placeholders for the actual data values received, similar to macro substitution.

Example:

json-format: >
  {"fld-int32":"$fld1", "fld-float":"$fld2"}

Following are the important pointers related to the JSON format parameter:

The supplied JSON must conform to the RFC 8259 standard or the parser will reject it. Use a JSON validator to make sure that the custom JSON is properly formatted and meets this standard.
All YAML formatting rules still apply to this configuration parameter, that is, make sure that the specified JSON format is properly indented.

EMB Subscriber - IPC Parameters #

A file folder may be specified for the IPC socket to use.

emb-subscriber: socket-dir #

This parameter defines the folder in which IPC stores temporary data.

Example:

socket-dir: "/tmp"

EMB Subscriber - TCP Required Parameters #

The host and port must be specified for the publisher to define the EII destination.

emb-subscriber: host #

This parameter defines the IP Address of the EII data source.

Example:

host: "127.0.0.1"

emb-subscriber: port #

This parameter defines the port of the EII data source.

Example:

port: 5569

EMB Subscriber - TCP Security Parameters #

The server public key, client private key, and client public key may be specified for the subscriber.

emb-subscriber: server-public-key #

This parameter defines the key value, in clear text, in the configuration file. Eventually, this parameter will be stored securely in HW.

Example:

server-public-key: "121JPFTMGj.wJL8{{SO>?AL0=(a6/a8FyG#=OeYQ"

emb-subscriber: client-private-key #

This parameter defines the key value, in clear text, in the configuration file. Eventually, this parameter will be stored securely in HW.

Example:

client-private-key: "vxJD1x?-v]Y=a>uv<<hR]?B$Pf(U9r4<SU9J+1cF"

emb-subscriber: client-public-key #

This parameter defines the key value, in clear text, in the configuration file. Eventually, this parameter will be stored securely in HW.

Example:

client-public-key: "y-G]27SC}{!mC4(]}=c=KH1M{x)Kd/{i%o]j7YT3

EMB - Putting in all together #

This section provides the sample configuration snippets for both the publisher and subscriber. This section also provides the list of example configuration files, which can be used for testing.

EMB - Publisher Configuration Example #

The following is a snippet of the configuration file for an IPC publisher:

-
plugin-id: plg-emb
filename: libplgemb.so
dataset:
  -
    dataset-id: emb-pub-ds
    listener-dataset-id: sim-ds
configuration:
  publisher:
    -
      publisher-id: pub1
      dataset-id: emb-pub-ds
      type: zmq_ipc
      topic: publish_test
      socket-dir: "/tmp"

The following is a snippet of the configuration file for a TCP publisher with security:

  -
plugin-id: plg-emb
filename: libplgemb.so
dataset:
  -
    dataset-id: emb-pub-ds
    listener-dataset-id: sim-ds
configuration:
  publisher:
    -
      publisher-id: pub1
      dataset-id: emb-pub-ds
      type: zmq_tcp
      host: "127.0.0.1"
      port: 5569
      topic: publish_test
      server-private-key: "qydUsM#PP4r<E*2]<]kbLRwk1IX:H^y{Gk56e:tc"
      authorized-clients:
        -
          "y-G]27SC}{!mC4(]}=c=KH1M{x)Kd/{i%o]j7YT3"

EMB - Subscriber Configuration Example #

The following is a snippet of the configuration file for an IPC subscriber:

-
  plugin-id: plg-emb
  filename: libplgemb.so
  dataset:
    -
      dataset-id: emb-sub-ds
      dataset-fields:
        -
          datafld-id: fld1
          datatype: int32
        -
          datafld-id: fld2
          datatype: float
  configuration:
    subscriber:
      -
        subscriber-id: sub1
        dataset-id: emb-sub-ds
        type: zmq_ipc
        topic: publish_test
        polling-interval-us: 1000
        json-format: >
          {"fld-int32":"$fld1", "fld-float":"$fld2"}
        socket-dir: "/tmp"

The following is a snippet of the configuration file for a TCP subscriber with security:

-
  plugin-id: plg-emb
  filename: libplgemb.so
  dataset:
    -
      dataset-id: emb-sub-ds
      dataset-fields:
        -
          datafld-id: fld1
          datatype: int32
        -
          datafld-id: fld2
          datatype: float
  configuration:
    subscriber:
      -
        subscriber-id: sub1
        dataset-id: emb-sub-ds
        type: zmq_tcp
        host: "127.0.0.1"
        port: 5569
        topic: publish_test
        polling-interval-us: 1000
        json-format: >
          {"fld-int32":"$fld1", "fld-float":"$fld2"}
        server-public-key: "121JPFTMGj.wJL8{{SO>?AL0=(a6/a8FyG#=OeYQ"
        client-private-key: "vxJD1x?-v]Y=a>uv<<hR]?B$Pf(U9r4<SU9J+1cF"
        client-public-key: "y-G]27SC}{!mC4(]}=c=KH1M{x)Kd/{i%o]j7YT3"

EMB - Test Configuration Files #

The following configuration file can be found in /opt/ec-protocol-bridge/config:

emb-tpc-loopback.yaml: A TCP publisher and subscriber loopback on the same compute node