Bluetooth Control Plugin

Version: 1.0

Status:

BluetoothControl plugin for Thunder framework.

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	M/O	Description
callsign	string	mandatory	Plugin instance name (default: BluetoothControl)
classname	string	mandatory	Class name: BluetoothControl
locator	string	mandatory	Library name: libThunderBluetoothControl.so
startmode	string	mandatory	Determines in which state the plugin should be moved to at startup of the framework
configuration	object	optional	...
configuration?.interface	integer	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	integer	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	mandatory	(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:

IBluetoothControl (IBluetooth.h) (version 1.0.0) (compliant format)

This interface uses legacy lowercase naming convention. With the next major release the naming convention will change to camelCase.

Methods

The following methods are provided by the BluetoothControl plugin:

BluetoothControl interface methods:

Method	Description
setdiscoverable	Starts LE advertising or BR/EDR inquiry scanning, making the local interface visible for nearby Bluetooth devices
stopdiscoverable	Stops LE advertising or BR/EDR inquiry scanning operation
scan	Starts LE active discovery or BR/EDR inquiry of nearby Bluetooth devices
stopscanning	Stops LE discovery or BR/EDR 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
confirmpasskey	Confirms a passkey for authentication during a BR/EDR SSP pairing processs
providepasskey	Provides a passkey for authentication during a pairing process
forget	Forgets a previously seen Bluetooth device
getdevicelist	Retrieves a list of known remote Bluetooth devices
getdeviceinfo	Retrieves detailed information about a known Bluetooth device

setdiscoverable ^method

Starts LE advertising or BR/EDR inquiry scanning, making the local interface visible for nearby Bluetooth devices.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy)
params?.mode	string	optional	Advertising or inquiry scanning mode (must be one of the following: General, Limited) (default: General)
params?.connectable	boolean	optional	Specifies if LE advertising should report the device is connectable (LE-only) (default: True)
params?.duration	integer	optional	Time span of the discoverable state in seconds (default: 30)

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Errors

Message	Description
`ERROR_UNAVAILABLE`	The adapter does not support selected discovery type
`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": "Limited",
    "connectable": true,
    "duration": 30
  }
}

Response

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

stopdiscoverable ^method

Stops LE advertising or BR/EDR inquiry scanning operation.

Parameters

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

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Errors

Message	Description
`ERROR_UNAVAILABLE`	The adapter does not support selected discovery type
`ERROR_ILLEGAL_STATE`	The 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 LE active discovery or BR/EDR inquiry of nearby Bluetooth devices.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy)
params?.mode	string	optional	Discovery or inquiry mode (scan picks up only devices discoverable in paricular mode) (must be one of the following: General, Limited) (default: General)
params?.duration	integer	optional	Time span of the discovery in seconds (default: 12)

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Errors

Message	Description
`ERROR_UNAVAILABLE`	The adapter does not support selected scan type
`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": "Limited",
    "duration": 12
  }
}

Response

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

stopscanning ^method

Stops LE discovery or BR/EDR inquiry operation.

Parameters

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

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Errors

Message	Description
`ERROR_UNAVAILABLE`	The adapter does not support selected scan type
`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. This call is asynchronous.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Errors

Message	Description
`ERROR_UNKNOWN_KEY`	The device is not known
`ERROR_INPROGRESS`	The host adapter is currently busy
`ERROR_ILLEGAL_STATE`	The device is not paired
`ERROR_ALREADY_CONNECTED`	The device is already connected
`ERROR_REQUEST_SUBMITTED`	The device has not been connected, but will be automatically connected when it becomes available

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.connect",
  "params": {
    "address": "...",
    "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 again becomes available.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Errors

Message	Description
`ERROR_UNKNOWN_KEY`	The device is not known
`ERROR_INPROGRESS`	The host adapter is currently busy
`ERROR_ALREADY_RELEASED`	The device is not connected
`ERROR_REQUEST_SUBMITTED`	The device is currently not connected, but it's automatic reconnection mode has been disabled

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.disconnect",
  "params": {
    "address": "...",
    "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 abortPairing. This call is asynchronous.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
params?.capabilities	string	optional	Host device pairing capabilities (must be one of the following: DisplayOnly, DisplayYesNo, KeyboardDisplay, KeyboardOnly, NoInputNoOutput) (default: NoInputNoOutput)
params?.timeout	integer	optional	Time allowed for the pairing process to complete (default: 10)

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Errors

Message	Description
`ERROR_UNKNOWN_KEY`	The device is not known
`ERROR_INPROGRESS`	The host adapter is currently busy
`ERROR_ALREADY_CONNECTED`	The device is already paired
`ERROR_GENERAL`	Failed to pair

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.pair",
  "params": {
    "address": "...",
    "type": "LowEnergy",
    "capabilities": "DisplayYesNo",
    "timeout": 10
  }
}

Response

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

unpair ^method

Unpairs a paired Bluetooth device.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Errors

Message	Description
`ERROR_UNKNOWN_KEY`	The device is not known
`ERROR_INPROGRESS`	The host adapter is currently busy
`ERROR_ALREADY_RELEASED`	The device is not paired

Example

Request

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

Response

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

abortpairing ^method

Aborts pairing operation.

Description

This call is asynchronous.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Errors

Message	Description
`ERROR_UNKNOWN_KEY`	The device is not known
`ERROR_ILLEGAL_STATE`	The device not currently pairing

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.abortpairing",
  "params": {
    "address": "...",
    "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.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
params.secret	string	mandatory	A PIN code, typically 4 ASCII digits String length must be at most 16 chars.

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Errors

Message	Description
`ERROR_UNKNOWN_KEY`	The device is not known
`ERROR_ILLEGAL_STATE`	The device not currently pairing or a PIN code has not been requested

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.providepincode",
  "params": {
    "address": "...",
    "type": "LowEnergy",
    "secret": "1234"
  }
}

Response

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

confirmpasskey ^method

Confirms a passkey for authentication during a BR/EDR SSP pairing processs.

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.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
params.accept	boolean	mandatory	Confirm pairing (normally if the presented passkey is correct)

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Errors

Message	Description
`ERROR_UNKNOWN_KEY`	Unknown device
`ERROR_ILLEGAL_STATE`	The 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": "...",
    "type": "LowEnergy",
    "accept": false
  }
}

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.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
params.secret	integer	mandatory	A decimal six-digit passkey value Value must be in range [0..999999].

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Errors

Message	Description
`ERROR_UNKNOWN_KEY`	Unknown device
`ERROR_ILLEGAL_STATE`	The device not currently pairing or a passkey has not been requested

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.providepasskey",
  "params": {
    "address": "...",
    "type": "LowEnergy",
    "secret": 123456
  }
}

Response

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

forget ^method

Forgets a previously seen Bluetooth device.

Description

The device will no longer be listed and its status tracked. If paired the device must be unpaired first.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Errors

Message	Description
`ERROR_UNKNOWN_KEY`	The device is not known
`ERROR_ILLEGAL_STATE`	The device is paired

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.forget",
  "params": {
    "address": "...",
    "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	M/O	Description
result	array	mandatory	...
result[#]	object	mandatory	...
result[#].address	string	mandatory	Bluetooth address
result[#].type	string	mandatory	Bluetooth device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
result[#].name	string	mandatory	Bluetooth short name

Example

Request

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

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    {
      "address": "...",
      "type": "LowEnergy",
      "name": "..."
    }
  ]
}

getdeviceinfo ^method

Retrieves detailed information about a known Bluetooth device.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)

Result

Name	Type	M/O	Description
result	object	mandatory	...
result.address	string	mandatory	...
result.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
result?.name	string	optional	Device local name
result?.version	integer	optional	Device version
result?.manufacturer	integer	optional	Company Identification Code (CIC)
result?.class	integer	optional	Class of Device (CoD) value Value must be in range [0..16777215].
result?.appearance	integer	optional	Appearance value (LE-only)
result?.services	array	optional	A list of supported service UUIDs
result?.services[#]	string	mandatory	...
result.paired	boolean	mandatory	Specifies if the device is currently paired
result.connected	boolean	mandatory	Specifies if the device is currently connected

Errors

Message	Description
`ERROR_UNKNOWN_KEY`	The device is not known

Example

Request

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

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "address": "...",
    "type": "LowEnergy",
    "name": "...",
    "version": 0,
    "manufacturer": 305,
    "class": 2360324,
    "appearance": 2113,
    "services": [
      "..."
    ],
    "paired": false,
    "connected": false
  }
}

Properties

The following properties are provided by the BluetoothControl plugin:

BluetoothControl interface properties:

Property	R/W	Description
adapters	read-only	List of local Bluetooth adapters
adapter	read-only	Local Bluetooth adapter information
devices ^deprecated	read-only	List of known remote Bluetooth LE devices
device ^deprecated	read-only	Remote Bluetooth LE device information

adapters ^property

Provides access to the list of local Bluetooth adapters.

This property is read-only.

Value

Name	Type	M/O	Description
(property)	array	mandatory	List of local Bluetooth adapters
(property)[#]	integer	mandatory	...

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.

The adapter parameter shall be passed as the index to the property, i.e. adapter@<adapter>.

Index

Name	Type	M/O	Description
adapter	integer	mandatory	Adapter index

Value

Name	Type	M/O	Description
(property)	object	mandatory	Local Bluetooth adapter information
(property).id	integer	mandatory	Adapter ID number
(property).interface	string	mandatory	Interface name
(property).address	string	mandatory	Bluetooth address
(property).type	string	mandatory	Adapter type (must be one of the following: Classic, Dual, LowEnergy)
(property).version	integer	mandatory	Version
(property)?.manufacturer	integer	optional	Company Identification Code (CIC)
(property)?.class	integer	optional	Class of Device (CoD) value Value must be in range [0..16777215].
(property)?.name	string	optional	Name
(property)?.shortname	string	optional	Shortened name

Errors

Message	Description
`ERROR_UNKNOWN_KEY`	The adapter ID is invalid

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": "...",
    "type": "LowEnergy",
    "version": 0,
    "manufacturer": 305,
    "class": 2360324,
    "name": "...",
    "shortname": "..."
  }
}

devices ^property

Provides access to the list of known remote Bluetooth LE devices.

This property is read-only.

devices is an alternative name for this property. This name is deprecated and may be removed in the future. It is not recommended for use in new implementations.

Value

Name	Type	M/O	Description
(property)	array	mandatory	List of known remote Bluetooth LE devices
(property)[#]	string	mandatory	...

Example

Get Request

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

Get Response

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

device ^property

Provides access to the remote Bluetooth LE device information.

This property is read-only.

device is an alternative name for this property. This name is deprecated and may be removed in the future. It is not recommended for use in new implementations.

The deviceaddress parameter shall be passed as the index to the property, i.e. device@<deviceaddress>.

Index

Name	Type	M/O	Description
deviceaddress	string	mandatory	...

Value

Name	Type	M/O	Description
(property)	object	mandatory	Remote Bluetooth LE device information
(property).address	string	mandatory	Bluetooth address
(property).type	string	mandatory	Device type (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
(property)?.name	string	optional	Device name
(property)?.class	integer	optional	Class of Device (CoD) value Value must be in range [0..16777215].
(property)?.appearance	integer	optional	Appearance value (LE only)
(property)?.services	opaque object	optional	Array of supported service UUIDs
(property).paired	boolean	mandatory	Specifies if the device is currently paired
(property).connected	boolean	mandatory	Specifies if the device is currently connected

Errors

Message	Description
`ERROR_UNKNOWN_KEY`	The device is not known

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.device@xyz"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "address": "...",
    "type": "LowEnergy",
    "name": "...",
    "class": 2360324,
    "appearance": 2113,
    "services": {},
    "paired": false,
    "connected": false
  }
}

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:

Notification	Description
pincoderequest	Notifies of a PIN code request during authenticated BR/EDR legacy pairing process
passkeyconfirmrequest	Notifies of a user confirmation request during authenticated BR/EDR SSP pairing process
passkeyrequest	Notifies of a passkey supply request during authenticated LE pairing process
passkeydisplayrequest	Notifies of a passkey presentation request during authenticated LE pairing process
discoverablestarted	Reports entering the discoverable state
discoverablecomplete	Reports leaving the discoverable state
scanstarted	Reports start of scanning
scancomplete	Reports end of scanning
devicestatechanged	disconnectReason If disconnected specifies the cause of disconnection

pincoderequest ^notification

Notifies of a PIN code request during authenticated BR/EDR legacy pairing process.

Description

Upon receiving this event the client is required to respond with "providePinCode" call in order to complete the pairing procedure. The PIN code value is typically collected by prompting the end-user on the local device. If the client fails to respond before the pairing timeout elapses the pairing procedure will be aborted.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.register",
  "params": {
    "event": "pincoderequest",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.pincoderequest",
  "params": {
    "address": "...",
    "type": "LowEnergy"
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.pincoderequest.

passkeyconfirmrequest ^notification

Notifies of a user confirmation request during authenticated BR/EDR SSP pairing process.

Description

Upon receiving this event the client is required to respond with "confirmPasskey" call in order to complete the pairing procedure. The passkey confirmation is typically collected by prompting the end-user on the local device. If the client fails to respond before the pairing timeout elapses the pairing procedure will be aborted.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
params?.secret	integer	optional	A six-digit decimal number sent by the remote device to be presented to the end-user for confirmation on the local device (e.g 123456). The passkey may be omitted for simple yes/no paring Value must be in range [0..999999].

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.register",
  "params": {
    "event": "passkeyconfirmrequest",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.passkeyconfirmrequest",
  "params": {
    "address": "...",
    "type": "LowEnergy",
    "secret": 0
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.passkeyconfirmrequest.

passkeyrequest ^notification

Notifies of a passkey supply request during authenticated LE pairing process.

Description

Upon receiving this event the client is required to respond with "providePasskey" call in order to complete the pairing procedure. The passkey value is typically collected by prompting the end-user on the local device. If the client fails to respond before the pairing timeout elapses the pairing procedure will be aborted.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.register",
  "params": {
    "event": "passkeyrequest",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.passkeyrequest",
  "params": {
    "address": "...",
    "type": "LowEnergy"
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.passkeyrequest.

passkeydisplayrequest ^notification

Notifies of a passkey presentation request during authenticated LE pairing process.

Description

Upon receiving this event the client is required to display the passkey on the local device. The end-user on the remote device will need to enter this passkey to complete the pairing procedure. If end-user fails to respond before the pairing timeout elapses the pairing procedure will be aborted.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
params.secret	integer	mandatory	A six-digit decimal number to be displayed on the local device (e.g 123456) Value must be in range [0..999999].

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.register",
  "params": {
    "event": "passkeydisplayrequest",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.passkeydisplayrequest",
  "params": {
    "address": "...",
    "type": "LowEnergy",
    "secret": 0
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.passkeydisplayrequest.

discoverablestarted ^notification

Reports entering the discoverable state.

This notification may also be triggered by client registration.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy)
params.mode	string	mandatory	Advertising or inquiry scanning mode (must be one of the following: General, Limited)
params?.connectable	boolean	optional	Specifies if LE advertising reports that the device is connectable (LE-only)

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.register",
  "params": {
    "event": "discoverablestarted",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.discoverablestarted",
  "params": {
    "type": "LowEnergy",
    "mode": "Limited",
    "connectable": false
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.discoverablestarted.

discoverablecomplete ^notification

Reports leaving the discoverable state.

Notification Parameters

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

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.register",
  "params": {
    "event": "discoverablecomplete",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.discoverablecomplete",
  "params": {
    "type": "LowEnergy"
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.discoverablecomplete.

scanstarted ^notification

Reports start of scanning.

This notification may also be triggered by client registration.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy)
params.mode	string	mandatory	Discovery or inquiry mode (must be one of the following: General, Limited)

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.register",
  "params": {
    "event": "scanstarted",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.scanstarted",
  "params": {
    "type": "LowEnergy",
    "mode": "Limited"
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.scanstarted.

scancomplete ^notification

Reports end of scanning.

Notification Parameters

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

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.register",
  "params": {
    "event": "scancomplete",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.scancomplete",
  "params": {
    "type": "LowEnergy"
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.scancomplete.

devicestatechanged ^notification

disconnectReason If disconnected specifies the cause of disconnection.

This notification may also be triggered by client registration.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	...
params.type	string	mandatory	... (must be one of the following: Classic, LowEnergy, LowEnergyRandom)
params.state	string	mandatory	... (must be one of the following: Connected, Disconnected, Paired, Pairing, Unpaired)
params?.disconnectreason	string	optional	... (must be one of the following: AuthenticationFailure, ConnectionTimeout, RemoteLowOnResources, RemotePoweredOff, TerminatedByHost, TerminatedByRemote)

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothControl.1.register",
  "params": {
    "event": "devicestatechanged",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.devicestatechanged",
  "params": {
    "address": "...",
    "type": "LowEnergy",
    "state": "Paired",
    "disconnectreason": "AuthenticationFailure"
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.devicestatechanged.

Bluetooth Control Plugin

Table of Contents

Introduction

Scope

Case Sensitivity

Acronyms, Abbreviations and Terms

References

Description

Configuration

Interfaces

Methods

setdiscoverable method

Parameters

Result

Errors

Example

Request

Response

stopdiscoverable method

Parameters

Result

Errors

Example

Request

Response

scan method

Parameters

Result

Errors

Example

Request

Response

stopscanning method

Parameters

Result

Errors

Example

Request

Response

connect method

Description

Parameters

Result

Errors

Example

Request

Response

disconnect method

Description

Parameters

Result

Errors

Example

Request

Response

pair method

Description

Parameters

Result

Errors

Example

Request

Response

unpair method

Parameters

Result

Errors

Example

Request

Response

abortpairing method

Description

Parameters

Result

Errors

Example

Request

Response

providepincode method

Description

setdiscoverable ^method

stopdiscoverable ^method

scan ^method

stopscanning ^method

connect ^method

disconnect ^method

pair ^method

unpair ^method

abortpairing ^method

providepincode ^method

confirmpasskey ^method

providepasskey ^method

forget ^method

getdevicelist ^method

getdeviceinfo ^method

adapters ^property

adapter ^property

devices ^property

device ^property

pincoderequest ^notification