Installing the Firmware
There are four methods you can use to upload the initial firmware to your device. Two of them are a bit technical but not insurmountable. If you develop software on ESP devices then you probably already have the Arduino IDE v1.8 software installed on your computer or are 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.esp32xx.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.
Starting in release v2.2.3 there are compiled onboard files for various ESP32 series. These are named for the chip series so the SomfyController.onboard.esp32s3.zip file contains the binary firmware for the ESP32-S3 and ESP32-S3 mini chip series. This also works very well on the zero series boards.
If you have a Wrover or similar series chip then the SomfyController.onboard.esp32.zip file contains your firmware. You will notice that there are only compiled firmware files for ESP32, ESP32-Sx, and ESP32-Cx files provided. This does not mean that the H series will not work it simply means that I don't have the energy to chase that chip based on its specs. On paper, including the kind money is printed on, most of the other ESP32 chip series simply walk all over the H.
| Chip Series | Onboard File | Comments |
|---|---|---|
| ESP32 | SomfyController.onboard.esp32.bin.zip | This includes chips marked as WROOM, WROVER, or devkit C or V1 |
| ESP32S2 | SomfyController.onboard.esp32s2.bin.zip | This includes mini and devkit versions |
| ESP32S3 | SomfyController.onboard.esp32s3.bin.zip | All s3 versions with 4 or 8mb of flash |
| ESP32C3 | SomfyController.onboard.esp32c3.bin.zip | All c3 versions |
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.esp32.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.esp32.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 ESP32-D2WD 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.esp32.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.esp32.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.esp32.binI developed this using the painfully awful Arduino IDE v1.8. I originally installed v2.0 then found out you cannot upload the file data to it. Download v1.8 (legacy) and save yourself several hours of searching through forums for functions that are not supported on 2.0 even several years after its release. If you are using VS Code then you are on your own since I don't have any experience with it. The good news is that you only need this during the initial install and all follow on work for the module is user friendly.
Did I mention that you shouldn't waste your time on Arduino IDE v2.0. As of January 2023, it is incomplete, and it exists only for tortured souls in search of a never realized promise. Don't do it you will be disappointed. If this situation improves I will be back to update my recommendations.
First compile and upload the firmware to the ESP32. Then upload the data using the Sketch Data upload tool. You will be happy to know that once the initial install is done you don't have to go through all these hoops to update the firmware or the LittleFS file system if you are using an ESP32S-WROOM-32 module. I created a utility that is part of the software to do this task but it is a chicken/egg thing where you need the hen on the ESP32 to hatch the egg. You can install the future firmware and the applicaton files remotely. So you can put the ESPSomfy RTS module into a remote location.
You must first install the Arduino IDE v1.8 which you will find on the Arduino Software Site. Install what they call the Legacy IDE for the platform you are developing on. Then follow the instructions to configure it for your ESP32 board. Make sure you use a USB data cable not one of the ones that is only for charging. If you cannot connect to your ESP32 then this is likely the problem.
To compile the firmware you will need to include four libraries. To install them, navigate to Sketch -> Install Library. Some of these libraries may be installed by default when you installed the Arduino IDE. They are listed below in the least likelihood of being installed already.
The libraries include:
- SmartRC-CC1101-Driver-Lib - Used to configure the transceiver.
- PubSubClient - Used to provide the MQTT interface for integration.
- WebSockets - Used to communicate the state of the shades over a websocket connection.
- ArduinoJson - JSON serializer and deserializer.
This project uses the file system on the ESP32. Follow the instructions found here to set up your Arduino IDE so it can upload the files to your board. Why this isn't just part of the Arduino development suite is a mystery but I guess that is why it is called hacking.
Once you have set up the environment press the arrow button at the top left of the Arduino IDE and it will begin compiling the software then upload when it is done. Bear in mind that this takes a bit of time to compile. If it is successful it will show in the console area at the bottom of the IDE.
All of the files required to build the file system are included in the /data/ directory of the repository. When you click on the menu Tool -> ESP32 Sketch Data Upload it will compress these files into the file system layout and upload it to the ESP32. If you have the Serial Monitor open, close it before you perform this operation as it will fail if it is open.
The good news is that it will give you some innocuous message about how the port is busy. So you don't do something silly like shut everything down, open the serial monitor and try it repeatedly.
Once you have completed compiling and uploading the sketch you are done with the arduous part. Hopefully you have not spent all your F-Bombs on this process and have some left for bombing other targets. I am seeking easier ways so if you have a suggestion feel free to open an issue describing it.
Each new release contains two files related to the firmware and can be uploaded without disconnecting the device or connecting it to USB. Keep in mind that flashing with the onboarding process will likely clear your configuration so unless you are onboarding your ESPSomfy RTS do not reflash it with the onboarding procedure.
To update your firmware to the latest version navigate to the releases section on this repository and download the SomfyController.ino.esp32.bin and SomfyController.littlefs.bin files that are contained with the release version. Once you have downloaded them navigate to the System -> Firmware tab on the ESPSomfy RTS configuration page. You should update the firmware first then the application.
Click the UPDATE FIRMWARE button and a screen will appear prompting you to select the SomfyController.ino.esp32.bin file. Once you have selected the file, press the UPLOAD FILE button to begin the transfer. The progress bard will indicate when it is done uploading the file. Your the ESPSofy RTS device will reboot after it finishes so give it at least 15 seconds to reconnect after the upload finishes.
After the firmware has been updated, you are ready to update the application binary file. Press the UPDATE APPLICATION button and select the SomfyController.littlefs.bin into the space provided. Once it is selected press the UPLOAD FILE button. Once completed, the screen will refresh and your software update is complete.