WII5Firmware/CONTRIBUTING.md

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:

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