scottp
95bc2ae9fe
CONTRIBUTING.md: remove the deleted wii5_modes sketch from the testing
guidance; mention the surviving test/ subsystem sketches instead.
README.md: drop the now-incorrect "hardware schematics" entry from the
repository-layout block (doc/hardware/ was removed earlier). Add a
Repository section naming the Gitea canonical and the GitHub mirror
(https://github.com/SH3D/WII5Firmware) used for community issues and PRs.
SECURITY.md, CODE_OF_CONDUCT.md: point at the GitHub mirror for security
advisories; drop the vague "private GitHub message" path from the CoC.
CHANGELOG: replace the "TODO" placeholder with a real v5.5.1 initial
public release entry.
Doxyfile: rewrite the PROJECT_NUMBER injection example to use
`git describe` instead of the deleted VERSION file.
VERSION: removed. It was bumped by tools/tag_version.sh +
tools/build_version.sh (both deleted in c89c636); build_local.sh injects
WII5_SOFTWARE_VERSION from `git log -1 --pretty=%h` at compile time, so
nothing load-bearing depends on the file.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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/.
First written in 2011 and first deployed in Antarctica with NIWA in 2012; data collected was published in Nature.
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, EEPROMEx, RadioHead.
RadioHead is dual-licensed GPLv2 / commercial. The default ATmega2560
build does not link RadioHead; only LoRa-enabled builds
(-DWII5_RADIO_LORA) do, and binaries distributed from such builds
inherit GPLv2 terms.
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, generated API docs
test/ Smaller per-subsystem test sketches
tools/ Build, flash, and size-profile 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.
Repository
The canonical source is hosted on Gitea:
- Main repository: https://gitea.sh3d.com.au/Sh3d/WII5Firmware
A read-only mirror is published on GitHub for community issues and pull requests:
- GitHub mirror: https://github.com/SH3D/WII5Firmware
Open issues and PRs against the GitHub mirror; changes are reviewed there and merged back through the Gitea canonical.
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.