Protocol Details

DEJA IO supports three communication protocols. All use JSON messages.

🔌 Serial USB

Direct wired connection between the DEJA Server and any of the USB-serial Arduino-family device types: deja-arduino (Arduino Mega) or deja-esp32 (ESP32 Dev Module). Both share the same firmware sketch and identical wire format.

How It Works

1. The board connects via USB to the server machine
2. DEJA Server auto-detects the serial port
3. Server opens the port at 115200 baud
4. JSON command arrays are written to the port; responses are read line-by-line
5. Auto-reconnect with exponential backoff (1s → 30s max) on disconnect

Wire Format

Commands arrive as a JSON array (multiple commands can be batched per write):

[
  { "action": "pin", "payload": { "pin": 8, "state": 1 } },
  { "action": "servo", "payload": { "servo": 0, "value": 90, "profile": "medium" } }
]

Sensor state changes are published back over the same serial line as single objects (e.g. { "sensor": 0, "state": 1 }), debounced with a 500ms minimum between state changes.

Port Detection

The server lists available serial ports and matches them to registered devices. You can also manually specify a port path in your device configuration.

📬 MQTT over WiFi

Wireless publish/subscribe messaging via an MQTT broker (built into the DEJA Server). Used by both wireless device types: deja-mqtt (Raspberry Pi Pico W, CircuitPython) and deja-esp32-wifi (ESP32, Arduino C++). Both share the same topic scheme and the same single-object command format — the DEJA Server treats them identically on the wire.

Topic Structure

{TOPIC_ID}/{LAYOUT_ID}/{DEVICE_ID}          ← device subscribes (receives commands)
{TOPIC_ID}/{LAYOUT_ID}/{DEVICE_ID}/messages ← device publishes (sensor events, status)

Default TOPIC_ID is DEJA. Example for a device on the "tam" layout:

DEJA/tam/tj-eagle-nest-pico          ← commands IN
DEJA/tam/tj-eagle-nest-pico/messages ← sensor events / status OUT

Wire Format

Commands arrive as single JSON objects (one command per MQTT message) with a device field for filtering:

{
  "action": "pin",
  "device": "my-esp32-wifi",
  "payload": { "pin": 18, "state": 1 }
}

Sensor events the device publishes back to …/messages flow through the same pipeline as USB-serial sensors, so state updates show up in the Cloud app and Monitor the same way.

Device Filtering

Multiple devices can share the same MQTT topic prefix. Each message includes a device field, and devices only process messages matching their own DEVICE_ID. This is true for both deja-mqtt and deja-esp32-wifi.

Broker Setup

Nothing to install — the DEJA Server runs its own MQTT broker on port 1883 whenever MQTT is enabled (the default). Point your devices at the server machine's LAN IP (the deploy wizard suggests it automatically, and deja config prints it).

Already running Mosquitto or another broker? The server detects a broker on the port (or an MQTT_BROKER pointing at another machine) and connects to it instead. Set MQTT_EMBEDDED=false in ~/.deja/.env to never start the built-in broker.

WebSocket

Real-time bidirectional communication over TCP.

Connection

Connect to ws://{serverHost}:8082. On connection, the server sends an acknowledgment:

{ "action": "ack", "payload": { "layoutId": "tam", "serverId": "DEJA.js" } }

Device Monitoring

Subscribe to a device's serial I/O stream:

{ "action": "subscribe-device", "deviceId": "my-arduino" }

The server forwards serial data for that device:

{
  "action": "serial-data",
  "payload": {
    "deviceId": "my-arduino",
    "data": "{ \"sensor\": 0, \"state\": 1 }",
    "timestamp": "2026-04-03T12:00:00Z",
    "direction": "incoming"
  }
}

Unsubscribe when done:

{ "action": "unsubscribe-device", "deviceId": "my-arduino" }

See the WebSocket Integration guide for full message reference and code examples.