Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.feral.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

FERAL’s wristband integration provides real-time biometric streaming over Bluetooth Low Energy. The brain uses this data for health baselines, proactive coaching, anomaly detection, and digital twin enrichment.

​
Supported Metrics

MetricUpdate FrequencyUnitDescription
Heart Rate1 HzbpmContinuous PPG-based heart rate
SpO2Every 30s%Blood oxygen saturation
Skin TemperatureEvery 60s°CWrist skin temperature
Sleep StagesPost-sleepenumWake / Light / Deep / REM classification
StepsContinuouscountDaily step accumulation
HRVEvery 5 minmsHeart rate variability (RMSSD)

​
BLE Pairing Flow

1

Enable BLE in FERAL

Ensure BLE is enabled in your configuration:
settings.json
{
  "hardware": {
    "ble_enabled": true
  }
}
2

Put the wristband in pairing mode

Hold the side button for 3 seconds until the LED flashes blue. The wristband advertises as FERAL-Wristband-XXXX.
3

Scan and pair

Pair via the HTTP API — the brain scans BLE advertisements and writes the device to its registry:
curl -X POST http://localhost:9090/api/devices/pair \
  -H "Content-Type: application/json" \
  -d '{ "name": "FERAL-Wristband-A3F2" }'
To list currently advertising / paired devices, use feral devices (CLI) or curl http://localhost:9090/api/devices (HTTP).
4

Verify the data stream

feral status

Hardware    ● 1 device   FERAL-Wristband-A3F2 (streaming)
  HR: 72 bpm | SpO2: 98% | Temp: 36.4°C | Battery: 84%

​
Data Format

The wristband streams data as HUP (Hardware Unified Protocol) messages over the /v1/node WebSocket: 
{
  "type": "sensor_data",
  "device_id": "wristband_a3f2",
  "timestamp": "2026-04-12T08:30:00Z",
  "payload": {
    "heart_rate": 72,
    "spo2": 98,
    "skin_temp": 36.4,
    "hrv_rmssd": 42.1,
    "steps": 3421,
    "battery": 84
  }
}

​
Real-Time Streaming to Brain

The brain aggregates wristband data into a rolling health context window. This data is:
  • Available to the LLM for health-related queries (“What’s my heart rate?”)
  • Fed into the proactive engine for anomaly detection
  • Stored in episodic memory for trend analysis
  • Used by the digital twin to model your physical state
Data stays local. Biometric readings are stored in your local memory database and never leave your machine.

​
Whoop & Oura Integration

The brain combines wristband data with third-party wearables for a unified health view. 
{
  "integrations": {
    "whoop": {
      "enabled": true,
      "client_id": "your_whoop_client_id",
      "client_secret": "your_whoop_client_secret"
    }
  }
}
When both the wristband and a third-party wearable are connected, the brain cross-references data for higher accuracy — e.g., comparing PPG heart rate from the wristband with optical HR from Whoop.

​
Troubleshooting

Ensure the wristband is in pairing mode (flashing blue LED) and within ~5 meters. Check that ble_enabled is true in settings.
BLE range is ~10m. Move closer to the machine running FERAL. Walls and interference can reduce range.
Ensure the wristband is worn snugly on the wrist. Loose fit causes poor PPG signal.