NAV Navbar
HTTP

Shelly Family Overview

These pages describe the HTTP API exposed by the Shelly family of devices.

Devices in the Shelly family are IoT nodes connected to the Internet over WiFi. All devices support a common set of configuration parameters, some share common features. Apart from these, each device extends the common HTTP endpoints with a set of device-specific settings and behavior.

WiFi Modes

Shelly devices can operate as either WiFi Access Point (AP mode) or Client Mode (STA). The factory default is AP mode with SSID shelly<MODEL>-XXXXXXXXXXXX with no authentication enabled.

Initially, devices come preprogrammed in Access Point mode with no password set. To be able to connect to Allterco's cloud service, synchronize time, etc. the device has to be configured to connect to an existing, Internet-connected WiFi infrastructure.

Connecting the device to an existing WiFi infrastructure can be done:

Control of these parameters via HTTP is possible via the /settings/sta and /settings/ap endpoints.

HTTP Server

All devices run a local HTTP server on port 80. It serves as a simple web page which allows the user to setup basic parameters. While in AP WiFi mode, the web page can be accessed at:

http://192.168.33.1/

The web interface makes use of the HTTP endpoints described in this document. HTTP authentication is disabled by default.

mDNS Discovery

Shelly devices announce a HTTP service on port 80 via mDNS. Hostname is always in the form of shelly<model>-XXXXXXXXXXXX.

SNTP Time Sync

Shelly devices do not have a built-in real time clock but will automatically synchronize their clock when in WiFi Client mode and there is connection to the Internet. Once the time is synchronized devices can execute commands triggered by user-defined weekly schedule or based on sunrise and sunset times. Geolocation data used for sun events is obtained automatically from the public IP address of the device. However, if this fails, tzautodetect can be disabled and the timezone and geolocation data (for sunrise and sunset calculation) can be set manually.

Cloud

Shelly devices can report their settings and state to an Internet connected cloud service. The cloud service can modify the settings and change the device state. All communication is over SSL. This service allows device monitoring and control over the Internet using the accompanying mobile applications.

CoIoT

Shelly devices implement a CoAP-based protocol for monitoring and control which we call CoIoT. Documentation:

Based on Mongoose-OS

Shelly devices are built on top of, and along with Mongoose-OS. Mongoose provides an integrated framework for secure sockets, over-the-air updates, application storage, common device housekeeping tasks and more, that are making the reliability and security of the Shelly portfolio possible.

Feedback

If you find issues with this documentation or have other questions or comments about Shelly devices, please email developers@shelly.cloud

Common HTTP API

This section documents the HTTP API implemented by all Shelly devices, which defines their common traits:

For every Shelly device, one should consult this section, along with the chapter dedicated to the Shelly model in question.

HTTP dialect

All properly formed requests return a JSON-encoded payload with an application/json MIME type. The meaning of values is described as Attributes for each documented resource.

Each resource may also accept a list of Parameters which should be supplied either as query-string in the URL or as application/x-www-form-urlencoded POST payload.

Error responses carry a 4xx HTTP response code and a text/plain response body, usually with an informative message for the type of error which occurred.

All resources except for /shelly will require Basic HTTP authentication when it is enabled via /settings/login.

The HTTP method used for performing any of the requests below is intentionally ignored. Most endpoints will always return their specific json payload and perform actions if query parameters are specified.

Boolean parameters can be given as 1, y, Y, t, T or case-insensitive true for true, any other value will be interpreted as false.

/shelly

GET /shelly

{
    "type": "SHSW-21",
    "mac": "5ECF7F1632E8",
    "auth": true,
    "fw": "20161223-111304/master@2bc16496",
    "num_outputs": 1
}

Provides basic information about the device. It does not require HTTP authentication, even if authentication is enabled globally. This endpoint can be used in conjunction with mDNS for device discovery and identification. It accepts no parameters.

Attributes

Attribute Type Description
type string Shelly model identifier
mac string MAC address of the device
auth bool Whether HTTP requests require authentication
fw string Current firmware version
num_outputs number Number of outputs for actuators

/settings

GET /settings

{
    "device": {
        "type": "SHSW-21",
        "mac": "16324CAABBCC",
    },
    "wifi_ap": {
        "enabled": false,
        "ssid": "shellyMODEL-16324CAABBCC",
        "key": ""
    },
    "wifi_sta": {
        "enabled": true,
        "ssid": "Castle",
        "ipv4_method": "dhcp",
    "ip": null,
    "gw": null,
    "mask": null,
    "dns": null
    },
    "login": {
        "enabled": false,
        "unprotected": false,
        "username": "admin",
        "password": "admin"
    },
    "name": "shellyMODEL-16324CAABBCC",
    "fw": "20170427-114337/master@79dbb397",
    "cloud": {
        "enabled": true,
        "connected": true
    },
    "timezone": "Europe/Sofia",
    "lat": 42.1234,
    "lng": 24.5678,
    "tzautodetect": true,
    "time": "16:40",
    "coiot_execute_enable": false
}

Represents device configuration: all devices support a set of common features which are described here. Look at the device-specific /settings endpoint to see how each device extends it.

To configure timezone and location (for sunrise/sunset calculation) manually, set tzautodetect to false, so that custom values for lat, lng and timezone take effect. For a list of supported timezones, please fetch

https://api.shelly.cloud/timezone/tzlist

Parameters

Parameter Type Description
reset bool Will perform a factory reset of the device
mqtt_enable bool Enable connecting to a MQTT broker
mqtt_server string MQTT broker IP address and port, ex. 10.0.0.1:1883
mqtt_user string MQTT username, leave empty to disable authentication
mqtt_pass string MQTT password
mqtt_reconnect_timeout_max int maximum interval for reconnect attempts
mqtt_reconnect_timeout_min int minimum interval for reconnect attempts
mqtt_clean_session bool MQTT clean session flag
mqtt_keep_alive int MQTT keep alive period in seconds
mqtt_max_qos int Max value of QOS for MQTT packets
mqtt_retain bool MQTT retain flag
coiot_execute_enable bool Whether to allow execution of CoIoT commands
tzautodetect bool Set this to false if you want to set custom geolocation (lat and lng) or custom timezone.
lat number Degrees latitude in decimal format, South is negative
lng number Degrees longitude in decimal format, between -180 and 180
timezone string Timezone identifier.

Attributes

Attribute Type Description
device.type string Device model identifier
device.mac string MAC address of the device in hexadecimal
wifi_ap hash WiFi access point configuration, see /settings/ap for details
wifi_sta hash WiFi client configuration. See /settings/sta for details
login hash credentials used for HTTP Basic authentication for the REST interface. If enabled is true clients must include an Authorization: Basic ... HTTP header with valid credentials when performing TP requests.
name string unique name of the device.
fw string current FW version
cloud.enabled bool cloud enabled flag
time string current time in HH:MM format if synced
mqtt hash contains MQTT-related settings

/settings/ap

GET /settings/ap

{
    "enabled": false,
    "ssid": "shellyswitch-163248",
    "key": ""
}

Provides information about the current WiFi AP configuration and allows changes. The returned document is identical to the one returned by /settings in the wifi_ap key. Shelly devices do not allow the SSID for AP WiFi mode to be changed.

Parameters are applied immediately. Setting the enabled flag for AP mode to 1 will automatically disable STA mode.

Parameters

Parameter Type Description
enabled bool Set to 1 to return the device to AP WiFi mode
key string WiFi password required for association with the device's AP

Attributes

Attribute Type Description
enabled bool whether AP mode is active.
ssid string SSID created by the device's AP
key string WiFi password required for association with the device's AP

/settings/sta

GET /settings/sta

{
    "enabled": true,
    "ssid": "Castle",
    "key": "BigSecretKeyForCastle",
    "ipv4_method": "dhcp",
    "ip": null,
    "gw": null,
    "mask": null,
    "dns": null
}

Provides information about the current WiFi Client mode configuration and allows changes. The returned document is identical to the one returned by /settings in the wifi_sta key.

Parameters are applied immediately. Setting the enabled flag for STA mode to 1 will automatically disable AP mode.

Parameters

Parameter Type Description
enabled bool Set to 1 to make STA the current WiFi mode
ssid string The WiFi SSID to associate with
key string The password required for associating to the given WiFi SSID
ipv4 method string "dhcp" or "static"
ip string local ip addres if ipv4 method is "static"
gw string local Geateway ip address if ipv4 method is "static"
mask string Mask address if ipv4 method is "static"
dns string DNS address if ipv4 method is "static"

Attributes

Attribute Type Description
enabled bool whether STA mode is active.
ssid string SSID of STA the device will associate with
key string WiFi password for the selected SSID
ipv4 method` string
ip string local ip addres if ipv4 method is "static"
gw string local Geateway ip address if ipv4 method is "static"
mask string Mask address if ipv4 method is "static"
dns string DNS address if ipv4 method is "static"

/settings/login

GET /settings/login

{
    "enabled": false,
    "unprotected": false,
    "username": "admin",
    "password": "admin"
}
GET /settings/login?enabled=1&username=boss&password=thebigone

{
    "enabled": true,
    "unprotected": false,
    "username": "boss",
    "password": "thebigone"
}

HTTP authentication configuration: enabled flag, credentials. unprotected is initially false and is used by the user interface to show a warning when auth is disabled. If the user wants to keep using Shelly without a password, they can set unprotected to hide the warning.

Parameters

Parameter Type Description
username string length between 1 and 50
password string length between 1 and 50
enabled bool whether to require HTTP authentication
unprotected bool whether the user is aware of the risks

Attributes

Attributes are identical with the parameters and their semantics.

/settings/cloud

GET /settings/cloud?enabled=1

{
    "enabled": true
}

Can set the "connect to cloud" flag. When set, Shelly will keep a secure connection to Allterco's servers and allow monitoring and control from anywhere.

/status

GET /status

{
    "wifi_sta": {
        "connected": true,
        "ssid": "Castle",
        "ip": "192.168.2.65"
    },
    "cloud": {
        "enabled": false,
        "connected": false
    },
    "time": "17:42",
    "has_update": true,
    "ram_total": 50648,
    "ram_free": 38376,
    "uptime": 39
}

Encapsulates current device status information. While settings can generally be modified and don't react to the environment, this endpoint provides information about transient data which may change due to external conditions.

Attributes

Parameter Type Description
wifi_sta hash Current status of the WiFi connection
wifi_sta.ip string IP address assigned to this device by the WiFi router
cloud hash current cloud connection status
mqtt.connected bool MQTT connection, when MQTT is enabled
time string The current hour and minutes, in HH:MM format
has_update bool If a newer firmware version is available
ram_total, ram_free number Total and available amount of system memory in bytes
uptime number seconds elapsed since boot

/reboot

GET /reboot

{}

When requested will cause a reboot of the device.

MQTT Support

Shelly devices include basic MQTT support since version 1.3.0. While many device settings are only available over HTTP, MQTT allows for real-time monitoring and eases integration with external systems.

To configure a Shelly device for MQTT, set the connection parameters via the Shelly App, web interface or HTTP /settings endpoint. Note, that enabling MQTT will disable Allterco's cloud service. Shelly devices do not yet support secure MQTT connections.

Mandatory settings are:

In case authentication is required, mqtt_user and mqtt_pass must also be set. In certain scenarios, it may be desirable to set mqtt_qos and mqtt_retain to prevent loss of data.

All Shelly devices will publish their current state on MQTT connect, and also identify themselves on shellies/announce with a json payload. Currently, it only contains the device id, but this is sufficient to identify the device model and its topics. Additionally, devices support two "commands" on shellies/command:

Each Shelly model exports it's own set of topics for monitoring and control, all structured under /shellies/<shellymodel>-<deviceid>. Last testament can be configured with the mqtt_will_topic and mqtt_will_message parameters. On MQTT connect, devices will report their current status. Please see the respective product docs for details on the protocol:

Shelly1

Shelly1

Shelly1: Overview

Shelly1 is the smallest intelligent Wi-Fi power switch on the market today. Visit the product page for detailed description and User Manual:

https://shelly.cloud/shelly1/

Commands to turn the relay on or off can come from:

Factory Reset

If the web interface of the device cannot be accessed, settings can be brought back to default by switching ON and OFF 5 times the physical switch connected to the device, within the first minute after a reboot or power-on.

About the device

Shelly1 supports the ON and OFF commands which control the coil of a 16A 250VAC relay.

Shelly1 also supports auto_on and auto_off settings -- these are timers in seconds which will turn the device ON or OFF when it has been turned OFF or ON respectively, from either a physical button or network command. Thus, the user can set a limit for how long the1 can be ON or OFF.

Upon power-on, output is initialized using one of 4 available strategies:

To control Shelly1, use these resources:

Shelly1: MQTT

Shelly1 uses the following topics:

Shelly1: /settings

The device doesn't extend this endpoint, common parameters apply.

Shelly1: /settings/relay/{index}

GET /settings/relay/0

{
    "name": null,
    "ison": false,
    "has_timer": false,
    "default_state": "off",
    "btn_type": "toggle",
    "auto_on": 0,
    "auto_off": 0,
}

The returned document here is identical to the data returned in /settings for the single output channel in the relays array. The channel index exists to preserve API compatibility with multi-channel Shelly devices. Attributes in the response match the set of accepted parameters.

Parameters

Parameter Type Description
reset any Submitting a non-empty value will reset settings for the output to factory defaults.
default_state string Accepted values: off, on, last, switch
btn_type string Accepted values: momentary, toggle, edge
auto_on number Automatic flip back timer, seconds. Will engage after turning Shelly1 OFF.
auto_off number Automatic flip back timer, seconds. Will engage after turning Shelly1 ON.

Shelly1: /status

/status is extended with information about the current state of the output channel as well as the presence of a pending timer.

GET /status

{
    "relays": [{
        "ison": true,
        "has_timer": false,
    }]
}
Attribute Type Description
relays array of hashes Contains the current state of the relay output channels. See /relay/0 for description of attributes

Shelly1: /relay/{index}

Shows current status of the output channel and accepts commands for controlling the channel.

Parameters

Parameter Type Description
turn string Accepted values are on and off. This will turn ON/OFF the respective output channel when request is sent .
timer number A one-shot flip-back timer in seconds.

Attributes

Attribute Type Description
ison boolean Whether the channel is turned ON or OFF
has_timer boolean Whether a timer is currently armed for this channel

Shelly1: flash/debug, power options

Shelly1 comes with a programming/debug header which can be used to flash alternative firmwares on the device. It has an ESP8266 inside, with a 2MB flash chip. A USB-to-UART adapter is needed as well as a reliable 3.3V with at least 350 mA drive capability. The following diagram shows the device pinout and power source voltage selection jumper:

Shelly1 flash/debug and power

To boot the ESP8266 for serial programming, tie GPIO0 to GND before powering up. Flashing can be done with esptool. There is a very wide range of platforms, languages and libraries for the ESP8266 chip which can be used to integrate the device with virtually any system. A few examples are:

Shelly1: wiring in the field

When using DC power supply, observe polarity as indicated:

Shelly1 power and output

Note, that internally, GND from the flash/debug connector is connected to the AC/L terminal. SW input can be floating or connected to AC/L. Do not connect this terminal to any other net.

Shelly1: Mongoose-OS Application

A multi-purpose ready-for-use application based on Mongoose-OS can easily be flashed on the Shelly1 over the flash/debug connector. Mongoose-OS enables programming in C and JavaScript, with clean and rich APIs.

Please take a look at the official documentation of Mongoose-OS. They also have video tutorials, forum and developer chat.

Installation

To flash the universal Mongoose-OS firmware:

Once this is done, you can reboot the device in "normal" mode (leave GPIO0 disconnected) and use mos to configure and control the device. init.js can be edited to add your custom logic and event handlers. MQTT, WebSockets, HTTP and ordinary TCP and UDP sockets are supported. Mongoose also supports TLS out of the box.

Sample integration with Home Assistant over MQTT

Assuming you have a working Home Assistant installation with the mqtt component enabled.

Run mos and connect it to your device. You can do that over a number of channels:

Configure MQTT: set your broker address, credentials and enable it:

Enable MQTT for Shelly1

The module should connect to your dispatcher after a reboot. See here for additional options (qos, will topic, etc.)

The last step is adding a mqtt switch device to your HA setup:

switch:
  - platform: mqtt
    command_topic: "shelly1/shelly1_9F5CC9/commands"
    state_topic: "shelly1/shelly1_9F5CC9/state"
    payload_on: "on"
    payload_off: "off"

You should be able to control the Shelly1 relay from Home Assistant:

Shelly1 in Home Assistant

Shelly2

Shelly2: Overview

Shelly2 is a WiFi-enabled dual-channel relay with a common power meter. To find out more and download the User Manual, visit the product page

https://shelly.cloud/shelly2/

Shelly2 can operate in two distinct device modes: Relay and Roller Shutter. Devices are initially programmed to work in Relay Mode. The operating mode of Shelly2 can be set via the /settings endpoint. Commands to perform actions can come from:

Factory Reset

If the web interface of the device cannot be accessed, settings can be brought back to default by switching ON and OFF 5 times the physical switch connected to the device, within the first minute after a reboot or power-on.

Shelly2 in Relay Mode

In Relay mode, each of the two channels is controlled individually and supports the ON and OFF commands. In this mode, an overpower threshold can be enabled for each of the two channels, via the max_power parameter in /settings. If set to a value different than 0, the relay will automatically turn off if current power consumption exceeds:

Relay channels also support auto_on and auto_off settings -- these are timers in seconds which will turn ON or OFF the channel when it has been turned OFF or ON respectively, from either a physical switch or network command. Thus, the user can set a limit for how long the channel can be ON or OFF.

Upon power-on, outputs are initialized using one of 4 available strategies:

Physical input switches can be one of:

Note: Setting output state based on inputs on power on is not supported when inputs are configured as momentary or edge.

To control Shelly2 in Relay mode, use these resources:

Shelly2 in Roller Mode

In Roller mode the device can be used to control bi-directional motor, with optional obstacle detection and safety switch features. Commands are: Open, Close and Stop.

Shelly2 has a single logical Roller, but we index the HTTP resources to allow for future devices with more output channels and Roller-s.

When Shelly2 is in Roller mode, use:

Obstacle detection

In Roller mode, the integrated power meter of Shelly2 can be used to detect motor overload which usually means something obstructing the movement of the door or roller shutter. A set of parameters define the behavior of Shelly2 when such event occurs. These are:

Safety-switch input

While in Roller Mode and when inputs are configured as "one button", the second physical input can be used as a safety input -- it can be tied to an end-stop switch or user safety stop button. Its configuration parameters are:

Shelly2: MQTT

Shelly2 allows control and monitoring over MQTT for both relay and roller modes. Device mode, along with other parameters need to be configured using the mobile application or web interface.

MQTT in Relay mode

In relay mode, the following topics can be used to read and set output channels 0 and 1:

The device measures the total consumption on both channels, which can be seen on:

MQTT in Roller mode

When configured to operate in roller mode, MQTT topics used by Shelly2 are:

New in v1.4.0: roller mode position control. For this to work, the device must first be successfully calibrated, so that the time it takes for closing and opening are known.

Shelly2: /settings

GET /settings?mode=relay

{
    "name": "shellyswitch-163248",
    "mode": "relay",
    "max_power": 1840,
    "relays": [ ... ],
    "rollers": [ ... ],
    "meters": [{"power": 0, "is_valid": true}]
}

Shelly2 extends the common /settings endpoint with relay and roller-mode specific data, power consumption status and contains the settings for this device's Relays and Rollers. Both are indexed, to allow implementation of the same interface on devices with more output channels.

and also exposes /settings/relay/N and /settings/roller/M for setting the parameters.

Parameters

Parameter Type Description
mode string Accepted values are relay and roller
max_power number Overpower threshold in Watts

Attributes

Attribute Type Description
relays array of hashes See /settings/relay for explanation of values
rollers array of hashes See /settings/roller for explanation of values
meters array of hashes Contains the status of the integrated power meter.

meters attributes

Attribute Type Description
is_valid boolean Whether power metering self-checks OK
power number Current real AC power being drawn, in Watts

Shelly2: /settings/relay/{index}

GET /settings/relay/0

{
    "ison": false,
    "has_timer": false,
    "overpower": false,
    "default_state": "off",
    "btn_type": "toggle",
    "auto_on": 0,
    "auto_off": 0,
    "schedule": true,
    "schedule_on": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "schedule_off": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "sun": true,
    "sun_on_times": "0000000000000000000000000000",
    "sun_off_times": "0000000000000000000000000000"
}

The returned document here is identical to the data returned in /settings for the particular output channel in the relays array. The attributes match the set of accepted parameters.

Parameters

Parameter Type Description
reset any Submitting a non-empty value will reset settings for this relay output channel to factory defaults.
default_state string Accepted values: off, on, last, switch
btn_type string Accepted values: momentary, toggle, edge
auto_on number Automatic flip back timer, seconds. Will engage after turning the channel OFF.
auto_off number Automatic flip back timer, seconds. Will engage after turning the channel ON.

Shelly2: /settings/roller/{index}

GET /settings/roller/0

{
    "maxtime": 20,
    "default_state": "stop",
    "swap": false,
    "input_mode": "onebutton",
    "button_type": "toggle",
    "state": "stop",
    "power": 0,
    "is_valid": true,
    "safety_switch": false,
    "obstacle_mode": "disabled",
    "obstacle_action": "stop",
    "obstacle_power": 200,
    "obstacle_delay": 1,
    "safety_mode": "while_opening",
    "safety_action": "stop",
    "safety_allowed_on_trigger": "none"
}

The returned document here is identical to the data returned in /settings as a hash in the rollers. The attributes match the set of accepted parameters.

Parameters

Parameter Type Description
reset any Submitting a non-empty value will reset Roller settings to factory defaults
maxtime number The maximum time needed for the mechanism to completely open or close, seconds.
default_state string One of stop, open, close. This parameters determines the behavior on power-on.
swap boolean Whether to swap Open and Close directions
input_mode string One of openclose -- each input controls one direction of motion, onebutton -- a single button press cycles through states: open, stop, close, stop ...
btn_type string One of momentary or toggle.
obstacle_mode string One of disabled, while_opening, while_closing, while_moving.
obstacle_action string One of stop, reverse.
obstacle_power number Power threshold for triggering "obstacle" condition, Watts.
obstacle_delay number Number of seconds to wait after powering on the motor before obstacle detection is activated
safety_mode string One of disabled, while_opening, while_closing, while_moving
safety_action string One of stop, pause, reverse.
safety_allowed_on_trigger string Which commands are allowed while the safety switch is triggered: none, open, close, all.

Shelly2: /status

GET /status

"relays": [
{
    "ison": false,
    "has_timer": false,
    "overpower": false,
    "is_valid": true
},
{
    "ison": false,
    "has_timer": false,
    "overpower": false,
    "is_valid": true
}
],
"rollers": [
    {
    "state": "stop",
    "power": 0,
    "is_valid": true,
    "safety_switch": false,
    "stop_reason": "normal",
    "last_direction": "stop"
    }
],
"meters": [
    {
        "power": 0,
        "is_valid": true,
    }
],

Shelly2 adds information about the current state of the output channels, the logical "roller" device and power metering.

Attribute Type Description
relays array of hashes Contains the current state of the relay output channels. See /relay/N for description of attributes
rollers array of hashes Contains the current state of the logical "roller" device. See /roller/N for description of attributes
meters array of hashes Current status of the power meters

Shelly2: /relay/{index}

Shows current status of each output channel and accepts commands for controlling the channel. This is usable only when device mode is set to relay via /settings.

Parameters

Parameter Type Description
turn string Accepted values are on and off. This will turn ON/OFF the respective output channel when request is sent .
timer number A one-shot flip-back timer in seconds.

Attributes

Attribute Type Description
ison boolean Whether the channel is turned ON or OFF
has_timer boolean Whether a timer is currently armed for this channel
overpower boolean Whether an overpower condition turned the channel OFF
is_valid boolean Whether the associated power meter is functioning correctly

Shelly2: /roller/{index}

Controls the logical "roller" device and retrieves its current status. When go=to_pos, roller_pos must also be specified and valid.

Parameters

Parameter Type Description
go string Accepted values are open, close, stop and to_pos
roller_pos number Desired position in percent
duration number If specified, the motor will move for this period in seconds. If missing, the value of maxtime in /settings/roller/N will be used.

Attributes

Attribute Type Description
state bool One of stop, open, close
power number Current power consumption in Watts
is_valid bool If the power meter functions properly
safety_switch bool Whether the safety input is currently triggered
stop_reason bool Last cause for stopping: normal, safety_switch, obstacle
last_direction bool Last direction of motion, open or close

Shelly2: /roller/{index}/calibrate

New in v1.4.0: Requesting this endpoint will trigger a calibration procedure to be performed. Shelly2 will measure the time it takes to open and close the mechanical device under control. Once this completes successfully, Shelly2 will be able to not only open and close, but target a specific position between the two.

Shelly4Pro

4Pro: Overview

Shelly4pro is a 4-channel DIN mountable WiFi connected relay with power meters for each channel. With Shelly4Pro you can control 4 electrical circuits, 10 amperes each (4 x 2300 W). You can also monitor the real time consumption. Visit the product page for more information and to download the User Manual:

https://shelly.cloud/shelly-4-pro/

The operating mode of 4Pro can be set via the /settings endpoint. Commands to perform actions can come from:

Factory Reset

If the web interface of the device cannot be accessed, settings can be brought back to defaults by pressing and holding the device button for more then 10 seconds or until the led light start flashing fast.

About the device

Each of the four channels is controlled individually and supports the ON and OFF commands. In this mode, an overpower threshold can be enabled for each of the channels, via the max_power parameter in /settings. If set to a value different than 0, the relay will automatically turn off if current power consumption exceeds:

Relay channels also support auto_on and auto_off settings -- these are timers in seconds which will turn ON or OFF the channel when it has been turned OFF or ON respectively, from either a physical switch or network command. Thus, the user can set a limit for how long the channel can be ON or OFF.

Upon power-on, outputs are initialized using one of these strategies:

Physical input switches can be one of:

Note: Setting output state based on inputs on power on is not supported when inputs are configured as momentary or edge.

To control Shelly4Pro in Relay mode, use these resources:

/settings/relay/{index} to configure the behavior of each channel /relay/{index} to control and monitor the channel

4Pro: MQTT

Shelly 4Pro uses the following topics for each channel. <i> ranges from 0 to 3:

4Pro: /settings

GET /settings

{
    "name": "shellyplug-163248",
    "max_power": 3500,
    "relays": [ ... ],
    "meters": [{"power": 0, "is_valid": true}]
}

Shelly4pro extends the common /settings endpoint with relay, power consumption status and contains the settings for this device's Relays . They are indexed, to allow implementation of the same interface on devices with more output channels.

Shelly4pro also exposes /settings/relay/N for setting the channel parameters.

Parameters

Parameter Type Description
max_power number Overpower threshold in Watts

Attributes

Attribute Type Description
relays array of hashes See /settings/relay for explanation of values
meters array of hashes Contains the status of the integrated power meter.

meters attributes

Attribute Type Description
is_valid boolean Whether power metering self-checks OK
power number Current real AC power being drawn, in Watts

4Pro: /settings/relay/{index}

GET /settings/relay/0

{
    "ison": false,
    "has_timer": false,
    "overpower": false,
    "default_state": "off",
    "btn_type": "toggle",
    "auto_on": 0,
    "auto_off": 0,
    "schedule": true,
    "schedule_on": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "schedule_off": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "sun": true,
    "sun_on_times": "0000000000000000000000000000",
    "sun_off_times": "0000000000000000000000000000"
}

The returned document here is identical to the data returned in /settings for the particular output channel in the relays array. The attributes match the set of accepted parameters.

Parameters

Parameter Type Description
reset any Submitting a non-empty value will reset settings for this relay output channel to factory defaults.
default_state string Accepted values: off, on, last, switch
btn_type string Accepted values: momentary, toggle, edge
auto_on number Automatic flip back timer, seconds. Will engage after turning the channel OFF.
auto_off number Automatic flip back timer, seconds. Will engage after turning the channel ON.

4Pro: /status

GET /status

"relays": [
{
    "ison": false,
    "has_timer": false,
    "overpower": false,
    "is_valid": true
},
"meters": [
    {
        "power": 0,
        "is_valid": true,
    }
],

4Pro adds information about the current state of the output channels, the logical "roller" device and power metering.

Attribute Type Description
relays array of hashes Contains the current state of the relay output channels. See [/relay/N where N is 0-3/](#4Pro-relay-index for description of attributes
meters array of hashes Current status of the power meters

4Pro: /relay/{index}

Shows current status of each output channel and accepts commands for controlling the channel via /settings.

Parameters

Parameter Type Description
turn string Accepted values are on and off. This will turn ON/OFF the respective output channel when request is sent .
timer number A one-shot flip-back timer in seconds.

Attributes

Attribute Type Description
ison boolean Whether the channel is turned ON or OFF
has_timer boolean Whether a timer is currently armed for this channel
overpower boolean Whether an overpower condition turned the channel OFF
is_valid boolean Whether the associated power meter is functioning correctly

Shelly Plug

Shelly Plug: Overview

Shelly Plug is the most intelligent Wi-Fi power outlet on the market today. Visit the product page for a detailed features overview and User Manual:

https://shelly.cloud/shelly-plug/

The settings of Shelly Plug can be change via the /settings endpoint. Commands to perform actions can come from:

Factory Reset

If the web interface of the device cannot be accessed, settings can be brought back to defaults by holding the button for more then 10 seconds or until the red LED starts flashing rapidly.

About the device

Shelly Plug supports the ON and OFF commands. An overpower threshold can be enabled, via the max_power parameter in /settings. If set to a value different than 0, the relay will automatically turn off if current power consumption exceeds:

Shelly Plug also support auto_on and auto_off settings -- these are timers in seconds which will turn ON or OFF the plug when it has been turned OFF or ON respectively, from either a physical button or network command. Thus, the user can set a limit for how long the plug can be ON or OFF.

Upon power-on, output are initialized using one of 4 available strategies:

To control Shelly Plug, use these resources:

Shelly Plug: MQTT

Shelly Plug uses:

Shelly Plug: /settings

Shelly Switch extends the common /settings endpoint for power consumption status and contains the settings for this device.

GET /settings

{
    "name": "shellyplug-163248",
    "max_power": 3500,
    "relays": [ ... ],
    "meters": [{"power": 0, "is_valid": true}]
}

Shelly Plug adds max_power to the list of parameters which can be set via the common /settings endpoint:

Parameters

Parameter Type Description
max_power number Overpower threshold in Watts

Attributes

Attribute Type Description
relays array of hashes See /settings/relay for explanation of values
meters array of hashes Contains the status of the integrated power meter.
max_power number Overpower threshold in Watts

meters attributes

Attribute Type Description
is_valid boolean Whether power metering self-checks OK
power number Current real AC power being drawn, in Watts

Shelly Plug: /status

GET /status

{
    "relays": [{
        "ison": true,
        "has_timer": false,
        "overpower": false}],
    "meters": [{
        "power": 0.01,
        "is_valid": true}]}
    ]
}

Shelly Plug adds information about the current state of the plug (ON or OFF) and instantaneous power reading in Watts.

Attribute Type Description
relays array of hashes Contains the current state of the relay output channels. See /relay/0 for description of attributes
meters array of hashes Current status of the power meter, see

Shelly Plug: /settings/relay/{index}

GET /settings/relay/0

{
    "ison": false,
    "has_timer": false,
    "overpower": false,
    "default_state": "off",
    "btn_type": "toggle",
    "auto_on": 0,
    "auto_off": 0
}

The returned document here is identical to the data returned in /settings for the single output channel in the relays array. The channel index exists to preserve API compatibility with multi-channel Shelly devices. Attributes in the response match the set of accepted parameters.

Parameters

Parameter Type Description
reset any Submitting a non-empty value will reset settings for the plug output to factory defaults.
default_state string Accepted values: off, on, last, switch
btn_type string Accepted values: momentary, toggle, edge
auto_on number Automatic flip back timer, seconds. Will engage after turning the plug OFF.
auto_off number Automatic flip back timer, seconds. Will engage after turning the plug ON.

Shelly Plug: /status

The returned document here is identical to the data returned in /settings. The attributes match the set of accepted parameters.

GET /status

"relays": [
{
    "ison": false,
    "has_timer": false,
    "overpower": false,
    "is_valid": true
},
"meters": [
    {
        "power": 0,
        "is_valid": true,
    }
],

Shelly Plug adds information about the current state of it's output and power metering.

Attribute Type Description
relays array of hashes Contains the current state of the relay output channels. See /relay/0 for description of attributes
meters array of hashes Current status of the power meters

Shelly Plug: /relay/{index}

Shows current status of the output channel and accepts commands for controlling the channel.

Parameters

Parameter Type Description
turn string Accepted values are on and off. This will turn ON/OFF the respective output channel when request is sent .
timer number A one-shot flip-back timer in seconds.

Attributes

Attribute Type Description
ison boolean Whether the channel is turned ON or OFF
has_timer boolean Whether a timer is currently armed for this channel
overpower boolean Whether an overpower condition turned the channel OFF

Shelly Bulb

Bulb: Overview

Shelly Bulb is a WiFi-enabled E27 bulb with Red, Green, Blue and White LEDs. Visit the product page for detailed information and User Manual:

https://shelly.cloud/shelly-bulb/

A number of exposed endpoints allow configuring all aspects of Shelly Bulb:

Factory Reset

Factory reset can be performed by:

Performing factory reset will revert all settings to their initial values.

Bulb: Device Modes

Shelly Color can operate in two distinct device modes:

In Color mode, each output channel: Red, Green, Blue and White is individually controllable.

In Warm/Cold White mode the device accepts color temperature and brightness and adjusts power output of all channels to produce the desired white light.

Shelly Bulb can also play a set of pre-defined effects, specified by a numerical index:

Bulb: MQTT

Shelly Bulb allows the simple on and off commands and status, as well as setting the color, brightness and effects using a json payload.

To control the bulb with a simple on-off switch functionality, use:

For controlling other paramters of the LED channels publish to

shellies/shellybulb-<deviceid>/color/0/set

Device expects a JSON payload on this topic, with the following sample contents:

{
    "ison": false,   /* bool, can be set with on and off commands */
    "mode": "color", /* "color" or "white" */
    "red": 0,        /* red brightness, 0..255, applies in mode="color" */
    "green": 0,      /* green brightness, 0..255, applies in mode="color" */
    "blue": 255,     /* blue brightness, 0..255, applies in mode="color" */
    "white": 0,      /* white brightness, 0..255, applies in mode="color" */
    "gain": 100,     /* gain for all channels, 0..100, applies in mode="color" */
    "temp": 4750,       /* color temperature in K, 3000..6500, applies in mode="white" */
    "brightness": 100,  /* brightness, 0..100, applies in mode="white" */
    "effect": 0 /* applies an effect when set */
}

mode controls which set of parameters are used:

effect is specified as an integer, see description above

An identical JSON payload will be published by Shelly Bulb on

shellies/shellybulb-<deviceid>/color/0/status

Subscribers can use this to obtain the latest device state.

Bulb: /settings


GET /settings

{
    "mode": "white",
    "lights": [
        {
            "ison": false,
            "red": 255,
            "green": 127,
            "blue": 0,
            "white": 0,
            "gain": 100,
            "temp": 5406,
            "brightness": 90,
            "default_state": "last",
            "auto_on": 0,
            "auto_off": 0,
        }
    ]
}

The mode of operation of Shelly Bulb can be set here, along with other standard settings.

Parameters

Parameter Type Description
mode string Accepted values are white and color

Attributes

Attribute Type Description
mode string currently configure mode
lights array of hashes output channel settings. Bulb only supports a single channel, indexed as 0. See /settings/light/0 for more details.

bulb: /settings/light/0

Parameters

Parameter Type Description
reset string Any non-zero-length value will reset light settings to default
effect int Applies an effect, see description
default_state string Sets default power-on state, one of on, off or last
auto_on number Sets a default timer to turn the bulb ON after every OFF command in seconds
auto_off number Sets a default timer to turn the bulb OFF after every ON command in seconds

Attributes

Attribute Type Description
ison bool Whether the bulb is on or off
red number red brightness, 0..255, applies in mode="color"
green number green brightness, 0..255, applies in mode="color"
blue number blue brightness, 0..255, applies in mode="color"
white number white brightness, 0..255, applies in mode="color"
gain number gain for all channels, 0..100, applies in mode="color"
temp number color temperature in K, 3000..6500, applies in mode="white"
brightness number brightness, 0..100, applies in mode="white"
effect number Currently applied effect, description
default_state string one of on, off or last
auto_on number see above
auto_off number see above

bulb: /light/0

This endpoint allows sending commands to the bulb to control it.

Parameter Type Description
mode string Accepted values are white and color
timer number Automatic flip-back timer in seconds, used in combination with turn
turn string Command to turn on or off
red number red brightness, 0..255, applies in mode="color"
green number green brightness, 0..255, applies in mode="color"
blue number blue brightness, 0..255, applies in mode="color"
white number white brightness, 0..255, applies in mode="color"
gain number gain for all channels, 0..100, applies in mode="color"
temp number color temperature in K, 3000..6500, applies in mode="white"
brightness number brightness, 0..100, applies in mode="white"

Shelly Sense

Sense: Overview

Shelly Sense is the most advanced Wi-Fi Room sensor and universal IR control on the market today. Shelly Sense has:

Shelly Sense can operate up to 10 days on the battery. Visit the product page for a detailed features overview and User Manual:

https://shelly.cloud/shelly-sense/

The settings of Shelly Sense can be changed via the /settings endpoint. Commands to perform actions can come from:

Factory Reset

If the web interface of the device cannot be accessed, settings can be brought back to defaults by pressing and holding the setup button for more then 10 seconds or until the red led light start flashing fast.
Factory reset will remove all added IR codes and schedules from the device.

Shelly Sense: MQTT

Shelly Sense sends values from its internal sensors on the following topics:

Shelly Sense: /settings

The settings for Shelly Sense are:

GET /settings/
{
    "device": {
    "type": "SHSEN-1",
    "mac": "508CB14A448A",
    "hostname": "shellysense-4A448A"
    },
{
    "sensors": {
    "motion_duration": 20,
    "motion_led": true,
},
    {
    "tmp": {
    "units": "C"
    },
    },
}

Attributes

Attribute Type Description
pir_motion_duration_time Boolean Set duration time in seconds for motion flag after motion detection.
motion_led Boolean Set if LED light should indicate motion detected.
temperature_units text Set temperature units C for Celsius and F for Fahrenheit
schedule Boolean Activate/Deactivate schedule settings.
schedule_rules string Add or Remove weekly schedule.

The returned document here is identical to the data returned in /settings

Parameters

Parameter Type Description
pir_motion_duration_time number Duration time in seconds for motion flag after motion detection
motion_led Boolean Whether LED light should indicate motion detected 1 or 0.
temperature_units string Temperature units C for Celsius and F for Fahrenheit
schedule Boolean Whether schedule settings are active/inactive. Value is 1 or 0.
schedule_rules String Add or Remove weekly schedule. See /settings/?schedule.

Shelly Sense Schedule: /settings/?schedule

Shelly Sense can send IR codes automatically by predefined weekly schedule. Before adding schedule rules, IR codes must be stored in the device (See /ir/add and /ir/list.


 GET /settings/?schedule={value}

Parameters

Parameter Type Description
schedule Boolean Activate/Deactivate schedules.
schedule_rules text Set schedules.

Shelly Sense Schedule rules: /settings/?schedule_rules

Schedule rules is a string that contains:

Value Range Description
ET 24h Executing time in format HHMM
WD 0123456 Days of week witch schedule will be executed starts from Monday.
ID ID of the stored pronto code (ID)

/settings/?schedule_rules

These variables should be concatenated with -. If you want to add more schedules then use , between each of them. The final string should look like like:

schedule_rules=ET-WD-ID,ET-WD-ID

The schedule is set as whole set. Every time you want to add a new rule, you should append old ones too.

Examples

Description Example
Set Shedule http://localIP/settings/?schedule_rules=1734-012-ir0_17_1_0_0_25,1222-0123456-ir1_41_pwr

Shelly Sense: /status

GET /status
{
    "device": {
    "type": "SHSEN-1",
    "mac": "508CB1715350",
    "hostname": "shellysense-715350"
    },
{
    "motion": false,
    "charger": false,
},
{
    "tmp": {
    "value": 9.55536,
},
{
    "hum": {
    "value": 85.548308,
    },
{
    "lux": {
    "value": 3.896104,
},
{
    "bat": {
    "value": 100
},
}

Shelly Sense status command give information about all device and sensor status.

Attributes

Attribute Type Description
motion Boolean Value for motion detection
charger Boolean Value for charging status
tmp number Temperature
hum number Humidity
lux number Brightness
bat number Battery level

Shelly Sense: /ir

To preset IR codes in your Shelly Sens you should use Shelly cloud application from iOS or Android store. These apps provide access to huge database for TV, Hi-Fi sets and air conditioners. Any IR code can be added to Shelly Sens in "pronto" format so you can command your exotic IR operated devices.

Parameters

Parameter Type Description
list text List for stored infrared devices in Shelly Sense
add text Add new device into Shelly Sense. For more information see /ir/add
remove text Remove IR code or device stored in Shelly Sense. See /ir/remove
emit text Send IR code from Shelly Sens. See /ir/emit

Shelly Sense: /ir/list

Here is a sample list of stored IR codes in Shelly Sense for TV and Air-conditioning.

 GET /ir/list
[
 [
        "1_41_pwr",
        "TV Philips(41) - Power"
],
 ]
        "0_17_1_0_0_25",
        ":;8<0 (17) - Turn on, Mode: AUTO, Fan: AUTO, Temp: 25"
],
]

Attributes

Attribute Type Description
ID text ID of the stored IR code into Shelly Sense.
name text Short description or name of the stored IR code.

Shelly Sense: /ir/add

You can add base64 encoded pronto code into Shelly Sense and send it by ID.

 GET /ir/add?

Parameters

Parameter Type Description
ID text ID of the IR code.
name text Short description or name of the stored IR code.
pronto text IR pronto code base64. To convert HEX pronto code to Shelly Sens supported format use this tool

Shelly Sense: /ir/remove

Shelly Sense API support few ways to remove codes:


 GET /ir/remove?

Parameters

Parameter Type Description
ID text ID of the stored IR code into Shelly Sense.
all text remove all pronto codes from Shelly Sense
prefix text remove pronto codes by prefix.

Examples

Description Example
Remove by ID http://localIP/ir/remove?id=1_91_chdwn
Remove all http://localIP/ir/remove?all=1
Remove by prefix: http://localIP/ir/remove?prefix=1_91
Add IR http://localIP/ir/add?id=1_91_chdwn&name=tv(91)%20-%20Channel%20Down&pronto=AAAAbQAiAAIBV...

Shelly Sense: /ir/emit

You can send IR code from Shelly Sens using:


 GET /ir/emit

Parameters

Parameter Type Description
type text Type of IR code you want to send: stored or pronto
ID text Send stored pronto code by ID when type = stored
pronto text Send Base64 encoded pronto code when type = pronto
pronto_hex text Send HEX encoded pronto code when type = pronto

Shelly H&T

H&T: Overview

Shelly H&T is a WiFi humidity and temperature sensor with long battery life:

https://shelly.cloud/shelly-humidity-and-temperature/

Shelly H&T normally keeps its WiFi controller shut down and only wakes up when an update is due. This can either be a periodic wakeup or sensor reading change greater than the configured threshold. On these events, the device wakes up to report updated sensor values and shuts back down immediately afterwards.

When the user button is pressed, the device switches to a "setup" mode -- it will remain turned on for 3 minutes, allowing configuration over the web interface. Another short button press will put it back to sleep.

Factory Reset

To restore Shelly H&T to its factory settings, turn the device on if needed, then press and hold the user button until the LED stops blinking rapidly.

H&T: MQTT

When configured for MQTT Shelly H&T sends values from its internal sensors on the following topics:

H&T: /settings

GET /settings

{
    "sensors": {
        "temperature_threshold": 1,
        "temperature_unit": "C",
        "humidity_threshold": 5
    },
    "sleep_mode": {
        "period": 3,
        "unit": "h"
    }
}

Shelly HT accepts the following extra parameters on it's /settings endpoint:

Parameters

Parameter Type Description
temperature_units string Either 'C' or 'F'
temperature_threshold number Temperature delta (in configured degree units) which triggers an update
humidity_threshold number RH delta in % which triggers an update
sleep_mode_period number Periodic update period in hours, between 1 and 24

The same settings are contained in the response payload, under sensors and sleep_mode.

H&T: /status

GET /status

{
    "tmp": {
        "value": 22,
        "units": "C",
        "tC": 22,
        "tF": 71.6,
        "is_valid": true
    },
    "hum": {
        "value": 57,
        "is_valid": true
    },
    "bat": {
        "value": 71,
        "voltage": 2.73
    },
    "act_reasons": [
        "button"
    ],
...
}

Sensor values are repoted on the /status endpoint, along with info on the reason the device is awake.

Attributes

Parameter Type Description
tmp.value number Temperature in configured unites
tmp.units number 'C' or 'F'
tmp.tC number temperature in deg C
tmp.tF number temperature in deg F
tmp.is_valid bool whether the internal sensor is operating properly
hum.value number relative humidity in %
bat.value number estimated remaining battery capacity in %
bat.voltage number battery voltage
act_reasons array of strings list of reasons which woke up the device

Shelly Smoke

Smoke: Overview

Shelly Smoke is a WiFi temperature sensor and fire detector with long battery life:

https://shelly.cloud/shelly-smoke/

Shelly Smoke normally keeps its WiFi controller shut down and only goes online when an update is due. This can either be a periodic wakeup, low battery condition, temperature reading change greater than the configured threshold or, hopefully not, a fire. On these events, the device wakes up to report updated sensor values and shuts back down. In the case of a fire alarm, the sensor will keep alarming until the smoke clears up or it's battery dies.

When the user button is pressed, the device switches to a "setup" mode -- it will remain turned on for 3 minutes, allowing configuration over the web interface. Another short button press will put it back to sleep.

Factory Reset

To restore Shelly Smoke to its factory settings, turn the device on if needed, then press and hold the user button until the LED stops blinking rapidly.

Smoke: MQTT

When configured for MQTT Shelly Smoke sends values from its internal sensors on the following topics:

Smoke: /settings

GET /settings

{
    "sensors": {
        "temperature_threshold": 1,
        "temperature_unit": "C",
    },
    "sleep_mode": {
        "period": 3,
        "unit": "h"
    }
}

Shelly Smoke accepts the following extra parameters on it's /settings endpoint:

Parameters

Parameter Type Description
temperature_units string Either 'C' or 'F'
temperature_threshold number Temperature delta (in configured degree units) which triggers an update
sleep_mode_period number Periodic update period in hours, between 1 and 24

The same settings are contained in the response payload, under sensors and sleep_mode.

Smoke: /status

GET /status

{
    "tmp": {
        "value": 22,
        "units": "C",
        "tC": 22,
        "tF": 71.6,
        "is_valid": true
    },
    "bat": {
        "value": 71,
        "voltage": 2.73
    },
    "act_reasons": [
        "button"
    ],
...
}

Sensor values are repoted on the /status endpoint, along with info on the reason the device is awake.

Attributes

Parameter Type Description
tmp.value number Temperature in configured unites
tmp.units number 'C' or 'F'
tmp.tC number temperature in deg C
tmp.tF number temperature in deg F
tmp.is_valid bool whether the internal sensor is operating properly
bat.value number estimated remaining battery capacity in %
bat.voltage number battery voltage
act_reasons array of strings list of reasons which woke up the device, may contain either of: battery, button, periodic, poweron, sensor, alarm.