Broker Connection

This article covers everything you need to configure your device's connection to the intelliThings MQTT broker — the broker address, port, topic structure, and how publishing and subscribing work.

Broker Details

Topic Structure

Each device has two dedicated topics — one for sending data from the device and one for receiving commands to the device.

Topic Placeholders

Replace the placeholders with your actual values:

• {tenant_slug} — your tenant identifier on the intelliThings platform
• {serial_number} — the serial number you assigned to the device when creating it in the Device Template

Example

If your tenant slug is mycompany and your device's serial number is SN12345:

• Publish data to: mycompany/fromDevice/SN12345
• Subscribe to commands: mycompany/toDevice/SN12345

Publishing Data

Publishing is how your device sends data to the intelliThings platform. When your device publishes a message to its fromDevice topic, the platform receives the data and makes it available for dashboards, workflows, and AI agents.

Publishing Example

Topic: mycompany/fromDevice/SN12345
QoS: 1
Payload: {"temperature": 22.5, "humidity": 45}

Publishing Tips

• Keep messages under 2 KB — this is the maximum message size limit
• Use JSON format for structured data that workflows and AI agents can parse
• Use QoS 1 for guaranteed delivery, or QoS 0 for best-effort (lower overhead)

Subscribing to Commands

Subscribing is how your device receives commands from the intelliThings platform. When a workflow, dashboard control, or AI agent sends a command to your device, it publishes the message to the device's toDevice topic.

Subscribing Example

Topic: mycompany/toDevice/SN12345
QoS: 1

Once subscribed, your device will receive any message published to this topic.

Quality of Service (QoS)

The intelliThings broker supports two QoS levels:

Choose QoS 1 for data or commands where delivery is important. Use QoS 0 for high-frequency data where occasional loss is acceptable.

Certificate Permissions

Each device certificate is restricted to its own topics only. Your device can only publish to and subscribe from its own fromDevice and toDevice topics.

This restriction protects against cross-access to other devices on the platform. Even if a device is compromised, the attacker cannot access data from or send commands to other devices.

Note: Exceptions to this restriction can be configured in the Policy Editor, which is covered in a separate article.

Connection Checklist

Before connecting your device, make sure you have:

• Device created in the Device Template section
• Serial number noted (used in topic paths)
• Tenant slug known
• Certificates downloaded (PEM certificate + PEM key)
• Device configured with broker URL: broker2.mqtt.intellithings.io
• Device configured with port: 8883
• TLS/SSL enabled on the connection
• Client certificate and key loaded
• MQTT version set to 3.1.1
• Topics configured with correct tenant slug and serial number

Troubleshooting

Connection Refused

• Verify the broker URL is exactly broker2.mqtt.intellithings.io
• Verify the port is 8883
• Ensure TLS/SSL is enabled
• Check that your device's clock is synchronized (TLS requires valid timestamps)

Authentication Failed

• Verify the client certificate and key are correctly loaded
• Ensure you are using the certificates for the correct device (certificates are device-specific)
• Check that the certificates have not been corrupted during transfer

Cannot Publish or Subscribe

• Verify the topic path matches the pattern {tenant_slug}/fromDevice/{serial_number} or {tenant_slug}/toDevice/{serial_number}
• Check that the tenant slug and serial number are correct
• Remember: each certificate can only access its own device's topics