Skip to main content
Version: 0.14

Switch

The Switch component handles a switch (relay) output terminal with optional power metering capabilities. It uses Switch as RPC namespace and provides the methods:

Switch components are identified with switch:<id> in objects containing multiple component payloads.

Methods​

Switch.SetConfig​

Properties:

PropertyTypeDescription

id

number

Id of the Switch component instance

config

object

Configuration that the method takes

Find more about the config properties in config section

Switch.GetConfig​

Properties:

PropertyTypeDescription

id

number

Id of the Switch component instance

Find the Switch.GetConfig response properties in config section

Switch.GetStatus​

Properties:

PropertyTypeDescription

id

number

Id of the Switch component instance

Find more about the status response properties in status section

Switch.Set​

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

Request​

Parameters:

PropertyTypeDescription

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

Response​

Attributes in the result:

PropertyTypeDescription

was_on

boolean

True if the switch was on before the method was executed, false otherwise.

Switch.Toggle​

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

Request​

Parameters:

PropertyTypeDescription

id

number

Id of the Switch component instance. Required

Response​

Attributes in the result:

PropertyTypeDescription

was_on

boolean

True if the switch was on before the method was executed, false otherwise.

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:

PropertyTypeDescription

turn

string

Action to be executed. Range of values: on, off, toggle. Required

timer

number

A one-shot flip-back timer in seconds.

Response​

Received attributes:

PropertyTypeDescription

ison

boolean

True if the switch is turned on, false otherwise

has_timer

boolean

True if the switch is turned on, 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, ...

Configuration​

The configuration of the Switch component contains information about the input mode, the timers and the protection settings of the chosen switch instance. To Get/Set the configuration of the Switch component its id must be specified.

PropertyTypeDescription

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

autorecover_voltage_errors

boolean

True if switch output state should be restored after over/undervoltage error is cleared, false otherwise (shown if applicable)

input_id

number

Id of the Input component which controls the Switch. Applicable only to Pro1 and Pro1PM devices. Valid values: 0, 1

power_limit

number

Limit (in Watts) over which overpower condition occurs (shown if applicable)

voltage_limit

number

Limit (in Volts) over which overvoltage condition occurs (shown if applicable)

undervoltage_limit

number

Limit (in Volts) under which undervoltage condition occurs (shown if applicable)

current_limit

number

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).

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 reset to default value
  • voltage_limit can be set from undervoltage_limit to the max rated output voltage or to null to reset to default value
  • undervoltage_limit can be set from 0V (disabled) to the voltage_limit 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

Status​

The status of the Switch component contains information about the temperature, voltage, energy level and other physical characteristics of the switch instance. To obtain the status of the Switch component its id must be specified.

For switches with power metering capabilities the status payload contains an additional set of properties with information about instantaneous power, supply voltage parameters and energy counters.

PropertyTypeDescription

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 active 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

object

Information about the active energy counter (shown if applicable)

PropertyTypeDescription

total

number

Total energy consumed in Watt-hours

by_minute

array of type number

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

object

Information about the temperature

PropertyTypeDescription

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, undervoltage, (shown if at least one error is present)

Webhook Events​

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

MQTT Control​

Since version 0.14.0

  • Shelly will subscribe to the following topics, accepting commands:

    • <topic_prefix>/command/switch:<id>

  • Shelly publishes on:

    • <topic_prefix>/status/switch:<id> - topic where the result of the status_update command is published. The command can be sent either on the common device topic or the component specific topic. This topic is already used for existing status notifications, if enabled.
    • <topic_prefix>/error/switch:<id> - error message is published if switch command receives incorrect parameters or results in an error.

  • Accepted commands are:

    • status_update - causes status of the corresponding component to be published on its <topic_prefix>/status/switch:<id> topic.
    • on[,number] - turns the switch on, optional toggle_after parameter.
    • off[,number] - turns the switch off, optional toggle_after parameter.
    • toggle - toggles the switch.
note

<topic_prefix> is a custom prefix if set or defaults to <device_id>

Examples​

Switch.Set example​

http://192.168.33.1/rpc/Switch.Set?id=0&on=true

Response

{
  "was_on": false
}

Switch.Toggle example​

http://192.168.33.1/rpc/Switch.Toggle?id=0

Response

{
  "was_on": false
}

Switch.SetConfig example​

http://192.168.33.1/rpc/Switch.SetConfig?id=0&config={"name":"Switch0"}

Response

{
  "restart_required": false
}

Switch.GetConfig example​

http://192.168.33.1/rpc/Switch.GetConfig?id=0

Response

{
  "id": 0,
  "name": "Switchdsds",
  "in_mode": "follow",
  "initial_state": "match_input",
  "auto_on": false,
  "auto_on_delay": 60,
  "auto_off": false,
  "auto_off_delay": 60,
  "autorecover_voltage_errors": false,
  "power_limit": 4480,
  "voltage_limit": 280,
  "undervoltage_limit": 0,
  "current_limit": 16
}

Switch.GetStatus example​

http://192.168.33.1/rpc/Switch.GetStatus?id=0

Response

{
  "id": 0,
  "source": "WS_in",
  "output": false,
  "apower": 0,
  "voltage": 225.9,
  "current": 0,
  "aenergy": {
    "total": 11.679,
    "by_minute": [
      0,
      0,
      0
    ],
    "minute_ts": 1654511972
  },
  "temperature": {
    "tC": 53.3,
    "tF": 127.9
  }
}

HTTP Endpoint example​

Example:

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

Example:

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

Request status over MQTT example​

Subscription
export MQTT_SERVER="broker.hivemq.com"
export MQTT_PORT=1883
export SHELLY_ID="shellyplus1-a8032abe54dc" # The <shelly-id> of your device
mosquitto_sub -h ${MQTT_SERVER} -p ${MQTT_PORT} -t ${SHELLY_ID}/status/switch:0
Send command
export MQTT_SERVER="broker.hivemq.com"
export MQTT_PORT=1883
export SHELLY_ID="shellyplus1-a8032abe54dc" # The <shelly-id> of your device
mosquitto_pub -h ${MQTT_SERVER} -p ${MQTT_PORT} -t ${SHELLY_ID}/command/switch:0 -m status_update
Result
{
  "id": 0,
  "source": "init",
  "output": false,
  "temperature": {
    "tC": 46.4,
    "tF": 115.6
  }
}

Turn switch on with toggle_after over MQTT example​

Turn switch on with toggle_after 10 seconds
export MQTT_SERVER="broker.hivemq.com"
export MQTT_PORT=1883
export SHELLY_ID="shellyplus1-a8032abe54dc" # The <shelly-id> of your device
mosquitto_pub -h ${MQTT_SERVER} -p ${MQTT_PORT} -t ${SHELLY_ID}/command -m on,10