Skip to content

Latest commit

 

History

History
1490 lines (1108 loc) · 39.7 KB

BluetoothControlPlugin.md

File metadata and controls

1490 lines (1108 loc) · 39.7 KB
Raw

Bluetooth Control Plugin

Version: 1.0

Status: ⚫⚪⚪

BluetoothControl plugin for Thunder framework.

Table of Contents

Introduction

Scope

This document describes purpose and functionality of the BluetoothControl plugin. It includes detailed specification about its configuration, methods and properties as well as sent notifications.

Case Sensitivity

All identifiers of the interfaces described in this document are case-sensitive. Thus, unless stated otherwise, all keywords, entities, properties, relations and actions should be treated as such.

Acronyms, Abbreviations and Terms

The table below provides and overview of acronyms used in this document and their definitions.

Acronym Description
API Application Programming Interface
HTTP Hypertext Transfer Protocol
JSON JavaScript Object Notation; a data interchange format
JSON-RPC A remote procedure call protocol encoded in JSON

The table below provides and overview of terms and abbreviations used in this document and their definitions.

Term Description
callsign The name given to an instance of a plugin. One plugin can be instantiated multiple times, but each instance the instance name, callsign, must be unique.

References

Ref ID Description
HTTP HTTP specification
JSON-RPC JSON-RPC 2.0 specification
JSON JSON specification
Thunder Thunder API Reference

Description

The Bluetooth Control plugin allows Bluetooth device administration.

The plugin is designed to be loaded and executed within the Thunder framework. For more information about the framework refer to [Thunder].

Configuration

The table below lists configuration options of the plugin.

Name Type Description
callsign string Plugin instance name (default: BluetoothControl)
classname string Class name: BluetoothControl
locator string Library name: libThunderBluetoothControl.so
startmode string Determines if the plugin shall be started automatically along with the framework
configuration object (optional)
configuration?.interface number (optional) ID of the local Bluetooth interface
configuration?.autopasskeyconfirm boolean (optional) Enable automatic passkey confirmation (may pose a security risk)
configuration?.persistmac boolean (optional) Enable persistent Bluetooth address
configuration?.name String (optional) Name of the local Bluetooth interface
configuration?.shortname String (optional) Shortened name of the local Bluetooth interface
configuration?.class number (optional) Class of device value of the local Bluetooth interface
configuration?.uuids array (optional) UUIDs to include in the outbound EIR/AD blocks
configuration?.uuids[#] object (optional) (UUID entry)
configuration?.uuids[#]?.callsign string (optional) Callsign of the plugin providing the service
configuration?.uuids[#]?.uuid string (optional) UUID value (short or long)
configuration?.uuids[#]?.service integer (optional) Corresponding service bit in Class of Device value

Interfaces

This plugin implements the following interfaces:

Methods

The following methods are provided by the BluetoothControl plugin:

BluetoothControl interface methods:

Method Description
setdiscoverable Starts advertising (or inquiry scanning), making the local interface visible by nearby Bluetooth devices
stopdiscoverable Stops advertising (or inquiry scanning) operation
scan Starts active discovery (or inquiry) of nearby Bluetooth devices
stopscanning Stops discovery (or inquiry) operation
connect Connects to a Bluetooth device
disconnect Disconnects from a connected Bluetooth device
pair Pairs a Bluetooth device
unpair Unpairs a paired Bluetooth device
abortpairing Aborts pairing operation
providepincode Provides a PIN-code for authentication during a legacy pairing process
providepasskey Provides a passkey for authentication during a pairing process
confirmpasskey Confirms a passkey for authentication during a pairing process
forget Forgets a known Bluetooth device
getdevicelist Retrieves a list of known remote Bluetooth devices
getdeviceinfo Retrieves detailed information about a known Bluetooth device

setdiscoverable method

Starts advertising (or inquiry scanning), making the local interface visible by nearby Bluetooth devices.

Description

Please note that discoverable state in Limited mode for Bluetooth Classic is bounded to 30 seconds only.

Also see: discoverablestarted, discoverablecomplete

Parameters

Name Type Description
params object
params.type string Discoverable type (must be one of the following: Classic, LowEnergy)
params?.mode string (optional) Discoverable mode (must be one of the following: General, Limited) (default: General)
params?.connectable boolean (optional) Selects connectable advertising (true, LowEnergy only) (default: False)
params?.duration integer (optional) Duration of the discoverable operation (in seconds) (default: 30)

Result

Name Type Description
result null Always null

Errors

Code Message Description
1 ERROR_GENERAL Failed set discoverable state
12 ERROR_INPROGRESS Discoverable state of selected type is already in progress

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.setdiscoverable",
  "params": {
    "type": "LowEnergy",
    "mode": "General",
    "connectable": false,
    "duration": 30
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

stopdiscoverable method

Stops advertising (or inquiry scanning) operation.

Also see: discoverablecomplete

Parameters

Name Type Description
params object
params.type string Discoverable type (must be one of the following: Classic, LowEnergy)

Result

Name Type Description
result null Always null

Errors

Code Message Description
1 ERROR_GENERAL Failed to top scanning
5 ERROR_ILLEGAL_STATE Adapter is in not discoverable state of selected type

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.stopdiscoverable",
  "params": {
    "type": "LowEnergy"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

scan method

Starts active discovery (or inquiry) of nearby Bluetooth devices.

Also see: scanstarted, scancomplete

Parameters

Name Type Description
params object
params.type string Scan type (must be one of the following: Classic, LowEnergy)
params?.mode string (optional) Scan mode (must be one of the following: General, Limited) (default: General)
params?.timeout integer (deprecated) (optional) Duration of the scan (in seconds) (default: 10)
params?.duration integer (optional) Duration of the scan (in seconds) (default: 10)

Result

Name Type Description
result null Always null

Errors

Code Message Description
1 ERROR_GENERAL Failed to scan
12 ERROR_INPROGRESS Scan of selected type is already in progress

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.scan",
  "params": {
    "type": "LowEnergy",
    "mode": "General",
    "duration": 60
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

stopscanning method

Stops discovery (or inquiry) operation.

Also see: scancomplete

Parameters

Name Type Description
params object
params?.type string (optional) Scan type (must be one of the following: Classic, LowEnergy) (default: LowEnergy)

Result

Name Type Description
result null Always null

Errors

Code Message Description
1 ERROR_GENERAL Failed to top scanning
5 ERROR_ILLEGAL_STATE Scan of selected type is not in progress

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.stopscanning",
  "params": {
    "type": "LowEnergy"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

connect method

Connects to a Bluetooth device.

Description

This call also enables automatic reconnection of the device. If the device is currently not available it will be automatically connected as soon it becomes available.

Also see: devicestatechange

Parameters

Name Type Description
params object
params.address string Bluetooth address
params?.type string (optional) Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom) (default: LowEnergy)

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown device
5 ERROR_ILLEGAL_STATE Device not paired
9 ERROR_ALREADY_CONNECTED Device already connected
1 ERROR_GENERAL Failed to connect the device
27 ERROR_REQUEST_SUBMITTED Device has not been connected but will be automatically connected when available

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.connect",
  "params": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "LowEnergy"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

disconnect method

Disconnects from a connected Bluetooth device.

Description

This call also disables automatic reconnection. If the device is currently not connected it will not be reconnected when it becomes available.

Also see: devicestatechange

Parameters

Name Type Description
params object
params.address string Bluetooth address
params?.type string (optional) Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom) (default: LowEnergy)

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown device
36 ERROR_ALREADY_RELEASED Device not connected
27 ERROR_REQUEST_SUBMITTED Device is currently not connected but it's autoconnection mode has been disabled

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.disconnect",
  "params": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "LowEnergy"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

pair method

Pairs a Bluetooth device.

Description

PIN-code or passkey requests may appear during the pairing process. The process can be cancelled any time by calling the abortpairing method.

Also see: devicestatechange, pincoderequest, passkeyrequest, passkeyconfirmrequest

Parameters

Name Type Description
params object
params.address string Bluetooth address
params?.type string (optional) Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom) (default: LowEnergy)
params?.capabilities string (optional) Pairing capabilities (must be one of the following: DisplayOnly, DisplayYesNo, KeyboardOnly, NoInputNoOutput, KeyboardDisplay) (default: NoInputNoOutput)
params?.timeout integer (optional) Maximum time allowed for the pairing process to complete (in seconds) (default: 20)

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown device
9 ERROR_ALREADY_CONNECTED Device already paired
1 ERROR_GENERAL Failed to pair the device

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.pair",
  "params": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "LowEnergy",
    "capabilities": "NoInputNoOutput",
    "timeout": 60
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

unpair method

Unpairs a paired Bluetooth device.

Also see: devicestatechange

Parameters

Name Type Description
params object
params.address string Bluetooth address
params?.type string (optional) Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom) (default: LowEnergy)

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown device
36 ERROR_ALREADY_RELEASED Device not paired

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.unpair",
  "params": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "LowEnergy"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

abortpairing method

Aborts pairing operation.

Also see: devicestatechange

Parameters

Name Type Description
params object
params.address string Bluetooth address
params?.type string (optional) Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom) (default: LowEnergy)

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown device
5 ERROR_ILLEGAL_STATE Device not currently pairing

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.abortpairing",
  "params": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "LowEnergy"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

providepincode method

Provides a PIN-code for authentication during a legacy pairing process.

Description

This method should be called upon receiving a pincoderequest event during a legacy pairing process. If the specified PIN-code is incorrect the pairing process will be aborted.

Also see: devicestatechange, pincoderequest

Parameters

Name Type Description
params object
params.address string Bluetooth address
params.type string Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
params.secret string A PIN-code string typically consisting of (but not limited to) four decimal digits

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown device
5 ERROR_ILLEGAL_STATE Device not currently pairing or PIN code has not been requested

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.providepincode",
  "params": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "Classic",
    "secret": "0000"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

providepasskey method

Provides a passkey for authentication during a pairing process.

Description

This method should be called upon receiving a passkeyrequest event during pairing process. If the specified passkey is incorrect or empty the pairing process will be aborted.

Also see: devicestatechange, passkeyrequest

Parameters

Name Type Description
params object
params.address string Bluetooth address
params.type string Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
params.secret integer A six-digit decimal number passkey

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown device
5 ERROR_ILLEGAL_STATE Device not currently pairing or a passkey has not been requested

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.providepasskey",
  "params": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "Classic",
    "secret": 123456
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

confirmpasskey method

Confirms a passkey for authentication during a pairing process.

Description

This method should be called upon receiving a passkeyconfirmationrequest event during a pairing process. If the confirmation is negative the pairing process will be aborted.

Also see: devicestatechange, passkeyconfirmrequest

Parameters

Name Type Description
params object
params.address string Bluetooth address
params.type string Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
params.iscorrect boolean Specifies if the passkey sent in passkeyconfirmrequest event is correct (true) or incorrect (false)

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown device
5 ERROR_ILLEGAL_STATE Device is currently not pairing or passkey confirmation has not been requested

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.confirmpasskey",
  "params": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "Classic",
    "iscorrect": true
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

forget method

Forgets a known Bluetooth device.

Description

The device will no longer be listed and its status tracked. If the device is connected and/or paired it will be disconnected and unpaired.

Also see: devicestatechange

Parameters

Name Type Description
params object
params.address string Bluetooth address
params.type string Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom)

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown device

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.forget",
  "params": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "LowEnergy"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

getdevicelist method

Retrieves a list of known remote Bluetooth devices.

Parameters

This method takes no parameters.

Result

Name Type Description
result array List of devices
result[#] object (device entry)
result[#].address string Bluetooth address
result[#].type string Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom)

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.getdevicelist"
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    {
      "address": "81:6F:B0:91:9B:FE",
      "type": "LowEnergy"
    }
  ]
}

getdeviceinfo method

Retrieves detailed information about a known Bluetooth device.

Parameters

Name Type Description
params object
params.address string Bluetooth address
params.type string Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom)

Result

Name Type Description
result object
result.address string Bluetooth address
result.type string Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
result?.name string (optional) Name of the device
result?.class integer (optional) Class of device
result?.appearance integer (optional) Appearance value
result?.services array (optional) List of supported services
result?.services[#] string (optional) Service UUID
result.connected boolean Indicates if the device is currently connected
result.paired boolean Indicates if the device is currently paired

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown device

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.getdeviceinfo",
  "params": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "LowEnergy"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "Classic",
    "name": "Thunder Bluetooth Speaker",
    "class": 2360324,
    "appearance": 2113,
    "services": [
      "110a"
    ],
    "connected": true,
    "paired": true
  }
}

Properties

The following properties are provided by the BluetoothControl plugin:

BluetoothControl interface properties:

Property Description
adapters RO List of local Bluetooth adapters
adapter RO Local Bluetooth adapter information
deprecated devices RO List of known remote Bluetooth devices
deprecated device RO Remote Bluetooth device information

adapters property

Provides access to the list of local Bluetooth adapters.

This property is read-only.

Value

Result

Name Type Description
result array List of local Bluetooth adapters
result[#] integer Adapter ID

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.adapters"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    0
  ]
}

adapter property

Provides access to the local Bluetooth adapter information.

This property is read-only.

Value

The adapter id argument shall be passed as the index to the property, e.g. BluetoothControl.1.adapter@0.

Result

Name Type Description
result object Local Bluetooth adapter information
result.id integer Interface ID number
result.interface string Interface name
result.address string Bluetooth address
result.type string Adapter type (must be one of the following: Classic, LowEnergy, Dual)
result.version integer Version
result?.manufacturer integer (optional) Manufacturer company identifer
result?.class integer (optional) Class of device
result?.name string (optional) Name
result?.shortname string (optional) Short name

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown adapter device

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.adapter@0"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "id": 0,
    "interface": "hci0",
    "address": "81:6F:B0:91:9B:FE",
    "type": "Dual",
    "version": 8,
    "manufacturer": 15,
    "class": 1060,
    "name": "Thunder Bluetooth Controller",
    "shortname": "Thunder"
  }
}

devices property

Provides access to the list of known remote Bluetooth devices.

This property is read-only.

This API is deprecated and may be removed in the future. It is no longer recommended for use in new implementations.

Value

Result

Name Type Description
result array List of known remote Bluetooth devices
result[#] string Bluetooth address

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.devices"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    "81:6F:B0:91:9B:FE"
  ]
}

device property

Provides access to the remote Bluetooth device information.

This property is read-only.

This API is deprecated and may be removed in the future. It is no longer recommended for use in new implementations.

Value

The device address argument shall be passed as the index to the property, e.g. BluetoothControl.1.device@81:6F:B0:91:9B:FE.

Result

Name Type Description
result object Remote Bluetooth device information
result.address string Bluetooth address
result.type string Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
result?.name string (optional) Name of the device
result?.class integer (optional) Class of device
result?.appearance integer (optional) Appearance value
result?.services array (optional) List of supported services
result?.services[#] string (optional) Service UUID
result.connected boolean Indicates if the device is currently connected
result.paired boolean Indicates if the device is currently paired

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown device

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.device@81:6F:B0:91:9B:FE"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "Classic",
    "name": "Thunder Bluetooth Speaker",
    "class": 2360324,
    "appearance": 2113,
    "services": [
      "110a"
    ],
    "connected": true,
    "paired": true
  }
}

Notifications

Notifications are autonomous events triggered by the internals of the implementation and broadcasted via JSON-RPC to all registered observers. Refer to [Thunder] for information on how to register for a notification.

The following events are provided by the BluetoothControl plugin:

BluetoothControl interface events:

Event Description
discoverablestarted Notifies of entering the discoverable state
discoverablecomplete Notifies of leaving the discoverable state
scanstarted Notifies of scan start
scancomplete Notifies of scan completion
devicestatechange Notifies of device state changes
pincoderequest Notifies of a PIN code request
passkeyrequest Notifies of a passkey request
passkeyconfirmrequest Notifies of a passkey confirmation request

discoverablestarted event

Notifies of entering the discoverable state.

Description

Register to this event to be notified about entering the discoverable state

If applicable, this notification may be sent out during registration, reflecting the current status.

Parameters

Name Type Description
params object
params.type string Discoverable type (must be one of the following: Classic, LowEnergy)
params.mode string Discoverable mode (must be one of the following: General, Limited)
params?.connectable boolean (optional) Indicates connectable advertising (true, LowEnergy only) (default: False)

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.discoverablestarted",
  "params": {
    "type": "LowEnergy",
    "mode": "General",
    "connectable": false
  }
}

discoverablecomplete event

Notifies of leaving the discoverable state.

Description

Register to this event to be notified about leaving the discoverable state

Parameters

Name Type Description
params object
params.type string Discoverable type (must be one of the following: Classic, LowEnergy)

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.discoverablecomplete",
  "params": {
    "type": "LowEnergy"
  }
}

scanstarted event

Notifies of scan start.

Description

Register to this event to be notified about device scan start

If applicable, this notification may be sent out during registration, reflecting the current status.

Parameters

Name Type Description
params object
params.type string Scan type (must be one of the following: Classic, LowEnergy)
params?.mode string (optional) Scan mode (must be one of the following: General, Limited) (default: General)

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.scanstarted",
  "params": {
    "type": "LowEnergy",
    "mode": "General"
  }
}

scancomplete event

Notifies of scan completion.

Description

Register to this event to be notified about device scan completion

Parameters

Name Type Description
params object
params.type string Scan type (must be one of the following: Classic, LowEnergy)

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.scancomplete",
  "params": {
    "type": "LowEnergy"
  }
}

devicestatechange event

Notifies of device state changes.

Description

Register to this event to be notified about device state changes

If applicable, this notification may be sent out during registration, reflecting the current status.

Parameters

Name Type Description
params object
params.address string Bluetooth address
params.type string Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
params.state string Device state (must be one of the following: Pairing, Paired, Unpaired, Connected, Disconnected)
params?.disconnectreason string (optional) Disconnection reason in case of Disconnected event (must be one of the following: ConnectionTimeout, AuthenticationFailure, RemoteLowOnResources, RemotePoweredOff, TerminatedByRemote, TerminatedByHost)

The device type argument shall be passed within the designator, e.g. LowEnergy.client.events.1.

Example

{
  "jsonrpc": "2.0",
  "method": "LowEnergy.client.events.1.devicestatechange",
  "params": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "LowEnergy",
    "state": "Disconnected",
    "disconnectreason": "ConnectionTimeout"
  }
}

pincoderequest event

Notifies of a PIN code request.

Description

Register to this event to be notified about PIN code requests during a legacy pairing process. Upon receiving this event the client is required to respond with a providepincode call in order to complete the pairing procedure. The PIN code value would typically be collected by prompting the end-user. If the client fails to respond before the pairing timeout elapses the pairing procedure will be aborted.

Note that this event will never be send for a Bluetooth LowEnergy device

Parameters

Name Type Description
params object
params.address string Bluetooth address
params.type string Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom)

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.pincoderequest",
  "params": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "Classic"
  }
}

passkeyrequest event

Notifies of a passkey request.

Description

Register to this event to be notified about passkey requests that may be required during a pairing process. Upon receiving this event the client is required to respond with a providepasskey call in order to complete the pairing procedure. The passkey value would typically be collected by prompting the end-user. If the client fails to respond before the pairing timeout elapses the pairing procedure will be aborted

Parameters

Name Type Description
params object
params.address string Bluetooth address
params.type string Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom)

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.passkeyrequest",
  "params": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "Classic"
  }
}

passkeyconfirmrequest event

Notifies of a passkey confirmation request.

Description

Register to this event to be notified about passkey confirmation requests that may required during a pairing process. Upon receiving this event the client is required to respond with a passkeyconfirm call in order to complete the pairing procedure. The passkey confirmation would typically be collected by prompting the end-user. If the client fails to respond before the pairing timeout elapses the pairing procedure will be aborted

Parameters

Name Type Description
params object
params.address string Bluetooth address
params.type string Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
params.secret integer A six-digit decimal number passkey sent by the remote device for confirmation; may be 0 for a simple accept/forbid paring request

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.passkeyconfirmrequest",
  "params": {
    "address": "81:6F:B0:91:9B:FE",
    "type": "Classic",
    "secret": 123456
  }
}