BluetoothControl API

Version: 1.0.0

Status:

BluetoothControl interface for Thunder framework.

(Defined with IBluetoothControl in IBluetooth.h)

Table of Contents

• Introduction
• Description
• Methods
• Properties
• Notifications

Introduction

Scope

This document describes purpose and functionality of the BluetoothControl interface (version 1.0.0). It includes detailed specification about its 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

BluetoothControl JSON-RPC interface.

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 interface:

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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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 interface:

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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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 interface:

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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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": "<callsign>.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.