Files

Eric Ratliff 8fe1ef0e27 Refactor CLI, add refresh command, fix port detection, add device tracking

- Remove build/upload/monitor subcommands (projects are self-contained)
- Remove ctrlc dependency (only used by removed monitor watch mode)
- Update next-steps messaging to reference project scripts directly

- Add 'anvil refresh [DIR] [--force]' to update project scripts
  to latest templates without touching user code

- Fix Windows port detection: replace fragile findstr/batch TOML
  parsing with proper comment-skipping logic; add _detect_port.ps1
  helper for reliable JSON-based port detection via PowerShell

- Add .anvil.local for machine-specific config (gitignored)
  - 'anvil devices --set [PORT] [-d DIR]' saves port + VID:PID
  - 'anvil devices --get [-d DIR]' shows saved port status
  - VID:PID tracks USB devices across COM port reassignment
  - Port resolution: -p flag > VID:PID > saved port > auto-detect
  - Uppercase normalization for Windows COM port names

- Update all .bat/.sh templates to read from .anvil.local
- Remove port entries from .anvil.toml (no machine-specific config in git)
- Add .anvil.local to .gitignore template
- Expand 'anvil devices' output with VID:PID, serial number, and
  usage instructions

2026-02-18 20:32:42 -06:00

3.7 KiB

Raw Blame History

Anvil

Arduino project generator and build tool -- forges clean embedded projects.

A single binary that scaffolds self-contained Arduino projects with hardware abstraction, Google Mock infrastructure, and a streamlined build/upload/monitor workflow. Works on Linux and Windows.

Generated projects are fully standalone -- they only need arduino-cli in PATH. The Anvil binary is a scaffolding and diagnostic tool, not a runtime dependency.

Anvil is a Nexus Workshops project.

Install

Download the latest release binary for your platform:

# Linux
chmod +x anvil
sudo mv anvil /usr/local/bin/

# Windows
# Add anvil.exe to a directory in your PATH

Then run first-time setup:

anvil setup

This checks for arduino-cli, installs the arduino:avr core, and verifies your system is ready.

Quick Start

# Create a new project
anvil new blink

# Enter the project
cd blink

# Compile (verify only)
./build.sh

# Compile and upload to board
./upload.sh

# Compile, upload, and open serial monitor
./upload.sh --monitor

# Run host-side tests (no board needed)
./test/run_tests.sh

On Windows, use build.bat, upload.bat, monitor.bat, and test\run_tests.bat.

What Anvil Does vs. What the Project Does

Need Anvil for	Don't need Anvil for
`anvil new` (create project)	`./build.sh` (compile)
`anvil doctor` (diagnose)	`./upload.sh` (flash)
`anvil setup` (install core)	`./monitor.sh` (serial)
`anvil devices` (port scan)	`./test/run_tests.sh` (test)

Once a project is created, Anvil is optional. Students clone the repo, plug in a board, and run ./upload.sh.

Commands

Command	Description
`anvil new NAME`	Create a new project with HAL and test scaffold
`anvil doctor`	Check system prerequisites
`anvil setup`	Install arduino-cli and AVR core
`anvil devices`	List connected boards and serial ports
`anvil build DIR`	Compile and upload a sketch (convenience)
`anvil upload DIR`	Upload cached build (convenience)
`anvil monitor`	Open serial monitor (convenience)

The build, upload, and monitor commands are convenience wrappers. They do the same thing as the generated scripts.

Project Architecture

Every Anvil project uses a Hardware Abstraction Layer (HAL):

your-project/
    your-project/your-project.ino   -- entry point
    lib/hal/hal.h                   -- abstract interface
    lib/hal/hal_arduino.h           -- real hardware (Arduino.h)
    lib/app/your-project_app.h      -- app logic (testable)
    test/mocks/mock_hal.h           -- Google Mock HAL
    test/test_unit.cpp              -- unit tests
    build.sh / build.bat            -- compile
    upload.sh / upload.bat          -- compile + flash
    monitor.sh / monitor.bat        -- serial monitor
    .anvil.toml                     -- project config

The app code depends on Hal, never on Arduino.h directly. This means your application logic compiles and runs on the host for testing.

Configuration

Each project has an .anvil.toml:

[project]
name = "blink"

[build]
fqbn = "arduino:avr:uno"
warnings = "more"
include_dirs = ["lib/hal", "lib/app"]
extra_flags = ["-Werror"]

[monitor]
baud = 115200

Building from Source

cargo build --release

The release binary is at target/release/anvil (Linux) or target\release\anvil.exe (Windows).

License

MIT -- see LICENSE.

3.7 KiB Raw Blame History