Skip to content
Communicator Badge

Build and flash

With ESP-IDF active in your shell, build from the repository root:

Terminal window
idf.py set-target esp32s3
idf.py build

The first build fetches LVGL through the component manager and compiles ESP-IDF, so it takes a few minutes. Later builds reuse the cache and are much faster. A clean build produces an app of roughly 1.6 MB, about half of one of the two 3 MB application slots.

Flash

Section titled “Flash”

Connect the badge over USB and find its serial port (for example COM12 on Windows, or /dev/ttyACM0 on Linux). Then:

Terminal window
idf.py -p COM12 flash monitor

flash writes the bootloader, partition table, and application. monitor opens the serial console so you can watch the boot log. Exit the monitor with Ctrl+].

If the badge does not enter download mode on its own, hold BOOT, tap RESET, and release BOOT, then run the command again.

First flash over the badge’s original firmware

Section titled “First flash over the badge’s original firmware”

The first time you flash a badge that shipped with other firmware (the original MicroPython image), erase the whole chip once before the normal flash:

Terminal window
idf.py -p COM12 erase-flash
idf.py -p COM12 flash monitor

A plain flash only writes the bootloader, partition table, otadata, and the application slot; it leaves the nvs, phy_init, and storage partitions untouched. Stale nvs left by the previous firmware can be read back as out-of-spec settings and cause hard-to-diagnose misbehaviour — see a solid white screen for the case seen in practice. erase-flash clears all of it. You only need to do this once per badge.

Flash a build you already have

Section titled “Flash a build you already have”

idf.py flash reuses whatever is in build/ if nothing changed, so it does not rebuild. You can also flash with esptool directly from the build directory using the arguments the build printed:

Terminal window
python -m esptool --chip esp32s3 -p COM12 write-flash "@flash_args"

Notes on configuration

Section titled “Notes on configuration”

sdkconfig.defaults sets the target to ESP32-S3, 16 MB flash, octal PSRAM, and dynamic frequency scaling. The LVGL NV3007 display driver is not exposed through LVGL’s Kconfig, so the top level CMakeLists.txt enables it (and its generic-MIPI dependency) with -DCONFIG_LV_USE_NV3007=1 and -DCONFIG_LV_USE_GENERIC_MIPI=1. You do not need to change anything for a normal build.

Partitions and over-the-air updates

Section titled “Partitions and over-the-air updates”

partitions.csv carries two 3 MB application slots (ota_0 and ota_1) plus the otadata marker, so a new image can be written to the spare slot — over USB or through the web UI — and booted with rollback if it fails to start. The rest of the flash is an ~9.6 MB SPIFFS area for GPS tracks and assets.

Changing the partition table is a one-time USB flash: a new table, and the SPIFFS area that moves with it, cannot be delivered over the air, and the SPIFFS reformats (saved GPS tracks are lost). After that first cable flash you can update over the air from the web UI.