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:

• Subscribing to commands
• Device Management Protocol
• Clean or durable sessions

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

• event_id is the ID of the event, for example status. The event ID can be any string that is valid in MQTT. When receiving these event messages, the subscribing application can either use a wildcard to receive events with any ID or subscribe with an event_id that matches the event_id that the publisher used.
• format_string is a string that defines the content type of the message payload so that the receiver of the message can determine how to parse the content. Common content type values include but are not limited to "json", "xml", "txt", and "csv". The value can be any string that is valid in MQTT.

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

• command_id is the ID of the command, for example, update. The command ID can be any string that is valid in the MQTT protocol. When receiving these command messages, the subscribing device can either use a wildcard to receive commands with any ID or subscribe with a command_id that matches the command_id that the publisher used.
• format_string is a string that defines the content type of the command payload so that the receiver of the command can determine how to parse the content. Common content type values include but are not limited to "json", "xml", "txt", and "csv". The value can be any string that is valid in MQTT.

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:

• The managed device publishes device management responses on iotdevice-1/response.
• For other topics that a managed device can publish to, see Device Management Protocol and Device management requests.

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:

• d carries any data that is relevant to the request.
• reqId is an identifier of the request and must be copied into a response. If a response is not required, you can omit the reqId field.

Responses

Responses are formatted as shown in the following code sample:

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

Where:

• rc is a result code of the original request.
• message is an optional element with a text description of the response code.
• d is an optional data element that accompanies the response.
• reqId is the request ID of the original request, which is used to correlate responses with requests. The device must ensure that all request IDs are unique. Responses to Platform Service requests must include the correct reqId value.

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