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. The default NTP server is time.google.com, but a custom one can also be configured.

Local actions

Since v1.7.0 Shelly devices support "local" action URLs. This allows devices to invoke actions not only on other devices, but on themselves as well. To execute a local action, the action URL should be set with a prefix http://localhost/.

For example, to make relay 1 turn on when relay 0 is turned on:

deviceIP/settings/relay/0?out_on_url=http://localhost/relay/1?turn=on

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

Changelog

Revision Date Description
v1.7.0 26.5.2020 * [New devices] Add new devices Shelly RGBW2 Color / Shelly Shelly RGBW2 White (split from former Shelly RGBW2), Shelly Gas, Shelly i3 and Shelly Button1
* [All devices] Add attribute fw_mode to /settings endpoint (only applicable for devices with changeable firmware mode)
* [All devices] Add attribute ram_lwm to /status endpoint
* [All devices] Remove attribute password from /settings/login endpoint
* [All devices] Add support for local action URLs via prefix http://localhost/
* [All devices] Fix empty user agent string when calling action URLs
* [All devices] Make gateway optional when setting static IP via /settings/sta endpoint
* [Shelly1, Shelly1PM, Shelly2, Shelly2.5, Shelly Plug, Shelly PlugS, Shelly EM, Shelly 3EM] Add attributes timer_started and timer_duration to /relay/{index} endpoint
* [Shelly Bulb, Shelly Vintage, Shelly Duo, Shelly Dimmer/SL] Add attributes timer_started and timer_duration to /light/0 endpoint
* [Shelly1, Shelly1PM, Shelly2, Shelly2.5, Shelly Dimmer/SL] Add attributes event and event_cnt to inputs.{index} in /status endpoint
* [Shelly1, Shelly1PM, Shelly2, Shelly2.5, Shelly Dimmer/SL] Publish new MQTT topic shellies/<model>-<deviceid>/input_event/<i>
* [Shelly1, Shelly1PM, Shelly2, Shelly2.5] Invoke shortpush_url and longpush_url only if button is configured as momentary, momentary_on_release or detached
* [Shelly Vintage, Shelly Duo] Add parameter timer to /light/0 endpoint
* [Shelly Dimmer/SL] Add new endpoint /settings/warm_up
* [Shelly Smoke] Add attribute/parameter temperature_offset to /settings endpoint
* [Shelly1, Shelly1PM] Convert ext_temperature and ext_humidity in /settings endpoint from arrays to objects
* [Shelly1, Shelly1PM] Add attribute hwID to ext_temperature.{index} and ext_humidity.{index} in /status endpoint
* [Shelly1, Shelly1PM] Publish new MQTT topics shellies/<model>-<deviceid>/ext_temperatures, shellies/<model>-<deviceid>/ext_temperatures_f and shellies/<model>-<deviceid>/ext_humidities
* [Shelly Door/Window] Remove parameter closed from /calibrate endpoint, parameter opened now handles requests for both opened and closed position calibrations
* [Shelly Door/Window] Add parameter clear to /calibrate endpoint
* [Shelly Door/Window] Add attributes/parameters close_url and vibration_url to /settings endpoint
* [Shelly Door/Window] Change type of attribute accel.vibration in /status endpoint from bool to number, add new value -1
* [Shelly Door/Window] Add attribute accel.vibration_time to /status endpoint
* [Shelly EM, Shelly 3EM] Remove attribute/parameter max_power from /settings endpoint
* [Shelly EM, Shelly 3EM] Remove attribute/parameter max_power from /settings/relay/0 endpoint
* [Shelly EM, Shelly 3EM] Add attributes/parameters over_power_url, over_power_url_threshold, under_power_url, under_power_url_threshold and max_power to /settings/emeter/{index} endpoint
* [Shelly EM, Shelly 3EM] Add parameter reset_totals to /emeter/{index} endpoint
* [Shelly EM, Shelly 3EM] Add new endpoint /reset_data
* [Shelly EM, Shelly 3EM] Subscribe to new MQTT topic shellies/<model>-<deviceid>/emeter/<i>/command with message reset_totals
* [Shelly EM, Shelly 3EM] Subscribe to MQTT topic shellies/<model>-<deviceid>/command with message reset_data
* [Shelly 3EM] Remove attribute/parameter ctraf_type from /settings/emeter/{index} endpoint
v1.6.0 5.3.2020 * [New devices] Add new devices Shelly Vintage, Shelly Duo, Shelly Door/Window, Shelly 3EM
* [All devices] Add attribute longid to /shelly endpoint
* [All devices] Add attribute coiot.update_period and parameter coiot_update_period to /settings endpoint
* [All devices] Add attribute sntp.enabled to /settings endpoint
* [All devices] Add attributes/parameters tz_utc_offset, tz_dst and tz_dst_auto to /settings endpoint
* [All devices] Add attribute unixtime to /status and /settings endpoints
* [All devices] Add attribute/parameter discoverable to /settings endpoint
* [All devices] Introduce per-device MQTT announce topic shellies/<shellymodel>-<deviceid>/announce
* [Shelly1, Shelly1PM, Shelly2, Shelly2.5, Shelly RGBW2, Shelly Dimmer] Add attribute/parameter factory_reset_from_switch to /settings endpoint
* [Shelly1, Shelly1PM, Shelly2, Shelly2.5, Shelly4Pro, Shelly EM, Shelly Plug, Shelly PlugS] Add attribute timer_remaining to /relay/{index} endpoint
* [Shelly Bulb] Add experimental attribute timer_remaining to /light/{index} endpoint
* [Shelly Dimmer/SL] Add attribute has_timer and experimental attribute timer_remaining to /light/0 endpoint
* [Shelly1, Shelly1PM, Shelly2, Shelly2.5] Add attribute/parameter longpush_time to /settings endpoint
* [Shelly1, Shelly1PM, Shelly2, Shelly2.5] Add new value momentary_on_release for attribute/parameter btn_type in settings/relay/{index} endpoint
* [Shelly2, Shelly2.5] Hide relays or rollers arrays of hashes from /status endpoint depending on current device mode
* [Shelly2, Shelly2.5] Add attribute array inputs to /status endpoint
* [Shelly1, Shelly1PM] If add-on attached (DS1820/DHT22) Add attribute ext_sensors.temperature_unit to /status and /settings endpoints; add parameter ext_sensors_temperature_unit to /settings endpoint
* [Shelly1, Shelly1PM] If add-on attached (DS1820/DHT22) Add attribute hash ext_temperature and ext_humidity to /status endpoint, add same as array of hashes to /settings endpoints
* [Shelly1, Shelly1PM] If add-on attached (DS1820/DHT22) Add new endpoints /settings/ext_temperature/{index} and /settings/ext_humidity/0 to configure external temperature/humidity thresholds and actions
* [Shelly1, Shelly1PM] If add-on attached (DS1820/DHT22) Publish new MQTT topics shellies/<shellymodel>-<deviceid>/ext_temperature/<i>, shellies/<shellymodel>-<deviceid>/ext_temperature_f/<i> and shellies/<shellymodel>-<deviceid>/ext_humidity/0
* [Shelly1PM] Add atrribute/parameter power_correction to /settings endpoint
* [Shelly2] Remove voltage and current from power measurement info
* [Shelly2.5] Add attributes temperature, overtemperature and tmp attributes to /status endpoint
* [Shelly RGBW2] Add value toggle for parameter turn in subscribed MQTT topic shellies/shellyrgbw2-<deviceid>/white/<n>/set
* [Shelly Dimmer/SL] Add new value action for attribute/parameter btn_type in /settings/light/0 endpoint
* [Shelly Dimmer/SL] Add attribute/parameter btn_debounce to /settings/light/0 endpoint
* [Shelly Dimmer/SL] Add attribute/parameter min_brightness to /settings endpoint
* [Shelly Dimmer/SL] Add attributes/parameters btn1_longpush_url, btn1_shortpush_url, btn2_longpush_url, btn2_shortpush_url to /settings/light/0 endpoint
* [Shelly Dimmer/SL] Add value toggle for parameter turn in /light/0 endpoint
* [Shelly Dimmer/SL] Publish new MQTT topics shellies/shellydimmer-<deviceid>/longpush/<i> and shellies/shellydimmer-<deviceid>/light/0/energy
* [Shelly EM] Publish new MQTT topics shellies/shellyem-<deviceid>/emeter/<i>/total and shellies/shellyem-<deviceid>/emeter/<i>/total_returned
* [Shelly Flood] Add attributes/parameters flood_detected_url and flood_gone_url to /settings endpoint
v1.5.10 4.2.2020 * [All devices] Allow setting empty NTP server, this disables timekeeping on the device
v1.5.6 26.11.2019 * [All devices] Remove CoIoT actions
* [All devices] MQTT ID is now user-configurable (mqtt_id)
* [All devices] Removed parameters mqtt_will_topic and mqtt_will_message from /settings endpoint
* [Shelly1, Shelly1PM, Shelly2, Shelly2.5] Add longpush and shortpush actions (longpush_url, shortpush_url)
* [Shelly2] Add voltage and current in power measurement info
* [Shelly Dimmer/SL] Add /settings/night_mode endpoint, add fade_rate command, add calibrate_cancel command, add output activated/deactivated actions (out_on_url, out_off_url)
* [Shelly Dimmer/SL] Add Night Mode

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"
    "longid": 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
longid number 1 if the device identifies itself with its full MAC address; 0 if only the last 3 bytes are used

/settings

GET /settings

{
    "device": {
        "type": "SHSW-21",
        "mac": "16324CAABBCC",
        "hostname": "shelly1-B929CC"
    },
    "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
    },
    "wifi_sta1" : { ... },
    "mqtt": {
        "enable": false,
        "server": "192.168.33.3:1883",
        "user": "",
        "id": "shelly1-B929CC",
        "reconnect_timeout_max": 60,
        "reconnect_timeout_min": 2,
        "clean_session": true,
        "keep_alive": 60,
        "max_qos": 0,
        "retain": false,
        "update_period": 30
    },
    "coiot": {
        "update_period": 15
    },
    "sntp": {
        "server": "time.google.com",
        "enabled": true
    },
    "login": {
        "enabled": false,
        "unprotected": false,
        "username": "admin"
    },
    "pin_code": "123456",
    "name": "shellyMODEL-16324CAABBCC",
    "fw": "20170427-114337/master@79dbb397",
    "discoverable": true,
    "build_info": {
        "build_id": "20191112-140800",
        "build_timestamp": "2019-11-12T14:08:00Z",
        "build_version": "1.0"
    },
    "cloud": {
        "enabled": true,
        "connected": true
    },
    "timezone": "Europe/Sofia",
    "lat": 42.1234,
    "lng": 24.5678,
    "tzautodetect": true,
    "tz_utc_offset": 0,
    "tz_dst": false,
    "tz_dst_auto": true,
    "time": "16:40",
    "unixtime": 0
}

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

Attributes

Attribute Type Description
device.type string Device model identifier
device.mac string MAC address of the device in hexadecimal
device.hostname string Device hostname
wifi_ap hash WiFi access point configuration, see /settings/ap for details
wifi_sta hash WiFi client configuration. See /settings/sta for details
wifi_sta1 hash Alternative WiFi client configuration. See /settings/sta for details
mqtt hash Contains MQTT-related settings
coiot.update_period number Update period of CoIoT messages, s
sntp.server string Time server host
sntp.enabled bool SNTP enabled flag
login hash Credentials used for HTTP Basic authentication for the REST interface. If login.enabled is true clients must include an Authorization: Basic ... HTTP header with valid credentials when performing TP requests
pin_code string Current generated PIN code
name string Unique name of the device
fw string Current FW version
discoverable bool Device discoverable (i.e. visible) flag
build_info hash Build info
cloud.enabled bool Cloud enabled flag
cloud.connected bool Cloud connected flag
timezone string Timezone identifier
lat number Degrees latitude in decimal format, South is negative
lng number Degrees longitude in decimal fomrat, between -180° and 180°
tzautodetect bool Timezone auto-detect enabled
tz_utc_offset number UTC offset
tz_dst bool Daylight saving time
tz_dst_auto bool Auto update daylight saving time
time string Current time in HH:MM format if synced
unixtime number Unix timestamp if synced; 0 otherwise
fw_mode string Current firmware mode, only for devices where this is changeable (e.g. Shelly RGBW2 Color/RGBW2 White)

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_clean_session bool MQTT clean session flag
mqtt_retain bool MQTT retain flag
mqtt_user string MQTT username, leave empty to disable authentication
mqtt_pass string MQTT password
mqtt_id string MQTT ID -- by default this has the form <shellymodel>-<deviceid> e.g. shelly1-B929CC. If you wish to use custom a MQTT ID, it is recommended that it doesn't exceed 25 characters.
mqtt_reconnect_timeout_max number Maximum interval for reconnect attempts
mqtt_reconnect_timeout_min number Minimum interval for reconnect attempts
mqtt_keep_alive number MQTT keep alive period in seconds
mqtt_update_period number Periodic update in seconds, 0 to disable
mqtt_max_qos number Max value of QOS for MQTT packets
coiot_update_period number Update period of CoIoT messages 15..65535s
sntp_server string Time server host to be used instead of the default time.google.com. An empty value disables timekeeping and requires reboot to apply.
name string User-configurable device name
discoverable bool Set whether device should be discoverable (i.e. visible)
timezone string Timezone identifier
lat number Degrees latitude in decimal format, South is negative
lng number Degrees longitude in decimal format, -180°..180°
tzautodetect bool Set this to false if you want to set custom geolocation (lat and lng) or custom timezone.
tz_utc_offset number UTC offset
tz_dst number Daylight saving time 0/1
tz_dst_auto number Auto update daylight saving time 0/1

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

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

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

/settings/sta

GET /settings/sta

{
    "enabled": true,
    "ssid": "Castle",
    "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.

An identical resource is available at /settings/sta1. This allows for devices to have a second WiFi STA configuration for fallback, and will cycle between the two when the one currently selected becomes unavailable.

Attributes

Attribute Type Description
enabled bool Whether STA mode is active
ssid string SSID of STA the device will associate with
ipv4_method string dhcp or static
ip string Local IP address if ipv4_method is static
gw string Local gateway IP address if ipv4_method is static
mask string Mask if ipv4_method is static
dns string DNS address if ipv4_method is static

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 address if ipv4_method is static
netmask string Mask if ipv4_method is static
gateway string Local gateway IP address if ipv4_method is static
dns string DNS address if ipv4_method is static

Sinve v.1.7.0, setting a static IP only requires netmask to be specified, gateway can be left empty.

Please note that cloud must be disabled manually before setting a static IP config without a gateway and enabled manually when switching back to dhcp config (/settings/cloud).

/settings/login

GET /settings/login

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

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

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.

Attributes

Attribute Type Description
enabled bool Whether HTTP authentication is required
unprotected bool Whether the user is aware of the risks
username string Username

In order to prevent security issues (e.g. when forwarding logs to 3rd parties), since v1.7.0 the password attribute for login protected devices is no longer returned on the API call.

Parameters

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

/settings/cloud

GET /settings/cloud?enabled=1

{
    "enabled": true
}

Can set the enabled (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",
        "rssi": -54
    },
    "cloud": {
        "enabled": false,
        "connected": false
    },
    "mqtt": {
        "connected": false
    },
    "time": "17:42",
    "unixtime": 0,
    "serial": 1,
    "has_update": true,
    "mac": "98F4ABB929CC",
    "update": {
        "status": "pending",
        "has_update": true,
        "new_version": "20200320-123430/v1.6.2@514044b4",
        "old_version": "20200320-123430/v1.6.2@514044b4"
    },
    "ram_total": 50648,
    "ram_free": 38376,
    "ram_lwm": 32968,
    "fs_size": 233681,
    "fs_free": 174194,
    "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

Attribute 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 status, when MQTT is enabled
time string The current hour and minutes, in HH:MM format
unixtime number Unix timestamp if synced; 0 otherwise
serial number Cloud serial number
update hash Info whether newer firmware version is available, see /ota for more details
ram_total number Total amount of system memory in bytes
ram_free number Available amount of system memory in bytes
ram_lwm number Minimal watermark of the system free memory in bytes
fs_size number Total amount of the file system in bytes
fs_free number Available amount of the file system in bytes
uptime number Seconds elapsed since boot

/reboot

GET /reboot

{}

When requested will cause a reboot of the device.

/ota

GET /ota

{
    "status": "idle",
    "has_update": false,
    "new_version": "20200320-123430/v1.6.2@514044b4",
    "old_version": "20200320-123430/v1.6.2@514044b4"
}

Provides information about the device firmware version and the ability to trigger an over-the-air update.

Attributes

Attribute Type Description
status string One of idle, pending, updating, unknown
has_update bool Whether an update is available
new_version string ID of new firmware version
old_version string ID of old (current) firmware version

Parameters

Parameter Type Description
url string Run firmware update from specified URL
update bool Run firmware update from default URL

/wifiscan

GET /wifiscan

{
    "wifiscan": "done",
    "results": [
        {
            "ssid": "some_network_1",
            "auth": 4,
            "channel": 1,
            "bssid": "XXXXXXXXXXXX",
            "rssi": -70
        },
        {
            "ssid": "some_network_2",
            "auth": 3,
            "channel": 6,
            "bssid": "YYYYYYYYYYYY",
            "rssi": -83
        }
    ]
}

Only available when in AP mode. Starts a WiFi scan and provides information about found networks.

Attributes

Attribute Type Description
wifiscan string One of failed, done, not AP mode, started, inprogress
results.{index}.ssid string SSID
results.{index}.auth number Auth mode: 0=open, 1=WEP, 2=WPA PSK, 3=WPA2 PSK, 4=WPA WPA2 PSK, 5=WPA2 ENTERPRISE
results.{index}.channel number Channel
results.{index}.bssid string BSSID in hex
results.{index}.rssi number Signal strength

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.

MQTT Configuration

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 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_max_qos and mqtt_retain to prevent loss of data.

By default, the device's MQTT ID is <shellymodel>-<deviceid>, for example shelly1-B929CC. The MQTT ID can be changed via the mqtt_id parameter in /settings. If you wish to use custom a MQTT ID, it is recommended that it doesn't exceed 25 characters.

Availability and announces

Since v1.4.3: on MQTT connect, Shellies will publish:

Device state is reported periodically, every 30 seconds by default. This can be changed by setting a new period for updates: mqtt_update_period under /settings. A value of 0 will disable periodic updates.

Default LWT topic and message are shellies/<shellymodel>-<deviceid>/online, false. If these are not set after a firmware upgrade -- perform a factory reset of the device.

Common MQTT commands

Shellies support a set of commands published on shellies/command or shellies/<shellymodel>-<deviceid>/command to address an individual device:

Each Shelly model exports it's own set of topics for monitoring and control, all structured under /shellies/<shellymodel>-<deviceid>. Please see the respective product docs for details on the protocol:

Shelly1 / Shelly1PM

Shelly1

Shelly1/PM: 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/products/shelly-1-smart-home-automation-relay/

Shelly1PM also includes energy metering:

https://shelly.cloud/shelly-1pm-wifi-smart-relay-home-automation/

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/1PM supports the ON and OFF commands which control the coil of a 16A 250VAC relay.

Shelly1/1PM 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 the device can be ON or OFF.

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

To control Shelly1/1PM, use these resources:

Shelly1/1PM: MQTT

Shelly1 and Shelly1PM uses the following topics, where <model> is either shelly1 or shelly1pm:

Shelly1PM adds:

If Shelly1/1PM is equipped with a temperature add-on, following topics are published as well:

For add-ons with DS1820 sensors:

For add-ons with a DHT22 sensor, in addition to the temperature topic above, a humidity topic is published too:

Shelly1/1PM also provide aggregated topics which contain data from all sensors along with their hardware IDs. They publish a JSON payload similar to the one in /status

{
    "0":{"hwID":"XXXXXXXX","tC":20.5},
    "1":{"hwID":"YYYYYYYY","tC":21.5},
    "2":{"hwID":"ZZZZZZZZ","tC":22.5}
}
{
    "0":{"hwID":"XXXXXXXX","tF":68.9},
    "1":{"hwID":"YYYYYYYY","tF":70.7},
    "2":{"hwID":"ZZZZZZZZ","tF":72.5}
}
{
    "0":{"hwID":"XXXXXXXX","hum":50}
}

Shelly1/1PM: /settings

GET /settings (Shelly1PM without temperature add-on)

{
    "factory_reset_from_switch": true,
    "max_power": 2000,
    "power_correction": 1,
    "mode": "relay",
    "longpush_time": 1000,
    "relays": [
        {
            "name": null,
            "ison": false,
            "has_timer": false,
            "default_state": "off",
            "btn_type": "toggle",
            "btn_reverse": 0,
            "auto_on": 0,
            "auto_off": 0,
            "power": 0,
            "btn_on_url": null,
            "btn_off_url": null,
            "out_on_url": null,
            "out_off_url": null,
            "longpush_url": null,
            "shortpush_url": null,
            "schedule": false,
            "schedule_rules": [],
            "max_power": 0
        }
    ],
    "meters": [
        {
            "power": 0,
            "is_valid": true,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        }
    ],
    "ext_sensors": {},
    "ext_temperature": {},
    "ext_humidity": {}
}

Common attributes apply for the /settings endpoint. Additionally:

Attributes

Attribute Type Description
factory_reset_from_switch bool Whether factory reset via 5-time flip of the input switch is enabled
max_power number Shelly1PM only Power threshold above which an overpower condition will be triggered
power_correction number Shelly1PM only Power correction coefficient
mode string Always relay
longpush_time number Duration to detect long push, ms
relays array of hashes Current relay settings, see /settings/relay/0
meters array of hashes Contains information about instantaneous power and cumulative energy counter, see /status
ext_sensors.temperature_unit string If add-on attached (DS1820/DHT22): External temperature unit C/F
ext_temperature hash If add-on attached (DS1820/DHT22): External temperature thresholds and actions, see /settings/ext_temperature/{index}
ext_humidity hash If add-on attached (DHT22 only): External humidity thresholds and actions, see /settings/ext_humidity/0

Common parameters apply for the /settings endpoint. Additionally:

Parameters

Parameter Type Description
factory_reset_from_switch bool Enable/disable factory reset via 5-time flip of the input switch
max_power number Shelly1PM only Power threshold above which an overpower condition will be triggered
power_correction number Shelly1PM only Power correction coefficient, [0.85-1.15]
mode string Only value relay is allowed for these devices
longpush_time number Set duration to detect long push, 1..5000ms
ext_sensors_temperature_unit string If add-on attached (DS1820/DHT22): Set external temperature unit C/F

Shelly1/1PM: /settings/relay/0

GET /settings/relay/0 (Shelly1PM)

{
    "name": null,
    "ison": false,
    "has_timer": false,
    "default_state": "off",
    "btn_type": "toggle",
    "btn_reverse": 0,
    "auto_on": 0,
    "auto_off": 0,
    "btn_on_url": null,
    "btn_off_url": null,
    "out_on_url": null,
    "out_off_url": null,
    "longpush_url": null,
    "shortpush_url": null,
    "schedule": false,
    "schedule_rules": [],
    "max_power": 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.

Attributes

Attribute Type Description
name string Relay name
ison bool Relay state
has_timer bool Whether there is an active timer
default_state string State on power-on, one of off, on, last, switch
btn_type string Button type, one of momentary, toggle, edge, detached, action, momentary_on_release
btn_reverse number Whether logical state of the input is inverted
auto_on number Automatic flip back timer, seconds
auto_off number Automatic flip back timer, seconds
power number Shelly1 only User power constant to display in meters when relay is on, see /settings/power/0
btn_on_url string URL to access when SW input is activated
btn_off_url string URL to access when SW input is deactivated
out_on_url string URL to access when output is activated
out_off_url string URL to access when output is deactivated
longpush_url string URL to access on longpush. Works only when button is configured as momentary, momentary_on_release or detached.
shortpush_url string URL to access on shortpush. Works only when button is configured as momentary, momentary_on_release or detached.
schedule bool Whether scheduling is enabled
schedule_rules array of strings Rules for schedule activation
max_power number Shelly1PM only power threshold above which an overpower condition will be triggered

Parameters

Parameter Type Description
reset any Submitting a non-empty value will reset settings for the output to factory defaults
name string Set relay name
default_state string Accepted values: off, on, last, switch
btn_type string Accepted values: momentary, toggle, edge, detached, action, momentary_on_release
btn_reverse bool Inverts the logical state of the input
auto_on number Automatic flip back timer, seconds. Will engage after turning Shelly1/1PM OFF
auto_off number Automatic flip back timer, seconds. Will engage after turning Shelly1/1PM ON
power number Shelly1 only Set user power constant to display in meters when relay is on, see /settings/power/0
btn_on_url string Set URL to access when SW input is activated
btn_off_url string Set URL to access when SW input is deactivated
out_on_url string Set URL to access when output is activated
out_off_url string Set URL to access when output is deactivated
longpush_url string Set URL to access on longpush. Works only when button is configured as momentary, momentary_on_release or detached.
shortpush_url string Set URL to access on shortpush. Works only when button is configured as momentary, momentary_on_release or detached.
schedule bool Enable schedule timer
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on
max_power number Shelly1PM only Set power threshold above which an overpower condition will be triggered

Shelly1: /settings/power/0

Parameters

Parameter Type Description
power number Shelly1 only Set user power constant to display in meters when relay is on, 0..4000W

Shelly1/1PM: /settings/ext_temperature/{index}

GET /settings/ext_temperature/0

{
    "overtemp_threshold_tC": 25.6,
    "overtemp_threshold_tF": 78.1,
    "undertemp_threshold_tC": 18.4,
    "undertemp_threshold_tF": 65.1,
    "overtemp_act": "disabled",
    "undertemp_act": "disabled"
}

Only applicable if add-on attached (DS1820/DHT22)

Parameters

Parameter Type Description
overtemp_threshold_tC number Temperature (in °C) over which to trigger overtemp_act
overtemp_threshold_tF number Temperature (in °F) over which to trigger overtemp_act
undertemp_threshold_tC number Temperature (in °C) under which to trigger undertemp_act
undertemp_threshold_tF number Temperature (in °F) under which to trigger undertemp_act
overtemp_act string Over-temperature action, one of disabled, relay_on, relay_off
undertemp_act string Under-temperature action, one of disabled, relay_on, relay_off

Temperature thresholds: The values of over-/under-temperature thresholds must be inside the ranges measurable by the DS1820/DHT22 sensors:

Shelly1/1PM: /settings/ext_humidity/0

GET /settings/ext_humidity/0

{
    "overhum_threshold": 85.4,
    "underhum_threshold": 10.0,
    "overhum_act": "disabled",
    "underhum_act": "disabled"
}

Only applicable if add-on attached (DHT22)

Parameters

Parameter Type Description
overhum_threshold number Humidity (in %) over which to trigger overhum_act
underhum_threshold number Humidity (in %) under which to trigger underhum_act
overhum_act string Over-humidity action, one of disabled, relay_on, relay_off
underhum_act string Under-humidity action, one of disabled, relay_on, relay_off

Humidity thresholds: The values of over-/under-humidity thresholds must be inside the range measurable by the DHT22 sensor: [0/100]%

Shelly1/1PM: /status

GET /status (Shelly1PM without temperature add-on)

{
    "relays": [
        {
            "ison": false,
            "has_timer": false,
            "timer_started": 0,
            "timer_duration": 0,
            "timer_remaining": 0,
            "overpower": false
        }
    ],
    "meters": [
        {
            "power": 0,
            "is_valid": true,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        }
    ],
    "inputs": [
        {
            "input": 0,
            "event": "S",
            "event_cnt": 2
        }
    ],
    "ext_sensors": {},
    "ext_temperature": {},
    "ext_humidity": {},
    "temperature": 29.35,
    "overtemperature": false,
    "tmp": {
        "tC": 29.35,
        "tF": 84.83,
        "is_valid": true
    }
}

/status is extended with information about the current state of the output channel as well as data from the power meter and external sensors (if available).

Attributes

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 Contains information about instantaneous power and cumulative energy counter, see description below
inputs array of hashes Current state of the inputs, see description below
ext_sensors.temperature_unit string If add-on attached (DS1820/DHT22): external temperature unit C/F
ext_temperature hash If add-on attached (DS1820/DHT22): external temperature data, see below for description of attributes
ext_humidity hash If add-on attached (DHT22 only): external humidity data, see below for description of attributes
temperature number Shelly1PM only internal device temperature in °C
overtemperature bool Shelly1PM only true when device has overheated
tmp.tC number Shelly1PM only Device temperature in °C
tmp.tF number Shelly1PM only Device temperature in °F
tmp.is_valid bool Shelly1PM only Whether device temperature is valid

meters attributes: Shelly1

Attribute Type Description
power number When relay is on, displays the value of the user power constant (see /settings/power/0); otherwise 0
is_valid bool Always true

meters attributes: Shelly1PM

Note: Energy counters (in the counters array and total) will reset to 0 after reboot.

Attribute Type Description
power number Current real AC power being drawn, in Watts
is_valid bool Whether power metering self-checks OK
timestamp number Unix timestamp of the last energy counter value
counters array of numbers Energy counter value for the last 3 round minutes in Watt-minute
total number Total energy consumed by the attached electrical appliance in Watt-minute

inputs attributes

Attribute Type Description
input number Current state of the input
event string Last input event, S=shortpush, L=longpush, ""=none/invalid
event_cnt number Event counter, uint16

input shows the current logical state of the input: 0=OFF and 1=ON. event provides a short string, designating the last detected input event (shortpush/longpush). event_cnt is incremented each time a new input event occurs. event_cnt is not stored in non-volatile memory.

Input events are only detected when btn_type is configured as momentary, momentary_on_release or detached.

ext_temperature.{index} attributes

Attributes

Attribute Type Description
hwID string Hardware ID of sensor {index}
tC number Temperature reading of sensor {index}, °C, 999 if invalid
tF number Temperature reading of sensor {index}, °F, 999 if invalid

ext_humidity.0 attributes

Attributes

Attribute Type Description
hwID string Hardware ID of sensor 0
hum number Humidity reading of sensor 0, percent, 999 if invalid

Shelly1/1PM: /relay/0

GET /relay/0 (Shelly1PM)

{
    "ison": false,
    "has_timer": false,
    "timer_started": 0,
    "timer_duration": 0,
    "timer_remaining": 0,
    "overpower": false
}

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

Attributes

Attribute Type Description
ison bool Whether the channel is turned ON or OFF
has_timer bool Whether a timer is currently armed for this channel
timer_started number Unix timestamp of timer start; 0 if timer inactive or time not synced
timer_duration number Timer duration, s
timer_remaining number experimental If there is an active timer, shows seconds until timer elapses; 0 otherwise
overpower bool Shelly1PM only if maximum allowed power was exceeded

Parameters

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

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 source 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: Internally, GND from the flash/debug connector is connected to the AC/L terminal. SW can be wired through a switch to either L or N and will detect transitions between open and closed state of the switch.

Shelly2

Shelly2: Overview

Shelly2 is a WiFi-enabled dual-channel relay with a common power meter.

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 a 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 onebutton, 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. In either mode, Shelly2 reports:

MQTT in Relay mode

Input events can be monitored on:

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:

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

Since 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

{
    "factory_reset_from_switch": true,
    "mode": "relay",
    "max_power": 1840,
    "longpush_time": 1000,
    "relays": [
        {
            "name": null,
            "ison": false,
            "has_timer": false,
            "overpower": false,
            "default_state": "switch",
            "btn_type": "toggle",
            "btn_reverse": 0,
            "auto_on": 0,
            "auto_off": 0,
            "btn_on_url": null,
            "btn_off_url": null,
            "out_on_url": null,
            "out_off_url": null,
            "longpush_url": null,
            "shortpush_url": null,
            "schedule": false,
            "schedule_rules": []
        },
        {
            "name": null,
            "ison": false,
            "has_timer": false,
            "overpower": false,
            "default_state": "switch",
            "btn_type": "toggle",
            "btn_reverse": 0,
            "auto_on": 0,
            "auto_off": 0,
            "btn_on_url": null,
            "btn_off_url": null,
            "out_on_url": null,
            "out_off_url": null,
            "longpush_url": null,
            "shortpush_url": null,
            "schedule": false,
            "schedule_rules": []
        }
    ],
    "rollers": [
        {
            "maxtime": 20,
            "maxtime_open": 20,
            "maxtime_close": 20,
            "default_state": "stop",
            "swap": false,
            "swap_inputs": false,
            "input_mode": "openclose",
            "button_type": "toggle",
            "btn_reverse": 0,
            "state": "stop",
            "power": 0,
            "is_valid": false,
            "safety_switch": false,
            "roller_open_url": null,
            "roller_close_url": null,
            "roller_stop_url": null,
            "schedule": false,
            "schedule_rules": [],
            "obstacle_mode": "disabled",
            "obstacle_action": "stop",
            "obstacle_power": 200,
            "obstacle_delay": 1,
            "safety_mode": "while_opening",
            "safety_action": "stop",
            "safety_allowed_on_trigger": "none",
            "off_power": 2,
            "positioning": true
        }
    ],
    "meters": [
        {
            "power": 0,
            "is_valid": true,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        }
    ]
}

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 and adds /settings/relay/{index} and /settings/roller/{index} for setting the parameters.

Attributes

Attribute Type Description
factory_reset_from_switch bool Whether factory reset via 5-time flip of an input switch is enabled
mode string relay or roller
max_power number Overpower threshold in Watts
longpush_time number Duration to detect long push, ms
relays array of hashes See /settings/relay/{index} for explanation of values
rollers array of hashes See /settings/roller/{index} for explanation of values
meters array of hashes Contains the status of the integrated power meter, see description below

meters attributes

Attributes

Attribute Type Description
power number Current real AC power being drawn, in Watts
is_valid bool Whether power metering self-checks OK
timestamp number Unix timestamp of the last energy counter value
counters array of numbers Energy counter value for the last 3 round minutes in Watt-minute
total number Total energy consumed by the attached electrical appliance in Watt-minute

Parameters

Parameter Type Description
factory_reset_from_switch bool Enable/disable factory reset via 5-time flip of an input switch
mode string Accepted values are relay and roller
max_power number Overpower threshold in Watts
longpush_time number Set duration to detect long push, 1..5000ms

Shelly2: /settings/relay/{index}

GET /settings/relay/0

{
    "name": null,
    "ison": false,
    "has_timer": false,
    "overpower": false,
    "default_state": "off",
    "btn_type": "toggle",
    "btn_reverse": 0,
    "auto_on": 0,
    "auto_off": 0,
    "btn_on_url": null,
    "btn_off_url": null,
    "out_on_url": null,
    "out_off_url": null,
    "longpush_url": null,
    "shortpush_url": null,
    "schedule": false,
    "schedule_rules": []
}

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.

Attributes

Attribute Type Description
name string Relay name
ison bool Channel state
has_timer bool Whether there is an active timer on the channel
overpower bool Whether an overpower condition has occurred
default_state string Default power-on state, one of off, on, last, switch
btn_type string Button type, one of momentary, toggle, edge, detached, action, cycle, momentary_on_release
btn_reverse number Whether input switch state is inverted
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
btn_on_url string URL to access when SW input is activated
btn_off_url string URL to access when SW input is deactivated
out_on_url string URL to access when output is activated
out_off_url string URL to access when output is deactivated
longpush_url string URL to access on longpush. Works only when button is configured as momentary, momentary_on_release or detached.
shortpush_url string URL to access on shortpush. Works only when button is configured as momentary, momentary_on_release or detached.
schedule bool Whether scheduling is enabled
schedule_rules array of strings Rules for schedule activation

Parameters

Parameter Type Description
reset any Submitting a non-empty value will reset settings for this relay output channel to factory defaults
name string Relay name
default_state string Accepted values: off, on, last, switch
btn_type string Accepted values: momentary, toggle, edge, detached, action, momentary_on_release
btn_reverse bool Inverts the logical state of the input
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
btn_on_url string URL to access when SW input is activated
btn_off_url string URL to access when SW input is deactivated
out_on_url string URL to access when output is activated
out_off_url string URL to access when output is deactivated
longpush_url string URL to access on longpush. Works only when button is configured as momentary, momentary_on_release or detached.
shortpush_url string URL to access on shortpush. Works only when button is configured as momentary, momentary_on_release or detached.
schedule bool Enable schedule timer
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on

Shelly2: /settings/roller/{index}

GET /settings/roller/0

{
    "maxtime": 20,
    "maxtime_open": 0,
    "maxtime_close": 0,
    "default_state": "stop",
    "swap": false,
    "swap_inputs": false,
    "input_mode": "onebutton",
    "button_type": "toggle",
    "btn_reverse": 0,
    "state": "stop",
    "power": 0,
    "is_valid": true,
    "safety_switch": false,
    "roller_open_url": null,
    "roller_close_url": null,
    "roller_stop_url": null,
    "schedule": false,
    "schedule_rules": [],
    "obstacle_mode": "disabled",
    "obstacle_action": "stop",
    "obstacle_power": 200,
    "obstacle_delay": 1,
    "safety_mode": "while_opening",
    "safety_action": "stop",
    "safety_allowed_on_trigger": "none",
    "off_power": 0,
    "positioning": false
}

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.

Attributes

Attribute Type Description
maxtime number The maximum time needed for the mechanism to completely open or close, seconds
maxtime_open number The maximum time needed for the mechanism to completely open, seconds
maxtime_close number The maximum time needed for the mechanism to completely close, seconds
default_state string One of stop, open, close. This parameters determines the behavior on power-on
swap bool Whether to swap OPEN and CLOSE directions
swap_inputs bool Whether inputs are swapped
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 ...
button_type string One of momentary, toggle, detached or action
btn_reverse number Whether to invert the state of input switch before interpreting it
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
roller_open_url string URL to access when roller is open
roller_close_url string URL to access when roller is closed
roller_stop_url string URL to access when roller is stopped
schedule bool Whether scheduling is enabled
schedule_rules array of strings Rules for schedule activation
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
off_power number Power value below which the roller is considered "stopped", i.e. the actuator is stopped by an end-stop switch
positioning bool Whether the device is calibrated for positioning control

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
maxtime_open number The maximum time needed for the mechanism to completely open, seconds
maxtime_close number The maximum time needed for the mechanism to completely close, seconds
default_state string One of stop, open, close. This parameter determines the behavior on power-on
swap bool Whether to swap OPEN and CLOSE directions
swap_inputs bool Whether to swap inputs
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, toggle, detached or action
btn_reverse bool Inverts the logical state of the input
roller_open_url string URL to access when roller is open
roller_close_url string URL to access when roller is closed
roller_stop_url string URL to access when roller is stopped
schedule bool Enable schedule timer
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on
obstacle_mode string One of disabled, while_opening, while_closing, while_moving
obstacle_action string One of stop, reverse.
off_power number Power value below which the roller is considered "stopped", i.e. the actuator is stopped by an end-stop switch
positioning bool Positioning enabled/disabled
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 (in relay mode)

"relays": [
    {
        "ison": false,
        "has_timer": false,
        "timer_started": 0,
        "timer_duration": 0,
        "timer_remaining": 0,
        "overpower": false,
        "is_valid": true
    },
    {
        "ison": false,
        "has_timer": false,
        "timer_started": 0,
        "timer_duration": 0,
        "timer_remaining": 0,
        "overpower": false,
        "is_valid": true
    }
],
"meters": [
    {
        "power": 0,
        "is_valid": true,
        "timestamp": 0,
        "counters": [1,2,3],
        "total": 4
    }
],
"inputs": [
    {
        "input": 0,
        "event": "S",
        "event_cnt": 2
    },
    {
        "input": 0,
        "event": "S",
        "event_cnt": 2
    }
]

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

Attributes

Attribute Type Description
relays array of hashes Displayed in Relay mode: Contains the current state of the relay output channels. See /relay/{index} for description of attributes
rollers array of hashes Displayed in Roller mode: Contains the current state of the logical roller device. See /roller/{index} for description of attributes
meters array of hashes Current status of the power meters, see description below
inputs array of hashes Current state of the inputs, see description below

inputs.{index} attributes

Attribute Type Description
input number Current state of the input
event string Last input event, S=shortpush, L=longpush, ""=none/invalid
event_cnt number Event counter, uint16

input shows the current logical state of the input: 0=OFF and 1=ON. event provides a short string, designating the last detected input event (shortpush/longpush). event_cnt is incremented each time a new input event occurs. event_cnt is not stored in non-volatile memory.

Input events are only detected in relay mode and only when btn_type is configured as momentary, momentary_on_release or detached.

Shelly2: /meter/{index}

GET /meter/0

{
    "power": 0,
    "is_valid": true,
    "timestamp": 0,
    "counters": [1,2,3],
    "total": 4
}

Attributes

Attribute Type Description
power number Current real AC power being drawn, in Watts
is_valid bool Whether power metering self-checks OK
timestamp number Unix timestamp of the last energy counter value
counters array of numbers Energy counter value for the last 3 round minutes in Watt-minute
total number Total energy consumed by the attached electrical appliance in Watt-minute

Shelly2: /relay/{index}

GET /relay/0

{
    "ison": true,
    "has_timer": false,
    "timer_started": 0,
    "timer_duration": 0,
    "timer_remaining": 0,
    "overpower": false,
    "is_valid": false
}

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.

Attributes

Attribute Type Description
ison bool Whether the channel is turned ON or OFF
has_timer bool Whether a timer is currently armed for this channel
timer_started number Unix timestamp of timer start; 0 if timer inactive or time not synced
timer_duration number Timer duration, s
timer_remaining number experimental If there is an active timer, shows seconds until timer elapses; 0 otherwise
overpower bool Whether an overpower condition turned the channel OFF
is_valid bool Whether the associated power meter is functioning correctly

Parameters

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

Shelly2: /roller/{index}

GET /roller/0

{
    "state": "stop",
    "power": 0,
    "is_valid": false,
    "safety_switch": false,
    "overtemperature" false,
    "stop_reason": "normal",
    "last_direction": "stop",
    "current_pos": 90,
    "calibrating": false,
    "positioning": true
}

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

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, overpower
last_direction bool Last direction of motion, open or close
current_pos number Current position in percent
calibrating bool Whether the device is currently performing a calibration procedure
positioning bool Whether the device is calibrated for positioning control

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/{index} will be used
offset number Offset 0 - 100%. Use offset or duration, not both

Shelly2: /roller/{index}/calibrate

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

Shelly2.5

Shelly25

Shelly2.5: Overview

Shelly2.5 is the improved successor to our popular Shelly2 model. The product page:

https://shelly.cloud/products/shelly-25-smart-home-automation-relay/

has all key features described, wiring diagram and User Manual.

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

Factory Reset

To perform a factory reset on a Shelly2.5 device, do so by pressing the user button or relay input switches:

Shelly2.5 in Relay Mode

In Relay mode, each of the two channels is controlled individually and supports the ON and OFF commands.

Relay channels 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:

To control Shelly2.5 in Relay mode, use these resources:

Shelly2.5 in Roller Mode

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

Shelly2.5 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.5 is in Roller mode, use:

Obstacle detection

In Roller mode, the integrated power meter of Shelly2.5 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.5 when such event occurs. These are:

Safety-switch input

While in Roller mode and when inputs are configured as onebutton, 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:

Position control

Shelly2.5 can be commanded to move the door (cover, sliding gate, etc.) to a relative position between fully open and completely closed. For this feature to work the device needs to perform a calibration procedure, measuring the time it takes for closing and opening. See /roller/{index}/calibrate

Shelly2.5: MQTT

Shelly2.5 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. In either mode, Shelly2.5 reports:

MQTT in Relay mode

Input events can be monitored on:

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

The device measures energy flow for each channel and reports these values on:

MQTT in Roller mode

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

For position control to work the device must be successfully calibrated, so that the time it takes for closing and opening are known.

Shelly2.5: /settings

GET /settings

{
    "factory_reset_from_switch": true,
    "mode": "relay",
    "max_power": 1840,
    "longpush_time": 1000,
    "relays": [
        {
            "name": null,
            "ison": false,
            "has_timer": false,
            "overpower": false,
            "default_state": "switch",
            "btn_type": "toggle",
            "btn_reverse": 0,
            "auto_on": 0,
            "auto_off": 0,
            "max_power": 0,
            "btn_on_url": null,
            "btn_off_url": null,
            "out_on_url": null,
            "out_off_url": null,
            "longpush_url": null,
            "shortpush_url": null,
            "schedule": false,
            "schedule_rules": []
        },
        {
            "name": null,
            "ison": false,
            "has_timer": false,
            "overpower": false,
            "default_state": "switch",
            "btn_type": "toggle",
            "btn_reverse": 0,
            "auto_on": 0,
            "auto_off": 0,
            "max_power": 0,
            "btn_on_url": null,
            "btn_off_url": null,
            "out_on_url": null,
            "out_off_url": null,
            "longpush_url": null,
            "shortpush_url": null,
            "schedule": false,
            "schedule_rules": []
        }
    ],
    "rollers": [
        {
            "maxtime": 20,
            "maxtime_open": 20,
            "maxtime_close": 20,
            "default_state": "stop",
            "swap": false,
            "swap_inputs": false,
            "input_mode": "openclose",
            "button_type": "toggle",
            "btn_reverse": 0,
            "state": "stop",
            "power": 0,
            "is_valid": false,
            "safety_switch": false,
            "roller_open_url": null,
            "roller_close_url": null,
            "roller_stop_url": null,
            "schedule": false,
            "schedule_rules": [],
            "obstacle_mode": "disabled",
            "obstacle_action": "stop",
            "obstacle_power": 200,
            "obstacle_delay": 1,
            "safety_mode": "while_opening",
            "safety_action": "stop",
            "safety_allowed_on_trigger": "none",
            "off_power": 2,
            "positioning": true
        }
    ],
    "meters": [
        {
            "power": 0,
            "is_valid": true,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        },
        {
            "power": 0,
            "is_valid": true,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        }
    ]
}

Shelly2.5 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 and adds /settings/relay/{index} and /settings/roller/{index} for setting the parameters.

Attributes

Attribute Type Description
factory_reset_from_switch bool Whether factory reset via 5-time flip of an input switch is enabled
mode string relay or roller
max_power number Overpower threshold in Watts for roller mode only. For relay mode the device keeps separate, per-channel configurations, see /settings/relay/{index}
longpush_time number Duration to detect long push, ms
relays array of hashes See /settings/relay/{index} for explanation of values
rollers array of hashes See /settings/roller/{index} for explanation of values
meters array of hashes Contains the status of the integrated power meters per channel, see description below

meters attributes

Attribute Type Description
power number Current real AC power being drawn, in Watts
is_valid bool Whether power metering self-checks OK
timestamp number Unix timestamp of the last energy counter value
counters array of numbers Energy counter value for the last 3 round minutes in Watt-minute
total number Total energy consumed by the attached electrical appliance in Watt-minute

The counters array contains the values of the energy counter per channel for the last 3 round minutes. The value will always increase, but will reset to zero on reboot or power cycle. When observing this value (over MQTT or HTTP polling) the observer should keep an accumulator locally, and add the new value whenever it goes backwards.

Parameters

Parameter Type Description
factory_reset_from_switch bool Enable/disable factory reset via 5-time flip of an input switch
mode string Set device mode. Accepted values are relay and roller
max_power number Set overpower threshold in Watts for roller mode only. For relay mode the device keeps separate, per-channel configurations, see /settings/relay/{index}
longpush_time number Set duration to detect long push, 1..5000ms

Shelly2.5: /settings/relay/{index}

GET /settings/relay/0

{
    "name": null,
    "ison": false,
    "has_timer": false,
    "overpower": false,
    "default_state": "off",
    "btn_type": "toggle",
    "btn_reverse": 0,
    "auto_on": 0,
    "auto_off": 0,
    "max_power": 2300,
    "btn_on_url": null,
    "btn_off_url": null,
    "out_on_url": null,
    "out_off_url": null,
    "longpush_url": null,
    "shortpush_url": null,
    "schedule": false,
    "schedule_rules": []
}

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.

Attributes

Attribute Type Description
name string Relay name
ison bool Channel state
has_timer bool Whether there is an active timer on the channel
overpower bool Whether an overpower condition has occurred
default_state string Default power-on state, one of off, on, last, switch
btn_type string Button type, one of momentary, toggle, edge, detached, action, cycle, momentary_on_release
btn_reverse number Whether input switch state is inverted
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
max_power number Per-channel overpower threshold (used in relay mode)
btn_on_url string URL to access when SW input is activated
btn_off_url string URL to access when SW input is deactivated
out_on_url string URL to access when output is activated
out_off_url string URL to access when output is deactivated
longpush_url string URL to access on longpush. Works only when button is configured as momentary, momentary_on_release or detached.
shortpush_url string URL to access on shortpush. Works only when button is configured as momentary, momentary_on_release or detached.
schedule bool Whether scheduling is enabled
schedule_rules array of strings Rules for schedule activation

Parameters

Parameter Type Description
reset any Submitting a non-empty value will reset settings for this relay output channel to factory defaults
name string Relay name
default_state string Accepted values: off, on, last, switch
btn_type string Accepted values: momentary, toggle, edge, detached, action, cycle, momentary_on_release
btn_reverse bool Invert the input switch state
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
max_power number Set per-channel overpower threshold (used in relay mode)
btn_on_url string Set URL to access when SW input is activated
btn_off_url string Set URL to access when SW input is deactivated
out_on_url string Set URL to access when output is activated
out_off_url string Set URL to access when output is deactivated
longpush_url string Set URL to access on longpush. Works only when button is configured as momentary, momentary_on_release or detached.
shortpush_url string Set URL to access on shortpush. Works only when button is configured as momentary, momentary_on_release or detached.
schedule bool Enable or disable schedules and sunrise/sunset commands for this channel
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on

Shelly2.5: /settings/roller/{index}

GET /settings/roller/0

{
    "maxtime": 20,
    "maxtime_open": 0,
    "maxtime_close": 0,
    "default_state": "stop",
    "swap": false,
    "swap_inputs": false,
    "input_mode": "openclose",
    "button_type": "toggle",
    "btn_reverse": 0,
    "state": "stop",
    "power": 0,
    "is_valid": true,
    "safety_switch": false,
    "roller_open_url": null,
    "roller_close_url": null,
    "roller_stop_url": null,
    "schedule": false,
    "schedule_rules": [],
    "obstacle_mode": "disabled",
    "obstacle_action": "stop",
    "obstacle_power": 200,
    "obstacle_delay": 1,
    "safety_mode": "while_opening",
    "safety_action": "stop",
    "safety_allowed_on_trigger": "none",
    "off_power": 2,
    "positioning": true
}

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.

Attributes

Attribute Type Description
maxtime number The maximum time needed for the mechanism to completely open or close, seconds
maxtime_open number The maximum time needed for the mechanism to completely open, seconds
maxtime_close number The maximum time needed for the mechanism to completely close, seconds
default_state string One of stop, open, close. This parameters determines the behavior on power-on
swap bool Whether to swap OPEN and CLOSE directions
swap_inputs bool Whether inputs are swapped
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 ...
button_type string One of momentary, toggle, detached or action
btn_reverse number Whether to invert the state of input switch before interpreting it
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
roller_open_url string URL to access when roller is open
roller_close_url string URL to access when roller is closed
roller_stop_url string URL to access when roller is stopped
schedule bool Whether scheduling is enabled
schedule_rules array of strings Rules for schedule activation
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
off_power number Power value below which the roller is considered "stopped", i.e. the actuator is stopped by an end-stop switch
positioning bool Whether the device is calibrated for positioning control

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
maxtime_open number The maximum time needed for the mechanism to completely open, seconds
maxtime_close number The maximum time needed for the mechanism to completely close, seconds
default_state string One of stop, open, close. This parameters determines the behavior on power-on
swap bool Whether to swap OPEN and CLOSE directions
swap_inputs bool Swap inputs
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, toggle, detached or action
btn_reverse bool Whether to invert the state of input switch before interpreting it
roller_open_url string Set URL to access when roller is open
roller_close_url string Set URL to access when roller is closed
roller_stop_url string Set URL to access when roller is stopped
schedule bool Enable or disable schedules and sunrise/sunset commands for this channel
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on
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
off_power number Power value below which the roller is considered "stopped", i.e. the actuator is stopped by an end-stop switch
positioning number Whether position control is possible (calibration was performed and successful)
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.5: /status

GET /status (in relay mode)

{
    "relays": [
        {
            "ison": false,
            "has_timer": false,
            "timer_started": 0,
            "timer_duration": 0,
            "timer_remaining": 0,
            "overpower": false,
            "overtemperature": false,
            "is_valid": true
        },
        {
            "ison": false,
            "has_timer": false,
            "timer_started": 0,
            "timer_duration": 0,
            "timer_remaining": 0,
            "overpower": false,
            "overtemperature": false,
            "is_valid": true
        }
    ],
    "meters": [
        {
            "power": 0,
            "is_valid": true,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        },
        {
            "power": 0,
            "is_valid": true,
            "timestamp": 0,
            "counters": [5,6,7],
            "total": 8
        }
    ],
    "inputs": [
        {
            "input": 0,
            "event": "S",
            "event_cnt": 2
        },
        {
            "input": 0,
            "event": "S",
            "event_cnt": 2
        }
    ],
    "temperature": 37.04,
    "overtemperature": false,
    "tmp": {
        "tC": 37.04,
        "tF": 98.67,
        "is_valid": true
    }
}

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

Attributes

Attribute Type Description
relays array of hashes Displayed in Relay mode: Contains the current state of the relay output channels. See /relay/{index} for description of attributes
rollers array of hashes Displayed in Roller mode: Contains the current state of the logical "roller" device. See /roller/{index} for description of attributes
meters array of hashes Current status of the power meters, see description below
inputs array of hashes Current state of the inputs, see description below
temperature number Device temperature in °C
overtemperature bool Whether an overtemperature condition has occurred
tmp.tC number Device temperature in °C
tmp.tF number Device temperature in °F
tmp.is_valid bool Whether device temperature is valid

inputs.{index} attributes

Attribute Type Description
input number Current state of the input
event string Last input event, S=shortpush, L=longpush, ""=none/invalid
event_cnt number Event counter, uint16

input shows the current logical state of the input: 0=OFF and 1=ON. event provides a short string, designating the last detected input event (shortpush/longpush). event_cnt is incremented each time a new input event occurs. event_cnt is not stored in non-volatile memory.

Input events are only detected in relay mode and only when btn_type is configured as momentary, momentary_on_release or detached.

Shelly2.5: /meter/{index}

GET /meter/0

{
    "power": 0,
    "is_valid": true,
    "timestamp": 0,
    "counters": [1,2,3],
    "total": 4
}

Attributes

Attribute Type Description
power number Current real AC power being drawn, in Watts
is_valid bool Whether power metering self-checks OK
timestamp number Unix timestamp of the last energy counter value
counters array of numbers Energy counter value for the last 3 round minutes in Watt-minute
total number Total energy consumed by the attached electrical appliance in Watt-minute

Shelly2.5: /relay/{index}

GET /relay/0

{
    "ison": true,
    "has_timer": false,
    "timer_started": 0,
    "timer_duration": 0,
    "timer_remaining": 0,
    "overpower": false,
    "overtemperature": false,
    "is_valid": false
}

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.

Attributes

Attribute Type Description
ison bool Whether the channel is turned ON or OFF
has_timer bool Whether a timer is currently armed for this channel
timer_started number Unix timestamp of timer start; 0 if timer inactive or time not synced
timer_duration number Timer duration, s
timer_remaining number experimental If there is an active timer, shows seconds until timer elapses; 0 otherwise
overpower bool Whether an overpower condition turned the channel OFF
overtemperature bool Whether an overtemperature condition occurred
is_valid bool Whether the associated power meter is functioning correctly

Parameters

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

Shelly2.5: /roller/{index}

GET /roller/0

{
    "state": "stop",
    "power": 0,
    "is_valid": false,
    "safety_switch": false,
    "overtemperature" false,
    "stop_reason": "normal",
    "last_direction": "stop",
    "current_pos": 90,
    "calibrating": false,
    "positioning": true
}

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

Attributes

Attribute Type Description
state string 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
overtemperature bool Whether an overtemperature condition occurred
stop_reason bool Last cause for stopping: normal, safety_switch, obstacle, overpower
last_direction bool Last direction of motion, open or close
current_pos number Current position in percent
calibrating bool Whether the device is currently performing a calibration procedure
positioning bool Whether the device is calibrated for positioning control

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/{index} will be used
offset number Offset 0 - 100%. Use offset or duration, not both

Shelly2.5: /roller/{index}/calibrate

Requesting this endpoint will trigger a calibration procedure to be performed. Shelly2.5 will measure the time it takes to open and close the mechanical device under control. Once this completes successfully, Shelly2.5 will be able to not only open and close, but target a specific position between the two. The procedure will open and close the actuated cover (door, roller shutter, etc.) detecting when an end position is reached. The average times for opening and closing will be stored by the device and used when a go=to_pos command is issued.

Shelly4Pro

Shelly4Pro

Shelly4Pro: 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/products/shelly-4pro-smart-home-automation-relay/

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.

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:

Shelly4Pro: MQTT

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

Shelly4Pro: /settings

GET /settings

{
    "relays": [
        {
            "name": null,
            "ison": false,
            "has_timer": false,
            "overpower": false,
            "default_state": "off",
            "btn_type": "toggle",
            "auto_on": 0,
            "auto_off": 0,
            "max_power": 0,
            "schedule": true,
            "schedule_rules": []
        }
    ],
    "meters": [
        {
            "power": 0,
            "is_valid": true,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        }
    ]
}

Shelly4Pro extends the common /settings endpoint with relay and 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/{index} for setting the channel parameters.

Attributes

Attribute Type Description
relays array of hashes See /settings/relay/{index} for explanation of values
meters array of hashes Contains the status of the integrated power meter, see description below

meters attributes

Attribute Type Description
power number Current real AC power being drawn, in Watts
is_valid bool Whether power metering self-checks OK
timestamp number Unix timestamp of the last energy counter value
counters array of numbers Energy counter value for the last 3 round minutes
total number Total energy consumed by the attached electrical appliance in Watt-minute

The counters array contains the values of the energy counter per channel for the last 3 round minutes. The value will always increase, but will reset to zero on reboot or power cycle. When observing this value (over MQTT or HTTP polling) the observer should keep an accumulator locally, and add the new value whenever it goes backwards.

Shelly4Pro: /settings/relay/{index}

GET /settings/relay/0

{
    "name": null,
    "ison": false,
    "has_timer": false,
    "overpower": false,
    "default_state": "off",
    "btn_type": "toggle",
    "auto_on": 0,
    "auto_off": 0,
    "max_power": 0,
    "schedule": true,
    "schedule_rules": []
}

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.

Attributes

Attribute Type Description
name string Relay name
ison bool Channel state
has_timer bool Whether there is an active timer on the channel
overpower bool Whether an overpower condition has occurred
default_state string Power-on default state, one of off, on, last, switch
btn_type string Button type, one of momentary, toggle, edge, action, detached
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
max_power number Per-channel overpower threshold
schedule bool Whether scheduling is enabled
schedule_rules array of strings Rules for schedule activation

Parameters

Parameter Type Description
reset any Submitting a non-empty value will reset settings for this relay output channel to factory defaults
name string Relay name
default_state string Accepted values: off, on, last, switch
btn_type string Accepted values: momentary, toggle, edge, action, detached
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
max_power number Per-channel overpower threshold
schedule bool Enable or disable schedules
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on

Shelly4Pro: /status

GET /status

{
    "relays": [
        {
            "ison": false,
            "has_timer": false,
            "timer_remaining": 0,
            "overpower": false,
            "is_valid": true
        }
    ],
    "meters": [
        {
            "power": 0,
            "is_valid": true,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        }
    ]
}

4Pro adds information about the current state of the output channels and power metering.

Attributes

Attribute Type Description
relays array of hashes Contains the current state of the relay output channels. See /relay/{index} for description of attributes
meters array of hashes Current status of the power meters, see description in /settings

Shelly4Pro: /meter/{index}

GET /meter/0

{
    "power": 0,
    "is_valid": true,
    "timestamp": 0,
    "counters": [1,2,3],
    "total": 4
}

Attributes

Attribute Type Description
power number Current real AC power being drawn, in Watts
is_valid bool Whether power metering self-checks OK
timestamp number Unix timestamp of the last energy counter value
counters array of numbers Energy counter value for the last 3 round minutes in Watt-minute
total number Total energy consumed by the attached electrical appliance in Watt-minute

Shelly4Pro: /relay/{index}

GET /relay/0

{
    "ison": false,
    "has_timer": false,
    "timer_remaining": 0,
    "overpower": false,
    "is_valid": true
}

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

Attributes

Attribute Type Description
ison bool Whether the channel is turned ON or OFF
has_timer bool Whether a timer is currently armed for this channel
timer_remaining number experimental If there is an active timer, shows seconds until timer elapses; 0 otherwise
overpower bool Whether an overpower condition turned the channel OFF
is_valid bool Whether the associated power meter is functioning correctly

Parameters

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

Shelly Plug / PlugS

Plug

Plug-S

Shelly Plug/PlugS: Overview

Shelly Plug/PlugS are among the most intelligent Wi-Fi power outlets on the market today. Visit the product pages for a detailed features overview and User Manual:

https://shelly.cloud/products/shelly-plug-smart-home-automation-device/

https://shelly.cloud/products/shelly-plug-s-smart-home-automation-device/

The settings of Shelly Plug 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 holding the button for more than 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 the value of max_power.

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. Thus, the user can set a limit for how long the plug can be ON or OFF.

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

To control Shelly Plug/PlugS, use these resources:

Shelly Plug/PlugS: MQTT

MQTT topics used by Plug / PlugS (where <model> is either shellyplug or shellyplug-s):

Shelly PlugS adds:

Shelly Plug/PlugS: /settings

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

GET /settings (Shelly PlugS)

{
    "max_power": 3500,
    "led_status_disable": false,
    "led_power_disable": false,
    "relays": [
        {
            "ison": false,
            "has_timer": false,
            "overpower": false,
            "default_state": "off",
            "auto_on": 0,
            "auto_off": 0,
            "btn_on_url": null,
            "out_on_url": null,
            "out_off_url": null,
            "schedule": false,
            "schedule_rules": [],
            "max_power": 0
        }
    ],
    "meters": [
        {
            "power": 0.01,
            "is_valid": true,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        }
    ]
}

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

Attributes

Attribute Type Description
max_power number Overpower threshold in Watts
led_status_disable bool PlugS only Whether LED indication for network status is enabled
led_power_disable bool PlugS only Whether LED indication for output status is enabled
relays array of hashes See /settings/relay/0 for explanation of values
meters array of hashes Contains the status of the integrated power meter, see below for description of attributes

meters attributes

Note: Energy counters (in the counters array and total) will reset to 0 after reboot.

Attribute Type Description
power number Current real AC power being drawn, in Watts
is_valid bool Whether power metering self-checks OK
timestamp number Unix timestamp of the last energy counter value
counters array of numbers Energy counter value for the last 3 round minutes in Watt-minute
total number Total energy consumed by the attached electrical appliance in Watt-minute

Parameters

Parameter Type Description
max_power number Overpower threshold in Watts
led_status_disable bool PlugS only Disable LED indication for network status
led_power_disable bool PlugS only Disable LED indication for output status

Shelly Plug/PlugS: /settings/relay/0

GET /settings/relay/0

{
    "ison": false,
    "has_timer": false,
    "overpower": false,
    "default_state": "off",
    "auto_on": 0,
    "auto_off": 0,
    "btn_on_url": null,
    "out_on_url": null,
    "out_off_url": null,
    "schedule": false,
    "schedule_rules": [],
    "max_power": 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.

Attributes

Attribute Type Description
ison bool State of the channel
has_timer bool Whether there is an active timer on the channel
overpower bool Whether an overpower condition has occurred
default_state string Default power-on state, one of off, on, last
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
btn_on_url string URL to access when SW input is activated
out_on_url string URL to access when output is activated
out_off_url string URL to access when output is deactivated
schedule bool Whether scheduling is enabled
schedule_rules array of strings Rules for schedule activation
max_power number Overpower threshold in Watts

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
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
btn_on_url string Set URL to access when SW input is activated
out_on_url string Set URL to access when output is activated
out_off_url string Set URL to access when output is deactivated
schedule bool Enable schedule timer
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on
max_power number Overpower threshold in Watts

Shelly Plug/PlugS: /status

GET /status (Shelly PlugS)

{
    "relays": [
        {
            "ison": true,
            "has_timer": false,
            "timer_started": 0,
            "timer_duration": 0,
            "timer_remaining": 0,
            "overpower": false
        }
    ],
    "meters": [
        {
            "power": 0.01,
            "is_valid": true,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        }
    ],
    "temperature": 41.94,
    "overtemperature": false,
    "tmp": {
        "tC": 41.94,
        "tF": 107.5,
        "is_valid": true
    }
}

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

Attributes

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
temperature number PlugS only internal device temperature in °C
overtemperature bool PlugS only true when device has overheated
tmp.tC number PlugS only Internal device temperature in °C
tmp.tF number PlugS only Internal device temperature in °F
tmp.is_valid bool PlugS only Whether the internal temperature sensor functions correctly

Shelly Plug/PlugS: /meter/0

GET /meter/0

{
    "power": 0,
    "is_valid": true,
    "timestamp": 0,
    "counters": [1,2,3],
    "total": 4
}

Attributes

Attribute Type Description
power number Current real AC power being drawn, in Watts
is_valid bool Whether power metering self-checks OK
timestamp number Unix timestamp of the last energy counter value
counters array of numbers Energy counter value for the last 3 round minutes in Watt-minute
total number Total energy consumed by the attached electrical appliance in Watt-minute

Shelly Plug/PlugS: /relay/0

GET /relay/0

{
    "ison": false,
    "has_timer": false,
    "timer_started": 0,
    "timer_duration": 0,
    "timer_remaining": 0,
    "overpower": false
}

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

Attributes

Attribute Type Description
ison bool Whether the channel is turned ON or OFF
has_timer bool Whether a timer is currently armed for this channel
timer_started number Unix timestamp of timer start; 0 if timer inactive or time not synced
timer_duration number Timer duration, s
timer_remaining number experimental If there is an active timer, shows seconds until timer elapses; 0 otherwise
overpower bool Whether an overpower condition turned the channel OFF

Parameters

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

Shelly i3

Shellyi3

Shelly i3: Overview

Shelly i3 is a WiFi AC switch reader. It has 3 independent input channels which can operare with all types of toggle and momentary AC switches.

Shelly i3 can detect and announce not only simple ON/OFF state changes, but also complex (multipush) input events, for example double shortpush, shortpush + longpush, etc. For each of this events Shelly i3 can invoke user-configurable action URLs. For more information see Shelly i3: Input events

The product page has all key features described, wiring diagram and User Manual.

Factory Reset

To perform a factory reset on a Shelly i3 device:

Shelly i3: Input events

Shelly i3 can detect and announce the following input events on any of its channels:

For each input event, an action URL can be configured via the /settings/input/{index} endpoint.

To configure the detection of input events, set the parameters described below via the /settings endpoint. These parameters are common for all 3 input channels.

Parameter Type Accepted values Default
longpush_duration_ms_min number >= 100ms 800ms
longpush_duration_ms_max number >= (longpush_duration_ms_min + 100ms) 3000ms
multipush_time_between_pushes_ms_max number >= 100ms 500ms

Following rules apply:

Shelly i3 announces input events using the attributes described below (see /status):

Attribute Type Value Value on power-on / reboot
event string "" = none / invalid ""
S = shortpush
L = longpush
SS = double shortpush
SSS = triple shortpush
SL = shortpush + longpush
LS = longpush + shortpush
event_cnt number uint16 0

The event counter event_cnt is incremented each time there is a new event on the input channel. It doesn't take in account which event it is exactly. On power-on / reboot, the value of the counter is 0.

Shelly i3: MQTT

Shelly i3 publishes on the following MQTT topics, where <index> is the input channel (0,1,2):

MQTT topic Message Message on power-on / reboot
shellies/shellyix3-<deviceid>/input/<index> 0 = input is OFF depends on physical state
1 = input is ON
shellies/shellyix3-<deviceid>/input_event/<index> {"event":"string","event_cnt":number} {"event":"","event_cnt":0}
event and event_cnt are described in detail in Shelly i3: Input events

Note: by default, Shelly i3 will send periodic MQTT updates every 30 seconds. You can turn these off and only receive messages when an input has changed by setting the mqtt_update_period parameter to 0 (see /settings).

Shelly i3: /settings

GET /settings

{
    "longpush_duration_ms": {
        "min": 800,
        "max": 3000
    },
    "multipush_time_between_pushes_ms": {
        "max": 500
    },
    "inputs": [
        {
            "name": null,
            "btn_type": "momentary",
            "btn_reverse": 0,
            "btn_on_url": "http://xxx",
            "btn_off_url": "http://xxx",
            "shortpush_url": "http://xxx",
            "longpush_url": "http://xxx",
            "double_shortpush_url": "http://xxx",
            "triple_shortpush_url": "http://xxx",
            "shortpush_longpush_url": "http://xxx",
            "longpush_shortpush_url": "http://xxx"
        },
        {
            "name": null,
            "btn_type": "momentary",
            "btn_reverse": 0,
            "btn_on_url": "http://xxx",
            "btn_off_url": "http://xxx",
            "shortpush_url": "http://xxx",
            "longpush_url": "http://xxx",
            "double_shortpush_url": "http://xxx",
            "triple_shortpush_url": "http://xxx",
            "shortpush_longpush_url": "http://xxx",
            "longpush_shortpush_url": "http://xxx"
        },
        {
            "name": null,
            "btn_type": "momentary",
            "btn_reverse": 0,
            "btn_on_url": "http://xxx",
            "btn_off_url": "http://xxx",
            "shortpush_url": "http://xxx",
            "longpush_url": "http://xxx",
            "double_shortpush_url": "http://xxx",
            "triple_shortpush_url": "http://xxx",
            "shortpush_longpush_url": "http://xxx",
            "longpush_shortpush_url": "http://xxx"
        }
    ]
}

Shelly i3 extends the common /settings endpoint with input timing settings and adds /settings/input/{index} for configuring input channel-specific parameters.

Attributes

Attribute Type Description
longpush_duration_ms.min number Longpush min duration (ms)
longpush_duration_ms.max number Longpush max duration (ms)
multipush_time_between_pushes_ms.max number Max time between sequential pushes (ms)
inputs array of hashes See /settings/input/{index}

Parameters

For a detailed description see Shelly i3: Input events

Parameter Type Description
longpush_duration_ms_min number Set longpush min duration (ms)
longpush_duration_ms_max number Set longpush max duration (ms)
multipush_time_between_pushes_ms_max number Set max time between sequential pushes (ms)

Shelly i3: /settings/input/{index}

GET /settings/input/0

{
    "name": null,
    "btn_type": "momentary",
    "btn_reverse": 0,
    "btn_on_url": "http://xxx",
    "btn_off_url": "http://xxx",
    "shortpush_url": "http://xxx",
    "longpush_url": "http://xxx",
    "double_shortpush_url": "http://xxx",
    "triple_shortpush_url": "http://xxx",
    "shortpush_longpush_url": "http://xxx",
    "longpush_shortpush_url": "http://xxx"
}

The returned document here is identical to the data returned in /settings for the particular input channel in the inputs array.

Attributes

Attribute Type Description
name string Input name
btn_type string Button type: toggle or momentary
btn_reverse number If input logical state is inverted
btn_on_url string URL to access when switch is ON (works only when btn_type=toggle)
btn_off_url string URL to access when switch is OFF (works only when btn_type=toggle)
shortpush_url string URL to access when switch is pressed short (works only when btn_type=momentary)
longpush_url string URL to access when switch is pressed long (works only when btn_type=momentary)
double_shortpush_url string URL to access when switch is 2x pressed short (works only when btn_type=momentary)
triple_shortpush_url string URL to access when switch is 3x pressed short (works only when btn_type=momentary)
shortpush_longpush_url string URL to access when switch is pressed short + long (works only when btn_type=momentary)
longpush_shortpush_url string URL to access when switch is pressed long + short (works only when btn_type=momentary)

Parameters

Parameter Type Description
reset any Submitting a non-empty value will reset settings for this input channel to factory defaults
name string Set input name
btn_type string Set button type: toggle or momentary
btn_reverse bool Set whether to invert the input logical state
btn_on_url string Set URL to access when switch is ON (works only when btn_type=toggle)
btn_off_url string Set URL to access when switch is OFF (works only when btn_type=toggle)
shortpush_url string Set URL to access when switch is pressed short (works only when btn_type=momentary)
longpush_url string Set URL to access when switch is pressed long (works only when btn_type=momentary)
double_shortpush_url string Set URL to access when switch is 2x pressed short (works only when btn_type=momentary)
triple_shortpush_url string Set URL to access when switch is 3x pressed short (works only when btn_type=momentary)
shortpush_longpush_url string Set URL to access when switch is pressed short + long (works only when btn_type=momentary)
longpush_shortpush_url string Set URL to access when switch is pressed long + short (works only when btn_type=momentary)

Shelly i3: /status

GET /status

{
    "inputs": [
        {
            "input": 0,
            "event": "S",
            "event_cnt": 11
        },
        {
            "input": 1,
            "event": "SS",
            "event_cnt": 22
        },
        {
            "input": 0,
            "event": "LS",
            "event_cnt": 15
        }
    ]
}

Shelly i3 extends the common /status endpoint with the current status of the input channels.

Attributes

Attribute Type Description
inputs array of hashes Contains the current state of the input channels. See /input/{index} for description of attributes

Shelly i3: /input/{index}

GET /input/0

{
    "input": 0,
    "event": "S",
    "event_cnt": 11
}

Shows current status of {index} input channel.

Attributes

Attribute Type Description
input number 0 = input is OFF
1 = input is ON
event string Input event, see Shelly i3: Input events
event_cnt number Input event counter, see Shelly i3: Input events

Shelly Button1

Shelly Button1

Shelly Button1: Overview

Shelly Button1 is a WiFi button which can detect and announce 4 types of button presses - short, 2x short, 3x short, long. We developed Shelly Button1 to help you easily activate or deactivate any device or scene manually with just a click. Powered by rechargeable batteries, allowing for more than 3000 actions per charge. As an option it can be connectted via USB for constant power supply and Wi-Fi connection. Response time of less than 2sec. on battery and 100 ms on USB power.

The product page has all key features described and User Manual.

Factory Reset

To perform a factory reset on a Shelly Button1:

Shelly Button1: MQTT

Shelly Button1 publishes on the following MQTT topics:

Shelly Button1: /settings

GET /settings

{
    "device": {
        "sleep_mode": true
    },
    "sleep_mode": {
        "period": 12,
        "unit": "h"
    },
    "led_status_disable": false,
    "longpush_duration_ms": {
        "max": 800
    },
    "multipush_time_between_pushes_ms": {
        "max": 500
    },
    "remain_awake": 0,
    "inputs": [
        {
            "shortpush_url": "http://xxx",
            "double_shortpush_url": "http://xxx",
            "triple_shortpush_url": "http://xxx",
            "longpush_url": "http://xxx"
        }
    ]
}

Attributes

Attribute Type Description
device.sleep_mode bool Always true
sleep_mode.period number Periodic update period, always 12
sleep_mode.unit string Always h
led_status_disable bool Whether status LED is enabled/disabled
longpush_duration_ms.max number Longpush max duration (ms)
multipush_time_between_pushes_ms.max number Max time between sequential pushes (ms)
remain_awake number Time after last event before go to sleep in sec
inputs array of hashes See /settings/input/0

Parameters

Parameter Type Description
remain_awake number Set time after last event before go to sleep in sec, [0..5]
longpush_duration_ms_max number Set longpush max duration (ms), [800..2000]
multipush_time_between_pushes_ms_max number Set max time between sequential pushes (ms), [200..2000]
led_status_disable bool Enable/disable status LED

Shelly Button1: /settings/input/0

GET /settings/input/0

{
    "shortpush_url": "http://xxx",
    "double_shortpush_url": "http://xxx",
    "triple_shortpush_url": "http://xxx",
    "longpush_url": "http://xxx"
}

Attributes

Attribute Type Description
shortpush_url string URL to access when switch is pressed short
double_shortpush_url string URL to access when switch is 2x pressed short
triple_shortpush_url string URL to access when switch is 3x pressed short
longpush_url string URL to access when switch is pressed long

Parameters

Parameter Type Description
reset any Submitting a non-empty value will reset settings for this input channel to factory defaults
shortpush_url string Set URL to access when switch is pressed short
double_shortpush_url string Set URL to access when switch is 2x pressed short
triple_shortpush_url string Set URL to access when switch is 3x pressed short
longpush_url string Set URL to access when switch is pressed long

Shelly Button1: /status

GET /status

{
    "inputs": [
        {
            "input": 0,
            "event": "S",
            "event_cnt": 11
        }
    ],
    "is_valid": true,
    "bat": {
        "value": 71,
        "voltage": 2.73
    },
    "charger": false,
    "act_reasons": [
        "button"
    ],
    "connect_retries": 0
}

Attributes

Attribute Type Description
inputs array of hashes Contains the current state of the input channels. See /input/0 for description of attributes
is_valid bool Whether button self-checks OK
bat.value number Estimated remaining battery capacity in %, 0..100
bat.voltage number Battery voltage, V
charger bool Whether external power is available
act_reasons array of strings List of reasons which woke up the device: battery, button, periodic, poweron, sensor, ext_power
connect_retries number WiFi connect retries
sensor_error number Only displayed in case of error

Shelly Button1: /input/0

GET /input/0

{
    "input": 0,
    "event": "S",
    "event_cnt": 11
}

Attributes

Attribute Type Description
input number Input state physical - always 0
event string Input event, S = shortpush, SS = double shortpush, SSS = triple shortpush, L = longpush
event_cnt number Input event counter, uint16

Shelly Bulb

Shelly Bulb

Shelly 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/products/shelly-bulb-smart-home-automation-device/

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.

Shelly 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:

Shelly Bulb: MQTT

Shelly Bulb allows the simple on and off commands, 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 parameters of the LED channels publish to:

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

{
    "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" */
    "gain": 100,        /* gain for all channels, 0..100, applies in mode="color" */
    "brightness": 100,  /* brightness, 0..100, applies in mode="white" */
    "white": 0,         /* white brightness, 0..255, applies in mode="color" */
    "temp": 4750,       /* color temperature in K, 3000..6500, applies in mode="white" */
    "effect": 0,        /* applies an effect when set */
    "turn": "on"        /* "on", "off" or "toggle" */
}

mode controls which set of parameters are used:

A JSON payload will be published by Shelly Bulb on:

Subscribers can use this to obtain the latest device state.

{
    "ison": false,        /* whether the bulb is on */
    "has_timer": false,   /* whether a timer is currently armed */
    "timer_started": 0,   /* unix timestamp of timer start; 0 if timer inactive or time not synced */
    "timer_duration": 0,  /* timer duration, s */
    "timer_remaining": 0, /* if there is an active timer, shows seconds until timer elapses; 0 otherwise */
    "mode": "color",      /* currently configured mode */
    "red": 255,           /* red brightness, 0..255, applies in mode="color" */
    "green": 125,         /* green brightness, 0..255, applies in mode="color" */
    "blue": 0,            /* 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": 5406,         /* color temperature in K, 3000..6500, applies in mode="white" */
    "brightness": 90,     /* brightness, 0..100, applies in mode="white" */
    "effect": 0           /* currently applied effect */
}

Shelly Bulb: /settings


GET /settings

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

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

Attributes

Attribute Type Description
mode string Currently configured mode
lights array of hashes Output channel settings. Shelly Bulb only supports a single channel, indexed as 0. See /settings/light/0 for more details.

Parameters

Parameter Type Description
mode string Accepted values are white and color

Shelly Bulb: /settings/light/0


GET /settings/light/0

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

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 ON-timer value, s
auto_off number OFF-timer value, s
power number User power constant to display in meters when bulb is on, see /settings/power/0
schedule bool Whether scheduling is enabled
schedule_rules array of strings Rules for schedule activation

Parameters

Parameter Type Description
reset any Any non-zero-length value will reset light settings to default
effect number 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
schedule bool Enable schedule timer
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on

Shelly Bulb: /settings/color/0

Same as /settings/light/0

Shelly Bulb: /settings/white/0

Same as /settings/light/0

Shelly Bulb: /settings/power/0

Parameters

Parameter Type Description
power number User power constant to display in meters when bulb is on, 0..4000W

Shelly Bulb: /status


GET /status

{
    "lights": [
        {
            "ison": false,
            "has_timer": false,
            "timer_started": 0,
            "timer_duration": 0,
            "timer_remaining": 0,
            "mode": "color",
            "red": 255,
            "green": 127,
            "blue": 0,
            "white": 0,
            "gain": 100,
            "temp": 5406,
            "brightness": 90,
            "effect": 0
        }
    ],
    "meters": [
        {
            "power": 0,
            "is_valid": true
        }
    ]
}

Attributes

Attribute Type Description
lights array of hashes Contains the current state of the light channels. See /light/0 for description of attributes
meters array of hashes Power information, see description below

meters attributes

Attribute Type Description
power number When bulb is on, displays the value of the user power constant (see /settings/power/0); otherwise 0
is_valid bool Always true

Shelly Bulb: /light/0


GET /light/0

{
    "ison": false,
    "has_timer": false,
    "timer_started": 0,
    "timer_duration": 0,
    "timer_remaining": 0,
    "mode": "color",
    "red": 255,
    "green": 127,
    "blue": 0,
    "white": 0,
    "gain": 100,
    "temp": 5406,
    "brightness": 90,
    "effect": 0
}

Attributes

Attribute Type Description
ison bool Whether the channel is turned ON or OFF
has_timer bool Whether a timer is currently armed for this channel
timer_started number Unix timestamp of timer start; 0 if timer inactive or time not synced
timer_duration number Timer duration, s
timer_remaining number experimental If there is an active timer, shows seconds until timer elapses; 0 otherwise
mode string Currently configured mode
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

Parameters

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, off or toggle
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 Applies an effect, see description

Shelly Bulb: /color/0

Same as /light/0

Shelly Bulb: /white/0

Same as /light/0

Shelly Vintage

Shelly Vintage

Shelly Vintage: Overview

Shelly Vintage - Wi-Fi on board, Cloud and MQTT enabled, dimmable, voice control, smart Wake-up and Night mode. Visit the product page for detailed information and User Manual:

https://shelly.cloud/products/shelly-vintage-smart-home-automation-bulb/

Factory Reset

Factory reset can be performed by:

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

Shelly Vintage: MQTT

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

For controlling other parameters of the light channel publish to:

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

{
    "brightness": 100,  /* brightness, 0..100 */
    "turn": "on"        /* "on", "off" or "toggle" */
}

A JSON payload will be published by Shelly Vintage on:

Subscribers can use this to obtain the latest device state.

{
    "ison": false,        /* whether the bulb is on */
    "has_timer": false,   /* whether a timer is currently armed */
    "timer_started": 0,   /* unix timestamp of timer start; 0 if timer inactive or time not synced */
    "timer_duration": 0,  /* timer duration, s */
    "timer_remaining": 0, /* if there is an active timer, shows seconds until timer elapses; 0 otherwise */
    "brightness": 90      /* brightness, 0..100 */
}

Power and energy info can be obtained at:

Shelly Vintage: /settings


GET /settings

{
    "mode": "white",
    "transition": 1000,
    "lights": [
        {
            "ison": false,
            "brightness": 100,
            "default_state": "on",
            "auto_on": 0,
            "auto_off": 0,
            "schedule": false,
            "out_on_url": "",
            "out_off_url": "",
            "schedule_rules": []
        }
    ],
    "night_mode": {
        "enabled": false,
        "start_time": "00:00",
        "end_time": "00:00",
        "brightness": 0
    }
}

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

Attributes

Attribute Type Description
mode string Currently configured mode, always white for Shelly Vintage
transition number On/off transition time, ms
lights array of hashes Output channel settings. Shelly Vintage only supports a single channel, indexed as 0. See /settings/light/0 for more details.
night_mode hash Nightmode settings, see /settings/night_mode for more details.

Parameters

Parameter Type Description
transition number Set on/off transition time, 0..5000ms

Shelly Vintage: /settings/light/0


GET /settings/light/0

{
    "ison": false,
    "brightness": 100,
    "default_state": "on",
    "auto_on": 0,
    "auto_off": 0,
    "schedule": false,
    "out_on_url": "",
    "out_off_url": "",
    "schedule_rules": []
}

Attributes

Attribute Type Description
ison bool Whether the bulb is on or off
brightness number Brightness, 0..100
default_state string One of on, off or last
auto_on number ON-timer value, s
auto_off number OFF-timer value, s
schedule bool Whether scheduling is enabled
out_on_url string URL to access when output is activated
out_off_url string URL to access when output is deactivated
schedule_rules array of strings Rules for schedule activation

Parameters

Parameter Type Description
reset any Any non-zero-length value will reset light settings to default
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
schedule bool Enable schedule timer
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on
out_on_url string Set URL to access when output is activated
out_off_url string Set URL to access when output is deactivated

Shelly Vintage: /settings/night_mode


GET /settings/night_mode

{
    "enabled": false,
    "start_time": "00:00",
    "end_time": "00:00",
    "brightness": 0
}

Parameters

Parameter Type Description
enabled bool Enable/disable night mode
start_time string Set night mode start time in format hh:mm
end_time string Set night mode end time in format hh:mm
brightness number Set brightness when in night mode, 0..100

Shelly Vintage: /status


GET /status

{
    "lights": [
        {
            "ison": false,
            "has_timer": false,
            "timer_started": 0,
            "timer_duration": 0,
            "timer_remaining": 0,
            "brightness": 90
        }
    ],
    "meters": [
        {
            "power": 0,
            "is_valid": true,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        }
    ]
}

Attributes

Attribute Type Description
lights array of hashes Contains the current state of the light channel. See /light/0 for description of attributes
meters array of hashes Power information, see description below

meters attributes

Attributes

Attribute Type Description
power number Current real AC power being drawn, in Watts
is_valid bool Whether power metering self-checks OK
timestamp number Unix timestamp of the last energy counter value
counters array of numbers Energy counter value for the last 3 round minutes in Watt-minute
total number Total energy consumed in Watt-minute

Shelly Vintage: /light/0


GET /light/0

{
    "ison": false,
    "has_timer": false,
    "timer_started": 0,
    "timer_duration": 0,
    "timer_remaining": 0,
    "brightness": 90
}

Attributes

Attribute Type Description
ison bool Whether the channel is turned ON or OFF
has_timer bool Whether a timer is currently armed for this channel
timer_started number Unix timestamp of timer start; 0 if timer inactive or time not synced
timer_duration number Timer duration, s
timer_remaining number experimental If there is an active timer, shows seconds until timer elapses; 0 otherwise
brightness number Brightness, 0..100

Parameters

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

Parameter Type Description
turn string Command to turn on, off or toggle
timer number Automatic flip-back timer in seconds, used in combination with turn
brightness number Set brightness, 0..100

Shelly Duo

Shelly Duo

Shelly Duo: Overview

Shelly Duo - Wi-Fi on board, Cloud and MQTT enabled, dimmable, 2700K up to 6500K, voice control, smart Wake-up and Night mode. Visit the product page for detailed information and User Manual:

https://shelly.cloud/products/shelly-duo-smart-home-automation-bulb/

Factory Reset

Factory reset can be performed by:

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

Shelly Duo: MQTT

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

For controlling other parameters of the light channel publish to:

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

{
    "brightness": 100,  /* brightness, 0..100 */
    "white": 0,         /* white level, 0..100 */
    "temp": 2700,       /* color temperature in K, 2700..6500 */
    "turn": "on"        /* "on", "off" or "toggle" */
}

A JSON payload will be published by Shelly Duo on:

Subscribers can use this to obtain the latest device state.

{
    "ison": false,        /* whether the channel is turned ON or OFF */
    "has_timer": false,   /* whether a timer is currently armed for this channel */
    "timer_started": 0,   /* unix timestamp of timer start; 0 if timer inactive or time not synced */
    "timer_duration": 0,  /* timer duration, s */
    "timer_remaining": 0, /* if there is an active timer, shows seconds until timer elapses; 0 otherwise */
    "brightness": 100,    /* brightness, 0..100 */
    "white": 0,           /* white level, 0..100 */
    "temp": 2700          /* color temperature, 2700..6500K */
}

Power and energy info can be obtained at:

Shelly Duo: /settings


GET /settings

{
    "mode": "white",
    "transition": 1000,
    "lights": [
        {
            "ison": false,
            "brightness": 100,
            "white": 50,
            "temp": 4600,
            "default_state": "on",
            "auto_on": 0,
            "auto_off": 0,
            "schedule": false,
            "out_on_url": "",
            "out_off_url": "",
            "schedule_rules": []
        }
    ],
    "night_mode": {
        "enabled": false,
        "start_time": "00:00",
        "end_time": "00:00",
        "brightness": 0
    }
}

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

Attributes

Attribute Type Description
mode string Currently configured mode, always white for Shelly Duo
transition number On/off transition time, ms
lights array of hashes Output channel settings. Shelly Duo only supports a single channel, indexed as 0. See /settings/light/0 for more details.
night_mode hash Nightmode settings, see /settings/night_mode for more details.

Parameters

Parameter Type Description
transition number Set on/off transition time, 0..5000ms

Shelly Duo: /settings/light/0


GET /settings/light/0

{
    "ison": false,
    "brightness": 100,
    "white": 50,
    "temp": 4600,
    "default_state": "on",
    "auto_on": 0,
    "auto_off": 0,
    "schedule": false,
    "out_on_url": "",
    "out_off_url": "",
    "schedule_rules": []
}

Attributes

Attribute Type Description
ison bool Whether the bulb is on or off
brightness number Brightness, 0..100
white number White level, 0..100
temp number Color temperature, 2700..6500K (derived from white)
default_state string One of on, off or last
auto_on number ON-timer value, s
auto_off number OFF-timer value, s
schedule bool Whether scheduling is enabled
out_on_url string URL to access when output is activated
out_off_url string URL to access when output is deactivated
schedule_rules array of strings Rules for schedule activation

Parameters

Parameter Type Description
reset any Any non-zero-length value will reset light settings to default
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
schedule bool Enable schedule timer
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on
out_on_url string Set URL to access when output is activated
out_off_url string Set URL to access when output is deactivated

Shelly Duo: /settings/night_mode


GET /settings/night_mode

{
    "enabled": false,
    "start_time": "00:00",
    "end_time": "00:00",
    "brightness": 0
}

Parameters

Parameter Type Description
enabled bool Enable/disable night mode
start_time string Set night mode start time in format hh:mm
end_time string Set night mode end time in format hh:mm
brightness number Set brightness when in night mode, 0..100

Shelly Duo: /status


GET /status

{
    "lights": [
        {
            "ison": false,
            "has_timer": false,
            "timer_started": 0,
            "timer_duration": 0,
            "timer_remaining": 0,
            "brightness": 90,
            "white": 0,
            "temp": 2700
        }
    ],
    "meters": [
        {
            "power": 0,
            "is_valid": true,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        }
    ]
}

Attributes

Attribute Type Description
lights array of hashes Contains the current state of the light channels. See /light/0 for description of attributes
meters array of hashes Power information, see description below

meters attributes

Attribute Type Description
power number Consumed power, W
is_valid bool Always true
timestamp number Unix timestamp of the last energy counter value
counters array of numbers Energy counter value for the last 3 round minutes in Watt-minute
total number Total energy consumed in Watt-minute

Shelly Duo: /light/0


GET /light/0

{
    "ison": false,
    "has_timer": false,
    "timer_started": 0,
    "timer_duration": 0,
    "timer_remaining": 0,
    "brightness": 90,
    "white": 0,
    "temp": 2700
}

Attributes

Attribute Type Description
ison bool Whether the channel is turned ON or OFF
has_timer bool Whether a timer is currently armed for this channel
timer_started number Unix timestamp of timer start; 0 if timer inactive or time not synced
timer_duration number Timer duration, s
timer_remaining number experimental If there is an active timer, shows seconds until timer elapses; 0 otherwise
brightness number Brightness, 0..100
white number White level, 0..100
temp number Color temperature, 2700..6500K (derived from white)

Parameters

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

Parameter Type Description
turn string Command to turn on, off or toggle
timer number Automatic flip-back timer in seconds, used in combination with turn
brightness number Brightness, 0..100
white number White level, 0..100
temp number Color temperature in K, 2700..6500

Shelly RGBW2 Color

Shelly RGBW2 Color: Overview

Shelly RGBW2 Color is a WiFi-enabled 4-channel 12V/24V LED driver which can control a single RGB+W installation. Via firmware change the same device can be used to control the 4 output channels independently, see Shelly RGBW2 White.

https://shelly.cloud/products/shelly-rgbw2-smart-home-automation-led-controller/

Factory Reset

A factory reset can be performed over the local web interface or Shelly application. In case the device cannot be accessed over network, physical methods for factory reset exist:

Shelly RGBW2 Color: MQTT

The device can be controlled using the same MQTT protocol as Shelly Bulb and looks like a single logical device.

Command topics

Shelly RGBW2 Color subscribes to the following topics:

{
    "mode": "color",    /* "color" */
    "red": 0,           /* red brightness, 0..255 */
    "green": 0,         /* green brightness, 0..255 */
    "blue": 255,        /* blue brightness, 0..255 */
    "gain": 100,        /* gain for all channels, 0..100 */
    "white": 0,         /* white brightness, 0..255 */
    "effect": 0,        /* applies an effect when set */
    "turn": "on"        /* "on", "off" or "toggle" */
}

Status topics

Shelly RGBW2 Color publishes to:

{
    "ison",            /* whether the output is ON or OFF */
    "has_timer",       /* whether a timer is currently armed for this channel */
    "timer_started",   /* unix timestamp of timer start; 0 if timer inactive or time not synced */
    "timer_duration",  /* timer duration, s */
    "timer_remaining", /* if there is an active timer, shows seconds until timer elapses; 0 otherwise */
    "mode",            /* currently configured mode */
    "red",             /* red brightness, 0..255 */
    "green",           /* green brightness, 0..255 */
    "blue",            /* blue brightness, 0..255 */
    "white",           /* white brightness, 0..255 */
    "gain",            /* gain for all channels, 0..100 */
    "effect",          /* applied effect */
    "power",           /* consumed power, W */
    "overpower"        /* whether an overpower condition has occurred */
}

Shelly RGBW2 Color: /settings


GET /settings

{
    "factory_reset_from_switch": true,
    "mode": "color",
    "alt_modes": ["white"],
    "dcpower": 1,
    "lights": [
        {
            "ison": true,
            "red": 0,
            "green": 0,
            "blue": 255,
            "white": 0,
            "gain": 50,
            "effect": 0,
            "default_state": "on",
            "auto_on": 0,
            "auto_off": 0,
            "schedule": false,
            "btn_type": "toggle",
            "btn_reverse": 0,
            "schedule_rules": []
        }
    ],
    "night_mode": {
        "enabled": false,
        "start_time": "00:00",
        "end_time": "00:00",
        "brightness": 20
    },
    "actions": {
        "btn_on_url": "",
        "btn_off_url": "",
        "btn_longpush_url": "",
        "btn_shortpush_url": "",
        "out_on_url": "",
        "out_off_url": ""
    }
}

Attributes

Attribute Type Description
factory_reset_from_switch bool Whether factory reset via 5-time flip of the input switch is enabled
mode string Currently configured mode, color or white
alt_modes array of strings Alternative device modes
dcpower number DC supply voltage 0=12V, 1=24V
lights array of hashes Output channel settings. See /settings/color/0 for more details.
night_mode hash Night mode settings, see /settings/night_mode
actions hash Action URLs. See /settings/color/0 for more details.

3 additional parameters are supported on the /settings endpoint for RGBW2 Color:

Parameters

Parameter Type Description
factory_reset_from_switch bool Enable/disable factory reset via 5-time flip of the input switch
mode string Set to color or white; determines the operating mode
dcpower bool Set to true for 24 V power supply, false for 12 V

Shelly RGBW2 Color: /settings/color/0


GET /settings/color/0

{
    "ison": true,
    "red": 0,
    "green": 0,
    "blue": 255,
    "white": 0,
    "gain": 50,
    "effect": 0,
    "default_state": "on",
    "auto_on": 0,
    "auto_off": 0,
    "schedule": false,
    "btn_type": "toggle",
    "btn_reverse": 0,
    "schedule_rules": []
}

Attributes

Attribute Type Description
ison bool Whether the outputs are ON or OFF
red number Red brightness, 0..255
green number Green brightness, 0..255
blue number Blue brightness, 0..255
white number White brightness, 0..255
gain number Gain for all channels, 0..100
effect number Applied effect, see description below
default_state string One of on, off or last
auto_on number ON-timer value, s
auto_off number OFF-timer value, s
btn_type string Input type, one of momentary, toggle, edge, detached or action
btn_reverse number Whether the logical state of the input is inverted
schedule bool Whether scheduling is enabled
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on

This endpoint sets persistent settings for color mode:

Parameters

Parameter Type Description
reset any Any non-zero-length value will reset light settings to default
effect number Applies an effect, see description below
default_state string Sets default power-on state: on, off or last
auto_on number Sets a default timer to turn ON after every OFF command in seconds
auto_off number Sets a default timer to turn OFF after every ON command in seconds
btn_type string Input type: momentary, toggle, edge, detached or action
btn_reverse bool Whether to invert external switch input
schedule bool Enable schedule timer
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on
btn_on_url string Set URL to access when input switch is activated
btn_off_url string Set URL to access when input switch is deactivated
btn_longpush_url string Set URL to access when input switch is held down
btn_shortpush_url string Set URL to access when input switch is pressed briefly
out_on_url string Set URL to access when output is activated
out_off_url string Set URL to access when output is deactivated

Supported values for effect are:

Shelly RGBW2 Color: /settings/night_mode


GET /settings/night_mode

{
    "enabled": false,
    "start_time": "00:00",
    "end_time": "00:00",
    "brightness": 20
}

When night mode is active, turning ON the device during the set interval it will only go up to the pre-set brightness limit.

Parameters

Parameter Type Description
enabled bool Enable/disable night mode
start_time string Set night mode start time in format hh:mm
end_time string Set night mode end time in format hh:mm
brightness number Set night mode brightness in percent 1..100

Shelly RGBW2 Color: /status


GET /status (in color mode)

{
    "mode": "color",
    "input": 0,
    "lights": [
        {
            "ison": true,
            "has_timer": false,
            "timer_started": 0,
            "timer_duration": 0,
            "timer_remaining": 0,
            "mode": "color",
            "red": 255,
            "green": 127,
            "blue": 0,
            "white": 0,
            "gain": 100,
            "effect": 0,
            "power": 0.46,
            "overpower": false
        }
    ],
    "meters": [
        {
            "power": 0.46,
            "is_valid": true,
            "overpower": false,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        }
    ],
    "inputs": [
        {
            "input": 0,
            "event": "S",
            "event_cnt": 2
        }
    ]
}

Attributes

Attribute Type Description
mode string Currently configured mode, color or white
input number State of the SW input
lights array of hashes Contains the current state of the light channels. See /color/0 for description of attributes
meters array of hashes Power and energy information, see description below
inputs array of hashes Current state of the inputs, see description below

meters attributes

Attribute Type Description
power number Power consumption, W
is_valid bool Whether power metering self-checks OK
overpower bool Whether an overpower condition has occured
timestamp number Unix timestamp of the last energy counter value
counters array of numbers Energy counter value for the last 3 round minutes in Watt-minute
total number Total energy consumed in Watt-minute

inputs attributes

Attribute Type Description
input number Current state of the input
event string Last input event, S=shortpush, L=longpush, ""=none/invalid
event_cnt number Event counter, uint16

input shows the current logical state of the input: 0=OFF and 1=ON. event provides a short string, designating the last detected input event (shortpush/longpush). event_cnt is incremented each time a new input event occurs. event_cnt is not stored in non-volatile memory.

Shelly RGBW2 Color: /color/0


GET /color/0

{
    "ison": true,
    "has_timer": false,
    "timer_started": 0,
    "timer_duration": 0,
    "timer_remaining": 0,
    "mode": "color",
    "red": 255,
    "green": 127,
    "blue": 0,
    "white": 0,
    "gain": 100,
    "effect": 0,
    "power": 0.46,
    "overpower": false
}

This endpoint controls the output and provides up-to-date state of the device in color mode.

Attributes

Attribute Type Description
ison bool Whether the output is ON or OFF
has_timer bool Whether a timer is currently armed for this channel
timer_started number Unix timestamp of timer start; 0 if timer inactive or time not synced
timer_duration number Timer duration, s
timer_remaining number experimental If there is an active timer, shows seconds until timer elapses; 0 otherwise
mode string Currently configured mode
red number Red brightness, 0..255
green number Green brightness, 0..255
blue number Blue brightness, 0..255
white number White brightness, 0..255
gain number Gain for all channels, 0..100
effect number Applied effect
power number Consumed power, W
overpower bool Whether an overpower condition has occurred

Parameters

Parameter Type Description
timer number Automatic flip-back timer in seconds, used in combination with turn
turn string Accepted values: on, off or toggle
red number Red brightness, 0..255
green number Green brightness, 0..255
blue number Blue brightness, 0..255
white number White brightness, 0..255
gain number Gain for all channels, 0..100
effect number Applies an effect

Shelly RGBW2 White

Shelly RGBW2 White: Overview

Shelly RGBW2 White is a WiFi-enabled 4-channel 12V/24V LED driver which can control the output channels independently. Via firmware change the same device can be used to control a single RGB+W installation, see Shelly RGBW2 Color.

https://shelly.cloud/products/shelly-rgbw2-smart-home-automation-led-controller/

Factory Reset

A factory reset can be performed over the local web interface or Shelly application. In case the device cannot be accessed over network, physical methods for factory reset exist:

Shelly RGBW2 White: MQTT


mosquitto_pub -t shellies/shellyrgbw2-11ABD9/white/2/set \
    -m '{"brightness":70}'

mosquitto_pub -t shellies/shellyrgbw2-11ABD9/white/2/set \
    -m '{"turn":"off","brightness":33}'

Shelly RGBW2 White allows for independent control of the 4 output channels with an identical set of MQTT topics. Channels are indexed 0 to 3.

Command topics

{
    "brightness": 50,   /* output brightness, 0..100 */
    "turn": "on"        /* "on", "off" or "toggle" */
}

Status topics

Information about each output channel is published on:

{
    "ison",             /* whether the output is ON or OFF */
    "has_timer",        /* whether a timer is currently armed for this channel */
    "timer_started",    /* unix timestamp of timer start; 0 if timer inactive or time not synced */
    "timer_duration",   /* timer duration, s */
    "timer_remaining",  /* if there is an active timer, shows seconds until timer elapses; 0 otherwise */
    "mode",             /* "white" */
    "brightness"        /* output brightness, 0..100 */
}

Shelly RGBW2 White: /settings


GET /settings

{
    "factory_reset_from_switch": true,
    "mode": "white",
    "dcpower": 1,
    "lights": [
        {
            "ison": true,
            "brightness": 20,
            "default_state": "on",
            "auto_on": 0,
            "auto_off": 0,
            "schedule": false,
            "btn_type": "toggle",
            "btn_reverse": 0,
            "schedule_rules": [],
            "out_on_url": "",
            "out_off_url": ""
        },
        {
            "ison": true,
            "brightness": 20,
            "default_state": "on",
            "auto_on": 0,
            "auto_off": 0,
            "schedule": false,
            "schedule_rules": [],
            "out_on_url": "",
            "out_off_url": ""
        },
        {
            "ison": true,
            "brightness": 20,
            "default_state": "on",
            "auto_on": 0,
            "auto_off": 0,
            "schedule": false,
            "schedule_rules": [],
            "out_on_url": "",
            "out_off_url": ""
        },
        {
            "ison": true,
            "brightness": 20,
            "default_state": "on",
            "auto_on": 0,
            "auto_off": 0,
            "schedule": false,
            "schedule_rules": [],
            "out_on_url": "",
            "out_off_url": ""
        }
    ],
    "actions": {
        "btn_on_url": "",
        "btn_off_url": "",
        "btn_longpush_url": "",
        "btn_shortpush_url": ""
    }
}

Attributes

Attribute Type Description
factory_reset_from_switch bool Whether factory reset via 5-time flip of the input switch is enabled
mode string Currently configured mode, color or white
dcpower number DC supply voltage 0=12V, 1=24V
lights array of hashes Output channel settings. See /settings/white/{index} for more details.
actions hash Action URLs. See /settings/white/{index} for more details.

3 additional parameters are supported on the /settings endpoint for RGBW2 White:

Parameters

Parameter Type Description
factory_reset_from_switch bool Enable/disable factory reset via 5-time flip of the input switch
mode string Set to color or white; determines the operating mode
dcpower bool Set to true for 24 V power supply, false for 12 V

Shelly RGBW2 White: /settings/white/{index}


GET /settings/white/0

{
    "ison": true,
    "brightness": 50,
    "default_state": "on",
    "auto_on": 0,
    "auto_off": 0,
    "schedule": false,
    "btn_type": "toggle",
    "btn_reverse": 0,
    "schedule_rules": [],
    "out_on_url": "",
    "out_off_url": ""
}

Attributes

Attribute Type Description
ison bool Whether the outputs are ON or OFF
brightness number Output level, 0..100
default_state string One of on, off or last
auto_on number ON-timer value, s
auto_off number OFF-timer value, s
btn_type string Input type, one of momentary, toggle, edge, detached or action
btn_reverse number Whether the logical state of the input is inverted
schedule bool Whether scheduling is enabled
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on
out_on_url string URL to access when output is activated
out_off_url string URL to access when output is deactivated

Each output channel's settings are individually controlled when the device operates in white mode with the exception of btn_type and btn_reverse: they are shared for all channels (and are only visible in /settings/white/0)

Parameters

Parameter Type Description
reset any Any non-zero-length value will reset light settings to default
default_state string Sets default power-on state: on, off or last
auto_on number Sets a default timer to turn ON after every OFF command in seconds
auto_off number Sets a default timer to turn OFF after every ON command in seconds
btn_type string Input type: momentary, toggle, edge, detached or action
btn_reverse bool Whether to invert external switch input
schedule bool Enable schedule timer
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on
btn_on_url string Set URL to access when input switch is activated
btn_off_url string Set URL to access when input switch is deactivated
btn_longpush_url string Set URL to access when input switch is held down
btn_shortpush_url string Set URL to access when input switch is pressed briefly
out_on_url string Set URL to access when output is activated
out_off_url string Set URL to access when output is deactivated

Shelly RGBW2 White: /status


GET /status

{
    "mode": "white",
    "input": 0,
    "total_power": 0,
    "lights": [
        {
            "ison": true,
            "has_timer": false,
            "timer_started": 0,
            "timer_duration": 0,
            "timer_remaining": 0,
            "mode": "white",
            "brightness": 20
        },
        {
            "ison": true,
            "has_timer": false,
            "timer_started": 0,
            "timer_duration": 0,
            "timer_remaining": 0,
            "mode": "white",
            "brightness": 20
        },
        {
            "ison": true,
            "has_timer": false,
            "timer_started": 0,
            "timer_duration": 0,
            "timer_remaining": 0,
            "mode": "white",
            "brightness": 20
        },
        {
            "ison": true,
            "has_timer": false,
            "timer_started": 0,
            "timer_duration": 0,
            "timer_remaining": 0,
            "mode": "white",
            "brightness": 20
        }
    ],
    "meters": [
        {
            "power": 0.46,
            "is_valid": true,
            "overpower": false,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        },
        {
            "power": 0.46,
            "is_valid": true,
            "overpower": false,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        },
        {
            "power": 0.46,
            "is_valid": true,
            "overpower": false,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        },
        {
            "power": 0.46,
            "is_valid": true,
            "overpower": false,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        }
    ],
    "inputs": [
        {
            "input": 0,
            "event": "S",
            "event_cnt": 2
        }
    ]
}

Attributes

Attribute Type Description
mode string Currently configured mode, color or white
input number State of the SW input
total_power number Total power consumed by all channels, W
lights array of hashes Contains the current state of the light channels. See /white/{index} for description of attributes
meters array of hashes Power and energy information, see description below
inputs array of hashes Current state of the inputs, see description below

meters attributes

Attribute Type Description
power number Power consumption, W
is_valid bool Whether power metering self-checks OK
overpower bool Whether an overpower condition has occured
timestamp number Unix timestamp of the last energy counter value
counters array of numbers Energy counter value for the last 3 round minutes in Watt-minute
total number Total energy consumed in Watt-minute

inputs attributes

Attribute Type Description
input number Current state of the input
event string Last input event, S=shortpush, L=longpush, ""=none/invalid
event_cnt number Event counter, uint16

input shows the current logical state of the input: 0=OFF and 1=ON. event provides a short string, designating the last detected input event (shortpush/longpush). event_cnt is incremented each time a new input event occurs. event_cnt is not stored in non-volatile memory.

Shelly RGBW2 White: /white/{index}


GET /white/0

{
    "ison": true,
    "has_timer": false,
    "timer_started": 0,
    "timer_duration": 0,
    "timer_remaining": 0,
    "mode": "white",
    "brightness": 20
}

This endpoint controls each output channel in white mode and can be used for monitoring thereof.

Attributes

Attribute Type Description
ison bool Whether the output is ON or OFF
has_timer bool Whether a timer is currently armed for this channel
timer_started number Unix timestamp of timer start; 0 if timer inactive or time not synced
timer_duration number Timer duration, s
timer_remaining number experimental If there is an active timer, shows seconds until timer elapses; 0 otherwise
mode string Currently configured mode
brightness number Output brightness, 0..100

Parameters

Parameter Type Description
timer number Automatic flip-back timer in seconds, used in combination with turn
turn string Accepted values: on, off or toggle
brightness number Brightness, 0..100, applies in mode="white"

Shelly Dimmer/SL

Shelly Dimmer

Shelly Dimmer/SL: Overview

Shelly Dimmer/SL is a new smart switch, and this one doesn’t just turn lights on and off, it dims them. Shelly Dimmer/SL can be found on https://shelly.cloud/products/shelly-dimmer-2-smart-home-light-contoller/

Shelly Dimmer/SL can be used with:

Shelly Dimmer SL has the same features as Shelly Dimmer, the only difference being that neutral connection is not required.

Factory Reset

Shelly Dimmer/SL: MQTT

Shelly Dimmer/SL allows on and off commands, as well as brightness:

Topic Description
shellies/shellydimmer-<deviceid>/light/0/command accepts on and off payloads
shellies/shellydimmer-<deviceid>/light/0/set accepts a JSON payload in the format {"brightness": 100, "turn": "on"}, see description below
{
    "brightness": 100,  /* output brightness 1..100 */
    "turn": "on"        /* one of "on", "off", or "toggle" */
}

Status information about Shelly Dimmer/SL can be accessed on:

Topic Description
shellies/shellydimmer-<deviceid>/input/<i> for each SW input <i>; reports the current state as 0 or 1
shellies/shellydimmer-<deviceid>/longpush/<i> for each SW input <i>; reports a value indicating longpush state as 0 (shortpush) or 1 (longpush)
shellies/shellydimmer-<deviceid>/input_event/<i> for each SW input <i>; reports input event and event counter, e.g.: {"event":"S","event_cnt":2} see /status for details
shellies/shellydimmer-<deviceid>/temperature reports device temperature in Celsius
shellies/shellydimmer-<deviceid>/temperature_f reports device temperature in Fahrenheit
shellies/shellydimmer-<deviceid>/overtemperature reports overtemperature condition
shellies/shellydimmer-<deviceid>/overload reports overload condition
shellies/shellydimmer-<deviceid>/loaderror reports load error condition
shellies/shellydimmer-<deviceid>/light/0 reports on/оff status
shellies/shellydimmer-<deviceid>/light/0/power reports power consumption, W
shellies/shellydimmer-<deviceid>/light/0/energy reports total energy consumed, W-min
shellies/shellydimmer-<deviceid>/light/0/status reports periodic status, see description below
{
    "ison",            /* whether the channel is turned ON or OFF */
    "has_timer",       /* whether a timer is currently armed for this channel */
    "timer_started",   /* unix timestamp of timer start; 0 if timer inactive or time not synced */
    "timer_duration",  /* timer duration, s */
    "timer_remaining", /* if there is an active timer, shows seconds until timer elapses; 0 otherwise */
    "mode",            /* always `white` */
    "brightness"       /* output brightness, `1..100` */
}

Shelly Dimmer/SL: /settings


GET /settings
{
    "factory_reset_from_switch": true,
    "mode": "white",
    "pulse_mode": 0,
    "calibrated": false,
    "transition": 0,
    "fade_rate": 0,
    "min_brightness": 20,
    "lights": [
        {
            "name": null,
            "ison": true,
            "default_state": "off",
            "auto_on": 0,
            "auto_off": 0,
            "btn1_on_url": "http://192.168.63.189:8080/b1ON",
            "btn1_off_url": "http://192.168.63.189:8080/b1OFF",
            "btn1_longpush_url": "",
            "btn1_shortpush_url": "",
            "btn2_on_url": "http://192.168.63.189:8080/b2ON",
            "btn2_off_url": "http://192.168.63.189:8080/b2OFF",
            "btn2_longpush_url": "",
            "btn2_shortpush_url": "",
            "out_on_url": "http://192.168.63.189:8080/outON",
            "out_off_url": "http://192.168.63.189:8080/outOFF",
            "schedule": true,
            "schedule_rules": [
                "1720-0123456-120@50%",
                "0000-0123456-123@35%"
                ],
            "btn_type": "edge",
            "btn_debounce": 80,
            "swap_inputs": 0
        }
    ],
    "night_mode": {
        "enabled": false,
        "start_time": "00:00",
        "end_time": "00:00",
        "brightness": 20
    },
    "warm_up": {
        "enabled": 0,
        "brightness": 0,
        "time": 20
    }
}

Shelly Dimmer/SL supports only one mode - white. It supports a single channel, indexed as 0.

Attributes

Attribute Type Description
factory_reset_from_switch bool Whether factory reset via 5-time flip of the input switch is enabled
mode string Currently configured mode
pulse_mode number 1 - Leading Edge Dimming, 2 - Trailing Edge Dimming
calibrated bool Calibration flag
transition number Transition time for on/off: 0..5000 ms
fade_rate number Brightness change speed when button is pressed: 1..5
min_brightness number Min brightness
lights array of hashes Output channel settings, see /settings/light/0 for more details
night_mode hash Night mode settings, see /settings/night_mode
warm_up hash Warm up settings, see /settings/warm_up

Parameters

Parameter Type Description
factory_reset_from_switch bool Enable/disable factory reset via 5-time flip of the input switch
pulse_mode number 1 - Leading Edge Dimming, 2 - Trailing Edge Dimming
transition number Transition time for on/off: 0..5000 ms
fade_rate number Brightness change speed when button is pressed: 1..5
min_brightness number Min brightness 0..50
calibrate number 0 - Delete calibration, 1 - Start calibration
calibrate_cancel number 1 - Cancel calibration

Shelly Dimmer/SL: /settings/light/0


GET /settings/light/0
{
    "name": null,
    "ison": true,
    "default_state": "off",
    "auto_on": 0,
    "auto_off": 0,
    "btn1_on_url": "http://192.168.63.189:8080/b1ON",
    "btn1_off_url": "http://192.168.63.189:8080/b1OFF",
    "btn1_longpush_url": "",
    "btn1_shortpush_url": "",
    "btn2_on_url": "http://192.168.63.189:8080/b2ON",
    "btn2_off_url": "http://192.168.63.189:8080/b2OFF",
    "btn2_longpush_url": "",
    "btn2_shortpush_url": "",
    "out_on_url": "http://192.168.63.189:8080/outON",
    "out_off_url": "http://192.168.63.189:8080/outOFF",
    "schedule": true,
    "schedule_rules": [
        "1720-0123456-120@50%",
        "0000-0123456-123@35%"
        ],
    "btn_type": "edge",
    "btn_debounce": 80,
    "swap_inputs": 0
}

Attributes

Attribute Type Description
name string Name
ison bool Dimmer is on or off
default_state string Default power-on state, one of on, off, last, switch
auto_on number Default timer to turn the dimmer ON after every OFF command in seconds
auto_off number Default timer to turn the dimmer OFF after every ON command in seconds
btn1_on_url string URL to access when SW1 input is activated
btn1_off_url string URL to access when SW1 input is deactivated
btn1_longpush_url string URL to access when SW1 input is held down. Works only when button is configured as detached
btn1_shortpush_url string URL to access when SW1 input is pressed briefly. Works only when button is configured as detached
btn2_on_url string URL to access when SW2 input is activated
btn2_off_url string URL to access when SW2 input is deactivated
btn2_longpush_url string URL to access when SW2 input is held down. Works only when button is configured as detached
btn2_shortpush_url string URL to access when SW2 input is pressed briefly. Works only when button is configured as detached
out_on_url string URL to access when output is activated
out_off_url string URL to access when output is deactivated
btn_type string Input type: one of one_button, dual_button, toglle, edge, detached, action
btn_debounce number Button debounce time, ms
swap_inputs bool Swap inputs
schedule bool Whether scheduling is enabled
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on

Parameters

Parameter Type Description
reset any Perform settings reset
default_state string Default power-on state, one of on, off, last, switch
auto_on number Default timer to turn the dimmer ON after every OFF command in seconds
auto_off number Default timer to turn the dimmer OFF after every ON command in seconds
schedule bool Enable scheduling timer
schedule_rules array of strings String values for sheduling in ir format see description below
btn_type string Input type: one of one_button, dual_button, toglle, edge, detached or action
btn_debounce number Set button debounce time, 60..200ms
swap_inputs bool Swap inputs
btn1_on_url string URL to access when SW1 input is activated
btn1_off_url string URL to access when SW1 input is deactivated
btn1_longpush_url string URL to access when SW1 input is held down. Works only when button is configured as detached
btn1_shortpush_url string URL to access when SW1 input is pressed briefly. Works only when button is configured as detached
btn2_on_url string URL to access when SW2 input is activated
btn2_off_url string URL to access when SW2 input is deactivated
btn2_longpush_url string URL to access when SW2 input is held down. Works only when button is configured as detached
btn2_shortpush_url string URL to access when SW2 input is pressed briefly. Works only when button is configured as detached
out_on_url string URL to access when output is activated
out_off_url string URL to access when output is deactivated

Shelly Dimmer/SL: /settings/night_mode


GET /settings/night_mode

{
    "enabled": false,
    "start_time": "00:00",
    "end_time": "00:00",
    "brightness": 20
}

When night mode is active, turning ON the device during the set interval it will only go up to the pre-set brightness limit.

Parameters

Parameter Type Description
enabled bool Enable/disable night mode
start_time string Set night mode start time in format hh:mm
end_time string Set night mode end time in format hh:mm
brightness number Set night mode brightness in percent 1..100

Shelly Dimmer/SL: /settings/warm_up


GET /settings/warm_up

{
    "enabled": 0,
    "brightness": 0,
    "time": 20
}

Specify a startup warmup brightness for a short period of time.

Parameters

Parameter Type Description
enabled bool Enable/disable warm up
brightness number Set warm up brightness in percent 10..100
time number Set warm up time 20..200ms

Shelly Dimmer/SL: /status


GET /status

{
    "lights": [
        {
            "ison": false,
            "has_timer": false,
            "timer_started": 0,
            "timer_duration": 0,
            "timer_remaining": 0,
            "mode": "white",
            "brightness": 50
        }
    ],
    "meters": [
        {
            "power": 0,
            "is_valid": true,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        }
    ],
    "inputs": [
        {
            "input": 0,
            "event": "S",
            "event_cnt": 2
        },
        {
            "input": 0,
            "event": "L",
            "event_cnt": 4
        }
    ],
    "tmp": {
        "tC": 50.3,
        "tF": 122.54,
        "is_valid": true
    },
    "calib_progress": 0,
    "overtemperature": false,
    "loaderror": false,
    "overload": false
}

Attributes

Attribute Type Description
lights array of hashes Contains the current state of the dimmer output channels. See /light/0 for description of attributes
meters array of hashes Current status of the power meters, see description below
inputs array of hashes Current state of the inputs, see description below
tmp.tC number Device temperature in °C
tmp.tF number Device temperature in °F
tmp.is_valid bool Whether device temperature is valid
calib_progress number Calibration progress
overtemperature bool Whether an overtemperature condition has occurred
loaderror bool Whether a load error has occurred
overload bool Whether an overload condition has occurred

meters attributes

Attribute Type Description
power number Current power being drawn, in Watts
is_valid bool Whether power metering self-checks OK
timestamp number Unix timestamp of the last energy counter value
counters array of numbers Energy counter value for the last 3 round minutes in Watt-minute
total number Total energy consumed in Watt-minute

inputs.{index} attributes

Attribute Type Description
input number Current state of the input 0/1
event string Last input event, S=shortpush, L=longpush, ""=none/invalid
event_cnt number Event counter, uint16

input shows the current logical state of the input: 0=OFF and 1=ON. event provides a short string, designating the last detected input event (shortpush/longpush). event_cnt is incremented each time a new input event occurs. event_cnt is not stored in non-volatile memory.

Shelly Dimmer/SL: /light/0


GET /light/0

{
    "ison": false,
    "has_timer": false,
    "timer_started": 0,
    "timer_duration": 0,
    "timer_remaining": 0,
    "mode": "white",
    "brightness": 50
}

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

Attributes

Attribute Type Description
ison bool Whether the channel is turned ON or OFF
has_timer bool Whether a timer is currently armed for this channel
timer_started number Unix timestamp of timer start; 0 if timer inactive or time not synced
timer_duration number Timer duration, s
timer_remaining number experimental If there is an active timer, shows seconds until timer elapses; 0 otherwise
mode string Always white
brightness number Output brightness, 1..100

Parameters

Parameter Type Description
timer number A one-shot flip-back timer in seconds
turn string Command to turn on, off or toggle
brightness number Brightness, 1..100

Shelly Sense

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

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:

Topic Description
shellies/shellysense-<deviceid>/sensor/motion true when motion is detected, false otherwise
shellies/shellysense-<deviceid>/sensor/charger Whether external power is available, true or false
shellies/shellysense-<deviceid>/sensor/temperature In °C or °F depending on configuration
shellies/shellysense-<deviceid>/sensor/humidity RH in %
shellies/shellysense-<deviceid>/sensor/lux Illuminance in Lux
shellies/shellysense-<deviceid>/sensor/battery Battery level in %

Shelly Sense: /settings

The settings for Shelly Sense are:

GET /settings/
{
    "light_sensor": "NOA1305",
    "schedule": false,
    "schedule_rules": [],
    "sensors": {
        "motion_duration": 20,
        "motion_led": true,
        "temperature_unit": "C"
    }
}

Attributes

Attribute Type Description
light_sensor string Light sensor type name
schedule bool Schedule timer enabled/disabled
schedule_rules array of strings Definition of scheduling rules
sensors.motion_duration number Duration time in seconds for motion flag after motion detection
sensors.motion_led bool Whether LED light should indicate motion detected
sensors.temperature_unit string Temperature units: C for Celsius and F for Fahrenheit

Parameters

Parameter Type Description
temperature_units string Set temperature units: C for Celsius and F for Fahrenheit
pir_motion_duration_time number Set duration time in seconds for motion flag after motion detection
pir_motion_led bool Set whether LED light should indicate motion detected
schedule bool Enable/disable scheduling timer
schedule_rules array of strings Add or Remove weekly schedule. See description below

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)

Parameters

Parameter Type Description
schedule bool Activate/Deactivate schedules
schedule_rules array of strings Set schedule rules

Shelly Sense Schedule rules: /settings/?schedule_rules

A schedule rule is a string that contains:

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

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:

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
{
    "motion": false,
    "charger": false,
    "tmp": {
        "value": 9.55536,
        "is_valid": true,
        "units": "C"
    },
    "hum": {
        "value": 85.548308,
        "is_valid": true,
    },
    "lux":{
        "value": 3.896104,
        "is_valid": true,
    },
    "bat":{
        "value": 100
    }
}

Shelly Sense status command gives information about the device and all sensors status.

Attributes

Attribute Type Description
motion bool Motion detection
charger bool Charging status
tmp hash Temperature information
hum hash Humidity information
lux hash Brightness information
bat hash Battery level

Shelly Sense: /ir

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

Parameters

Parameter Type Description
list string List for stored infrared devices in Shelly Sense
add string Add new device into Shelly Sense. For more information see /ir/add
remove string Remove IR code or device stored in Shelly Sense. See /ir/remove
emit string 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 string ID of the stored IR code into Shelly Sense
name string 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 string ID of the IR code
name string Short description or name of the stored IR code
pronto string IR pronto code base64

Shelly Sense: /ir/remove

Shelly Sense API support few ways to remove codes:


 GET /ir/remove?

Parameters

Parameter Type Description
ID string ID of the stored IR code into Shelly Sense
all string Remove all pronto codes from Shelly Sense
prefix string 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 Sense using:


 GET /ir/emit

Parameters

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

Shelly H&T

Shelly H&T

Shelly H&T: Overview

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

https://shelly.cloud/products/shelly-humidity-temperature-smart-home-automation-sensor/

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.

Shelly H&T: MQTT

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

Shelly H&T: /settings

GET /settings

{
    "device": {
        "sleep_mode": true
    },
    "sensors": {
        "temperature_threshold": 1,
        "temperature_unit": "C",
        "humidity_threshold": 5
    },
    "sleep_mode": {
        "period": 12,
        "unit": "h"
    },
    "report_url": "",
    "external_power": 0,
    "temperature_offset": 0,
    "humidity_offset": 0
}

Attributes

Attribute Type Description
device.sleep_mode bool Always true
sensors.temperature_threshold number Temperature delta (in °C) which triggers an update
sensors.temperature_unit string Either C or F
sensors.humidity_threshold number Humidity delta (in %) which triggers an update
sleep_mode.period number Periodic update period in sleep_mode.unit, depends on external_power (12h if external_power=0, 10m if external_power=1)
sleep_mode.unit string m or h
report_url string URL to report sensor events on (/?temp=999.99&hum=100)
external_power number Whether external power supply is installed
temperature_offset number Temperature offset (in °C)
humidity_offset number Humidity offset (in %)

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 °C) which triggers an update, 0..15
humidity_threshold number Humidity delta (in %) which triggers an update, 0..100
report_url string Set URL to report sensor events on
external_power bool Set if external power supply is installed
temperature_offset number Temperature offset (in °C), -50..50
humidity_offset number Humidity offset (in %), -50..50

Shelly H&T: /status

GET /status

{
    "is_valid": true,
    "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"
    ],
    "connect_retries": 0
}

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

Attributes

Parameter Type Description
is_valid bool Whether ht sensor self-checks OK
tmp.value number Temperature in configured units
tmp.units string C or F
tmp.tC number Temperature in °C
tmp.tF number Temperature in °F
tmp.is_valid bool Whether the internal sensor is operating properly
hum.value number Relative humidity in %
hum.is_valid bool Whether the internal sensor is operating properly
bat.value number Estimated remaining battery capacity in %, 0..100
bat.voltage number Battery voltage, V
act_reasons array of strings List of reasons which woke up the device: battery, button, periodic, poweron, sensor, alarm
connect_retries number WiFi connect retries
sensor_error number Only displayed in case of error

Shelly Smoke

ShellySmoke

Shelly Smoke: Overview

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

https://shelly.cloud/products/shelly-smoke-smart-home-automation-sensor/

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.

Shelly Smoke: MQTT

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

Shelly Smoke: /settings

GET /settings

{
    "device": {
        "sleep_mode": true
    },
    "sensors": {
        "temperature_threshold": 1,
        "temperature_unit": "C",
    },
    "sleep_mode": {
        "period": 12,
        "unit": "h"
    },
    "temperature_offset": 0
}

Attributes

Attribute Type Description
device.sleep_mode bool Always true
sensors.temperature_threshold number Temperature delta (in °C) which triggers an update
sensors.temperature_unit string Either C or F
sleep_mode.period number Periodic update period in hours, always 12
sleep_mode.unit string Always h
temperature_offset number Temperature offset (in °C)

Shelly Smoke accepts the following extra parameters on its /settings endpoint:

Parameters

Parameter Type Description
temperature_units string Either C or F
temperature_threshold number Temperature delta (in °C) which triggers an update, 0..15
temperature_offset number Temperature offset (in °C), -50..50

Shelly Smoke: /status

GET /status

{
    "is_valid": true,
    "smoke": false,
    "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
is_valid bool Whether smoke sensor self-checks OK
smoke bool Wheter smoke is detected
tmp.value number Temperature in configured unites
tmp.units string C or F
tmp.tC number Temperature in °C
tmp.tF number Temperature in °F
tmp.is_valid bool Whether the internal temperature sensor is operating properly
bat.value number Estimated remaining battery capacity in %, 0..100
bat.voltage number Battery voltage, V
act_reasons array of strings List of reasons which woke up the device, may contain either of: battery, button, periodic, poweron, sensor, alarm.
sensor_error number Only displayed in case of error

Shelly Flood

Shelly Flood

Shelly Flood: Overview

Shelly Flood is a WiFi-connected water-leak sensor.

Product page

Shelly Flood normally keeps its WiFi controller shut down and only wakes up when an update is due or an event needs to be reported. 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.

When Rain Mode is enabled, the device will not raise any alarms when water is detected. Instead, it will just report the event and go back to sleep. Another event update will be sent when the water clears.

Factory Reset

To restore Shelly Flood to its factory settings:

Shelly Flood: MQTT

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

Shelly Flood: /settings

GET /settings

{
    "device": {
        "sleep_mode": true
    },
    "sensors": {
        "temperature_threshold": 1,
        "temperature_unit": "C"
    },
    "sleep_mode": {
        "period": 12,
        "unit": "h"
    },
    "report_url": "",
    "flood_detected_url": "",
    "flood_gone_url": "",
    "rain_sensor": false
}

Attributes

Attribute Type Description
device.sleep_mode bool Always true
sensors.temperature_threshold number Temperature delta (in °C) which triggers an update
sensors.temperature_unit string Either C or F
sleep_mode.period number Periodic update period in hours, between 1 and 24
sleep_mode.unit string Always h
report_url string URL to report sensor events on (/?temp=999.99&flood=0&batV=1.00)
flood_detected_url string URL to access when flood is detected
flood_gone_url string URL to access when flood is gone
rain_sensor bool Whether Rain Mode is enabled (no buzzer and report only when water changes)

Shelly Flood 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 °C) which triggers an update, 0..15
sleep_mode_period number Periodic update period in hours, 1..24
report_url string Set URL to report sensor events on
flood_detected_url string Set URL to access when flood is detected
flood_gone_url string Set URL to access when flood is gone
rain_sensor bool Enable/disable Rain Mode (no buzzer and report only when water changes)

Shelly Flood: /status

GET /status

{
    "is_valid": true,
    "flood": false,
    "tmp": {
        "value": 20,
        "units": "C",
        "tC": 20,
        "tF": 68,
        "is_valid": true
    },
    "bat": {
        "value": 71,
        "voltage": 2.73
    },
    "act_reasons": [
        "periodic"
    ],
    "rain_sensor": false
}

Attributes

Parameter Type Description
is_valid bool Whether flood sensor self-checks OK
flood bool Wheter a flood condition is detected
tmp.value number Temperature in configured units
tmp.units string C or F
tmp.tC number Temperature in °C
tmp.tF number Temperature in °F
tmp.is_valid bool Whether the internal temperature sensor is operating properly
bat.value number Estimated remaining battery capacity in %, 0..100
bat.voltage number Battery voltage, V
act_reasons array of strings List of reasons which woke up the device: battery, button, periodic, poweron, sensor, alarm
rain_sensor bool Whether Rain Mode is enabled (no buzzer and report only when water changes)
sensor_error number Only displayed in case of error

Shelly Door/Window

ShellyDoorWindow

Shelly Door/Window: Overview

Shelly Door/Window is a WiFi-connected door and window sensor with lux measurement.

Product page

Factory Reset

To restore Shelly Door/Window to its factory settings:

Shelly Door/Window: MQTT

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

Shelly Door/Window: /settings

GET /settings

{
    "device": {
        "sleep_mode": true
    },
    "dark_threshold": 100,
    "twilight_threshold": 300,
    "sleep_mode": {
        "period": 6,
        "unit": "h"
    },
    "led_status_disable": true,
    "dark_url": null,
    "twilight_url": null,
    "close_url": null,
    "vibration_url": null,
    "tilt_enabled": false,
    "tilt_calibrated": false,
    "vibration_enabled": false,
    "reverse_open_close": false
}

Attributes

Attribute Type Description
device.sleep_mode bool Always true
dark_threshold number Illumination definition for "dark" in lux
twilight_threshold number Illumination definition for "twilight" in lux
sleep_mode.period number Periodic update period in hours, 1..24
sleep_mode.unit string Always h
led_status_disable bool Whether status LED is enabled/disabled
dark_url string URL to invoke when luminance <= dark_threshold
twilight_url string URL to invoke when luminance > dark_threshold AND luminance <= twilight_threshold
close_url string URL to invoke on close
vibration_url string URL to invoke on vibration detection
tilt_enabled bool Whether tilt monitoring is activated
tilt_calibrated bool Whether calibration data is valid
vibration_enabled bool Whether vibration monitoring is activated
reverse_open_close bool Whether to reverse which position the sensor consideres "open"

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

Parameters

Parameter Type Description
dark_threshold number Illumination definition for "dark" in lux, 0..100000 and must be lower than twilight_threshold
twilight_threshold number Illumination definition for "dusk" in lux, 0..100000 and must be greater than dark_threshold
dark_url string Set URL to invoke when luminance <= dark_threshold
twilight_url string Set URL to invoke when luminance > dark_threshold AND luminance <= twilight_threshold
close_url string Set URL to invoke on close
vibration_url string Set URL to invoke on vibration detection
led_status_disable bool Enable/disable status LED
sleep_mode_period number Periodic update period in hours, 1..24
reverse_open_close bool Reverse which position the sensor consideres "open"
tilt_enabled bool Enable/disable tilt detection
vibration_enabled bool Enable/disable vibration detection

Shelly Door/Window: /status

GET /status

{
    "is_valid": true,
    "lux": {
        "value": 0,
        "illumination": "dark",
        "is_valid": true
    },
    "accel": {
        "tilt": 0,
        "vibration": 1,
        "vibration_time": 60,
    }, 
    "sensor": {
        "state": "close",
        "is_valid": true
    },
    "bat": {
        "value": 71,
        "voltage": 2.73
    },
    "act_reasons": [
        "periodic"
    ]
}

Attributes

Parameter Type Description
is_valid bool Whether door/window sensor self-checks OK
lux.value number Luminance level, lux
lux.illumination string One of dark, twilight or bright; depends on dark_threshold and twilight_threshold
lux.is_valid bool Whether the internal luminance sensor is operating properly
accel.tilt number Tilt in °, 0..180
accel.vibration number Whether vibration is detected 0/1, -1 if vibration detection is disabled
accel.vibration_time number If vibration is detected, displays validity time in seconds
sensor.state string Door/window sensor state: open or close
sensor.is_valid bool Whether door/window sensor self-checks OK
bat.value number Estimated remaining battery capacity in %, 0..100
bat.voltage number Battery voltage, V
act_reasons array of strings List of reasons which woke up the device: battery, button, periodic, poweron, sensor, alarm
sensor_error number Only displayed in case of error

Shelly Door/Window: /calibrate

Parameters

Parameter Type Description
clear bool true = clear calibration
opened bool true = request calibration of opened position, false = request calibration of closed position

Shelly Gas

ShellyGas

Shelly Gas: Overview

Shelly Gas is a sensor which can measure combustible gas concentration and issue an alarm in the event of a gas leak. Shelly Gas operates on AC voltage.

The product page has all key features described and User Manual.

LED

The center circle-shaped LED indicates the sensor status:

Factory Reset

To perform a factory reset on a Shelly Gas device:

Shelly Gas: MQTT

Shelly Gas publishes on the following MQTT topics:

MQTT topic Message
shellies/shellygas-<deviceid>/sensor/operation unknown = Sensor state is unknown
warmup = Sensor is warming up
normal = Sensor is in normal operation
fault = Sensor has a fault
shellies/shellygas-<deviceid>/sensor/gas unknown = Alarm state is unknown
none = There is no alarm
mild = There is a mild gas leak
heavy = There is a heavy gas leak
test = Issued after a successful self-test
shellies/shellygas-<deviceid>/sensor/self_test not_completed = Self-test not completed
completed = Self-test completed
running = Self-test is running
pending = Self-test scheduled to run
shellies/shellygas-<deviceid>/sensor/concentration Gas concentration in parts per million: [0..65535], -1 if not valid

Note: by default, Shelly Gas will send periodic MQTT updates every 30 seconds. You can turn these off and only receive messages when there is a change by setting the mqtt_update_period parameter to 0 (see /settings).

Shelly Gas subscribes to the following MQTT topics:

MQTT topic Message
shellies/shellygas-<deviceid>/sensor/start_self_test Any message triggers sensor self-test
shellies/shellygas-<deviceid>/sensor/mute Any message mutes an active alarm
shellies/shellygas-<deviceid>/sensor/unmute Any message unmutes an active alarm

Shelly Gas: /settings

GET /settings

{
    "set_volume": 11,
    "alarm_off_url": "http://xxx",
    "alarm_mild_url": "http://xxx",
    "alarm_heavy_url": "http://xxx"
}

Attributes

Attribute Type Description
set_volume number Buzzer volume [1 (lowest) .. 11 (highest)]
alarm_off_url string URL to access when gas alarm is gone
alarm_mild_url string URL to access when there is a mild gas alarm
alarm_heavy_url string URL to access when there is a heavy gas alarm

Shelly Gas extends the common /settings endpoint with the following parameters:

Parameters

Parameter Type Description
set_volume number Set the buzzer volume [1 (lowest) .. 11 (highest)]
alarm_off_url string Set URL to access when gas alarm is gone
alarm_mild_url string Set URL to access when there is a mild gas alarm
alarm_heavy_url string Set URL to access when there is a heavy gas alarm

Shelly Gas: /status

GET /status

{
    "gas_sensor": {
        "sensor_state": "normal",
        "self_test_state": "completed",
        "alarm_state": "none"
    },
    "concentration": {
        "ppm": 100,
        "is_valid": true
    },
}

Attributes

Shelly Gas extends the common /status endpoint with the following attributes:

Attribute Type Description
gas_sensor.sensor_state string unknown = Sensor state is unknown
warmup = Sensor is warming up
normal = Sensor is in normal operation
fault = Sensor has a fault
gas.sensor.self_test_state string not_completed = Self-test not completed
completed = Self-test completed
running = Self-test is running
pending = Self-test scheduled to run
gas.sensor.alarm_state string unknown = Alarm state is unknown
none = There is no alarm
mild = There is a mild gas leak
heavy = There is a heavy gas leak
test = Issued after a successful self-test
concentration.ppm number Gas concentration in parts per million, [0..65535]
concentration.is_valid bool false = ppm value is not valid
true = ppm value is valid

Shelly Gas: /self_test

GET /self_test

{
    "ok": true
}

Start sensor self-test

Shelly Gas: /mute

GET /mute

{
    "ok": true
}

Mute active alarm

Shelly Gas: /unmute

GET /mute

{
    "ok": true
}

Unmute active alarm

Shelly EM

Shelly EM

Shelly EM: Overview

Shelly EM measures electrical consumption on two channels (shared phase) and allows for controlling one low-power external appliance.

Product page

Factory Reset

To perform a factory reset, if doing so from the web interface or application is not possible -- press and hold the built-in user button until the LED starts blinking rapidly.

Shelly EM: MQTT

When configured for MQTT Shelly EM reports data on:

Note, that energy and returned_energy do not survive power cycle or reboot -- this is how the value is implemented on other Shellies. Shelly EM features a persisted version which is not affected by power cycling or lack of connectivity. To get the persisted counters use total and total_returned.

Commands are accepted on:

Shelly EM: /settings

GET /settings

{
    "relays": [
        {
            "name": null,
            "ison": false,
            "has_timer": false,
            "overpower": false,
            "default_state": "off",
            "auto_on": 0,
            "auto_off": 0,
            "out_on_url": null,
            "out_off_url": null,
            "schedule": false,
            "schedule_rules": []
        }
    ],
    "emeters": [
        {
            "ctraf_type": 50,
            "over_power_url": null,
            "over_power_url_threshold": 0,
            "under_power_url": null,
            "under_power_url_threshold": 0,
            "max_power": 0
        },
        {
            "ctraf_type": 50,
            "over_power_url": null,
            "over_power_url_threshold": 0,
            "under_power_url": null,
            "under_power_url_threshold": 0,
            "max_power": 0
        }
    ]
}

Attributes

Attribute Type Description
relays array of hashes Relay settings, see /settings/relay/0
emeters array of hashes EM channels configuration, see /settings/emeter/{index}

Common parameters apply for the /settings endpoint. Additionally:

Parameters

Parameter Type Description
set_time string Time and date manual setting in format [yyyy][mm][dd][hh][mm][ss][utc_offset_sec], for example settings/?set_time=20200328151600-120 means 2020-03-28 15:16:00

Shelly EM: /settings/relay/0

GET /settings/relay/0

{
    "name": null,
    "ison": false,
    "has_timer": false,
    "overpower": false,
    "default_state": "off",
    "auto_on": 0,
    "auto_off": 0,
    "out_on_url": null,
    "out_off_url": null,
    "schedule": false,
    "schedule_rules": []
}

This is identical to /settings/relay/{index} endpoints on most other Shelly devices with built in relays. The returned document 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.

Attributes

Attribute Type Description
name string Relay name
ison bool Relay state
has_timer bool Whether there is an active timer
overpower bool Whether an overpower condition has occurred
default_state string State on power-on, one of off, on, last, switch
auto_on number Automatic flip back timer, seconds
auto_off number Automatic flip back timer, seconds
out_on_url string URL to access when output is activated
out_off_url string URL to access when output is deactivated
schedule bool Whether scheduling is enabled
schedule_rules array of strings Rules for schedule activation

Parameters

Parameter Type Description
reset any Submitting a non-empty value will reset settings for the output to factory defaults
name string Set relay name
default_state string Accepted values: off, on, last, switch
auto_on number Automatic flip back timer, seconds. Will engage after turning OFF
auto_off number Automatic flip back timer, seconds. Will engage after turning ON
out_on_url string URL to access when output is activated
out_off_url string URL to access when output is deactivated
schedule bool Enable schedule timer
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on

Shelly EM: /settings/emeter/{index}

GET /settings/emeter/0

{
    "ctraf_type": 50,
    "over_power_url": null,
    "over_power_url_threshold": 0,
    "under_power_url": null,
    "under_power_url_threshold": 0,
    "max_power": 0
}

This endpoint allows for configuring over/under-power actions and max power protection.

Attributes

Attribute Type Description
ctraf_type number Current transformer type, 50 or 120 - currently unused
over_power_url string URL to invoke when over_power_url_threshold is reached
over_power_url_threshold number Over-power threshold, W
under_power_url string URL to invoke when under_power_url_threshold is reached
under_power_url_threshold number Under-power threshold, W
max_power number Maximum allowed power before contactor is switched off, W

Parameters

Parameter Type Description
ctraf_type number Set current transformer type, 50 or 120 - currently unused
over_power_url string Set URL to invoke when over_power_url_threshold is reached
over_power_url_threshold number Set over-power threshold, W
under_power_url string Set URL to invoke when under_power_url_threshold is reached
under_power_url_threshold number Set under-power threshold, W
max_power number Set maximum allowed power before contactor is switched off, W

Shelly EM: /status

GET /status

{
    "relays": [
        {
            "ison": false,
            "has_timer": false,
            "timer_started": 0,
            "timer_duration": 0,
            "timer_remaining": 0,
            "overpower": false,
            "is_valid": true
        }
    ],
    "emeters": [
        {
            "power": 0,
            "reactive": 0,
            "voltage": 0,
            "is_valid": true,
            "total": 0,
            "total_returned": 0
        },
        {
            "power": 0,
            "reactive": 0,
            "voltage": 0,
            "is_valid": true,
            "total": 0,
            "total_returned": 0
        }
    ]
}

In addition to common status info, EM adds:

Attributes

Attribute Type Description
relays array of hashes Status of the internal relay, see /relay/0
emeters array of hashes Current meter readings, see /emeter/{index}

Shelly EM: /relay/0

GET /relay/0

{
    "ison": false,
    "has_timer": false,
    "timer_started": 0,
    "timer_duration": 0,
    "timer_remaining": 0,
    "overpower": false,
    "is_valid": true
}

Returns the state of the internal relay.

Attributes

Attribute Type Description
ison bool Whether the channel is turned ON or OFF
has_timer bool Whether a timer is currently armed for this channel
timer_started number Unix timestamp of timer start; 0 if timer inactive or time not synced
timer_duration number Timer duration, s
timer_remaining number experimental If there is an active timer, shows seconds until timer elapses; 0 otherwise
overpower bool Whether an overpower condition has occurred
is_valid bool Whether power result is valid

Parameters

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

Shelly EM: /emeter/{index}

GET /emeter/0

{
    "power": 0,
    "reactive": 0,
    "voltage": 0,
    "is_valid": true,
    "total": 0,
    "total_returned": 0
}

Attributes

Attribute Type Description
power number Instantaneous power, Watts
reactive number Instantaneous reactive power, Watts
voltage number RMS voltage, Volts
is_valid bool Whether the associated meter is functioning properly
total number Total consumed energy, Wh
total_returned number Total returned energy, Wh

Parameters

Parameter Type Description
reset_totals any When requested will reset total and total_returned energy counters to 0

Shelly EM: /emeter/{index}/em_data.csv

This provides an export of the data gathered by the device. For each measurement channel, a CSV file is generated with the following columns:

This will always contain data for the entire time range stored on the device.

Shelly EM: /reset_data

GET /reset_data

{
    "reset_data": 1
}

When requested will reset all device data.

Shelly 3EM

Shelly3EM

Shelly 3EM: Overview

Shelly 3EM is a professional 3-phase energy meter with the following features:

Product page

Factory Reset

To perform a factory reset, if doing so from the web interface or application is not possible -- press and hold the built-in user button until the LED starts blinking rapidly.

Shelly 3EM: MQTT

When configured for MQTT Shelly 3EM reports data on:

Note, that energy and returned_energy do not survive power cycle or reboot -- this is how the value is implemented on other Shellies. Shelly 3EM features a persisted version which is not affected by power cycling or lack of connectivity. To get the persisted counters use total and total_returned.

Commands are accepted on:

Shelly 3EM: /settings

GET /settings

{
    "relays": [
        {
            "name": null,
            "ison": false,
            "has_timer": false,
            "overpower": false,
            "default_state": "off",
            "auto_on": 0,
            "auto_off": 0,
            "out_on_url": null,
            "out_off_url": null,
            "schedule": false,
            "schedule_rules": []
        }
    ],
    "emeters": [
        {
            "over_power_url": null,
            "over_power_url_threshold": 0,
            "under_power_url": null,
            "under_power_url_threshold": 0,
            "max_power": 0
        },
        {
            "over_power_url": null,
            "over_power_url_threshold": 0,
            "under_power_url": null,
            "under_power_url_threshold": 0,
            "max_power": 0
        },
        {
            "over_power_url": null,
            "over_power_url_threshold": 0,
            "under_power_url": null,
            "under_power_url_threshold": 0,
            "max_power": 0
        }
    ]
}

Attributes

Attribute Type Description
relays array of hashes Relay settings, see /settings/relay/0
emeters array of hashes 3EM channels configuration, see /settings/emeter/{index}

Common parameters apply for the /settings endpoint. Additionally:

Parameters

Parameter Type Description
set_time string Time and date manual setting in format [yyyy][mm][dd][hh][mm][ss][utc_offset_sec], for example settings/?set_time=20200328151600-120 means 2020-03-28 15:16:00

Shelly 3EM: /settings/relay/0

GET /settings/relay/0

{
    "name": null,
    "ison": false,
    "has_timer": false,
    "overpower": false,
    "default_state": "off",
    "auto_on": 0,
    "auto_off": 0,
    "out_on_url": null,
    "out_off_url": null,
    "schedule": false,
    "schedule_rules": []
}

This is identical to /settings/relay/{index} endpoints on most other Shelly devices with built in relays. The returned document 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.

Attributes

Attribute Type Description
name string Relay name
ison bool Relay state
has_timer bool Whether there is an active timer
overpower bool Whether an overpower condition has occurred
default_state string State on power-on, one of off, on, last, switch
auto_on number Automatic flip back timer, seconds
auto_off number Automatic flip back timer, seconds
out_on_url string URL to access when output is activated
out_off_url string URL to access when output is deactivated
schedule bool Whether scheduling is enabled
schedule_rules array of strings Rules for schedule activation

Parameters

Parameter Type Description
reset any Submitting a non-empty value will reset settings for the output to factory defaults
name string Set relay name
default_state string Accepted values: off, on, last, switch
auto_on number Automatic flip back timer, seconds. Will engage after turning OFF
auto_off number Automatic flip back timer, seconds. Will engage after turning ON
out_on_url string URL to access when output is activated
out_off_url string URL to access when output is deactivated
schedule bool Enable schedule timer
schedule_rules array of strings Rules for schedule activation, e.g. 0000-0123456-on

Shelly 3EM: /settings/emeter/{index}

GET /settings/emeter/0

{
    "over_power_url": null,
    "over_power_url_threshold": 0,
    "under_power_url": null,
    "under_power_url_threshold": 0,
    "max_power": 0
}

This endpoint allows for configuring over/under-power actions and max power protection.

Attributes

Attribute Type Description
over_power_url string URL to invoke when over_power_url_threshold is reached
over_power_url_threshold number Over-power threshold, W
under_power_url string URL to invoke when under_power_url_threshold is reached
under_power_url_threshold number Under-power threshold, W
max_power number Maximum allowed power before contactor is switched off, W

Parameters

Parameter Type Description
over_power_url string Set URL to invoke when over_power_url_threshold is reached
over_power_url_threshold number Set over-power threshold, W
under_power_url string Set URL to invoke when under_power_url_threshold is reached
under_power_url_threshold number Set under-power threshold, W
max_power number Set maximum allowed power before contactor is switched off, W

Shelly 3EM: /status

GET /status

{
    "relays": [
        {
            "ison": false,
            "has_timer": false,
            "timer_started": 0,
            "timer_duration": 0,
            "timer_remaining": 0,
            "overpower": false,
            "is_valid": true
        }
    ],
    "emeters": [
        {
            "power": 0,
            "pf": 0,
            "current": 0,
            "voltage": 0,
            "is_valid": true,
            "total": 0,
            "total_returned": 0
        },
        {
            "power": 0,
            "pf": 0,
            "current": 0,
            "voltage": 0,
            "is_valid": true,
            "total": 0,
            "total_returned": 0
        },
        {
            "power": 0,
            "pf": 0,
            "current": 0,
            "voltage": 0,
            "is_valid": true,
            "total": 0,
            "total_returned": 0
        }
    ],
    "fs_mounted": true
}

In addition to common status info, 3EM adds:

Attributes

Attribute Type Description
relays array of hashes Status of the internal relay, see /relay/0
emeters array of hashes Current meter readings, see /emeter/{index}
fs_mounted bool Whether sysflash is mounted

Shelly 3EM: /relay/0

GET /relay/0

{
    "ison": false,
    "has_timer": false,
    "timer_started": 0,
    "timer_duration": 0,
    "timer_remaining": 0,
    "overpower": false,
    "is_valid": true
}

Returns the state of the internal relay.

Attributes

Attribute Type Description
ison bool Whether the channel is turned ON or OFF
has_timer bool Whether a timer is currently armed for this channel
timer_started number Unix timestamp of timer start; 0 if timer inactive or time not synced
timer_duration number Timer duration, s
timer_remaining number experimental If there is an active timer, shows seconds until timer elapses; 0 otherwise
overpower bool Whether an overpower condition has occurred
is_valid bool Whether power result is valid

Parameters

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

Shelly 3EM: /emeter/{index}

GET /emeter/0

{
    "power": 0,
    "pf": 0,
    "current": 0,
    "voltage": 0,
    "is_valid": true,
    "total": 0,
    "total_returned": 0
}

Attributes

Attribute Type Description
power number Instantaneous power, Watts
pf number Power factor (dimensionless)
current number Current, A
voltage number RMS voltage, Volts
is_valid bool Whether the associated meter is functioning properly
total number Total consumed energy, Wh
total_returned number Total returned energy, Wh

Parameters

Parameter Type Description
reset_totals any When requested will reset total and total_returned energy counters to 0

Shelly 3EM: /emeter/{index}/em_data.csv

This provides an export of the data gathered by the device. For each measurement channel, a CSV file is generated with the following columns:

This will always contain data for the entire time range stored on the device.

Shelly 3EM: /reset_data

GET /reset_data

{
    "reset_data": 1
}

When requested will reset all device data.