Dryad API - MQTT Sensor Data Integration
Learn how to use Dryad's API, the MQTT Sensor Data Integration
Last updated
Learn how to use Dryad's API, the MQTT Sensor Data Integration
Last updated
© 2024, Dryad Networks GmbH, Eisenbahnstr. 37, 16225 Eberswalde, Germany
The Dryad external Message Queuing Telemetry Transport (MQTT) broker facilitates the integration of its sensor data with third-party systems. This includes customers and partners who wish to integrate the Dryad cloud platform with their own IT systems, such as command and control systems, and other data analytics platforms. For instance, this integration can be utilized for weather data analysis.
The MQTT is based on publish/subscribe architecture. It consists of
MQTT broker
MQTT clients
The term client refers to both publishers (Wildfire Sensors) and subscribers (third-party systems) for messages.
Dryad sensors, such as Wildfire Sensors, publish sensor readings to the Dryad external MQTT broker. The MQTT broker keeps track of subscribers who have subscribed to different topics. When the broker receives a message on a specific topic, it distributes the message to all subscribers who are subscribed to that topic.
For example, a wildfire sensor might publish its sensor readings to the topic:
If a subscriber (client) has subscribed to the same topic, it will receive the same message.
The message contains a payload (the actual sensor data) and metadata.
The connection is initiated when the client sends a CONNECT
message to the Dryad external MQTT broker. The broker responds with a CONNACK
message. Once the connection is established, the broker maintains it until either the client initiates a disconnect command or the connection is interrupted.
The CONNACK
message contains a return code indicating whether the connection was successful or not.
Return codes
Refer to the official MQTT documentation’s Connect Reason Code section to find out the possible return (reason) codes.
To receive messages on topics of interest as a client, you must first send a SUBSCRIBE
message to the Dryad external MQTT broker. The SUBSCRIBE
message can have a packet identifier and a list of subscriptions.
Each subscription contains
Case-sensitivity
MQTT topics are case-sensitive.
For example, the topic:
/sensor/envmon/Site-001/#
differs from the topic:
/sensor/envmon/site-001/#
To confirm each subscription, the Dryad MQTT broker sends a SUBACK
acknowledgement message.
The SUBACK
message contains the packet identifier of the original SUBSCRIBE
message and a return code. The return code indicates whether the subscription has been granted or rejected.
Refer to the official MQTT documentation's SUBACK payload section to find out the possible return (reason) codes.
After receiving the SUBACK
message, messages are received that match the topics you subscribed to when they were published.
If you no longer want to receive messages on a topic, you can send a UNSUBSCRIBE
message to the Dryad external MQTT broker.
With the UNSUBSCRIBE
message, you must include a list of topics from which you want to unsubscribe. To confirm the unsubscribe, the Dryad external MQTT broker sends a UNSUBACK
acknowledgement message.
The UNSUBACK
message contains a packet identifier, which is the same as the packet identifier of the UNSUBSCRIBE
message, along with a return code. The return code indicates whether the subscription has been granted or rejected.
See Also
Refer to the official MQTT documentation's UNSUBACK payload section to find out the possible return (reason) codes.
To subscribe to topics and receive messages, you need an MQTT client to connect with the Dryad external MQTT broker.
To configure your MQTT client to communicate with the Dryad external MQTT broker use one of the following options:
The site serial ID, username and password are provided separately via email with the username and password shared via a 1Password link. The 1Password link is valid for a period of 7 days.
See Also
For more information, see iPassword.
If your client supports Secure Socket Layer (SSL) connection mode, use that mode to communicate with the Dryad eternal MQTT broker whenever possible. The secure port uses SSL certificates generated by Let’s Encrypt. The ISRG Root X1 Certificate Authority (CA) certificate is available here and can be used for a secure connection. You can specify the file location of the isrgrootx1.pem when you connect to the broker with the secure port, 31393.
See Also
For SSL certificate details, see Let's Encrypt.
Dryad uses the default Quality of Service (QoS) level, which is QoS level 0 (delivery at most once) when publishing messages. Consequently, the maximum level of QoS the subscriber can expect is also 0.
See Also
For more information, see Eclipse Mosquitto MQTT man page.
This section describes the Dryad external MQTT topics that can be subscribe to, either securely or insecurely, along with examples.
Use of the term "sensor"
The term sensor
refers to a Wildfire Sensor, which is a LoRaWAN end device that collects data, including fire alerts, temperature, humidity and air pressure using its internal Bosch (BME 688) gas sensor.
The payload is created using this data, along with other information such as sensor ID, longitude, latitude, and so on.
Dryad MQTT topics are used to receive messages from all sensors deployed in a Site:
Site is indicated by <site serial id>
Sensors are indicated by #
You receive one sensor data reading at a time on the same MQTT topic.
The MQTT topic has the following form:
It returns the following message JSON payload.
The table below explains each field in the JSON payload.
New fields can be added at any time, and there may be times where this table lags behind recent changes.
Each payload received contains data from a single Wildfire Sensor.
There is no pre-defined sequence for receiving data from each wildfire sensor. You receive data as soon as it gets published by a wildfire sensor.
For example, to receive all sensor data from a site having the following Site ID:
Use the following topic:
The JSON payload of the message sends data similar to the following example.
Dryad supports many commonly used MQTT clients. Currently, instructions for using the following MQTT clients are provided:
More to be added.
Eclipse Mosquitto's mosquitto_sub
is part of the Mosquitto MQTT broker.
With mosquitto_sub
you can subscribe and unsubscribe from topics.
Using mosquitto_sub
, the command syntax for subscribing to a topic is as follows:
where:
Flags
Only the following flags are supported:
-d
to debug the messages
-i
to set the client id
-c
to enable persistent client mode
For example, to subscribe to the topic:
Use the following non-secure or secure mosquitto_sub
commands shown below.
Non-secure:
Secure (uses ISRG Root X1 CA certificate):
See Also
For more information about command line options, see the mosquitto_sub manual.
With mosquitto_sub
, the command syntax for unsubscribing from a topic is as follows:
where:
For example, to unsubscribe from the topic:
Use the non-secure or secure mosquitto_sub
commands shown below.
Non-secure:
Secure (uses ISRG Root X1 CA certificate):
See Also
For more information about command line options, see the mosquitto_sub manual.
Return code | Description |
---|---|
Return code | Description |
---|---|
Host | Port | Connection type | Encryption |
---|---|---|---|
Name | Type | Description |
---|---|---|
Parameter | Description |
---|---|
Parameter | Description |
---|---|