Initial public release of WII5 Buoy firmware
Firmware for an autonomous wave-measurement buoy (ATmega2560-based WII5 v2 board). Reads wave motion from a Sparton AHRS-M1/M2 IMU, samples GPS and battery state, and reports back over Iridium SBD satellite telemetry. Originally developed 2012-2024. This is the first public release. Code, documentation, and field-tested operating modes (Capture, Sleep, Position, ManualTest, SelfTest, LowBattery) are licensed under Apache 2.0 — see LICENSE and NOTICE. See README.md for an overview and build instructions, CONTRIBUTING.md for how to contribute, and DEPLOYMENTS.md for the field-deployment log.
This commit is contained in:
@@ -0,0 +1,90 @@
|
||||
# Contributing to WII5 Buoy Firmware
|
||||
|
||||
Thanks for your interest in contributing! This is firmware for an
|
||||
Arduino/AVR-based wave-measurement buoy. Most contributors will be people
|
||||
porting it to new hardware, fixing bugs found in the field, or adding sensor
|
||||
support. The notes below are aimed at making PRs reviewable and avoiding the
|
||||
classes of mistakes that have bitten us in the past.
|
||||
|
||||
## How to discuss before coding
|
||||
|
||||
For anything bigger than a typo or a small bug fix, **open an issue first**
|
||||
to discuss the approach. Embedded firmware is full of subtle hardware
|
||||
constraints (program-memory budget, real-time deadlines, ISR safety) and a
|
||||
short up-front conversation usually saves a long review.
|
||||
|
||||
## Building locally
|
||||
|
||||
This is an Arduino IDE / `arduino-cli` project targeting the
|
||||
ATmega2560 on a custom WII5 v2 board (see `WII5_board_v2.h`).
|
||||
|
||||
The build scripts in `tools/` are parameterized via env vars; copy
|
||||
`tools/upload.sh` to `tools/upload.local.sh` (gitignored) and edit, or
|
||||
export `WII5_BUILD_DIR`, `WII5_AVRDUDE_CONF`, `WII5_REMOTE`, etc. as needed.
|
||||
See each script's preamble for the env vars it expects.
|
||||
|
||||
## Submitting changes
|
||||
|
||||
1. Fork the repository, create a topic branch off `main`.
|
||||
2. Keep commits small and reviewable. One logical change per commit.
|
||||
3. Use clear commit messages. The first line is a short summary
|
||||
(`<area>: <verb> <object>`), followed by a blank line and the rationale
|
||||
in prose if non-obvious.
|
||||
4. Sign off your commits to certify the
|
||||
[Developer Certificate of Origin](https://developercertificate.org/):
|
||||
```
|
||||
git commit -s
|
||||
```
|
||||
5. Verify the sketch still compiles for `WII:avr:wii5_v2_2560_3V` before
|
||||
pushing.
|
||||
6. Open a pull request. The PR template will prompt you for the things
|
||||
reviewers care about (testing performed, hardware impact, etc.).
|
||||
|
||||
## Code conventions
|
||||
|
||||
- **No internal infrastructure references.** Don't introduce hardcoded
|
||||
hostnames, IP addresses, IMEIs, GPS coordinates, personal email addresses,
|
||||
or developer-specific paths. Use env vars in scripts and `#define`s in
|
||||
`WII5_board_*.h` for hardware-specific values. See `SECURITY.md`.
|
||||
- **Don't break the flash budget.** The ATmega2560 has 256 KB of program
|
||||
memory; we already use a meaningful fraction. Watch the `Sketch uses ...`
|
||||
line at the end of `arduino-cli compile`. New features that cost more than
|
||||
~2 KB should mention the cost in the PR description.
|
||||
- **Use the `console` abstraction**, not raw `Serial.print`. The console
|
||||
routes output to whatever serial port the board is configured for, and
|
||||
supports `LOG_DEBUG` / `LOG_INFO` / `LOG_WARN` / `LOG_ERROR` / `LOG_FATAL`
|
||||
log levels. Raw `Serial.print` should only appear inside `#ifdef
|
||||
WII5_DEBUG_*` blocks.
|
||||
- **Use `F()` / `PSTR()` for string literals** to keep them in flash, not RAM.
|
||||
- **TODO/FIXME convention.** `// TODO: ...` for known gaps, `// FIXME: ...`
|
||||
for known-broken things that need attention. We previously used `XXX`
|
||||
internally; new code should use `TODO`/`FIXME`.
|
||||
- **Keep comments accurate.** A comment that contradicts the code is worse
|
||||
than no comment.
|
||||
|
||||
## Adding a new sensor / driver
|
||||
|
||||
Subclass `WII5Power` (gives you `powerOn()` / `powerOff()` / `running` state).
|
||||
Implement `controllerId()` and `driverId()` to return the appropriate
|
||||
enumerators in `WII5Data.h`. Provide `begin()`, `loop()`, `start()`, `stop()`.
|
||||
Wire it into `WII5Setup.cpp`'s `begin()` and `WII5Controller.cpp`'s
|
||||
`loopOther()`. Look at `WII5GPS`, `WII5Battery`, or `WII5Weather_18B20` for
|
||||
small worked examples.
|
||||
|
||||
## Testing
|
||||
|
||||
There is no automated test harness for the firmware itself — testing is done
|
||||
by flashing onto real hardware and exercising the `wii5_buoy` and
|
||||
`wii5_modes` sketches. The `test/` directory contains smaller sketches
|
||||
demonstrating individual subsystems; please add a sketch there if you add a
|
||||
new driver.
|
||||
|
||||
In your PR, describe:
|
||||
- What you tested on (hardware or just compile?)
|
||||
- Which mode(s) you exercised (Capture, Position, Sleep, ManualTest, etc.)
|
||||
- Any known gaps (e.g. "didn't test on a battery-only run").
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions will be licensed under
|
||||
the Apache License 2.0 (see `LICENSE`).
|
||||
Reference in New Issue
Block a user