Controller Plugin

Version: 1.0

Status: ⚫⚫⚫

A Controller plugin for Thunder framework.

Introduction

Scope

This document describes purpose and functionality of the Controller plugin. It includes detailed specification about its configuration, methods and properties provided, as well as notifications sent.

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
FQDN	Fully Qualified Domain Name
HTTP	Hypertext Transfer Protocol
JSON	JavaScript Object Notation; a data interchange format
JSON-RPC	A remote procedure call protocol encoded in JSON
SSDP	Simple Service Discovery Protocol
URL	Uniform Resource Locator

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 Controller plugin controls (activates and deactivates) the configured plugins. The plugin is part of the framework and cannot be activated or deactivated itself, thus as well cannot not be unloaded.

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	^(optional) Instance name of the plugin (default: Controller)
autostart	boolean	^(optional) Determines if the plugin is to be started along with the framework (always true as Controller is a part of the framework)
configuration	object	^(optional) Custom plugin configuration:
configuration?.downloadstore	string	^(optional) Path within persistent storage to hold file downloads
configuration?.ttl	number	^(optional) TTL to be set on the broadcast package for framework discovery in the network (default: 1)
configuration?.resumes	array	^(optional) List of callsigns that have an IStateControl interface and need a resume at startup
configuration?.resumes[#]	string	^(optional) Plugin callsign
configuration?.subsystems	array	^(optional) List of subsystems configured for the system
configuration?.subsystems[#]	string	^(optional) Subsystem name

Interfaces

This plugin implements the following interfaces:

Controller.json

Methods

The following methods are provided by the Controller plugin:

Controller interface methods:

Method	Description
activate	Activates a plugin
deactivate	Deactivates a plugin
unavailable	Set a plugin unavailable for interaction
startdiscovery	Starts the network discovery
storeconfig	Stores the configuration
delete	Removes contents of a directory from the persistent storage
harakiri	Reboots the device

activate ^method

Activates a plugin.

Description

Use this method to activate a plugin, i.e. move from Deactivated, via Activating to Activated state. If a plugin is in the Activated state, it can handle JSON-RPC requests that are coming in. The plugin is loaded into memory only if it gets activated.

Also see: statechange

Parameters

Name	Type	Description
params	object
params.callsign	string	Plugin callsign

Result

Name	Type	Description
result	null	Always null

Errors

Code	Message	Description
31	`ERROR_PENDING_CONDITIONS`	The plugin will be activated once its activation preconditions are met
12	`ERROR_INPROGRESS`	The plugin is currently being activated
22	`ERROR_UNKNOWN_KEY`	The plugin does not exist
6	`ERROR_OPENING_FAILED`	Failed to activate the plugin
5	`ERROR_ILLEGAL_STATE`	Current state of the plugin does not allow activation
24	`ERROR_PRIVILEGED_REQUEST`	Activation of the plugin is not allowed (e.g. Controller)

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.activate",
    "params": {
        "callsign": "DeviceInfo"
    }
}

Response

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

deactivate ^method

Deactivates a plugin.

Description

Use this method to deactivate a plugin, i.e. move from Activated, via Deactivating to Deactivated state. If a plugin is Deactivated, the actual plugin (.so) is no longer loaded into the memory of the process. In a deactivated state, the plugin will not respond to any JSON-RPC requests.

Also see: statechange

Parameters

Name	Type	Description
params	object
params.callsign	string	Callsign of the plugin

Result

Name	Type	Description
result	null	Always null

Errors

Code	Message	Description
12	`ERROR_INPROGRESS`	The plugin is currently being deactivated
22	`ERROR_UNKNOWN_KEY`	The plugin does not exist
5	`ERROR_ILLEGAL_STATE`	Current state of the plugin does not allow deactivation
19	`ERROR_CLOSING_FAILED`	Failed to activate the plugin
24	`ERROR_PRIVILEGED_REQUEST`	Deactivation of the plugin is not allowed (e.g. Controller)

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.deactivate",
    "params": {
        "callsign": "DeviceInfo"
    }
}

Response

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

unavailable ^method

Set a plugin unavailable for interaction.

Description

Use this method to mark a plugin as unavailable, i.e. move from Deactivated to Unavailable state. If a plugin is Unavailable, the actual plugin (.so) is no longer loaded into the memory of the process. The plugin will not respond to any JSON-RPC requests and it can not be startedunless it is first deactivated (which triggers a state transition.

Also see: statechange

Parameters

Name	Type	Description
params	object
params.callsign	string	Callsign of the plugin

Result

Name	Type	Description
result	null	Always null

Errors

Code	Message	Description
22	`ERROR_UNKNOWN_KEY`	The plugin does not exist
5	`ERROR_ILLEGAL_STATE`	Current state of the plugin does not allow setting to Unavailable
19	`ERROR_CLOSING_FAILED`	Failed to activate the plugin
24	`ERROR_PRIVILEGED_REQUEST`	Marking the plugin as unavailable is not allowed (e.g. Controller)

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.unavailable",
    "params": {
        "callsign": "DeviceInfo"
    }
}

Response

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

startdiscovery ^method

Starts the network discovery.

Description

Use this method to initiate SSDP network discovery process.

Parameters

Name	Type	Description
params	object
params.ttl	number	TTL (time to live) parameter for SSDP discovery

Result

Name	Type	Description
result	null	Always null

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.startdiscovery",
    "params": {
        "ttl": 1
    }
}

Response

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

storeconfig ^method

Stores the configuration.

Description

Use this method to save the current configuration to persistent memory.

Parameters

This method takes no parameters.

Result

Name	Type	Description
result	null	Always null

Errors

Code	Message	Description
1	`ERROR_GENERAL`	Failed to store the configuration

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.storeconfig"
}

Response

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

delete ^method

Removes contents of a directory from the persistent storage.

Description

Use this method to recursively delete contents of a directory

Parameters

Name	Type	Description
params	object
params.path	string	Path to directory (within the persistent storage) to delete contents of

Result

Name	Type	Description
result	null	Always null

Errors

Code	Message	Description
22	`ERROR_UNKNOWN_KEY`	The given path was incorrect
24	`ERROR_PRIVILEGED_REQUEST`	The path points outside of persistent directory or some files/directories couldn't have been deleted

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.delete",
    "params": {
        "path": "test/test.txt"
    }
}

Response

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

harakiri ^method

Reboots the device.

Description

Use this method to reboot the device. Depending on the device, this call may not generate a response.

Parameters

This method takes no parameters.

Result

Name	Type	Description
result	null	Always null

Errors

Code	Message	Description
2	`ERROR_UNAVAILABLE`	Rebooting procedure is not available on the device
24	`ERROR_PRIVILEGED_REQUEST`	Insufficient privileges to reboot the device
1	`ERROR_GENERAL`	Failed to reboot the device

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.harakiri"
}

Response

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

Properties

The following properties are provided by the Controller plugin:

Controller interface properties:

Property	Description
status ^RO	Information about plugins, including their configurations
links ^RO	Information about active connections
processinfo ^RO	Information about the framework process
subsystems ^RO	Status of the subsystems
discoveryresults ^RO	SSDP network discovery results
environment ^RO	Value of an environment variable
configuration	Configuration object of a service
version	version of the controller
prefix	prefix
idletime	idle time
latitude	latitude
longitude	longitude

status ^property

Provides access to the information about plugins, including their configurations.

This property is read-only.

Value

Name	Type	Description
(property)	array	A list of loaded plugins
(property)[#]	object	(a plugin entry)
(property)[#].callsign	string	Instance name of the plugin
(property)[#].locator	string	Library name
(property)[#].classname	string	Class name
(property)[#].autostart	string	Determines if the plugin is to be started automatically along with the framework
(property)[#]?.precondition	array	^(optional) List of subsystems the plugin depends on
(property)[#]?.precondition[#]	string	^(optional) (a subsystem entry) (must be one of the following: Platform, Network, Security, Identifier, Internet, Location, Time, Provisioning, Decryption, Graphics, WebSource, Streaming)
(property)[#]?.configuration	string	^(optional) Custom configuration properties of the plugin
(property)[#].state	string	State of the plugin (must be one of the following: Deactivated, Deactivation, Activated, Activation, Suspended, Resumed, Precondition)
(property)[#].processedrequests	number	Number of API requests that have been processed by the plugin
(property)[#].processedobjects	number	Number of objects that have been processed by the plugin
(property)[#].observers	number	Number of observers currently watching the plugin (WebSockets)
(property)[#]?.module	string	^(optional) Name of the plugin from a module perspective (used e.g. in tracing)
(property)[#]?.hash	string	^(optional) SHA256 hash identifying the sources from which this plugin was build

The callsign argument shall be passed as the index to the property, e.g. Controller.1.status@DeviceInfo. If the callsign is omitted, then status of all plugins is returned.

Errors

Code	Message	Description
22	`ERROR_UNKNOWN_KEY`	The plugin does not exist

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.status@DeviceInfo"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": [
        {
            "callsign": "DeviceInfo",
            "locator": "libWPEFrameworkDeviceInfo",
            "classname": "DeviceInfo",
            "autostart": "True",
            "precondition": [
                "Platform"
            ],
            "configuration": "...",
            "state": "Activated",
            "processedrequests": 2,
            "processedobjects": 0,
            "observers": 0,
            "module": "Plugin_DeviceInfo",
            "hash": "custom"
        }
    ]
}

links ^property

Provides access to the information about active connections.

This property is read-only.

Value

Name	Type	Description
(property)	array	List of active connections
(property)[#]	object	(a connection entry)
(property)[#].remote	string	IP address (or FQDN) of the other side of the connection
(property)[#].state	string	State of the link (must be one of the following: WebServer, WebSocket, RawSocket, Closed, Suspended)
(property)[#].activity	boolean	Denotes if there was any activity on this connection
(property)[#].id	number	A unique number identifying the connection
(property)[#]?.name	string	^(optional) Name of the connection

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.links"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": [
        {
            "remote": "localhost:52116",
            "state": "RawSocket",
            "activity": false,
            "id": 1,
            "name": "Controller"
        }
    ]
}

processinfo ^property

Provides access to the information about the framework process.

This property is read-only.

Value

Name	Type	Description
(property)	object	Information about the framework process
(property).threads	array	Thread pool
(property).threads[#]	number	(a thread entry)
(property).pending	number	Pending requests
(property).occupation	number	Pool occupation

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.processinfo"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "threads": [
            0
        ],
        "pending": 0,
        "occupation": 2
    }
}

subsystems ^property

Provides access to the status of the subsystems.

This property is read-only.

Value

Name	Type	Description
(property)	array	Status of the subsystems
(property)[#]	object
(property)[#].subsystem	string	Subsystem name (must be one of the following: Platform, Network, Security, Identifier, Internet, Location, Time, Provisioning, Decryption, Graphics, WebSource, Streaming)
(property)[#].active	boolean	Denotes whether the subsystem is active (true)

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.subsystems"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": [
        {
            "subsystem": "Platform",
            "active": true
        }
    ]
}

discoveryresults ^property

Provides access to the SSDP network discovery results.

This property is read-only.

Value

Name	Type	Description
(property)	array	List of network discovery results
(property)[#]	object	(a discovery result entry)
(property)[#].locator	string
(property)[#].latency	number
(property)[#].model	string
(property)[#].secure	boolean

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.discoveryresults"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": [
        {
            "locator": "...",
            "latency": 0,
            "model": "...",
            "secure": true
        }
    ]
}

environment ^property

Provides access to the value of an environment variable.

This property is read-only.

Value

Name	Type	Description
(property)	string	Value of an environment variable

The variable argument shall be passed as the index to the property, e.g. Controller.1.environment@SHELL.

Errors

Code	Message	Description
22	`ERROR_UNKNOWN_KEY`	The variable is not defined

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.environment@SHELL"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "/bin/sh"
}

configuration ^property

Provides access to the configuration object of a service.

Value

Name	Type	Description
(property)	object	The configuration JSON object

The callsign argument shall be passed as the index to the property, e.g. Controller.1.configuration@WebKitBrowser.

Errors

Code	Message	Description
22	`ERROR_UNKNOWN_KEY`	The service does not exist
1	`ERROR_GENERAL`	Failed to update the configuration

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.configuration@WebKitBrowser"
}

Get Response

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

Set Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.configuration@WebKitBrowser",
    "params": {}
}

Set Response

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

version ^property

Provides access to the version of the controller.

Value

Name	Type	Description
(property)	string	version of the controller

Errors

Code	Message	Description
1	`ERROR_GENERAL`	Failed to get/update the version

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.version"
}

Get Response

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

Set Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.version",
    "params": "1.0"
}

Set Response

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

prefix ^property

Provides access to the prefix.

Value

Name	Type	Description
(property)	string	prefix

Errors

Code	Message	Description
1	`ERROR_GENERAL`	Failed to update the prefix

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.prefix"
}

Get Response

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

Set Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.prefix",
    "params": "prefix"
}

Set Response

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

idletime ^property

Provides access to the idle time.

Value

Name	Type	Description
(property)	number	idle time

Errors

Code	Message	Description
1	`ERROR_GENERAL`	Failed to update the idletime

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.idletime"
}

Get Response

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

Set Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.idletime",
    "params": 1
}

Set Response

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

latitude ^property

Provides access to the latitude.

Value

Name	Type	Description
(property)	number	latitude

Errors

Code	Message	Description
1	`ERROR_GENERAL`	Failed to update the latitude

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.latitude"
}

Get Response

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

Set Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.latitude",
    "params": 100
}

Set Response

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

longitude ^property

Provides access to the longitude.

Value

Name	Type	Description
(property)	number	longitude

Errors

Code	Message	Description
1	`ERROR_GENERAL`	Failed to update the longitude

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.longitude"
}

Get Response

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

Set Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "Controller.1.longitude",
    "params": 200
}

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 Controller plugin:

Controller interface events:

Event	Description
all	Signals each and every event in the system
statechange	Signals a plugin state change
subsystemchange	Signals a subsystem state change

all ^event

Signals each and every event in the system. The Controller plugin is an aggregator of all the events triggered by a specific plugin. All notifications send by any plugin are forwarded over the Controller socket as an event.

Parameters

Name	Type	Description
params	object
params.callsign	string	Callsign of the originator plugin of the event
params.data	object	Object that was broadcasted as an event by the originator plugin

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.1.all",
    "params": {
        "callsign": "WebKitBrowser",
        "data": {}
    }
}

statechange ^event

Signals a plugin state change.

Parameters

Name	Type	Description
params	object
params.callsign	string	Callsign of the plugin that changed state
params.state	string	State of the plugin (must be one of the following: Deactivated, Deactivation, Activated, Activation, Suspended, Resumed, Precondition)
params.reason	string	Cause of the state change (must be one of the following: Requested, Automatic, Failure, MemoryExceeded, Startup, Shutdown)

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.1.statechange",
    "params": {
        "callsign": "WebKitBrowser",
        "state": "Activated",
        "reason": "Requested"
    }
}

subsystemchange ^event

Signals a subsystem state change.

Parameters

Name	Type	Description
params	array
params[#]	object
params[#].subsystem	string	Subsystem name (must be one of the following: Platform, Network, Security, Identifier, Internet, Location, Time, Provisioning, Decryption, Graphics, WebSource, Streaming)
params[#].active	boolean	Denotes whether the subsystem is active (true)

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.1.subsystemchange",
    "params": [
        {
            "subsystem": "Platform",
            "active": true
        }
    ]
}

Files

ControllerPlugin.md

Latest commit

History

ControllerPlugin.md

File metadata and controls

Controller Plugin

Table of Contents

Introduction

Scope

Case Sensitivity

Acronyms, Abbreviations and Terms

References

Description

Configuration

Interfaces

Methods

activate method

Description

Parameters

Result

Errors

Example

Request

Response

deactivate method

Description

Parameters

Result

Errors

Example

Request

Response

unavailable method

Description

Parameters

Result

Errors

Example

Request

Response

startdiscovery method

Description

Parameters

Result

Example

Request

Response

storeconfig method

Description

Parameters

Result

Errors

Example

Request

Response

delete method

Description

Parameters

Result

Errors

Example

Request

Response

harakiri method

Description

Parameters

Result

Errors

Example

Request

Response

Properties

status property

Value

Errors

Example

Get Request

Get Response

links property

activate ^method

deactivate ^method

unavailable ^method

startdiscovery ^method

storeconfig ^method

delete ^method

harakiri ^method

status ^property

links ^property

processinfo ^property

subsystems ^property

discoveryresults ^property

environment ^property

configuration ^property

version ^property

prefix ^property

idletime ^property

latitude ^property