Devices

Register and manage devices

A device is any hardware endpoint connected to Cadreen — an ESP32, Arduino, robot, arm, drone, or sensor. Register it, track it, send commands, and set alerts.

What is a device?

A device is a hardware endpoint connected to Cadreen. It has a position, velocity, battery level, and status. Cadreen tracks all of this in real time.

Devices send telemetry through MQTT or serial. Cadreen receives it, stores it, checks alert rules, and makes it available in the dashboard.

What types of devices work?

ESP32

Arduino, WiFi, Bluetooth — the most common entry point

Arduino

Uno, Mega, Nano — connect via USB serial bridge

Mobile robots

AMRs, AGVs, delivery robots

Industrial arms

Robotic arms, grippers, welders

Drones

UAVs, inspection drones

Sensors

Temperature, vibration, current monitors

Cameras

Visual inspection, quality control

LiDAR

3D mapping, obstacle detection

How do I connect a device?

The fastest way is the connect-a-sensor wizard. Pick a sensor, wire it up, flash the code — Cadreen walks you through it.

Connect a sensor

How do I manage devices?

POST/api/v1/cadreen/devices

Response

{
  "id": "robot-1",
  "status": "connected",
  "message": "Device added"
}

Example

curl -X POST http://localhost:8080/api/v1/cadreen/devices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "robot-1", "pose": {"position": {"x": 0.0, "y": 0.0, "z": 0.0}, "orientation": {"x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0}}}'

POST/api/v1/cadreen/devices/auto-register

Response

{
  "device_id": "esp32-temp-01",
  "mqtt_broker": "mqtt.cadreen.com",
  "mqtt_port": 8883,
  "mqtt_username": "workspace-id/esp32-temp-01",
  "mqtt_password": "random-uuid",
  "mqtt_client_id": "cadreen-esp32-temp-01"
}

Example

curl -X POST http://localhost:8080/api/v1/cadreen/devices/auto-register \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "esp32-temp-01", "name": "Temperature Sensor", "type": "dht22"}'

GET/api/v1/cadreen/devices

List all registered devices. Returns their position, velocity, battery, and last update time.

Response

{
  "devices": [
    {
      "id": "robot-1",
      "pose": {"position": {"x": 1.5, "y": 2.0, "z": 0.0}},
      "twist": {"linear": {"x": 0.5}},
      "battery": {"percentage": 0.85, "voltage": 12.1},
      "last_update": "2026-07-18T10:30:00Z"
    }
  ],
  "total": 1
}

Example

curl http://localhost:8080/api/v1/cadreen/devices \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/v1/cadreen/devices/{deviceID}

Get details for a specific device.

Response

{
  "id": "robot-1",
  "pose": {"position": {"x": 1.5, "y": 2.0, "z": 0.0}},
  "twist": {"linear": {"x": 0.5}},
  "battery": {"percentage": 0.85, "voltage": 12.1},
  "last_update": "2026-07-18T10:30:00Z"
}

Example

curl http://localhost:8080/api/v1/cadreen/devices/robot-1 \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE/api/v1/cadreen/devices/{deviceID}

Remove a device from Cadreen. The device can be re-registered later.

Response

{
  "id": "robot-1",
  "status": "removed",
  "message": "Device removed"
}

Example

curl -X DELETE http://localhost:8080/api/v1/cadreen/devices/robot-1 \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/v1/cadreen/devices/{deviceID}/telemetry

Store sensor readings for a device. Each reading has a topic, value, and unit.

Response

{
  "device_id": "esp32-temp-01",
  "stored": 2,
  "alerts_fired": 0
}

Example

curl -X POST http://localhost:8080/api/v1/cadreen/devices/esp32-temp-01/telemetry \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"readings": [{"topic": "temperature", "value": 23.5, "unit": "celsius"}]}'

GET/api/v1/cadreen/devices/{deviceID}/telemetry

Get the latest sensor readings for a device. Returns the most recent reading per topic.

Response

{
  "device_id": "esp32-temp-01",
  "latest": {
    "temperature": {"value": 23.5, "unit": "celsius", "timestamp": "2026-07-27T19:45:00Z"},
    "humidity": {"value": 65.2, "unit": "%", "timestamp": "2026-07-27T19:45:00Z"}
  }
}

Example

curl http://localhost:8080/api/v1/cadreen/devices/esp32-temp-01/telemetry \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/v1/cadreen/devices/{deviceID}/telemetry/history

Get historical sensor readings for a device. Returns time-series data for charts.

Response

{
  "device_id": "esp32-temp-01",
  "topic": "temperature",
  "points": [
    {"value": 23.5, "unit": "celsius", "timestamp": "2026-07-27T19:45:00Z"},
    {"value": 23.6, "unit": "celsius", "timestamp": "2026-07-27T19:44:00Z"}
  ],
  "total": 2
}

Example

curl "http://localhost:8080/api/v1/cadreen/devices/esp32-temp-01/telemetry/history?topic=temperature&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/v1/cadreen/devices/{deviceID}/telemetry/export

Export telemetry data as CSV or JSON. Returns a downloadable file.

Response

// CSV: timestamp,topic,value,unit
// JSON: { "readings": [...], "total": N }

Example

curl "http://localhost:8080/api/v1/cadreen/devices/esp32-temp-01/telemetry/export?format=csv" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o telemetry.csv

POST/api/v1/cadreen/devices/{deviceID}/commands

Send a command to a device. The command is queued and delivered when the device connects.

Response

{
  "command_id": "uuid",
  "device_id": "esp32-relay-01",
  "topic": "relay",
  "status": "pending"
}

Example

curl -X POST http://localhost:8080/api/v1/cadreen/devices/esp32-relay-01/commands \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic": "relay", "payload": {"state": "on"}}'

GET/api/v1/cadreen/devices/{deviceID}/commands

Get pending commands for a device. Returns commands that haven't been delivered yet.

Response

{
  "commands": [
    {
      "id": "uuid",
      "device_id": "esp32-relay-01",
      "topic": "relay",
      "payload": {"state": "on"},
      "status": "pending",
      "created_at": "2026-07-27T19:45:00Z"
    }
  ],
  "total": 1
}

Example

curl http://localhost:8080/api/v1/cadreen/devices/esp32-relay-01/commands \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/api/v1/cadreen/devices/alerts/rules

Create an alert rule. Cadreen fires an alert when a sensor reading crosses the threshold.

Response

{
  "id": "uuid",
  "device_id": "esp32-temp-01",
  "sensor_id": "temperature",
  "condition": "gt",
  "threshold": 30,
  "severity": "warning"
}

Example

curl -X POST http://localhost:8080/api/v1/cadreen/devices/alerts/rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device_id": "esp32-temp-01", "sensor_id": "temperature", "condition": "gt", "threshold": 30, "severity": "warning", "message": "Temperature is above 30°C"}'

GET/api/v1/cadreen/devices/alerts/rules

List all alert rules for the workspace.

Response

{
  "rules": [
    {
      "id": "uuid",
      "device_id": "esp32-temp-01",
      "sensor_id": "temperature",
      "condition": "gt",
      "threshold": 30,
      "severity": "warning",
      "enabled": true
    }
  ],
  "total": 1
}

Example

curl http://localhost:8080/api/v1/cadreen/devices/alerts/rules \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/v1/cadreen/devices/alerts/events

List fired alert events. Returns alerts that have been triggered by sensor readings.

Response

{
  "events": [
    {
      "id": "uuid",
      "rule_id": "uuid",
      "device_id": "esp32-temp-01",
      "sensor_id": "temperature",
      "value": 31.5,
      "threshold": 30,
      "severity": "warning",
      "message": "Temperature is above 30°C",
      "acknowledged": false,
      "fired_at": "2026-07-27T19:45:00Z"
    }
  ],
  "total": 1
}

Example

curl http://localhost:8080/api/v1/cadreen/devices/alerts/events \
  -H "Authorization: Bearer YOUR_API_KEY"