Skip to main content
DEJA
Sign up

📋 Command Reference

All DEJA IO devices receive JSON commands with an action and payload. The same handlers run on every device type — pin, servo, turnout, effects, and ialed work identically whether the message arrives over USB serial, MQTT or WebSocket. Only the wrapping format differs:

  • 🟢🟠 USB serial (deja-arduino, deja-esp32) — JSON array of commands
  • 🛜🍓 MQTT or WebSocket (deja-esp32-wifi, deja-mqtt) — single JSON object { action, device, payload }. The envelope is identical on both transports

Actions

pin — Digital Output

Toggle a digital GPIO pin on or off.

{
  "action": "pin",
  "payload": { "pin": 8, "state": 1 }
}
Field Type Description
pin number GPIO pin number (must match device config)
state number 1 = on (HIGH), 0 = off (LOW)

servo — Servo Position

Set a PCA9685 servo channel to a specific angle.

{
  "action": "servo",
  "payload": { "servo": 0, "value": 90, "profile": "medium", "current": 45 }
}
Field Type Description
servo number PCA9685 channel (0–15)
value number Target angle in degrees
profile string Movement profile: instant, fast, medium (default), slow, or bounce. The firmware steps the servo toward value over time to match the chosen profile — this is what produces the smooth transition.
current number Fallback starting angle, used only if the device doesn't yet know the servo's last position (e.g. right after boot)

turnout — Turnout Control

Throw or close a configured Kato turnout. The device pulses the turnout's straight coil for false and its divergent coil for true (250 ms).

{
  "action": "turnout",
  "payload": { "turnout": 0, "state": true }
}
Field Type Description
turnout number Turnout index (matches device config array position)
state boolean true = thrown, false = closed

ialed — Addressable LED Strip (Planned)

Control individually addressable LED strips.

{
  "action": "ialed",
  "payload": { "strip": 0, "pattern": 0, "r": 255, "g": 0, "b": 0 }
}
Field Type Description
strip number LED strip index
pattern number Animation pattern ID
r, g, b number RGB color values (0–255)

This action is defined in the Arduino firmware but not yet fully implemented.

📦 Format Differences

🟢🟠 USB Serial (deja-arduino / deja-esp32)

Commands are sent as a JSON array over serial at 115200 baud. Both device types share the same firmware sketch, so they accept the same wire format:

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

Multiple commands can be batched in a single array.

🛜🍓 MQTT or WebSocket (deja-esp32-wifi / deja-mqtt)

Commands are sent as a single JSON object with a device field for filtering — one per MQTT message or WebSocket text frame. The envelope { action, device, payload } is identical on MQTT and WebSocket, and both wireless device types accept it:

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

The device field is required — devices ignore messages that don't match their own DEVICE_ID. The deja-esp32-wifi firmware also accepts the JSON-array shape used by the deja-arduino sketch as a convenience, so the same handlers work for both transports.

📡 Sensor Responses

USB-serial devices (deja-arduino, deja-esp32) send sensor state changes back over serial:

{ "sensor": 0, "state": 1 }

WiFi devices (deja-esp32-wifi, deja-mqtt) send { "device": "<id>", "sensor": 0, "state": 1 } — to their …/messages topic on MQTT, or as a text frame on WebSocket. The device debounces before sending — a minimum time between two reported changes of a sensor: SENSOR_DEBOUNCE_MS (default 500 ms) on the Arduino-family sketches, each sensor's debounceMs (default 100 ms) on the Pico W.