Connecting devices via MQTT

This guide explains how to integrate IoT devices with the EdgeIQ Symphony platform using MQTT. It covers the essential operations including connecting devices, sending reports, and transmitting heartbeats.

EdgeIQ Symphony IoT Platform MQTT Integration Guide

Prerequisites

Before you begin, ensure you have:

A registered device in the EdgeIQ Symphony platform
Your company ID
Your device ID
Your device password
Mosquitto MQTT client installed (to follow the examples)

MQTT Broker Information

EdgeIQ Symphony uses the following MQTT broker:

Production Broker: mqtt.edgeiq.io:443
Protocol: MQTTS (MQTT over TLS)
Port: 443
AWS Root CA: AmazonRootCA1.pem
TLS: Required (with ALPN protocol set to "mqtt")

Use Case 1: Connecting a Device via MQTT

Proper connection to the EdgeIQ Symphony platform requires specific formatting for client ID and username.

Connection Parameters

Client ID: <company_id>/<device_id>/custom-v1.2.3 - the <custom-v1.2.3> part can be left empty or filled with your client name and version
Username: <company_id>/<device_id>
Password: Your device password
TLS: Required (with ALPN protocol set to "mqtt")

Example Connection Using Mosquitto

mosquitto_pub \
-h mqtt.edgeiq.io \
-p 443 \
-i "your_company/your_device_id/custom-v1.2.3" \
-u "your_company/your_device_id" \
-P "your_password" \
-t "u/your_company/your_device_id/status" \
-m '{"serial":"1234567890", "firmware_version":"1.2.3"}' \
--tls-use-os-certs \
--tls-alpn mqtt \
-q 1

If the message was processed successfully, the Device Details page should be updated with the submitted information (Serial and Firmware Version). The connection counter chips should also indicate that the device was connected once:

Connection counter chip shows "1" connection and Serial and Firmware Version have been updated.

Connection Notes

The client ID format includes a version string that helps identify your client software version
TLS is mandatory for production environments
Quality of Service (QoS) level 1 is recommended for most messages

Use Case 2: Sending a Report Message

Reports are used to send device data to the EdgeIQ Symphony platform. They follow a specific topic structure and payload format.

Report Topic Structure

u/<company_id>/<device_id>/reports

Example Report Message

mosquitto_pub \
-h mqtt.edgeiq.io \
-p 443 \
-t "u/your_company/your_device_id/reports" \
-u "your_company/your_device_id" \
-P "your_password" \
-i "your_company/your_device_id/custom-v1.2.3" \
-m '{"payload":{"temp":22.5,"humidity":45.2,"pressure":1013.2}}' \
--tls-use-os-certs \
--tls-alpn mqtt \
-q 1

If the message was processed successfully, you should see the report under the Reports drop-down in the Device Activity sidebar:

Report appears in the Device Activity sidebar.

Opening the report shows the submitted payload.

Report Payload Structure

The basic report payload contains a payload object with your device data:

{
  "payload": {
  "temp": 22.5
  }
}

Extended Report Options

You can include additional fields in your report:

{
  "device_unique_id": "your_device_id",
  "device_datetime": "2023-06-15T12:34:56Z",
  "payload": {
  "temp": 22.5,
  "humidity": 45.2
  },
  "seq": 123
}

device_unique_id: Identifies the device (useful when sending on behalf of sensors)
device_datetime: Timestamp when the data was collected
seq: Sequence number for tracking message order

Use Case 3: Sending a Heartbeat Message

Heartbeats provide operational metrics about your device to the EdgeIQ Symphony platform. To configure heartbeats, please set a Heartbeat Period on the Device Details page. The heartbeat period is used to trigger status changes to At Risk and Offline based on the time passed since the last heartbeat. A device is considered At Risk, if it missed at least one heartbeat, and Offline, if it missed more than 3 heartbeats.

Set a heartbeat period on the device details page.

Heartbeat Topic Structure

u/<company_id>/<device_id>/reports/hb

Example Heartbeat Message

mosquitto_pub \
-h mqtt.edgeiq.io \
-p 443 \
-t "u/your_company/your_device_id/reports/hb" \
-u "your_company/your_device_id" \
-P "your_password" \
-i "your_company/your_device_id/custom-v1.2.3" \
-m '{"cpu_usage":"10","ram_usage":"50.2","disk_usage":"75.1"}' \
--tls-use-os-certs \
--tls-alpn mqtt \
-q 1

After sending the message, the device status should change to Online. MQTT will report disconnected, because mosquitto_pub will connect, submit the message, and disconnect:

Device is marked online after the heartbeat message was received. The heartbeat message is shown under Device Activity.

Heartbeat Payload Structure

The heartbeat payload contains operational metrics:

{
  "cpu_usage": "10",
  "ram_usage": "50.2",
  "disk_usage": "75.1"
}

Extended Heartbeat Options

You can include additional fields in your heartbeat:

{
  "status": "online",
  "edge_version": "4.2.1",
  "cell_signal": "excellent",
  "cell_usage": "1.2GB",
  "cpu_usage": "15",
  "ram_usage": "50.2",
  "disk_usage": "65.1",
  "disk_size": "32GB",
  "disk_free": "10.5GB",
  "ips": ["192.168.1.100", "10.0.0.5"],
  "connections": {
  "ethernet": "connected",
  "wifi": "connected",
  "cellular": "connected"
  },
  "wifi_clients": ["device1", "device2"]
}

Next Steps

Please refer to the EdgeIQ MQTT Device Spec for more advanced use cases.

Troubleshooting

Common Connection Issues

Connection Refused
- Verify your credentials (company ID, device ID, password)
- Ensure TLS is properly configured
- Check that the ALPN protocol is set to "mqtt"
- Check that the AWS Root CA is installed on the system or manually added to the truststore
Message Not Received
- Verify the topic format is correct
- Ensure the payload is valid JSON
- Check QoS level (1 is recommended)
TLS Errors
- Ensure your system has up-to-date CA certificates
- Try using the --capath option with a specific CA certificate

Debugging Tips

Use the -d flag with mosquitto_pub for verbose output
Check your device logs for connection errors
Verify network connectivity to the broker

Additional Resources

EdgeIQ

EdgeIQ MQTT Device Spec

MQTT

For more information or support, contact EdgeIQ support at support@edgeiq.io.

Table of Contents