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
UUID	Universally Unique Identifier
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:

IBluetoothRemoteControl (IBluetoothRemoteControl.h) (version 1.0.0) (compliant format)
IAudioStream (IAudioStream.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:

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

AudioStream interface properties:

Property	R/W	Description
name	read-only	Name of the stream
state	read-only	Current state of the stream
capabilities	read-only	List of codecs supported by the stream
audioprofile	read/write	Preferred profile of the stream
time	read-only	Stream position
speed	read/write	Stream speed

device ^property

Provides access to the bluetooth address.

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.

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.

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"
}

name ^property

Provides access to the name of the stream.

Value

Result

Name	Type	M/O	Description
result	string	mandatory	Name of the stream

Errors

Message	Description
`ERROR_ILLEGAL_STATE`	The stream is not ready for this operation

Example

Get Request

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

Get Response

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

state ^property

Provides access to the current state of the stream.

Value

Result

Name	Type	M/O	Description
result	string	mandatory	Current state of the stream (must be one of the following: Idle, Started, Unavailable)

Example

Get Request

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

Get Response

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

capabilities ^property

Provides access to the list of codecs supported by the stream.

Value

Result

Name	Type	M/O	Description
result	array	mandatory	List of codecs supported by the stream
result[#]	string	mandatory	... (must be one of the following: IMA-ADPCM, PCM)

Errors

Message	Description
`ERROR_ILLEGAL_STATE`	The stream is not ready for this operation

Example

Get Request

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

Get Response

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

audioprofile ^property

Provides access to the preferred profile of the stream.

Value

Name	Type	M/O	Description
(property)	object	mandatory	Preferred profile of the stream
(property).value	object	mandatory	...
(property).value.codec	string	mandatory	Compression method (PCM: uncompressed) (must be one of the following: IMA-ADPCM, PCM)
(property).value?.codecparams	opaque object	optional	Additional parameters for codec
(property).value.channels	integer	mandatory	Number of audio channels
(property).value.resolution	integer	mandatory	Sample resultion in bits
(property).value.samplerate	integer	mandatory	Sample rate in hertz
(property).value?.bitrate	integer	optional	Data rate of the compressed stream in bits per second

Result

Name	Type	M/O	Description
result	object	mandatory	Preferred profile of the stream
result.codec	string	mandatory	Compression method (PCM: uncompressed) (must be one of the following: IMA-ADPCM, PCM)
result?.codecparams	opaque object	optional	Additional parameters for codec
result.channels	integer	mandatory	Number of audio channels
result.resolution	integer	mandatory	Sample resultion in bits
result.samplerate	integer	mandatory	Sample rate in hertz
result?.bitrate	integer	optional	Data rate of the compressed stream in bits per second

Errors

Message	Description
`ERROR_NOT_SUPPORTED`	Profile change is not supported by this stream
`ERROR_ILLEGAL_STATE`	The stream is not ready for this operation
`ERROR_BAD_REQUEST`	The profile specified is invalid
`ERROR_INPROGRESS`	Stream is started, profile will be changed for the next streaming

Example

Get Request

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

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "codec": "PCM",
    "codecparams": {},
    "channels": 1,
    "resolution": 16,
    "samplerate": 16000,
    "bitrate": 64000
  }
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothRemoteControl.1.audioprofile",
  "params": {
    "value": {
      "codec": "PCM",
      "codecparams": {},
      "channels": 1,
      "resolution": 16,
      "samplerate": 16000,
      "bitrate": 64000
    }
  }
}

Set Response

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

time ^property

Provides access to the stream position.

Value

Result

Name	Type	M/O	Description
result	integer	mandatory	Stream position

Errors

Message	Description
`ERROR_NOT_SUPPORTED`	Time reporting is not supported by this stream
`ERROR_ILLEGAL_STATE`	The stream is not ready for this operation

Example

Get Request

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

Get Response

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

speed ^property

Provides access to the stream speed.

Value

Name	Type	M/O	Description
(property)	object	mandatory	Stream speed
(property).value	integer	mandatory	...

Result

Name	Type	M/O	Description
result	integer	mandatory	Stream speed

Errors

Message	Description
`ERROR_NOT_SUPPORTED`	Speed setting is not supported by this stream
`ERROR_ILLEGAL_STATE`	The stream is not ready for this operation

Example

Get Request

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

Get Response

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

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothRemoteControl.1.speed",
  "params": {
    "value": 0
  }
}

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

BluetoothRemoteControl interface events:

Notification	Description
batterylevelchange	Signals battery level change

AudioStream interface events:

Notification	Description
audioframe	Provides audio data
audiotransmission	Signals state of the stream

batterylevelchange ^notification

Signals battery level change.

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
  }
}

audioframe ^notification

Provides audio data.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params?.seq	integer	optional	Frame number in current transmission
params?.timestamp	integer	optional	Timestamp of the frame
params.length	integer	mandatory	Size of the raw data frame in bytes
params.data	string (base64)	mandatory	Raw audio data, the format of the data is specified in the most recent audiotransmission notification

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,
    "timestamp": 0,
    "length": 400,
    "data": "..."
  }
}

audiotransmission ^notification

Signals state of the stream.

Parameters

Name	Type	M/O	Description
params	object	mandatory	...
params.state	string	mandatory	New state of the stream (must be one of the following: Idle, Started, Unavailable)
params?.profile	object	optional	Details on the format used in the stream
params?.profile.codec	string	mandatory	Compression method (PCM: uncompressed) (must be one of the following: IMA-ADPCM, PCM)
params?.profile?.codecparams	opaque object	optional	Additional parameters for codec
params?.profile.channels	integer	mandatory	Number of audio channels
params?.profile.resolution	integer	mandatory	Sample resultion in bits
params?.profile.samplerate	integer	mandatory	Sample rate in hertz
params?.profile?.bitrate	integer	optional	Data rate of the compressed stream in bits per second

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": "Unavailable",
    "profile": {
      "codec": "PCM",
      "codecparams": {},
      "channels": 1,
      "resolution": 16,
      "samplerate": 16000,
      "bitrate": 64000
    }
  }
}

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

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

name property

Value

Result

Errors

Example

Get Request

Get Response

state property

Value

Result

Example

Get Request

Get Response

capabilities property

Value

Result

Errors

Example

assign ^method

revoke ^method

device ^property

metadata ^property

batterylevel ^property

voicecontrol ^property

name ^property

state ^property

capabilities ^property

audioprofile ^property

time ^property

speed ^property

batterylevelchange ^notification

audioframe ^notification

audiotransmission ^notification