Bluetooth Remote Control Plugin

Version: 1.0

Status: ⚫⚪⚪

BluetoothRemoteControl plugin for Thunder framework.

Introduction

Scope

This document describes purpose and functionality of the BluetoothRemoteControl 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
ADPCM	Adaptive Pulse-code Modulation
API	Application Programming Interface
BLE	Bluetooth Low Energy
GATT	Generic Attribute Profile
HTTP	Hypertext Transfer Protocol
JSON	JavaScript Object Notation; a data interchange format
JSON-RPC	A remote procedure call protocol encoded in JSON
PCM	Pulse-code Modulation
WAV	Waveform Audio File Format

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 Remote Control plugin allows configuring and enabling Bluetooth LE remote control units.

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: BluetoothRemoteControl)
classname	string	mandatory	Class name: BluetoothRemoteControl
locator	string	mandatory	Library name: libThunderBluetoothRemoteControl.so
startmode	string	mandatory	Determines in which state the plugin should be moved to at startup of the framework
configuration	object	optional	...
configuration?.controller	string	optional	Name of the Bluetooth controller service (default: BluetoothControl)
configuration?.keymap	string	optional	Keymap name
configuration?.keyingest	boolean	optional	Enable key ingestion
configuration?.serviceuuid	string	optional	UUID of the voice control GATT service
configuration?.commanduuid	string	optional	UUID of the voice control command GATT characteristic
configuration?.datauuid	string	optional	UUID of the voice control data GATT characteristic
configuration?.recorder	string	optional	Enable voice data recording (debug purposes) to WAV file (must be one of the following: off, sequenced, sequenced_persist, single, single_persist)
configuration?.audiobuffersize	integer	optional	Size of the audio buffer in miliseconds (if not set then determined automatically)
configuration?.firstaudiochunksize	integer	optional	Size of the first audio transmission notification in miliseconds
configuration?.audiochunksize	integer	optional	Size of the audio transmission notifications in miliseconds (if not set then audio data is not buffered)
configuration?.audioprofile	object	optional	...
configuration?.audioprofile?.samplerate	integer	optional	Audio data sample rate in Hz (e.g. 16000)
configuration?.audioprofile?.channels	integer	optional	Number of audio channels (e.g. 1 for mono stream)
configuration?.audioprofile?.resolution	integer	optional	Audio samples resolution in bits (e.g. 16)

Interfaces

This plugin implements the following interfaces:

IBluetoothRemoteControlLegacy (IBluetoothRemoteControl.h) (version 1.0.0) (compliant format)
IBluetoothRemoteControl (IBluetoothRemoteControl.h) (version 1.0.0) (compliant format)

Methods

The following methods are provided by the BluetoothRemoteControl plugin:

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": "BluetoothRemoteControl.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": "BluetoothRemoteControl.1.revoke"
}

Response

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

Properties

The following properties are provided by the BluetoothRemoteControl plugin:

BluetoothRemoteControlLegacy interface properties:

Property	R/W	Description
name ^deprecated	read-only	Name of the RCU device

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
audioprofile	read-only	Details of used audio format

name ^property

Provides access to the name of the RCU device.

This property is read-only.

name 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

Result

Name	Type	M/O	Description
result	string	mandatory	Name of the RCU device

Errors

Message	Description
`ERROR_ILLEGAL_STATE`	The RCU device is not assigned

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothRemoteControl.1.name"
}

Get Response

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

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

Result

Name	Type	M/O	Description
result	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": "BluetoothRemoteControl.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

Result

Name	Type	M/O	Description
result	object	mandatory	Device metadata
result.name	string	mandatory	Name of the unit
result?.model	string	optional	Model name
result?.serial	string	optional	Serial number
result?.firmware	string	optional	Firmware version
result?.software	string	optional	Software version
result?.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": "BluetoothRemoteControl.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

Result

Name	Type	M/O	Description
result	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": "BluetoothRemoteControl.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	...

Result

Name	Type	M/O	Description
result	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": "BluetoothRemoteControl.1.voicecontrol"
}

Get Response

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

Set Request

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

Set Response

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

audioprofile ^property

Provides access to the details of used audio format.

This property is read-only.

Value

Result

Name	Type	M/O	Description
result	object	mandatory	Details of used audio format
result.codec	string	mandatory	Compression method (pcm: uncompressed) (must be one of the following: ima-adpcm, pcm)
result.channels	integer	mandatory	Number of audio channels
result.resolution	integer	mandatory	Sample resultion in bits
result.samplerate	integer	mandatory	Sample rate in hertz

Errors

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

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothRemoteControl.1.audioprofile"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "codec": "pcm",
    "channels": 1,
    "resolution": 16,
    "samplerate": 16000
  }
}

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

BluetoothRemoteControl interface events:

Notification	Description
audiotransmission	Signals beginning end of audio transmission
audioframe	Provides audio frame data
batterylevelchange	Signals battery level change

audiotransmission ^notification

Signals beginning end of audio transmission.

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

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.state	string	mandatory	New state of the voice transmission (must be one of the following: Started, Stopped)

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothRemoteControl.1.register",
  "params": {
    "event": "audiotransmission",
    "id": "client"
  }
}

Message

{
  "jsonrpc": "2.0",
  "method": "client.audiotransmission",
  "params": {
    "state": "Stopped"
  }
}

audioframe ^notification

Provides audio frame data.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.seq	integer	mandatory	Frame number in current transmission
params.size	integer	mandatory	Size of the raw data frame in bytes
params.data	string (base64)	mandatory	Raw audio data

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothRemoteControl.1.register",
  "params": {
    "event": "audioframe",
    "id": "client"
  }
}

Message

{
  "jsonrpc": "2.0",
  "method": "client.audioframe",
  "params": {
    "seq": 1,
    "size": 400,
    "data": "..."
  }
}

batterylevelchange ^notification

Signals battery level change.

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

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": "BluetoothRemoteControl.1.register",
  "params": {
    "event": "batterylevelchange",
    "id": "client"
  }
}

Message

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

Files

BluetoothRemoteControlPlugin.md

Latest commit

History

BluetoothRemoteControlPlugin.md

File metadata and controls

Bluetooth Remote Control Plugin

Table of Contents

Introduction

Scope

Case Sensitivity

Acronyms, Abbreviations and Terms

References

Description

Configuration

Interfaces

Methods

assign method

Parameters

Result

Errors

Example

Request

Response

revoke method

Parameters

Result

Errors

Example

Request

Response

Properties

name property

Value

Result

Errors

Example

Get Request

Get Response

device property

Value

Result

Errors

Example

Get Request

Get Response

metadata property

Value

Result

Errors

Example

Get Request

Get Response

batterylevel property

Value

Result

Errors

Example

Get Request

Get Response

voicecontrol property

Value

Result

Errors

Example

Get Request

Get Response

Set Request

Set Response

audioprofile property

Value

Result

Errors

Example

Get Request

Get Response

Notifications

audiotransmission notification

Parameters

Example

assign ^method

revoke ^method

name ^property

device ^property

metadata ^property

batterylevel ^property

voicecontrol ^property

audioprofile ^property

audiotransmission ^notification

audioframe ^notification

batterylevelchange ^notification