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