Publishing over MQTT

This section explains how devices can use the MQTT bridge to communicate with ClearBlade IoT Core. For HTTP and MQTT information, see Protocols.

To publish over the MQTT bridge:

1. Install an MQTT client on your device.

2. Download an MQTT server certificate onto your device.

3. Configure the MQTT client to authenticate the device to ClearBlade IoT Core.

4. Initiate a TLS handshake over the appropriate MQTT regional URL or an external proxy run in your instance group.

5. Publish telemetry events or set the device state.

MQTT server

ClearBlade IoT Core supports the MQTT protocol by running a managed broker that listens to port 8883. Port 8883 is the standard TCP port reserved with IANA for secure MQTT connections. Connections to this port must use TLS transport, supported by open-source clients like Eclipse Paho.

If your firewall blocks port 8883, you can use port 443.

The MQTT standard is defined for implementing a full publish/subscribe broker. However, the managed MQTT bridge run by ClearBlade IoT Core does not support all publish/subscribe operations, such as creating arbitrary topics that devices can use to send messages between them. Filtering can be accomplished with downstream processes running on Cloud Pub/Sub. ClearBlade IoT Core uses a predefined set of topics and specific topic formats.

Quality of service (QoS)

The MQTT specification describes three QoS levels:

• QoS 0, delivered at most once

• QoS 1, delivered at least once

• QoS 2, delivered exactly once

ClearBlade IoT Core does not support QoS 2. Publishing QoS 2 messages closes the connection, and subscribing to a predefined topic with QoS 2 downgrades the QoS level to QoS 1.

QoS 0 and 1 function as follows in ClearBlade IoT Core:

• A PUBLISH message with QoS 1 will be acknowledged by the PUBACK message after successfully sending it to Cloud Pub/Sub.

• PUBLISH messages with QoS 0 do not require PUBACK responses. They may be dropped if there is any jitter along the message delivery path (for example, if Cloud Pub/Sub is temporarily unavailable).

• The ClearBlade IoT Core MQTT bridge maintains a small buffer of undelivered messages to retry them. If the buffer becomes full, the message with QoS 1 may be dropped, and a PUBACK message will not be sent to the client. The client is expected to resend the message.

For device configurations, QoS levels are as follows:

• When QoS is 0, a given configuration version will be published to the device only once. If the device does not receive the configuration, it must resubscribe. A QoS of 0 is thus useful when a configuration is frequently updated (on the order of seconds or minutes), and the device only needs to receive some updates.

• When QoS is 1, the latest configuration update will be retried until the device acknowledges it with a PUBACK. If a newer configuration is pushed before the older one is acknowledged, the older one will not be redelivered; instead, the new one will be delivered (and redelivered). This level is the safest mode for device configurations: it guarantees the device will eventually get the latest configuration.

Downloading MQTT server certificates

ClearBlade uses DigiCert-based certificates (long-term support, 2031, and 1.3K in size). The minimal root ca file can be found here.

Configuring MQTT clients

MQTT clients authenticate devices by connecting to the MQTT bridge. To configure an MQTT client to authenticate a device:

1. Set the MQTT client ID to the full device path:

   CODE

   projects/PROJECT_ID/locations/REGION/registries/REGISTRY_ID/devices/DEVICE_ID

2. Associate the MQTT client with MQTT server certificates.

3. Choose the appropriate MQTT host name.

4. Specify a username. The MQTT bridge ignores the username field, but some MQTT client libraries will not send the password field unless the username field is specified. For best results, supply an arbitrary username like unused or ignored.

5. Set the password. The password field must contain the JWT.

Publishing telemetry events

After the device is configured with an MQTT client and connected to the MQTT bridge, it can publish a telemetry event by issuing a PUBLISH message to an MQTT topic in this format:

/devices/DEVICE_ID/events

The device ID is the device’s string ID specified in the MQTT client ID. The device ID is case-sensitive.

Messages published to this MQTT topic are forwarded to the corresponding registry's default telemetry topic. The default telemetry topic is the Cloud Pub/Sub topic specified in the eventNotificationConfigs[i].pubsubTopicName field in the registry resource. If no default Pub/Sub topic exists, published telemetry data will be lost.

The forwarded message data field contains a message’s copy published by the device, and the following message attributes are added to each message in the Cloud Pub/Sub topic:

If you try to publish a device telemetry event without specifying a Cloud Pub/Sub topic for the device's registry, the MQTT connection closes automatically. To verify why the connection closed, get the device details and check the lastErrorStatus field in the response. This applies only to telemetry events, not state data.

Publishing telemetry events to additional Cloud Pub/Sub topics

Devices can publish data to additional Cloud Pub/Sub topics. By default, MQTT messages published to /devices/DEVICE_ID/events are forwarded to the corresponding registry's default telemetry topic. You can specify a subfolder in the MQTT topic to forward data to additional Cloud Pub/Sub topics. The subfolder is the subtopic after /devices/DEVICE_ID/events.

Messages published to a subfolder are forwarded to the Cloud Pub/Sub topic with the same name. The corresponding registry must be configured with the Cloud Pub/Sub topic; otherwise, messages are forwarded to the default Cloud Pub/Sub topic.

Messages are forwarded to the default Cloud Pub/Sub topic instead of the additional Cloud Pub/Sub topic in these cases:

• No subfolder is specified in the MQTT topic

• A subfolder is specified in the MQTT topic but doesn't have a matching device registry’s Pub/Sub topic

For example, if the device publishes to the MQTT topic /devices/DEVICE_ID/events/alerts, the subfolder is the string alerts. Messages are forwarded to the additional Cloud Pub/Sub topic if the eventNotificationConfigs[i].subfolderMatches and eventNotificationConfigs[i].pubsubTopicName fields are set to alerts. Otherwise, messages are forwarded to the default Cloud Pub/Sub topic.

Setting device state

Connected devices can report the device state by issuing a PUBLISH message to the following MQTT topic:

/devices/DEVICE_ID/state

Configure the registry with a device state topic to categorize and retrieve state messages. The device state topic is the Cloud Pub/Sub topic specified in the StateNotificationConfig.pubsubTopicName field. If the registry is configured with a device state topic, these messages are forwarded to the matching Cloud Pub/Sub topic on a best-effort basis.

Subfolders are not supported for device state messages. Devices that attempt to publish state messages to an MQTT topic with a subfolder will be automatically disconnected.

For more details on retrieving state messages, see Getting device state.

Limiting MQTT traffic

ClearBlade IoT Core limits projects that generate excessive load. When devices retry failed operations without waiting, they can trigger limits that affect all devices in the same Google Cloud project.

You are strongly encouraged to implement a truncated exponential backoff algorithm with introduced jitter for retries.

Keep-alive

You can supply a keep-alive value when sending a client’s initial MQTT CONNECT message. This value is a time interval, measured in seconds, during which the broker expects a client to send a message, such as PUBLISH. If no message is sent from the client to the broker during the interval, the broker automatically closes the connection. The keep-alive value you specify is multiplied by 1.5, so setting a 10-minute keep-alive results in a 15-minute interval.

For more information, see the MQTT specification.

Client settings

ClearBlade IoT Core does not supply its default keep-alive value; if you specify a keep-alive interval, you must set it in the client.

Set the client's keep-alive interval to a 60-second minimum for best results. Many open-source client libraries, including the Paho MQTT libraries for C, Python, Node.js, and Java, use 60 seconds by default.

Idle time limit

Separate from the keep-alive interval, ClearBlade IoT Core’s idle time limit is 20 minutes. Based on this, a client connection will automatically be terminated if the client doesn't send any messages for 20 minutes, even if the keep-alive interval is longer. If a keep-alive value isn't supplied, the default 20-minute idle timeout still takes effect.

Error codes

The ClearBlade MQTT broker honors these MQTT 3.1.1 error codes: