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

Main firmware lives in Gaugecontroller/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

# Upload
arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:avr:mega Gaugecontroller

Current default serial setup: CMD_PORT and DEBUG_PORT both point to Serial1 at 38400 baud.

Switching serial ports (debug → production)

Two #defines at the top of Gaugecontroller.ino control where commands and debug output go:

#define CMD_PORT   Serial1  // command channel (host sends SET, HOME, etc.)
#define DEBUG_PORT Serial1  // diagnostic prints (homing, boot messages)

Current default: both point to Serial1, so command and debug traffic share Mega pins TX1=18 / RX1=19 at 38400 baud.

USB-only debug setup: point both defines back at Serial if you want to talk to the sketch over the Arduino USB port instead:

#define CMD_PORT   Serial
#define DEBUG_PORT Serial

At that point the matching begin() call in setup() also needs to use the same baud rate you expect on the host side.

Split command/debug ports: if CMD_PORT and DEBUG_PORT do not point to the same serial port, setup() must initialise both. Right now it only calls:

DEBUG_PORT.begin(38400);

If you split them, add a second CMD_PORT.begin(...) call.

Arduino Mega hardware UARTs for reference:

Port	TX pin	RX pin
Serial1	18	19
Serial2	16	17
Serial3	14	15

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, ledOrder string). 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 (currently 22). Each gauge owns a contiguous segment of the strip; gaugePins[i].ledOrder is a per-LED type string (one char per LED, 'G' = GRB-ordered, 'R' = RGB-ordered) and its length defines the segment length (empty string = no LEDs). TOTAL_LEDS is computed at compile time via constexpr sumLedCounts() — no manual constant to keep in sync. Per-gauge offsets and counts are cached in setup() into gaugeLedOffset[] and gaugeLedCount[]. The strip is initialised as GRB; writes to RGB-ordered LEDs are R/G-swapped via the writeLed/readLed helpers so callers always work in logical RGB. LED commands and effects mark the strip dirty, and FastLED.show() is called once per main-loop iteration if anything changed.

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 the ledOrder string — one char per LED, 'G' for GRB or 'R' for RGB).
3. Tune maxPos and homingBackoffSteps in the corresponding Gauge default or at runtime.
4. TOTAL_LEDS, gaugeLedOffset[], and gaugeLedCount[] update automatically — no manual changes needed.