Today I’m bringing you the second chance that I’ll give Shelly. My first Shelly Dimmer blew up for excess temperature inside a connection box, but another Shelly 2.5 controlling two lights is holding fine, also fitted in the wall.

Maybe the difference is the extra 5ºC that they withstand, so I’m going to fit a wall plug with switch and scheduler using a tiny Shelly 1, and just hope it survives.

Apart from the tiny size, Shelly are easy to configure, so we’ll also see how to control them locally via the HTTP API.

Requirements

My goal is to enable a wall plug that I can control and schedule via WIFI, in my case, to manage the electrical water heater. This is what I'll use:

  • Shelly 1.
  • Two wire electric cable (line and neutral).
  • Male plug.
  • Female plug socket.
  • Assembling material for a case (3D printer, plywood, etc).
Shelly 1
Electric cable
Male plug
Female plug socket (front)
Female plug socket (back)
Assembly support printed in 3D

Electric connection

Let's look at Shelly's user manual and see how we need to make the connections:

https://www.shelly.com/documents/user_guide/shelly_1_multi_language.pdf

The idea for this standard schematic is to connect Shelly 1 to a light bulb and its switch, where every symbol means the following:

  • L: line
  • N: neutral
  • SW: switch
  • I: input
  • O: output

As I want to enable a plug socket, the schematic will vary slightly, as I will not be using any switch and I can connect the input directly to the line. On the other hand, and for I reason I ignore, there is no cabling inside the connection box, so I bring the electric line from another plug using the cable... In the end, it all ends like this:

TIP! I'd say that I confused the cable color norm, but it is not important in this case as its a closed circuit and it will work anyways.

Assembly

You might see that I made a small 3D support to guide the cabling, as well as a lid to cover the void around the socket. Modelling every part in 3D, with real measures, helps to distribute the space properly and ensure that your solution fits:

I'll leave here the 3D .stl models ready to send to your slider software.

Shelly-Plug_support_v1.stl

https://theroamingworkshop.cloud/demos/Shelly-Plug_support_v1.stl

Shelly-Plug_tapa_v1.stl

https://theroamingworkshop.cloud/demos/Shelly-Plug_tapa_v1.stl

Finally, this is how it all looks crafted in place. It's not the perfect fit, but it does the job I needed.

Internet connection

Let's now see how to bring the Shelly 1 to life and control it locally.

Opposite to Sonoff, Shelly makes it much easier and you just need to follow the user manual.

  1. Power Shelly 1 using the male plug.
  2. This will activate an AP (Access Point) or Wi-Fi network with an SSID looking like "shelly1-01A3B4". Connect to this Wi-Fi network using a smartphone or PC.
  3. Once connected, use a web browser to access the IP at 192.168.33.1 and it will take you to Shelly's web interface for device configuration.
  1. Once in, you must config the device (inside Internet & Security menu) so that it automatically connects to your local Wi-Fi network, as well as it is recommended to restrict access with username and password.

We're all set to communicate with Shelly 1 locally.

Shelly HTTP API usage

To use the command of the HTTP API you must know the device IP in your local network.

Find IP in the router

You can access the network map in your router, usually from the address http://192.168.1.1

The address and the password should be in some sticker in your router. Then you'll see your device with a name like shelly1-XXXXXXXXXXXX:

Find IP using nmap

In a terminal you can use the tool nmap to scan your local network.

  • Download it if not done yet:
    sudo apt-get update
    sudo apt-get install nmap
  • Scan your network (using sudo you'll get the MAC address, which is useful as the IP could change when restarting the router)
    sudo nmap -v -sn 192.168.1.0/241.0/24

Send HTTP requests to the device

Shelly's HTTP API is well documented in their website:

https://shelly-api-docs.shelly.cloud/gen1/#common-http-api

In order to communicate with the device, you need to send HTTP requests using some software like Postman or using curl or wget in a terminal.

The request will be sent to the device IP with:

$ curl -X GET http://192.168.1.XX/command

If you defined user and password, you need to include them in the URL like below, or you'll receive a "401 unauthorized" response:

$ curl -X GET http://user:[email protected]/command

Now let's see some specific cases:

Device information

http://[user]:[pass]@[ip]/status

  • curl

curl -X GET 'http://user:[email protected]/status

  • Response
{"wifi_sta":{"connected":true,"ssid":"MYWIFINETWORK","ip":"192.168.1.XX","rssi":-70},"cloud":{"enabled":false,"connected":false},"mqtt":{"connected":false},"time":"19:30","unixtime":1699295403,"serial":1,"has_update":false,"mac":"A4CF12F407B1","cfg_changed_cnt":0,"actions_stats":{"skipped":0},"relays":[{"ison":false,"has_timer":false,"timer_started":0,"timer_duration":0,"timer_remaining":0,"source":"input"}],"meters":[{"power":0.00,"is_valid":true}],"inputs":[{"input":0,"event":"","event_cnt":0}],"ext_sensors":{},"ext_temperature":{},"ext_humidity":{},"update":{"status":"idle","has_update":false,"new_version":"20230913-112003/v1.14.0-gcb84623","old_version":"20230913-112003/v1.14.0-gcb84623"},"ram_total":51688,"ram_free":39164,"fs_size":233681,"fs_free":146333,"uptime":2679}

Turn (on/off)

http://[usr]:[pass]@[ip]/relay/0?turn=[on/off]

  • curl

curl -X GET http://user:[email protected]/relay/0?turn=on

  • Response
{"ison":true,"has_timer":false,"timer_started":0,"timer_duration":0,"timer_remaining":0,"source":"http"}

The value 0 in the URL matches te number of the relay or internal switch in the Shelly. In this case there is only one, but in the case of Shelly 2.5 you have two relays, so you can call them individually changing this value.

Scheduler

http://[usr]:[pass]@[ip]/settings/relay/0?schedule_rules=[HHMM]-[0123456]-[on/off]

  • curl

curl -X GET http://user:[email protected]/settings/relay/0?schedule_rules=1945-0123456-on

  • Response
{"name":"CALENTADOR","appliance_type":"General","ison":false,"has_timer":false,"default_state":"off","btn_type":"toggle","btn_reverse":0,"auto_on":0.00,"auto_off":0.00,"power":0.00,"schedule":true,"schedule_rules":["1945-0123456-on"]}

In this case, the URL defines the following schedule rule parameters:

  • HHMM: hour and minute that activate the rule
  • 0123456: days of the week when the rule is active
  • on/off: status that the rule triggers

This way, to schedule the on and off of the device (except during weekends), you could send a request like this one:

curl -X GET http://192.168.1.XX/settings/relay/0?schedule_rules=2300-01234-on,0700-01234-off

Obviously you can also configure the schedule rules from the web interface, or just check the commands worked:

And that would cover all of it. Jump off and fill your house with tiny Shellys completely customizable. Any questions or comments on Twitter 🐦 please! (though given what's going on with the X thing, who knows how long I'll last...)