Skip to main content

Switch

The Switch component handles the switch (relay) of a device.

Status#

The status of the Switch component contains information about the temperature, voltage, energy level and other physical characteristics of the switch instance.

Properties:

  • 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, last measured instantaneous power (in Watts) delivered to the attached load (shown if applicable)
  • voltage: number, last measured voltage in Volts (shown if applicable)
  • current: number, last measured current in Amperes (shown if applicable)
  • pf: number, last measured power factor (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)
  • temperature: JSON object, information about the temperature
    • tC: number or null, temperature in Celsius (null if temperature is out of the measurement range)
    • tF: number or null, temperature in Fahrenheit (null if temperature is out of the measurement range)
  • errors: array of type string, error conditions occurred. May contain overtemp, overpower, overvoltage, (shown if at least one error is present)
Example status object
{
"id": 0,
"source": "timer",
"output": false,
"timer_started_at": 1626942399.36,
"timer_duration": 60,
"apower": 0.0,
"voltage": 237.5,
"current": 0.0,
"pf": -0.41,
"aenergy": {
"total": 14.093,
"by_minute": [
0,
88.547,
47.276
],
"minute_ts": 1626942456
},
"temperature": {
"tC": 57,
"tF": 134.6
},
"errors": ["overpower", "overvoltage"]
}

Configuration#

The configuration of the Switch component contains information about the input mode, the timers and the protection settings of the chosen switch instance.

Properties:

  • 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 until 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 until the component is switched back off
  • power_limit: number or null, limit (in Watts) over which overpower condition occurs or null when overpower protection is disabled (shown if applicable)
  • voltage_limit: number, limit (in Volts) over which overvoltage condition occurs (shown if applicable)
  • current_limit: number, limit (in Amperes) over which overcurrent condition occurs (shown if applicable)
info
  • momentary: available only when the corresponding input is stateless (e.g. type: button)

  • follow: the state of the switch is the same as the state of the input (e.g. when the input is off => the switch is off)

  • flip: change of the state of the input causes change of the state of the switch (e.g. when input is toggled the switch is also)

  • detached: the state of the input doesn't affect the state of the switch

    follow and flip are available only when the input has state (e.g. type:switch).

Example configuration object
{
"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,
"voltage_limit": 280,
"current_limit": 16.00
}
info

When setting a configuration through Switch.SetConfig() take into account that:

  • power_limit can be set from 0W to the max rated output power or to null to disable overpower protection
  • voltage_limit can be set from 0V to the max rated output voltage or to null to reset to default value
  • current_limit can be set from 0A to the max rated output current or to null to reset to default value

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 invocation 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_after: 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 invocation 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, toggle}. 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