Skip to content

Latest commit

 

History

History
780 lines (608 loc) · 17.3 KB

RemoteControlPlugin.md

File metadata and controls

780 lines (608 loc) · 17.3 KB
Raw

Remote Control Plugin

Version: 1.0

Status: ⚫⚫⚫

RemoteControl plugin for Thunder framework.

Table of Contents

Introduction

Scope

This document describes purpose and functionality of the RemoteControl plugin. It includes detailed specification of its configuration, methods and properties provided.

Case Sensitivity

All identifiers on the interface 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 RemoteControl plugin provides user-input functionality from various key-code sources (e.g. STB RC).

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: RemoteControl)
classname string Class name: RemoteControl
locator string Library name: libWPEFrameworkRemoteControl.so
autostart boolean Determines if the plugin is to be started automatically along with the framework

Methods

The following methods are provided by the RemoteControl plugin:

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 Description
params object
params.device string Device name
params.code number Key code

Result

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

Errors

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

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "RemoteControl.1.key",
    "params": {
        "device": "DevInput",
        "code": 1
    }
}

Response

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

send method

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

Parameters

Name Type Description
params object
params.device string Device name
params.code number Key code

Result

Name Type Description
result null Always null

Errors

Code Message Description
2 ERROR_UNAVAILABLE Unknown device
30 ERROR_BAD_REQUEST Bad JSON param data format
22 ERROR_UNKNOWN_KEY Key does not exist
28 ERROR_UNKNOWN_TABLE Key map table does not exist
36 ERROR_ALREADY_RELEASED Key is already released

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "RemoteControl.1.send",
    "params": {
        "device": "DevInput",
        "code": 1
    }
}

Response

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

press method

Presses a key on a device.

Parameters

Name Type Description
params object
params.device string Device name
params.code number Key code

Result

Name Type Description
result null Always null

Errors

Code Message Description
2 ERROR_UNAVAILABLE Unknown device
30 ERROR_BAD_REQUEST Bad JSON param data format
22 ERROR_UNKNOWN_KEY Key does not exist
28 ERROR_UNKNOWN_TABLE Key map table does not exist

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "RemoteControl.1.press",
    "params": {
        "device": "DevInput",
        "code": 1
    }
}

Response

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

release method

Releases a key on a device.

Parameters

Name Type Description
params object
params.device string Device name
params.code number Key code

Result

Name Type Description
result null Always null

Errors

Code Message Description
2 ERROR_UNAVAILABLE Unknown device
30 ERROR_BAD_REQUEST Bad JSON param data format
22 ERROR_UNKNOWN_KEY Key does not exist
28 ERROR_UNKNOWN_TABLE Key map table does not exist
36 ERROR_ALREADY_RELEASED Key is already released

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "RemoteControl.1.release",
    "params": {
        "device": "DevInput",
        "code": 1
    }
}

Response

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

add method

Adds a key code to the key map.

Parameters

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

Result

Name Type Description
result null Always null

Errors

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

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "RemoteControl.1.add",
    "params": {
        "device": "DevInput",
        "code": 1,
        "key": 103,
        "modifiers": [
            "leftshift"
        ]
    }
}

Response

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

modify method

Modifies a key code in the key map.

Parameters

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

Result

Name Type Description
result null Always null

Errors

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

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "RemoteControl.1.modify",
    "params": {
        "device": "DevInput",
        "code": 1,
        "key": 103,
        "modifiers": [
            "leftshift"
        ]
    }
}

Response

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

delete method

Deletes a key code from the key map.

Parameters

Name Type Description
params object
params.device string Device name
params.code number Key code

Result

Name Type Description
result null Always null

Errors

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

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "RemoteControl.1.delete",
    "params": {
        "device": "DevInput",
        "code": 1
    }
}

Response

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

load method

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

Parameters

Name Type Description
params object
params.device string Device name

Result

Name Type Description
result null Always null

Errors

Code Message Description
2 ERROR_UNAVAILABLE Unknown device
1 ERROR_GENERAL File does not exist
30 ERROR_BAD_REQUEST Bad JSON param data format
5 ERROR_ILLEGAL_STATE Illegal state
6 ERROR_OPENING_FAILED Opening failed

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "RemoteControl.1.load",
    "params": {
        "device": "DevInput"
    }
}

Response

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

save method

Saves the device's key map into persistent path.

Parameters

Name Type Description
params object
params.device string Device name

Result

Name Type Description
result null Always null

Errors

Code Message Description
2 ERROR_UNAVAILABLE Unknown device
1 ERROR_GENERAL File is not created
30 ERROR_BAD_REQUEST Bad JSON param data format
5 ERROR_ILLEGAL_STATE Illegal state

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "RemoteControl.1.save",
    "params": {
        "device": "DevInput"
    }
}

Response

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

pair method

Activates pairing mode of a device.

Parameters

Name Type Description
params object
params.device string Device name

Result

Name Type Description
result null Always null

Errors

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

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "RemoteControl.1.pair",
    "params": {
        "device": "DevInput"
    }
}

Response

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

unpair method

Unpairs a device.

Parameters

Name Type Description
params object
params.device string Device name
params.bindid string Binding ID

Result

Name Type Description
result null Always null

Errors

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

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "RemoteControl.1.unpair",
    "params": {
        "device": "DevInput",
        "bindid": "id"
    }
}

Response

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

Properties

The following properties are provided by the RemoteControl plugin:

RemoteControl interface properties:

Property Description
devices RO Names of all available devices
device RO Metadata of a specific device

devices property

Provides access to the names of all available devices.

This property is read-only.

Value

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

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "RemoteControl.1.devices"
}

Get Response

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

device property

Provides access to the metadata of a specific device.

This property is read-only.

Value

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

The device shall be passed as the index to the property, e.g. RemoteControl.1.device@DevInput.

Errors

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

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "RemoteControl.1.device@DevInput"
}

Get Response

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