Dryad Integration/Interfaces
Dryad Silvanet Documentation
  • Dryad Integration/Interfaces
  • Dryad API - MQTT Sensor Data Integration
  • Webhook Integration
Powered by GitBook

© 2025, Dryad Networks GmbH, Eisenbahnstr. 37, 16225 Eberswalde, Germany

On this page
  • Dryad External MQTT Broker
  • Connect
  • Subscribe
  • Unsubscribe
  • MQTT Client Configuration
  • Credentials
  • Secure Port
  • QoS
  • Dryad MQTT Topics
  • Receive All Sensor Data from a Site
  • MQTT Clients
  • Eclipse Mosquitto
  • MQTTx
Export as PDF

Dryad API - MQTT Sensor Data Integration

This document provides details regarding the Dryad MQTT Sensor Data Integration.

PreviousDryad Integration/InterfacesNextWebhook Integration

Last updated 4 months ago

Approved

Table of contents

Dryad External MQTT Broker

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 an MQTT broker and MQTT clients. The term client refers to both publishers (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 subscribe to it.

For example, a wildfire sensor might publish its sensor readings to the topic /sensor/envmon/site1/sensor1. 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.

Connect

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.

Subscribe

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 a topic and a QoS level.

MQTT topics are case-sensitive. The topic /sensor/envmon/Site-001/# differs from the topic /sensor/envmon/site-001/#, for example.

To confirm each subscription, the Dryad MQTT broker sends a SUBACK acknowledgement message to you.

Return code
Description

0

Successful

After receiving the SUBACK message, you will start receiving messages that match the topics you subscribed to when they were published.

Unsubscribe

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 you want to unsubscribe from. To confirm the unsubscribe, the Dryad external MQTT broker sends a UNSUBACK acknowledgement message to you.

Return code

0

Successful

MQTT Client Configuration

To subscribe to topics and receive messages, you'll need an MQTT client to connect with the Dryad external MQTT broker. You can configure your MQTT client to communicate with the Dryad external MQTT broker based on one of the following options:

Host
Port
Connection type
Encryption

ext.mqtt.dryad.app

31383

TCP

None (Non-secure)

ext.mqtt.dryad.app

31393

TCP

TLS/SSL (Secure)

Credentials

Secure Port

QoS

Dryad MQTT Topics

This section describes all the Dryad external MQTT topics that you can subscribe to, either insecurely or securely, along with examples:

Receive All Sensor Data from a Site

Use the topic Receive All Sensor Data from a Site to receive messages from all sensors deployed on a site. You will receive one sensor data reading at a time on the same MQTT topic.

We use the term 'sensor' to refer to a 'wildfire sensor,' which is a LoRaWAN end device that collects data, such as fire alerts, temperature, humidity, and air pressure, through its BME 688 gas sensor. The payload is created using this data, along with other information such as sensor ID, longitude, latitude, etc.

/sensor/envmon/<site serial id>/#

For example, to receive all sensor data from the site xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, the topic is as follows:

/sensor/envmon/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/#

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.

The JSON payload of the message you will receive looks something like this (Please note that every time the payload you receive contains data from a single wildfire sensor):

In some cases, you will receive MQTT messages with payloads where temperature, humidity and airQuality fields are missing, which is normal.

{
    "siteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "applicationNSId": "xxxxxxxx-xxxx-xxxx-xxxx-x",
    "sensorNSId": "sn-silvav2nxxx-xxxxxxxx-xxxx-xxxx-xx",
    "time": "2024-03-07T16:54:34.106672Z",
    "fireAlertStatus": 0,
    "temperature": 25.7,
    "humidity": 30,
    "airPressure": 67101.0,
    "latitude": 38.1714972222,
    "longitude": 23.7332222222,
    "batteryPct":98,
    "airQuality":659.0
  }

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.

Field
Type
Description

siteId

String

Unique identifier for the site where the sensor is deployed. It's the same as the site serial id.

Format:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

applicationNSId

String

The sensor's application ID

Format: xxxxxxxx-xxxx-xxxx-xxxx-x

sensorNSId

String

The sensor ID

time

Timestamp indicates the time the data was recorded. The format of the timestamp is "YYYY-MM-DDTHH:MM:SS.mmmmmmZ". For example, if the timestamp is 2024-03-07T16:54:34.106672Z the following can be extracted.

  • 2024-03-07: Indicates the date in the format of year-month-day.

  • T: Separates the date and time components.

  • 16:54:34.106672: Indicates the time in the format of hours:minutes:seconds.microseconds.

  • Z: Denotes that the timestamp is in Coordinated Universal Time (UTC), also known as Greenwich Mean Time (GMT).

fireAlertStatus

int

Represents the fire alert status:

  • 0 : No alert

  • 2 : Alert. Smoke/Fire detected

temperature

float

Temperature [ambient] reading by the sensor in Celcius.

humidity

float

Relative Humidity [ambient] reading by the sensor as a percentage.

airPressure

float

Air pressure reading recorded by the sensor in Pascal (Pa).

latitude

float

Latitude coordinates of the sensor's location.

longitude

float

Longitude coordinates of the sensor's location.

batteryPct

int

Battery capacity as percentage (%)

airQuality

float

Index for Air Quality (IAQ)

MQTT Clients

Dryad supports many commonly used MQTT clients. Currently, instructions for using the following MQTT clients are provided:

  • MQTTx

More to be added.

Eclipse Mosquitto

Eclipse Mosquitto's mosquitto_sub is part of the Mosquitto MQTT broker. With mosquitto_sub, you can subscribe to topics and also unsubscribe from topics.

Subscribe

With mosquitto_sub, the command syntax for subscribing to a topic is as follows:

mosquitto_sub -h <hostname> -p <port> -u <username> -P <password> [-–cafile <path_to_ca_cert.pem>] -t <message-topic> where,

  • -h <hostname>: Specifies the MQTT broker's hostname.

  • -p <port>: Specifies the MQTT broker's port number.

  • -u <username>: Specifies the username for authentication.

  • -P <password>: Specifies the password for authentication.

  • --cafile <path_to_ca_cert.pem>: [optional, only use with SSL] Specifies the path to the CA certificate file in PEM format.

  • -t <message-topic>: Specifies the MQTT topic you want to subscribe to.

Use -d to debug the messages, -i to set the client id, and -c to enable persistent client mode.

For example, to subscribe to the topic /sensor/envmon/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/#, the mosquitto_sub command is as follows:

Non-secure:

mosquitto_sub -h ext.mqtt.dryad.app -p 31383-u username-P password-t /sensor/envmon/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/#

Secure (uses ISRG Root X1 CA certificate):

mosquitto_sub -h ext.mqtt.dryad.app -p 31393 -u username -P password --cafile isrgrootx1.pem -t /sensor/envmon/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/#

Unsubscribe

With mosquitto_sub, the command syntax for unsubscribing from a topic is as follows:

mosquitto_sub -h <hostname> -p <port> -u <username> -P <password> [-–cafile <path_to_ca_cert.pem>]-U <unsub-topic>

where,

  • -h <hostname>: Specifies the MQTT broker's hostname.

  • -p <port>: Specifies the MQTT broker's port number.

  • -u <username>: Specifies the username for authentication.

  • -P <password>: Specifies the password for authentication.

  • --cafile <path_to_ca_cert.pem>: [optional, only use with SSL] Specifies the path to the CA certificate file in PEM format.

  • -U <unsub-topic>: Specifies the MQTT topic you want to unsubscribe from.

For example, to unsubscribe from the topic /sensor/envmon/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/#, the mosquitto_sub command is as follows:

Non-secure:

mosquitto_sub -h ext.mqtt.dryad.app -p 31383 -u username -P password -U /sensor/envmon/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/#

Secure (uses ISRG Root X1 CA certificate):

mosquitto_sub -h ext.mqtt.dryad.app -p 31393 -u username -P password --cafile isrgrootx1.pem -U /sensor/envmon/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/#

MQTTx

  • Start MQTTx.

  • Click on the + New Connection button.

  • You can connect to the Dryad's external MQTT broker in two ways:

    • Non-secure

    • Secure

  • To connect in a non-secure way, enter/configure the following parameters under the General section:

    • Name: Enter any name to identify your subscription.

    • Host: mqtt:// + ext.mqtt.dryad.app

    • Port: 31383

    • Client ID: Auto generated.

    • Username: Username for your site, provided through 1Password

    • Password: Password for your site, provided through 1Password

    • SSL/TLS: Off

  • To connect in a secure way, enter/configure the following parameters under the General section:

    • Name: Enter any name to identify your subscription.

    • Host: mqtts:// + ext.mqtt.dryad.app

    • Port: 31393

    • Client ID: Auto generated.

    • Username: Username for your site, provided through 1Password

    • Password: Password for your site, provided through 1Password

    • SSL/TLS: On

    • SSL Secure: On

  • After configuring the required parameters, click on the Connect button.

  • Once connected, you will see the following window. Click on the + New Subscription button.

  • The New Subscription window appears. In the New Subscription window, enter the topic to subscribe to. The format of the topic is as follows.

    • /sensor/envmon/<site_id>/#

  • Click on the Confirm button.

  • The sensor data from your site will now be displayed in MQTTx as it arrives at the Dryad cloud/application. Make sure to select JSON from the dropdown menu to view the sensor data in a properly formatted way.

  • The image below shows the sensor data under a non-secure connection (Port: 31383).

  • The image below shows the sensor data under a secure connection (Port: 31393).

The CONNACK message contains a return code indicating whether the connection is successful or not. Please refer to the official MQTT documentation’s section to find out the possible return (reason) codes.

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. Please refer to the official MQTT documentation's section to find out the possible return (reason) codes.

The site serial ID, username, and password will be provided separately via email with the username and password shared via a link. The 1Password link is valid for a period of 7 days.

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 . The ISRG Root X1 Certificate Authority (CA) certificate is available 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.

Dryad uses the default Quality of Service (QoS) level, which is QoS level 0 (delivery at most once) when publishing messages. So the maximum level of QoS the subscriber can expect is also 0. Read the Eclipse Mosquitto for more information.

String

You can find more about the command line options in the .

You can find more about the command line options in the .

This guide explains how to use as an MQTT client to subscribe to sensor data from Dryad's external MQTT broker. MQTTx provides you a GUI for configuring and connecting to any MQTT broker, allowing you to create subscriptions to receive data.

Download the and install it on your computer. It is available for Windows, Mac, and Linux, and you can also run it inside a Docker container.

Enter the following information in the New window. Here, we focus only on the basic and minimal parameters needed to create a subscription and connect to Dryad's external MQTT broker. Using other advanced parameters is beyond the scope of this example. You may refer to the for more information.

For more information, read .

Connect Reason Code
SUBACK payload
1Password
Let’s Encrypt
here
MQTT man page
mosquitto_sub manual
mosquitto_sub manual
MQTTx
MQTTx client
MQTTx documentation
MQTTx docs
Eclipse Mosquitto
ISO 8601
Dryad External MQTT Broker
Connect
Subscribe
Unsubcribe
MQTT Client Configuration
Credentials
Secure Port
QoS
Dryad MQTT Topics
Receive all Sensor Data from a Site
MQTT Clients
Eclipse Mosquitto
Subscribe
Unsubscribe
Dryad MQTT publish/subscribe architecture
Exchange of CONNECT/CONNACK messages
Exchange of SUBSCRIBE/SUBACK messages
Exchange of SUBSCRIBE/SUBACK/PUBLISH messages
Exchange of UNSUBSCRIBE/UNSUBACK messages