Skip to content

Latest commit

 

History

History
937 lines (712 loc) · 24.3 KB

BluetoothControlPlugin.md

File metadata and controls

937 lines (712 loc) · 24.3 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 of its configuration, methods and properties provided, as well as notifications sent.

Case Sensitivity

All identifiers on the interface 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: libWPEFrameworkBluetoothControl.so
autostart boolean Determines if the plugin is to be started automatically along with the framework

Methods

The following methods are provided by the BluetoothControl plugin:

BluetoothControl interface methods:

Method Description
scan Starts scanning for Bluetooth devices
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 the pairing process
pincode Specifies a PIN code for authentication during a legacy pairing process
passkey Specifies a passkey for authentication during a pairing process
confirmpasskey Confirms a passkey for authentication during a pairing process

scan method

Starts scanning for Bluetooth devices.

Also see: scancomplete

Parameters

Name Type Description
params object
params.type string Bluetooth device type (must be one of the following: Classic, LowEnergy)
params?.timeout number (optional) Duration of the scan (in seconds); default: 10 seconds

Result

Name Type Description
result null Always null

Errors

Code Message Description
1 ERROR_GENERAL Failed to scan
3 ERROR_ASYNC_FAILED Controller operation failed
12 ERROR_INPROGRESS Scan already in progress

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "BluetoothControl.1.scan",
    "params": {
        "type": "LowEnergy",
        "timeout": 60
    }
}

Response

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

connect method

Connects to a Bluetooth device.

Also see: devicestatechange

Parameters

Name Type Description
params object
params.address string Bluetooth address

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown device
9 ERROR_ALREADY_CONNECTED Device already connected
5 ERROR_ILLEGAL_STATE Device not paired
11 ERROR_TIMEDOUT Connect request timed out
3 ERROR_ASYNC_FAILED Controller operation failed
12 ERROR_INPROGRESS Device is currently busy
1 ERROR_GENERAL Failed to connect the device

Example

Request

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

Response

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

disconnect method

Disconnects from a connected Bluetooth device.

Also see: devicestatechange

Parameters

Name Type Description
params object
params.address string Bluetooth address

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
12 ERROR_INPROGRESS Device is currently busy
11 ERROR_TIMEDOUT Disconnect request timed out
3 ERROR_ASYNC_FAILED Controller operation failed

Example

Request

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

Response

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

pair method

Pairs a Bluetooth device.

Description

The client may expect PIN or passkey requests 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?.timeout integer (optional) Maximum time allowed for the pairing process to complete (in seconds); default: 20 seconds

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
3 ERROR_ASYNC_FAILED Controller operation failed
12 ERROR_INPROGRESS Device is currently busy
11 ERROR_TIMEDOUT Pairing timeout elapsed
1 ERROR_GENERAL Failed to pair the device

Example

Request

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

Response

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

unpair method

Unpairs a paired Bluetooth device.

Also see: devicestatechange

Parameters

Name Type Description
params object
params.address string Bluetooth address

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
12 ERROR_INPROGRESS Device is currently busy
11 ERROR_TIMEDOUT Unpair request timed out
3 ERROR_ASYNC_FAILED Controller operation failed

Example

Request

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

Response

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

abortpairing method

Aborts the pairing process.

Parameters

Name Type Description
params object
params.address string Bluetooth address

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
11 ERROR_TIMEDOUT Unpair request timed out
3 ERROR_ASYNC_FAILED Controller operation failed

Example

Request

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

Response

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

pincode method

Specifies a PIN code for authentication during a legacy pairing process.

Description

This method is to 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: pincoderequest

Parameters

Name Type Description
params object
params.address string Bluetooth address
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
3 ERROR_ASYNC_FAILED Controller operation failed

Example

Request

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

Response

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

passkey method

Specifies a passkey for authentication during a pairing process.

Description

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

Also see: passkeyrequest

Parameters

Name Type Description
params object
params.address string Bluetooth address
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
3 ERROR_ASYNC_FAILED Controller operation failed

Example

Request

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

Response

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

confirmpasskey method

Confirms a passkey for authentication during a pairing process.

Description

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

Also see: passkeyconfirmrequest

Parameters

Name Type Description
params object
params.address string Bluetooth address
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
3 ERROR_ASYNC_FAILED Controller operation failed

Example

Request

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

Response

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

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
devices RO List of known remote Bluetooth devices
device RO Remote Bluetooth device information

adapters property

Provides access to the list of local Bluetooth adapters.

This property is read-only.

Value

Name Type Description
(property) array List of local Bluetooth adapters
(property)[#] number Adapter ID

Example

Get Request

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

Get Response

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

adapter property

Provides access to the local Bluetooth adapter information.

This property is read-only.

Value

Name Type Description
(property) object Local Bluetooth adapter information
(property).interface string Ndapter interface name
(property).address string Bluetooth address
(property).version number Device version
(property)?.manufacturer number (optional) Device manufacturer Company Identifer
(property)?.name string (optional) Device name
(property)?.shortname string (optional) Device short name

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

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown device

Example

Get Request

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

Get Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": {
        "interface": "hci0",
        "address": "81:6F:B0:91:9B:FE",
        "version": 8,
        "manufacturer": 0,
        "name": "Thunder",
        "shortname": "Thunder"
    }
}

devices property

Provides access to the list of known remote Bluetooth devices.

This property is read-only.

Value

Name Type Description
(property) array List of known remote Bluetooth devices
(property)[#] string Bluetooth address

Example

Get Request

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

Get Response

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

device property

Provides access to the remote Bluetooth device information.

This property is read-only.

Value

Name Type Description
(property) object Remote Bluetooth device information
(property).name string Name of the device
(property).type string Bluetooth device type (must be one of the following: Classic, LowEnergy)
(property)?.class integer (optional) Class of device (3 octets)
(property).connected boolean Denotes if the device is currently connected to host
(property).paired boolean Denotes if the device is currently paired with host

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

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown device

Example

Get Request

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

Get Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": {
        "name": "Acme Bluetooth Device",
        "type": "LowEnergy",
        "class": 2360324,
        "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
scancomplete Notifies about scan completion
devicestatechange Notifies about device state change
pincoderequest Notifies about a PIN code request
passkeyrequest Notifies about a passkey request
passkeyconfirmrequest Notifies about a passkey confirmation request

scancomplete event

Notifies about scan completion.

Description

Register to this event to be notified about device scan completion

Parameters

This event carries no parameters.

Example

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

devicestatechange event

Notifies about device state change.

Description

Register to this event to be notified about device state changes

Parameters

Name Type Description
params object
params.address string Bluetooth address
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)

Example

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

pincoderequest event

Notifies about 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 pincode 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

Example

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

passkeyrequest event

Notifies about 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 passkey 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

Example

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

passkeyconfirmrequest event

Notifies about 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.secret integer A six-digit decimal number passkey sent by the remote device for confirmation

Example

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