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>
91 lines
4.1 KiB
Markdown
91 lines
4.1 KiB
Markdown
# 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 any
|
|
of them to `tools/<name>.local.sh` (gitignored) and edit, or export
|
|
`WII5_BUILD_DIR`, `WII5_AVRDUDE_CONF`, `WII5_SERIAL`, 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` sketch. The
|
|
`test/` directory contains smaller per-subsystem sketches (Iridium, Sparton,
|
|
GPS, DS18B20, BinData, console commands, pin diagnostics); 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`).
|