Protocol Requirements

Do this work before implementation starts. A clean protocol inventory prevents most integration delays and avoids the common failure mode where the adapter works only for one test session or one firmware version.

Required Handoff

Collect this information for every device and firmware line you plan to support.

Area	What to capture
Discovery	device name patterns, service UUIDs, filters
GATT layout	characteristics, direction, notification/read/write behavior
Packet format	framing, byte order, headers, counters, checksums
EEG payload	channel names, channel count, sample rate, units, scaling
Timing	device timestamps, local timestamps, sequence behavior
Session control	any commands required to start or stop streaming
Failure modes	disconnect behavior, low battery behavior, firmware quirks

BLE Inventory Template

Use this as the minimum intake format:

## Device
- Model:
- Firmware:
- Transport: Web Bluetooth / bridge / native helper

## Discovery
- Device name prefix:
- Primary service UUIDs:
- Required optional services:

## Characteristics
- UUID:
  - purpose:
  - read / write / notify:
  - notes:

## EEG payload
- channel names:
- channel count:
- sample rate:
- units and scaling:
- timestamp source:

## Session control
- how streaming starts:
- how streaming stops:
- reconnect notes:

Packet Questions You Should Answer Early

Question	Why it matters
How does a packet start and end?	The decoder needs a deterministic framing rule.
Is there a packet counter or sequence field?	This helps detect drops, reordering, and corruption.
Is there a checksum or CRC?	This helps reject bad packets safely.
How are samples packed?	The decoder needs the exact byte layout and endianness.
Can multiple time steps arrive in one packet?	This affects row batching and timestamp handling.
What changes across firmware versions?	You need predictable version gating and test coverage.

Metadata Rules

Your adapter should never guess the basics.

Metadata	Rule
Channel names	Use a documented, stable order
Channel count	Match the emitted EEG rows exactly
Sample rate	Use the true output rate for the active mode
Units	Document whether values are raw, scaled, or converted
Clock source	Clearly state `device` or `local`

Do not tune models or downstream app logic until this metadata is verified. Most reliability issues start here.

Browser and Platform Questions

This guide focuses on device integration, but platform constraints still matter. Confirm these before planning a browser BLE rollout:

Question	What to confirm
Does the device work over Web Bluetooth?	Chromium browsers only for this workflow
Does it require a secure context?	`https://` or `localhost`
Does it need a native helper?	If yes, use a separate package or bridge path
Does Safari or iOS matter?	Browser Web Bluetooth is not available there

See Compatibility for the current platform expectations.

Definition of Ready

You are ready to implement when you can answer all of the following without guessing:

which transport path you are taking
how the browser discovers the device
how the session starts and stops
how packet bytes become EEG rows
how timestamps and channel metadata should be emitted
what caveats apply by firmware, browser, or platform

Build the adapter

Use the protocol inventory to implement a clean device layer.

Validate reliability

Turn protocol assumptions into repeatable tests.

Overview

EEG Web SDK

EEG BLE Web SDK

Camera Web SDK

Operations

Contributors

Maintainers

Protocol Requirements

Required Handoff

BLE Inventory Template

Packet Questions You Should Answer Early

Metadata Rules

Browser and Platform Questions

Definition of Ready

Next

Build the adapter

Validate reliability

​Required Handoff

​BLE Inventory Template

​Packet Questions You Should Answer Early

​Metadata Rules

​Browser and Platform Questions

​Definition of Ready

​Related Docs

​Next

Build the adapter

Validate reliability

Required Handoff

BLE Inventory Template

Packet Questions You Should Answer Early

Metadata Rules

Browser and Platform Questions

Definition of Ready

Related Docs

Next