Setup

Set up MQTT

MQTT is how Cadreen talks to hardware. It's the most common protocol for robots and sensors — lightweight, fast, and reliable.

What is MQTT?

MQTT is a messaging protocol designed for devices. Devices publish messages to topics (like channels), and servers subscribe to those topics to receive the messages. It's fast, lightweight, and works even on slow or unreliable networks.

Cadreen subscribes to device topics. When your robot publishes a temperature reading, Cadreen receives it automatically.

Which broker should I use?

Mosquitto

Best for local development and small deployments. Free, open source, lightweight.

Mosquitto

# macOS
brew install mosquitto

# Ubuntu/Debian
sudo apt install mosquitto

# Start
mosquitto -v

HiveMQ

Cloud-hosted broker. Good for production when you don't want to manage infrastructure.

HiveMQ

# Docker
docker run -p 1883:1883 hivemq/hivemq-ce

# Or use HiveMQ Cloud (managed)
# Sign up at https://www.hivemq.com/mqtt-cloud-broker/

EMQX

Enterprise-grade. High throughput, clustering, rules engine. For large-scale deployments.

EMQX

# Docker
docker run -p 1883:1883 -p 8083:8083 emqx/emqx

# Or install from package
# https://www.emqx.io/docs/en/latest/installing.html

How do I configure the connection?

Variable	Default	Description
CADREEN_MQTT_BROKER	tcp://localhost:1883	Broker URL. Use ssl:// for TLS connections.
CADREEN_MQTT_CLIENT_ID	edge-{edgeID}	Client ID for the edge runtime connection. Each edge instance gets a unique ID.
CADREEN_MQTT_QOS	1	Quality of service. 0 = send and forget, 1 = make sure it arrives (default), 2 = make sure it arrives exactly once.

How are topics structured?

Cadreen expects device data on specific topics. The main ones:

edge/{edgeID}/+/telemetrySensor readings — temperature, voltage, current, battery

Device not connecting?

Check that the broker is running (mosquitto -v), the URL is correct, and the port (default 1883) is not blocked by a firewall.

Messages not arriving?

Verify the topic matches what Cadreen expects. Device telemetry topics follow the pattern: edge/{edgeID}/+/telemetry

Connection drops?

Increase the keep-alive interval. Cloud brokers may have connection limits. Check your broker's max connections setting.