...
ClearBlade IoT Core supports the MQTT protocol by running a managed broker that listens to the port mqtt.googleapis.com:8883. Port 8883 is the standard TCP port reserved with IANA for secure MQTT connections. Connections to this port must use TLS transport, which is supported by open source clients like Eclipse Paho.
...
A
PUBLISHmessage with QoS 1 will be acknowledged by thePUBACKmessage after it has been successfully sent to Cloud Pub/Sub.PUBLISHmessages with QoS 0 do not requirePUBACKresponses, and 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 in order to retry them. If the buffer becomes full, the message with QoS 1 may be dropped and a
PUBACKmessage will not be sent to the client. The client is expected to resend the message.
For device configurations, QoS levels are as follows:
...
The complete Google root CA certification package (128 KB) for
mqtt.googleapis.com.Caution: Google services' certificates can be issued by any of the Certificate Authority from this regularly updated list https://pki.goog/roots.pem. Applications connecting to Google services should trust all the Certificate Authorities from that list.
This package establishes the chain of trust to communicate with Google products and services, including ClearBlade IoT Core.
Devices with the complete root CA certification package communicate directly with the MQTT server.
This package is regularly updated.
Google's minimal root CA set (<1 KB) for
mqtt.2030.ltsapis.goog. The minimal root CA set includes a primary and backup certificate.This set is for devices with memory constraints, like microcontrollers, and establishes the chain of trust to communicate with ClearBlade IoT Core only.
Devices with the minimal root CA set communicate with the ClearBlade IoT Core via long-term support domains.
This set is fixed through 2030 (the primary and backup certificates won't change). For added security, Google Trust Services may switch between the primary and backup certificates at any time without notice.
After downloading Google root CA certificates to your device, you can configure an MQTT client to authenticate the device, connect to the MQTT server, and communicate over the MQTT bridge.
...
Set the MQTT client ID to the full device path:
Code Block projects/PROJECT_ID/locations/REGION/registries/REGISTRY_ID/devices/DEVICE_ID
Associate the MQTT client with MQTT server certificates.
Set the MQTT host name to
mqtt.googleapis.comor a long-term support domain (if you used the minimal root CA set).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
unusedorignored.Set the password. The password field must contain the JWT.
The following sample shows how to configure the MQTT client to authenticate a device:
The steps for configuring the client ID and authenticating a device are highlighted below:View on GitHub Feedback
| Code Block |
|---|
int Publish(char* payload, int payload_size) { int rc = -1; MQTTClient client = {0}; MQTTClient_connectOptions conn_opts = MQTTClient_connectOptions_initializer; MQTTClient_message pubmsg = MQTTClient_message_initializer; MQTTClient_deliveryToken token = {0}; MQTTClient_create(&client, opts.address, opts.clientid, MQTTCLIENT_PERSISTENCE_NONE, NULL); conn_opts.keepAliveInterval = 60; conn_opts.cleansession = 1; conn_opts.username = k_username; conn_opts.password = CreateJwt(opts.keypath, opts.projectid, opts.algorithm); MQTTClient_SSLOptions sslopts = MQTTClient_SSLOptions_initializer; sslopts.trustStore = opts.rootpath; sslopts.privateKey = opts.keypath; conn_opts.ssl = &sslopts; unsigned long retry_interval_ms = kInitialConnectIntervalMillis; unsigned long total_retry_time_ms = 0; while ((rc = MQTTClient_connect(client, &conn_opts)) != MQTTCLIENT_SUCCESS) { if (rc == 3) { // connection refused: server unavailable usleep(retry_interval_ms * 1000); total_retry_time_ms += retry_interval_ms; if (total_retry_time_ms >= kMaxConnectRetryTimeElapsedMillis) { printf("Failed to connect, maximum retry time exceeded."); exit(EXIT_FAILURE); } retry_interval_ms *= kIntervalMultiplier; if (retry_interval_ms > kMaxConnectIntervalMillis) { retry_interval_ms = kMaxConnectIntervalMillis; } } else { printf("Failed to connect, return code %d\n", rc); exit(EXIT_FAILURE); } }
pubmsg.payload = payload;
pubmsg.payloadlen = payload_size;
pubmsg.qos = kQos;
pubmsg.retained = 0;
MQTTClient_publishMessage(client, opts.topic, &pubmsg, &token);
printf(
"Waiting for up to %lu seconds for publication of %s\n"
"on topic %s for client with ClientID: %s\n",
(kTimeout / 1000), opts.payload, opts.topic, opts.clientid);
rc = MQTTClient_waitForCompletion(client, token, kTimeout);
printf("Message with delivery token %d delivered\n", token);
MQTTClient_disconnect(client, 10000);
MQTTClient_destroy(&client);
return rc;} |
Using a long-term MQTT domain
Long-term support (LTS) domains let you use one TLS configuration for an extended period of time. You can set up an MQTT client once, configure the MQTT client to publish messages through an LTS domain, and then communicate over the MQTT bridge continuously during the supported time frame.
The current active LTS domain is mqtt.2030.ltsapis.goog. This LTS domain is supported through 2030.
To use the LTS domain:
Configure an MQTT client to publish messages through an LTS domain.
Configure the MQTT client to authenticate the device to ClearBlade IoT Core.
When configuring the device, associate the minimal root CA set's primary and backup certificates with the MQTT client.
Initiate a TLS handshake over
mqtt.2030.ltsapis.googon port 8883 or 443. Use at least the following TLS features.Caution: Long term support is only guaranteed if all the TLS requirements below are met by the MQTT client:
P-256 with SHA-256 as the certificate key and hash algorithm
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 using P-256 and uncompressed points for the cipher suite
Server Name Indication (SNI)
DNS over TCP or UDP
For more information on securing MQTT traffic, including messages sent to LTS domains, see Device security recommendations.
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 the following format:
| Code Block |
|---|
/devices/DEVICE_ID/events
|
The device ID is the string ID of the device 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. To publish messages to other Cloud Pub/Sub topics, see Publishing telemetry events to additional Cloud Pub/Sub topics.
The forwarded message data field contains a copy of the message published by the device, and the following message attributes are added to each message in the Cloud Pub/Sub topic:
...
Attribute
...
Description
...
deviceId
...
The user-defined string identifier for the device, for example, thing1. The device ID must be unique within the registry.
...
deviceNumId
...
The server-generated numeric ID of the device. When you create a device, ClearBlade IoT Core automatically generates the device numeric ID; it's globally unique and not editable.
...
deviceRegistryLocation
...
The Google Cloud Platform region of the device registry, for example, us-central1.
...
deviceRegistryId
...
The user-defined string identifier for the device registry, for example, registry1.
...
projectId
...
The string ID of the cloud project that owns the registry and device.
...
subFolder
...
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.
Note: 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.
The following sample shows how to send PUBLISH messages through the MQTT connection:
This sample uses the Google API Client Library for Python.View on GitHub Feedback
...
Using a long-term MQTT domain
Long-term support (LTS) domains let you use one TLS configuration for an extended period of time. You can set up an MQTT client once, configure the MQTT client to publish messages through an LTS domain, and then communicate over the MQTT bridge continuously during the supported time frame.
The current active LTS domain is mqtt.2030.ltsapis.goog. This LTS domain is supported through 2030.
To use the LTS domain:
Configure an MQTT client to publish messages through an LTS domain.
Initiate a TLS handshake over
mqtt.2030.ltsapis.googon port 8883 or 443. Use at least the following TLS features.Caution: Long term support is only guaranteed if all the TLS requirements below are met by the MQTT client:
P-256 with SHA-256 as the certificate key and hash algorithm
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 using P-256 and uncompressed points for the cipher suite
Server Name Indication (SNI)
DNS over TCP or UDP
For more information on securing MQTT traffic, including messages sent to LTS domains, see Device security recommendations.
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 the following format:
| Code Block |
|---|
/devices/DEVICE_ID/events
|
The device ID is the string ID of the device 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 copy of the message published by the device, and the following message attributes are added to each message in the Cloud Pub/Sub topic:
Attribute | Description |
|---|---|
| The user-defined string identifier for the device, for example, |
| The server-generated numeric ID of the device. When you create a device, ClearBlade IoT Core automatically generates the device numeric ID; it's globally unique and not editable. |
| The Google Cloud Platform region of the device registry, for example, |
| The user-defined string identifier for the device registry, for example, |
| The string ID of the cloud project 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 |
Note: 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
...
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 the following cases:
...
To categorize and retrieve state messages, configure the registry with a device state topic. 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.
...
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.
For retries, you are strongly encouraged to implement a truncated exponential backoff algorithm with introduced jitter.
Keep-alive
...
Separate from the keep-alive interval, ClearBlade IoT Core has its own idle time limit of 20 minutes. Based on this limit, 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 idle timeout of 20 minutes still takes effect.
Troubleshooting
If you have trouble connecting, see Troubleshooting.