From a608285f11d1cf463f786c2c737191017a045b3a Mon Sep 17 00:00:00 2001 From: Michael Holzmann Date: Sat, 14 Nov 2026 15:38:05 +0000 Subject: [PATCH 1/4] docs: add build instructions (PlatformIO CLI, venv, notes) - Document CLI/venv setup alongside the VS Code extension - Add compile/upload/monitor commands and firmware output path - Record the pinned espressif32 version and why, dependency versions, first-build download, reference flash/RAM usage and clean rebuild - Add upload troubleshooting (config.h, baud rate, permissions, BOOT) --- README.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 55 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0f294b9..6ce4360 100644 --- a/README.md +++ b/README.md @@ -96,10 +96,26 @@ git clone https://github.com/MrSossidge/victron-esp32-ble-mqtt.git cd victron-esp32-ble-mqtt ``` -### 2. Install VS Code + PlatformIO +### 2. Install PlatformIO -Install [VS Code](https://code.visualstudio.com) and the **PlatformIO IDE** extension, then -open the project folder — PlatformIO reads `platformio.ini` and pulls dependencies itself. +Use either the VS Code extension (handy for interactive work) or the CLI in a +Python virtual environment: + +- **VS Code** — install [VS Code](https://code.visualstudio.com) and the + **PlatformIO IDE** extension. +- **CLI** — PlatformIO needs a Python environment: + + ```bash + sudo apt install python3-venv # Debian/Ubuntu, only if missing + python3 -m venv ~/.venvs/pio + source ~/.venvs/pio/bin/activate + python -m pip install --upgrade pip platformio + pio --version + ``` + + The venv isolates the `pio` CLI only; PlatformIO still downloads the ESP32 + toolchain and libraries into `~/.platformio` (a few hundred MB on the first + build). ### 3. Configure @@ -146,12 +162,48 @@ so its entities and discovery topics do not collide with the first one. ### 4. Build and upload +With the venv active (or call `~/.venvs/pio/bin/pio` directly): + +```bash +pio run # compile only +pio run -t upload # compile + flash +pio device monitor -b 115200 # serial log at 115200 baud +pio run -t upload -t monitor # flash, then open the monitor +``` + +In VS Code the PlatformIO status bar does the same: + | Action | Shortcut | |---|---| | Build | `Ctrl+Alt+B` | | Upload | `Ctrl+Alt+U` | | Serial monitor | `Ctrl+Alt+S` | +The binary is written to `.pio/build/esp32dev/firmware.bin`. + +#### Build notes + +- `platformio.ini` pins `espressif32@6.13.0` (Arduino core 2.0.17). It is the + last platform compatible with NimBLE-Arduino 1.4.x — do not bump it without + migrating to NimBLE-Arduino 2.x. +- Dependencies are NimBLE-Arduino 1.4.x, PubSubClient 2.8.x and ArduinoJson + 6.21.x, resolved by PlatformIO from `lib_deps`. +- A clean build takes a few minutes and needs network access; rebuilds only + compile changed files. +- Reference sizes with the default 4 MB partition table: about **77 % flash** + and **17 % RAM** used. Disabling `HA_DISCOVERY_ENABLED` frees ~4.6 KB of flash. +- Clean rebuild: `pio run -t clean`. + +#### Upload troubleshooting + +- `fatal error: config.h: No such file or directory` — run step 3 first. +- Upload times out at 921600 baud — lower `upload_speed` in `platformio.ini` + to `460800` (or `115200`). +- `Permission denied: /dev/ttyUSB0` — `sudo usermod -aG dialout $USER`, then + log out and back in. On Windows, install the CH340 driver. +- Board not detected — hold **BOOT** while the upload starts (needed on some + ESP32-C3 SuperMini boards). + --- ## MQTT topics From 98eaf718b1da64dbc59d53253dde8e82f90872ee Mon Sep 17 00:00:00 2001 From: Michael Holzmann Date: Sat, 14 Nov 2026 15:39:52 +0000 Subject: [PATCH 2/4] docs: describe build output files and where to find them --- README.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6ce4360..060d14e 100644 --- a/README.md +++ b/README.md @@ -179,7 +179,29 @@ In VS Code the PlatformIO status bar does the same: | Upload | `Ctrl+Alt+U` | | Serial monitor | `Ctrl+Alt+S` | -The binary is written to `.pio/build/esp32dev/firmware.bin`. +#### Build output + +Everything is written to the hidden `.pio/build/esp32dev/` directory: + +``` +.pio/build/esp32dev/ +├── firmware.bin # application image (the file you flash / ship via OTA) +├── bootloader.bin # ESP32 bootloader +├── partitions.bin # partition table +├── firmware.elf # ELF with debug symbols +├── firmware.map # linker map +└── src/ # compiled objects for main.cpp and victron_ble.cpp +``` + +- `.pio/` is gitignored, so build artefacts are never committed. +- `pio run -t upload` flashes all three images automatically at the usual + offsets: `bootloader.bin` at `0x1000`, `partitions.bin` at `0x8000`, + `firmware.bin` at `0x10000`. +- For OTA updates or a manual `esptool.py` write, `firmware.bin` is the image + you need. +- `firmware.elf` is used to decode crash backtraces, e.g. + `xtensa-esp32-elf-addr2line -pfiaC -e .pio/build/esp32dev/firmware.elf `, + or with PlatformIO's exception decoder in the serial monitor. #### Build notes From 593a426d4fe18ee3cb85a43537a4ce50a8e478f8 Mon Sep 17 00:00:00 2001 From: Michael Holzmann Date: Sat, 14 Nov 2026 15:42:53 +0000 Subject: [PATCH 3/4] docs: add manual esptool flashing instructions --- README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/README.md b/README.md index 060d14e..45b9830 100644 --- a/README.md +++ b/README.md @@ -226,6 +226,69 @@ Everything is written to the hidden `.pio/build/esp32dev/` directory: - Board not detected — hold **BOOT** while the upload starts (needed on some ESP32-C3 SuperMini boards). +#### Manual flashing with esptool + +`pio run -t upload` drives esptool internally. For recovery, a board without +PlatformIO, or a machine that only has the pre-built images, flash the three +partitions yourself. + +```bash +pip install esptool # esptool 5.x installs the command as `esptool` +``` + +Port names: Linux `/dev/ttyUSB0`, macOS `/dev/cu.usbserial-XXXX`, Windows `COM5`. + +Linux / macOS: + +```bash +esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash \ + 0x1000 .pio/build/esp32dev/bootloader.bin \ + 0x8000 .pio/build/esp32dev/partitions.bin \ + 0x10000 .pio/build/esp32dev/firmware.bin +``` + +Windows PowerShell (backtick continues the line): + +```powershell +esptool.py --chip esp32 --port COM5 --baud 460800 write_flash ` + 0x1000 .pio\build\esp32dev\bootloader.bin ` + 0x8000 .pio\build\esp32dev\partitions.bin ` + 0x10000 .pio\build\esp32dev\firmware.bin +``` + +Erase the whole flash first if the board is in a bad state or has a different +partition table: + +```bash +esptool.py --chip esp32 --port /dev/ttyUSB0 erase_flash +``` + +Optional: merge everything into one factory image (handy for archiving or +sharing a known-good build): + +```bash +esptool.py --chip esp32 merge_bin \ + --flash_mode dio --flash_freq 40m --flash_size 4MB \ + -o factory.bin \ + 0x1000 .pio/build/esp32dev/bootloader.bin \ + 0x8000 .pio/build/esp32dev/partitions.bin \ + 0x10000 .pio/build/esp32dev/firmware.bin + +esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash 0x0 factory.bin +``` + +Notes: + +- These offsets assume the default PlatformIO `esp32dev` 4 MB layout. If you + changed the partition table, flash `partitions.bin` and `firmware.bin` using + the offsets from that table instead. +- 921600 baud works on most boards; drop to 460800 or 115200 for flaky CH340 + clones. +- If esptool reports `Failed to connect`, hold **BOOT** while it tries, and + make sure the serial monitor is closed. +- `firmware.bin` alone is what an OTA update expects; the bootloader and + partition table are only written over USB. + --- ## MQTT topics From 83683de27c20687c4da480e7dfc6a44cf4f56ad6 Mon Sep 17 00:00:00 2001 From: Michael Holzmann Date: Sat, 14 Nov 2026 15:53:56 +0000 Subject: [PATCH 4/4] docs: use esptool 5.x hyphenated commands - write-flash / erase-flash / merge-bin instead of the deprecated write_flash / erase_flash / merge_bin - esptool instead of esptool.py - hyphenated --flash-mode/--flash-freq/--flash-size for merge-bin - note that esptool 4.x still works but prints the deprecation warning --- README.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 45b9830..57b9bc9 100644 --- a/README.md +++ b/README.md @@ -197,7 +197,7 @@ Everything is written to the hidden `.pio/build/esp32dev/` directory: - `pio run -t upload` flashes all three images automatically at the usual offsets: `bootloader.bin` at `0x1000`, `partitions.bin` at `0x8000`, `firmware.bin` at `0x10000`. -- For OTA updates or a manual `esptool.py` write, `firmware.bin` is the image +- For OTA updates or a manual `esptool` write, `firmware.bin` is the image you need. - `firmware.elf` is used to decode crash backtraces, e.g. `xtensa-esp32-elf-addr2line -pfiaC -e .pio/build/esp32dev/firmware.elf `, @@ -233,15 +233,20 @@ PlatformIO, or a machine that only has the pre-built images, flash the three partitions yourself. ```bash -pip install esptool # esptool 5.x installs the command as `esptool` +pip install esptool ``` +esptool **5.x** installs the `esptool` command and uses hyphenated subcommands +(`write-flash`, `erase-flash`, `merge-bin`). The older esptool **4.x** used +`esptool.py` with underscores (`write_flash`); that still works but prints +`Command 'write_flash' is deprecated`, so prefer the 5.x form below. + Port names: Linux `/dev/ttyUSB0`, macOS `/dev/cu.usbserial-XXXX`, Windows `COM5`. Linux / macOS: ```bash -esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash \ +esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 write-flash \ 0x1000 .pio/build/esp32dev/bootloader.bin \ 0x8000 .pio/build/esp32dev/partitions.bin \ 0x10000 .pio/build/esp32dev/firmware.bin @@ -250,7 +255,7 @@ esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash \ Windows PowerShell (backtick continues the line): ```powershell -esptool.py --chip esp32 --port COM5 --baud 460800 write_flash ` +esptool --chip esp32 --port COM5 --baud 460800 write-flash ` 0x1000 .pio\build\esp32dev\bootloader.bin ` 0x8000 .pio\build\esp32dev\partitions.bin ` 0x10000 .pio\build\esp32dev\firmware.bin @@ -260,21 +265,21 @@ Erase the whole flash first if the board is in a bad state or has a different partition table: ```bash -esptool.py --chip esp32 --port /dev/ttyUSB0 erase_flash +esptool --chip esp32 --port /dev/ttyUSB0 erase-flash ``` Optional: merge everything into one factory image (handy for archiving or sharing a known-good build): ```bash -esptool.py --chip esp32 merge_bin \ - --flash_mode dio --flash_freq 40m --flash_size 4MB \ +esptool --chip esp32 merge-bin \ + --flash-mode dio --flash-freq 40m --flash-size 4MB \ -o factory.bin \ 0x1000 .pio/build/esp32dev/bootloader.bin \ 0x8000 .pio/build/esp32dev/partitions.bin \ 0x10000 .pio/build/esp32dev/firmware.bin -esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash 0x0 factory.bin +esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 write-flash 0x0 factory.bin ``` Notes: