# Connect a physical EEG device to Noetryx

This is a developer/research acquisition path, not direct phone Bluetooth pairing. The bridge runs on a computer that can acquire the EEG device. Your phone or desktop browser receives the samples over WSS. No Noetryx-operated acquisition server is provided. Physical-device compatibility has not yet been verified end to end.

## Setup

1. Identify the exact physical board and supported settings in BrainFlow's device documentation: https://brainflow.readthedocs.io/en/stable/SupportedBoards.html . Confirm EEG electrode placement and units with the hardware documentation. BrainFlow's EEG channel API can also expose general-purpose EXG channels on some boards; correct configuration is required.
2. Download `/evidence/noetryx_eeg_bridge.py` from this website. Install `brainflow` and `websockets>=16,<18` in an isolated Python environment. Record and pin the versions that pass your device test.
3. Obtain a TLS certificate and key valid for a bridge hostname reachable by the browser. The phone must trust the certificate. A public HTTPS website cannot connect to an insecure `ws://` endpoint. Configure the network and hostname for your own environment; no tunnel or public endpoint is created by the website.
4. Generate a random access token of at least 24 characters and set the `NOETRYX_STREAM_TOKEN` environment variable on the bridge computer. Keep it secret; do not place it in a URL, source repository or screenshot.
5. Run the script with your physical board ID and the appropriate connection parameters. Required flags are `--board-id`, `--confirm-microvolts`, `--cert` and `--key`. Optional flags include `--serial-port`, `--mac-address`, `--params-json`, `--host`, `--port` and `--origin`. The default bind address is localhost, so another device requires an appropriately secured reachable bind address.
6. Open Noetryx `/engine`, enter the `wss://` bridge address and access token, confirm the source settings, then connect. Keep the acquisition computer and page active. The bridge permits one receiver and only the configured Noetryx origin.

The bridge rejects negative synthetic/replay board IDs. It accepts 1–16 EEG channels at 128–1024 Hz. It checks acquisition timestamps for reversal or gaps over 1.5 nominal sample intervals; some host-timestamped devices may fail this rule and require a device-specific adapter. Do not weaken timing checks without measuring the device behavior. It releases the hardware session when a connection stops.

## Wire protocol

Browser sends one authorization message after the secure connection opens:

```json
{"type":"authorize","token":"YOUR_PRIVATE_ACCESS_TOKEN"}
```

Authorized physical-device sender replies with metadata, then sample frames:

```json
{"type":"hello","protocol":"noetryx-eeg-1","source":"device","sourceName":"Configured EEG board","sampleRate":256,"channels":["Fp1","Fp2"],"unit":"uV"}
```

Each data frame has `type: "samples"`, a zero-based increasing integer `sequence`, a cumulative zero-based `firstSample`, and `samples` as channel-major arrays of equal length. The first frame begins at sequence 0 and firstSample 0. Send at most two seconds per frame. The sample rate and channel list stay fixed until reconnect. No synthetic frame values are provided here.

The receiver detects transport gaps; it cannot prove that a sender is physical hardware or that no samples were lost before the bridge. Device-side timing, packet continuity and montage must also be verified. Do not use the spectral display for diagnosis or stimulation.

## End-to-end acceptance

Confirm acquisition against a separately saved device recording, voltage scale and known input/reference. Verify detach/reconnect, missing packets, stale data, tab backgrounding, channel changes, token rejection, origin restriction and TLS on each intended browser. Numerical unit tests alone do not establish physical-device accuracy or neurofeedback benefit.

Protocol implementation: `/signal-core.mjs`, `/signal-stream.mjs`, `/signal-connection.mjs`.
Source references: https://brainflow.readthedocs.io/en/stable/Examples.html and https://websockets.readthedocs.io/en/stable/reference/asyncio/server.html .