This document provides details regarding the Dryad MQTT Sensor Data Integration.
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.
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.
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.
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.
Return code
Description
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
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
Credentials
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.
Secure Port
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.
QoS
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.
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:
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.
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
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:
You can find more about the command line options in the .
MQTTx
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.
Start MQTTx.
Click on the + New Connection button.
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.
You can connect to the Dryad's external MQTT broker in two ways:
Non-secure
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
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).
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).
The scope of this document is to provide customers with a 'preview' of how Dryad sensor data is can be accessed using Webhooks.
Webhook integration "Preview" document
Disclaimer: The schemas (data fields) of webhook messages you receive in your application may be updated at any time without prior notice, but only backwards compatible changes will be made (adding fields, we won't delete fields, nor change the name or type of fields). While we strive to keep this documentation up-to-date, please refer to the built-in svix documentation (Event Catalog in your Integration Application) for the latest information.
Table of Contents
Dryad allows customers to receive sensor data via webhooks using the new Silvanet API integration feature in the Silvanet Site Management Application.
What is a Webhook
Webhooks send messages on specific events in formats like JSON, XML, or form-encoded data to specific HTTP(S) endpoints configured in your application. Silvanet uses JSON as the content type for its webhook messages.
How Webhooks Work
A webhook is a service that listens for specific events and sends a message to a designated URL (the endpoint) on your application when those events occur. For example, Dryad can send a webhook every time a fire alert event occurs, which will then be displayed in your application within the Silvanet Site Management Application.
The webhook consists of the following entities:
Messages - These are the webhooks being sent. A message can have contents and a few other properties.
Application - This is where the messages are sent to. You can create one application per organization on your platform.
Endpoints - Endpoints are the URLs messages will be sent to. Each application can have multiple endpoints, and each message sent to that application will be delivered to all of them, unless you are not subscribed to specific events for each endpoint. Endpoints listen for webhook messages.
The following diagram shows how webhooks are sent to your endpoint if a specific event occurs.
Advantages of Using Webhooks
Customers can add any number of endpoints to their application (Webhook Portal) and edit them.
Customers can choose which event types are sent to which endpoint. By default, all messages are sent to all endpoints.
Webhooks use stateless HTTP requests to ensure that no persistent connections are required.
Webhook Configuration
The Silvanet API integration feature in the Silvanet Site Management Application allows you to configure webhooks by creating an application for each organization you have and then adding endpoints to each application. With these endpoints, you can subscribe to the event types you want, view messages, and recover/replay past and failed messages.
Only Admins and Super Admins are allowed to use the Silvanet API integration feature to create applications and configure additional settings.
Creating an Integration Application
Log in to the Silvanet Site Management Application using your credentials.
On the sidebar, click API Integration.
The Silvanet API Integration dashboard appears.
Click on the Create Application button to create a new integration application.
In the Create a New Integration Application dialog box, select the organization for which you want to create the application. For example, Dryad Internal.
You can create only one application per organization.
Click on the Submit button to create the application.
The application you created will be listed under Current API Integrations.
Adding an Endpoint
To receive messages, you need to add an endpoint to the Application. Of course, you can add more than one endpoint.
On the Silvanet API Integration page, under Current API Integrations, click on the application name you want to configure.
The application page appears, and the application name can be seen at the top left of the page.
Click Endpoints tab if it is not selected by default.
You can add more than one endpoint for each application.
On the New Endpoint page, configure the following:
Endpoint URL -Enter your endpoint URL here. If you don't have an endpoint, you can click on the option "Configure an endpoint or test with Svix Play." This will automatically generate an endpoint and fill the textbox for you. You can also use a service like to generate a URL for your HTTP endpoint.
Description - Enter an optional description here mentioning what the endpoint is used for.
Subscribe to events - Select one or more event types that you want to subscribe to by clicking on the checkboxes. If you want to add all the event types of a specific group, just click on the group.
If you don't subscribe to any event types, your endpoint will receive messages for all event types by default.
(Optional) Advanced Configuration - click to expand this section.
Rate Limit (per second) - provide the maximum number of webhook messages allowed to send to this endpoint per second. For example, enter 10
Click on the Create button.
The endpoint is added to your application. Your page should look something similar to the following:
Viewing Messages
With the Endpoints tab selected, scroll down the page until you can see the table view. It shows all the received messages with their EVENT TYPE, MESSAGE ID, and TIMESTAMP.
From the table, click a message to view its content. You will be switched to the Logs tab. The message content is simply a JSON object.
Message Attempts
There are two types of message attempts, labelled as:
indicates a webhook event that was successful and has sent a webhook message to your application.
indicates a webhook event that failed due to the unavailability or disabling of the endpoint, or because of a server error.
Replay Messages
Use the following options to replay messages to recover past and failed messages:
Replay all messages - You can replay the past or failed all the messages using the replay button to receive those webhook messages to your application.
This option is suitable to replay all the messages from some point in the past.
In the table, use the TIMESTAMP to find the message that closest to the desired time. For example, if you want to replay all messages starting from 2:54 PM, locate the message with the nearest timestamp. Click on the
The following dialog box will appear with three options:
Resend this message - select this option to replay the message you selected from the table.
Resend all failed messages since - this will replay all the failed messages since the event time of this message.
Filtering Event Types / Messages
There are several ways you can filter messages.
Filter event types or messages by message attempts using the following buttons:
All
Succeeded
Event Catalog
The Event Catalog can be treated as the built-in svix documentation for webhook integration, which provides up-to-date information about event types, their schemas, and examples.
Disclaimer: The schemas (data fields) of webhook messages you receive in your application may be updated at any time without prior notice, but only backwards compatible changes will be made (adding fields, we won't delete fields, nor change the name or type of fields). While we strive to keep this documentation up-to-date, please refer to the built-in svix documentation (Event Catalog in your Integration Application) for the latest information.
Click Event Catalog tab. It lists and describes all the event types we expose.
Event Types
Click on an event type to expand its content. You can see its schema and example JSON payload.
Currently Dryad exposes three event types:
alert-event.new
A new relevant gas scan has been received in the context of an active alert.
Follow the steps below if you want to update the endpoint URL.
Navigate to your application and select the Endpoints tab if it is not selected by default. Then select the Endpoint you want to edit under the Endpoints. This will expand the Endpoint configuration section.
Click on the Edit button next to the existing endpoint URL.
Replace the existing endpoint URL with the new endpoint URL.
Click on the Save button.
Editing Subscribed Events
With your application, you can edit your subscribed events on each endpoint at any time.
Navigate to your application and select the Endpoints tab if it is not selected by default. Then select the Endpoint you want to edit the subscribed events. This will expand the Endpoint configuration section.
In the right-side panel, under the Subscribed Events section, you can see which events you are subscribed to for this endpoint.
Click the Edit button.
Select or deselect the event types you want to subscribe to or unsubscribe from.
Click the Save button.
Testing Endpoints
This feature allows you to test your endpoint to see if it will receive messages.
Navigate to your application and select the Endpoints tab if it is not selected by default. Then select the Endpoint you want to test. This will expand the Endpoint configuration section.
Go to the Testing tab.
Select an event type from the dropdown you want to test.
Once you select an event type, its schema will display on the page along with an example JSON payload so you can see what fields will be sent with the message.
Click Send Example button to send the message.
After sending a message for an event, if successful, you will be able to see it on the Overview tab.
Disabling an Endpoint
Navigate to your application and select the Endpoints tab, if it is not selected by default. Then select the Endpoint you want to disable. This will expand the Endpoint configuration section.
Disabling an endpoint will stop messages from being sent to that endpoint.
In the top-right menu, click Disable Endpoint.
Once disabled, a label named Disabled will appear on the endpoint page, as shown below.
To enable the endpoint again, click Enable Endpoint from the same menu.
Deleting an Endpoint
Navigate to your application and select the Endpoints tab, if it is not selected by default. Then select the Endpoint you want to delete. This will expand the Endpoint configuration section.
On the top-right menu, click Delete. This will permanently delete the endpoint from your application and cannot be undone.
