Merge branch 'feature/overshoot'

CLAUDE.md

@@ -0,0 +1,104 @@
+# 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 |
+| `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.

Gaugecontroller/Gaugecontroller.ino

@@ -1,8 +1,14 @@
 #include <Arduino.h>
 #include <math.h>
+#include <FastLED.h>
 
 static const uint8_t GAUGE_COUNT = 2;
 
+// LED strip — one shared WS2812B strip, segmented per gauge.
+// 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
 #define CMD_PORT Serial
 #define DEBUG_PORT Serial
@@ -14,14 +20,20 @@ struct GaugePins {
   bool dirInverted;
   bool stepActiveHigh;
   bool enableActiveLow;
+  uint8_t ledCount;          // WS2812B LEDs on this gauge's strip segment (0 if none)
 };
 
-GaugePins gaugePins[GAUGE_COUNT] = {
+constexpr GaugePins gaugePins[GAUGE_COUNT] = {
-  // dir, step, en, dirInv, stepHigh, enActiveLow
+  // dir, step, en, dirInv, stepHigh, enActiveLow, leds
-  {50, 51, -1, false, true, true},   // Gauge 0
+  {50, 51, -1, false, true, true, 6},   // Gauge 0
-  {8, 9, -1, true, true, true},   // Gauge 1
+  {8,  9,  -1, true,  true, true, 6},   // Gauge 1
 };
 
+constexpr uint8_t sumLedCounts(uint8_t i = 0) {
+  return i >= GAUGE_COUNT ? 0 : gaugePins[i].ledCount + sumLedCounts(i + 1);
+}
+static const uint8_t TOTAL_LEDS = sumLedCounts();
+
 enum HomingState : uint8_t {
   HS_IDLE,
   HS_START,
@@ -35,12 +47,12 @@ struct Gauge {
   long targetPos = 0;
 
   long minPos = 0;
-  long maxPos = 3610;             // adjust to your usable travel
+  long maxPos = 3780;             // adjust to your usable travel
   long homingBackoffSteps = 3700; // should exceed reverse travel slightly
 
   float velocity = 0.0f;
-  float maxSpeed = 8000.0f;
+  float maxSpeed = 5000.0f;
-  float accel = 9000.0f;
+  float accel = 6000.0f;
   float homingSpeed = 500.0f;
 
   float stepAccumulator = 0.0f;
@@ -61,6 +73,9 @@ struct Gauge {
 Gauge gauges[GAUGE_COUNT];
 String rxLine;
 
+CRGB leds[TOTAL_LEDS];
+uint8_t gaugeLedOffset[GAUGE_COUNT];
+
 void sendReply(const String& s) {
   CMD_PORT.println(s);
 }
@@ -481,6 +496,50 @@ bool parsePing(const String& line) {
   return false;
 }
 
+bool parseLedQuery(const String& line) {
+  if (line == "LED?") {
+    for (uint8_t i = 0; i < GAUGE_COUNT; i++) {
+      for (uint8_t j = 0; j < gaugePins[i].ledCount; j++) {
+        const CRGB& c = leds[gaugeLedOffset[i] + j];
+        CMD_PORT.print("LED ");
+        CMD_PORT.print(i);
+        CMD_PORT.print(' ');
+        CMD_PORT.print(j);
+        CMD_PORT.print(' ');
+        CMD_PORT.print(c.r);
+        CMD_PORT.print(' ');
+        CMD_PORT.print(c.g);
+        CMD_PORT.print(' ');
+        CMD_PORT.println(c.b);
+      }
+    }
+    sendReply("OK");
+    return true;
+  }
+  return false;
+}
+
+bool parseLed(const String& line) {
+  int id, r, g, b;
+  char idxToken[16];
+  if (sscanf(line.c_str(), "LED %d %15s %d %d %d", &id, idxToken, &r, &g, &b) == 5) {
+    if (id < 0 || id >= GAUGE_COUNT) { sendReply("ERR BAD_ID"); return true; }
+    char* dash = strchr(idxToken, '-');
+    int idxFirst = atoi(idxToken);
+    int idxLast  = dash ? atoi(dash + 1) : idxFirst;
+    if (idxFirst < 0 || idxLast >= gaugePins[id].ledCount || idxFirst > idxLast) {
+      sendReply("ERR BAD_IDX"); return true;
+    }
+    CRGB color(constrain(r, 0, 255), constrain(g, 0, 255), constrain(b, 0, 255));
+    for (int i = idxFirst; i <= idxLast; i++)
+      leds[gaugeLedOffset[id] + i] = color;
+    FastLED.show();
+    sendReply("OK");
+    return true;
+  }
+  return false;
+}
+
 void processLine(const String& line) {
   if (parseSet(line)) return;
   if (parseSpeed(line)) return;
@@ -490,6 +549,8 @@ void processLine(const String& line) {
   if (parseHome(line)) return;
   if (parseSweep(line)) return;
   if (parsePosQuery(line)) return;
+  if (parseLedQuery(line)) return;
+  if (parseLed(line)) return;
   if (parsePing(line)) return;
 
   sendReply("ERR BAD_CMD");
@@ -534,6 +595,16 @@ void setup() {
     gauges[i].lastUpdateMicros = micros();
   }
 
+  // Compute per-gauge LED offsets and initialise the strip.
+  uint8_t ledOff = 0;
+  for (uint8_t i = 0; i < GAUGE_COUNT; i++) {
+    gaugeLedOffset[i] = ledOff;
+    ledOff += gaugePins[i].ledCount;
+  }
+  FastLED.addLeds<WS2812B, LED_DATA_PIN, GRB>(leds, TOTAL_LEDS);
+  FastLED.setBrightness(255);
+  FastLED.show();
+
   requestHomeAll();
 
   DEBUG_PORT.println("READY");
@@ -546,4 +617,4 @@ void loop() {
   for (uint8_t i = 0; i < GAUGE_COUNT; i++) {
     updateGauge(i);
   }
-}
+}