Communicating with devices (MQTT)

The primary protocol that devices and applications use to communicate with the Platform Service is MQTT. Client libraries, information, and samples are provided to help you to connect and integrate your devices with Platform Service.

Quickstart service

The Quickstart service is the fastest level of service. It offers no confirmation of receipt and does not support MQTT quality of service (QoS) levels greater than zero. When you connect to the Quickstart service, authentication or registration is not required, and the orgId must be set to quickstart.

If you are writing device code for use with Quickstart, be aware that the following Platform Service service features are not supported in Quickstart mode:

Messages that are sent from devices at a rate greater than one per second might be discarded.

MQTT authentication

For devices, Platform Service uses MQTT token-based authentication.

To enable MQTT authentication, submit a user name and password when you make an MQTT connection.

User name

The user name is the same value for all devices: use-token-auth. This value causes Platform Service to use the device's authentication token, which is specified as the password.

Password

The password for each device is the unique authentication token that was generated when the device was registered with Platform Service.

Client ID

The MQTT client ID is in the format d:orgId:deviceType:deviceId.

Publishing events

Devices publish to the event topics in the following format:

iot-2/evt/event_id/fmt/format_string

Where

Important: The message payload is limited to a maximum of 131072 bytes. Messages larger than this limit are rejected.

Retained messages

Platform Service organizations are not authorized to publish retained MQTT messages. If a device sends a retained message, the Platform Service service overrides the retained message flag when it is set to true and processes the message as if the retained message flag is set to false.

Subscribing to commands

Devices can subscribe to command topics in the following format:

iot-2/cmd/command_id/fmt/format_string

Where

Devices cannot subscribe to events from other devices. A device receives commands that are published only to its own device.

Managing devices

Support for device lifecycle management is optional. The Device Management Protocol uses the same MQTT connection that your device already uses for events and command control.

Quality of service levels and durability of subscriptions

Managed devices can publish messages that have a quality of service (QoS) level of 0, 1, or 2.

Messages that have a QoS level of 0 can be discarded and do not persist after the messaging server is restarted. Messages that have a QoS level of 1 can be queued and do persist after the messaging server is restarted. The durability of the subscription determines whether a request is queued. For MQTT V5.0, the durability is controlled by the session expiry interval parameter. For MQTT V3.1 and V3.1.1, the parameter is clean session. Devices can publish messages at QoS2, but the device management server publishes and subscribes at QoS1, so the response messages are only QoS1.

Platform Service publishes requests that have a QoS level of 1 to support queuing of messages.

For MQTT V5.0, to queue messages that are sent while a managed device is not connected, configure the device to use durable subscriptions by setting the clean start parameter to false and the session expiry interval parameter to a nonzero value. Note: The session expiry interval determines the number of seconds to keep the data. It must be set to an appropriate value that varies depending on the application.

For MQTT V3.1.1 or V3.1, to queue messages that are sent while a managed device is not connected, configure the device to not use clean sessions by setting the clean session parameter to false.

Warning: If your managed device uses a durable subscription, any commands that are sent to your device while it is offline are reported as failed operations if the device does not reconnect to the service before the request times out. However, when the device reconnects, those requests are processed by the device. For MQTT V5.0, a durable subscription is specified when the clean start parameter is set to false and the session expiry interval parameter is set to a nonzero value. For MQTT V3.1.1 or V3.1, a durable subscription is specified when the clean session parameter is set to false.

Topics

A managed device is required to subscribe to the following topic to handle requests and responses from the Platform Service service:

iotdm-1/#

A managed device publishes to topics that are specific to the type of management request that is being performed:

Message format

All messages are sent in JSON format.

Requests

Requests are formatted as shown in the following code sample:

{  "d": {...}, "reqId": "b53eb43e-401c-453c-b8f5-94b73290c056" }

Where:

Responses

Responses are formatted as shown in the following code sample:

        {
            "rc": 0,
            "message": "success",
            "d": {...},
            "reqId": "b53eb43e-401c-453c-b8f5-94b73290c056"
        }

Where:

For more information about specific request and response messages, see Device Management Protocol and Device Management Requests.