Shelly relay devices (Shelly Plus 1, Shelly 1, see https://shelly.cloud/ ) are installed in power sockets and light switches and can be used without any cloud services.
They have a publicly documented API at https://shelly-api-docs.shelly.cloud/gen1/ (Shelly 1) and https://shelly-api-docs.shelly.cloud/gen2/ (Shelly Plus 1).
It would be nice if HomeApp would support their API.
I would like to support that by buying you some test devices. Please contact [email protected] if you are interested and let me know your postal address.
Service Discovery
Shelly devices announce themselves via MDNS (Bonjour/Zeroconf) and not SSDP. One can use the linux tool "avahi-browse" to find them.
Gen2 shellies advertise themselves the Multicast Domain Name System (mDNS), also known as Bonjour. Devices advertise two types of services:
- _http._tcp - a web server serving on port 80. This service is also advertised for Gen1 shellies
- _shelly._tcp - service instance specific to Gen2 Shelly devices."
$ avahi-browse --cache --no-db-lookup --parsable --all
+;wlp1s0;IPv4;ShellyPlus1-A8032ABD2342;_http._tcp;local
+;wlp1s0;IPv4;ShellyPlus1-A8032ABD2343;_http._tcp;local
+;wlp1s0;IPv4;ShellyPlus1-A8032ABE2344;_http._tcp;local
+;wlp1s0;IPv4;shellyplus1-a8032abd2342;_shelly._tcp;local
+;wlp1s0;IPv4;shellyplus1-a8032abd2343;_shelly._tcp;local
+;wlp1s0;IPv4;shellyplus1-a8032abe2344;_shelly._tcp;local
Android natively supports mDNS discovery also with Kotlin: https://developer.android.com/training/connect-devices-wirelessly/nsd#discover
Device information
All devices (v1 and v2) have a public (unprotected) JSON information file at /shelly
:
v1
{
"type": "SHSW-1",
"mac": "483FDA82687A",
"auth": false,
"fw": "20211109-124958/v1.11.7-g682a0db",
"longid": 1,
"num_outputs": 1
}
https://shelly-api-docs.shelly.cloud/gen1/#shelly
v2
$ curl -s shelly1.home.cweiske.de/shelly|jq .
{
"id": "shellyplus1-a8032abd1bcc",
"mac": "A8032ABD2342",
"model": "SNSW-001X16EU",
"gen": 2,
"fw_id": "20210921-202758/0.8.1-g52de872",
"ver": "0.8.1",
"app": "Plus1",
"auth_en": false,
"auth_domain": null
}
The "gen" key is only available on v2 devices.
https://shelly-api-docs.shelly.cloud/gen2/Overview/CommonServices/Shelly#http-endpoint-shelly
Number of switches
v1
The JSON object in GET /status
has a "relays" array property: https://shelly-api-docs.shelly.cloud/gen1/#shelly1-1pm-status
{
"relays": [
{
"ison": false,
"has_timer": false,
"timer_started": 0,
"timer_duration": 0,
"timer_remaining": 0,
"overpower": false,
"source": "http"
}
],
...
}
v2
We have to look for "switch:*" keys in the device configuration object for v2-devices:
https://shelly-api-docs.shelly.cloud/gen2/Overview/CommonServices/Shelly#shellygetconfig
$ curl -s shelly1.home.cweiske.de/rpc/Shelly.GetConfig | jq .
{
...
"switch:0": {
"id": 0,
"name": "wohnzimmer_1",
"in_mode": "follow",
"initial_state": "restore_last",
"auto_on": false,
"auto_on_delay": 60,
"auto_off": false,
"auto_off_delay": 60
},
...
}
Detecting on/off device state
v1 returns the ison
state in the /status
route as well.
Both v1 and v2 devices have the /relay/0
URL, which tells us if it is switched on or off via ison
:
$ curl -s shelly1.home.cweiske.de/relay/0|jq .
{
"ison": true,
"has_timer": false,
"timer_started_at": 0,
"timer_duration": 0,
"timer_remaining": 0,
"source": "http"
}
v2 also returns all states in /rpc/Shelly.GetStatus
:
$ http -p b shelly1.home.cweiske.de/rpc/Shelly.GetStatus
{
...
"switch:0": {
"id": 0,
"output": true,
"source": "http",
"temperature": {
"tC": 58.8,
"tF": 137.8
}
},
...
}
Switching on/off
Both v1 and v2 devices have the /relay/0
URL, which allows turning the device on, off or toggling the device state with a GET parameter:
$ curl http://shelly1.home.cweiske.de/relay/0?turn=on
$ curl http://shelly1.home.cweiske.de/relay/0?turn=off
$ curl http://shelly1.home.cweiske.de/relay/0?turn=toggle
Note: Some devices have more that one relay. See above for detecting the number and names of switches.
Temperature sensors
v1
It's possible to attach a temperature sensor to a Shelly 1 device. /status
gives us the values:
{
...
"ext_sensors": {
"temperature_unit": "C"
},
"ext_temperature": {
"0": {
"hwID": "0300",
"tC": 23,
"tF": 73.4
}
},
"ext_humidity": {
"0": {
"hwID": "0300",
"hum": 52.3
}
},
...
}
Authentication
v1
https://shelly-api-docs.shelly.cloud/gen1/#common-http-api
All resources except for /shelly will require Basic HTTP authentication when it is enabled
v2
https://shelly-api-docs.shelly.cloud/gen2/Overview/CommonDeviceTraits#authentication
Communication through HTTP and Websocket channels is secured by a digest authentication mechanism using the SHA256 hmac algorithm as defined in RFC7616.
When enabled, all communication is protected except:
- the RPC method Shelly.GetDeviceInfo
- the HTTP endpoint /shelly