MQTT brokers, client ID, certificates and topics.
A device talks to Things5 over MQTT 3.1.1 or 5 with TLS and a client certificate (mutual TLS). Each device has its own certificate and private key, obtained with one of the flows in Secure device provisioning.
Things5 has two MQTT brokers. Which one a device uses depends on the kind of certificate it has:
| Things5 CA broker (recommended) | AWS IoT broker (deprecated) | |
|---|---|---|
| Host | v2.mqtt.things5.digital | mqtt.things5.digital |
| Port | 8883 (TLS) | 8883 (TLS) |
| Device certificate | Issued by the Things5 CA: Generate certificate (Things5 CA) or pairing code | Issued by AWS IoT: Generate certificate (AWS IoT, deprecated) |
| Server certificate to trust | The ca.pem delivered with the certificate (Things5 CA) | Amazon Root CA 1 (delivered as ca.pem) |
| Client ID | The certificate id: the UUID prefix of the certificate file names, also returned as certificate_id | things5-production-machine-{device_id} |
| One certificate for several devices | Yes, see Share a certificate between devices | No, one certificate per device |
Example: if the downloaded certificate is ce22c81b-444d-4ab5-bbb2-40dc8469ac96.certificate.pem, the client ID on the Things5 CA broker is ce22c81b-444d-4ab5-bbb2-40dc8469ac96. On the AWS IoT broker the client ID of device 83b6b9fc-c8cd-4801-b373-be961634b961 is things5-production-machine-83b6b9fc-c8cd-4801-b373-be961634b961.
Use exactly this client ID
With any other client ID the connection is refused, or the device is never shown as connected and commands that need a connected device (parameters, recipes, commands) fail.
Things5 sends every message addressed to a device through both brokers, so a device receives commands on whichever broker it is connected to.
Topics
Every topic of a device starts with its own prefix:
things5-production/v1/devices/{device_id}/
A device can publish and subscribe only under its own prefix (or, with a shared certificate, under the prefixes of the devices bound to it). The simplest way to receive everything addressed to the device is one subscription to things5-production/v1/devices/{device_id}/#; the device also receives back its own publications and should ignore them. See MQTT API introduction for the list of topics.
Connection rules
- Use one connection per client ID: a second connection with the same client ID disconnects the first one.
- Subscribe with at most 8 topic filters in a single SUBSCRIBE packet and do not use overlapping filters: on the AWS IoT broker a message matching two filters is delivered twice.
- Payloads are UTF-8 JSON. Messages from Things5 are sent with QoS 1. A message published by the device can be at most 128 KB.
- The connection status shown in Things5 comes from the broker: connect, disconnect and keep-alive timeout (1.5 times the keep-alive interval chosen by the client).
Firewall
Open the outbound ports listed in Firewall.
See also this video for a complete walkthrough: https://www.youtube.com/watch?v=bFtIU6Y-l4g