BluetoothRemoteControl API

Version: 1.0.0

Status:

BluetoothRemoteControl interface for Thunder framework.

(Defined with IBluetoothRemoteControl in IBluetoothRemoteControl.h)

Table of Contents

• Introduction
• Description
• Methods
• Properties
• Notifications

Introduction

Scope

This document describes purpose and functionality of the BluetoothRemoteControl 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

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

BluetoothRemoteControl interface methods:

Method	Description
assign	Assigns a Bluetooth device as a RCU
revoke	Revokes a Bluetooth device from RCU operation

assign ^method

Assigns a Bluetooth device as a RCU.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.address	string	mandatory	Address of the Bluetooth device to assign

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Errors

Message	Description
ERROR_UNKNOWN_KEY	Device address value is invalid
ERROR_ALREADY_CONNECTED	A RCU device is already assigned

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.assign",
  "params": {
    "address": "..."
  }
}

Response

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

revoke ^method

Revokes a Bluetooth device from RCU operation.

Parameters

This method takes no parameters.

Result

Name	Type	M/O	Description
result	null	mandatory	Always null

Errors

Message	Description
ERROR_ALREADY_RELEASED	No device is currently assigned as RCU

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.revoke"
}

Response

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

Properties

The following properties are provided by the BluetoothRemoteControl interface:

BluetoothRemoteControl interface properties:

Property	R/W	Description
device / address	read-only	Bluetooth address
metadata / info	read-only	Device metadata
batterylevel	read-only	Battery level
voicecontrol	read/write	Toggle voice control

device ^property

Provides access to the bluetooth address.

This property is read-only.

address 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)	string	mandatory	Bluetooth address

Errors

Message	Description
ERROR_ILLEGAL_STATE	The RCU device currently is not assigned

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.device"
}

Get Response

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

metadata ^property

Provides access to the device metadata.

This property is read-only.

info 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)	object	mandatory	Device metadata
(property).name	string	mandatory	Name of the unit
(property)?.model	string	optional	Model name
(property)?.serial	string	optional	Serial number
(property)?.firmware	string	optional	Firmware version
(property)?.software	string	optional	Software version
(property)?.manufacturer	string	optional	Vendor/manufacturer name

Errors

Message	Description
ERROR_ILLEGAL_STATE	The RCU device currently is not assigned

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.metadata"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "name": "...",
    "model": "...",
    "serial": "...",
    "firmware": "...",
    "software": "...",
    "manufacturer": "..."
  }
}

batterylevel ^property

Provides access to the battery level.

This property is read-only.

Value

Name	Type	M/O	Description
(property)	integer	mandatory	Battery level

Errors

Message	Description
ERROR_UNAVAILABLE	The device is not connected or does not support battery information
ERROR_ILLEGAL_STATE	The RCU device currently is not assigned

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.batterylevel"
}

Get Response

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

voicecontrol ^property

Provides access to the toggle voice control.

Value

Name	Type	M/O	Description
(property)	object	mandatory	Toggle voice control
(property).value	boolean	mandatory	...

Name	Type	M/O	Description
(property)	boolean	mandatory	Toggle voice control

Errors

Message	Description
ERROR_NOT_SUPPORTED	The device does not support voice input
ERROR_ILLEGAL_STATE	The RCU device currently is not assigned

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.voicecontrol"
}

Get Response

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

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.voicecontrol",
  "params": {
    "value": false
  }
}

Set Response

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

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

BluetoothRemoteControl interface events:

Notification	Description
batterylevelchange	Signals battery level change

batterylevelchange ^notification

Signals battery level change.

This notification may also be triggered by client registration.

Notification Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.level	integer	mandatory	Battery level in percent

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.register",
  "params": {
    "event": "batterylevelchange",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.batterylevelchange",
  "params": {
    "level": 75
  }
}

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