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>
153 lines
5.5 KiB
Markdown
153 lines
5.5 KiB
Markdown
# 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, 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](CONTRIBUTING.md). Please also read
|
|
[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) and [SECURITY.md](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](https://github.com/SH3D/WII5Firmware/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.
|