Skip to main content

Switch

The Switch component handles the switch (relay) of a device. It supports the following methods:

Switch.GetStatus#

This method returns the status of the component instance.

Request#

Parameters.

  • id: number, id of the Switch component instance. Required
http://192.168.33.1/rpc/Switch.GetStatus?id=0

Response#

Attributes in the result:

  • id: number, id of the Switch component instance
  • source: string, source of the last command, for example: init, WS_in, http, ...
  • output: boolean, true if the output channel is currently on, false otherwise
  • timer_started_at: number, unix timestamp, start time of the timer (in UTC) (shown if the timer is triggered)
  • timer_duration: number, duration of the timer in seconds (shown if the timer is triggered)
  • apower: number, the current (last measured) instantaneous power (in Watts) delivered to the attached load (shown if applicable)
  • voltage: number, current voltage in Volts (shown if applicable)
  • aenergy: JSON object, information about the energy counter (shown if applicable)
    • total: number, total energy consumed in Watt-hours
    • by_minute: array of numbers, energy consumption by minute (in Milliwatt-hours) for the last three minutes (the lower the index of the element in the array, the closer to the current moment the minute)
    • minute_ts: number, unix timestamp of the first second of the last minute (in UTC)
  • temprature: JSON object, information about the temprature
    • tC: number or null, temprature in Celsius (null if not available)
    • tF: number or null, temprature in Fahrenheit (null if not available)
  • errors: array of type string, error conditions occurred. May contain overtemp, overpower, overvoltage (shown if at least one error is present)
{
"id": 0,
"source": "timer",
"output": false,
"timer_started_at": 1626942399.36,
"timer_duration": 60,
"apower": 0,
"voltage": 237.571,
"aenergy": {
"total": 14.093,
"by_minute": [
0,
88.547,
47.276
],
"minute_ts": 1626942456
},
"temperature": {
"tC": 57,
"tF": 134.6
},
"errors": ["overpower", "overvoltage"]
}

Switch.GetConfig#

This method returns the configuration of the component instance.

Request#

Parameters:

  • id: number, id of the Switch component instance. Required
http://192.168.33.1/rpc/Switch.GetConfig?id=0

Response#

Attributes in the result:

  • id: number, id of the Switch component instance
  • name: string or null, name of the switch instance
  • in_mode: string, mode of the associated input. Range of values: {momentary, follow, flip, detached}
  • initial_state: string, output state to set on power_on. Range of values: {off, on, restore_last, match_input}
  • auto_on: boolean, true if the "Automatic ON" function is enabled, false otherwise
  • auto_on_delay: number, seconds to pass untill the component is switched back on
  • auto_off: boolean, true if the "Automatic OFF" function is enabled, false otherwise
  • auto_off_delay: number, seconds to pass untill the component is switched back off
  • power_limit: number, limit (in Watts) over which overpower condition occurs (shown if applicable)

Example:

{
"id": 0,
"name": null,
"in_mode": "follow",
"initial_state": "match_input",
"auto_on": true,
"auto_on_delay": 60,
"auto_off": true,
"auto_off_delay": 60,
"power_limit": 3500
}

Switch.SetConfig#

This method makes changes in the configuration of the component instance.

Request#

Parameters:

  • id: number, id of the Switch component instance. Required
  • config: JSON object, configuration to be applied. This object should be identical in structure to the JSON returned by Switch.GetConfig, containing only the keys that need to be modified. Note that id of the instance cannot be configured. Required
Change the configuration of the switch with id=0 naming it my-Shelly-One and setting it to turn automatically on 5 seconds after it is turned off.
curl -X POST -d '{"id":1, "src":"user_1", "method":"Switch.SetConfig", "params":{"id":0,
"config":{"name":"my-Shelly-One", "auto_on":true, "auto_on_delay":5}}}' http://${SHELLY}/rpc

Response#

Attributes in the result:

  • restart_required: boolean, true if restart is required to apply the changes, false otherwise.
{
"id": 1,
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"result": {
"restart_required": false
}
}

Switch.Toggle#

This method toggles the Switch component. It can be used to trigger webhooks. More information about the events triggering webhooks available for this component can be found below.

Request#

Parameters:

  • id: number, id of the Switch component instance. Required
http://192.168.33.1/rpc/Switch.Toggle?id=0

Response#

Attributes in the result:

  • was_on: boolean, true if the switch was on before the method was executed, false otherwise.
The switch was turned off before the invokation of this method.
{
"was_on": false
}

Switch.Set#

This method sets the output of the Switch component (on/off/toggle). It can be used to trigger webhooks. More information about the events triggering webhooks available for this component can be found below.

Request#

Parameters.

  • id: number, id of the Switch component instance. Required
  • on: boolean, true for switch on, false otherwise. Required
  • toggle: number, optional flip-back timer in seconds. Optional
http://192.168.33.1/rpc/Switch.Set?id=0&on=true

Response#

Attributes in the result:

  • was_on: boolean, true if the switch was on before the method was executed, false otherwise.
The switch was turned off before the invokation of this method.
{
"was_on": false
}

HTTP Endpoint: /relay/id#

Through this endpoint a switch can be turned on/off with or without a timer. This can be used to trigger webhooks. More information about the events triggering webhooks available for this component can be found below.

Request#

Parameters:

  • turn: string, action to be executed. Range of values: {on, off}. Required
  • timer: number, time in ms until the request is executed. Optional

Example:

curl http://${SHELLY}/relay/0?turn=on

Response#

Received attributes:

  • ison: boolean, true if the switch is turned on, false otherwise
  • has_timer: boolean, true if timer is set, false otherwise
  • timer_started_at: number, unix timestamp, start time of the timer (in UTC)
  • timer_duration: number, duration of the timer in seconds
  • timer_remaining: number, time remaining (in seconds) until the request is executed
  • overpower: boolean, true if overpower condition occurred, false otherwise (shown if applicable)
  • source: string, source of the last command, for example: init, WS_in, http, ...

Example:

{
"ison": true,
"has_timer":false,
"timer_started_at": 0,
"timer_duration": 0.00,
"timer_remaining": 0.00,
"overpower": false,
"source": "http"
}

Events Triggering Webhooks#

Currently, there are two events related to the Switch component that can trigger webhooks:

  • switch.on - produced when the switch changes its state from off to on
  • switch.off - produced when the switch changes its state from on to off