Repository navigation
Installing the Firmware
There are three methods you can use to upload the initial firmware to your device, and you can also build it from source. If you develop software on ESP devices then you are probably familiar with the esptool.py script. If you haven't dabbled in these tools, then choose either the ESP32 flash download tool method or the ESPHome web method as they are fairly straight forward. I didn't ask him to try, but I think that even the hairy cave dude from the Geico commercials can get this done.
The initial firmware onboarding can be performed using a single file without having to recompile the software using the SomfyController.onboard.<chip>.bin file for the release. Download the file that matches your ESP32 chip series to your computer somewhere and un-compress the zip. The file is located on this repository under releases on the right side of the main page. Please note that if you flash this file to your device it will erase your shade configuration so if this is not a new install perform the update procedure instead of this onboarding procedure.
The onboard files are named for the chip series, so SomfyController.onboard.esp32s3.bin.zip contains the firmware for the ESP32-S3, and SomfyController.onboard.esp32.bin.zip the firmware for the original ESP32, such as a WROOM or WROVER. Find your chip in the table below. There are no files for the ESP32-S2 or the H series.
| Chip Series | Onboard File | Comments |
|---|---|---|
| ESP32 | SomfyController.onboard.esp32.bin.zip | This includes chips marked as WROOM, WROVER, or devkit C or V1. Needs 4 MB of flash. Wired Ethernet support, like the ESP32-P4 |
| ESP32S2 | SomfyController.onboard.esp32s2.bin.zip | Last built for v2.4.7. Releases from v3.0.0 have no S2 file |
| ESP32S3 | SomfyController.onboard.esp32s3.bin.zip | Needs 8 MB of flash or more. The image doesn't fit an S3 board with 4 MB, such as many S3 Zero and Super Mini boards |
| ESP32C3 | SomfyController.onboard.esp32c3.bin.zip | v3.1.0 to v4.0.0.beta have no C3 file. From v4.0.0, chip revision v0.3 or later only. esptool prints the revision when it connects, e.g. Chip is ESP32-C3 (QFN32) (revision v0.4). An older C3 stays on v3.0.x |
| ESP32C5 | SomfyController.onboard.esp32c5.bin.zip | From v4.0.0, not tested on hardware yet. Like the C6, it has one app slot, so it is updated over USB with this file, not with Update Firmware in the web UI. This file also replaces the configuration: take a backup first and restore it afterwards |
| ESP32C6 | SomfyController.onboard.esp32c6.bin.zip | From v3.0.10. It has one app slot, so it is updated over USB with this file, not with Update Firmware in the web UI. This file also replaces the configuration: take a backup first and restore it afterwards |
| ESP32P4 | SomfyController.onboard.esp32p4.bin.zip | From the release after v4.0.0, not tested on hardware yet. For chip revision v3.01 or later. esptool prints the revision when it connects, e.g. Chip is ESP32-P4 (revision v3.1). Updates from the web UI like the ESP32. Wired Ethernet too, e.g. on Waveshare's ESP32-P4-WIFI6-POE-ETH; WiFi goes through the board's ESP32-C6, which needs the esp-hosted firmware the board ships with |
| ESP32P4 before v2.0 | SomfyController.onboard.esp32p4es.bin.zip | As the line above, for chip revision v1.x (before v2.0), which most P4 boards sold so far have. A file for the wrong revision doesn't boot. No file runs on revision v2.x or v3.00 |
Next connect your ESPSomfy RTS device to your computer with a USB data cable. You must use a data cable and not a charge only cable. You will not be able to tell these apart and if you are having issues communicating with the device, it is likely that you have a charge only cable. Dig through that big box of cables that everyone has for another one and give it a try.
The easiest way to onboard a new ESPSomfy RTS device is to use the https://web.esphome.io website. To get started, set up your device to begin receive firmware. If you are using an ESP32s device there is nothing to do here other than connecting a USB data cable between your computer and the ESPSomfy RTS device. For others you may need to enable the firmware flash mode by jumpering certain pins on the board. Check the documentation for your board to set it into firmware flash mode.
After you have dowloaded the SomfyController.onboard.<chip>.bin file from the releases section of this repository, open the https://web.esphome.io website. Next click the connect button on the ESPHome web interface and a list of installed serial ports should appear in a dialog. Select the port that your ESPSomfy RTS device is connected to and press connect.
Ignore the Prepare for first use button and choose install. When the Install your existing ESPHome project dialog appears, click on the choose file button and select the SomfyController.onboard.<chip>.bin file. Finally, click the INSTALL button and the firmware will load onto your device.
Once the flash process is complete disconnect any jumpers you have installed to get the device to accept firmware and reboot the device. Then follow the instructions to connect the device to your network in the Configuring the Software wiki.
The flash download tool is a straight forward way to onboard your new ESPSomfy RTS device but requires downloading the flash download tool to your computer. Depending on the device you have chosen, you may need to set the device into download mode. For instance, the WT32-ETH01 requires a jumper between the IO0 and ground before uploading any firmware to it. So check your documentation and set the board appropriately.
For those of you using a regular ESP32S device then you do not need to set any jumpers. The chip select will be controlled by the software.
Download the ESP32 Flash Download tool from the Espressif website. https://www.espressif.com/en/support/download/other-tools
This tool only works in Windows but I suspect that if you are on a Linux environment you will be using the other method anyway. For you Mac users, I just dunno... yet. If you have some variant on how to get this done when a user has five thumbs on each hand let me know.
Once you download the zip file extract it to a directory. In this newly extracted directory you will find an executable file named for the version you downloaded. I downloaded version 3.9.4 so run the flash_download_tool_3.9.4.exe file.
A window will appear asking for a ChipType. Choose the one that matches your board (ESP32-D2WD for an original ESP32) and leave the rest of the settings alone. Then press OK. At the top of the next screen check the top file checkbox. Then click the ... next to the top one and select the file SomfyController.onboard.<chip>.bin file from the location where you downloaded it to. In the @ box next to it enter 0x0000. The download tool will have one entry in it this like below.
Next choose the COM port from the dropdown. If you do not know which COM port the device is on, unplug the USB port and see which one goes away from the dropdown. Then plug it back in and use that one. You do not need to change any of the other values. Once you have selected the COM Port press the START button and the firmware will start flashing to your device. If you receive a communications stability error 8-download data fail try it again as any inconsistency in the packets over the port can cause it to fail.
If you continue to receive an error then double check to ensure you have set the board to download mode using whatever jumper or voodoo chant required to get the board to accept firmware. If you are sure you have done this correctly, then the next most likely issue is the cable you are using. There are a ton of cables out there that are charge only. This means they are not capable of sending or receiving data. On the surface you will not be able to tell which is which but I suspect it is cheaper to not include two wires inside the cable.
Once the flash process is complete disconnect any jumpers you have installed to get the device to accept firmware and reboot the device. Then follow the instructions to connect the device to your network in the Configuring the Software wiki.
You are now free to upload firmware using the included web interface.
You can use esptool to install the initial firmware. This will require running a few scripts from the command line.
If you do not already have esptool installed run the following command to install it.
pip install --user esptoolFirst determine which port your ESP32 is connected to. If this is a linux computer a likely candidate will be /dev/ttyUSBn where n is the port number for the usb device. The easiest way to find this port number is to plug in the ESP32 then run ls -l /dev/ttyUSB* then disconnect it and run the command again. Whichever port went away is the one you want.
If you are running in a Windows environment you can find the COMn port from the device manager.
Once you have determined which port your ESP32 is connected to you can flash it using the following commands. Replace /dev/ttyUSB0 with the port you identified above and the ~/path/to/SomfyController.onboard.<chip>.bin with the location of the firmware file.
# Check if everything works by checking the ID of the ESP32
esptool.py --port /dev/ttyUSB0 flash_id
# Erase whatever is on there
esptool.py --port /dev/ttyUSB0 erase_flash
# Write the SomfyController image
esptool.py --port /dev/ttyUSB0 write_flash 0x0 ~/path/to/SomfyController.onboard.<chip>.binThe firmware is built with PlatformIO on the pioarduino platform (Arduino 3.3 on ESP-IDF 5.5). Stock PlatformIO Core refuses that platform, so install pioarduino's Core instead, either with pip install pioarduino or with the pioarduino IDE extension for VS Code. The Arduino IDE can't build it.
Clone the repository, connect the board, and build and upload both the firmware and the file system for your chip:
pio run -e esp32dev -t upload # the firmware
pio run -e esp32dev -t uploadfs # the web UI, on LittleFS| Chip | Environment |
|---|---|
| ESP32 | esp32dev |
| ESP32-S3 | esp32s3 |
| ESP32-C3 | esp32c3 |
| ESP32-C5 | esp32c5 |
| ESP32-C6 | esp32c6 |
| ESP32-P4, revision v3.01 or later | esp32p4 |
| ESP32-P4, revision before v2.0 | esp32p4es |
The web UI is built from data-src into data as part of the build. The repository's AGENTS.md describes the unit tests.
An update from a 3.x device's web UI to 4.0.0 fails: the 3.x web UI and the 4.0.0 firmware don't work with each other. Flash 4.0.0 over USB instead:
- Take a backup in the 3.x web UI (System -> Firmware -> Backup).
- Flash
SomfyController.onboard.<chip>.binfrom the 4.0.0 release's.zip, with any of the methods above. It holds the firmware, the web UI and an empty configuration. - Connect the device to your network (Configuring the Software), then restore the backup (System -> Firmware -> Restore).
Before you flash, update the Home Assistant integration to v3.0.1 or later; older versions don't work with 4.0.0. The 4.0.0 release notes list the other changes.
Once a device runs 4.0.0, ESP32, ESP32-S3, ESP32-C3 and ESP32-P4 devices update from the web UI: see Updating ESPSomfy RTS. ESP32-C5 and ESP32-C6 devices have no room for a second firmware, so they are always updated over USB with the onboard file. It replaces the configuration too: take a backup first and restore it afterwards.
Don't reflash a device that is already set up with the onboard file unless you have to: it clears the configuration.