Skip to content

Latest commit

 

History

History
853 lines (658 loc) · 18.2 KB

RemoteControlPlugin.md

File metadata and controls

853 lines (658 loc) · 18.2 KB
Raw

Remote Control Plugin

Version: 1.0

Status: ⚫⚫⚫

RemoteControl plugin for WPEFramework.

Table of Contents

Introduction

Scope

This document describes purpose and functionality of the RemoteControl plugin. It includes detailed specification of its configuration and methods 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
WPEF WPEFramework 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 WPEFramework. For more information on WPEFramework refer to [WPEF].

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
devices Retrieves device information
device Retrieves device metadata
key Retrieves key actions
delete Deletes key actions
modify Modifies key actions
pair Pairs a device
unpair Unpairs a device
send Sends key actions
press Presses a key
release Releases a key
save Saves the key map
load Loads a keymap
add Adds a key

devices method

Retrieves device information

Description

Retrieves names of all available devices.

Parameters

This method takes no parameters.

Result

Name Type Description
result array
result[#] string Available device name

Example

Request

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

Response

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

device method

Retrieves device metadata

Description

Retrieves the metadata of specific devices.

Parameters

Name Type Description
params object
params.device string Device name

Result

Name Type Description
result object
result.name string Device name
result.metadata string Device metadata

Errors

Code Message Description
1 ERROR_GENERAL Virtual device is loaded
2 ERROR_UNAVAILABLE Unknown device
30 ERROR_BAD_REQUEST Bad JSON param data format

Example

Request

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

Response

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

key method

Retrieves key actions

Description

Retrieves the 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 code
result.modifiers array
result.modifiers[#] string Key modifiers (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"
        ]
    }
}

delete method

Deletes key actions

Description

Deletes the key code from 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
}

modify method

Modifies key actions

Description

Modifies the key code in the map.

Parameters

Name Type Description
params object
params.device string Device name
params.code number Key code
params.key number Key ingest code
params.modifiers array
params.modifiers[#] string Key modifiers (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
}

pair method

Pairs a device

Description

Activates pairing mode of specific 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

Description

Unpairs a specific 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 a specific 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
}

send method

Sends key actions

Description

Sends a code to a device.

Parameters

Name Type Description
params object
params.device string Device name
params.code number Key code
params.key number Key ingest code
params.modifiers array
params.modifiers[#] string Key modifiers (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
28 ERROR_UNKNOWN_TABLE Key map table does not exist
36 ERROR_ALREADY_RELEASED Key is already releases

Example

Request

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

Response

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

press method

Presses a key

Description

Sends a 'Press' code to a device.

Parameters

Name Type Description
params object
params.device string Device name
params.code number Key code
params.key number Key ingest code
params.modifiers array
params.modifiers[#] string Key modifiers (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
28 ERROR_UNKNOWN_TABLE Key map table does not exist
36 ERROR_ALREADY_RELEASED Key is already releases

Example

Request

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

Response

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

release method

Releases a key.

Description

Sends a code 'Release' to a device.

Parameters

Name Type Description
params object
params.device string Device name
params.code number Key code
params.key number Key ingest code
params.modifiers array
params.modifiers[#] string Key modifiers (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
28 ERROR_UNKNOWN_TABLE Key map table does not exist
36 ERROR_ALREADY_RELEASED Key is already releases

Example

Request

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

Response

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

save method

Saves the key map

Description

Saves the loaded key map as DEVICE_NAME.json 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
}

load method

Loads a keymap

Description

Re-loads DEVICE_NAME.json key map into 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
}

add method

Adds a key

Description

Adds the key code in the map.

Parameters

Name Type Description
params object
params.device string Device name
params.code number Key code
params.key number Key ingest code
params.modifiers array
params.modifiers[#] string Key modifiers (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
}