ESP32 Firmware¶

Preparation¶

First, uv (version 0.10 or newer), and git have to be installed according to their installation manuals.

Additionally, on Windows Node.js (version 20 or newer) including the Node.js package manager npm (version 9 or newer) are required.

For Windows the Silicon Labs CP210x Universal Windows Driver has to be installed. Linux and macOS have this driver already build in.

The ESP32 firmware contains a few files with very long filenames. These might exceed the Windows legacy limit of 260 characters. It is recommended to enable long filename support for Windows.

Next, clone the esp32-firmware repository from GitHub using git.

We recommend Visual Studio Code as IDE with the PlatformIO IDE extension.

For initial setup the command uv sync has to be executed in a terminal in the software/ directory. The terminal inside Visual Studio Code can be used for this.

To make Visual Studio Code use the uv environment correctly, edit the following settings (ctrl+,):

• change python-envs.terminal.autoActivationType to shellStartup

• chnage platformio-ide.customPATH to the absolute path to the software/.venv/bin/ directory (Linux and macOS) or the absolute path to the software/.venv/Scripts/ directory (Windows)

• change platformio-ide.useBuiltinPIOCore to false

• change platformio-ide.useBuiltinPython to false

Then restart Visual Studio Code.

If the PlatformIO IDE extension reports problems now try to delete the .platformio/ directory in your home directory and restart Visual Studio Code.

The platformio.ini file is located in the software/ directory. Make sure to open the software/ directory in Visual Studio Code as the PlatformIO project directory to build any of the environment environments.

Firmware Building¶

The default PlatformIO environment is set to empty and doesn't build a useful firmware. Choose the PlatformIO environment corresponding to the firmware variation you want to build:

• ESP32 Brick: esp32 defined in esp32.ini

• ESP32 Ethernet Brick: esp32_ethernet defined in esp32_ethernet.ini

• WARP Charger Smart and Pro: warp defined in warp.ini

• WARP2 Charger Smart and Pro: warp2 defined in warp2.ini

• WARP3 Charger Smart and Pro: warp3 defined in warp3.ini

• WARP Energy Manager: energy_manager defined in energy_manager.ini

• WARP Energy Manager 2.0: energy_manager_v2 defined in energy_manager_v2.ini

To build a specific firmware run its corresponding PlatformIO "Build" task. You can also change the default PlatformIO environment from empty to the desired environment by modifying the platformio.ini file. For example, replace empty with esp32_ethernet in this line to build the ESP32 Ethernet Brick firmware by default:

default_envs = empty

To build a firmware, upload it to a Brick and connect to its serial console all in one step you can run the PlatformIO "Upload and Monitor" task. This requires that the Brick is connected to USB beforehand. You can also upload the built firmware via the web interface.

The firmware file can be found in software/build/ and its name ends with _merged.bin The file name has the form [environment]_firmware_[version]_[build timestamp][extension]. For example warp2_firmware_2_0_7_62d7d0b1_merged.bin is a WARP2 Charger firmware version 2.0.7 that was built at the unix timestamp 0x62d7d0b1 = 1658310833, (i.e. 2022-07-20 13:27:02).

Firmware Structure¶

The functionality and the web interface of the firmware are put together from modules. The variations of the firmware differ mostly in their list of active modules. This list is specified per environment in the corresponding .ini file using the custom_backend_modules and custom_frontend_modules options.

The tutorial regarding the ESP32 firmware shows step by step how to add a custom module to the firmware.