Attempt at building a platformio version before starting on changes to testing

README.md

@@ -41,7 +41,33 @@ External vendor documentation is not redistributed in this repo; see
 
 ## Build & flash
 
-This is an Arduino-IDE / `arduino-cli` project, not PlatformIO.
+This builds with either **PlatformIO** or the original **Arduino-IDE /
+`arduino-cli`** toolchain — the sources stay at the repo root and both flows
+compile them in place.
+
+### PlatformIO (recommended)
+
+`platformio.ini` lives at the repo root and defines a single `wii5_buoy`
+environment with a custom board (`boards/wii5_v2_2560.json`: ATmega2560 @
+11.0592 MHz, serial bootloader @ 230400).
+
+```sh
+pio run                         # compile (env: wii5_buoy)
+pio run -t upload               # compile + flash (override port with --upload-port)
+pio device monitor              # serial console @ 230400
+```
+
+Public library dependencies are declared in `lib_deps` and fetched
+automatically. Scott's own libraries (`AvgStd`, `PushButton`, `MemoryFree`,
+`SDBlock`) are vendored under `lib/`. The entry sketch
+`app/wii5_buoy/wii5_buoy.ino` is pulled into the build by `pio_main.cpp`
+(PlatformIO only auto-detects sketches at the source-dir root).
+
+> Note: PlatformIO's registry library versions differ from the historical
+> arduino-cli set, so the flash footprint is larger than the figures quoted
+> elsewhere in this repo. Pin specific `lib_deps` versions if you need parity.
+
+### Arduino IDE / arduino-cli
 
 ```sh
 # Verify the sketch compiles
@@ -112,6 +138,10 @@ A running log of notable real-world deployments lives in `DEPLOYMENTS.md`.
 app/wii5_buoy/        Arduino sketch entry point
 WII5*.{h,cpp}         Firmware source (board root, see Architecture)
 WII5_board_v2.h       Pin/peripheral map for the WII5 v2 board
+platformio.ini        PlatformIO build configuration
+boards/               PlatformIO custom board definition (wii5_v2_2560.json)
+pio_main.cpp          PlatformIO entry shim (#includes the .ino sketch)
+lib/                  Vendored libraries (AvgStd, PushButton, MemoryFree, SDBlock)
 doc/                  Design notes, command reference, generated API docs
 test/                 Smaller per-subsystem test sketches
 tools/                Build, flash, and size-profile helper scripts