bare-bluetooth-apple

stable

bare-bluetooth-apple — CoreBluetooth bindings for Bare. It is a native addon.

npm i bare-bluetooth-apple

Usage

const bluetooth = require('bare-bluetooth-apple')

const manager = new bluetooth.PeripheralManager()

manager.on('stateChange', (state) => {
  if (state !== 'poweredOn') return

  const char = new bluetooth.Characteristic('01230001-0000-1000-8000-00805F9B34FB', {
    write: true,
    notify: true
  })

  const service = new bluetooth.Service('01230000-0000-1000-8000-00805F9B34FB', [char])
  manager.addService(service)
})

manager.on('serviceAdd', (uuid, error) => {
  if (error) return

  manager.startAdvertising({
    name: 'MyDevice',
    serviceUUIDs: ['01230000-0000-1000-8000-00805F9B34FB']
  })
})

manager.on('writeRequest', (requests) => {
  // Handle incoming write requests
  manager.respondToRequest(requests[0], bluetooth.PeripheralManager.ATT_SUCCESS, null)
})

API

L2CAPChannel

`new L2CAPChannel(channelHandle: ArrayBuffer)`

An L2CAP channel, obtained through the 'channelOpen' event on PeripheralManager or Peripheral. Extends Duplex from bare-stream and supports standard readable and writable stream operations.

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`

The UUID of the remote peer if available

`psm: number`

The L2CAP PSM (Protocol/Service Multiplexer) for this channel

Service

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

Create a 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[]`

The characteristics belonging to this service

`primary: boolean`

Whether this is a primary service

`Service.uuid: string`

The service UUID

Characteristic

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

Create a GATT characteristic definition.

Parameters

Parameter	Type	Default	Description
`uuid`	`string`	—	The characteristic's UUID.
`opts?`	`CharacteristicOptions`	—	Options selecting the characteristic `properties` (`read`, `write`, `writeWithoutResponse`, `notify`, `indicate`) and its optional `permissions` and initial `value`.

`Characteristic.PROPERTY_INDICATE: number`

`Characteristic.PROPERTY_NOTIFY: number`

`Characteristic.PROPERTY_READ: number`

`Characteristic.PROPERTY_WRITE: number`

`Characteristic.PROPERTY_WRITE_WITHOUT_RESPONSE: number`

`permissions: number | null`

Bitmask of characteristic permissions, if set explicitly

`properties: number`

Bitmask of characteristic properties

`Characteristic.uuid: string`

The characteristic UUID

`value: Uint8Array | null`

The current value, if set

PeripheralManager

`new PeripheralManager()`

Create a new BLE peripheral manager. Advertises services and handles read/write requests from centrals.

`addService(service: Service): void`

Add a service to the manager. The service and its characteristics will be registered with the system.

Parameters

Parameter	Type	Default	Description
`service`	`Service`	—	The `Service` to register with the system, along with its characteristics.

`PeripheralManager.destroy(): void`

Destroy the instance and release all resources.

`PeripheralManager.ATT_INSUFFICIENT_RESOURCES: number`

`PeripheralManager.ATT_INVALID_HANDLE: number`

`PeripheralManager.ATT_READ_NOT_PERMITTED: number`

`PeripheralManager.ATT_SUCCESS: number`

`PeripheralManager.ATT_UNLIKELY_ERROR: number`

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

`PeripheralManager.ATT_WRITE_NOT_PERMITTED: number`

`PeripheralManager.PERMISSION_READ_ENCRYPTED: number`

`PeripheralManager.PERMISSION_READABLE: number`

`PeripheralManager.PERMISSION_WRITE_ENCRYPTED: number`

Characteristic permission flags.

`PeripheralManager.PERMISSION_WRITEABLE: number`

`PeripheralManager.PROPERTY_INDICATE: number`

Characteristic property flags.

`PeripheralManager.PROPERTY_NOTIFY: number`

`PeripheralManager.PROPERTY_READ: number`

`PeripheralManager.PROPERTY_WRITE: number`

`PeripheralManager.PROPERTY_WRITE_WITHOUT_RESPONSE: number`

`PeripheralManager.STATE_POWERED_OFF: number`

`PeripheralManager.STATE_POWERED_ON: number`

`PeripheralManager.STATE_RESETTING: number`

`PeripheralManager.STATE_UNAUTHORIZED: number`

`PeripheralManager.STATE_UNKNOWN: number`

`PeripheralManager.STATE_UNSUPPORTED: number`

Bluetooth state constants.

`publishChannel(opts?: ChannelOptions): void`

Publish an L2CAP channel.

Parameters

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

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

Respond to a read or write request with the given ATT result code. Optionally include data for read responses.

Parameters

Parameter	Type	Default	Description
`request`	`ReadRequest`	—	The read or write request to respond to, as delivered by the `'readRequest'`/`'writeRequest'` event.
`result`	`number`	—	The ATT result code, for example `PeripheralManager.ATT_SUCCESS`.
`data?`	`Uint8Array` \| `null`	—	The value to return for a read request; omit for write responses.

`startAdvertising(opts?: AdvertisingOptions): void`

Start advertising.

Parameters

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

`PeripheralManager.state: BluetoothState`

The current Bluetooth adapter state

`stopAdvertising(): void`

Stop advertising.

`unpublishChannel(psm: number): void`

Unpublish a previously published L2CAP channel identified by 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`

Update the value of a characteristic and notify subscribed centrals.

Parameters

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

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

Central

`new Central()`

Create a new BLE central manager. The central scans for and connects to peripherals.

`Central.STATE_POWERED_OFF: number`

`Central.STATE_POWERED_ON: number`

`Central.STATE_RESETTING: number`

`Central.STATE_UNAUTHORIZED: number`

`Central.STATE_UNKNOWN: number`

`Central.STATE_UNSUPPORTED: number`

`connect(peripheral: DiscoveredPeripheral): void`

Connect to a discovered peripheral.

Parameters

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

`Central.destroy(): void`

Destroy the instance and release all resources.

`disconnect(peripheral: Peripheral): void`

Disconnect from a connected peripheral.

Parameters

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

`startScan(serviceUUIDs?: string[], opts?: { allowDuplicates?: boolean }): void`

Start scanning for peripherals. If serviceUUIDs is provided, only peripherals advertising those services will be discovered.

Parameters

Parameter	Type	Default	Description
`serviceUUIDs?`	`string[]`	—	The service UUIDs to filter advertisements by; omit to discover all peripherals.
`opts?`	`{ allowDuplicates?: boolean }`	—	—

`Central.state: BluetoothState`

The current Bluetooth adapter state

`stopScan(): void`

Stop scanning for peripherals.

Peripheral

`new Peripheral(peripheralHandle: ArrayBuffer, opts?: PeripheralOptions)`

Represents a connected BLE peripheral. Obtained through the 'connect' event on Central — not typically constructed directly.

Parameters

Parameter	Type	Default	Description
`peripheralHandle`	`ArrayBuffer`	—	The native peripheral handle; supplied internally when Central emits `'connect'`, not usually passed directly.
`opts?`	`PeripheralOptions`	—	Options carrying the peripheral's advertised metadata.

`Peripheral.destroy(): void`

Destroy the instance and release all resources.

`discoverCharacteristics(service: Service, characteristicUUIDs?: string[]): void`

Discover characteristics for a service. If characteristicUUIDs is provided, only those characteristics will be discovered.

Parameters

Parameter	Type	Default	Description
`service`	`Service`	—	The service to discover characteristics on.
`characteristicUUIDs?`	`string[]`	—	The characteristic UUIDs to discover; omit to discover all characteristics of the service.

`discoverServices(serviceUUIDs?: string[]): void`

Discover services on the peripheral. If serviceUUIDs is provided, only those services will be discovered.

Parameters

Parameter	Type	Default	Description
`serviceUUIDs?`	`string[]`	—	The service UUIDs to discover; omit to discover all services.

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

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

`serviceData: { [uuid: string]: Uint8Array } | null`

Service data captured from the most recent advertisement seen before connect, or null

`subscribe(characteristic: Characteristic): void`

Subscribe to notifications for a characteristic.

Parameters

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

`unsubscribe(characteristic: Characteristic): void`

Unsubscribe from notifications for a characteristic.

Parameters

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

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

Write data to a characteristic. If withResponse is true (the default), the write will be confirmed by the peripheral.

Parameters

Parameter	Type	Default	Description
`characteristic`	`Characteristic`	—	The characteristic to write to.
`data`	`Uint8Array`	—	The bytes to write.
`withResponse?`	`boolean`	—	Whether the peripheral confirms the write (default `true`).

Types

`ServiceOptions`

interface ServiceOptions {
  primary?: boolean
}

`CharacteristicOptions`

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

`BluetoothState`

type BluetoothState = 'unknown' | 'resetting' | 'unsupported' | 'unauthorized' | 'poweredOff' | 'poweredOn'

`AdvertisingOptions`

interface AdvertisingOptions {
  name?: string
  serviceUUIDs?: string[]
  serviceData?: { [uuid: string]: Uint8Array }
}

`ChannelOptions`

interface ChannelOptions {
  encrypted?: boolean
}

`ReadRequest`

interface ReadRequest {
  characteristicUuid: string
  offset: number
}

`WriteRequest`

interface WriteRequest {
  characteristicUuid: string
  data: Uint8Array
  offset: number
}

`PeripheralManagerEventMap`

interface PeripheralManagerEventMap {
  stateChange: [state: BluetoothState]
  error: [error: BluetoothError]
  serviceAdd: [uuid: string]
  channelPublish: [psm: number]
  channelOpen: [channel: L2CAPChannel]
  readRequest: [request: ReadRequest]
  writeRequest: [requests: WriteRequest[]]
  subscribe: [centralHandle: ArrayBuffer, characteristicUuid: string]
  unsubscribe: [centralHandle: ArrayBuffer, characteristicUuid: string]
  readyToUpdate: []
}

`DiscoveredPeripheral`

interface DiscoveredPeripheral {
  id: string
  name: string | null
  rssi: number
  serviceData: { [uuid: string]: Uint8Array } | null
}

`CentralEventMap`

interface CentralEventMap {
  stateChange: [state: BluetoothState]
  error: [error: BluetoothError]
  discover: [peripheral: DiscoveredPeripheral]
  connect: [peripheral: Peripheral]
  disconnect: [peripheral: Peripheral | null]
}

`PeripheralOptions`

interface PeripheralOptions {
  central?: Central
  id?: string
  name?: string
  serviceData?: { [uuid: string]: Uint8Array } | null
}

`PeripheralEventMap`

interface PeripheralEventMap {
  error: [error: BluetoothError]
  servicesDiscover: [services: Service[]]
  characteristicsDiscover: [service: Service | null, characteristics: Characteristic[]]
  read: [characteristic: Characteristic | null, data: Uint8Array | null]
  write: [characteristic: Characteristic | null]
  notify: [characteristic: Characteristic | null, data: Uint8Array | null]
  notifyState: [characteristic: Characteristic | null, isNotifying: boolean]
  channelOpen: [channel: L2CAPChannel]
}

bare-bluetooth-apple

On this page