This section explains how devices can use the MQTT bridge to communicate with ClearBlade IoT Core. For general information about HTTP and MQTT information, see Protocols.
Refer to the API documentation for full details about each method described in this section.
To publish over the MQTT bridge:
Install an MQTT client on your device.
Download an MQTT server certificate onto your device.
Configure the MQTT client to authenticate the device to ClearBlade IoT Core.
Initiate a TLS handshake over the appropriate MQTT regional URL or an external proxy run in your instance group.
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 is blocked by your firewall, 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.
...
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:
...
The device ID is the device’s string ID specified in the MQTT client ID, and the . The device ID is case-sensitive.
...
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:
Attribute | Description |
|---|---|
| The device’s user-defined string identifier, for example, |
| 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, |
| The device registry’s user-defined string identifier, for example, |
| 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 |
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.
...
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.
...
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.
For best results, set Set the client's keep-alive interval to a minimum of 60 seconds60-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.
...
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 of 20 minutes still takes effect.
Error
...
codes
The ClearBlade MQTT broker honors these MQTT 3.1.1 error codes:
Value | Return |
|---|
code response | Description | |
|---|---|---|
0 | 0x00 Connection Accepted | Connection accepted |
1 | 0x01 Connection Refused, unacceptable protocol version | The server does not support the MQTT protocol level requested by the client |
2 | 0x02 Connection Refused, identifier rejected | The client identifier is correct (UTF-8) but unallowed by the server. |
A duplicate | ||
3 | 0x03 Connection Refused, Server unavailable | The network connection has been made, but the MQTT service is unavailable |
4 | 0x04 Connection Refused, bad user name or password | The data in the user name or password is malformed |
5 | 0x05 | Unused by IoT Core |
13 | 0x13 | All other events for connect, disconnect, publish, and subscribe |