Code commented, Serial speed moved into constant

CLAUDE.md

@@ -4,37 +4,47 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## 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`:
+Main firmware lives in `Gaugecontroller/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
+arduino-cli compile --fqbn arduino:avr:mega Gaugecontroller
 
 # Upload
-arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:avr:mega Gaugecontroller.ino
+arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:avr:mega Gaugecontroller
 ```
 
-Serial monitor: 115200 baud (`Serial` is both CMD_PORT and DEBUG_PORT).
+Current default serial setup: `CMD_PORT` and `DEBUG_PORT` both point to `Serial1` at 38400 baud.
 
 ## 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 CMD_PORT   Serial1  // command channel (host sends SET, HOME, etc.)
-#define DEBUG_PORT Serial   // diagnostic prints (homing, boot messages)
+#define DEBUG_PORT Serial1  // 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.
+**Current default:** both point to `Serial1`, so command and debug traffic share Mega pins TX1=18 / RX1=19 at 38400 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:
+**USB-only debug setup:** point both defines back at `Serial` if you want to talk to the sketch over the Arduino USB port instead:
 
 ```cpp
-#define CMD_PORT   Serial1  // TX1=pin18, RX1=pin19
+#define CMD_PORT   Serial
-#define DEBUG_PORT Serial   // keep USB for monitoring, or silence it (see below)
+#define DEBUG_PORT Serial
 ```
 
-Arduino Mega hardware UARTs:
+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:
+
+```cpp
+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 |
 |---------|--------|--------|
@@ -42,14 +52,6 @@ Arduino Mega hardware UARTs:
 | 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.
@@ -74,7 +76,7 @@ When `sweepEnabled`, `updateSweepTarget` bounces `targetPos` between `minPos` an
 
 ### 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.
+One shared WS2812B strip is driven from `LED_DATA_PIN` (currently 22). 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[]`. LED commands and effects mark the strip dirty, and `FastLED.show()` is called once per main-loop iteration if anything changed.
 
 ### Serial command protocol
 

Gaugecontroller/Gaugecontroller.ino

@@ -2,31 +2,31 @@
 #include <math.h>
 #include <FastLED.h>
 
-static const uint8_t GAUGE_COUNT = 2;
+static const uint8_t GAUGE_COUNT = 3;
 
-// LED strip — one shared WS2812B strip, segmented per gauge.
+// One shared WS2812B strip, split into per-gauge segments.
-// Set LED_DATA_PIN to the digital pin driving the strip data line.
-// TOTAL_LEDS is computed automatically from gaugePins[].ledCount.
 static const uint8_t LED_DATA_PIN = 22;
 
-// For now: commands come over USB serial
+// For now, command and debug traffic share the same serial port.
 #define CMD_PORT Serial1
 #define DEBUG_PORT Serial1
+static const unsigned long SERIAL_BAUD = 38400;
 
 struct GaugePins {
   uint8_t dirPin;
   uint8_t stepPin;
-  int8_t enablePin;          // -1 if unused
+  int8_t enablePin;          // -1 means there is no enable pin
   bool dirInverted;
   bool stepActiveHigh;
   bool enableActiveLow;
-  uint8_t ledCount;          // WS2812B LEDs on this gauge's strip segment (0 if none)
+  uint8_t ledCount;          // LEDs assigned to this gauge
 };
 
 constexpr GaugePins gaugePins[GAUGE_COUNT] = {
   // dir, step, en, dirInv, stepHigh, enActiveLow, leds
   {50, 51, -1, false, true, true, 7},   // Gauge 0
   {8,  9,  -1, true,  true, true, 7},   // Gauge 1
+  {52, 53, -1, false, true, true, 7},   // Gauge 2
 };
 
 constexpr uint8_t sumLedCounts(uint8_t i = 0) {
@@ -47,8 +47,8 @@ struct Gauge {
   long targetPos = 0;
 
   long minPos = 0;
-  long maxPos = 3780;             // adjust to your usable travel
+  long maxPos = 3780;
-  long homingBackoffSteps = 3800; // should exceed reverse travel slightly
+  long homingBackoffSteps = 3800; // Deliberately a touch past full reverse travel.
 
   float velocity = 0.0f;
   float maxSpeed = 5000.0f;
@@ -77,14 +77,11 @@ struct BlinkState {
   LedFx         fx          = FX_BLINK;
   CRGB          onColor;
   unsigned long lastMs      = 0;
-  // FX_BLINK
   uint16_t      onMs        = 500;
   uint16_t      offMs       = 500;
   bool          currentlyOn = false;
-  // FX_BREATHE: smooth triangle-wave fade
   uint16_t      periodMs    = 2000;
   uint16_t      cyclePos    = 0;
-  // FX_DFLASH: two quick flashes then pause
   uint8_t       dphase      = 0;
 };
 
@@ -96,14 +93,65 @@ uint8_t gaugeLedOffset[GAUGE_COUNT];
 BlinkState blinkState[TOTAL_LEDS];
 bool ledsDirty = false;
 
+// Sends one-line command replies back over the control port.
+//
+// Serial protocol summary.
+//
+// Host -> controller commands (newline-terminated ASCII):
+//   SET <id> <pos>
+//   SPEED <id> <steps_per_s>
+//   ACCEL <id> <steps_per_s2>
+//   ENABLE <id> <0|1>
+//   ZERO <id>
+//   HOME <id>
+//   HOMEALL
+//   SWEEP <id> <accel> <speed>
+//   POS?
+//   LED?
+//   LED <id> <idx|a-b> <r> <g> <b>
+//   BLINK <id> <idx|a-b> <on_ms> <off_ms> [<r> <g> <b>]
+//   BREATHE <id> <idx|a-b> <period_ms> <r> <g> <b>
+//   DFLASH <id> <idx|a-b> <r> <g> <b>
+//   PING
+//
+// Controller -> host replies / events:
+//   READY
+//     Sent once from setup() after boot completes.
+//   OK
+//     Sent after a valid mutating command, and after POS?/LED? once all data lines
+//     for that query have been emitted.
+//   PONG
+//     Sent in response to PING.
+//   ERR BAD_CMD
+//     Sent when a complete line matches no parser.
+//   ERR TOO_LONG
+//     Sent when an input line exceeds the receive buffer limit.
+//   ERR BAD_ID
+//     Sent by commands that take a gauge id when the id is outside 0..GAUGE_COUNT-1.
+//   ERR BAD_SPEED
+//     Sent by SPEED when the requested speed is <= 0.
+//   ERR BAD_ACCEL
+//     Sent by ACCEL when the requested acceleration is <= 0.
+//   ERR BAD_IDX
+//     Sent by LED/BLINK/BREATHE/DFLASH when an LED index or range is invalid.
+//   ERR BAD_TIME
+//     Sent by BLINK/BREATHE when the timing parameter is invalid.
+//   POS <id> <currentPos> <targetPos> <homed> <homingState> <sweepEnabled>
+//     Emitted once per gauge before the trailing OK reply to POS?.
+//   LED <id> <idx> <r> <g> <b>
+//     Emitted once per configured LED before the trailing OK reply to LED?.
+//   HOMED <id>
+//     Debug event printed on DEBUG_PORT when a homing sequence settles successfully.
 void sendReply(const String& s) {
   CMD_PORT.println(s);
 }
 
+// Tiny float absolute-value helper to avoid dragging more machinery into the sketch.
 float absf(float x) {
   return (x < 0.0f) ? -x : x;
 }
 
+// Updates the cached enable state and toggles the hardware pin if one exists.
 void setEnable(uint8_t id, bool en) {
   if (id >= GAUGE_COUNT) return;
   gauges[id].enabled = en;
@@ -115,11 +163,13 @@ void setEnable(uint8_t id, bool en) {
   digitalWrite(pin, level ? HIGH : LOW);
 }
 
+// Applies the logical direction after accounting for per-gauge inversion.
 void setDir(uint8_t id, bool forward) {
   bool level = gaugePins[id].dirInverted ? !forward : forward;
   digitalWrite(gaugePins[id].dirPin, level ? HIGH : LOW);
 }
 
+// Emits one step pulse with the polarity expected by the driver.
 void pulseStep(uint8_t id) {
   bool active = gaugePins[id].stepActiveHigh;
   digitalWrite(gaugePins[id].stepPin, active ? HIGH : LOW);
@@ -127,6 +177,7 @@ void pulseStep(uint8_t id) {
   digitalWrite(gaugePins[id].stepPin, active ? LOW : HIGH);
 }
 
+// Moves the motor by one step if the requested direction is still within allowed travel.
 void doStep(uint8_t id, int dir, bool allowPastMin = false) {
   Gauge& g = gauges[id];
   if (!g.enabled) return;
@@ -144,6 +195,7 @@ void doStep(uint8_t id, int dir, bool allowPastMin = false) {
   }
 }
 
+// Arms the homing state machine for one gauge and clears any in-flight motion.
 void requestHome(uint8_t id) {
   if (id >= GAUGE_COUNT) return;
   Gauge& g = gauges[id];
@@ -154,12 +206,14 @@ void requestHome(uint8_t id) {
   g.sweepEnabled = false;
 }
 
+// Starts the same homing sequence on every configured gauge.
 void requestHomeAll() {
   for (uint8_t i = 0; i < GAUGE_COUNT; i++) {
     requestHome(i);
   }
 }
 
+// Advances the simple homing state machine until the gauge is parked at logical zero.
 void updateHoming(uint8_t id) {
   Gauge& g = gauges[id];
   unsigned long nowUs = micros();
@@ -170,6 +224,7 @@ void updateHoming(uint8_t id) {
       return;
 
     case HS_START:
+      // No endstop here; homing just walks back far enough to hit the hard stop.
       g.velocity = 0.0f;
       g.stepAccumulator = 0.0f;
       g.homingStepsRemaining = g.homingBackoffSteps;
@@ -213,6 +268,7 @@ void updateHoming(uint8_t id) {
   }
 }
 
+// Flips the sweep destination when the gauge has settled at either end of travel.
 void updateSweepTarget(uint8_t id) {
   Gauge& g = gauges[id];
   if (!g.sweepEnabled || !g.homed || g.homingState != HS_IDLE) return;
@@ -232,6 +288,7 @@ void updateSweepTarget(uint8_t id) {
   }
 }
 
+// Runs one gauge worth of motion control, including homing and optional sweeping.
 void updateGauge(uint8_t id) {
   Gauge& g = gauges[id];
 
@@ -266,6 +323,7 @@ void updateGauge(uint8_t id) {
   }
 
   float dir = (error > 0) ? 1.0f : (error < 0 ? -1.0f : 0.0f);
+  // Basic trapezoidal profile: brake if the remaining travel is shorter than the stop distance.
   float brakingDistance = (g.velocity * g.velocity) / (2.0f * g.accel + 0.0001f);
 
   if ((float)labs(error) <= brakingDistance) {
@@ -286,6 +344,7 @@ void updateGauge(uint8_t id) {
     g.velocity = dir * 5.0f;
   }
 
+  // Integrate fractional steps until there is enough to emit a real pulse.
   g.stepAccumulator += g.velocity * dt;
 
   while (g.stepAccumulator >= 1.0f) {
@@ -327,6 +386,8 @@ void updateGauge(uint8_t id) {
   }
 }
 
+// Parses `SET <id> <pos>` and updates the target position.
+// Replies: `OK`, `ERR BAD_ID`.
 bool parseSet(const String& line) {
   int id;
   long pos;
@@ -346,6 +407,8 @@ bool parseSet(const String& line) {
   return false;
 }
 
+// Parses `SPEED <id> <speed>` and updates the max step rate.
+// Replies: `OK`, `ERR BAD_ID`, `ERR BAD_SPEED`.
 bool parseSpeed(const String& line) {
   int firstSpace = line.indexOf(' ');
   int secondSpace = line.indexOf(' ', firstSpace + 1);
@@ -369,6 +432,8 @@ bool parseSpeed(const String& line) {
   return true;
 }
 
+// Parses `ACCEL <id> <accel>` and updates the acceleration limit.
+// Replies: `OK`, `ERR BAD_ID`, `ERR BAD_ACCEL`.
 bool parseAccel(const String& line) {
   int firstSpace = line.indexOf(' ');
   int secondSpace = line.indexOf(' ', firstSpace + 1);
@@ -392,6 +457,8 @@ bool parseAccel(const String& line) {
   return true;
 }
 
+// Parses `ENABLE <id> <0|1>` and toggles the selected driver.
+// Replies: `OK`, `ERR BAD_ID`.
 bool parseEnable(const String& line) {
   int id, en;
   if (sscanf(line.c_str(), "ENABLE %d %d", &id, &en) == 2) {
@@ -407,6 +474,8 @@ bool parseEnable(const String& line) {
   return false;
 }
 
+// Parses `ZERO <id>` and declares the current position to be home.
+// Replies: `OK`, `ERR BAD_ID`.
 bool parseZero(const String& line) {
   int id;
   if (sscanf(line.c_str(), "ZERO %d", &id) == 1) {
@@ -428,6 +497,8 @@ bool parseZero(const String& line) {
   return false;
 }
 
+// Parses `HOME <id>` or `HOMEALL` and kicks off the homing sequence.
+// Replies: `OK`, `ERR BAD_ID`. Successful completion later emits debug line `HOMED <id>`.
 bool parseHome(const String& line) {
   int id;
   if (sscanf(line.c_str(), "HOME %d", &id) == 1) {
@@ -450,6 +521,8 @@ bool parseHome(const String& line) {
   return false;
 }
 
+// Parses `SWEEP <id> <accel> <speed>` and enables or disables end-to-end motion.
+// Replies: `OK`, `ERR BAD_ID`.
 bool parseSweep(const String& line) {
   int firstSpace = line.indexOf(' ');
   int secondSpace = line.indexOf(' ', firstSpace + 1);
@@ -486,6 +559,9 @@ bool parseSweep(const String& line) {
   return true;
 }
 
+// Answers `POS?` with current motion state for every gauge.
+// Emits one `POS <id> <cur> <tgt> <homed> <homingState> <sweep>` line per gauge,
+// then replies `OK`.
 bool parsePosQuery(const String& line) {
   if (line == "POS?") {
     for (uint8_t i = 0; i < GAUGE_COUNT; i++) {
@@ -508,6 +584,8 @@ bool parsePosQuery(const String& line) {
   return false;
 }
 
+// Answers the mandatory life question: are you there?
+// Reply: `PONG`.
 bool parsePing(const String& line) {
   if (line == "PING") {
     sendReply("PONG");
@@ -516,6 +594,8 @@ bool parsePing(const String& line) {
   return false;
 }
 
+// Answers `LED?` with the current RGB values for every configured LED.
+// Emits one `LED <id> <idx> <r> <g> <b>` line per configured LED, then replies `OK`.
 bool parseLedQuery(const String& line) {
   if (line == "LED?") {
     for (uint8_t i = 0; i < GAUGE_COUNT; i++) {
@@ -539,6 +619,8 @@ bool parseLedQuery(const String& line) {
   return false;
 }
 
+// Parses `LED <id> <idx|a-b> <r> <g> <b>` and writes static colours.
+// Replies: `OK`, `ERR BAD_ID`, `ERR BAD_IDX`.
 bool parseLed(const String& line) {
   int id, r, g, b;
   char idxToken[16];
@@ -562,12 +644,12 @@ bool parseLed(const String& line) {
   return false;
 }
 
+// Parses `BLINK ...` and assigns a simple on/off effect to one LED or a range.
+// Replies: `OK`, `ERR BAD_ID`, `ERR BAD_IDX`, `ERR BAD_TIME`.
 bool parseBlink(const String& line) {
   int id, onMs, offMs, r, g, b;
   char idxToken[16];
-  // Accept both forms:
+  // Optional RGB values let BLINK either reuse or replace the current colour.
-  //   BLINK <id> <idx> <on_ms> <off_ms>           — use current LED colour
-  //   BLINK <id> <idx> <on_ms> <off_ms> <r> <g> <b> — set colour in same command
   int count = sscanf(line.c_str(), "BLINK %d %15s %d %d %d %d %d",
                      &id, idxToken, &onMs, &offMs, &r, &g, &b);
   if (count != 4 && count != 7) return false;
@@ -590,7 +672,7 @@ bool parseBlink(const String& line) {
 
   CRGB color = (count == 7)
     ? CRGB(constrain(r, 0, 255), constrain(g, 0, 255), constrain(b, 0, 255))
-    : CRGB(0, 0, 0);  // placeholder; overwritten per-LED below when count==4
+    : CRGB(0, 0, 0);  // Placeholder; replaced with the live LED colour below.
 
   unsigned long nowMs = millis();
   for (int i = idxFirst; i <= idxLast; i++) {
@@ -610,6 +692,8 @@ bool parseBlink(const String& line) {
   return true;
 }
 
+// Parses `BREATHE ...` and assigns a triangle-wave fade effect.
+// Replies: `OK`, `ERR BAD_ID`, `ERR BAD_IDX`, `ERR BAD_TIME`.
 bool parseBreathe(const String& line) {
   int id, periodMs, r, g, b;
   char idxToken[16];
@@ -641,6 +725,8 @@ bool parseBreathe(const String& line) {
   return true;
 }
 
+// Parses `DFLASH ...` and assigns the double-flash pattern.
+// Replies: `OK`, `ERR BAD_ID`, `ERR BAD_IDX`.
 bool parseDflash(const String& line) {
   int id, r, g, b;
   char idxToken[16];
@@ -670,6 +756,7 @@ bool parseDflash(const String& line) {
   return true;
 }
 
+// Advances all active LED effects and marks the strip dirty when something changed.
 void updateBlink() {
   unsigned long nowMs = millis();
   bool changed = false;
@@ -697,6 +784,7 @@ void updateBlink() {
           uint32_t newPos = (uint32_t)bs.cyclePos + dt;
           bs.cyclePos = (uint16_t)(newPos % bs.periodMs);
           bs.lastMs = nowMs;
+          // Cheap triangle wave. It does the job and nobody has complained yet.
           uint16_t half = bs.periodMs >> 1;
           uint8_t bri = (bs.cyclePos < half)
               ? (uint8_t)((uint32_t)bs.cyclePos * 255 / half)
@@ -707,7 +795,7 @@ void updateBlink() {
           break;
         }
         case FX_DFLASH: {
-          static const uint16_t dur[4] = {100, 100, 100, 700};
+          static const uint16_t dur[4] = {100, 100, 100, 700}; // on, off, on, longer off
           if ((nowMs - bs.lastMs) >= dur[bs.dphase]) {
             bs.lastMs = nowMs;
             bs.dphase = (bs.dphase + 1) & 3;
@@ -723,6 +811,8 @@ void updateBlink() {
   if (changed) ledsDirty = true;
 }
 
+// Runs the command parsers in order until one claims the line.
+// Reply: `ERR BAD_CMD` when no parser accepts the line.
 void processLine(const String& line) {
   if (parseSet(line)) return;
   if (parseSpeed(line)) return;
@@ -742,6 +832,8 @@ void processLine(const String& line) {
   sendReply("ERR BAD_CMD");
 }
 
+// Reads newline-delimited commands from serial and hands complete lines to the parser.
+// Reply: `ERR TOO_LONG` when the buffered line exceeds the receive limit before newline.
 void readCommands() {
   while (CMD_PORT.available()) {
     char c = (char)CMD_PORT.read();
@@ -762,8 +854,10 @@ void readCommands() {
   }
 }
 
+// Initialises pins, LED bookkeeping and the initial homing cycle.
+// Reply/event: emits `READY` on CMD_PORT once boot is complete.
 void setup() {
-  DEBUG_PORT.begin(38400);
+  DEBUG_PORT.begin(SERIAL_BAUD);
   DEBUG_PORT.println("Gauge controller booting");
 
   for (uint8_t i = 0; i < GAUGE_COUNT; i++) {
@@ -781,7 +875,7 @@ void setup() {
     gauges[i].lastUpdateMicros = micros();
   }
 
-  // Compute per-gauge LED offsets and initialise the strip.
+  // Flatten the per-gauge LED counts into offsets on the shared strip.
   uint8_t ledOff = 0;
   for (uint8_t i = 0; i < GAUGE_COUNT; i++) {
     gaugeLedOffset[i] = ledOff;
@@ -794,19 +888,23 @@ void setup() {
   requestHomeAll();
 
   DEBUG_PORT.println("READY");
+  // Boot-complete handshake for the command channel.
   sendReply("READY");
 }
 
+// Main service loop: ingest commands, advance effects, move gauges, flush LEDs.
 void loop() {
   readCommands();
   updateBlink();
 
+  for (uint8_t i = 0; i < GAUGE_COUNT; i++) {
+    updateGauge(i);
+  }
+  
   if (ledsDirty) {
     FastLED.show();
     ledsDirty = false;
   }
 
-  for (uint8_t i = 0; i < GAUGE_COUNT; i++) {
+
-    updateGauge(i);
-  }
 }