scottp
c89c636cb7
Reduce tools/ to the four scripts an outside contributor needs: build, verify, flash, and size-profile. Drop maintainer-only workflow scripts (sibling-repo pulls, firmware-archive auto-commit, version tagging), broken stubs (doxygen.sh, variables.sh), and the entire tools/2024/ directory. tools/2024/ included a 647 KB Arduino.tar.gz bundling 20 third-party Arduino libraries (RadioHead = GPLv2, TinyGPSPlus = LGPL, etc.) without per-library attribution in NOTICE; a 503 KB GPL avrdude.conf; the GPL Optiboot bootloader hex; and pre-built firmware/test binaries. Users install the libraries via Arduino Library Manager (per README), use the system avrdude, and reproduce the firmware from source. README.md: add EEPROMEx to the library list (used by WII5Config / WII5Sh3dConfig); note that RadioHead is GPLv2 dual-licensed and only LoRa builds (-DWII5_RADIO_LORA) link it. CONTRIBUTING.md: replace the dead tools/upload.sh reference with the generic *.local.sh pattern. Kept: build_local.sh, verify.sh, icsp.sh, memory.pl. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
136 lines
5.0 KiB
Markdown
136 lines
5.0 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/`.
|
|
|
|
## 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.
|