arduino_gauge_controller/CLAUDE.md

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:

# 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).

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)
LED?	LED?	Query all LEDs: one LED <id> <idx> <r> <g> <b> line per LED, then OK
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.