anvil/templates/basic

# {{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`