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)

This interface uses legacy lowercase naming convention. With the next major release the naming convention will change to camelCase.
IAudioStream (IAudioStream.h) (version 1.0.0) (compliant format)

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

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

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

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

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

This property is read-only.

Value

Name	Type	M/O	Description
(property)	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.

This property is read-only.

Value

Name	Type	M/O	Description
(property)	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": "Idle"
}

capabilities ^property

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

This property is read-only.

Value

Name	Type	M/O	Description
(property)	array	mandatory	List of codecs supported by the stream
(property)[#]	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": [
    "IMA-ADPCM"
  ]
}

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

Name	Type	M/O	Description
(property)	object	mandatory	Preferred profile of the stream
(property).codec	string	mandatory	Compression method (PCM: uncompressed) (must be one of the following: IMA-ADPCM, PCM)
(property)?.codecparams	opaque object	optional	Additional parameters for codec
(property).channels	integer	mandatory	Number of audio channels
(property).resolution	integer	mandatory	Sample resultion in bits
(property).samplerate	integer	mandatory	Sample rate in hertz
(property)?.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": "IMA-ADPCM",
    "codecparams": {},
    "channels": 1,
    "resolution": 16,
    "samplerate": 16000,
    "bitrate": 64000
  }
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothRemoteControl.1.audioprofile",
  "params": {
    "value": {
      "codec": "IMA-ADPCM",
      "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.

This property is read-only.

Value

Name	Type	M/O	Description
(property)	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	...

Name	Type	M/O	Description
(property)	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.

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

audioframe ^notification

Provides audio data.

Notification 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": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.audioframe",
  "params": {
    "seq": 1,
    "timestamp": 0,
    "length": 400,
    "data": "..."
  }
}

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

audiotransmission ^notification

Signals state of the stream.

This notification may also be triggered by client registration.

Notification 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": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.audiotransmission",
  "params": {
    "state": "Idle",
    "profile": {
      "codec": "IMA-ADPCM",
      "codecparams": {},
      "channels": 1,
      "resolution": 16,
      "samplerate": 16000,
      "bitrate": 64000
    }
  }
}

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

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

Errors

Example

Get Request

Get Response

metadata property

Value

Errors

Example

Get Request

Get Response

batterylevel property

Value

Errors

Example

Get Request

Get Response

voicecontrol property

Value

Errors

Example

Get Request

Get Response

Set Request

Set Response

name property

Value

Errors

Example

Get Request

Get Response

state property

Value

Example

Get Request

Get Response

capabilities property

Value

Errors

Example

Get Request

Get Response

audioprofile property

Value

Errors

Example

Get Request

Get Response

Set Request

Set Response

time property

Value

Errors

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