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:

• Via Allterco's mobile applications for Android and iOS
• Using the local web interface via a browser (open http://192.168.33.1/ )
• By performing a HTTP request to set the desired WiFi settings (see HTTP API below).

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.

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

Common HTTP API

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

• WiFi configuration
• Cloud settings
• HTTP authentication settings
• Firmware updates, identification and other system functions

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,
    "discoverable": true
}

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

/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" : { ... },
    "ap_roaming": {
        "enabled": false,
        "threshold": -70
    },
    "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": {
        "enabled": true,
        "update_period": 15,
        "peer": ""
    },
    "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,
    "led_status_disable": false,
    "debug_enable": false,
    "allow_cross_origin": false,
    "wifirecovery_reboot_enabled": true
}

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

Parameters

/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

Parameters

/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

Parameters

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

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

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

/settings/actions

GET /settings/actions

{
  "actions": {
    "out_on_url": [
      {
        "index": 0,
        "urls": [
          "http://192.168.1.4/on",
          "http://192.168.1.5/on"
        ],
        "enabled": true
      }
    ],
    "out_off_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "over_power_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false,
        "over_power_url_threshold": 0
      },
      {
        "index": 1,
        "urls": [],
        "enabled": false,
        "over_power_url_threshold": 0
      },
      {
        "index": 2,
        "urls": [],
        "enabled": false,
        "over_power_url_threshold": 0
      }
    ],
    "under_power_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false,
        "under_power_url_threshold": 0
      },
      {
        "index": 1,
        "urls": [],
        "enabled": false,
        "under_power_url_threshold": 0
      },
      {
        "index": 2,
        "urls": [],
        "enabled": false,
        "under_power_url_threshold": 0
      }
    ]
  }
}

Attributes

Parameters

Since v1.8.0 devices support multiple actions. Max number of URLs per action is 5. Max URLs length is 256.

Examples:

• Setting two URLs for out_on_url action on channel 0:

http://192.168.33.1/settings/actions?index=0&name=out_on_url&enabled=true&urls[]=http://192.168.1.4/on&urls[]=http://192.168.1.5/on

• Disable only action out_on_url on channel 0:

http://192.168.33.1/settings/actions?index=0&name=out_on_url&enabled=false

• Delete URLs for action out_on_url action on channel 0:

http://192.168.33.1/settings/actions?index=0&name=out_on_url&urls[]=

• Some devices have additional parameters which may be set along with actions. Example: Setting URLs and over_power_url_threshold parameter for action over_power_url on channel 0:

http://192.168.33.1/settings/actions?index=0&name=over_power_url&enabled=true&urls[]=192.168.1.4/overpower&urls[]=192.168.1.5/overpower&over_power_url_threshold=100

/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

/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

Parameters

/ota/check

GET /ota/check

{
    "status": "ok"
}

Manual check for new firmware version.

Attributes

/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

/debug/log

GET /debug/log

Retrieve debug log file 0

/debug/log1

GET /debug/log1

Retrieve debug log file 1

/cit/d

GET /cit/d

{
    "blk":[
        ...
    ],
    "sen":[
        ...
    ]
}

Get CoIoT description package over HTTP

/sta_cache_reset

GET /sta_cache_reset

Reset STA cache: only applicable on devices which support STA caching (battery operated devices Shelly Door/Window 1/2, Shelly H&T, Shelly Smoke, Shelly Flood, Shelly Button1)

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:

• mqtt_server is your broker's address:port
• mqtt_enable needs to be set to true

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.

In order to apply the MQTT configuration, the device requires a reboot.

Availability and announces

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

• an announce message on shellies/announce and, since v1.6.0, on shellies/<shellymodel>-<deviceid>/announce. The message is JSON-formatted and contains a list of attributes: id, mode (if applicable), model, mac, ip, new_fw (true when an update is available), fw_ver (contains the current firmware version);
• availability message on shellies/<shellymodel>-<deviceid>/online with payload true;
• complete current state. This is device specific and is described in detail for each device below.

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. The LWT topic is retained on user configuration (if the Retain flag is set). However, we do not recommend using retained MQTT messages.

Common MQTT commands

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

• announce will trigger:
  • an announce packet by every Shelly connected to the broker on shellies/announce and, since v1.6.0, on shellies/<shellymodel>-<deviceid>/announce;
  • since v1.8.0, shellies/<shellymodel>-<deviceid>/info with the content of the http /status endpoint.
• update will cause all Shellies to publish their state;
• update_fw to perform a firmware update when one is available.

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/1PM
• Shelly2
• Shelly2.5
• Shelly4Pro
• Shelly Plug/Plug S
• Shelly i3
• Shelly Button1
• Shelly Bulb
• Shelly Vintage
• Shelly Duo
• Shelly RGBW2 Color
• Shelly RGBW2 White
• Shelly Dimmer/SL
• Shelly Sense
• Shelly H&T
• Shelly Smoke
• Shelly Flood
• Shelly Door/Window
• Shelly Gas
• Shelly EM
• Shelly 3EM

CoIoT Protocol

The CoIoT protocol is yet another protocol for IoT communication and integration. CoIoT is based on CoAP with some additions as new request code 0.30 for status publishing. All payloads are JSON encoded. All responses are piggyback sent with the acknowledgement to further simplify CoAP implementation.

Every CoIoT device is expected to handle a set of request URIs and generate responses in predefined format. Also every device is required to periodically send a multicast CoAP request with code 0.30 that describes it state.

Every CoAP request package and every response with payload should also carry some mandatory CoAP options (headers).

CoIoT protocol version

CoIoT protocol version can be obtained from option 3332 COIOT_OPTION_GLOBAL_DEVID : <devtype>#<devid>#<version>

• Devices with FW < v1.8.0 will return version 1, e.g.: SHSW-1#A020A6146209#1
• Devices with FW >= v1.8.0 will return version 2, e.g.: SHSW-1#A020A6146209#2

Documentation for version 1 can be found here: CoIoT for Shelly devices (rev 1.0) .pdf

The rest of this document is applicable for version 2.

CoIoT mandatory CoAP options

Some non-standard CoAP options are required to be transmitted to help quickly identify the remote device and determine if further processing is needed. The options are numbered with the help of these C/C++ preprocessor macros:

#define COIOT_OPTION_BASE               3332 //non critical, save to forward, no cache key
#define COIOT_OPTION_INCR               8
#define COIOT_OPTION_N(n)               (COIOT_OPTION_BASE+(COIOT_OPTION_INCR)*(n))

#define COIOT_OPTION_GLOBAL_DEVID       COIOT_OPTION_N(0)
#define COIOT_OPTION_MGR_GLOBAL_NBASE   1
#define COIOT_OPTION_STATUS_NBASE       10
#define COIOT_OPTION_STATUS_VALIDITY    COIOT_OPTION_N(COIOT_OPTION_STATUS_NBASE+0)
#define COIOT_OPTION_STATUS_SERIAL      COIOT_OPTION_N(COIOT_OPTION_STATUS_NBASE+1)
#define COIOT_OPTION_MGR_STATUS_NBASE   20

To follow the CoAP standard, options are numbered above 2048 where proprietary options should reside. LS Bits carry some CoAP proxy flags so we guard them with spacing the numbers with increment of 8.

COIOT_OPTION_GLOBAL_DEVID

First defined option is COIOT_OPTION_GLOBAL_DEVID. This is a global option and must be present in all CoIoT packages with request or payload. Its value is a string in format <devtype>#<devid>#<version> for example SHSEN-1#4B3F9E#1 The whole option should be less than 50 bytes.

Other mandatory options are COIOT_OPTION_STATUS_VALIDITY and COIOT_OPTION_STATUS_SERIAL. They are mandatory only in status responses or publishes.

COIOT_OPTION_STATUS_VALIDITY

COIOT_OPTION_STATUS_VALIDITY is a uint16_t in network byte order (big endian) that states the maximal time between this and the next status publish. This way a device can state its report interval. If a report is not received from this device after the interval has passed the device should be considered offline. The LS bit of this option controls how the value is scaled:

• If the LS bit is 0, the value is number of 1/10 of seconds in the validity period, so 2 is 0.2 seconds, 10 is a second, 600 is a minute, 65534 is 109 minutes and 13 seconds.
• If the LS bit is 1, the value is number of 4 seconds interval in the whole interval. So 3 is 12 seconds, 11 is 44 seconds and 65535 is more than 3 days.

COIOT_OPTION_STATUS_SERIAL

This option is mandatory in status response and publishes. It is a uint16_t in network byte order which indicates a change in the status report. When a new status report is handled, all payload processing can be skipped if the serial number does not change from the last processed payload. The value 0 is reserved and should not be sent. This allows easy initialization in the receiving devices.

Serial will always be incremented monotonically (i.e. +1). If you have a packet with serial "4" and the next is with serial "6", it means "5" got lost and didn't reach you.

CoIoT device description (/cit/d)

Every device should response to CoAP GET request with URI /cit/d and return a JSON payload describing the device.

Note: since v1.10.0 all devices support an HTTP endpoint /cit/d which allows to retrieve the same CoIoT description package as the CoAP GET request.

Throughout the description all <id> values should be non-overlapping integers that are used as unique identificators of blocks and sensors.

Toplevel object should look like:

{
    "blk": [...],
    "sen": [...]
}

blk array

blk array should hold list of all "blocks" of the device. Each device should have at least one block. For example if your device exposes just a few sensors it needs just one block, but if you have a multi channel relay you should define a block for each relay. Each sensor should be linked to one or many blocks to help users better understand what is measured in more complex devices.

blk elements should be objects with structure:

{
    "I": id,
    "D": description
}

for example:

"blk":[
    {
        "I":1,
        "D":"relay_0"
    },
    {
        "I":2,
        "D":"relay_1"
    },
    {
        "I":3,
        "D":"device"
    }
]

"I":id (mandatory)

• <id> is recommended to start from 1 for the first declared block and increment monotonically (i.e. +1) for subsequent blocks, but in general it's not forbidden to declare blocks with arbitrary <id>s.

"D":description (mandatory)

• <description> is recommended to be one word, camelCase or camelCase_N (where N is some number), but in general it's not forbidden to have longer descriptions.
• “device” block will always be present.

sen array

sen array should hold a list of all sensors and states in the device. These should be objects with structure:

{
    "I": id,
    "T": type,
    "D": description,
    "U": unit,
    "R": range,
    "L": links
}

for example:

"sen":[
    {
        "I":1101,
        "T":"S",
        "D":"output",
        "R":"0/1",
        "L":1
    },
    {
        "I":1201,
        "T":"S",
        "D":"output",
        "R":"0/1",
        "L":2
    }
]

Device descriptions will strive to provide all properties supported by the device, even if they are currently disabled/unavailable on the specific device. For example, a Shelly1 will always include a description of properties related to external (add-on) sensors, even if they are not currently attached (but of course, in this case they will be hidden from the status packet).

“I”:id (mandatory)

• All devices will follow an internal scheme to generate <id>s for properties (i.e. specific <id>s map to specific properties), but this should NOT be relied upon. You should assume <id>s have no external meaning and treat them just as numbers to precisely "name" a property.

“T”:type (mandatory)

• <type> will always be 1 to 3 characters, only capital letters.

For now the following types are declared:

“EV” (Event) and “EVC” (Event counter) are newly introduced types to be able to communicate the occurrence of events. Such events are for example shortpush/longpush of buttons – devices will send a property of type “EV” to denote the exact event type (“S” = shortpush, “L” = longpush), and a property of type “EVC” that will increment its value when a new event occurs (e.g. to be able to know that two consecutive longpushes are actually two separate events).

“D”:description (mandatory)

• <description> is recommended to be one word, camelCase or camelCase_N (where N is some number) - e.g. “output”, “rollerPos”, but in general it's not forbidden to have longer descriptions (consider them "free text" - for a human reading the description to get a better understanding of the property).

“U”:unit (optional)

• <unit> is a newly introduced optional attribute. If it’s necessary to specify a dimension for a property, it will be done here, not in <type> or <description>.

For now the following units are declared:

“R”:range (optional)

<range> is allowed to be either:

• a single string, specifying normal range in form "from/to", "valueX/valueY/.../valueZ" or "<I|U><8|16|32>", the latter showing expected sIgned or Unsigned integer size
• an array of strings, specifying normal range and invalid value in form ["<normal>","<invalid>"]. "<invalid>" = the value you'll get if "real" data is unavailable at the moment (e.g. sensor broke)

For example:

• “0/100” - normal range is from 0 to 100; no invalid value
• “obstacle/overpower/safety_switch” - normal range is “obstacle”, “overpower” or “safety_switch”; no invalid value
• [“0/255”,”999”] - normal range is from 0 to 255; invalid value is 999
• [“U16”,”-1”] - normal range is uint16, invalid value is -1

“L”:links (mandatory)

• <links> can be a single integer or array of integers with <id>s of device blocks to which a property relates.

CoIoT device status (/cit/s)

Every device should respond to CoAP GET request with URI /cit/s and return a JSON payload describing the device. Every device should periodically publish its status using multicast packet in the form of non-confirmable request with code 0.30 and request path /cit/s. This code is non-standard CoAP code and all CoAP compliant servers should silently ignore it. Throughout the status report all <id> values should match sensors ids from the device description. The JSON payload should follow the form:

{
    "G":[
            [0,id,value],
            [0,id,value],
            ...
        ]
}

for example:

{
    "G":[
            [0,1101,1],
            [0,1104,136],
            ...
        ]
}

The G key stands for Generic. Currently all sensor values are generic and non-encrypted. Future extensions of the protocol might add P for Private and define some encryption scheme.

The 0 in the sensor tuples stands for the channel number. All sensors are required to be emitted in channel 0. Future extensions of the protocol might define a way for the users to define extra mapping for sensors to channels that will be added to the status after the values from channel 0. This will allow for easy reconfiguration of peer to peer network. For example, a multizone alarm system can be configured to react based on channel number activity and not to have to explicitly list every sensor on every siren. Currently the first position in the sensor tuple is reserved and should be 0.

The second position is for the sensor <id>, and the third is for the sensor's current <value>.

CoIoT list of properties

Below is a list of all properties currently reported by the devices with CoIoT protocol version 2, along with short comments on their meaning. Please bear in mind that this is just a generalized example – attributes such as e.g. <range> are device specific.

• CoIoT v2 property list

CoIoT examples

Example CoIoT description (/cit/d) and status (/cit/s) are provided separetely for each device:

• Shelly1/1PM
• Shelly2
• Shelly2.5
• Shelly Plug/Plug S
• Shelly i3
• Shelly Button1
• Shelly Bulb
• Shelly Vintage
• Shelly Duo
• Shelly RGBW2 Color
• Shelly RGBW2 White
• Shelly Dimmer/SL
• Shelly H&T
• Shelly Smoke
• Shelly Flood
• Shelly Door/Window
• Shelly Gas
• Shelly EM
• Shelly 3EM

Shelly1 / Shelly1PM

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:

• A physical button
• HTTP request, trough the local web interface
• A command sent via the cloud or MQTT
• A weekly-schedule event or a sunrise/sunset-generated event
• Shelly1PM only: Overpower condition will turn the relay OFF

Shelly1/PM supports up to 18 schedule rules.

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:

• Keep output OFF
• Turn output ON
• Restore the state of the output from before the power loss
• Read the physical switch state and configure the output accordingly

To control Shelly1/1PM, use these resources:

• /settings/relay/0 to configure behavior
• /relay/0 to control and monitor

Shelly1/1PM: MQTT

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

• shellies/<model>-<deviceid>/relay/0 to report status: on, off or overpower (the latter only for Shelly1PM)
• shellies/<model>-<deviceid>/relay/0/command accepts on, off or toggle and applies accordingly
• shellies/<model>-<deviceid>/input/0 reports the state of the SW terminal
• shellies/<model>-<deviceid>/longpush/0 reports longpush state as 0 (shortpush) or 1 (longpush)
• shellies/<model>-<deviceid>/input_event/0 reports input event and event counter, e.g.: {"event":"S","event_cnt":2} see /status for details

Shelly1PM adds:

• shellies/shelly1pm-<deviceid>/relay/0/power reports instantaneous power in Watts
• shellies/shelly1pm-<deviceid>/relay/0/energy reports an incrementing energy counter in Watt-minute
• shellies/shelly1pm-<deviceid>/temperature reports internal device temperature in °C
• shellies/shelly1pm-<deviceid>/temperature_f reports internal device temperature in °F
• shellies/shelly1pm-<deviceid>/overtemperature reports 1 when device has overheated, normally 0
• shellies/shelly1pm-<deviceid>/temperature_status reports Normal, High, Very High
• shellies/shelly1pm-<deviceid>/relay/0/overpower_value reports the value in Watts, on which an overpower condition is detected

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

For add-ons with DS1820 sensors:

• shellies/<model>-<deviceid>/ext_temperature/<i> where <i> is the sensor id [0,1,2]: reports temperature in °C, 999 if invalid
• shellies/<model>-<deviceid>/ext_temperature_f/<i> where <i> is the sensor id [0,1,2]: reports temperature in °F, 999 if invalid

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

• shellies/<model>-<deviceid>/ext_humidity/0 reports humidity in percent, 999 if invalid

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

• shellies/<model>-<deviceid>/ext_temperatures

{
    "0":{"hwID":"XXXXXXXX","tC":20.5},
    "1":{"hwID":"YYYYYYYY","tC":21.5},
    "2":{"hwID":"ZZZZZZZZ","tC":22.5}
}

• shellies/<model>-<deviceid>/ext_temperatures_f

{
    "0":{"hwID":"XXXXXXXX","tF":68.9},
    "1":{"hwID":"YYYYYYYY","tF":70.7},
    "2":{"hwID":"ZZZZZZZZ","tF":72.5}
}

• shellies/<model>-<deviceid>/ext_humidities

{
    "0":{"hwID":"XXXXXXXX","hum":50}
}

Shelly1/1PM: CoIoT

Example CoIoT description (/cit/d) and status (/cit/s):

Shelly1:

• Shelly 1 SHSW-1 no-addon
• Shelly 1 SHSW-1 with-ds1820
• Shelly 1 SHSW-1 with-dht22

Shelly 1PM:

• Shelly 1PM SHSW-PM no-addon
• Shelly 1PM SHSW-PM with-ds1820
• Shelly 1PM SHSW-PM with-dht22

Shelly1/1PM: /settings

GET /settings (Shelly1PM without temperature add-on, with low-power switch add-on)

{
    "factory_reset_from_switch": true,
    "max_power": 2000,
    "supply_voltage": 0,
    "power_correction": 1,
    "mode": "relay",
    "led_status_disable": false,
    "longpush_time": 1000,
    "actions": {
        "active": false,
        "names": [
            "btn_on_url",
            "btn_off_url",
            "out_on_url",
            "out_off_url",
            "longpush_url",
            "shortpush_url",  
            "lp_on_url",
            "lp_off_url",
            "ext_temp_over_url",
            "ext_temp_under_url",
            "ext_hum_over_url",
            "ext_hum_under_url"
        ]
    },
    "relays": [
        {
            "name": null,
            "appliance_type": "General",
            "ison": false,
            "has_timer": false,
            "default_state": "off",
            "btn_type": "toggle",
            "btn_reverse": 0,
            "auto_on": 0,
            "auto_off": 0,
            "power": 0,
            "schedule": false,
            "schedule_rules": [],
            "max_power": 0
        }
    ],
    "ext_sensors": {},
    "ext_temperature": {},
    "ext_humidity": {},
    "ext_switch_enable": 1,
    "ext_switch":{
      "0": {
        "relay_num": 0
      }
    }
}

Common attributes apply for the /settings endpoint. Additionally:

Attributes

Common parameters apply for the /settings endpoint. Additionally:

Parameters

Shelly1/1PM: /settings/actions

GET /settings/actions

{
  "actions": {
    "btn_on_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "btn_off_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "longpush_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "shortpush_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "out_on_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "out_off_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "lp_on_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "lp_off_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "ext_temp_over_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false,
        "ext_temp_over_value": 24.0,
        "ext_temp_over_onetime": false
      }
    ],
    "ext_temp_under_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false,
        "ext_temp_under_value": 22.5,
        "ext_temp_under_onetime": false
      }
    ],
    "ext_hum_over_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false,
        "ext_hum_over_value": 60,
        "ext_hum_over_onetime": false
      }
    ],
    "ext_hum_under_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false,
        "ext_hum_under_value": 40,
        "ext_hum_under_onetime": false
      }
    ]
  }
}

Actions

Shelly1/1PM supports the following actions, which can be set as described at /settings/actions:

Additional parameters

Shelly1/1PM: /settings/relay/0

GET /settings/relay/0 (Shelly1PM)

{
    "name": null,
    "appliance_type": "General",
    "ison": false,
    "has_timer": false,
    "default_state": "off",
    "btn_type": "toggle",
    "btn_reverse": 0,
    "auto_on": 0,
    "auto_off": 0,
    "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

Parameters

Shelly1: /settings/power/0

Parameters

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",
    "offset_tC": 0,
    "offset_tF": 0
}

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

Parameters

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

• DS1820: [-55 / 125 ]°C, [-67 / 257]°F
• DHT22: [-40 / 80]°C, [-40 / 176]°F

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",
    "offset": 0
}

Only applicable if add-on attached (DHT22)

Parameters

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

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

GET /settings/ext_switch/0

{
    "relay_num": 0
}

Only applicable if low-power switch add-on attached

Parameters

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,
            "source": "http"
        }
    ],
    "meters": [
        {
            "power": 0,
            "overpower": 23.78,
            "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
    },
    "temperature_status":"Normal",
    "ext_switch":{
        "0": {
            "input": 1
        }
    }
}

/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

meters attributes: Shelly1

meters attributes: Shelly1PM

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

inputs attributes

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 have a lifetime of 5s; after this event will be cleared to "".

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

ext_temperature.{index} attributes

Attributes

ext_humidity.0 attributes

Attributes

ext_switch.{index} attributes

Only applicable if low-power switch add-on attached

Attributes

Shelly1/1PM: /relay/0

GET /relay/0 (Shelly1PM)

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

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

Attributes

Parameters

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:

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:

• Espressif's SDK
• Arduino
• NodeMCU
• Micropython
• Sming
• and many others.

Shelly1: wiring in the field

When using DC power supply, observe polarity as indicated:

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.

Shelly1L

Shelly1L: Overview

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

https://shop.shelly.cloud/shelly-1l-wifi-smart-home-automation

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

• A physical button
• HTTP request, trough the local web interface
• A command sent via the cloud or MQTT
• A weekly-schedule event or a sunrise/sunset-generated event
• Overpower condition will turn the relay OFF

Shelly 1L supports up to 18 schedule rules.

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

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

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

• Keep output OFF
• Turn output ON
• Restore the state of the output from before the power loss
• Read the physical switch state and configure the output accordingly

To control Shelly1L, use these resources:

• /settings/relay/0 to configure behavior
• /relay/0 to control and monitor

Shelly1L: MQTT

Shelly1L uses the following topics:

• shellies/shelly1l-<deviceid>/relay/0 to report status: on, off or overpower (the latter only for Shelly1L)
• shellies/shelly1l-<deviceid>/relay/0/command accepts on, off or toggle and applies accordingly
• shellies/shelly1l-<deviceid>/input/0 reports the state of the SW terminal
• shellies/shelly1l-<deviceid>/longpush/0 reports longpush state as 0 (shortpush) or 1 (longpush)

• shellies/shelly1l-<deviceid>/input_event/0 reports input event and event counter, e.g.: {"event":"S","event_cnt":2} see /status for details

• shellies/shelly1l-<deviceid>/relay/0/power reports instantaneous power in Watts

• shellies/shelly1l-<deviceid>/relay/0/energy reports an incrementing energy counter in Watt-minute

• shellies/shelly1l-<deviceid>/temperature reports internal device temperature in °C

• shellies/shelly1l-<deviceid>/temperature_f reports internal device temperature in °F

• shellies/shelly1l-<deviceid>/overtemperature reports 1 when device has overheated, normally 0

• shellies/shelly1l-<deviceid>/relay/0/overpower_value reports the value in Watts, on which an overpower condition is detected

Shelly1L: CoIoT

Example CoIoT description (/cit/d) and status (/cit/s):

• Shelly 1L SHSW-L

Shelly1L: /settings

GET /settings

{
    "factory_reset_from_switch": true,
    "max_power": 2000,
    "supply_voltage": 0,
    "mode": "relay",
    "led_status_disable": false,
    "longpush_time": 1000,
    "actions": {
        "active": false,
        "names": [
            "btn1_on_url",
            "btn1_off_url",
            "btn1_longpush_url",
            "btn1_shortpush_url",
            "btn2_on_url",
            "btn2_off_url",
            "btn2_longpush_url",
            "btn2_shortpush_url",
            "out_on_url",
            "out_off_url"
        ]
    },
    "relays": [
        {
            "name": null,
            "appliance_type": "General",
            "ison": false,
            "has_timer": false,
            "default_state": "off",
            "btn1_type": "toggle",
            "btn1_reverse": 0,
            "btn2_type": "toggle",
            "btn2_reverse": 0,
            "swap_inputs": false,
            "auto_on": 0,
            "auto_off": 0,
            "power": 0,
            "schedule": false,
            "schedule_rules": [],
            "max_power": 0
        }
    ],
    "meters": [
        {
            "power": 0,
            "is_valid": true,
            "timestamp": 0,
            "counters": [1,2,3],
            "total": 4
        }
    ]
}

Common attributes apply for the /settings endpoint. Additionally:

Attributes

Common parameters apply for the /settings endpoint. Additionally:

Parameters

Shelly1L: /settings/actions

GET /settings/actions

{
  "actions": {
    "btn1_on_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "btn1_off_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "btn1_longpush_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "btn1_shortpush_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "btn2_on_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "btn2_off_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "btn2_longpush_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "btn2_shortpush_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "out_on_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ],
    "out_off_url": [
      {
        "index": 0,
        "urls": [],
        "enabled": false
      }
    ]
  }
}