# {{PROJECT_NAME}}
Arduino project generated by [Anvil](https://github.com/nexusworkshops/anvil) v{{ANVIL_VERSION}}.
This project is self-contained. After creation, it only needs `arduino-cli`
in PATH -- the Anvil binary is not required for day-to-day work.
## Quick Start
```bash
# Compile only (verify)
./build.sh
# Compile and upload to board
./upload.sh
# Compile, upload, and open serial monitor
./upload.sh --monitor
# Open serial monitor (no compile)
./monitor.sh
# Persistent monitor (reconnects after reset/replug)
./monitor.sh --watch
# Run host-side unit tests (no board needed)
./test/run_tests.sh
```
On Windows, use `build.bat`, `upload.bat`, `monitor.bat`, and
`test\run_tests.bat` instead.
All scripts read settings from `.anvil.toml` -- edit it to change
the board, baud rate, include paths, or compiler flags.
## Project Structure
```
{{PROJECT_NAME}}/
{{PROJECT_NAME}}/
{{PROJECT_NAME}}.ino Entry point (setup + loop)
lib/
hal/
hal.h Hardware abstraction interface
hal_arduino.h Real hardware implementation
app/
{{PROJECT_NAME}}_app.h Application logic (testable)
test/
mocks/
mock_hal.h Google Mock HAL
sim_hal.h Stateful simulator HAL
test_unit.cpp Unit tests
CMakeLists.txt Test build system
run_tests.sh Test runner (Linux/Mac)
run_tests.bat Test runner (Windows)
build.sh / build.bat Compile sketch
upload.sh / upload.bat Compile + upload to board
monitor.sh / monitor.bat Serial monitor
.anvil.toml Project configuration
```
## Architecture
All hardware access goes through the `Hal` interface. The app code
(`lib/app/`) depends only on `Hal`, never on `Arduino.h` directly.
This means the app can be compiled and tested on the host without
any Arduino hardware.
Two HAL implementations:
- `ArduinoHal` -- passthroughs to real hardware (used in the .ino)
- `MockHal` -- Google Mock for verifying exact call sequences in tests
## Configuration
Edit `.anvil.toml` to change board, baud rate, or build settings:
```toml
[build]
fqbn = "arduino:avr:uno"
warnings = "more"
include_dirs = ["lib/hal", "lib/app"]
extra_flags = ["-Werror"]
[monitor]
baud = 115200
```
## Prerequisites
- `arduino-cli` in PATH with `arduino:avr` core installed
- For host tests: `cmake`, `g++` (or `clang++`), `git`
- Install everything at once: `anvil setup`
8fe1ef0e27