Skip to content

Remote Control API

Version: 1.0.0

Status: ⚫⚪⚪

RemoteControl interface for Thunder framework.

(Defined by RemoteControl.json)

Table of Contents

Introduction

Scope

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

RemoteControl JSON-RPC interface.

Methods

The following methods are provided by the RemoteControl interface:

RemoteControl interface methods:

Method Description
key Gets key code details
send Sends a key to a device (press and release)
press Presses a key on a device
release Releases a key on a device
add Adds a key code to the key map
modify Modifies a key code in the key map
delete Deletes a key code from the key map
load Re-loads the device's key map from persistent memory
save Saves the device's key map into persistent path
pair Activates pairing mode of a device
unpair Unpairs a device

key method

Gets key code details.

Parameters

Name Type M/O Description
params object mandatory ...
params.device string mandatory Device name
params.code integer mandatory Key code

Result

Name Type M/O Description
result object mandatory ...
result.code integer mandatory Key code
result.key integer mandatory Key ingest value
result?.modifiers array optional List of key modifiers
result?.modifiers[#] string mandatory Key modifier (must be one of the following: leftalt, leftctrl, leftshift, rightalt, rightctrl, rightshift)

Errors

Message Description
ERROR_UNKNOWN_KEY Key does not exist
ERROR_UNAVAILABLE Unknown device
ERROR_BAD_REQUEST Bad JSON param data format

Example

Request

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

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "code": 1,
    "key": 103,
    "modifiers": [
      "leftshift"
    ]
  }
}

send method

Sends a key to a device (press and release).

Parameters

Name Type M/O Description
params object mandatory ...
params.device string mandatory Device name
params.code integer mandatory Key code

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_UNAVAILABLE Unknown device
ERROR_BAD_REQUEST Bad JSON param data format
ERROR_UNKNOWN_KEY Key does not exist
ERROR_UNKNOWN_TABLE Key map table does not exist
ERROR_ALREADY_RELEASED Key is already released

Example

Request

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

Response

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

press method

Presses a key on a device.

Parameters

Name Type M/O Description
params object mandatory ...
params.device string mandatory Device name
params.code integer mandatory Key code

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_UNAVAILABLE Unknown device
ERROR_BAD_REQUEST Bad JSON param data format
ERROR_UNKNOWN_KEY Key does not exist
ERROR_UNKNOWN_TABLE Key map table does not exist

Example

Request

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

Response

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

release method

Releases a key on a device.

Parameters

Name Type M/O Description
params object mandatory ...
params.device string mandatory Device name
params.code integer mandatory Key code

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_UNAVAILABLE Unknown device
ERROR_BAD_REQUEST Bad JSON param data format
ERROR_UNKNOWN_KEY Key does not exist
ERROR_UNKNOWN_TABLE Key map table does not exist
ERROR_ALREADY_RELEASED Key is already released

Example

Request

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

Response

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

add method

Adds a key code to the key map.

Parameters

Name Type M/O Description
params object mandatory ...
params.device string mandatory Device name
params.code integer mandatory Key code
params.key integer mandatory Key ingest value
params?.modifiers array optional List of key modifiers
params?.modifiers[#] string mandatory Key modifier (must be one of the following: leftalt, leftctrl, leftshift, rightalt, rightctrl, rightshift)

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_UNAVAILABLE Unknown device
ERROR_BAD_REQUEST Bad JSON param data format
ERROR_UNKNOWN_KEY Code already exists

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.add",
  "params": {
    "device": "DevInput",
    "code": 1,
    "key": 103,
    "modifiers": [
      "leftshift"
    ]
  }
}

Response

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

modify method

Modifies a key code in the key map.

Parameters

Name Type M/O Description
params object mandatory ...
params.device string mandatory Device name
params.code integer mandatory Key code
params.key integer mandatory Key ingest value
params?.modifiers array optional List of key modifiers
params?.modifiers[#] string mandatory Key modifier (must be one of the following: leftalt, leftctrl, leftshift, rightalt, rightctrl, rightshift)

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_UNAVAILABLE Unknown device
ERROR_BAD_REQUEST Bad JSON param data format
ERROR_UNKNOWN_KEY Key does not exist

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.modify",
  "params": {
    "device": "DevInput",
    "code": 1,
    "key": 103,
    "modifiers": [
      "leftshift"
    ]
  }
}

Response

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

delete method

Deletes a key code from the key map.

Parameters

Name Type M/O Description
params object mandatory ...
params.device string mandatory Device name
params.code integer mandatory Key code

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_UNKNOWN_KEY Key does not exist
ERROR_UNAVAILABLE Unknown device
ERROR_BAD_REQUEST Bad JSON param data format

Example

Request

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

Response

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

load method

Re-loads the device's key map from persistent memory.

Parameters

Name Type M/O Description
params object mandatory ...
params.device string mandatory Device name

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_UNAVAILABLE Unknown device
ERROR_GENERAL File does not exist
ERROR_BAD_REQUEST Bad JSON param data format
ERROR_ILLEGAL_STATE Illegal state
ERROR_OPENING_FAILED Opening failed

Example

Request

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

Response

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

save method

Saves the device's key map into persistent path.

Parameters

Name Type M/O Description
params object mandatory ...
params.device string mandatory Device name

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_UNAVAILABLE Unknown device
ERROR_GENERAL File is not created
ERROR_BAD_REQUEST Bad JSON param data format
ERROR_ILLEGAL_STATE Illegal state

Example

Request

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

Response

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

pair method

Activates pairing mode of a device.

Parameters

Name Type M/O Description
params object mandatory ...
params.device string mandatory Device name

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_UNAVAILABLE Unknown device
ERROR_GENERAL Failed to activate pairing
ERROR_BAD_REQUEST Bad JSON param data format

Example

Request

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

Response

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

unpair method

Unpairs a device.

Parameters

Name Type M/O Description
params object mandatory ...
params.device string mandatory Device name
params.bindid string mandatory Binding ID

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_UNAVAILABLE Unknown device
ERROR_GENERAL Failed to unpair the device
ERROR_BAD_REQUEST Bad JSON param data format

Example

Request

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

Response

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

Properties

The following properties are provided by the RemoteControl interface:

RemoteControl interface properties:

Property R/W Description
devices read-only Names of all available devices
device read-only Metadata of a specific device

devices property

Provides access to the names of all available devices.

This property is read-only.

Value

Name Type M/O Description
(property) array mandatory Names of all available devices
(property)[#] string mandatory Device name

Example

Get Request

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

Get Response

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

device property

Provides access to the metadata of a specific device.

This property is read-only.

The device parameter shall be passed as the index to the property, i.e. device@<device>.

Index

Name Type M/O Description
device string mandatory ...

Value

Name Type M/O Description
(property) object mandatory Metadata of a specific device
(property).metadata string mandatory Device metadata

Errors

Message Description
ERROR_GENERAL Metadata not supported on a virtual device
ERROR_UNAVAILABLE Unknown device
ERROR_BAD_REQUEST Bad JSON param data format

Example

Get Request

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

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "metadata": "It is based on protocol A"
  }
}

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

RemoteControl interface events:

Notification Description
keypressed Notifies of a key press/release action

keypressed notification

Notifies of a key press/release action.

Parameters

The key code parameter shall be passed within the id parameter to the register call, i.e. <key code>.<client-id>.

Notification Parameters

Name Type M/O Description
params object mandatory ...
params.pressed boolean mandatory Denotes if the key was pressed (true) or released (false)

Example

Registration

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

Notification

{
  "jsonrpc": "2.0",
  "method": "42.myid.keypressed",
  "params": {
    "pressed": false
  }
}

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

The key code parameter is passed within the notification designator, i.e. <key code>.<client-id>.keypressed.