MQTT Integration

MQTT (Message Queuing Telemetry Transport) is the primary protocol for real-time device communication with the SensoCAN platform.

Connection Configuration

Setting	Value	Notes
Protocol	MQTT (TCP) or MQTTS (TLS)	Use TLS (Port 8883) for production environments.
Broker Host	mqtt.sensocan.com	Configured in your deployment (e.g., mqtt.yourdomain.com) in case of a custom deployment.
Port	1883 (Non-SSL)	8883 (SSL/TLS)
Client ID	{Device_UUID} or any unique string	Recommended: Use your Device UUID for easy tracking.
Username	{DEVICE_MQTT_USERNAME}	Critical: This is the MQTT Username shown in Device Details.
Password	{DEVICE_MQTT_PASSWORD}	Critical: This is the MQTT Password shown in Device Details.
Clean Session	true	Recommended for most IoT devices.
QoS	0 or 1	Quality of Service. Use 1 for guaranteed delivery.

Topic Structure

The platform uses a hierarchical topic structure to identify the tenant, device, and sensor. The topic determines how the payload is processed.

1. Single Sensor Reading

Use this for devices reporting one value at a time for a specific sensor.

Topic Pattern:

tenant/{tenant_id}/device/{device_uuid}/sensor/{sensor_identifier}

Example:

tenant/123/device/a1b2c3d4-e5f6-7890-abcd-ef1234567890/sensor/temp_01

Payload:

{
  "value": 24.5,
  "timestamp": "2023-10-27T10:00:00Z"
}

Optional Fields:

• timestamp: ISO 8601 format. Defaults to server time if omitted.
• battery_voltage: Device battery level in volts (e.g., 3.7).

---

2. Bulk Sensor Data (Historical)

Use this when uploading multiple historical readings for a single sensor (e.g., offline data sync).

Topic Pattern:

tenant/{tenant_id}/device/{device_uuid}/sensors/{sensor_uuid}

Note: Use sensors (plural) to indicate bulk mode.

Example:

tenant/123/device/a1b2c3d4-e5f6-7890-abcd-ef1234567890/sensors/fe738b8f-9efe-46a7-a1c6-b861be358442

Payload:

[
  { "value": 24.0, "timestamp": "2023-10-27T09:00:00Z" },
  { "value": 24.2, "timestamp": "2023-10-27T09:15:00Z" },
  { "value": 24.4, "timestamp": "2023-10-27T09:30:00Z" }
]

---

3. Device Batch (Multiple Sensors)

Use this to send readings for multiple sensors in one message. This is the most bandwidth-efficient option.

Topic Pattern:

tenant/{tenant_id}/device/{device_uuid}

Example:

tenant/123/device/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Payload:

{
  "data": [
    { "sensor_slug": "temp_01", "value": 24.5 },
    { "sensor_slug": "humidity_01", "value": 45.2 },
    { "sensor_uuid": "7a8b9c0d-1234-5678-90ab-cdef12345678", "value": 100 }
  ],
  "battery_voltage": 3.7
}

Notes:

• You can use either sensor_slug OR sensor_uuid to identify the sensor.
• The sensor_slug must match exactly what you configured in the platform (case-sensitive).

---

Getting Your Topic Parameters

Tenant ID

• Found in the URL when logged in: https://app.sensocan.com/tenant/{tenant_id}/...
• Or ask your system administrator.

Device UUID

• Found in Device Details page under the "Overview" tab.

Sensor Identifier

• Sensor Slug: The short, human-readable identifier (e.g., temp_01). Shown in Device Details > Sensors.
• Sensor UUID: The unique ID (e.g., 7a8b9c0d-...). Also in Device Details > Sensors.

---

Example: ESP32 / Arduino

#include <PubSubClient.h>

const char* mqtt_server = "mqtt.sensocan.com";
const char* mqtt_user = "your-device-access-token";
const int mqtt_port = 1883;

// Topic for single sensor
String topic = "tenant/123/device/a1b2c3d4-e5f6-7890-abcd-ef1234567890/sensor/temp_01";

void setup() {
  client.setServer(mqtt_server, mqtt_port);
  client.connect("ESP32_Client", mqtt_user, ""); // Password is empty
}

void loop() {
  String payload = "{\"value\": 25.3}";
  client.publish(topic.c_str(), payload.c_str());
  delay(60000); // Send every minute
}

---

Troubleshooting

Connection Refused (Not Authorized)

• Verify Token: Check that the Access Token is copied exactly from the Device Details page.
• Device Status: Ensure the device is Enabled (not "Disabled" or "Suspended").
• Tenant Status: Confirm the tenant account is active.

Data Not Appearing in Dashboard

• Topic Mismatch: Verify the tenant_id and device_uuid in the topic match your actual Device UUID.
• Sensor Identifier Mismatch: The sensor_identifier (slug or UUID) must exactly match what's configured in the platform.
• JSON Payload Error: Ensure the payload is valid JSON. Test with a JSON validator.
• Check Logs: Use the "Live Logs" feature in Device Details to see rejected messages.

Payload Rejected

• Missing value Field: All sensor payloads must include a value field.
• Invalid Timestamp Format: Use ISO 8601 format (e.g., 2023-10-27T10:00:00Z).