8fe1ef0e27
- 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
140 lines
3.7 KiB
Markdown
140 lines
3.7 KiB
Markdown
# 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](https://nxlearn.net) project.
|
|
|
|
## Install
|
|
|
|
Download the latest release binary for your platform:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
anvil setup
|
|
```
|
|
|
|
This checks for `arduino-cli`, installs the `arduino:avr` core, and verifies
|
|
your system is ready.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```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
|
|
|
|
```bash
|
|
cargo build --release
|
|
```
|
|
|
|
The release binary is at `target/release/anvil` (Linux) or
|
|
`target\release\anvil.exe` (Windows).
|
|
|
|
## License
|
|
|
|
MIT -- see [LICENSE](LICENSE).
|