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 <daemon_name>

​

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

​

Brain-side self-description (feral-core)

1. Wire format — devices return an actions[] envelope documented as HUP_ACTION_SCHEMA in feral-core/hardware/protocol.py. Converters device_capability_from_action() and device_manifest_from_capabilities() map it to DeviceManifest / DeviceCapability (including optional action_type and verify honesty contracts).
2. Transport adapters — GenericSelfDescribingAdapter passthrough-executes any self-describing companion library; BridgedPeripheralAdapter routes actions to phone-bridged BLE peripherals via mesh.invoke; mesh nodes use WebSocketNodeAdapter.
3. Registration — state.register_generic_hardware_skill_for() runs on every ingress (brain-local discovery, mesh on_node_connected with node-supplied device_manifest, peripheral_bridge_register). It registers GenericHardwareSkill, which auto-generates LLM tools (hwdev_<device>__<capability>), enforces safety tiers and rate_limit_per_minute, and runs the closed-loop honesty loop when verify is declared.
4. Discovery — brain-local USB devices are listed in DEVICE_DISCOVERY_SPECS (hardware/discovery.py); override CuteBot path with FERAL_CUTEBOT_PATH.
5. Fleet API — GET /api/hardware/fleet returns manifests, derived safety tiers, last verification state, mesh nodes, and announced devices for companion-app rendering.
6. Kill switch — FERAL_GENERIC_HARDWARE_SKILLS (default "1") enables the generic path; "0" falls back to hand-written skill manifests only.