WII5Firmware/README.md

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 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).

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

# 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-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
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
                      (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.