MQTT Connection Configuration

This guide covers the technical details for establishing a secure MQTT connection to the CoCoCo platform, including authentication parameters, regional endpoints, and security requirements.

Authentication and Connection Details

Before your device can connect and send data, you need to configure it with the correct credentials and endpoint address.

MQTT Connection Parameters

When establishing the MQTT connection from your device, use the following parameters:

• Username: d:${device_id} (Replace ${device_id} with the actual ID of the device you created in CoCoCo). The username must start with d:
• Password: The Device Token you generated for this specific device.
• ClientID: A unique identifier for this specific MQTT client instance (e.g., my-client, device-serial-number). Choose a consistent and unique ID for each connecting device instance.

Here's an example structure often used in MQTT client libraries (JavaScript example):

{
  username: "d:your_actual_device_id", // Replace with your device ID
  password: "your_generated_device_token", // Replace with your token
  clientid: "unique_client_identifier" // e.g., device serial, MAC address
}

MQTT Broker Endpoints

We provide the MQTT interface as part of our CoConnect on-premise gateway application. You can use it by simply connecting to:

mqtt://$COCONNECT_IP:1883

Connection Best Practices

Keep Alive and Timeouts

• Set an appropriate keep-alive interval (typically 30-60 seconds) to maintain connection health
• Configure connection and reconnection timeouts suitable for your network conditions

Last Will and Testament

Consider setting up a Last Will and Testament message when connecting to automatically update device status if the connection is unexpectedly lost:

{
  will: {
    topic: `d/${deviceId}/s`,
    payload: JSON.stringify({ mode: 'unknown', status: 'stopped', online: false }),
    retain: true,
    qos: 1
  }
}

Quality of Service (QoS)

• Use QoS 0 for non-critical telemetry data where message loss is acceptable
• Use QoS 1 for important status updates and error reports where delivery confirmation is needed
• QoS 2 is generally not necessary for most IoT applications

Troubleshooting Connection Issues

Common Issues

1. Authentication Failed: Double-check that your device ID is correct and the token is valid
2. Connection Refused: Verify you're using the correct regional endpoint
3. TLS Errors: Ensure your client supports TLS 1.2+ and certificate verification
4. Client ID Conflicts: Make sure each device instance uses a unique Client ID

Testing Your Connection

Use MQTT client tools like mosquitto_pub or GUI tools like MQTT Explorer to test your connection parameters before implementing in your device code.