LogoPear Docs
ReferencesBareModules

bare-bluetooth-apple

CoreBluetooth bindings for Bare

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)

Source

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

ParameterTypeDefaultDescription
channelHandleArrayBufferThe native channel handle backing the stream; supplied internally when a channel opens, not usually passed directly.

peer: string | null

Source

The UUID of the remote peer if available

psm: number

Source

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

Service

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

Source

Create a GATT service definition.

Parameters

ParameterTypeDefaultDescription
uuidstringThe service's UUID.
characteristics?Characteristic[]The characteristics belonging to the service.
opts?ServiceOptionsOptions; set primary: true to mark this a primary service.

characteristics: Characteristic[]

Source

The characteristics belonging to this service

primary: boolean

Source

Whether this is a primary service

Service.uuid: string

Source

The service UUID

Characteristic

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

Source

Create a GATT characteristic definition.

Parameters

ParameterTypeDefaultDescription
uuidstringThe characteristic's UUID.
opts?CharacteristicOptionsOptions selecting the characteristic properties (read, write, writeWithoutResponse, notify, indicate) and its optional permissions and initial value.

Characteristic.PROPERTY_INDICATE: number

Source

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

Bitmask of characteristic permissions, if set explicitly

properties: number

Source

Bitmask of characteristic properties

Characteristic.uuid: string

Source

The characteristic UUID

value: Uint8Array | null

Source

The current value, if set

PeripheralManager

new PeripheralManager()

Source

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

addService(service: Service): void

Source

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

Parameters

ParameterTypeDefaultDescription
serviceServiceThe Service to register with the system, along with its characteristics.

PeripheralManager.destroy(): void

Source

Destroy the instance and release all resources.

PeripheralManager.ATT_INSUFFICIENT_RESOURCES: number

Source

PeripheralManager.ATT_INVALID_HANDLE: number

Source

PeripheralManager.ATT_READ_NOT_PERMITTED: number

Source

PeripheralManager.ATT_SUCCESS: number

Source

PeripheralManager.ATT_UNLIKELY_ERROR: number

Source

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

PeripheralManager.ATT_WRITE_NOT_PERMITTED: number

Source

PeripheralManager.PERMISSION_READ_ENCRYPTED: number

Source

PeripheralManager.PERMISSION_READABLE: number

Source

PeripheralManager.PERMISSION_WRITE_ENCRYPTED: number

Source

Characteristic permission flags.

PeripheralManager.PERMISSION_WRITEABLE: number

Source

PeripheralManager.PROPERTY_INDICATE: number

Source

Characteristic property flags.

PeripheralManager.PROPERTY_NOTIFY: number

Source

PeripheralManager.PROPERTY_READ: number

Source

PeripheralManager.PROPERTY_WRITE: number

Source

PeripheralManager.PROPERTY_WRITE_WITHOUT_RESPONSE: number

Source

PeripheralManager.STATE_POWERED_OFF: number

Source

PeripheralManager.STATE_POWERED_ON: number

Source

PeripheralManager.STATE_RESETTING: number

Source

PeripheralManager.STATE_UNAUTHORIZED: number

Source

PeripheralManager.STATE_UNKNOWN: number

Source

PeripheralManager.STATE_UNSUPPORTED: number

Source

Bluetooth state constants.

publishChannel(opts?: ChannelOptions): void

Source

Publish an L2CAP channel.

Parameters

ParameterTypeDefaultDescription
opts?ChannelOptionsOptions for the L2CAP channel to publish.

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

Source

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

Parameters

ParameterTypeDefaultDescription
requestReadRequestThe read or write request to respond to, as delivered by the 'readRequest'/'writeRequest' event.
resultnumberThe ATT result code, e.g. PeripheralManager.ATT_SUCCESS.
data?Uint8Array | nullThe value to return for a read request; omit for write responses.

startAdvertising(opts?: AdvertisingOptions): void

Source

Start advertising.

Parameters

ParameterTypeDefaultDescription
opts?AdvertisingOptionsAdvertising options such as the local name and the serviceUUIDs to advertise.

PeripheralManager.state: BluetoothState

Source

The current Bluetooth adapter state

stopAdvertising(): void

Source

Stop advertising.

unpublishChannel(psm: number): void

Source

Unpublish a previously published L2CAP channel identified by psm.

Parameters

ParameterTypeDefaultDescription
psmnumberThe PSM of the channel to unpublish, as assigned when it was published.

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

Source

Update the value of a characteristic and notify subscribed centrals.

Parameters

ParameterTypeDefaultDescription
characteristicCharacteristicThe characteristic whose value changed.
dataUint8ArrayThe new value to send to subscribed centrals.

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

Central

new Central()

Source

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

Central.STATE_POWERED_OFF: number

Source

Central.STATE_POWERED_ON: number

Source

Central.STATE_RESETTING: number

Source

Central.STATE_UNAUTHORIZED: number

Source

Central.STATE_UNKNOWN: number

Source

Central.STATE_UNSUPPORTED: number

Source

connect(peripheral: DiscoveredPeripheral): void

Source

Connect to a discovered peripheral.

Parameters

ParameterTypeDefaultDescription
peripheralDiscoveredPeripheralA discovered peripheral to connect to.

Central.destroy(): void

Source

Destroy the instance and release all resources.

disconnect(peripheral: Peripheral): void

Source

Disconnect from a connected peripheral.

Parameters

ParameterTypeDefaultDescription
peripheralPeripheralThe connected peripheral to disconnect from.

startScan(serviceUUIDs?: string[]): void

Source

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

Parameters

ParameterTypeDefaultDescription
serviceUUIDs?string[]The service UUIDs to filter advertisements by; omit to discover all peripherals.

Central.state: BluetoothState

Source

The current Bluetooth adapter state

stopScan(): void

Source

Stop scanning for peripherals.

Peripheral

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

Source

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

Parameters

ParameterTypeDefaultDescription
peripheralHandleArrayBufferThe native peripheral handle; supplied internally when Central emits 'connect', not usually passed directly.
opts?PeripheralOptionsOptions carrying the peripheral's advertised metadata.

Peripheral.destroy(): void

Source

Destroy the instance and release all resources.

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

Source

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

Parameters

ParameterTypeDefaultDescription
serviceServiceThe service to discover characteristics on.
characteristicUUIDs?string[]The characteristic UUIDs to discover; omit to discover all characteristics of the service.

discoverServices(serviceUUIDs?: string[]): void

Source

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

Parameters

ParameterTypeDefaultDescription
serviceUUIDs?string[]The service UUIDs to discover; omit to discover all services.

id: string

Source

The peripheral UUID identifier

name: string | null

Source

The peripheral name, if available

openL2CAPChannel(psm: number): void

Source

Open an L2CAP channel to the peripheral using the given psm.

Parameters

ParameterTypeDefaultDescription
psmnumberThe PSM (Protocol/Service Multiplexer) of the channel to open.

Peripheral.PROPERTY_INDICATE: number

Source

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 a characteristic.

Parameters

ParameterTypeDefaultDescription
characteristicCharacteristicThe characteristic to read.

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

Source

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

subscribe(characteristic: Characteristic): void

Source

Subscribe to notifications for a characteristic.

Parameters

ParameterTypeDefaultDescription
characteristicCharacteristicThe characteristic to start receiving notifications for.

unsubscribe(characteristic: Characteristic): void

Source

Unsubscribe from notifications for a characteristic.

Parameters

ParameterTypeDefaultDescription
characteristicCharacteristicThe characteristic to stop receiving notifications for.

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

Source

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

Parameters

ParameterTypeDefaultDescription
characteristicCharacteristicThe characteristic to write to.
dataUint8ArrayThe bytes to write.
withResponse?booleanWhether the peripheral confirms the write (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 = 'unknown' | 'resetting' | 'unsupported' | 'unauthorized' | 'poweredOff' | 'poweredOn'
Source

AdvertisingOptions

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

ChannelOptions

interface ChannelOptions {
  encrypted?: boolean
}
Source

ReadRequest

interface ReadRequest {
  characteristicUuid: string
  offset: number
}
Source

WriteRequest

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

PeripheralManagerEventMap

interface PeripheralManagerEventMap extends EventMap {
  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: []
}
Source

DiscoveredPeripheral

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

CentralEventMap

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

PeripheralOptions

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

PeripheralEventMap

interface PeripheralEventMap extends EventMap {
  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]
}
Source

See also

On this page

Usage
API
L2CAPChannel
new L2CAPChannel(channelHandle: ArrayBuffer)
peer: string | null
psm: number
Service
new Service(uuid: string, characteristics?: Characteristic[], opts?: ServiceOptions)
characteristics: Characteristic[]
primary: boolean
Service.uuid: string
Characteristic
new Characteristic(uuid: string, opts?: CharacteristicOptions)
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
properties: number
Characteristic.uuid: string
value: Uint8Array | null
PeripheralManager
new PeripheralManager()
addService(service: Service): void
PeripheralManager.destroy(): void
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
PeripheralManager.ATT_WRITE_NOT_PERMITTED: number
PeripheralManager.PERMISSION_READ_ENCRYPTED: number
PeripheralManager.PERMISSION_READABLE: number
PeripheralManager.PERMISSION_WRITE_ENCRYPTED: number
PeripheralManager.PERMISSION_WRITEABLE: number
PeripheralManager.PROPERTY_INDICATE: number
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
publishChannel(opts?: ChannelOptions): void
respondToRequest(request: ReadRequest, result: number, data?: Uint8Array | null): void
startAdvertising(opts?: AdvertisingOptions): void
PeripheralManager.state: BluetoothState
stopAdvertising(): void
unpublishChannel(psm: number): void
updateValue(characteristic: Characteristic, data: Uint8Array): boolean
Central
new Central()
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
Central.destroy(): void
disconnect(peripheral: Peripheral): void
startScan(serviceUUIDs?: string[]): void
Central.state: BluetoothState
stopScan(): void
Peripheral
new Peripheral(peripheralHandle: ArrayBuffer, opts?: PeripheralOptions)
Peripheral.destroy(): void
discoverCharacteristics(service: Service, characteristicUUIDs?: string[]): void
discoverServices(serviceUUIDs?: string[]): void
id: string
name: string | null
openL2CAPChannel(psm: number): void
Peripheral.PROPERTY_INDICATE: number
Peripheral.PROPERTY_NOTIFY: number
Peripheral.PROPERTY_READ: number
Peripheral.PROPERTY_WRITE: number
Peripheral.PROPERTY_WRITE_WITHOUT_RESPONSE: number
read(characteristic: Characteristic): void
serviceData: { [uuid: string]: Uint8Array } | null
subscribe(characteristic: Characteristic): void
unsubscribe(characteristic: Characteristic): void
write(characteristic: Characteristic, data: Uint8Array, withResponse?: boolean): void
Types
ServiceOptions
CharacteristicOptions
BluetoothState
AdvertisingOptions
ChannelOptions
ReadRequest
WriteRequest
PeripheralManagerEventMap
DiscoveredPeripheral
CentralEventMap
PeripheralOptions
PeripheralEventMap
See also