Skip to main content

MQTT

MQTT is a common network protocol for reading and writing data from and to cloud platforms.

It is a publish/subscribe based protocol. The hopit Edge MQTT Target is always the client and communicates with an external MQTT Broker. Additionally to the Data Streaming, the Namespace can be discoverer, the Device Twin can be synchronized via MQTT and Tasks can be triggered via the RPC protocol on top of MQTT.

Configuration​

The MQTT Target has the following parameters:

  • Host: Host name or IP address of the MQTT Broker. mqtt://, mqtts://, ws:// or wss:// are supported protocols.
  • Client ID: MQTT client ID, if not set generated automatically.
  • Username: The desired user name.
  • Password: The login password.
  • DeviceTwinTopic: Topic for the Device Twin. see the Device Twin section for details
  • TasksRequestTopic: Topic for subscribing to RPC Commands for Task execution. See the Tasks section for details.
  • TasksResponseTopic: Topic for publishing response of Task execution. See the Tasks section for details.
  • QoS: Quality of Service, select from:
    • AtMostOnce
    • AtLeastOnce
    • ExactlyOnce
  • ProtocolVersion: MQTT protocol version, select from:
    • V310
    • V311
    • V500
  • TargetType: The type is always MQTT for this Target.

For the common parameters, see the Introduction.

Corresponding Edge configuration and Device Twin definition to activate the MQTT Target service:
https://localhost:5050/Targets
MQTT Target Settings

Data Streaming​

MQTT messages will be exchanged in JSON format.

Signal Source​

If the MQTT Target is used as Source in a Route, the signal names uses the syntax topic.signal-name. Nested objects in the JSON message are separated with a . in the signal name. To read signals from the topic telemetry with the message format

{
  "object-1": {
    "signal-1": "value-1",
    "signal-2": "value-2"
  }
}

the names to configure would be telemetry.opject-1.signal-1 and telemetry.opject-1.signal-2.

info

The target subscribes automatically to all topics found in the Signals list.

Signal Destination​

When the MQTT Target is used as Destination in a Route, all signals will be added to a flat JSON format.

A sample message could be

{
  "signal-1": "value-1",
  "signal-2": "value-2"
}

The standard topic messages are published is /telemetry. To change this, a Property named topic can be added to the Route. The value of this property is the topic used for publishing the signals for this Destination.

Signals can be also read with Regex matcher. See the Router documentation for details.

Signal discovery is available for this Target. See the Introduction for more details.

For information how signals are named and labeled in Data Lakes, please read the Data Lake documentation.

Device Twin​

Device Twin updates are synchronized using the topic configured with the parameter DeviceTwinTopic if the Target is enabled in the Device Twin settings.

Report​

If the Device Twin is changed on the Edge, all settings are published as JSON message with the property DeviceTwinReported

{ 
    "DeviceTwinReported":{ 
        "AdsRouter": { 
          "Enabled":false 
        }, 
        "LogCollector": { 
          "Enabled":true 
        },
        ...
    }
}

Desire​

To update the Device Twin from the Broker, publish a message with the property DeviceTwinDesired to the topic configured with the parameter DeviceTwinTopic.

{ 
    "DeviceTwinDesired":{ 
        "AdsRouter": { 
          "Enabled":true 
        }
    }
}

Target or Route deletion​

To delete a Target or a Route via the Device Twin, it have to be set to null.

The Device Twin documentation shows more details about the operation.

Tasks​

To remotely execute Tasks on the Edge device, JSON-RPC calls can be used. The topics for requests and responses can be configured using the parameters TasksRequestTopic and TasksResponseTopic.

To trigger a Task execution via MQTT, publish a JSON message with the parameters method (the Task name) and params (the Task arguments). For example:

{"method":"Reboot","params":{}}

If a two way RPC call was executed, the Edge device will publish a response to the TasksResponseTopic.

Please read the Tasks for more information about Tasks.

Start Discovery Task​

The StartDiscovery Task can only be executed from a remote target. See the Tasks documentation for details.

The namespace is sent back to the topic configured DeviceTwinTopic with the JSON format:

{
  "DiscoveredSignals-[Target Name]": {
    "signal-1": "value-1",
    "signal-2": "value-2",
    ...
  }
}