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