Hermetry speaks MQTT 3.1.1. This page is the connection reference for device developers: how to reach the broker, how to log in, how sessions behave, what is acknowledged when, and what to do when a connection is refused. The topics and payloads are in MQTT topics and payload reference.
Connection
| Item | Value |
|---|---|
| Protocol | MQTT 3.1.1 (protocol level 4). A CONNECT for MQTT 5 is refused with CONNACK 1. |
| Port, TLS | 8883 |
| Port, plain | 1883, only for devices of a profile that allows plain MQTT |
| Host | The broker host on the device’s Connection details card. Use the host of your organisation’s region. |
| Clean session | Send true. A CONNECT with false is served as a clean session. |
| Keepalive | Use MQTT keepalive. A keepalive of 0, or above the broker’s maximum (300 seconds on a default installation), is served at the maximum. |
| Will message | Allowed, ignored. Hermetry decides the connection state itself. |
| Retain flag | Ignored. The message is processed, not retained. |
| Connect time | From the TCP connection to an accepted CONNECT (TLS handshake and login included) the device has a few seconds (5 by default). |
Nothing is queued for a device while it is offline except commands marked persistent. After every connect, the device subscribes again and asks for its shared attributes, which gives it the current values.
TLS
- TLS 1.2 minimum, TLS 1.3 preferred.
- TLS 1.2 suites:
ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256,ECDHE-ECDSA-CHACHA20-POLY1305. No RSA key exchange, no CBC. - SNI is required. Connect by host name, not by IP address.
- For third-party devices the server certificate is a public one. Verify it against your normal CA bundle and the host name.
- The server asks for a client certificate but does not require one, so one port serves every login type.
- Small devices may ask for 4 KB TLS records (
max_fragment_length).
A profile decides whether its devices may use the plain port at all (Plain MQTT on the profile’s Transport & auth tab). TLS-only is the default. See Device transport security.
Logging in
| Credential | Client ID | Username | Password |
|---|---|---|---|
| Access token | any valid ID | the access token | empty |
| MQTT basic | any, or the pinned client ID | the username | the password |
| X.509 certificate | the device serial (must equal the certificate CN) | the serial (ignored) | empty |
- A client ID has 1 to 64 characters from
A–Z a–z 0–9 . _ : -. Anything else is refused with CONNACK 2. - A CONNECT with a username but no password is read as an access token. A CONNECT without a username is refused.
- When a client certificate is presented, it decides. There is no fallback to a password. An untrusted certificate ends the TLS handshake.
- The username
provisionopens a provisioning session (see Adding and claiming devices). - The profile must allow the credential type, the device’s network and the port (TLS or plain); otherwise the login is refused with CONNACK 5.
Sessions
- One session per device. A second connection of the same device takes over and closes the first. A device whose session is taken over again and again from two networks is held back for a while, and your administrators get a notice (“takeover fight”); check for two devices sharing one credential.
- Re-checks. Every live session is checked again about every 60 seconds. A rotated or revoked credential, a disabled or deleted device, a suspended organisation, or a profile change the session no longer meets ends it at once.
- Quarantined devices connect, but their telemetry and attributes are acknowledged and dropped until an administrator activates them.
- New network notice. When a device logs in from another network than last time, your administrators may get a notice (at most once an hour per device), so a stolen credential does not go unnoticed.
- Connected-device limit. If your plan limits how many devices may be connected at once, a CONNECT over that limit is refused with CONNACK 5.
Acknowledgements and QoS
- Publish with QoS 1. QoS 0 is accepted; QoS 2 is handled as QoS 1.
- Hermetry sends the PUBACK only after the message is safely queued. PUBACKs leave in the order the device published.
- If a message cannot be queued, it gets no PUBACK (nor does anything after it on that session), and the session is closed after a few seconds. The device sends the unacknowledged messages again after it reconnects.
- A device may have at most 20 unacknowledged QoS 1 messages in flight by default (the profile’s Max unacknowledged messages (MQTT), 1 to 1,000).
- Duplicates of the same device, key and time stamp are stored once, so sending again is safe.
Limits
| Limit | Default | Where it is set |
|---|---|---|
| Telemetry messages | 10:1,300:60 (10 per second and 300 per minute) | Profile Limits |
| Telemetry data points | 200:1,6000:60 | Profile Limits |
| Attribute messages | 5:1,60:60 | Profile Limits |
| Message size | 64 KiB, up to 1,000 key-value points | Profile Max message payload (bytes) |
| Messages to the device | 64 KiB (4 KiB for licensed devices) | Profile Max downlink payload (bytes) |
- Over a rate limit, the message is acknowledged and dropped. A device that keeps breaking its limit (more than three times its minute allowance dropped within a minute) has its session closed. Owners and administrators get one notice per device per hour.
- A message that is too large is dropped whole; the connection stays up.
- Your organisation as a whole also has rate limits from its plan.
- Buffered readings that a device sends after an outage (every record carries an older
ts) must also fit the profile’s Replay messages per second. - Telemetry and attribute messages count toward your monthly message quota; connection events, commands and alarms do not. See Message quota and usage.
CONNACK codes
| Code | Meaning | What the device should do |
|---|---|---|
| 0 | Accepted | Continue. |
| 1 | Protocol version not supported | Stop retrying; fix the client. |
| 2 | Client ID rejected | Stop until the configuration changes. |
| 3 | Server unavailable: the service is busy, starting or stopping, or the address is briefly blocked | Back off and retry, with jitter. |
| 4 | Bad username or password | Back off for at least 5 minutes (up to 1 hour). |
| 5 | Not authorised: device disabled, certificate revoked or expired, organisation suspended or over its device or connected-device limit, login type, network or port not allowed by the profile | Back off with the long schedule. |
The reason behind code 5 is never sent to the device. It is written to the device’s Log tab.
Note
Repeated failed logins from one address block that address for a short time, for every device behind it. A misconfigured device can therefore lock out its neighbours behind the same NAT. Fix wrong credentials quickly.
Disconnect reasons
The device’s Log tab shows why a session ended:
| Reason | Meaning |
|---|---|
client_disconnect | The device closed the connection. |
keepalive_timeout | Nothing arrived within the keepalive time. |
takeover | Another connection of the same device took over. |
auth_revoked | The credential, device or organisation is no longer allowed. |
rate_limit | The device kept breaking its rate limit. |
server_shutdown | The broker node restarted; reconnect. |
protocol_error, inflight_exceeded, socket_error | The client broke the protocol, sent too many unacknowledged messages, or the network failed. |
Recommended device behaviour
- Connect over TLS by host name, with keepalive between 30 and 300 seconds.
- After CONNACK 0, subscribe to the downlink topics, ask for shared attributes, report client attributes, then send buffered telemetry before live data.
- Use QoS 1 and wait for PUBACK before you delete a buffered reading.
- Batch readings when you send more than one sample per second.
- On a refused connection, follow the back-off of the CONNACK table; add random jitter so a fleet does not reconnect at once.