HiveMQ Edge Protocol Adapters

HiveMQ Edge allows the runtime to connect to any proprietary protocol format and converts it into open standards MQTT. In HiveMQ Edge, the components that contribute this functionality are called 'protocol adapters'. To contribute new protocol adapters, you can create your own module that conforms to the requisite format and build the adapters into your runtime. When contributed, the runtime will manage the lifecycle of these components and allow you to create any number of connections to your devices.

HiveMQ Edge Protocol Adapter Configuration

Adapter instances can be added to the system using API, static configuration, or the user interface. All 3 mechanisms result in the main config.xml file being updated with a new element within the <protocol-adapters> element. Each adapter type has its own element name which matches the adapter type name in the ProtocolAdapterFactory. For example, the 'Simulation' protocol has a type of 'simulation' and a <simulation></simulation> configuration element.

In the adapter configuration, each adapter instance much be identified with a unique <id> element .

The HiveMQ Edge UI and API automatically validate the uniqueness of the instance.

HiveMQ Edge Provides the following protocol adapters:

Custom adapters can be built to adapt further protocols to fit your business needs.

Simulation Adapter

The simulation adapter enables the system to be configured to publish messages with random values through the protocol adapter layer at a specific interval. This functionality enables you to observe the behavior of adapters in the system.

The example configuration publishes random data with MQTT quality of service level 1 to the destination topic called 'topic'.

Example simulation adapter configuration
 <simulation>
    <id>test-simulation-server</id>
    <minValue>-10</minValue>
    <maxValue>10</maxValue>
    <pollingIntervalMillis>5000</pollingIntervalMillis>
    <subscriptions>
        <subscription>
            <destination>test</destination>
            <qos>1</qos>
        </subscription>
    </subscriptions>
</simulation>

Simulation Adapter Properties

Property Name Default Mandatory Description Format

id

The unique identifier of the selected adapter instance.

String [a-zA-Z0-9-_]

pollingIntervalMillis

10000

Time in milliseconds between the publish operations of the simulator.

Integer

minValue

0

Minimum limit for the randomly generated values of the simulator.

Integer

maxValue

1000

Maximum limit for the randomly generated values of the simulator.

Integer

subscription > destination

The destination topic to which the adapter publishes.

String UTF-8

subscription > qos

0

The quality of service level the adapter uses for the publish operation.

Integer 0, 1, 2

ModBus (TCP) Adapter

The ModBus adapter enables connections to ModBus slaves via TCP. Currently, the input registers can be read in the range 0-65534 (incl). The connection samples the ModBus slave on the sampling time specified in the configuration. Each connection can be configured to only publish samples when changes in values are detected.

Example ModBus (TCP) adapter configuration
 <modbus>
    <id>modbus-connection</id>
    <port>502</port>
    <host>some-ip4-address</host>
    <publishChangedDataOnly>true</publishChangedDataOnly>
    <publishingInterval>500</publishingInterval>
    <subscriptions>
        <subscription>
            <holding-registers>
                <endIdx>1</endIdx>
                <startIdx>0</startIdx>
            </holding-registers>
            <destination>test</destination>
        </subscription>
    </subscriptions>
    <maxPollingErrorsBeforeRemoval>5</maxPollingErrorsBeforeRemoval>
</modbus>

ModBus (TCP) Adapter Properties

Property Name Default Mandatory Description Format

id

The unique identifier of the selected adapter instance.

String [a-zA-Z0-9-_]

host

The host or IPv4/IPv6 of the ModBus device.

URI

port

The port to connect to.

Integer 1-65535

publishChangedDataOnly

true

Specifies whether the adapter only publishes data when a field value change is detected.

Boolean

publishingInterval

1000

Time in milliseconds between samplings.

Integer

subscription > holding-resisters

A parent element to denote the subscriptions to the holding registers.

Address range

subscription > holding-resisters > startIdx

0

The start index (inclusive) of the holding register to read.

Integer 0-65534

subscription > holding-resisters > endIdx

1

The end index (inclusive) of the holding register to read.

Integer 0-65534

subscription > destination

The destination topic to which the adapter publishes.

MQTT topic

subscription > qos

0

The quality of service to be used for the publish operation.

MQTT QoS

maxPollingErrorsBeforeRemoval

10

The number of times the adapter attempts to sample while an error condition is detected. If the configured maximum is exceeded, the sampling job ceases to execute until the connection is re-established.

Integer

Each sample is published as an array with each 16-bit index encoded as an 2 octet decimal value.

OPC UA Adapter

The OPC UA adapter enables connections to OPC UA servers. The connection creates subscriptions with the OPC UA serve and discovers available nodes on the server.

Subscriptions to OPC nodes can be made to node IDs that represent a value or nodes that represent an object or structure. Only changed values and an initial value when setting up the subscription are published.

Example MQTT message payload resulting from subscribing to a value
{
"value": 1000
}
Example MQTT message payload resulting from subscribing to an object/structure
{
  "value": {
    "Position_Reached": false,
    "Target_Position": 2700,
    "Increment": 0,
    "Actual_Position": 0,
    "Config": {
      "Ref_Pos": 0,
      "Loop_Value": 0
    }
  }
}
Example minimal OPC UA adapter configuration (anonymous authentication)
<opc-ua-client>
    <id>opc-example</id>
    <uri>opc.tcp://my-opc-server-uri-or-ip:4840</uri>
    <subscriptions>
        <subscription>
            <node>ns=3;s="node-name"</node>
            <mqtt-topic>my/mqtt/topic/1</mqtt-topic>
        </subscription>
    </subscriptions>
</opc-ua-client>
Example full OPC UA adapter configuration
<hivemq>
...
    <protocol-adapters>
        <opc-ua-client>
            <id>full-opc-example</id>
            <uri>opc.tcp://my-opc-server-uri-or-ip:4840</uri>
            <auth>
                <basic>
                    <username>my-user</username>
                    <password>secret</password>
                </basic>
            </auth>
            <tls>
                <enabled>true</enabled>
                <keystore>
                    <path>/path/to/my/keystore.jks</path>
                    <password>keystore-password</password>
                    <private-key-password>key-password</private-key-password>
                </keystore>
                <truststore>
                    <path>/path/to/my/truststore.jks</path>
                    <password>truststore-password</password>
                </truststore>
            </tls>
            <security>
                <policy>BASIC256SHA256</policy>
            </security>
            <subscriptions>
                <subscription>
                    <node>ns=3;s="node-name"</node>
                    <mqtt-topic>my/mqtt/topic/1</mqtt-topic>
                    <qos>2</qos>
                    <message-expiry-interval>60</message-expiry-interval>
                    <publishing-interval>1000</publishing-interval>
                    <server-queue-size>1</server-queue-size>
                </subscription>
                <subscription>
                    <node>ns=3;i=101</node>
                    <mqtt-topic>my/mqtt/topic/2</mqtt-topic>
                </subscription>
            </subscriptions>
        </opc-ua-client>
    </protocol-adapters>
...
</hivemq>

OPC UA Adapter Properties

Property Name Default Mandatory Description Format

id

The unique identifier of the selected adapter instance.

String [a-zA-Z0-9-_]

uri

URI of the OPC-UA server to connect to.

URI

auth

none

Authentication mechanism

tls

no TLS

TLS configuration

Boolean

security > policy

NONE

OPC UA Security Policy to use.

NONE, BASIC128RSA15, BASIC256, BASIC256SHA256, AES128_SHA256_RSAOAEP, AES256_SHA256_RSAPSS.

subscriptions

A parent element to denote the subscriptions to the OPC UA server.

subscription > node

The OPC UA node ID to subscribe to

OPC UA parsable node identifier. Example: ns=3;s="Temperature" or ns=1;i=101

subscription > mqtt-topic

The MQTT topic to which the changed values are published.

MQTT topic

subscription > qos

0

The MQTT Quality of Service to use for the publishes.

MQTT QoS

subscription > message-expiry-interval

no expiry

The message expiry in seconds that is used for the MQTT message.

Integer 1-4294967294

subscription > publishing-interval

1000

OPC UA publishing interval in milliseconds for this subscription on the server.

Integer >1

subscription > server-queue-size

1

OPC UA queue size for this subscription on the server.

Integer >1

OPC UA Authentication

HiveMQ Edge supports basic authentication and x509 authentication against OPC UA servers.

OPC UA Authentication Basic
Basic auth example
...
<opc-ua-client>
...
    <auth>
        <basic>
            <username>my-user</username>
            <password>secret</password>
        </basic>
    </auth>
...
</opc-ua-client>
...
OPC UA Authentication X509
To use x509 authentication, the TLS configuration must be set and a keystore must be configured.
X509 auth example
...
<opc-ua-client>
...
    <auth>
        <x509/>
    </auth>
...
</opc-ua-client>
...

OPC UA TLS configuration

HiveMQ Edge supports connections to OPC UA servers with TLS and mutual TLS. To utilize mTLS, specify a keystore and enable x509 authentication.

Minimal TLS example using system truststore
<opc-ua-client>
    ...
    <tls>
        <enabled>true</enabled>
    </tls>
    ...
</opc-ua-client>
TLS example with mutual TLS and custom truststore
<opc-ua-client>
    ...
    <tls>
        <enabled>true</enabled>
        <keystore>
            <path>/path/to/my/keystore.jks</path>
            <password>keystore-password</password>
            <private-key-password>key-password</private-key-password>
        </keystore>
        <truststore>
            <path>/path/to/my/truststore.jks</path>
            <password>truststore-password</password>
        </truststore>
    </tls>
    ...
</opc-ua-client>
Property Name Default Mandatory Description

enabled

false

Defines whether TLS is enabled.

keystore

Keystore that contains the private key and certificate chain for the client certificate.

truststore

System truststore

Truststore to verify the server certificate against.

S7 Adapter

The S7 adapter enables connections to Siemens S7 PLCs. Tags and data blocks can be read by the adapter.

S7 PUT/GET must be enabled on the PLC (Programmable Logic Controller), otherwise a connection with the S7 adapter is not possible. The setting can be found on your TIA Portal in the General tab, under Protection & SecurityConnection mechanismsPermit access with PUT/GET communication from remote partner.
Example minimal S7 adapter configuration
 <s7>
    <id>my-s7-id</id>
    <host>my-ip-address-or-host</host>
    <port>102</port>
    <controllerType>S7_1500</controllerType>
    <subscriptions>
        <subscription>
            <tagName>my-tag-name-1</tagName>
            <tagAddress>%I204.0</tagAddress>
            <destination>my/topic/1</destination>
            <dataType>SINT</dataType>
            <qos>1</qos>
        </subscription>
    </subscriptions>
</s7>
Example full S7 adapter configuration
 <s7>
    <id>my-s7-id</id>
    <host>my-ip-addr-or-host</host>
    <port>102</port>
    <controllerType>S7_1500</controllerType>
    <maxPollingErrorsBeforeRemoval>10</maxPollingErrorsBeforeRemoval>
    <pollingIntervalMillis>1000</pollingIntervalMillis>
    <remoteRack>0</remoteRack>
    <remoteSlot>0</remoteSlot>
    <remoteRack2>1</remoteRack2>
    <remoteSlot2>0</remoteSlot2>
    <remoteTsap>0</remoteTsap>
    <publishChangedDataOnly>true</publishChangedDataOnly>
    <subscriptions>
        <subscription>
            <tagName>my-tag-name-1</tagName>
            <tagAddress>%I204.0</tagAddress>
            <destination>my/topic/1</destination>
            <dataType>BOOL</dataType>
            <qos>1</qos>
            <messageHandlingOptions>MQTTMessagePerTag</messageHandlingOptions>
            <includeTimestamp>true</includeTimestamp>
            <includeTagNames>false</includeTagNames>
        </subscription>
        <subscription>
            <tagName>my-tag-name-2</tagName>
            <tagAddress>%I205.0</tagAddress>
            <destination>my/topic/2</destination>
            <dataType>BOOL</dataType>
            <qos>0</qos>
            <messageHandlingOptions>MQTTMessagePerTag</messageHandlingOptions>
            <includeTimestamp>true</includeTimestamp>
            <includeTagNames>true</includeTagNames>
        </subscription>
    </subscriptions>
</s7>

S7 Adapter Properties

Property Name Default Mandatory Description Format

id

The unique identifier of the selected adapter instance.

String [a-zA-Z0-9-_]

host

The host or IPv4/IPv6 of the S7 device.

URI

port

The port to which the adapter connects.

Integer 1-65535

controllerType

The series of the S7 PLC (Programmable Logic Controller).

one of: S7_300, S7_400, S7_1200, S7_1500, LOGO

publishChangedDataOnly

true

Specifies whether the adapter only publishes data when a field value change is detected.

Boolean

publishingInterval

1000

Time in milliseconds between samplings.

Integer

maxPollingErrorsBeforeRemoval

10

The number of times the adapter attempts to sample while an error condition is detected. If the configured maximum is exceeded, the sampling job ceases to execute until the connection is re-established.

Integer

remoteRack

0

Rack value for the remote main CPU.

Integer

remoteSlot

0

Slot value for the remote main CPU.

Integer

remoteRack

0

Rack value for the remote secondary CPU.

Integer

remoteSlot

0

Slot value for the remote secondary CPU.

Integer

remoteTsap

0

Remote TSAP value. The TSAP (Transport Services Access Point) mechanism is used as a further addressing level in the S7 PLC network. Usually, the value is only required for PLCs from the LOGO series.

Integer

subscription > qos

0

The quality of service to be used for the publish operation.

MQTT QoS

subscription > destination

The destination topic to which the adapter publishes.

MQTT Topic

subscription > tagName

The name of the selected tag.

String [a-zA-Z0-9-_]

subscription > tagAddress

The address of the selected tag. For more information, see S7 Tag Address

S7 Tag Address

subscription > includeTimestamp

true

Specifies whether a server timestamp is included in the resulting MQTT message.

true/false

subscription > includeTagNames

false

Specifies whether the tag name is included in the resulting MQTT message.

true/false

subscription > messageHandlingOptions

MQTTMessagePerTag

Defines the format of the resulting MQTT message. Either one message per changed tag or one message per subscription with multiple data points per sample

MQTTMessagePerTag or MQTTMessagePerSubscription

S7 Tag Address

The tag address for an S7 variable can be found in TIA Portal.

PLC (Programmable Logic Controllers) Tags

The address for tags can be found in TIA Portal in the Address column of the PLC Tags table . For PLC tags, this value can be used as it is directly in HiveMQ Edge.

a27cd79f e6f6 4632 b949 b7484213a102

If you cannot get the addresses directly from TIA Portal, you can use the following format to construct the address:

Format for bit addresses:

%<Memory-Area-Code><Byte-Offset>.<Bit-Offset>

Format for byte addresses

%<Memory-Area-Code><Memory-Size-Code><Byte-Offset>

Example: %I205.0 or ´ %QB207

Where the Memory-Area-Code is one of I(Inputs), Q(Outputs), D(Direct peripheral access), M(Markers), C(Counter), T(Timer), DB(Data block).

And Memory-Size-Code describes the size of the variable value. The codes are X(1 bit or 8 bytes), B(1 byte), W(2 bytes), D(4 bytes).
For detailed information on which code maps to which type, see S7 Types.

Data blocks

The data block addressing scheme is:

%DB<Data-Block-Number>:<Byte-Offset>.<Bit-Offset>

%DB<Data-Block-Number>:<Byte-Offset>

Example: %DB10:20.0 or %DB10:22

The Data-Block-Number is displayed in the tree view on the left in your TIA Portal, behind the name of your data block, enclosed in [] brackets or on the top of the data block view.

The Byte-Offset (and Bit-Offset) can be found in TIA Portal in the Offset column in the data block view

13030c6c b52d 4112 a461 48961f655cfa
Fixed offsets are only available for variables in data blocks if Optimized block access is turned off.

The setting for optimizing block access can be found in the properties of the data block in TIA Portal.

e06d9b94 ae36 4b51 9a84 2bc7278fd4e2

S7 Types

Type Description Memory size code MQTT payload example Value range

BOOL

1 bit

X

{"value": true}

true/false

BYTE

1 byte unsigned

B

{"value": 255}

0-255

SINT

1 byte signed

B

{"value": -75}

-128-127

USINT

1 byte unsigned

B

{"value": 255}

0-255

INT

2 byte signed

W

{"value": -3450}

-32768-32767

UINT

2 byte unsigned

W

{"value": 3450}

0-65535

DINT

4 byte signed

D

{"value": -3450}

-2147483648-2147483647

UDINT

4 byte unsigned

D

{"value": 123232}

0-4294967295

LINT

8 byte signed

X

{"value": -123232000}

-9223372036854775808-9223372036854775807

ULINT

8 byte unsigned

X

{"value": 123232000}

0-18446744073709551615

WORD

2 byte unsigned

W

{"value": 1024}

0-65535

DWORD

4 byte unsigned

D

{"value": 123456789}

0-4294967295

LWORD

8 byte unsigned

X

{"value": 1234567890000}

0-18446744073709551615

REAL

4 byte floating point signed

D

{"value":123.456789} or {"value":3.4028235E38}

1.4E-45-3.4028235E38

LREAL

8 byte floating point signed

X

{"value":123.456789} or {"value":4.9E-324}

4.9E-324-1.7976931348623157E308

CHAR

1 byte character

B

{"value":"a"}

ascii alphabet

WCHAR

2 byte character

W

{"value":"a"}

unicode alphabet

STRING

ascii string

X

{"value":"abcdefgh"}

ascii alphabet

WSTRING

unicode string

X

{"value":"abcdefgh"}

unicode alphabet

TIME

4 byte signed, millisecond duration

D

{"value":-1234}

-2147483648-2147483647

LTIME

8 byte signed, nanosecond duration

D

{"value":-1234}

-9223372036854775808-9223372036854775807

DATE

Date

X

{"value":"2020-03-12"}

(ISO 8601) "1990-01-01"-"2168-12-31"

TIME_OF_DAY

Time of day milliseconds

X

{"value":"01:23:45.678"}

(ISO 8601) "00:00:00.000"-"23:59:59.999"

LTIME_OF_DAY

Time of day nanoseconds

X

{"value":"01:23:45.678901234"}

(ISO 8601) "00:00:00.000"-"23:59:59.999999999"

DATE_AND_TIME

DateTime milliseconds

X

{"value":"2020-03-12"}

(ISO 8601) 1970-01-01T00:00:00.000-2089-12-31T23:59:59.999

LDATE_AND_TIME

DateTime nanoseconds

X

{"value":"2020-03-12T23:59:59.123456789"}

(ISO 8601) 1970-01-01T00:00:00.000-2089-12-31T23:59:59.999

ADS / TwinCAT Adapter

The ADS adapter enables connections to Beckhoff and other TwinCAT 3 capable PLCs.

Please see below for the example configuration.

Example minimal ADS adapter configuration
<ads>
    <id>my-ads-id</id>
    <host>my-ip-addr-or-host</host>
    <port>48898</port>
    <targetAmsNetId>2.3.4.5.1.1</targetAmsNetId>
    <targetAmsPort>850</targetAmsPort>
    <sourceAmsNetId>5.4.3.2.1.1</sourceAmsNetId>
    <subscriptions>
        <subscription>
            <tagName>my-tag-name</tagName>
            <tagAddress>MYPROGRAM.MyStringVar</tagAddress>
            <destination>my/mqtt/topic</destination>
            <dataType>STRING</dataType>
            <qos>1</qos>
        </subscription>
    </subscriptions>
</ads>
Example full ADS adapter configuration
<hivemq>
...
  <protocol-adapters>
    <ads>
        <id>asd</id>
        <host>172.16.10.54</host>
        <port>48898</port>
        <targetAmsNetId>2.3.4.5.1.1</targetAmsNetId>
        <targetAmsPort>850</targetAmsPort>
        <sourceAmsNetId>5.4.3.2.1.1</sourceAmsNetId>
        <sourceAmsPort>49999</sourceAmsPort>
        <subscriptions>
            <subscription>
                <tagName>my-tag-name</tagName>
                <tagAddress>MYPROGRAM.MyStringVar</tagAddress>
                <destination>my/mqtt/topic</destination>
                <dataType>STRING</dataType>
                <qos>1</qos>
                <includeTagNames>false</includeTagNames>
                <includeTimestamp>true</includeTimestamp>
                <messageHandlingOptions>MQTTMessagePerTag</messageHandlingOptions>
            </subscription>
        </subscriptions>
        <publishChangedDataOnly>true</publishChangedDataOnly>
        <pollingIntervalMillis>1000</pollingIntervalMillis>
        <maxPollingErrorsBeforeRemoval>10</maxPollingErrorsBeforeRemoval>
    </ads>
    ...
  </protocol-adapters>
...
</hivemq>

ADS Adapter Properties

Property Name Default Mandatory Description Format

id

The unique identifier of the adapter instance.

String [a-zA-Z0-9-_]

host

The host or IPv4/iIPv6 of the ModBus device.

URI

port

48898

The port to connect to.

Integer 1-65535

targetAmsNetId

The AMS Net ID of the device to connect to.

Integer 1-65535

targetAmsPort

The AMS port number on the device to connect to.

Integer 1-65535

sourceAmsNetId

The AMS Net ID of HiveMQ Edge.

Integer 1-65535

sourceAmsPort

The local AMS port number HiveMQ Edge uses.

Integer 1-65535

publishChangedDataOnly

true

Specifies whether the adapter only publishes data when a field value change is detected.

Boolean

publishingInterval

1000

Time in milliseconds between samplings.

Integer

maxPollingErrorsBeforeRemoval

10

The maximum number of times the adapter attempts to sample while an error condition is detected. If the configured maximum is exceeded, the sampling job ceases to execute until the connection is re-established.

Integer

subscription > qos

0

The quality of service to be used for the publish operation.

MQTT QoS

subscription > destination

The destination topic to which the adapter publishes.

MQTT Topic

subscription > tagName

The name of the selected tag.

String [a-zA-Z0-9-_]

subscription > tagAddress

The address of the selected tag. For more information, see ADS Tag Address

ADS Tag Address

subscription > dataType

The type of the selected tag. For more information, see ADS Types.

ADS data type

subscription > includeTimestamp

true

Specifies whether a server timestamp is included in the resulting MQTT message.

true/false

subscription > includeTagNames

false

Specifies whether the tag name is included in the resulting MQTT message.

true/false

subscription > messageHandlingOptions

MQTTMessagePerTag

Defines the format of the resulting MQTT message. Either one message per changed tag or one message per subscription with multiple data points per sample

MQTTMessagePerTag or MQTTMessagePerSubscription

ADS Tag Address

The tag address for ADS is the program name followed by the variable name separated by a dot, in the format <program-name>.<variable-name> .

Example program:

PROGRAM MAIN
VAR
    iCounter          : INT     := 41;
    MiCounter AT %MW2 : INT     := 21;
    QstrText AT %QB20 : STRING  := 'abcdefg';
END_VAR

The variable addresses for the protocol adapter are then:

  • MAIN.iCounter

  • MAIN.MiCounter

  • MAIN.QstrText

ADS Types

Type Description MQTT payload example Value range

BOOL / BIT

1 bit

{"value": true}

true/false

BYTE

1 byte unsigned

{"value": 255}

0-255

SINT

1 byte signed

{"value": -75}

-128-127

USINT

1 byte unsigned

{"value": 255}

0-255

INT

2 byte signed

{"value": -3450}

-32768-32767

UINT

2 byte unsigned

{"value": 3450}

0-65535

DINT

4 byte signed

{"value": -3450}

-2147483648-2147483647

UDINT

4 byte unsigned

{"value": 123232}

0-4294967295

LINT

8 byte signed

{"value": -123232000}

-9223372036854775808-9223372036854775807

ULINT

8 byte unsigned

{"value": 123232000}

0-18446744073709551615

WORD

2 byte unsigned

{"value": 1024}

0-65535

DWORD

4 byte unsigned

{"value": 123456789}

0-4294967295

LWORD

8 byte unsigned

{"value": 1234567890000}

0-18446744073709551615

REAL

4 byte floating point signed

{"value":123.456789} or {"value":3.4028235E38}

1.4E-45-3.4028235E38

LREAL

8 byte floating point signed

{"value":123.456789} or {"value":4.9E-324}

4.9E-324-1.7976931348623157E308

STRING

ascii string

{"value":"abcdefgh"}

ascii alphabet

WSTRING

unicode string

{"value":"abcdefgh"}

unicode alphabet

TIME

4 byte unsigned, millisecond duration, UDINT

{"value":1234}

0-4294967295

LTIME

8 byte unsigned, nanosecond duration, ULINT

{"value":12345}

0-18446744073709551615

DATE

Date, UDINT

{"value":"2020-03-12"}

(ISO 8601) "1990-01-01"-"2168-12-31"

LDATE

Date, ULINT

{"value":"2020-03-12"}

(ISO 8601) "1970-01-01"-"2554-07-21"

TIME_OF_DAY

Time of day milliseconds, UDINT

{"value":"01:23:45.678"}

(ISO 8601) "00:00:00.000"-"23:59:59.999"

LTIME_OF_DAY

Time of day nanoseconds, ULINT

{"value":"01:23:45.678901234"}

(ISO 8601) "00:00:00.000"-"23:59:59.999999999"

DATE_AND_TIME

DateTime milliseconds, UDINT

{"value":"2020-03-12"}

(ISO 8601) 1970-01-01T00:00:00.000-2089-12-31T23:59:59.999

LDATE_AND_TIME

DateTime nanoseconds, ULINT

{"value":"2020-03-12T23:59:59.123456789"}

(ISO 8601) 1970-01-01T00:00:00.000-2554-7-21-23:34:33.709551615

EtherNet/IP Adapter

The EtherNet/IP adapter enables connections to Rockwell / Allen-Bradley PLCs (Programmable Logic Controllers) from the ControLogix and CompactLogix series.

Example minimal EtherNet/IP adapter configuration
<ethernet-ip>
    <id>my-eip-id</id>
    <ethernet-ip>
        <id>my-eip-adapter-id</id>
        <host>my-ip-addr-or-host</host>
        <subscriptions>
            <subscription>
                <tagName>my-tag-name</tagName>
                <tagAddress>my_tag_name</tagAddress>
                <destination>my/mqtt/topic</destination>
                <dataType>STRING</dataType>
                <qos>1</qos>
            </subscription>
        </subscriptions>
    </ethernet-ip>
</ethernet-ip>
Example full EtherNet/IP adapter configuration
<hivemq>
...
  <protocol-adapters>
    <ethernet-ip>
        <id>my-eip-adapter-id</id>
        <host>172.16.10.54</host>
        <port>44818</port>
        <backplane>1</backplane>
        <slot>0</slot>
        <subscriptions>
            <subscription>
                <tagName>my-tag-name</tagName>
                <tagAddress>my_tag_name</tagAddress>
                <destination>my/mqtt/topic</destination>
                <dataType>STRING</dataType>
                <qos>1</qos>
                <includeTagNames>false</includeTagNames>
                <includeTimestamp>true</includeTimestamp>
                <messageHandlingOptions>MQTTMessagePerTag</messageHandlingOptions>
            </subscription>
        </subscriptions>
        <publishChangedDataOnly>true</publishChangedDataOnly>
        <pollingIntervalMillis>1000</pollingIntervalMillis>
        <maxPollingErrorsBeforeRemoval>10</maxPollingErrorsBeforeRemoval>
    </ethernet-ip>
    ...
  </protocol-adapters>
...
</hivemq>

EtherNet/IP Adapter Properties

Property Name Default Mandatory Description Format

id

The unique identifier of the selected adapter instance.

String [a-zA-Z0-9-_]

host

The host or IPv4/IPv6 of the EtherNet/IP device.

URI

port

48898

The port to connect to.

Integer 1-65535

backplane

1

The ID of the backplane.

Integer 1-65535

slot

0

The ID of the slot.

Integer 1-65535

publishChangedDataOnly

true

Specifies whether the adapter only publishes data when a field value change is detected.

Boolean

publishingInterval

1000

Time in milliseconds between samplings.

Integer

maxPollingErrorsBeforeRemoval

10

The number of times the adapter attempts to sample while an error condition is detected. If the configured maximum is exceeded, the sampling job ceases to execute until the connection is re-established.

Integer

subscription > qos

0

The quality of service to be used for the publish operation.

MQTT QoS

subscription > destination

The destination topic to which the adapter publishes.

MQTT Topic

subscription > tagName

The name of the selected tag.

String [a-zA-Z0-9-_]

subscription > tagAddress

The address of the selected tag. For more information, see EtherNet/IP Tag Address .

EtherNet/IP Tag Address

subscription > dataType

The type of selected tag. For more information, see EtherNet/IP Types.

EtherNet/IP data type

subscription > includeTimestamp

true

Specifies whether a server timestamp is included in the resulting MQTT message.

true/false

subscription > includeTagNames

false

Specifies whether the tag name is included in the resulting MQTT message.

true/false

subscription > messageHandlingOptions

MQTTMessagePerTag

Defines the format of the resulting MQTT message. Either one message per changed tag or one message per subscription with multiple data points per sample

MQTTMessagePerTag or MQTTMessagePerSubscription

EtherNet/IP Tag Address

The tag address for EtherNet/IP is the name of the Controller Tag <tag-name> that is shown in Logix/Studio 5000.

040ff166 6984 4d38 881a 35e92ba969bd

Example: at_int_tag

EtherNet/IP Types

Type Description MQTT payload example Value range

BOOL

1 bit

{"value": true}

true/false

SINT

1 byte signed

{"value": -75}

-128-127

USINT

1 byte unsigned

{"value": 255}

0-255

INT

2 byte signed

{"value": -3450}

-32768-32767

UINT

2 byte unsigned

{"value": 3450}

0-65535

DINT

4 byte signed

{"value": -3450}

-2147483648-2147483647

UDINT

4 byte unsigned

{"value": 123232}

0-4294967295

LINT

8 byte signed

{"value": -123232000}

-9223372036854775808-9223372036854775807

ULINT

8 byte unsigned

{"value": 123232000}

0-18446744073709551615

REAL

4 byte floating point signed

{"value":123.456789} or {"value":3.4028235E38}

1.4E-45-3.4028235E38

LREAL

8 byte floating point signed

{"value":123.456789} or {"value":4.9E-324}

4.9E-324-1.7976931348623157E308

STRING

ascii string

{"value":"abcdefgh"}

ascii alphabet

TIME

4 byte unsigned, millisecond duration, UDINT

{"value":1234}

0-4294967295

LTIME

8 byte unsigned, nanosecond duration, ULINT

{"value":12345}

0-18446744073709551615

HTTP(s) Adapter

The HTTP adapter is useful when data points can be gathered via HTTP even when other IoT protocols are not available or other software systems should be integrated. The HTTP adapter polls data from a configurable endpoint and converts it into an MQTT message.

Example HTTP Protocol Adapter Configuration
<protocol-adapters>
    ...
    <http>
        <qos>1</qos>
        <httpRequestMethod>GET</httpRequestMethod>
        <httpConnectTimeout>5</httpConnectTimeout>
        <httpRequestBodyContentType>JSON</httpRequestBodyContentType>
        <httpPublishSuccessStatusCodeOnly>true</httpPublishSuccessStatusCodeOnly>
        <httpHeaders>
            <httpHeader>
                <name>Authorization</name>
                <value>Bearer Some-Token</value>
            </httpHeader>
        </httpHeaders>
        <allowUntrustedCertificates>false</allowUntrustedCertificates>
        <maxPollingErrorsBeforeRemoval>10</maxPollingErrorsBeforeRemoval>
        <pollingIntervalMillis>1000</pollingIntervalMillis>
        <url>http://localhost:8080/metrics</url>
        <destination>http-device</destination>
        <id>HTTPEndpoint</id>
    </http>
    ...
</protocol-adapters>

HTTP Adapter Properties

Table 1. Parameters for top-level configuration
Property Name Default Mandatory Description Format

allowUntrustedCertificates

false

Defines whether untrusted HTTP sources such as expired certificates can be accepted.

true, false

maxPollingErrorsBeforeRemoval

10

The number of times the adapter attempts to sample while an error condition is detected. If the configured maximum is exceeded, the sampling job ceases to execute until the connection is re-established.

Integer > 0

pollingIntervalMillis

1000

Time in milliseconds that the endpoint is polled.

Integer > 0

url

The URL to the HTTP server for data requests.

URL

destination

The topic to which the response is published.

MQTT topic

id

the unique identifier of the protocol adapter.

String

httpRequestMethod

GET

The method to be used to make the HTTP request.

GET, POST, PUT

httpConnectTimeout

5

The length of time to wait for HTTP response (in seconds).

Integer > 0

httpPublishSuccessStatusCodeOnly

true

Specifies whether to Publish message only when the HTTP code is successful (200 - 299).

true, false

qos

The QoS to be used for publish.

MQTT QoS 0, 1, 2

Table 2. Configuration for HTTP headers
Property Name Default Mandatory Description Format

name

The name of the HTTP header.

String

value

The value of the HTTP header.

String

Contributing Custom Adapters

Each protocol is contributed to the runtime using the ServiceLoader framework. At the very least, an adapter must supply a protocol adapter factory implementation that is responsible for creating adapter instances (connections) as well as managing configuration required to configure the connections and metadata about the type and nature of the connection.

A typical adapter shall provide at a minimum the following:

com.<myorganisation>.adapter.

  • <ProtocolName>AdapterFactory - implements ProtocolAdapterFactory interface

  • <ProtocolName>AdapterInformation - implements ProtocolAdapterInformation interface

  • <ProtocolName>AdapterConfig - implements ProtocolAdapterInformation interface

  • <ProtocolName>AdapterConfigConverter - implements CustomConfig interface

  • <ProtocolName>Adapter - implements ProtocolAdapter (typically extends AbstractProtocolAdapter)

The adapter factory that is contributed couples the various implementations together.

Example adapter factory
public class SimulationProtocolAdapterFactory implements ProtocolAdapterFactory<SimulationAdapterConfig> {

    @Override
    public @NotNull ProtocolAdapterInformation getInformation() {
        return SimulationProtocolAdapterInformation.INSTANCE;
    }

    @Override
    public @NotNull ProtocolAdapter createAdapter(@NotNull final ProtocolAdapterInformation adapterInformation, @NotNull final ProtocolAdapterInput<SimulationAdapterConfig> input) {
        return new SimulationProtocolAdapter(adapterInformation, input.getConfig(), input.getMetricRegistry());
    }

    @Override
    public @NotNull SimulationAdapterConfig convertConfigObject(final @NotNull Map<@NotNull String, Object> config) {
        return SimulationConfigConverter.convertConfig(config);
    }

    @Override
    public Map<String, Object> unconvertConfigObject(final CustomConfig config) {
        return SimulationConfigConverter.unconvertConfig(config);
    }

    @Override
    public @NotNull Class<SimulationAdapterConfig> getConfigClass() {
        return SimulationAdapterConfig.class;
    }

}

To contribute a custom protocol adapter at runtime, create a .jar file that includes all of your dependencies and defines your adapter factory type in a META-INF/services/com.hivemq.edge.modules.api.adapters.ProtocolAdapterFactory file. Place the file in your HIVEMQ-HOME/modules/ directory.

During startup, the logging output indicates whether your module has been discovered by the runtime.

Example log statement
INFO  - Loaded 2 protocol adapters: ['ModBus TCP', 'OPC-UA Client']
Example custom adapter .jar file structure
+ your-adapter.jar
- META-INF/
    + services/
    -- com.hivemq.edge.modules.api.adapters.ProtocolAdapterFactory
- com
    + yourorganisation
        + adapter
        -- <ProtocolName>AdapterFactory
        -- <ProtocolName>AdapterInformation
        -- <ProtocolName>AdapterConfig
        -- <ProtocolName>AdapterConfigConverter
        -- <ProtocolName>Adapter