Skip to main content
Use this page before you write adapter code. The right path depends on whether the integration is broadly useful, whether it needs vendor SDKs or native bridges, and whether it will be maintained as a public SDK surface. If the device is likely to be useful to the wider Elata SDK audience, put it upstream in @elata-biosciences/eeg-web-ble. That keeps transport behavior centralized and avoids parallel adapters across multiple apps.

​
Choose By Outcome

PathBest whenWhy
Upstream device module in eeg-web-bleThe device is broadly useful and works through browser BLEBest default for public SDK support
Separate package under packages/You need a vendor SDK, a license gate, or a localhost/native bridgeKeeps heavier integrations isolated
App-local adapterYou are proving a concept or shipping a private integrationFastest path when no shared package is needed

​
Path 1: Upstream in eeg-web-ble

Choose this when:
  • the device can work through Web Bluetooth in a browser
  • the integration is likely to be reused by more than one app
  • you want one shared implementation of transport behavior
This path usually means:
  1. add a device module under the BLE package
  2. reuse BleTransport
  3. add mocked tests
  4. update consumer docs and device notes
This is the best path for a public, durable integration that should feel like a first-class part of the SDK.

​
Path 2: Separate Package

Choose this when the device needs more than a clean browser BLE flow. Typical reasons:
SituationWhy a separate package helps
Licensed or heavy vendor SDKKeeps extra dependencies out of the main BLE package
Localhost helper or native bridgeLets you ship a bridge-specific transport cleanly
Independent release cadenceLets the vendor or partner own versioning and support
The package should still expose a HeadbandTransport, or a thin wrapper around one, so app code stays consistent with the rest of the Elata stack.

​
Path 3: App-Local Adapter

Choose this when speed matters more than reuse. This is a good fit for:
  • a private customer deployment
  • a fast proof of concept
  • evaluation work before a public package exists
Keep the contract the same even if the code stays private. That makes it easier to move upstream later.

​
Decision Order

1

Ask whether the integration should be reusable

If multiple apps would benefit, start by assuming an upstream path.
2

Check for browser BLE blockers

If Web Bluetooth will not work, or if a native bridge is required, move to a separate package.
3

Decide who owns long-term support

Shared support usually belongs upstream. Vendor-owned release lines often fit better in a separate package.
4

Keep the app contract stable

No matter where the code lives, the app-facing contract should still be HeadbandTransport and HeadbandFrameV1.

​
Paths to Avoid

Do not choose an app-local adapter just because it is easy in the first hour. That usually creates extra work later if the integration becomes public. Do not push a heavy, bridge-based, or licensed integration into the shared BLE package either. Keep the public package lean.

​
Next

Transport Contract

Review the shared interfaces your chosen path must still satisfy.

Protocol Requirements

Gather the protocol details you need before implementation begins.