Using gateways with the MQTT bridge

This page explains how gateways can use the MQTT bridge to communicate with Cloud IoT Core and publish telemetry events on behalf of bound devices. Before you begin, read Using the MQTT bridge for general information on using the MQTT bridge with Cloud IoT Core.

Try an end-to-end demo

Using gateways with the MQTT bridge

  1. After you've created and configured the gateway, connect it to Cloud IoT Core over the MQTT bridge.
  2. Create devices if you haven't already.
  3. Optional: Bind the devices to the gateway.

    When using the MQTT bridge, you only need to bind the devices if they can't generate their own JWTs.

  4. Optional: Subscribe to the system error topic to get feedback on whether device operations are successful or not.

  5. Attach the devices to the gateway.

  6. Use the gateway to relay telemetry, device state, and configuration messages on behalf of its devices. Try the end-to-end demo to learn how.

Gateway messages

After the gateway connects to Cloud IoT Core over the MQTT bridge, it can send or receive three types of messages:

  • Control messages: Attaches a device to the gateway, or detaches a device from the gateway. These messages are sent between the gateway and Cloud IoT Core. Cloud IoT Core accepts control messages only from gateways; if another type of device attempts to send a control message, Cloud IoT Core closes the connection.
  • Messages from gateways and devices: Can be relayed by the gateway on behalf of a device, or sent directly from the gateway itself.
  • System error messages: When the gateway is subscribed to the MQTT system error topic on behalf of the device, Cloud IoT Core sends error messages to the gateway whenever the device encounters an error.

Attaching devices to a gateway

To enable the gateway to proxy device communications with Cloud IoT Core, have the gateway publish a QoS 1 /devices/{device_ID_to_attach}/attach control message over the MQTT bridge.

If you configured the gateway to authenticate devices using the devices' JWTs, the payload of the attach message must include the token in JSON format: { 'authorization' : '{JWT_token}' }. Otherwise, Cloud IoT Core authenticates the device by checking its association with the gateway.

Success response

After the device is authorized, Cloud IoT Core sends a PUBACK message to the gateway as a response to the attach message. After the gateway receives the PUBACK message, it can publish and subscribe to Cloud IoT Core topics on behalf of the device, such as, telemetry or configuration messages.

If a device is already attached when the gateway sends the attach message, Cloud IoT Core responds with a PUBACK message.

Detaching devices from the gateway

To detach a device from the gateway, have the gateway publish a QoS 1 /devices/{device_ID}/detach control message over the MQTT bridge. If the device isn't attached at the time the message is sent, Cloud IoT Core ignores the detach control message and sends a PUBACK message.

Troubleshooting

To be notified when a device encounters an error, subscribe the gateway to the MQTT system error topic using QoS level 0:

    # The topic gateways receive error updates on. QoS must be 0.
    error_topic = '/devices/{}/errors'.format(gateway_id)

    # Subscribe to the system error topic.
    client.subscribe(error_topic, qos=0)

Cloud IoT Core sends gateway errors on a best-effort basis, delivered over QoS 0. If the gateway isn't subscribed to the system error topic, Cloud IoT Core logs failure events but doesn't send a PUBACK message.

System errors have the following structure:

string error_type;  // A string description of the error type.
string device_id;   // The ID of the device that caused the error.
string description; // A description of the error.

If the error message was triggered by an MQTT message, the following information will be attached as well:

string message_type;  // The string MQTT message type.
string topic;  // The MQTT topic if applicable, otherwise it is empty.
int packet_id;  // The packet ID of the MQTT message if applicable, otherwise it is zero.

Error codes and error handling

Error code Description Recommended action
GATEWAY_ATTACHMENT_ERROR A gateway attachment request failed. Do not retry without fixing the problem.
GATEWAY_DEVICE_NOT_FOUND The gateway was unable to find an attached device to handle an incoming message. Do not retry without fixing the problem.
GATEWAY_INVALID_MQTT_TOPIC The gateway was unable to parse the specified MQTT topic, which was either ill-formatted or contained an invalid device ID or name. Do not retry without fixing the problem.
GATEWAY_UNEXPECTED_PACKET_ID The gateway was unable to process the message based on its packet ID. For example, a PUBACK may have contained a packet ID but nothing was waiting for the response. Do not retry without fixing the problem.
GATEWAY_UNEXPECTED_MESSAGE_TYPE The gateway received unexpected messages, such as unsupported PUBREL, PUBREC, etc. Do not retry without fixing the problem.
GATEWAY_DETACHMENT_DEVICE_ERROR The gateway detached a device because of a device error. Do not retry without fixing the problem.
UNKNOWN The error is unknown. Retry using exponential backoff.

See the main error messages documentation and the MQTT version 3.1.1 specification for more information.

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud IoT Core Documentation