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
Option | Mandatory | Type | Default | Description |
---|---|---|---|---|
Host | yes | String | - | DeviceHive MQTT Broker host address |
Port | yes | Number | 1883 | DeviceHive MQTT Broker port |
Client Id | yes | String | - | Client (Device) identificator. |
Keepalive | no | Number | 60 sec | The keep alive functionality assures that the connection is still open and both broker and client are connected to one another. Set to 0 to disable |
Username | no | String | - | DeviceHive user's login |
Password | no | String | - | DeviceHive user's password |
Clean | no | Boolean | false | Set to false to receive QoS 1 and 2 messages while offline |
Last will | no | Depends on client realization | - | A message that will sent by the broker automatically when the client disconnect badly |
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
Request (Publish) | Response (Subscription) topic | Originator | Authorization | Description |
---|---|---|---|---|
Topic: dh/request Payload action: authenticate | dh/response/authenticate@ | Client/Device | None | Authenticates a client by a JSON Web Token. |
Topic: dh/request Payload action: configuration/get | dh/response/configuration/get@ | Client/Device | Access JSON Web Token (ManageConfiguration) | Returns requested property value. |
Topic: dh/request Payload action: configuration/put | dh/response/configuration/put@ | Client/Device | Access JSON Web Token (ManageConfiguration) | Creates new or updates existing property. |
Topic: dh/request Payload action: configuration/delete | dh/response/configuration/delete@ | Client/Device | Access JSON Web Token (ManageConfiguration) | Deletes a property. |
Topic: dh/request Payload action: command/get | dh/response/command/get@ | Client/Device | Access JSON Web Token (GetDeviceCommand) | Gets information about the command. |
Topic: dh/request Payload action: command/list | dh/response/command/list@ | Client/Device | Access JSON Web Token (GetDeviceCommand) | Gets the list of commands. |
Topic: dh/request Payload action: command/insert | dh/response/command/insert@ | Client/Device | Access JSON Web Token (CreateDeviceCommand) | Creates new device command. |
Topic: dh/request Payload action: command/subscribe | dh/response/command/subscribe@ | Client/Device | Access JSON Web Token (GetDeviceCommand) | Subscribes to device commands. After subscription is completed, the server will start to send command/insert messages to the connected user. |
Topic: dh/request Payload action: command/unsubscribe | dh/response/command/unsubscribe@ | Client/Device | Access JSON Web Token (GetDeviceCommand) | Unsubscribes from device commands. |
Topic: dh/request Payload action: command/update | dh/response/command/update@ | Client/Device | Access JSON Web Token (UpdateDeviceCommand) | Updates an existing device command on behalf of device. |
Topic: dh/request Payload action: deviceget | dh/response/device/get@ | Client/Device | Access JSON Web Token (GetDevice) | Gets information about the current device. |
Topic: dh/request Payload action: device/list | dh/response/device/list@ | Client/Device | Access JSON Web Token (GetDevice) | Gets the list of devices. |
Topic: dh/request Payload action: device/count | dh/response/device/count@ | Client/Device | Access JSON Web Token (RegisterDevice) | Gets count of devices. |
Topic: dh/request Payload action: device/save | dh/response/device/save@ | Client/Device | Access JSON Web Token (GetDevice) | Registers or updates a device. |
Topic: dh/request Payload action: device/delete | dh/response/device/delete@ | Client/Device | Access JSON Web Token (RegisterDevice) | Deletes a device. |
Topic: dh/request Payload action: devicetype/list | dh/response/devicetype/list@ | Client/Device | Access JSON Web Token (GetDeviceType) | Gets list of device types. The result list is limited to device types the client has access to. |
Topic: dh/request Payload action: devicetype/count | dh/response/devicetype/count@ | Client/Device | Access JSON Web Token (GetDeviceType) | Gets count of device types the client has access to. |
Topic: dh/request Payload action: devicetype/get | dh/response/devicetype/get@ | Client/Device | Access JSON Web Token (GetDeviceType) | Gets information about device type and its devices. |
Topic: dh/request Payload action: devicetype/insert | dh/response/devicetype/insert@ | Client/Device | Access JSON Web Token (ManageDeviceType) | Creates new device type. |
Topic: dh/request Payload action: devicetype/update | dh/response/devicetype/update@ | Client/Device | Access JSON Web Token (ManageDeviceType) | Updates an existing device type. |
Topic: dh/request Payload action: devicetype/delete | dh/response/devicetype/delete@ | Client/Device | Access JSON Web Token (ManageDeviceType) | Deletes an existing device type. |
Topic: dh/request Payload action: network/list | dh/response/network/list@ | Client/Device | Access JSON Web Token (GetNetwork) | Gets the list of networks. |
Topic: dh/request Payload action: network/count | dh/response/network/count@ | Client/Device | Access JSON Web Token (GetNetwork) | Gets count of networks. |
Topic: dh/request Payload action: network/get | dh/response/network/get@ | Client/Device | Access JSON Web Token (GetNetwork) | Gets a network by ID. |
Topic: dh/request Payload action: network/insert | dh/response/network/insert@ | Client/Device | Access JSON Web Token (ManageNetwork) | Inserts new network. |
Topic: dh/request Payload action: network/update | dh/response/network/update@ | Client/Device | Access JSON Web Token (ManageNetwork) | Updates a network. |
Topic: dh/request Payload action: network/delete | dh/response/network/delete@ | Client/Device | Access JSON Web Token (ManageNetwork) | Deletes a network by ID. |
Topic: dh/request Payload action: user/list | dh/response/user/list@ | Client/Device | Access JSON Web Token () | Gets list of users. |
Topic: dh/request Payload action: user/count | dh/response/user/count@ | Client/Device | Access JSON Web Token () | Gets count of users. |
Topic: dh/request Payload action: userget | dh/response/user/get@ | Client/Device | Access JSON Web Token () | Gets information about user and its assigned networks. |
Topic: dh/request Payload action: user/insert | dh/response/user/insert@ | Client/Device | Access JSON Web Token () | Creates new user |
Topic: dh/request Payload action: user/update | dh/response/user/update@ | Client/Device | Access JSON Web Token () | Updates an existing user. |
Topic: dh/request Payload action: user/delete | dh/response/user/delete@ | Client/Device | Access JSON Web Token () | Deletes an existing user. |
Topic: dh/request Payload action: user/getCurrent | dh/response/user/getCurrent@ | Client/Device | Access JSON Web Token () | Gets information about user and its assigned networks. |
Topic: dh/request Payload action: user/updateCurrent | dh/response/user/updateCurrent@ | Client/Device | Access JSON Web Token () | Updates an existing user. |
Topic: dh/request Payload action: user/getNetwork | dh/response/user/getNetwork@ | Client/Device | Access JSON Web Token () | Gets information about user/network association. |
Topic: dh/request Payload action: user/assignNetwork | dh/response/user/assignNetwork@ | Client/Device | Access JSON Web Token () | Associates network with the user. |
Topic: dh/request Payload action: user/unassignNetwork | dh/response/user/unassignNetwork@ | Client/Device | Access JSON Web Token () | Removes association between network and user. |
Topic: dh/request Payload action: notification/get | dh/response/notification/get@ | Client/Device | Access JSON Web Token (GetDeviceNotification) | Gets information about the notification. |
Topic: dh/request Payload action: notification/list | dh/response/notification/list@ | Client/Device | Access JSON Web Token (GetDeviceNotification) | Gets the list of notifications. |
Topic: dh/request Payload action: notification/insert | dh/response/notification/insert@ | Client/Device | Access JSON Web Token (CreateDeviceNotification) | Creates new device notification on behalf of device. |
Topic: dh/request Payload action: notification/subscribe | dh/response/notification/subscribe@ | Client/Device | Access JSON Web Token (GetDeviceNotification) | Subscribes to device notifications. After subscription is completed, the server will start to send notification/insert messages to the connected user. |
Topic: dh/request Payload action: notification/unsubscribe | dh/response/notification/unsubscribe@ | Client/Device | Access JSON Web Token (GetDeviceNotification) | Unsubscribes from device notifications. |
Topic: dh/request Payload action: subscription/list | dh/response/subscription/list@ | Client/Device | Access JSON Web Token (GetDeviceCommand or GetDeviceNotification) | Returns list of user subscriptions. |
Topic: dh/request Payload action: server/info | dh/response/server/info@ | Client/Device | None | Gets meta-information about the current API. |
Topic: dh/request Payload action: token | dh/response/token@ | Client/Device | None | Creates access and refresh tokens by login and password. |
Topic: dh/request Payload action: token/create | dh/response/token/create@ | Client/Device | Access JSON Web Token (ManageToken) | Creates access and refresh tokens by payload. |
Topic: dh/request Payload action: token/refresh | dh/response/token/refresh@ | Client/Device | None | Refreshes access token by refresh token. |
broker: command/insert | dh/command/{network-id}/{device-type-id}/{device-id}/{command-name} | Broker | n/a | Notifies the user about new device command. |
broker: command/update | dh/command_update/{network-id}/{device-type-id}/{device-id}/{command-name} | Broker | n/a | Notifies the user about a command has been processed by a device. These messages are sent only for commands created by the current user within the current connection. |
broker: notification/insert | dh/notification/{network-id}/{device-type-id}/{device-id}/{command-name} | Broker | n/a | Notifies the user about new device notification. |
More information on GitHub:
DeviceHive MQTT Broker
Updated over 6 years ago