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.
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:
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.
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:
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:
The device’s user-defined string identifier, for example, thing1. The device ID must be unique within the registry.
The server-generated device numeric ID. When you create a device, ClearBlade IoT Core automatically generates the device’s numeric ID; it's globally unique and not editable.
The Google Cloud Platform device registry region, for example, us-central1.
The device registry’s user-defined string identifier, for example, registry1.
The cloud project’s string ID that owns the registry and device.
The subfolder can be used as an event category or classification. For MQTT clients, the subfolder is the subtopic after DEVICE_ID/events, which is copied directly. For example, if the client publishes to the MQTT topic /devices/DEVICE_ID/events/alerts, the subfolder is the string alerts.
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:
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.
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 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.
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.
The ClearBlade MQTT broker honors these MQTT 3.1.1 error codes:
Return code response
Return code response
0x00 Connection Accepted
0x01 Connection Refused, unacceptable protocol version
The server does not support the MQTT protocol level requested by the client
0x02 Connection Refused, identifier rejected
The client identifier is correct (UTF-8) but unallowed by the server. A duplicate clientid can cause this
0x03 Connection Refused, Server unavailable
The network connection has been made, but the MQTT service is unavailable
0x04 Connection Refused, bad user name or password
The data in the user name or password is malformed
Unused by IoT Core
All other events for connect, disconnect, publish, and subscribe