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

```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, 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
doc/                  Design notes, command reference, hardware schematics
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](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 <scottp@dd.com.au>
- 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.