108 lines
5.6 KiB
Markdown
108 lines
5.6 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Build & Upload
|
||
|
||
This is a single-file Arduino sketch (`Gaugecontroller.ino`). Requires the **FastLED** library (`arduino-cli lib install FastLED`). Use the Arduino IDE or `arduino-cli`:
|
||
|
||
```bash
|
||
# Compile (replace board/port as needed)
|
||
arduino-cli compile --fqbn arduino:avr:mega Gaugecontroller.ino
|
||
|
||
# Upload
|
||
arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:avr:mega Gaugecontroller.ino
|
||
```
|
||
|
||
Serial monitor: 115200 baud (`Serial` is both CMD_PORT and DEBUG_PORT).
|
||
|
||
## Switching serial ports (debug → production)
|
||
|
||
Two `#define`s at the top of `Gaugecontroller.ino` control where commands and debug output go:
|
||
|
||
```cpp
|
||
#define CMD_PORT Serial // command channel (host sends SET, HOME, etc.)
|
||
#define DEBUG_PORT Serial // diagnostic prints (homing, boot messages)
|
||
```
|
||
|
||
**Debug / USB-only (default):** both point to `Serial` (the USB-CDC port). Connect via `minicom` or the Arduino IDE serial monitor at 115200 baud.
|
||
|
||
**Production (hardware UART):** change `CMD_PORT` to a hardware serial port so a host MCU or Raspberry Pi can drive it without occupying the USB port:
|
||
|
||
```cpp
|
||
#define CMD_PORT Serial1 // TX1=pin18, RX1=pin19
|
||
#define DEBUG_PORT Serial // keep USB for monitoring, or silence it (see below)
|
||
```
|
||
|
||
Arduino Mega hardware UARTs:
|
||
|
||
| Port | TX pin | RX pin |
|
||
|---------|--------|--------|
|
||
| Serial1 | 18 | 19 |
|
||
| Serial2 | 16 | 17 |
|
||
| Serial3 | 14 | 15 |
|
||
|
||
`setup()` calls `DEBUG_PORT.begin(115200)` only. If `CMD_PORT` differs from `DEBUG_PORT` you must also begin it — add a second `begin` call in `setup()`:
|
||
|
||
```cpp
|
||
CMD_PORT.begin(115200);
|
||
```
|
||
|
||
**Silencing debug output entirely:** point `DEBUG_PORT` at a null stream, or wrap all `DEBUG_PORT` calls in an `#ifdef DEBUG` guard. The simplest option is to replace the define with a no-op object, but the easiest production approach is just to leave `DEBUG_PORT Serial` and ignore the USB output.
|
||
|
||
## Architecture
|
||
|
||
The sketch controls `GAUGE_COUNT` stepper-motor gauges using a trapezoidal velocity profile and a simple text serial protocol.
|
||
|
||
### Key data structures
|
||
|
||
- `GaugePins` — hardware pin mapping per gauge (dir, step, enable, active-high/low polarity flags, `ledCount`). Declared `constexpr` so `TOTAL_LEDS` can be computed from it at compile time. Configured in the `gaugePins[]` array at the top.
|
||
- `Gauge` — per-gauge runtime state: position, target, velocity, accel, homing state machine, sweep mode.
|
||
|
||
### Motion control (`updateGauge`)
|
||
|
||
Each call to `updateGauge(id)` in `loop()` computes `dt` since last call and updates velocity using a braking-distance check to produce smooth trapezoidal motion. Steps are accumulated as floating-point and emitted via `doStep` when the accumulator crosses ±1.
|
||
|
||
### Homing sequence (`updateHoming`)
|
||
|
||
State machine: `HS_START → HS_BACKING → HS_SETTLE → HS_DONE → HS_IDLE`.
|
||
Backs up `homingBackoffSteps` at `homingSpeed`, waits 100 ms settle, then declares `currentPos = 0`. No physical end-stop is used; homing is purely time/step-count based.
|
||
|
||
### Sweep mode
|
||
|
||
When `sweepEnabled`, `updateSweepTarget` bounces `targetPos` between `minPos` and `maxPos` autonomously.
|
||
|
||
### LED strip
|
||
|
||
One shared WS2812B strip is driven from `LED_DATA_PIN` (default 6). Each gauge owns a contiguous segment of the strip; `gaugePins[i].ledCount` sets the segment length (0 = no LEDs). `TOTAL_LEDS` is computed at compile time via `constexpr sumLedCounts()` — no manual constant to keep in sync. Per-gauge offsets into the flat `leds[]` array are computed once in `setup()` into `gaugeLedOffset[]`. `FastLED.show()` is called immediately after each `LED` command.
|
||
|
||
### Serial command protocol
|
||
|
||
Commands arrive as newline-terminated ASCII lines. Each `parse*` function in `processLine` handles one command family:
|
||
|
||
| Command | Syntax | Effect |
|
||
|---|---|---|
|
||
| `SET` | `SET <id> <pos>` | Move gauge to absolute step position |
|
||
| `SPEED` | `SPEED <id> <steps/s>` | Set max speed |
|
||
| `ACCEL` | `ACCEL <id> <steps/s²>` | Set acceleration |
|
||
| `ENABLE` | `ENABLE <id> <0\|1>` | Enable/disable driver output |
|
||
| `ZERO` | `ZERO <id>` | Mark current position as home without moving |
|
||
| `HOME` | `HOME <id>` / `HOMEALL` | Run homing sequence |
|
||
| `SWEEP` | `SWEEP <id> <accel> <speed>` | Start sweep (0/0 stops) |
|
||
| `POS?` | `POS?` | Query all gauges: `POS <id> <cur> <tgt> <homed> <homingState> <sweep>` |
|
||
| `LED` | `LED <id> <idx> <r> <g> <b>` | Set one LED (0-based index within gauge segment) to RGB colour (0–255 each); `<idx>` may be a range `N-M` to set LEDs N through M in one command; also stops any active effect on those LEDs |
|
||
| `LED?` | `LED?` | Query all LEDs: one `LED <id> <idx> <r> <g> <b>` line per LED, then `OK` |
|
||
| `BLINK` | `BLINK <id> <idx> <on_ms> <off_ms> <r> <g> <b>` | Blink LED(s) at given colour; `<idx>` may be a range `N-M`; `on_ms`/`off_ms` both 0 stops blinking. 4-arg form (no colour) uses current LED colour |
|
||
| `BREATHE` | `BREATHE <id> <idx> <period_ms> <r> <g> <b>` | Smooth triangle-wave fade between black and the given colour; `<idx>` may be a range `N-M` |
|
||
| `DFLASH` | `DFLASH <id> <idx> <r> <g> <b>` | Two quick flashes (100 ms on/off each) followed by a 700 ms pause, then repeats; `<idx>` may be a range `N-M` |
|
||
| `PING` | `PING` | Responds `PONG` |
|
||
|
||
All commands reply `OK` or `ERR BAD_ID` / `ERR BAD_CMD` etc.
|
||
|
||
### Adding gauges
|
||
|
||
1. Increment `GAUGE_COUNT`.
|
||
2. Add a `constexpr GaugePins` entry to `gaugePins[]` (including `ledCount`).
|
||
3. Tune `maxPos` and `homingBackoffSteps` in the corresponding `Gauge` default or at runtime.
|
||
4. `TOTAL_LEDS` and `gaugeLedOffset[]` update automatically — no manual changes needed.
|