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.
Tags
Industry protocols are very different in how they work and how they are configured. HiveMQ Edge minimizes the configuration burden and makes the usage easy. For example, configuring ModBus registers is very different from the configuration of nodeIds for OPC UA. All protocol adapters have the MQTT destination topic in common.
Managing Tags
Tags can be defined on the workspace by clicking on the device shown in the screenshot below:
A dialog will be opened which is almost identical for every protocol adapter. The first part of a tag definition includes a name of the tag and a description. A tag name is unique across a HiveMQ Edge deployment. The definition part of a tag is different per protocol adapter, e.g., OPC UA Tags.
Northbound
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
The tag name |
String (Tags), e.g., |
||
|
The MQTT topic |
String, e.g., |
||
|
|
The maximum MQTT QoS for the outgoing messages |
0,1, or 2 |
|
|
|
The message expiry in seconds that is used for the MQTT message. |
Integer 1 - 4294967294 |
Southbound
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
The tag name |
String (Tags), e.g., |
||
|
The MQTT topic filter to read from |
String, e.g., |
Topic Filters
MQTT topic filters are used to read data which is then written to a tag. A topic filter must have a data schema to provide reliable operations.
| Only JSON schemas are supported yet. |
Topic filters can be defined on the workspace:
A dialog will be opened that supports the user to create topic filters and to associate a schema with it.
Once a topic filter has been created, there are two options to assign a schema to it: Option 1: The easiest way is when you’re already sending data to a topic that is included in the topic filter. The topic filter dialog has the option to infer a schema from existing traffic.
Option 2: You can upload a JSON schema file to HiveMQ Edge that defines the schema of the incoming data.
HiveMQ Edge makes sure that the incoming MQTT traffic is continuously checked against the defined schema before it
writes to the tag and eventually to the device. All invalid messages are re-routed to the topic $invalid.
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'.
<simulation>
<id>sim</id>
<minDelay>0</minDelay>
<maxDelay>0</maxDelay>
<minValue>0</minValue>
<maxValue>1000</maxValue>
<simulationToMqtt>
<pollingIntervalMillis>1000</pollingIntervalMillis>
<simulationToMqttMappings>
<simulationToMqttMapping>
<includeTagNames>false</includeTagNames>
<includeTimestamp>true</includeTimestamp>
<messageHandlingOptions>MQTTMessagePerTag</messageHandlingOptions>
<mqttQos>0</mqttQos>
<mqttTopic>sim</mqttTopic>
</simulationToMqttMapping>
</simulationToMqttMappings>
</simulationToMqtt>
</simulation>Simulation Adapter Properties
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
The unique identifier of the selected adapter instance. |
String [a-zA-Z0-9-_] |
||
|
|
Minimum limit for the randomly generated values of the simulator. |
Integer |
|
|
|
Maximum limit for the randomly generated values of the simulator. |
Integer |
|
|
|
Minimum of artificial delay before the polling method generates a value |
Integer > 0 |
|
|
|
Maximum of artificial delay before the polling method generates a value |
Integer > 0 |
|
|
General config of mappings from simulator to MQTT |
|
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
|
Time in milliseconds between the publish operations of the simulator. |
Integer |
|
|
List of simulator to MQTT mappings |
|
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
Common configurations |
{
"timestamp" : 1730707250320,
"value" : 729.6615064364747
}ModBus (TCP) Adapter
The ModBus adapter enables connections to ModBus slaves via TCP. We support reading from coils, discrete inputs, input registers and holding registers in the address 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.
<modbus>
<id>my-modbus-protocol-adapter</id>
<host>my.modbus-server.com</host>
<port>502</port>
<timeoutMillis>500</timeoutMillis>
<modbusToMqtt>
<pollingIntervalMillis>150</pollingIntervalMillis>
<maxPollingErrorsBeforeRemoval>5</maxPollingErrorsBeforeRemoval>
<publishChangedDataOnly>false</publishChangedDataOnly>
<modbusToMqttMappings>
<modbusToMqttMapping>
<mqttTopic>my/topic</mqttTopic>
<mqttQos>1</mqttQos>
<tagName>myTag</tagName>
<messageHandlingOptions>MQTTMessagePerSubscription</messageHandlingOptions>
<mqttUserProperties>
<mqttUserProperty>
<name>name</name>
<value>value1</value>
</mqttUserProperty>
<mqttUserProperty>
<name>name</name>
<value>value2</value>
</mqttUserProperty>
</mqttUserProperties>
<includeTagNames>true</includeTagNames>
<includeTimestamp>false</includeTimestamp>
</modbusToMqttMapping>
</modbusToMqttMappings>
</modbusToMqtt>
</modbus><tag>
<tagDefinition>
<unitId>0</unitId>
<startIdx>11</startIdx>
<readType>HOLDING_REGISTERS</readType>
<dataType>INT_64</dataType>
</tagDefinition>
<tagName>myTag</tagName>
</tag>ModBus (TCP) Adapter Properties
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
The unique identifier of the selected adapter instance. |
String [a-zA-Z0-9-_] |
||
|
The host or IPv4/IPv6 of the ModBus device. |
URI |
||
|
The port to connect to. |
Integer 1-65535 |
||
|
|
Time in milliseconds between samplings. |
Integer |
|
|
|
The number of times the adapter attempts to sample while an error condition is detected. |
Integer (-1 to disable) |
|
|
|
Specifies whether the adapter only publishes data when a field value change is detected. |
Boolean |
|
|
|
Include names of the tags with each publish |
Boolean |
|
|
|
Include the timestamp of when the tag was collected |
Boolean |
|
|
|
Data type to be read from the addressRange |
BOOL | INT_16 | UINT_16 | INT_32 | UINT_32 | INT_64 | FLOAT_32 | FLOAT_64 | UTF_8 |
|
|
Specifies whether the adapter only publishes data when a field value change is detected. |
Boolean |
||
|
Topic to publish to |
String |
||
|
Quality of service level for publishing |
Integer 0 - 2 |
||
|
Unit to access on modbus |
Integer |
||
|
Address of the register from where reading should start |
Integer |
||
|
Register type being read from |
COILS | DISCRETE_INPUT | INPUT_REGISTERS | HOLDING_REGISTERS |
||
|
Name of a MQTT 5 property to be sent with each message |
String |
||
|
Value of a MQTT 5 property to be sent with each message |
String |
| name | definition | length | BOOL | boolean |
|---|---|---|---|---|
|
|
integer |
16 bit / 1 register |
UINT_16 |
|
|
INT_32 |
integer |
32 bit / 2 registers |
|
|
32 bit / 2 registers |
INT_64 |
integer (long) |
|
|
float |
32 bit / 2 registers |
FLOAT_64 |
|
|
UTF_8 |
utf-8 character |
64 bit / 4 registers |
| 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.
You can configure the adapter to read from OPC UA server and publish it to an MQTT topic (opcuaToMqtt) or write to an OPC UA server from an MQTT topic (mqttToOpcua).
Both directions require to configure basic connectivity information for OPC UA.
The connection creates subscriptions with the OPC UA server and discovers available nodes on the server.
The configuration below shows the basic OPC UA connectivity.
<protocol-adapters>
<opcua>
<config>
<id>opcua</id>
<overrideUri>false</overrideUri>
<uri>opc.tcp://opcua-server:4840</uri>
</config>
</opcua>
</protocol-adapters>As next step, you can configure to read an OPC UA nodeId from the server and publish it to an MQTT topic.
OPC UA to MQTT: Northbound
This section describe how to configure a OPC UA to MQTT configuration also called northbound.
| HiveMQ Edge 2024.8 introduces the concept of tags. Tags are used to simplify the usage of data from any protocol adapter. |
<hivemq>
...
<protocol-adapters>
<protocol-adapter>
<adapterId>simulation-server-2</adapterId>
<protocolId>opcua</protocolId>
<config>
<uri>opc.tcp://CSM1.local:53530/OPCUA/SimulationServer</uri>
<opcuaToMqtt>
</opcuaToMqtt>
</config>
<northboundMappings>
<northboundMapping>
<tagName>temperature/for/machine_1</tagName>
<topic>machine/1/temperature</topic>
</northboundMapping>
</northboundMappings>
</southboundMappings>
<tags>
<tag>
<name>temperature/for/machine_1</name>
<description>This tag is about sensor data</description>
<definition>
<node>ns=1;i=1004</node>
</definition>
</tag>
</tags>
</protocol-adapter>
</protocol-adapters>
...
</hivemq>The config defines a connection to an OPC UA server and a northbound mapping.
The mapping defines to read data from tag temperature/for/machine_1, which connected to the nodeId ns=1;i=1004. The read tag is published as MQTT message into the topic machine/1/temperature. The tags are defined in the <tags> section.
{
"value": 1000
}{
"value": {
"Position_Reached": false,
"Target_Position": 2700,
"Increment": 0,
"Actual_Position": 0,
"Config": {
"Ref_Pos": 0,
"Loop_Value": 0
}
}
}OPC UA to MQTT: Southbound
HiveMQ Edge can write to OPC UA nodes from any MQTT data sources. Mapping an MQTT topic filter to OPC UA data points works like the northbound mapping. The southbound mapping consists of a topic filter that includes a data schema of the MQTT payload and a tag to be written. An example configuration is shown below:
<hivemq>
<protocol-adapters>
<protocol-adapter>
<adapterId>simulation-server-2</adapterId>
<protocolId>opcua</protocolId>
<config>
<uri>opc.tcp://CSM1.local:53530/OPCUA/SimulationServer</uri>
<overrideUri>true</overrideUri>
<auth>
<basic>
<username>edge</username>
<password>password</password>
</basic>
<x509>
<enabled>true</enabled>
</x509>
</auth>
<tls>
<enabled>true</enabled>
<keystore>
<path>path/to/keystore</path>
<password>keystore-password</password>
<privateKeyPassword>private-key-password</privateKeyPassword>
</keystore>
<truststore>
<path>path/to/truststore</path>
<password>truststore-password</password>
</truststore>
</tls>
<security>
<policy>BASIC128RSA15</policy>
</security>
<opcuaToMqtt>
<publishingInterval>12</publishingInterval>
<serverQueueSize>13</serverQueueSize>
</opcuaToMqtt>
</config>
</northboundMappings>
<southboundMappings>
<southboundMapping>
<tagName>ns=1;i=1004</tagName>
<topicFilter>data/area1/#</topicFilter>
<fromNorthSchema>{}</fromNorthSchema>
</southboundMapping>
<southboundMapping>
<tagName>ns=2;i=1004</tagName>
<topicFilter>data/area2/#</topicFilter>
<fromNorthSchema>{}</fromNorthSchema>
</southboundMapping>
</southboundMappings>
<tags>
<tag>
<name>ns=1;i=1004</name>
<description>description1</description>
<definition>
<node>ns=1;i=1004</node>
</definition>
</tag>
<tag>
<name>ns=2;i=1004</name>
<description>description2</description>
<definition>
<node>ns=2;i=1004</node>
</definition>
</tag>
</tags>
</protocol-adapter>
</protocol-adapters>
</hivemq>| Writing to OPC UA Arrays data types is not supported yet. |
OPC UA Adapter Properties
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
URI of the OPC-UA server to connect to. |
URI |
||
|
Override the URI provided by the OPC UA server |
Boolean |
||
|
The auth mechanism to connect the OPC UA server |
Authentication mechanism More information |
||
|
|
TLS configuration |
Boolean |
|
|
|
OPC UA Security Policy to use. |
|
|
|
Configuration of OPC UA to MQTT (Northbound) |
OPC UA Northbound config details
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
|
Publishing Interval [ms] |
Integer > 0 |
|
|
|
Server queue size |
Integer > 0 |
Tag Definitions for OPC UA
The general structure of tags is defined identically for each protocol adapter as described in Tags. The precise definition is different as listed below. In OPC UA, nodeIds are configured to address specific data points.
<hivemq>
<protocol-adapters>
<protocol-adapter>
<adapterId>...</adapterId>
<protocolId>opcua</protocolId>
<config>
...
</config>
<tags>
<tag>
<name>boiler/temperature</name>
<description>Provides the temperature inside the boiler</description>
<definition>
<node>ns=1;s=Temperature</node>
</definition>
</tag>
</tags>
</protocol-adapter>
</protocol-adapters>
</hivemq>The definition field is specific for OPC UA and contains the nodeId definition, e.g., ns=1;s=Temperature.
Tags are defined over a list of tag-items.
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
The nodeId of OPC UA |
OPC UA nodeId adressing schema |
OPC UA Authentication
HiveMQ Edge supports basic authentication and x509 authentication against OPC UA servers.
OPC UA Authentication Basic
<opcua>
<config>
...
<auth>
<basic>
<username>edge</username>
<password>password</password>
</basic>
</auth>
...
</config>
</opcua>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.
<opcua>
<config>
...
<tls>
<enabled>true</enabled>
</tls>
...
</config>
</opcua><opcua>
<config>
...
<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>
...
</config>
</opcua>| Property Name | Default | Mandatory | Description |
|---|---|---|---|
|
|
Defines whether TLS is enabled. |
|
|
Keystore that contains the private key and certificate chain for the client certificate. |
||
|
|
Truststore to verify the server certificate against. |
S7 Adapter
The S7 adapter enables connections to Siemens S7 PLCs. S7 tags and data blocks can be read by the adapter.
| The S7 protocol is also using the term tags. Those tags are different from those used in the broader context of HiveMQ Edge. We will refer them in the following as S7 tags. |
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 & Security → Connection mechanisms → Permit access with PUT/GET communication from remote partner.
|
<hivemq>
<protocol-adapters>
<protocol-adapter>
<adapterId>my-s7-protocol-adapter</adapterId>
<protocolId>s7</protocolId>
<config>
<host>my.s7-device</host>
<port>102</port>
<controllerType>S7_1500</controllerType>
</config>
<northboundMappings>
<northboundMapping>
<topic>motor/speed</topic>
<tagName>motor_speed</tagName>
</northboundMapping>
</northboundMappings>
<tags>
<tag>
<name>motor_speed</name>
<description>The speed of the moto</description>
<definition>
<tagAddress>%ID103</tagAddress>
<dataType>DINT</dataType>
</definition>
</tag>
</tags>
</protocol-adapter>
</protocol-adapters>
</hivemq>S7 Adapter Properties (config)
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
The host or IPv4/IPv6 of the S7 device. |
URI |
||
|
The port to which the adapter connects. |
Integer 1-65535 |
||
|
The series of the S7 PLC (Programmable Logic Controller). |
one of: |
||
|
|
Rack value for the remote main CPU. |
Integer |
|
|
|
Slot value for the remote main CPU. |
Integer |
|
|
|
Rack value for the remote secondary CPU. |
Integer |
|
|
|
Slot value for the remote secondary CPU. |
Integer |
|
|
|
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 |
S7 Northbound config
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
|
Specifies whether the adapter only publishes data when a field value change is detected. |
Boolean |
|
|
|
Time in milliseconds between samplings. |
Integer |
|
|
|
The number of times the adapter attempts to sample while an error condition is detected. |
Integer |
Tag Definitions for OPC UA
The general structure of tags is defined identically for each protocol adapter as described in Tags. The precise definition is different as listed below. In OPC UA nodeIds are configured to address specific data points.
<hivemq>
<protocol-adapters>
<protocol-adapter>
<adapterId>...</adapterId>
<protocolId>opcua</protocolId>
<config>
...
</config>
<tags>
<tag>
<name>boiler/temperature</name>
<description>Provides the temperature inside the boiler</description>
<definition>
<node>ns=1;s=Temperature</node>
</definition>
</tag>
</tags>
</protocol-adapter>
</protocol-adapters>
</hivemq>The definition field is specific for OPC UA and contains the nodeId definition, e.g., ns=1;s=Temperature.
Tags are defined over a list of tag-items.
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
The nodeId of OPC UA |
OPC UA nodeId adressing schema |
S7 Tag Address
The general structure of tags is defined identically for each protocol adapter as described in Tags. The precise definition is different as listed below. In the following the S7 tags addresses are described. The S7 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.
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
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.
S7 Types
| Type | Description | Memory size code | MQTT payload example | Value range |
|---|---|---|---|---|
|
1 bit |
|
|
|
|
1 byte unsigned |
|
|
|
|
1 byte signed |
|
|
|
|
1 byte unsigned |
|
|
|
|
2 byte signed |
|
|
|
|
2 byte unsigned |
|
|
|
|
4 byte signed |
|
|
|
|
4 byte unsigned |
|
|
|
|
8 byte signed |
|
|
|
|
8 byte unsigned |
|
|
|
|
2 byte unsigned |
|
|
|
|
4 byte unsigned |
|
|
|
|
8 byte unsigned |
|
|
|
|
4 byte floating point signed |
|
|
|
|
8 byte floating point signed |
|
|
|
|
1 byte character |
|
|
ascii alphabet |
|
2 byte character |
|
|
unicode alphabet |
|
ascii string |
|
|
ascii alphabet |
|
unicode string |
|
|
unicode alphabet |
|
4 byte signed, millisecond duration |
|
|
|
|
8 byte signed, nanosecond duration |
|
|
|
|
Date |
|
|
(ISO 8601) |
|
Time of day milliseconds |
|
|
(ISO 8601) |
|
Time of day nanoseconds |
|
|
(ISO 8601) |
|
DateTime milliseconds |
|
|
(ISO 8601) |
|
DateTime nanoseconds |
|
|
(ISO 8601) |
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
The defined address of the tag |
String |
||
|
The data type |
Selection of S7 data types |
ADS / TwinCAT Adapter
The ADS adapter enables connections to Beckhoff and other TwinCAT 3 capable PLCs.
<hivemq>
<protocol-adapters>
<protocol-adapter>
<adapterId>my-ads-protocol-adapter</adapterId>
<protocolId>ads</protocolId>
<config>
<host>my.ads-server.com</host>
<port>1234</port>
<targetAmsPort>123</targetAmsPort>
<sourceAmsPort>124</sourceAmsPort>
<targetAmsNetId>1.2.3.4.5.6</targetAmsNetId>
<sourceAmsNetId>1.2.3.4.5.7</sourceAmsNetId>
</config>
<northboundMappings>
<northboundMapping>
<topic>my/topic</topic>
<tagName>tag-name</tagName>
</northboundMapping>
</northboundMappings>
<tags>
<tag>
<name>tag-name</name>
<description>description</description>
<definition>
<tagAddress>123</tagAddress>
<dataType>BOOL</dataType>
</definition>
</tag>
</tags>
</protocol-adapter>
</protocol-adapters>
</hivemq><hivemq>
<protocol-adapters>
<protocol-adapter>
<adapterId>my-ads-protocol-adapter</adapterId>
<protocolId>ads</protocolId>
<config>
<host>my.ads-server.com</host>
<port>1234</port>
<targetAmsPort>1234</targetAmsPort>
<sourceAmsPort>12345</sourceAmsPort>
<targetAmsNetId>1.2.3.4.5.6</targetAmsNetId>
<sourceAmsNetId>1.2.3.4.5.7</sourceAmsNetId>
<adsToMqtt>
<pollingIntervalMillis>10</pollingIntervalMillis>
<maxPollingErrorsBeforeRemoval>9</maxPollingErrorsBeforeRemoval>
<publishChangedDataOnly>false</publishChangedDataOnly>
</adsToMqtt>
</config>
<northboundMappings>
<northboundMapping>
<topic>my/topic</topic>
<maxQos>1</maxQos>
<includeTagNames>true</includeTagNames>
<includeTimestamp>true</includeTimestamp>
<messageHandlingOptions>MQTTMessagePerSubscription</messageHandlingOptions>
<tagName>tag-name</tagName>
<mqttUserProperties>
<mqttUserProperty>
<name>name</name>
<value>value1</value>
</mqttUserProperty>
<mqttUserProperty>
<name>name</name>
<value>value2</value>
</mqttUserProperty>
</mqttUserProperties>
</northboundMapping>
<northboundMapping>
<topic>my/topic/2</topic>
<maxQos>1</maxQos>
<includeTagNames>true</includeTagNames>
<includeTimestamp>true</includeTimestamp>
<messageHandlingOptions>MQTTMessagePerSubscription</messageHandlingOptions>
<tagName>tag-name</tagName>
<mqttUserProperties>
<mqttUserProperty>
<name>name</name>
<value>value1</value>
</mqttUserProperty>
<mqttUserProperty>
<name>name</name>
<value>value2</value>
</mqttUserProperty>
</mqttUserProperties>
</northboundMapping>
</northboundMappings>
<tags>
<tag>
<name>tag-name</name>
<description>description</description>
<definition>
<tagAddress>123</tagAddress>
<dataType>WORD</dataType>
</definition>
</tag>
</tags>
</protocol-adapter>
</protocol-adapters>
</hivemq>ADS Adapter Properties Config
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
The host or IPv4/iIPv6 of the ModBus device. |
URI |
||
|
|
The port to connect to. |
Integer 1-65535 |
|
|
The AMS Net ID of the device to connect to. |
Integer 1-65535 |
||
|
The AMS port number on the device to connect to. |
Integer 1-65535 |
||
|
The AMS Net ID of HiveMQ Edge. |
Integer 1-65535 |
||
|
The local AMS port number HiveMQ Edge uses. |
Integer 1-65535 |
ADS Tag Address
The general structure of tags is defined identically for each protocol adapter as described in Tags.
The precise definition is different as listed below. In the following the S7 tags addresses are described.
The ADS tag address 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_VARThe variable addresses for the protocol adapter are then:
-
MAIN.iCounter -
MAIN.MiCounter -
MAIN.QstrText
ADS Types
| Type | Description | MQTT payload example | Value range |
|---|---|---|---|
|
1 bit |
|
|
|
1 byte unsigned |
|
|
|
1 byte signed |
|
|
|
1 byte unsigned |
|
|
|
2 byte signed |
|
|
|
2 byte unsigned |
|
|
|
4 byte signed |
|
|
|
4 byte unsigned |
|
|
|
8 byte signed |
|
|
|
8 byte unsigned |
|
|
|
2 byte unsigned |
|
|
|
4 byte unsigned |
|
|
|
8 byte unsigned |
|
|
|
4 byte floating point signed |
|
|
|
8 byte floating point signed |
|
|
|
ascii string |
|
|
|
unicode string |
|
|
|
4 byte unsigned, millisecond duration, UDINT |
|
|
|
8 byte unsigned, nanosecond duration, ULINT |
|
|
|
Date, UDINT |
|
|
|
Date, ULINT |
|
|
|
Time of day milliseconds, UDINT |
|
|
|
Time of day nanoseconds, ULINT |
|
|
|
DateTime milliseconds, UDINT |
|
|
|
DateTime nanoseconds, ULINT |
|
|
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
The defined address of the tag |
String |
||
|
The data type |
Selection of ADS data types |
EtherNet/IP Adapter
The EtherNet/IP adapter enables connections to Rockwell / Allen-Bradley PLCs (Programmable Logic Controllers) from the ControLogix and CompactLogix series.
<hivemq>
<protocol-adapters>
<protocol-adapter>
<adapterId>my-eip-protocol-adapter</adapterId>
<protocolId>eip</protocolId>
<config>
<port>1234</port>
<host>my.eip-server.com</host>
</config>
<northboundMappings>
<northboundMapping>
<topic>my/topic</topic>
<tagName>tag-name</tagName>
</northboundMapping>
</northboundMappings>
<tags>
<tag>
<name>tag-name</name>
<description>description</description>
<definition>
<address>addressy</address>
<dataType>BOOL</dataType>
</definition>
</tag>
</tags>
</protocol-adapter>
</protocol-adapters>
</hivemq><hivemq>
<protocol-adapters>
<protocol-adapter>
<adapterId>my-eip-protocol-adapter</adapterId>
<protocolId>eip</protocolId>
<config>
<host>my.eip-server.com</host>
<port>1234</port>
<backplane>4</backplane>
<slot>5</slot>
<eipToMqtt>
<pollingIntervalMillis>10</pollingIntervalMillis>
<maxPollingErrorsBeforeRemoval>9</maxPollingErrorsBeforeRemoval>
<publishChangedDataOnly>false</publishChangedDataOnly>
</eipToMqtt>
</config>
<northboundMappings>
<northboundMapping>
<topic>my/topic</topic>
<maxQos>1</maxQos>
<includeTagNames>true</includeTagNames>
<includeTimestamp>true</includeTimestamp>
<messageHandlingOptions>MQTTMessagePerSubscription</messageHandlingOptions>
<tagName>tag-name</tagName>
<mqttUserProperties>
<mqttUserProperty>
<name>name</name>
<value>value1</value>
</mqttUserProperty>
<mqttUserProperty>
<name>name</name>
<value>value2</value>
</mqttUserProperty>
</mqttUserProperties>
</northboundMapping>
<northboundMapping>
<topic>my/topic/2</topic>
<maxQos>1</maxQos>
<includeTagNames>true</includeTagNames>
<includeTimestamp>true</includeTimestamp>
<messageHandlingOptions>MQTTMessagePerSubscription</messageHandlingOptions>
<tagName>tag-name</tagName>
<mqttUserProperties>
<mqttUserProperty>
<name>name</name>
<value>value1</value>
</mqttUserProperty>
<mqttUserProperty>
<name>name</name>
<value>value2</value>
</mqttUserProperty>
</mqttUserProperties>
</northboundMapping>
</northboundMappings>
<tags>
<tag>
<name>tag-name</name>
<description>description</description>
<definition>
<address>addressy</address>
<dataType>BOOL</dataType>
</definition>
</tag>
</tags>
</protocol-adapter>
</protocol-adapters>
</hivemq>EtherNet/IP Adapter Properties Config
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
The host or IPv4/IPv6 of the EtherNet/IP device. |
URI |
||
|
|
The port to connect to. |
Integer 1-65535 |
|
|
|
The ID of the backplane. |
Integer 1-65535 |
|
|
|
The ID of the slot. |
Integer 1-65535 |
EtherNet/IP Tag Address
The general structure of tags is defined identically for each protocol adapter as described in Tags.
The precise definition is different as listed below. In the following the S7 tags addresses are described.
The tag address for EtherNet/IP is the name of the Controller Tag <tag-name> that is shown in Logix/Studio 5000.
Example: at_int_tag
EtherNet/IP Types
| Type | Description | MQTT payload example | Value range |
|---|---|---|---|
|
1 bit |
|
|
|
1 byte signed |
|
|
|
1 byte unsigned |
|
|
|
2 byte signed |
|
|
|
2 byte unsigned |
|
|
|
4 byte signed |
|
|
|
4 byte unsigned |
|
|
|
8 byte signed |
|
|
|
8 byte unsigned |
|
|
|
4 byte floating point signed |
|
|
|
8 byte floating point signed |
|
|
|
ascii string |
|
|
|
4 byte unsigned, millisecond duration, UDINT |
|
|
|
8 byte unsigned, nanosecond duration, ULINT |
|
|
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
The defined address of the tag |
String |
||
|
The data type |
Selection of EIP data types |
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.
<hivemq>
<protocol-adapters>
<protocol-adapter>
<adapterId>my-protocol-adapter</adapterId>
<protocolId>http</protocolId>
<config>
</config>
<southboundMappings>
<southboundMapping>
<tagName>tag2</tagName>
<topicFilter>my/#</topicFilter>
<fromNorthSchema>{}</fromNorthSchema>
</southboundMapping>
</southboundMappings>
<northboundMappings>
<northboundMapping>
<tagName>tag1</tagName>
<topic>my/destination</topic>
<maxQos>1</maxQos>
</northboundMapping>
</northboundMappings>
<tags>
<tag>
<name>tag1</name>
<description>description1</description>
<definition>
<url>http://lol1.com</url>
</definition>
</tag>
<tag>
<name>tag2</name>
<description>description1</description>
<definition>
<url>http://lol1.com</url>
</definition>
</tag>
</tags>
</protocol-adapter>
</protocol-adapters>
</hivemq>HTTP Adapter Properties
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
|
Defines whether untrusted HTTP sources such as expired certificates can be accepted. |
|
|
|
|
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 |
|
|
|
Time in milliseconds that the endpoint is polled. |
Integer > 0 |
|
|
The URL to the HTTP server for data requests. |
URL |
||
|
The topic to which the response is published. |
MQTT topic |
||
|
the unique identifier of the protocol adapter. |
String |
||
|
|
The method to be used to make the HTTP request. |
|
|
|
|
The length of time to wait for HTTP response (in seconds). |
Integer > 0 |
|
|
|
Specifies whether to Publish message only when the HTTP code is successful (200 - 299). |
|
|
|
The QoS to be used for publish. |
MQTT QoS |
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
The name of the HTTP header. |
String |
||
|
The value of the HTTP header. |
String |
File Adapter
File adapters add functionality to read files from the file system on which HiveMQ Edge runs. The adapter supports different input formats and makes it possible to read information from systems that cannot communicate via the network or defined APIs.
| HiveMQ Data Hub can extract specific information from the content of a file or transform a payload to fit your business needs. |
Example configuration to read a file from /tmp/sensor.json.
<hivemq>
<protocol-adapters>
<protocol-adapter>
<adapterId>my-file-protocol-adapter</adapterId>
<protocolId>file</protocolId>
<config>
<fileToMqtt></fileToMqtt>
</config>
<northboundMappings>
<northboundMapping>
<topic>my/topic</topic>
<tagName>tag1</tagName>
</northboundMapping>
</northboundMappings>
<tags>
<tag>
<name>tag1</name>
<description>decsription</description>
<definition>
<filePath>pathy</filePath>
<contentType>BINARY</contentType>
</definition>
</tag>
</tags>
</protocol-adapter>
</protocol-adapters>
</hivemq>Example
Suppose a file named /tmp/sensor.json has the following example content:
{ "value": "42" }Create the config as introduced above, the following MQTT payload is generated and shown below:
You can use any MQTT tool that is capable of showing an MQTT topic’s content.
In the example, we use mqtt sub -t 'file-input'
|
{
"timestamp" : 1730122091809,
"value" : {
"value" : "42"
},
"tagName" : "value",
"contentType" : "application/json"
}| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
The local path to the file to read |
Path |
||
|
The content type of the file. The following types are supported: |
Enum |
||
|
Common configurations |
Common Configurations
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
The topic to which the response is published. |
MQTT topic |
||
|
MQTT Payload QoS |
MQTT QoS |
||
|
|
Include the name of the Tag |
MQTT QoS |
|
|
|
Add a timestamp to the MQTT payload |
boolean |
|
|
List of |
|||
|
|
Specifies whether the adapter only publishes data when a field value change is detected. (Not available for all protocol adapters) |
Boolean |
MQTT User Properties for Protocol Adapters
MQTT User Properties can be added to each MQTT message created out of a Protocol Adapter payload. Any number of User Properties can be created. For more information of MQTT User Properties, read MQTT 5 User Properties.
| Property Name | Default | Mandatory | Description | Format |
|---|---|---|---|---|
|
Name of the Key of the MQTT User Property |
String |
||
|
Name of the Key of the MQTT User Property |
String |
Contribute a Custom Adapter
The HiveMQ Edge protocol adapter SDK (Java Doc) can be utilized to implement a custom protocol adapter. For a step-by-step tutorial, see How to Build a File-based Protocol Adapter for HiveMQ Edge.