Skip to content

Latest commit

 

History

History
619 lines (447 loc) · 14.6 KB

BluetoothRemoteControlPlugin.md

File metadata and controls

619 lines (447 loc) · 14.6 KB
Raw

Bluetooth Remote Control Plugin

Version: 1.0

Status: ⚫⚪⚪

BluetoothRemoteControl plugin for Thunder framework.

Table of Contents

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
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 Remote Control plugin allows configuring and enabling Bluetooth 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 Description
callsign string Plugin instance name (default: BluetoothRemoteControl)
classname string Class name: BluetoothRemoteControl
locator string Library name: libThunderBluetoothRemoteControl.so
startmode string Determines if the plugin shall be started automatically along with the framework
configuration object (optional)
configuration?.controller string (optional) Controller
configuration?.keymap string (optional) Keymap
configuration?.keyingest boolean (optional) Enable keyingest
configuration?.recorder enum (optional) Recorder

Interfaces

This plugin implements the following interfaces:

Methods

The following methods are provided by the BluetoothRemoteControl plugin:

BluetoothRemoteControl interface methods:

Method Description
assign Assigns a bluetooth device as a remote control unit
revoke Revokes the current remote control assignment

assign method

Assigns a bluetooth device as a remote control unit.

Parameters

Name Type Description
params object
params.address string Bluetooth address

Result

Name Type Description
result null Always null

Errors

Code Message Description
2 ERROR_UNAVAILABLE Bluetooth unavailable
22 ERROR_UNKNOWN_KEY Device unknown
1 ERROR_GENERAL Failed to assign the device

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothRemoteControl.1.assign",
  "params": {
    "address": "81:6F:B0:91:9B:FE"
  }
}

Response

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

revoke method

Revokes the current remote control assignment.

Parameters

This method takes no parameters.

Result

Name Type Description
result null Always null

Errors

Code Message Description
5 ERROR_ILLEGAL_STATE Remote not assigned

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 Description
name RO Unit name
address RO Bluetooth address of the unit
info RO Unit auxiliary information
batterylevel RO Battery level
voice Enable or Disable the flow of Voice data fragments from the remote
audioprofile RO Audio profile details

name property

Provides access to the unit name.

This property is read-only.

Value

Result

Name Type Description
result string Name of the remote control unit

Errors

Code Message Description
5 ERROR_ILLEGAL_STATE No remote has been assigned

Example

Get Request

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

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "Acme Bluetooth RCU"
}

address property

Provides access to the bluetooth address of the unit.

This property is read-only.

Value

Result

Name Type Description
result string Bluetooth address

Errors

Code Message Description
5 ERROR_ILLEGAL_STATE No remote has been assigned

Example

Get Request

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

Get Response

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

info property

Provides access to the unit auxiliary information.

This property is read-only.

Value

Result

Name Type Description
result object Unit auxiliary information
result?.model string (optional) Unit model name or number
result?.serial string (optional) Unit serial number
result?.firmware string (optional) Unit firmware revision
result?.software string (optional) Unit software revision
result?.manufacturer string (optional) Unit manufacturer name

Errors

Code Message Description
5 ERROR_ILLEGAL_STATE No remote has been assigned
1 ERROR_GENERAL Failed to retrieve information

Example

Get Request

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

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "model": "Acme 1500 Plus",
    "serial": "1234567890",
    "firmware": "1.0",
    "software": "1.0",
    "manufacturer": "Acme Inc."
  }
}

batterylevel property

Provides access to the battery level.

This property is read-only.

Value

Result

Name Type Description
result number Remote control unit's battery level in percentage

Errors

Code Message Description
5 ERROR_ILLEGAL_STATE No remote has been assigned
1 ERROR_GENERAL Failed to retrieve battery level

Example

Get Request

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

Get Response

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

voice property

Provides access to the enable or Disable the flow of Voice data fragments from the remote.

Value

Name Type Description
(property) boolean enable (true) or disable (false) flow of voice data

Result

Name Type Description
result boolean enable (true) or disable (false) flow of voice data

Errors

Code Message Description
1 ERROR_GENERAL Failed to set the voice flow

Example

Get Request

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

Get Response

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

Set Request

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

Set Response

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

audioprofile property

Provides access to the audio profile details.

This property is read-only.

Value

Result

Name Type Description
result object Audio profile details
result.codec string Name of the audio codec (pcm for uncompressed audio) (must be one of the following: PCM, ADPCM)
result.channels number Number of audio channels (1: mono, 2: stereo, etc.)
result.rate number Sample rate (in Hz)
result.resolution number Sample resolution (in bits per sample)

Errors

Code Message Description
5 ERROR_ILLEGAL_STATE No remote has been assigned
22 ERROR_UNKNOWN_KEY The supplied audio profile is unknown

Example

Get Request

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

Get Response

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

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:

Event Description
audiotransmission Notifies about audio data transmission
audioframe Notifies about new audio data available
batterylevelchange Notifies about battery level changes

audiotransmission event

Notifies about audio data transmission.

Description

Register to this event to be notified about audio transmission status

Parameters

Name Type Description
params object
params?.profile string (optional) Type of audio profile, marking start of transmission; empty in case of end of transmission

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.audiotransmission",
  "params": {
    "profile": "pcm"
  }
}

audioframe event

Notifies about new audio data available.

Description

Register to this event to be notified about audio data

Parameters

Name Type Description
params object
params?.seq number (optional) Sequence number of the audio frame within current audio transmission
params.data string Base64 representation of the binary data of the audio frame; format of the data is specified by the audio profile denoted by the most recent audiotransmission notification

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.audioframe",
  "params": {
    "seq": 1,
    "data": "yKMHiYh6qJiDspB6S7ihlKOAbivApYEQDCgY0aECCQhpkAqZogP1ECk9GbHGEAkwG8Ax8wArgaAtEMjGQIoYCKKgGCuzBSA/iuWkKEwamLKzOKoCeR2hwQQZKqgBKKqELoGQwQ=="
  }
}

batterylevelchange event

Notifies about battery level changes.

Description

Register to this event to be notified about battery level drops

Parameters

Name Type Description
params object
params.level number Battery level (in percentage)

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.batterylevelchange",
  "params": {
    "level": 50
  }
}