🔧 Building Custom Devices

Want to go beyond the stock DEJA firmware? You can build your own MQTT-connected devices using any microcontroller with WiFi — ESP32, Raspberry Pi Pico W, ESP8266, or even a full Linux board. As long as your device can publish and subscribe to MQTT topics, it can talk to the DEJA Server.

This guide covers the MQTT protocol, command format, and provides minimal working examples you can use as a starting point.

💡 If you just want a working ESP32 WiFi build without writing your own firmware, use the stock deja-esp32-wifi target — see Arduino & ESP32 Setup. It uses exactly the topology and command format described on this page, so you can reuse the protocol details below to add custom actions on top of the stock sketch.

---

📡 MQTT Topic Structure

DEJA uses a simple hierarchical topic scheme:

{topicId}/{layoutId}/{deviceId}

📥 Subscribing for Commands

Your device subscribes to its own command topic to receive instructions from the server:

DEJA/tamarack/my-custom-pico

📤 Publishing Status Messages

Your device publishes status and sensor data back to the server on the /messages subtopic:

DEJA/tamarack/my-custom-pico/messages

---

📦 Command Format

All commands arrive as JSON messages on your subscription topic with three fields:

{
  "action": "pin",
  "device": "my-custom-pico",
  "payload": { "pin": 6, "state": true }
}

⚠️ Important: Multiple devices can share the same MQTT topic. Always compare the device field against your device's ID and ignore messages not intended for you.

---

🎯 Supported Actions

pin — Digital Pin Control

Turn a GPIO pin on or off. Used for LEDs, relays, and other digital outputs.

{
  "action": "pin",
  "device": "my-custom-pico",
  "payload": { "pin": 6, "state": true }
}

servo — Servo Positioning

Set a servo to a specific angle via a PCA9685 servo driver.

{
  "action": "servo",
  "device": "my-custom-pico",
  "payload": { "servo": 0, "value": 90 }
}

turnout — Turnout Control

Throw or close a turnout (uses servo positioning under the hood).

{
  "action": "turnouts",
  "device": "my-custom-pico",
  "payload": { "servo": 0, "value": 90 }
}

💡 Both servo and turnouts actions route to the same servo handler in the reference firmware.

effects — Effects Control

Trigger lighting effects, animations, or other GPIO-based effects. Uses the same payload format as pin.

{
  "action": "effects",
  "device": "my-custom-pico",
  "payload": { "pin": 8, "state": true }
}

ialed — Addressable LED Control

Control individually addressable LEDs (NeoPixel, WS2812, etc.) for signal heads, building lights, and animated effects.

---

✅ Server Acknowledgment

When a device first connects and subscribes, it should publish a status message to its /messages topic. The server sends an acknowledgment back:

{
  "action": "ack",
  "payload": { "layoutId": "tamarack" }
}

Use this to confirm your device is properly registered and communicating with the server.

---

🗄️ Device Registration

For the DEJA Server and Throttle's Devices page to track your device, register it in Throttle under Devices. Create an entry with at minimum:

---

🏗️ Minimal CircuitPython Example (Pico W)

This is a stripped-down version of the DEJA Pico W firmware — just enough to connect to WiFi, subscribe to MQTT, and handle a pin command. Use this as a starting point for your own device.

settings.toml

CIRCUITPY_WIFI_SSID = "YourNetwork"
CIRCUITPY_WIFI_PASSWORD = "YourPassword"
MQTT_BROKER = "192.168.1.100"
LAYOUT_ID = "tamarack"
DEVICE_ID = "my-custom-pico"
TOPIC_ID = "DEJA"

code.py

import board
import digitalio
import os
import json
import socketpool
import wifi
import adafruit_minimqtt.adafruit_minimqtt as MQTT

# 🔧 Configuration from settings.toml
ssid = os.getenv("CIRCUITPY_WIFI_SSID")
password = os.getenv("CIRCUITPY_WIFI_PASSWORD")
broker = os.getenv("MQTT_BROKER")
layout_id = os.getenv("LAYOUT_ID")
device_id = os.getenv("DEVICE_ID")
topic_id = os.getenv("TOPIC_ID")

subscribe_topic = f"{topic_id}/{layout_id}/{device_id}"
publish_topic = f"{topic_id}/{layout_id}/{device_id}/messages"

# 💡 Set up a single LED pin for demo purposes
led = digitalio.DigitalInOut(board.GP6)
led.direction = digitalio.Direction.OUTPUT

# 📥 Handle incoming MQTT messages
def on_message(client, topic, message):
    data = json.loads(message)

    # ⚠️ Ignore messages for other devices
    if data.get("device") != device_id:
        return

    action = data.get("action")
    payload = data.get("payload")

    if action == "pin" and payload:
        pin_num = payload.get("pin")
        state = payload.get("state", False)
        if pin_num == 6:
            led.value = state
            client.publish(publish_topic, f"Pin 6 set to {state}")
            print(f"✅ Pin 6 → {state}")

def on_connect(client, userdata, flags, rc):
    client.subscribe(subscribe_topic)
    client.publish(publish_topic, f"Connected: {device_id}")
    print(f"📡 Subscribed to {subscribe_topic}")

# 🌐 Connect to WiFi
print("Connecting to WiFi...")
wifi.radio.connect(ssid, password)
print(f"Connected! IP: {wifi.radio.ipv4_address}")

# 📡 Connect to MQTT broker
pool = socketpool.SocketPool(wifi.radio)
mqtt_client = MQTT.MQTT(broker=broker, port=1883, socket_pool=pool)
mqtt_client.on_connect = on_connect
mqtt_client.on_message = on_message

print("Connecting to MQTT...")
mqtt_client.connect()

# 🔄 Main loop — poll for messages
while True:
    mqtt_client.loop()

📦 Required libraries: Copy adafruit_minimqtt into the lib/ folder on your Pico W's CIRCUITPY drive. Get it from the Adafruit CircuitPython Bundle.

---

🔌 WebSocket instead of MQTT

A device can skip the broker and dial the DEJA Server directly. Register it as deja-esp32-wifi or deja-mqtt with Transport → WebSocket (the only types that may use it), then run deja deploy or pnpm build:firmware for it — the generated settings.toml / config.h holds its WS_TOKEN. The server only stores the token's hash.

Open ws://<server>:8082/device with these handshake headers:

Authorization: Bearer <WS_TOKEN>
X-Deja-Device: <deviceId>

A missing or wrong token gets HTTP 401. Once connected, the device receives the same { action, device, payload } objects as on MQTT, one per text frame, and sends its hello, sensor events and log lines back the same way (frames up to 4 KiB). Answer the server's pings — every 30 s — or it drops the connection. See Protocol Details.

The Pico W firmware's client, io/src/deja-pico-w/lib/deja_ws.py, also runs under desktop Python:

import json, socket, time
from deja_ws import WebSocketClient, WebSocketError  # io/src/deja-pico-w/lib/deja_ws.py

DEVICE_ID, TOKEN = "my-custom-pico", "<WS_TOKEN from deja deploy>"
ws = WebSocketClient(lambda h, p: socket.create_connection((h, p), timeout=5), "192.168.1.100", 8082, "/device",
                     headers={"Authorization": "Bearer " + TOKEN, "X-Deja-Device": DEVICE_ID})
ws.connect()  # raises on 401
ws.send_text(json.dumps({"status": "connected", "device": DEVICE_ID}))
try:
    while ws.connected:
        for text in ws.poll():  # never blocks; answers pings for you
            print("command:", json.loads(text))
        time.sleep(0.05)
except (WebSocketError, OSError) as e:  # server gone or socket reset
    print("disconnected:", e)  # a real device reconnects here, backing off 1 s → 30 s

---

💻 Minimal Python Script (Desktop/Raspberry Pi)

Control your layout from any computer on the network using the paho-mqtt library.

pip install paho-mqtt

import json
import paho.mqtt.client as mqtt

# 🔧 Configuration
BROKER = "192.168.1.100"
LAYOUT_ID = "tamarack"
DEVICE_ID = "my-custom-pico"
TOPIC_ID = "DEJA"

topic = f"{TOPIC_ID}/{LAYOUT_ID}/{DEVICE_ID}"

client = mqtt.Client()
client.connect(BROKER, 1883)

# 💡 Turn on pin 6
command = {
    "action": "pin",
    "device": DEVICE_ID,
    "payload": {"pin": 6, "state": True}
}
client.publish(topic, json.dumps(command))
print(f"📤 Sent: {json.dumps(command)}")

# 🔄 Turn a servo to 90 degrees
servo_command = {
    "action": "servo",
    "device": DEVICE_ID,
    "payload": {"servo": 0, "value": 90}
}
client.publish(topic, json.dumps(servo_command))
print(f"📤 Sent: {json.dumps(servo_command)}")

client.disconnect()

---

🟢 Minimal Node.js Script

Control your layout from Node.js using the mqtt npm package.

npm install mqtt

import mqtt from 'mqtt'

// 🔧 Configuration
const BROKER = 'mqtt://192.168.1.100'
const LAYOUT_ID = 'tamarack'
const DEVICE_ID = 'my-custom-pico'
const TOPIC_ID = 'DEJA'

const topic = `${TOPIC_ID}/${LAYOUT_ID}/${DEVICE_ID}`

const client = mqtt.connect(BROKER)

client.on('connect', () => {
  console.log('📡 Connected to MQTT broker')

  // 💡 Turn on pin 6
  client.publish(topic, JSON.stringify({
    action: 'pin',
    device: DEVICE_ID,
    payload: { pin: 6, state: true }
  }))

  // 🔄 Move servo to 90 degrees
  client.publish(topic, JSON.stringify({
    action: 'servo',
    device: DEVICE_ID,
    payload: { servo: 0, value: 90 }
  }))

  console.log('✅ Commands sent!')
  client.end()
})

---

🧪 Testing Your Device

1. Start the DEJA Server — it runs the MQTT broker on port 1883 (any external broker works too)
2. Enable MQTT on the DEJA Server — Set ENABLE_MQTT=true in your server's .env
3. Use an MQTT explorer — Tools like MQTT Explorer let you watch messages in real time
4. Send test commands — Use the Python or Node.js scripts above to publish commands to your device's topic
5. Check Throttle → Devices — If your device is registered in Firestore, its connection status appears on throttle.dejadcc.com/devices, and sensor/effect changes show up under Activity

---

📚 Next Steps

• 📖 IO Devices & Firmware Overview — Learn about the stock Arduino and Pico W firmware
• 📡 Protocol Details — Serial, MQTT and WebSocket connection specs
• 🚂 DEJA Throttle — Register devices and manage your layout configuration