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)
This commit is contained in:
Michael Holzmann 2026-11-14 15:38:05 +00:00
parent 156f43323c
commit a608285f11
1 changed files with 55 additions and 3 deletions

View File

@ -96,10 +96,26 @@ git clone https://github.com/MrSossidge/victron-esp32-ble-mqtt.git
cd victron-esp32-ble-mqtt 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 Use either the VS Code extension (handy for interactive work) or the CLI in a
open the project folder — PlatformIO reads `platformio.ini` and pulls dependencies itself. 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 ### 3. Configure
@ -146,12 +162,48 @@ so its entities and discovery topics do not collide with the first one.
### 4. Build and upload ### 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 | | Action | Shortcut |
|---|---| |---|---|
| Build | `Ctrl+Alt+B` | | Build | `Ctrl+Alt+B` |
| Upload | `Ctrl+Alt+U` | | Upload | `Ctrl+Alt+U` |
| Serial monitor | `Ctrl+Alt+S` | | 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 ## MQTT topics