HUP — Hardware Unification Protocol

​

What HUP is

​

How a daemon connects

                  wss://brain.local:9090/v1/node
                 ┌──────────────────────────────┐
 Device          │                              │         FERAL Brain
 Daemon ────────▶│     Persistent WebSocket     │────────▶ Hardware Mesh
   (HUP)         │                              │            Registry
                 └──────────────────────────────┘

1. Daemon opens a WebSocket to wss://<brain>:<port>/v1/node.
2. Sends a node_register frame with its node_id, capabilities, sensors, actuators, firmware version.
3. Brain replies with node_ack — session token, expected heartbeat interval, granted capabilities, denied capabilities.
4. From that point the daemon can send device_event frames (sensor readings, button presses, camera frames) and respond to hup_action_request frames the Brain sends to trigger actuators (buzz, LED, motor, etc.).

​

Message types (abbreviated)

​

Writing a daemon

from feral_node_sdk import FeralNode, capability

node = FeralNode(
    node_id="my-wristband",
    name="Acme Wristband",
    firmware_version="1.2.3",
    brain_url="wss://feral.local:9090/v1/node",
    api_key="...",  # from `feral pair`
    capabilities=[capability.HEART_RATE, capability.BUZZER, capability.BATTERY],
)

@node.on_action("buzz")
async def buzz(params):
    duration_ms = params.get("duration_ms", 200)
    # ... call your real hardware here ...
    return {"ok": True}

async def loop():
    async for reading in hr_sensor:
        await node.emit_event("heart_rate", {"bpm": reading})

node.run(loop())

​

Cookiecutter template

pip install cookiecutter
cookiecutter https://github.com/FERAL-AI/FERAL-AI.git \
    --directory feral-nodes/templates/hardware-daemon

​

Publishing to the registry

feral publish --daemon ./my-daemon/

feral install <item_id>

​

Pairing + security

• First-time pairing uses a 6-digit code the daemon prints to its own log. The user types that code into Settings → Devices → Pair. The Brain returns an API key the daemon saves locally.
• Steady-state: daemon sends Authorization: Bearer <key> in the WebSocket upgrade.
• Per-capability gating: the user approves each capability (camera, audio, actuator) in Settings. The Brain only sends hup_action_request frames for capabilities the user has granted.

​

Compliance

• Licensed Apache-2.0 — any vendor may implement, fork, or extend.
• No certification program — vendors self-declare conformance by passing the schemas in feral-node-sdk / @feral-ai/node-sdk.
• Bug reports + protocol additions go through github.com/FERAL-AI/FERAL-AI/issues.

​

Full spec