Connecting a device over MQTT

Every CoCoCo deployment runs an MQTT broker. Devices connect to it to send measurements (see Publishing metrics) and to start workflows (see Automating on device data).

In short:

• The broker is reached over mqtts:// (port 8883 unless your MQTT URL says otherwise). There is no plain-text mqtt:// listener.
• Devices authenticate with a client certificate (mutual TLS). Username and password are not used.
• The MQTT client ID must be the device token ID (dtk_…) you get when you issue the certificate.

1. Create the device

In the console, open IoT → Devices and create a device. Each device gets an ID of the form dev_….

You can also do this through the API with the createDevice mutation; only identifier is required.

2. Issue a device token

Open the device and choose Edit. The Connection & Tokens card lists the device's tokens. Choose Issue token, give it a name, and optionally set an expiry date.

The console then shows the connection bundle once:

Field	What it is
MQTT URL	The broker address, for example mqtts://<broker-host>:8883
Suggested client ID	The token ID (dtk_…). Use it as the MQTT client ID.
Client certificate	PEM certificate that identifies this device
Client key	PEM private key (PKCS#8) for the certificate
Server CA	PEM CA certificate the device uses to verify the broker
Tenant CA	PEM CA certificate that signed the client certificate (not needed to connect)

Nothing in the bundle can be read back later. If you lose it, revoke the token and issue a new one. Store the client key like a password.

The same bundle comes from the createDeviceToken mutation:

mutation IssueDeviceToken($input: CreateDeviceTokenInput!) {
  createDeviceToken(input: $input) {
    deviceToken {
      id
      deviceId
      name
      expiresAt
    }
    mqttUrl
    mqttClientId
    clientCertPem
    clientKeyPem
    serverCaCertPem
    tenantCaCertPem
    errors {
      path
      message
    }
  }
}

with variables such as {"input": {"deviceId": "dev_…", "name": "press-1"}}. The payload's token and mqttUsername fields are deprecated and not needed.

3. Connect

Setting	Value
Host and port	From the MQTT URL
TLS	Required. The broker supports up to TLS 1.2; a client that only allows TLS 1.3 cannot connect.
Client certificate and key	clientCertPem / clientKeyPem
Trusted CA	serverCaCertPem (the broker certificate is not signed by a public CA)
Client ID	mqttClientId (the dtk_… token ID)
Username / password	Leave empty. They are not read.

A quick test with mosquitto_pub, after saving the bundle into three files:

mosquitto_pub \
  -h <broker-host> -p 8883 \
  --cafile server-ca.pem \
  --cert client.pem \
  --key client.key \
  --tls-version tlsv1.2 \
  -i dtk_<token-id> \
  -t s/metrics \
  -m '{"points":[{"name":"temperature","value":22.5,"kind":"GAUGE","unit":"CELSIUS"}]}'

For a Node.js client, see the JavaScript example.

Topics are relative to the device

The broker gives every connected device its own topic namespace. A device publishes to relative topics such as s/metrics. Do not put the device ID or tenant in the topic: the broker adds the namespace itself. A device only sees messages in its own namespace.

Revoking access

Revoke a token on the device's Connection & Tokens card (or with revokeDeviceToken). This also revokes the certificate issued with it, so the device stops connecting. The revoke dialog warns you when a token has no certificate of its own (tokens issued before certificates recorded their token): revoking such a token does not disconnect the device. Deleting the device revokes all of its certificates.

Troubleshooting

The broker gives the device no error message when it drops data, so check these first:

• TLS handshake fails. The client did not present the client certificate and key, does not trust serverCaCertPem, or only allows TLS 1.3.
• Connected, but no data appears. The client ID is not the dtk_… token ID. The broker accepts the connection, but messages from any other client ID are ignored. Also check that the token has not expired or been revoked.
• Some messages are missing. See the payload rules in Publishing metrics: one bad point drops the whole message.
• Use QoS 1 if you need delivery confirmation from the broker, and set a keep-alive so the client notices lost connections and reconnects.