Versions Compared

Version Old Version 7 New Version 8
Changes made by

Aaron Allsbrook

Jeff Slavin (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

...

  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 Cloud ClearBlade IoT Core.

  4. Initiate a TLS handshake over mqtt.googleapis.com or a long-term support domain.

  5. Publish telemetry events or set the device state.

MQTT server

Cloud 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.

...

Note: The MQTT standard is defined for implementing a full publish/subscribe broker. However, the managed MQTT bridge run by Cloud 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.) Cloud 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

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

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

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

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

  • The Cloud 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 PUBACK message will not be sent to the client. The client is expected to resend the message.

...

To use TLS transport, devices must verify Cloud ClearBlade IoT Core server certificates to ensure they're communicating with Cloud ClearBlade IoT Core rather than an impersonator. The following certificate packages support verification:

  • 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 Cloud 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 Cloud ClearBlade IoT Core only.

    • Devices with the minimal root CA set communicate with the Cloud 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.

...

  1. Configure an MQTT client to publish messages through an LTS domain.

    1. Configure the MQTT client to authenticate the device to Cloud ClearBlade IoT Core.

    2. When configuring the device, associate the minimal root CA set's primary and backup certificates with the MQTT client.

  2. Initiate a TLS handshake over mqtt.2030.ltsapis.goog on 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:

    • TLS 1.2

    • 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

...

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, Cloud 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.

...

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

Limiting MQTT traffic

Cloud 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 more information, see the MQTT specification.

Client settings

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

...

Separate from the keep-alive interval, Cloud 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.

...