bare-bluetooth-apple
CoreBluetooth bindings for Bare
bare-bluetooth-apple — CoreBluetooth bindings for Bare. It is a native addon.
npm i bare-bluetooth-appleUsage
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
| 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 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
| 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 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
| 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
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
| Parameter | Type | Default | Description |
|---|---|---|---|
service | Service | — | The 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
| Parameter | Type | Default | Description |
|---|---|---|---|
opts? | ChannelOptions | — | Options 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
| 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, e.g. PeripheralManager.ATT_SUCCESS. |
data? | Uint8Array | null | — | The value to return for a read request; omit for write responses. |
startAdvertising(opts?: AdvertisingOptions): void
Source
Start advertising.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
opts? | AdvertisingOptions | — | Advertising 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
| 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 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()
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
| Parameter | Type | Default | Description |
|---|---|---|---|
peripheral | DiscoveredPeripheral | — | A 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
| Parameter | Type | Default | Description |
|---|---|---|---|
peripheral | Peripheral | — | The 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
| Parameter | Type | Default | Description |
|---|---|---|---|
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
| 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
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
| 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
Source
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. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
psm | number | — | The 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
| Parameter | Type | Default | Description |
|---|---|---|---|
characteristic | Characteristic | — | The 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
| Parameter | Type | Default | Description |
|---|---|---|---|
characteristic | Characteristic | — | The characteristic to start receiving notifications for. |
unsubscribe(characteristic: Characteristic): void
Source
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
Source
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 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: []
}DiscoveredPeripheral
interface DiscoveredPeripheral {
id: string
name: string | null
rssi: number
serviceData: { [uuid: string]: Uint8Array } | null
}CentralEventMap
interface CentralEventMap extends EventMap {
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 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]
}See also
- Bare modules — the full
bare-*catalog. - Bare runtime API — the runtime these modules extend.