Skip to main content

​
What HUP is

HUP is FERAL’s equivalent — for heterogeneous hardware — of what the USB HID class spec was for input devices: a stable, versioned, vendor-neutral protocol that lets any vendor plug hardware into any FERAL brain without proprietary glue. Current version: HUP v1.0.0 (stable, Apache-2.0 licensed) Full normative spec: feral-nodes/HUP_SPEC.md

​
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)

FrameDirectionPurpose
node_registerdaemon → brainFirst message: identity + capabilities.
node_ackbrain → daemonAcknowledges registration, grants capabilities.
node_heartbeatdaemon → brainEvery 10s; carries battery, RSSI.
device_eventdaemon → brainA sensor reading or observable event.
hup_action_requestbrain → daemonTrigger an actuator.
hup_action_responsedaemon → brainResult of an action.
node_byeeither sideGraceful disconnect.
Every frame is a JSON object with a type key. Schemas are Pydantic (Python SDK) and Zod (TypeScript SDK) — both enforce the same contract.

​
Writing a daemon

Two SDKs are published and maintained by FERAL:

Python SDK

pip install feral-node-sdk. Async FeralNode class with auto-reconnect, mDNS discovery, and 6-digit pairing.

TypeScript SDK

npm install @feral-ai/node-sdk. Same surface as the Python SDK for Node.js 20+.
Minimal Python example: 
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

Ship a new daemon in under an hour: 
pip install cookiecutter
cookiecutter https://github.com/FERAL-AI/FERAL-AI.git \
    --directory feral-nodes/templates/hardware-daemon
You get a runnable skeleton with manifest.json, mock hardware, two placeholder @on_action handlers, and one placeholder event stream. Replace the mocks with your real integration and feral publish --daemon . when ready.

​
Publishing to the registry

Once your daemon is stable: 
feral publish --daemon ./my-daemon/
The bundle lands in registry.feral.sh under kind=daemon. Any FERAL user can install it with: 
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

For the complete normative specification — all frame schemas, error codes, example wire traces, pairing flow details, and reserved fields — read the canonical document: feral-nodes/HUP_SPEC.md.