[Technical-Track] BrainFlow Sensor Adapter — Connect Real EEG Hardware to the SAL

[Cortex-psylead]

Labels: Technical-Track · Milestone-1 · good-first-project · help-wanted
Priority: High — Blocking for Milestone 1
Estimated effort: ~200–400 lines of Python
Skill level required: Intermediate Python + basic signal processing

---

Context

Cortex Protocol v0.5.1 has a fully working Sovereignty Abstraction Layer (SAL) with ECDH sensor handshake, Clinical Bridge validation, CDI drift detection, and TelemetryRouter ingestion — but all biometric input is currently a NumPy sine wave simulation.

The integration gap is exactly one module: a BrainFlowSensorAdapter that reads real EEG frames from hardware and feeds them into the existing bus_to_sal_bridge.py pipeline.

From HARDWARE_STATUS.md (Part J of the v0.5.1 reference):

"Devices that could work with a BrainFlow adapter (~100 lines): OpenBCI Cyton, Muse 2, Neurosity Crown. These are Milestone 1 targets. No adapter exists yet."

---

What exists today (your starting point)

The full pipeline is already built and tested. You only need to feed it real data:

[Real EEG Hardware]  ← YOU BUILD THIS PART
       │
       ▼  BrainFlowSensorAdapter (new file)
[EncryptedFrame]  ← sensor_channel.py already handles this
       │
       ▼  bus_to_sal_bridge.py  (already implemented)
       │
       ▼  TelemetryRouter.ingest_from_bridge()  (already implemented, J3.1)
       │
       ▼  CognitiveShield  (already implemented, 92 tests passing)

The interface you must satisfy is defined in src/keros/bus_to_sal_bridge.py:

# The bridge expects frames with this structure after decryption:
# - raw_samples: np.ndarray, shape (N,), dtype float32
# - sample_rate: int (Hz)
# - sensor_id: str (certified sensor identifier)
# - timestamp: float (Unix epoch)

And TelemetryRouter.ingest_from_bridge() expects:

payload = {
    "timestamp": float,          # Unix epoch, ±5s freshness window
    "features": np.ndarray,      # shape (5,) — Phase A clinical features
    "polyvagal_state": str,      # one of: "ventral_vagal", "sympathetic", "dorsal_vagal"
    "sensor_id": str,
    "frame_seq": int,            # monotone per sensor — replay protection
}

---

Deliverable

A new file: src/keros/brainflow_adapter.py

Minimum requirements:

1. Connects to a BrainFlow-supported device (OpenBCI Cyton, Muse 2, or Neurosity Crown)
2. Reads EEG frames at the device's native sample rate
3. Applies the Phase A feature extraction (Hilbert envelope → mean, std, p25, p75, max) — already implemented in cognitive_shield_v2.py, extract and reuse
4. Maps the 5 clinical features to a polyvagal_state label using the Clinical Bridge thresholds
5. Increments frame_seq monotonically per sensor session
6. Feeds the structured payload into TelemetryRouter.ingest_from_bridge()

Optional (highly valued):

• Abstract base class BiometricSensorAdapter so future adapters (Emotiv, Neurosity) follow the same interface
• Unit tests with BrainFlow's built-in synthetic board (BoardIds.SYNTHETIC_BOARD) so CI can run without physical hardware

---

Hardware you can use to test

Device	Price	Notes
OpenBCI Cyton	~$399	8-ch EEG, 250 Hz, USB dongle
Muse 2	~$199	4-ch EEG, BLE, consumer grade
Neurosity Crown	~$999	8-ch EEG, WiFi
BrainFlow Synthetic Board	$0	Software simulation — sufficient for CI

BrainFlow synthetic board is sufficient for a first PR. Physical hardware validation is a Milestone 1 clinical requirement but not required to merge the adapter code.

---

Resources

• BrainFlow Python docs
• src/keros/sensor_channel.py — ECDH handshake reference
• src/keros/bus_to_sal_bridge.py — pipeline integration
• src/sal/telemetry_router.py — ingest_from_bridge() method
• src/sal/cognitive_shield_v2.py — Phase A feature extraction (lines ~4587–4650)
• docs/clinical/CLINICAL-BRIDGE.md — Clinical threshold values for polyvagal state mapping

---

Acceptance criteria

• brainflow_adapter.py connects to BoardIds.SYNTHETIC_BOARD without errors
• Frames flow end-to-end: BrainFlow → adapter → ingest_from_bridge() → no exception
• frame_seq is monotonically increasing per session
• polyvagal_state is always one of the three canonical labels
• Tests pass with python -W error (zero warnings)
• A short docs/hardware/BRAINFLOW_SETUP.md explaining how to run with real hardware

---

This is the single highest-leverage technical contribution for Milestone 1.
Questions? Open a comment here or join the discussion with tag [Technical-Track].

[Cortex-psylead]

Closed by PR #7. Thank you @mayoka0 — first external contribution merged to main. The SAL now accepts real EEG hardware. Milestone 1 integration gap closed.