scottp
295abb37ee
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.
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.
# 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-upWII5Controller.cpp— main loop, mode dispatch, watchdogWII5Commands.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. Please also read CODE_OF_CONDUCT.md and SECURITY.md before opening issues or PRs.
Contact
- Maintainer: Scott Penrose <scottp@dd.com.au>
- Bugs and feature requests: GitHub Issues
- Security issues: see SECURITY.md
License
Apache License 2.0 — see LICENSE and NOTICE.
Copyright 2012-2024 Scott Penrose scottp@dd.com.au and WII5 Buoy contributors.