Initial public release of WII5 Buoy firmware

Firmware for an autonomous wave-measurement buoy (ATmega2560-based WII5 v2 board). Reads wave motion from a Sparton AHRS-M1/M2 IMU, samples GPS and battery state, and reports back over Iridium SBD satellite telemetry. Originally developed 2012-2024. This is the first public release. Code, documentation, and field-tested operating modes (Capture, Sleep, Position, ManualTest, SelfTest, LowBattery) are licensed under Apache 2.0 — see LICENSE and NOTICE. See README.md for an overview and build instructions, CONTRIBUTING.md for how to contribute, and DEPLOYMENTS.md for the field-deployment log.
2026-05-07 16:00:21 +10:00
commit 295abb37ee
122 changed files with 38142 additions and 0 deletions
@@ -0,0 +1,129 @@
+# WII5 Buoy Firmware
+
+Firmware for an autonomous wave-measurement buoy. Reads wave motion from a
+Sparton AHRS, samples GPS and battery state, and reports back over Iridium
+SBD satellite telemetry. Targets the ATmega2560 on a custom WII5 v2 board.
+
+> "WII5 = WII3 WDT + WII1 Buoy Combined" — the firmware merges the older
+> WII3 watchdog/maths-CPU lineage with the WII1 buoy I/O lineage. Design
+> notes and lineage live in `doc/`.
+
+## Overview
+
+The buoy runs in one of several modes:
+
+- **Capture** — IMU/wave-motion data capture and SD logging
+- **Position** — periodic GPS position + Iridium telemetry only (low power)
+- **Sleep** — long sleeps between wake-ups, Maths CPU off
+- **Manual Test** — operator-driven hardware exercise via console
+- **Self Test** — automated boot-time hardware checks
+- **Low Battery** — degraded operation when batteries are low
+
+Mode is selected from EEPROM defaults, then can be overridden by Iridium
+commands, the local console, or battery-management state. See
+`doc/MODES.txt` and `WII5Controller.cpp::calculateCurrentMode()`.
+
+## Hardware
+
+- **Main board:** WII5 v2 (custom AVR carrier)
+- **MCU:** ATmega2560 @ 11.0592 MHz, 256 KB flash, 8 KB RAM, 4 KB EEPROM
+- **IMU / wave sensor:** Sparton AHRS-M1 or AHRS-M2 (NorthTek-programmable)
+- **Sat radio:** Iridium 9602 / 9603 SBD
+- **GPS:** u-blox NEO-6M / NEO-7M (NMEA, parsed via TinyGPS++)
+- **Storage:** dual SD cards (one active, one reserve)
+- **Sensors:** Dallas DS18B20 temperature, battery voltage analog inputs
+
+External vendor documentation is not redistributed in this repo; see
+`doc/EXTERNAL_REFERENCES.md` for links.
+
+## Build & flash
+
+This is an Arduino-IDE / `arduino-cli` project, not PlatformIO.
+
+```sh
+# Verify the sketch compiles
+arduino-cli compile \
+    -b WII:avr:wii5_v2_2560_3V:cpu=atmega25603V3_11MHz230400 \
+    app/wii5_buoy/wii5_buoy.ino
+
+# Or use the parameterized helper script
+WII5_BUILD_DIR=~/Arduino/build \
+WII5_AVRDUDE_CONF=~/.arduino15/.../avrdude.conf \
+WII5_SERIAL=/dev/ttyUSB0 \
+WII5_FULL_HEX=~/Arduino/build/wii5_buoy.ino.hex \
+    tools/build_local.sh
+```
+
+The `tools/` scripts are all parameterized via env vars — read each
+script's preamble for the variables it expects. Copy any of them to
+`*.local.sh` (gitignored) if you want to set defaults locally.
+
+Library dependencies (install via Arduino Library Manager or
+`arduino-cli lib install`): TimeLib, RTClib, elapsedMillis, TinyGPSPlus,
+AvgStd, IridiumSBD, OneWire, DallasTemperature, SDBlock, CRC32,
+PushButton, MemoryFree, LowPower, RadioHead.
+
+## Architecture
+
+Each subsystem is a class deriving from `WII5` (base) or `WII5Power`
+(power-managed peripherals). Singleton instances hang off the global
+namespace (`wii5Controller`, `wii5Iridium`, `wii5Sparton`, etc.) and are
+called from `WII5Controller::loop()` according to the active mode.
+
+Top-level entry points:
+
+- `app/wii5_buoy/wii5_buoy.ino` — `setup()` / `loop()`
+- `WII5Setup.cpp` — initial hardware bring-up
+- `WII5Controller.cpp` — main loop, mode dispatch, watchdog
+- `WII5Commands.cpp` — text-protocol command handler (console + Iridium)
+
+## LED status codes
+
+LEDs are the field-diagnostic language; preserve their meanings.
+
+| Mode / state | LED 1 | Notes |
+| --- | --- | --- |
+| Capture (default after 5 min) | `LED_SHORT` | |
+| Capture, waiting | `LED_SLOW` | |
+| Capture, error | `LED_FAST` | |
+| Capture, just started | `LED_TRIPPLE` | reverts to `LED_SHORT` after 5 min |
+| Sleep | `LED_DOUBLE` | |
+| Low Battery | `LED_TRIPPLE_GAP` | |
+| Position | `LED_SHORT` | (same as Capture default — disambiguate by mode) |
+| Off / asleep / broken | `LED_OFF` | not a "safe" indicator |
+| On (no blink) | `LED_ON` | not safe — may have crashed |
+| Idle / good | `LED_SLOW` | |
+
+## Field deployments
+
+A running log of notable real-world deployments lives in `DEPLOYMENTS.md`.
+
+## Repository layout
+
+```
+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
+doc/                  Design notes, command reference, hardware schematics
+test/                 Smaller per-subsystem test sketches
+tools/                Build, flash, and version helper scripts (env-var
+                      driven; copy to *.local.sh to set local defaults)
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Please also read
+[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) and [SECURITY.md](SECURITY.md)
+before opening issues or PRs.
+
+## Contact
+
+- Maintainer: Scott Penrose &lt;scottp@dd.com.au&gt;
+- Bugs and feature requests: GitHub Issues
+- Security issues: see [SECURITY.md](SECURITY.md)
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
+
+Copyright 2012-2024 Scott Penrose <scottp@dd.com.au> and WII5 Buoy contributors.