capacitor-mesh-ble

Canonical configurable BLE mesh transport for Capacitor apps

The plugin provides Android and iOS radios, chunking, bounded reassembly, relay, background lifecycle hooks and a stable Capacitor API. Product identity, discovery UUID policy, cryptography and payload semantics stay in the consuming app. See the transport contract.

Until an npm release exists, pin an immutable Git commit over SSH:

npm install 'git+ssh://git@github.com/forgesworn/capacitor-mesh-ble.git#<commit-sha>'

For a published release:

npm install capacitor-mesh-ble@0.1.0

Sync native files

npx cap sync

• start(...)
• stop()
• broadcast(...)
• send(...)
• setKeepaliveFrame(...)
• getStatus()
• startRssiSampling(...)
• stopRssiSampling()
• addListener('frame', ...)
• addListener('peer', ...)
• addListener('status', ...)
• addListener('rssi', ...)
• removeAllListeners()
• Interfaces

start(options: MeshBleStartOptions) => Promise<void>

stop() => Promise<void>

broadcast(options: { data: string; }) => Promise<{ queuedPeers: number; }>

Returns: Promise<{ queuedPeers: number; }>

send(options: { peer: string; data: string; }) => Promise<{ queuedPeers: number; }>

Returns: Promise<{ queuedPeers: number; }>

setKeepaliveFrame(options: { data: string | null; }) => Promise<void>

iOS may repeat this frame while JavaScript is suspended in the background.

getStatus() => Promise<MeshBleStatus>

Returns: Promise<MeshBleStatus>

startRssiSampling(options?: MeshBleStartRssiSamplingOptions | undefined) => Promise<void>

Start periodic RSSI sampling: polls connected GATT links and attributes scanned advertisement RSSI, for peers already identified via a prior frame exchange. Off by default (battery cost). Idempotent — calling this again while sampling just updates the interval. Stops automatically when the transport is stopped.

Android only. iOS has no such method in its pluginMethods list, so a call there is REJECTED by the native bridge (not silently ignored) — callers must guard with try/catch if they run cross-platform. The web implementation, by contrast, DOES implement this method, as an inert no-op: there is no BLE hardware to sample, so it resolves rather than rejecting. NB the security-relevant honesty gate (no attribution while relaying) is likewise Android-only; if iOS ever grows sampling, the gate MUST be ported in the same change or iOS emits dishonest attributions.

stopRssiSampling() => Promise<void>

Stop RSSI sampling. Idempotent — safe to call when not sampling. Shares startRssiSampling's platform behaviour: Android runs the real stop, iOS rejects (bridge-level, method not implemented), web resolves as a no-op.

addListener(eventName: 'frame', listenerFunc: (event: MeshBleFrameEvent) => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

addListener(eventName: 'peer', listenerFunc: (event: MeshBlePeerEvent) => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

addListener(eventName: 'status', listenerFunc: (status: MeshBleStatus) => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

addListener(eventName: 'rssi', listenerFunc: (event: MeshBleRssiSample) => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

removeAllListeners() => Promise<void>

A product peer became reachable through a learned BLE next hop, or that route was lost.

A raw RSSI sample, attributed to the mesh peer id bound to the MAC it was observed on. The binding comes from a prior in-room frame exchange, and attribution is only emitted on a DIRECT, non-relaying link (discreet mode): while this device relays (crowd/mesh mode) a bound id can belong to a relayer's MAC, or be injected over the keyless crowd UUID, so no rssi event is emitted at all. It is therefore a proximity hint on a trusted-neighbour link, NOT a cryptographic identity proof — a consumer must not treat it as authentication. Banding or distance estimation is a product concern; this plugin reports dBm only. Emitted on Android only for now.