5.4.3 api switch ctrl

The /api/switch/ctrl is used for control of switches.

Service and Privileges Groups

Service group is Switch.
Privileges group is Switch Access Control.

Methods

GET
POST

Request

The request contains parameters in the URL (or in the application/x-www-form-urlencoded format when POST is used).

Table 1. Request Parameters

Parameter Name	Mandatory	Expected Values	Default Value	Description
switch	Yes	Integer defining a switch (typically 1 to 4)	–	Defines which switch will be controlled. api/switch/caps can be used for obtaining the number of switches of a particular device.
action	Yes	String defining the command	–	Defines which command will be applied to the switch. The available commands are: `on` - activate switch `off` - deactivate switch `trigger` - activate monostable switch, toggle the state of bistable switch `lock` - lock switch (locked switch is deactivated and cannot be operated) `unlock` - unlock switch (allow normal operation) `hold` - hold switch activated (held switch is activated and cannot be operated), if the switch is locked and held together it is deactivated `release` - release the switch from being held (allow normal operation)
response	No	String defining a text that is to be returned instead of standard JSON response	–	The device will return the text specified in this parameter instead of a standard JSON response.
timeout	No (used when `action=hold`)	Range of 1–86 400 seconds	–	Defines the timeout in seconds after which the switch releases again automatically after receiving the `hold` command.

Example of a Request

URL: https://192.168.1.1/api/switch/ctrl?switch=4&action=trigger&response=TEST

Response

The success response is in the application/json format (unless a custom text response is defined in the response parameter).

Table 2. Response JSON Keys

Key	Typical Returned Values	Description
success	`true` or `false`	When a command was performed successfully, the success value is `true`, and it is `false` when the requested switch state could not be reached (e.g. the switch is locked and the requested state is activated switch).

Example of a Response

{ "success": true }

Additional error information is contained in the response when the success is false. Error code 14 "action failed" is returned when the requested result could not be achieved (e.g. when the switch is locked and action=on is requested). A command to change the operation type (i.e. held, locked) will always succeed since the operation can be changed all the time except when the switch is disabled (a device will return error 14 to all commands when the switch is disabled).