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/[email protected]');

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/[email protected]

Client/Device

None

Authenticates a client by a JSON Web Token.

Topic: dh/request
Payload action: configuration/get

dh/response/configuration/[email protected]

Client/Device

Access JSON Web Token (ManageConfiguration)

Returns requested property value.

Topic: dh/request
Payload action: configuration/put

dh/response/configuration/[email protected]

Client/Device

Access JSON Web Token (ManageConfiguration)

Creates new or updates existing property.

Topic: dh/request
Payload action: configuration/delete

dh/response/configuration/[email protected]

Client/Device

Access JSON Web Token (ManageConfiguration)

Deletes a property.

Topic: dh/request
Payload action: command/get

dh/response/command/[email protected]

Client/Device

Access JSON Web Token (GetDeviceCommand)

Gets information about the command.

Topic: dh/request
Payload action: command/list

dh/response/command/[email protected]

Client/Device

Access JSON Web Token (GetDeviceCommand)

Gets the list of commands.

Topic: dh/request
Payload action: command/insert

dh/response/command/[email protected]

Client/Device

Access JSON Web Token (CreateDeviceCommand)

Creates new device command.

Topic: dh/request
Payload action: command/subscribe

dh/response/command/[email protected]

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/[email protected]

Client/Device

Access JSON Web Token (GetDeviceCommand)

Unsubscribes from device commands.

Topic: dh/request
Payload action: command/update

dh/response/command/[email protected]

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/[email protected]

Client/Device

Access JSON Web Token (GetDevice)

Gets information about the current device.

Topic: dh/request
Payload action: device/list

dh/response/device/[email protected]

Client/Device

Access JSON Web Token (GetDevice)

Gets the list of devices.

Topic: dh/request
Payload action: device/count

dh/response/device/[email protected]

Client/Device

Access JSON Web Token (RegisterDevice)

Gets count of devices.

Topic: dh/request
Payload action: device/save

dh/response/device/[email protected]

Client/Device

Access JSON Web Token (GetDevice)

Registers or updates a device.

Topic: dh/request
Payload action: device/delete

dh/response/device/[email protected]

Client/Device

Access JSON Web Token (RegisterDevice)

Deletes a device.

Topic: dh/request
Payload action: devicetype/list

dh/response/devicetype/[email protected]

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/[email protected]

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/[email protected]

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/[email protected]

Client/Device

Access JSON Web Token (ManageDeviceType)

Creates new device type.

Topic: dh/request
Payload action: devicetype/update

dh/response/devicetype/[email protected]

Client/Device

Access JSON Web Token (ManageDeviceType)

Updates an existing device type.

Topic: dh/request
Payload action: devicetype/delete

dh/response/devicetype/[email protected]

Client/Device

Access JSON Web Token (ManageDeviceType)

Deletes an existing device type.

Topic: dh/request
Payload action: network/list

dh/response/network/[email protected]

Client/Device

Access JSON Web Token (GetNetwork)

Gets the list of networks.

Topic: dh/request
Payload action: network/count

dh/response/network/[email protected]

Client/Device

Access JSON Web Token (GetNetwork)

Gets count of networks.

Topic: dh/request
Payload action: network/get

dh/response/network/[email protected]

Client/Device

Access JSON Web Token (GetNetwork)

Gets a network by ID.

Topic: dh/request
Payload action: network/insert

dh/response/network/[email protected]

Client/Device

Access JSON Web Token (ManageNetwork)

Inserts new network.

Topic: dh/request
Payload action: network/update

dh/response/network/[email protected]

Client/Device

Access JSON Web Token (ManageNetwork)

Updates a network.

Topic: dh/request
Payload action: network/delete

dh/response/network/[email protected]

Client/Device

Access JSON Web Token (ManageNetwork)

Deletes a network by ID.

Topic: dh/request
Payload action: user/list

dh/response/user/[email protected]

Client/Device

Access JSON Web Token ()

Gets list of users.

Topic: dh/request
Payload action: user/count

dh/response/user/[email protected]

Client/Device

Access JSON Web Token ()

Gets count of users.

Topic: dh/request
Payload action: userget

dh/response/user/[email protected]

Client/Device

Access JSON Web Token ()

Gets information about user and its assigned networks.

Topic: dh/request
Payload action: user/insert

dh/response/user/[email protected]

Client/Device

Access JSON Web Token ()

Creates new user

Topic: dh/request
Payload action: user/update

dh/response/user/[email protected]

Client/Device

Access JSON Web Token ()

Updates an existing user.

Topic: dh/request
Payload action: user/delete

dh/response/user/[email protected]

Client/Device

Access JSON Web Token ()

Deletes an existing user.

Topic: dh/request
Payload action: user/getCurrent

dh/response/user/[email protected]

Client/Device

Access JSON Web Token ()

Gets information about user and its assigned networks.

Topic: dh/request
Payload action: user/updateCurrent

dh/response/user/[email protected]

Client/Device

Access JSON Web Token ()

Updates an existing user.

Topic: dh/request
Payload action: user/getNetwork

dh/response/user/[email protected]

Client/Device

Access JSON Web Token ()

Gets information about user/network association.

Topic: dh/request
Payload action: user/assignNetwork

dh/response/user/[email protected]

Client/Device

Access JSON Web Token ()

Associates network with the user.

Topic: dh/request
Payload action: user/unassignNetwork

dh/response/user/[email protected]

Client/Device

Access JSON Web Token ()

Removes association between network and user.

Topic: dh/request
Payload action: notification/get

dh/response/notification/[email protected]

Client/Device

Access JSON Web Token (GetDeviceNotification)

Gets information about the notification.

Topic: dh/request
Payload action: notification/list

dh/response/notification/[email protected]

Client/Device

Access JSON Web Token (GetDeviceNotification)

Gets the list of notifications.

Topic: dh/request
Payload action: notification/insert

dh/response/notification/[email protected]

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/[email protected]

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/[email protected]

Client/Device

Access JSON Web Token (GetDeviceNotification)

Unsubscribes from device notifications.

Topic: dh/request
Payload action: subscription/list

dh/response/subscription/[email protected]

Client/Device

Access JSON Web Token (GetDeviceCommand or GetDeviceNotification)

Returns list of user subscriptions.

Topic: dh/request
Payload action: server/info

dh/response/server/[email protected]

Client/Device

None

Gets meta-information about the current API.

Topic: dh/request
Payload action: token

dh/response/[email protected]

Client/Device

None

Creates access and refresh tokens by login and password.

Topic: dh/request
Payload action: token/create

dh/response/token/[email protected]

Client/Device

Access JSON Web Token (ManageToken)

Creates access and refresh tokens by payload.

Topic: dh/request
Payload action: token/refresh

dh/response/token/[email protected]

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