bare-bluetooth-android

stable

bare-bluetooth-android — Android Bluetooth bindings for Bare. It is a native addon.

npm i bare-bluetooth-android

Usage

const { Central } = require('bare-bluetooth-android')

const central = new Central()

central.on('stateChange', (state) => {
  if (state === 'on') {
    central.startScan(['180D']) // Heart Rate service UUID
  }
})

central.on('discover', (peripheral) => {
  console.log('Found:', peripheral.name, peripheral.id)
  central.stopScan()
  central.connect(peripheral)
})

central.on('connect', (peripheral) => {
  peripheral.discoverServices()

  peripheral.on('servicesDiscover', (services) => {
    // Discover characteristics for each service
  })
})

Parameter	Type	Default	Description
`msg`	`string`	—	A human-readable error message.
`fn?`	`Function`	—	The function to omit from the captured stack trace (default `BluetoothError`).
`code?`	`string`	—	The error code; defaults to `fn.name` (e.g. `SCAN_FAILED`).

Parameter	Type	Default	Description
`msg`	`string`	—	—

Parameter	Type	Default	Description
`msg`	`string`	—	—

Parameter	Type	Default	Description
`msg`	`string`	—	—

Parameter	Type	Default	Description
`msg`	`string`	—	A human-readable error message.
`id`	`string`	—	The id of the peripheral the connection attempt targeted.

Parameter	Type	Default	Description
`msg`	`string`	—	A human-readable error message.
`id`	`string`	—	The id of the peripheral that disconnected.

Parameter	Type	Default	Description
`msg`	`string`	—	—

Parameter	Type	Default	Description
`msg`	`string`	—	—

Parameter	Type	Default	Description
`msg`	`string`	—	—

Parameter	Type	Default	Description
`msg`	`string`	—	—

Parameter	Type	Default	Description
`msg`	`string`	—	—

Parameter	Type	Default	Description
`msg`	`string`	—	—

Parameter	Type	Default	Description
`msg`	`string`	—	—

Parameter	Type	Default	Description
`msg`	`string`	—	—

A duplex stream representing an L2CAP connection-oriented channel. Extends Duplex from <https://github.com/holepunchto/bare-stream>. Typically obtained via the 'channelOpen' event rather than constructed directly.

Parameters

Parameter	Type	Default	Description
`channelHandle`	`ArrayBuffer`	—	The native channel handle backing the stream; supplied internally when a channel opens, not usually passed directly.

`peer: string | null`

_Source

The address of the remote peer, or null.

`psm: number`

_Source

The Protocol/Service Multiplexer number of the channel.

Service

`new Service(uuid: string, characteristics?: Characteristic[], opts?: ServiceOptions)`

_Source

Create a new GATT service definition.

Parameters

Parameter	Type	Default	Description
`uuid`	`string`	—	The service's UUID.
`characteristics?`	`Characteristic[]`	—	The characteristics belonging to the service.
`opts?`	`ServiceOptions`	—	Options; set `primary: true` to mark this a primary service.

`characteristics: Characteristic[]`

_Source

The array of characteristics belonging to the service.

`primary: boolean`

_Source

Whether the service is a primary service.

`Service.uuid: string`

_Source

The UUID of the service.

Characteristic

`new Characteristic(uuid: string, opts?: CharacteristicOptions)`

_Source

Create a new GATT characteristic definition.

Parameters

Parameter	Type	Default	Description
`uuid`	`string`	—	The characteristic's UUID.
`opts?`	`CharacteristicOptions`	—	Options selecting the characteristic `properties`, `permissions`, and initial `value`.

`Characteristic.PROPERTY_INDICATE: number`

_Source

Characteristic property constants.

`Characteristic.PROPERTY_NOTIFY: number`

_Source

`Characteristic.PROPERTY_READ: number`

_Source

`Characteristic.PROPERTY_WRITE: number`

_Source

`Characteristic.PROPERTY_WRITE_WITHOUT_RESPONSE: number`

_Source

`permissions: number | null`

_Source

The permission flags of the characteristic, or null if inferred.

`properties: number`

_Source

The property flags of the characteristic.

`Characteristic.uuid: string`

_Source

The UUID of the characteristic.

`value: Uint8Array | null`

_Source

The current value of the characteristic, or null.

Server

`new Server()`

_Source

Create a new BLE peripheral server for advertising services and handling client requests.

`addService(service: Service): void`

_Source

Add a service to the GATT server. The 'serviceAdd' event is emitted when the service has been registered.

Parameters

Parameter	Type	Default	Description
`service`	`Service`	—	The `Service` to register with the GATT server.

`Server.destroy(): void`

_Source

Destroy the server, stopping advertising and unpublishing all L2CAP channels.

`publishChannel(opts?: ChannelOptions): void`

_Source

Publish an L2CAP channel. The 'channelPublish' event is emitted with the assigned PSM.

Parameters

Parameter	Type	Default	Description
`opts?`	`ChannelOptions`	—	Options for the L2CAP channel to publish.

`respondToRequest(request: ReadRequest, result: number, data?: Uint8Array): void`

_Source

Respond to a read or write request with a result code and optional data. Use the Server.ATT_* constants for the result.

Parameters

Parameter	Type	Default	Description
`request`	`ReadRequest`	—	The read or write request to respond to.
`result`	`number`	—	The ATT result code; use the `Server.ATT_*` constants.
`data?`	`Uint8Array`	—	The value to return for a read request; omit for write responses.

`Server.ATT_INSUFFICIENT_RESOURCES: number`

_Source

`Server.ATT_INVALID_HANDLE: number`

_Source

`Server.ATT_READ_NOT_PERMITTED: number`

_Source

`Server.ATT_SUCCESS: number`

_Source

`Server.ATT_UNLIKELY_ERROR: number`

_Source

ATT result codes for use with server.respondToRequest().

`Server.ATT_WRITE_NOT_PERMITTED: number`

_Source

`Server.CONNECTION_STATE_CONNECTED: number`

_Source

`Server.CONNECTION_STATE_CONNECTING: number`

_Source

`Server.CONNECTION_STATE_DISCONNECTED: number`

_Source

`Server.CONNECTION_STATE_DISCONNECTING: number`

_Source

`Server.PERMISSION_READ_ENCRYPTED: number`

_Source

`Server.PERMISSION_READABLE: number`

_Source

`Server.PERMISSION_WRITE_ENCRYPTED: number`

_Source

Characteristic permission constants.

`Server.PERMISSION_WRITEABLE: number`

_Source

`Server.PROPERTY_INDICATE: number`

_Source

Characteristic property constants.

`Server.PROPERTY_NOTIFY: number`

_Source

`Server.PROPERTY_READ: number`

_Source

`Server.PROPERTY_WRITE: number`

_Source

`Server.PROPERTY_WRITE_WITHOUT_RESPONSE: number`

_Source

`Server.STATE_OFF: number`

_Source

`Server.STATE_ON: number`

_Source

`Server.STATE_TURNING_OFF: number`

_Source

`Server.STATE_TURNING_ON: number`

_Source

`startAdvertising(opts?: AdvertisingOptions): void`

_Source

Start advertising the server.

Parameters

Parameter	Type	Default	Description
`opts?`	`AdvertisingOptions`	—	Advertising options such as the local `name` and the `serviceUUIDs` to advertise.

`Server.state: BluetoothState`

_Source

The current Bluetooth adapter state. One of 'off', 'turningOn', 'on', or 'turningOff'.

`stopAdvertising(): void`

_Source

Stop advertising.

`unpublishChannel(psm: number): void`

_Source

Unpublish an L2CAP channel with the given psm.

Parameters

Parameter	Type	Default	Description
`psm`	`number`	—	The PSM of the channel to unpublish, as assigned when it was published.

`updateValue(characteristic: Characteristic, data: Uint8Array): boolean`

_Source

Update the value of characteristic with data and notify subscribed clients.

Parameters

Parameter	Type	Default	Description
`characteristic`	`Characteristic`	—	The characteristic whose value changed.
`data`	`Uint8Array`	—	The new value to send to subscribed clients.

Returns boolean — Whether the notification was sent to subscribed clients successfully.

Central

`new Central()`

_Source

Create a new BLE central manager for scanning and connecting to peripherals.

`Central.SCAN_MODE_BALANCED: number`

_Source

`Central.SCAN_MODE_LOW_LATENCY: number`

_Source

Scan mode constants for use with central.startScan().

`Central.SCAN_MODE_LOW_POWER: number`

_Source

`Central.SCAN_MODE_OPPORTUNISTIC: number`

_Source

`Central.STATE_OFF: number`

_Source

`Central.STATE_ON: number`

_Source

`Central.STATE_TURNING_OFF: number`

_Source

`Central.STATE_TURNING_ON: number`

_Source

`connect(peripheral: Peripheral): void`

_Source

Connect to a discovered peripheral.

Parameters

Parameter	Type	Default	Description
`peripheral`	`Peripheral`	—	A discovered peripheral to connect to.

`Central.destroy(): void`

_Source

Destroy the central manager, stopping any active scan and disconnecting all connected peripherals.

`disconnect(peripheral: Peripheral): void`

_Source

Disconnect from a connected peripheral.

Parameters

Parameter	Type	Default	Description
`peripheral`	`Peripheral`	—	The connected peripheral to disconnect from.

`startScan(serviceUUIDs?: string[], opts?: { scanMode?: number }): void`

_Source

Start scanning for peripherals advertising the given serviceUUIDs. Pass null to scan for all peripherals.

Parameters

Parameter	Type	Default	Description
`serviceUUIDs?`	`string[]`	—	The service UUIDs to filter advertisements by; pass `null` to scan for all peripherals.
`opts?`	`{ scanMode?: number }`	—	Options; `scanMode` selects the Android scan mode (one of the `Central.SCAN_MODE_*` constants).

`Central.state: BluetoothState`

_Source

The current Bluetooth adapter state. One of 'off', 'turningOn', 'on', or 'turningOff'.

`stopScan(): void`

_Source

Stop scanning for peripherals.

Peripheral

`new Peripheral(opts: PeripheralOptions)`

_Source

Create a new peripheral instance from a ScanResult. Typically obtained via the 'discover' event on Central rather than constructed directly. Its identity and advertised metadata are derived from the scan result.

Parameters

Parameter	Type	Default	Description
`opts`	`PeripheralOptions`	—	Options carrying the `ScanResult` this peripheral is derived from.

`Peripheral.destroy(): void`

_Source

Destroy the peripheral, releasing its underlying resources.

`discoverCharacteristics(service: Service): void`

_Source

Discover characteristics for the given service. Results are emitted via the 'characteristicsDiscover' event.

Parameters

Parameter	Type	Default	Description
`service`	`Service`	—	The service to discover characteristics on.

`discoverServices(): void`

_Source

Discover services offered by the peripheral. Results are emitted via the 'servicesDiscover' event.

`Peripheral.id: string`

_Source

The unique identifier of the peripheral, equal to scanResult.device.address.

`name: string | null`

_Source

The advertised name of the peripheral, or null if unavailable. Equal to scanResult.device.name.

`openL2CAPChannel(psm: number): void`

_Source

Open an L2CAP channel to the peripheral using the given psm. The result is emitted via the 'channelOpen' event.

Parameters

Parameter	Type	Default	Description
`psm`	`number`	—	The PSM (Protocol/Service Multiplexer) of the channel to open.

`Peripheral.PROPERTY_INDICATE: number`

_Source

Characteristic property constants.

`Peripheral.PROPERTY_NOTIFY: number`

_Source

`Peripheral.PROPERTY_READ: number`

_Source

`Peripheral.PROPERTY_WRITE: number`

_Source

`Peripheral.PROPERTY_WRITE_WITHOUT_RESPONSE: number`

_Source

`read(characteristic: Characteristic): void`

_Source

Read the value of characteristic. The result is emitted via the 'read' event.

Parameters

Parameter	Type	Default	Description
`characteristic`	`Characteristic`	—	The characteristic to read.

`requestMtu(mtu: number): void`

_Source

Request a new MTU size. The result is emitted via the 'mtuChanged' event.

Parameters

Parameter	Type	Default	Description
`mtu`	`number`	—	The desired ATT MTU size, in bytes.

Parameters

Parameter	Type	Default	Description
`characteristic`	`Characteristic`	—	The characteristic to start receiving notifications for.

`unsubscribe(characteristic: Characteristic): void`

_Source

Unsubscribe from notifications for characteristic.

Parameters

Parameter	Type	Default	Description
`characteristic`	`Characteristic`	—	The characteristic to stop receiving notifications for.

`write(characteristic: Characteristic, data: Uint8Array, withResponse?: boolean): void`

_Source

Write data to characteristic. If withResponse is true (the default), a write confirmation is requested.

Parameters

Parameter	Type	Default	Description
`characteristic`	`Characteristic`	—	The characteristic to write to.
`data`	`Uint8Array`	—	The bytes to write.
`withResponse?`	`boolean`	—	Whether a write confirmation is requested (default `true`).

Types

`ServiceOptions`

interface ServiceOptions {
  primary?: boolean
}

_Source

`CharacteristicOptions`

interface CharacteristicOptions {
  read?: boolean
  write?: boolean
  writeWithoutResponse?: boolean
  notify?: boolean
  indicate?: boolean
  permissions?: number
  value?: Uint8Array | null
}

_Source

`BluetoothState`

type BluetoothState = 'off' | 'turningOn' | 'on' | 'turningOff'

_Source

`AdvertisingOptions`

interface AdvertisingOptions {
  name?: string
  serviceUUIDs?: string[]
}

_Source

`ChannelOptions`

interface ChannelOptions {
  encrypted?: boolean
}

_Source

`ReadRequest`

interface ReadRequest {
  handle: unknown
  requestId: number
  characteristicUuid: string
  offset: number
}

_Source

`WriteRequest`

interface WriteRequest {
  handle: unknown
  requestId: number
  characteristicUuid: string
  data: Uint8Array
  offset: number
  responseNeeded: boolean
}

_Source

`PeripheralOptions`

interface PeripheralOptions {
  scanResult: ScanResult
}

_Source

`ServiceData`

type ServiceData = {
  [uuid: string]: Uint8Array
}

_Source

Classes

`ScanResult`

_Source

class ScanResult {
  device: Device
  rssi: number
  scanRecord: ScanRecord | null
}

`ScanRecord`

_Source

class ScanRecord {
  serviceData: ServiceData | null
}

`Device`

_Source

class Device {
  address: string
  name: string | null
}

bare-bluetooth-android

On this page