Skip to content

Latest commit

 

History

History
712 lines (556 loc) · 17.6 KB

WifiControlPlugin.md

File metadata and controls

712 lines (556 loc) · 17.6 KB
Raw

WiFi Control Plugin

Version: 1.0

Status: ⚫⚫⚪

WifiControl plugin for Thunder framework.

Table of Contents

Introduction

Scope

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

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 WiFi Control plugin allows to manage various aspects of wireless connectivity.

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

Methods

The following methods are provided by the WifiControl plugin:

WifiControl interface methods:

Method Description
delete Forgets the configuration of a network
store Stores the configurations in persistent storage
scan Searches for available networks
connect Attempts connection to a network
disconnect Disconnects from a network

delete method

Forgets the configuration of a network.

Parameters

Name Type Description
params object
params.ssid string Identifier of a network

Result

Name Type Description
result null Always null

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "WifiControl.1.delete",
    "params": {
        "ssid": "MyCorporateNetwork"
    }
}

Response

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

store method

Stores the configurations in persistent storage.

Parameters

This method takes no parameters.

Result

Name Type Description
result null Always null

Errors

Code Message Description
40 ERROR_WRITE_ERROR Returned when the operation failed

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "WifiControl.1.store"
}

Response

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

scan method

Searches for available networks.

Also see: scanresults

Parameters

This method takes no parameters.

Result

Name Type Description
result null Always null

Errors

Code Message Description
12 ERROR_INPROGRESS Returned when scan is already in progress
2 ERROR_UNAVAILABLE Returned when scanning is not available for some reason

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "WifiControl.1.scan"
}

Response

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

connect method

Attempts connection to a network.

Also see: connectionchange

Parameters

Name Type Description
params object
params.ssid string Identifier of a network

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Returned when the network with a the given SSID doesn't exists
4 ERROR_ASYNC_ABORTED Returned when connection attempt fails for other reasons

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "WifiControl.1.connect",
    "params": {
        "ssid": "MyCorporateNetwork"
    }
}

Response

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

disconnect method

Disconnects from a network.

Also see: connectionchange

Parameters

Name Type Description
params object
params.ssid string Identifier of a network

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Returned when the network with a the given SSID doesn't exists
4 ERROR_ASYNC_ABORTED Returned when disconnection attempt fails for other reasons

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "WifiControl.1.disconnect",
    "params": {
        "ssid": "MyCorporateNetwork"
    }
}

Response

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

Properties

The following properties are provided by the WifiControl plugin:

WifiControl interface properties:

Property Description
status RO Network status
networks RO Available networks
configs RO All WiFi configurations
config Single WiFi conifguration
debug WO Sets debug level

status property

Provides access to the network status.

This property is read-only.

Value

Name Type Description
(property) object Network status
(property).connected string Identifier of the connected network
(property).scanning boolean Indicates whether a scanning for available network is in progress

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "WifiControl.1.status"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": {
        "connected": "MyCorporateNetwork",
        "scanning": false
    }
}

networks property

Provides access to the available networks.

This property is read-only.

Value

Name Type Description
(property) array Available networks
(property)[#] object
(property)[#].ssid string Identifier of a network
(property)[#].pairs array
(property)[#].pairs[#] object
(property)[#].pairs[#].method string Encryption method used by the network
(property)[#].pairs[#].keys array
(property)[#].pairs[#].keys[#] string Types of supported keys
(property)[#]?.bssid string (optional) 48-bits long BSS identifier (might be MAC format)
(property)[#].frequency number Network's frequency in MHz
(property)[#].signal number Network's signal level in dBm

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "WifiControl.1.networks"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": [
        {
            "ssid": "MyCorporateNetwork",
            "pairs": [
                {
                    "method": "WPA",
                    "keys": [
                        "psk"
                    ]
                }
            ],
            "bssid": "94:b4:0f:77:cc:71",
            "frequency": 5180,
            "signal": -44
        }
    ]
}

configs property

Provides access to the all WiFi configurations.

This property is read-only.

Value

Name Type Description
(property) array All WiFi configurations
(property)[#] object
(property)[#].ssid string Identifier of a network
(property)[#]?.type string (optional) Level of security (must be one of the following: Unknown, Unsecure, WPA, Enterprise)
(property)[#].hidden boolean Indicates whether a network is hidden
(property)[#].accesspoint boolean Indicates if the network operates in AP mode
(property)[#]?.psk string (optional) Network's PSK in plaintext (irrelevant if hash is provided)
(property)[#]?.hash string (optional) Network's PSK as a hash
(property)[#].identity string User credentials (username part) for EAP
(property)[#].password string User credentials (password part) for EAP

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Configuration does not exist

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "WifiControl.1.configs"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": [
        {
            "ssid": "MyCorporateNetwork",
            "type": "WPA",
            "hidden": false,
            "accesspoint": true,
            "psk": "secretpresharedkey",
            "hash": "59e0d07fa4c7741797a4e394f38a5c321e3bed51d54ad5fcbd3f84bc7415d73d",
            "identity": "user",
            "password": "password"
        }
    ]
}

config property

Provides access to the single WiFi conifguration.

Value

Name Type Description
(property) object Single WiFi conifguration
(property).ssid string Identifier of a network
(property)?.type string (optional) Level of security (must be one of the following: Unknown, Unsecure, WPA, Enterprise)
(property).hidden boolean Indicates whether a network is hidden
(property).accesspoint boolean Indicates if the network operates in AP mode
(property)?.psk string (optional) Network's PSK in plaintext (irrelevant if hash is provided)
(property)?.hash string (optional) Network's PSK as a hash
(property).identity string User credentials (username part) for EAP
(property).password string User credentials (password part) for EAP

The ssid shall be passed as the index to the property, e.g. WifiControl.1.config@MyCorporateNetwork. If not specified all configurations are returned.

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Configuration does not exist
23 ERROR_INCOMPLETE_CONFIG Passed in configuration is invalid

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "WifiControl.1.config@MyCorporateNetwork"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": {
        "ssid": "MyCorporateNetwork",
        "type": "WPA",
        "hidden": false,
        "accesspoint": true,
        "psk": "secretpresharedkey",
        "hash": "59e0d07fa4c7741797a4e394f38a5c321e3bed51d54ad5fcbd3f84bc7415d73d",
        "identity": "user",
        "password": "password"
    }
}

Set Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "WifiControl.1.config@MyCorporateNetwork",
    "params": {
        "ssid": "MyCorporateNetwork",
        "type": "WPA",
        "hidden": false,
        "accesspoint": true,
        "psk": "secretpresharedkey",
        "hash": "59e0d07fa4c7741797a4e394f38a5c321e3bed51d54ad5fcbd3f84bc7415d73d",
        "identity": "user",
        "password": "password"
    }
}

Set Response

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

debug property

Provides access to the sets debug level.

This property is write-only.

Value

Name Type Description
(property) number Debug level

Errors

Code Message Description
2 ERROR_UNAVAILABLE Returned when the operation is unavailable

Example

Set Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "WifiControl.1.debug",
    "params": 0
}

Set Response

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

Notifications

Notifications are autonomous events, triggered by the internals of the plugin, 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 WifiControl plugin:

WifiControl interface events:

Event Description
scanresults Signals that the scan operation has finished
networkchange Signals that a network property has changed
connectionchange Notifies about connection state change

scanresults event

Signals that the scan operation has finished.

Parameters

Name Type Description
params array
params[#] object
params[#].ssid string Identifier of a network
params[#].pairs array
params[#].pairs[#] object
params[#].pairs[#].method string Encryption method used by the network
params[#].pairs[#].keys array
params[#].pairs[#].keys[#] string Types of supported keys
params[#]?.bssid string (optional) 48-bits long BSS identifier (might be MAC format)
params[#].frequency number Network's frequency in MHz
params[#].signal number Network's signal level in dBm

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.1.scanresults",
    "params": [
        {
            "ssid": "MyCorporateNetwork",
            "pairs": [
                {
                    "method": "WPA",
                    "keys": [
                        "psk"
                    ]
                }
            ],
            "bssid": "94:b4:0f:77:cc:71",
            "frequency": 5180,
            "signal": -44
        }
    ]
}

networkchange event

Signals that a network property has changed (e.g. frequency).

Parameters

This event carries no parameters.

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.1.networkchange"
}

connectionchange event

Notifies about connection state change (i.e. connected/disconnected).

Parameters

Name Type Description
params string SSID of the connected network in case of connect or empty in case of disconnect

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.1.connectionchange",
    "params": "MyCorporateNetwork"
}