MQTT API Reference

The DeviceHive MQTT API exposes the following services:

Client (Device)

The service allows clients to exchange messages with the DeviceHive server using a single persistent MQTT connection.

There is an ability to make a connection to the DeviceHive MQTT broker with the user credentials (e.g. username and password) or, after the connection is established, clients are able to authenticate using JSON Web Token, and then start sending commands to devices using the command/insert message or native MQTT publishing mechanism. As soon as a command is processed by a device, the server sends the command/update message.

After connection is established, devices need to register using the device/save message, perform authentication and then start sending notifications using the notification/insert message.

Clients may also subscribe to the device notifications using the native MQTT subscription mechanism and then start receiving server-originated messages about new device notifications.

Devices may also subscribe to commands using the native MQTT subscription mechanism and then start receiving server-originated messages about new commands.

Native MQTT functionality

• MQTT 3.1 and 3.1.1 compliant.
• QoS 0 and QoS 1.
• Last will functionality

MQTT Client basic connection options

Connection options mentioned above a bit depend on the tool that are used to implement MQTT client functionality (e.g. programming language, library, framework...). Please, read the documentation of the tool that you use before configuring MQTT client.

DeviceHive MQTT topic structure

DeviceHive MQTT Broker gives an ability for clients to communicate with DeviceHive server using MQTT topics in specific format described below. However, in the same time, ordinary MQTT topics also available for clients. Furthermore, clients are able to use them without any authentication.

Request

To make a request to the DeviceHive a client should publish a message with specific action field to the dh/request topic. List of supported actions is mentioned below (API list part)

Example:

mqttClient.publish('dh/request', '{"action":"device/list"}');

Response

To receive a response a client should subscribe for topic with the next structure:

dh/response/{request-action}@{client-id}

Where:

• request-action - action field mentioned in request
• client-id - MQTT client own id

The @{client-id} part of the topic is mandatory. It gives an ability to Broker to send response only to request originator

Example:

mqttClient.subscribe('dh/response/device/list@mqttClientId');

Notification/Command publishing

Notification insert topic template:
dh/notification/{network-id}/{devicetype-id}/{device-id}/{notification-name}

Command insert topic template:
dh/command/{network-id}/{devicetype-id}/{device-id}/{command-name}

Command update topic template:
dh/command_update/{network-id}/{devicetype-id}/{device-id}/{command-name}

Where:

• network-id - DeviceHive Network ID
• devicetype-id - DeviceHive DeviceType ID
• device-id - DeviceHive Device ID
• notification-name - Notification name
• command-name - Command name

Example:

mqttClient.publish('dh/notification/network1/devicetype1/device1/temperature', notificationObject);
mqttClient.publish('dh/command/network1/devicetype1/device1/light', commandObject);
mqttClient.publish('dh/command_update/network1/devicetype1/device1/light', updatedCommandObject);

Notification/Command subscrubtion/unsubscription

Notification insert subscription topic template:
dh/notification/{network-id}/{devicetype-id}/{device-id}/{notification-name}

Command insert subscription topic template:
dh/command/{network-id}/{devicetype-id}/{device-id}/{command-name}

Command update subscription topic template:
dh/command_update/{network-id}/{devicetype-id}/{device-id}/{command-name}

Where:

• network-id - DeviceHive Network ID
• devicetype-id - DeviceHive DeviceType ID
• device-id - DeviceHive Device ID
• notification-name - Notification name
• command-name - Command name

Example:

client.subscribe('dh/notification/network1/devicetype1/device1/temperature');
    client.subscribe('dh/command/network1/devicetype1/device1/light');
    client.subscribe('dh/command_update/network1/devicetype1/device1/light');

Subscription topic wildcards

There is an ability to subscribe to the wide range of networks/devicetypes/devices/names

MQTT supports the next wildcards:

• + - single level wildcard
• # - multi level wildcard

Example:

// Global notification subscription
    client.subscribe('dh/notification/#');
    // Subscription for a specific command name on any device on  mentioned network and with specific device type
    client.subscribe('dh/command/network1/devicetype1/+/light');
    // Subscription for command update with any name but with a specific device type on every network and device
    client.subscribe('dh/command_update/+/devicetype1/#');

API list

More information on GitHub:
DeviceHive MQTT Broker