Shelly Plus 1 flashing and setup guide/ tutorial

As I found no real instructions on flashing the Shelly Plus 1 (not PM) with esphome I decided to write a small guide for everyone also being lost.

First of all i got these shellys just for visual reference:

There is unfortunately not OTA- flashing method (as of now:17.11.22) so dont just pop them into the wall for now.

What you need to flash:

  • Shelly Plus 1 (obvioulsy)
  • USB to UART Adapter (just google it ther are really cheap. I’ve got the CP2102 but others with 3,3V should work as well.
  • Dupon Cables or matching pins sort of)

Connecting:
There is a UART Terminal on the back of the Shelly Plus 1 just flip. Be aware that the normal dupont cables won’t fit in. You could either buy a matching pin header (1.27 mm pitch 0.4 mm square pins) or like me just take the dirty way and push needles through the connector. And isolated them with some tape!


Not the most beautiful but it works :slight_smile:
You need to connect the cables like so (RX and TX already transposed):

Credits to digiblur and his amazing breakdown of the shelly.
Check it out here: https://youtu.be/eLoOT3mXcMs?t=528

Connect the Cables like shown and also connect IO-0 to ground before connecting ur UART Adapter.
This boots the shelly into the bootloader and you are able to flash from there. The ground LED should briefly flicker two times and then stay on. If TX or RX are also flashing you are not in flashing mode.
After a few seconds you can the disconnect IO-0 from ground even if it does not make any difference if it stays connected I think.

Software prep:
Once connected. Check that you have installed the proper driver for your UART Bridge. Usually the manufacturers website helps. Just google it :slight_smile:
Unfortunately flashing via the esphome Dashboard does not work because some library is missing (also state: 17.11.22) (edit: this is an ARM issue. Using a different machine to run HA might work. Thanks to @ddwdiot for pointing that out)
You need to install esphome on your local machine as described here: Installing ESPHome Manually — ESPHome

Generating Firmware:
Go back to your command line and generate the yaml.
type: esphome wizard your-shelly-name.yaml
Just follow the steps in the terminal output.
the device and board are esp32 and esp32doit-devkit-v1
Here is the long version:

After setting up the yaml find it on your device. (On my Mac it was under macintoshd/users/myusername)
Open it with a text editor and add the example yaml and change the passwords to your own.
Found here: Shelly Plus 1 | devices.esphome.io

Or just here:

substitutions:
  device_name: "Shelly Plus 1"
  # Higher value gives lower watt readout
  current_res: "0.001"
  # Lower value gives lower voltage readout
  voltage_div: "1925"

esphome:
  name: shelly-plus-1
  platformio_options:
    board_build.f_cpu: 160000000L

esp32:
  board: esp32doit-devkit-v1
  framework:
    type: esp-idf
    sdkconfig_options:
      CONFIG_FREERTOS_UNICORE: y
      CONFIG_ESP32_DEFAULT_CPU_FREQ_160: y
      CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ: "160"

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  
  ap:
    ssid: "Shelly Office Fallback Hotspot"
    password: !secret ap_password

logger:

api:
  password: !secret api_password
  encryption:
    key: !secret api_encryption_key

ota:
  password: !secret ota_password

output:
  - platform: gpio
    id: "relay_output"
    pin: GPIO26

switch:
  - platform: output
    id: "relay"
    name: "${device_name} Relay"
    output: "relay_output"

binary_sensor:
  - platform: gpio
    name: "${device_name} Switch"
    pin: GPIO4
    on_press:
      then:
        - switch.toggle: "relay"
    filters:
      - delayed_on_off: 50ms
  - platform: gpio
    name: "${device_name} Button"
    pin:
      number: GPIO25
      inverted: yes
      mode:
        input: true
        pullup: true
    on_press:
      then:
        - switch.toggle: "relay"
    filters:
      - delayed_on_off: 5ms

sensor:
  - platform: ntc
    sensor: temp_resistance_reading
    name: "${device_name} Temperature"
    unit_of_measurement: "°C"
    accuracy_decimals: 1
    icon: "mdi:thermometer"
    calibration:
      b_constant: 3350
      reference_resistance: 10kOhm
      reference_temperature: 298.15K
    on_value_range:
      - above: "80.0"
        then:
          - switch.turn_off: "relay"
  - platform: resistance
    id: temp_resistance_reading
    sensor: temp_analog_reading
    configuration: DOWNSTREAM
    resistor: 10kOhm
  - platform: adc
    id: temp_analog_reading
    pin: GPIO32
    attenuation: 11db

  - platform: adc
    name: "${device_name} Relay Supply Voltage"
    pin: GPIO33
    attenuation: 11db
    filters:
      - multiply: 8

status_led:
  pin:
    number: GPIO0
    inverted: true

Flashing:
back in the command line type: esphome run your-shelly-name.yaml
This should install esphome to your shelly plus 1! Chose USB UART when it asks.
Disconnect the USB and IO-0 from ground if you haven’t already. Plug into USB again to boot the shelly.
Make sure it connects to your Wifi. If yes it should pop up in home assistants devices page as discovered.
From now on you can flash over OTA so you can install the shelly into the wall.
Flashing is then the same process of changing the yaml and running it in the terminal just chose OTA instead of USB UART.

Easy as that :slight_smile:
Bonus: If you want to add a check if your homeassistant is reachable then add this for your switch input:

#Switch input 
binary_sensor:
  - platform: gpio
    name: "${device_name} Switch"
    pin: GPIO4
    on_state:
      then:
        - if:
            condition:
                - api.connected:
            then:
                - switch.turn_on: "relay"
                - homeassistant.service:
                    service: light.toggle
                    data:
                      entity_id: light.arbeitszimmer
                - logger.log: "It works?"
            else:
                - switch.toggle: "relay"
    filters:
      - delayed_on_off: 50ms

for me it toggles my lights in the office via the ha service or just switches the relais if ha is not reachable.

3 Likes

I’ve just been through a similar process. Wish I had seen your guide before I did it. And particularly wish I’d thought of using needles. It would have been much easier.

But I was able to flash using the HA esphome dashboard on a mini PC running HA. I got a missing library error on my RPi but the problem is apparently restricted to ARM devices.

1 Like

Ah thanks, I figured that it might be the connected to the Pi after googling the error. I’ll add a note to the guide.

Thank you for the comprehensive summary, it worked for me without problems when flashing via AMD64 processor.

Unfortunately, when flashing via the ESPHome integration in Home Assistant on my RPi 4, I get errors

-- The C compiler identification is unknown
-- The CXX compiler identification is unknown

I suppose this is the issue you mentioned regarding ARM devices?
Is there any possibility to fix this?

Thanks and kind regards!

EDIT:
One remark: RX and TX is switched in the screenshot (see here: Picture and Link)
Regarding your solution with the needles, just for information:
It’s also possible to use pin headers with 1.27 mm pitch (0.4 mm square pins)

As i am aware there is no solution for the Pi right now. Maybe in a future update of esphome.

As it says in the picture RX and TX are already transposed so you should be able to just plug in the cables as it says on your Adapter. For someone with absolutely no experience with UART I think it is easier that way.

Great addition with the headers. I was aware that there are matching headers but did not know the right size. Thanks!

If you use the pin headers linked, how are you connecting the headers to the UART adapter?

I thought that would be easier and safer than the needles, but my Dupont cables are too big for the headers. Would I solder the headers to wires?

The pin headers would be the nicer option for sure. Yes you would need to solder your ends of the Dupont cables to it

Easiest way to flash to ESPHome (imo) is to do it in the next order. Using this, you dont need to connect the shelly with wires.

  1. Connect Shelly to local wifi network.

  2. Flash the Shelly to Tasmota, using this link:
    GitHub - tasmota/mgos32-to-tasmota32: ESP32 Mongoose OS to Tasmota32 OTA Firmware Updates for Shelly

  3. Now flash the ESPHome firmware using this link:
    Migrating from Tasmota — ESPHome

In this way I did all my Shelly devices. Works great!

6 Likes

Very cool solution! Seems pretty new and I think it was not available when I flashed mine.
I’ll add your comment to the guide.

1 Like

Can I ask a really dumb question? Only because I am very new to Shelly and ESPHome. What is the advantage of flashing a Shelly Plus 1 to ESPHome rather that just using the HA Shelly integration?

1 Like

I’ve never so much as touched anything Tasmota, so maybe I’m doing something really stupid… But I’m stuck trying to upload the ESPHome firmware. I’ve compressed the binary into a gzip file but the upload fails due to it still being too big (I’ve also commented everything out but the absolute minimum ESPHome setup stuff).

The Tasmota to ESPHome migration page mentions a minimal version of Tasmota being needed, but there doesn’t appear to be an ESP32 based one?

Any help is appreciated. I’ve always just gone the serial method with the regular Shelly’s but figured I’d try a pure OTA method with these.

The only big plus for me is that you can check if HA is reachable. If something doe not work, wifi, HA, what else, you can let the Shelly work as a normal switch and just toggle the light as normal.
Ps. I have smartbulbs.
But the rest of the functionality should work without esphome

Still interested in getting the OTA conversion method to work, but I got inpatient and finally just flashed it over serial. Works fine using the example YAML but my primary use-case was to use it as a BT Proxy (in addition to other things). Unfortunately, after spending several hours going through every permutation I could think of, anytime I included the BT Proxy YAML, while it would compile and let me upload it just fine (OTA or serial), the device would never connect to WiFi and I’d have to serially flash firmware without BT Proxy to get it back.

Has anyone ever figured out a way to get this working? I explicitly was going to use it with a device that requires an active BT connection (SwitchBot lock), so unfortunately the current Shelly firmware doesn’t work either, as it doesn’t support this. May just have to send these back to Amazon…

Are you sure you got the Gen 2 Shelly versions that have a bluetooth chip? The previous generation (Gen 1) did not have bluetooth but are still for sale on Amazon and other channels. I have some of the older Gen 1 Shelly’s and just recently purchased a Shelly 1 Plus (Gen 2) myself and its bluetooth works.

The problem is that the Shelly firmware only supports passive BT (as in no back and forth communication, which is required in my case). I also verified this with the second one I had (picked up all my other BT devices except the one that requires an active connection). I was hoping to use ESPHome to get around this limitation but at least at the moment doesn’t appear possible.

And yes, I definitely have the Plus version with the ESP32 chip. :slight_smile:

Or had, I sent them back.

1 Like

ok, that actually helps me out too then. I just got the Shelly Plus 1 last week hoping to use as proxy for an LD2410 and it’s not working with it, either. Kinda bummed because I figured replacing the fan switch in the bathroom with a Gen2 Shelly would give me a close proxy for the mmWave sensor also in the bathroom. Looks like I’ll just do a regular ESP32 with a physical connection to the LD2410 to save myself the headache.

Thank you for sharing this. I was able to successfully OTA a couple of these devices (Tasmota, then ESPHome), but after doing that, they wouldn’t OTA from ESPHome, I assume due to having Tasmota safeboot. I ended up flashing using sewing needles, and it was a pain in the ass but it did work. The main issue I had was I needed an external 3.3V supply; my FTDI adapter couldn’t provide enough power to keep the Shelly Plus 1’s from browning out constantly.

2 Likes

Another annotation here:
I’ll also update the post on top.
The API password is deprecated since a few months. You need to use a enryption key for that now.
Add the key under api instead of the password.

api:
  encryption: 
    key: "your_key_here"

You can get a key here: Native API Component — ESPHome

You should also add this to your config and change the password.
This enables a fallback hotspot if the shelly can’t connect to your wifi.

  ap:
    ssid: "Shelly Fallback Hotspot"
    password: !secret wifi_ap_password

The second change that can be added to your config is a check if the shelly can reach home assistant.
I configured mine that if it fails to connect to HA, then it changes its operation mode from triggering a service in HA to simply switching the relais. So if my homeassitant is not reachable my lights simply revert back to standard light switch mode.

#Switch input 
binary_sensor:
  - platform: gpio
    name: "${device_name} Switch"
    pin: GPIO4
    on_state:
      then:
        - if:
            condition:
                - api.connected:
            then:
                - switch.turn_on: "relay"
                - homeassistant.service:
                    service: light.toggle
                    data:
                      entity_id: light.arbeitszimmer
                - logger.log: "It works?"
            else:
                - switch.toggle: "relay"
    filters:
      - delayed_on_off: 50ms

These modifications should help you out if something with your connection fails.

I was able to flash Tasmota using the OTA procedure, but couldn’t flash ESPHome OTA via Tasmota. Uploading the factory.bin image failed due to invalid hash, and compressing the image with gzip and then uploading failed because the image size was too large. I think this is due to the safeboot configuration in Tasmota. Not sure if its possible to skip this step during the upgrade, as the Shelly → Tasmota install procedure says that failing to convert to safeboot will result in the device getting bricked on the next firmware update.

1 Like

Here’s my $0.02 on this… I bought the Shelly Plus 1’s and thought “cool, I’ll flash them” and I did one to see how it works. In my opinion, I prefer the Shelly firmware over ESPHome in this case. All of my Shelly firmware 1’s work great, while the one I flashed with ESPHome goes on and offline constantly, even though there is an access point 5 feet away, unobstructed. It’s enough of a hassle that I’m going to ditch that ESPHome flashed device and put a regular Shelly in its place.

This was my first dive into Shelly and I’m really impressed with everything about them, enough so that I’ve bought a dozen Shelly’s (and of course they go into my subnet that is 100% blocked from the Internet until I want a firmware update).