475 lines
14 KiB
Markdown
475 lines
14 KiB
Markdown
# Gaugecontroller v2.0 Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** Centralise all gauge configuration in `gauge_config.h` and make the three inconsistently-written parsers use `sscanf` like the rest.
|
||
|
||
**Architecture:** A new header file holds one `constexpr GaugeConfig` table — pin assignments and motion defaults merged — and derives `GAUGE_COUNT` from its length. The sketch includes this header, removes the old `GaugePins` struct and all hardcoded defaults, and initialises `Gauge` runtime state from the table in `setup()`. Three parse functions are then rewritten from manual string splitting to `sscanf`.
|
||
|
||
**Tech Stack:** Arduino (AVR/Mega), `arduino-cli`, C++11 `constexpr`.
|
||
|
||
> **Note on testing:** This is a bare-metal Arduino sketch with no unit-test framework. Each task's verification step is a clean compile with `arduino-cli`. Functional testing requires the physical hardware; the plan notes what to check over serial when hardware is available.
|
||
|
||
---
|
||
|
||
## File Map
|
||
|
||
| File | Action | Responsibility |
|
||
|---|---|---|
|
||
| `Gaugecontroller/gauge_config.h` | **Create** | All pin assignments and motion defaults; `GAUGE_COUNT` |
|
||
| `Gaugecontroller/Gaugecontroller.ino` | **Modify** | Remove `GaugePins`, add include, strip `Gauge` defaults, update all references, rewrite 3 parsers |
|
||
|
||
---
|
||
|
||
## Task 1: Create `gauge_config.h`
|
||
|
||
**Files:**
|
||
- Create: `Gaugecontroller/gauge_config.h`
|
||
|
||
- [ ] **Step 1: Create the file**
|
||
|
||
Create `Gaugecontroller/gauge_config.h` with the following content:
|
||
|
||
```cpp
|
||
#pragma once
|
||
#include <stdint.h>
|
||
|
||
struct GaugeConfig {
|
||
// Hardware
|
||
uint8_t dirPin;
|
||
uint8_t stepPin;
|
||
int8_t enablePin; // -1 = no enable pin
|
||
bool dirInverted;
|
||
bool stepActiveHigh;
|
||
bool enableActiveLow;
|
||
|
||
// Motion defaults (integers; cast to float in setup())
|
||
long minPos;
|
||
long maxPos;
|
||
long homingBackoffSteps;
|
||
int maxSpeed; // steps/s
|
||
int accel; // steps/s²
|
||
int homingSpeed; // steps/s
|
||
};
|
||
|
||
constexpr GaugeConfig gaugeConfigs[] = {
|
||
// dir step en dirInv stepHi enLow min max backoff speed accel homeSpd
|
||
{ 48, 49, -1, false, true, true, 0, 3780, 3800, 4000, 6000, 500 },
|
||
{ 8, 9, -1, true, true, true, 0, 3780, 3800, 4000, 6000, 500 },
|
||
{ 52, 53, -1, false, true, true, 0, 3780, 3800, 4000, 6000, 500 },
|
||
{ 50, 51, -1, false, true, true, 0, 3780, 3800, 4000, 6000, 500 },
|
||
};
|
||
|
||
static const uint8_t GAUGE_COUNT =
|
||
sizeof(gaugeConfigs) / sizeof(gaugeConfigs[0]);
|
||
```
|
||
|
||
To add a fifth gauge later: append one row to `gaugeConfigs[]`. Nothing else changes.
|
||
|
||
---
|
||
|
||
## Task 2: Wire `gauge_config.h` into `Gaugecontroller.ino`
|
||
|
||
**Files:**
|
||
- Modify: `Gaugecontroller/Gaugecontroller.ino`
|
||
|
||
This task makes six targeted edits in order. Each edit is shown as old → new. Do them top-to-bottom so line numbers don't shift unexpectedly.
|
||
|
||
- [ ] **Step 1: Add the include**
|
||
|
||
After the existing three `#include` lines at the top, add:
|
||
|
||
```cpp
|
||
#include "gauge_config.h"
|
||
```
|
||
|
||
The top of the file should now read:
|
||
|
||
```cpp
|
||
#include <Arduino.h>
|
||
#include <avr/interrupt.h>
|
||
#include <math.h>
|
||
#include "gauge_config.h"
|
||
```
|
||
|
||
- [ ] **Step 2: Remove `GAUGE_COUNT` and `GaugePins`**
|
||
|
||
Delete these two blocks entirely (they are now in `gauge_config.h`):
|
||
|
||
```cpp
|
||
static const uint8_t GAUGE_COUNT = 4;
|
||
```
|
||
|
||
```cpp
|
||
struct GaugePins {
|
||
uint8_t dirPin;
|
||
uint8_t stepPin;
|
||
int8_t enablePin; // -1 means there is no enable pin
|
||
bool dirInverted;
|
||
bool stepActiveHigh;
|
||
bool enableActiveLow;
|
||
};
|
||
|
||
constexpr GaugePins gaugePins[GAUGE_COUNT] = {
|
||
// dir, step, en, dirInv, stepHigh, enActiveLow
|
||
{48, 49, -1, false, true, true}, // Gauge 0
|
||
{8, 9, -1, true, true, true}, // Gauge 1
|
||
{52, 53, -1, false, true, true}, // Gauge 2
|
||
{50, 51, -1, false, true, true}, // Gauge 3
|
||
};
|
||
```
|
||
|
||
- [ ] **Step 3: Strip hardcoded defaults from `struct Gauge`**
|
||
|
||
In the `Gauge` struct definition, remove the numeric defaults from the six motion fields. Change:
|
||
|
||
```cpp
|
||
long minPos = 0;
|
||
long maxPos = 3780;
|
||
long homingBackoffSteps = 3800; // Deliberately a touch past full reverse travel.
|
||
|
||
float velocity = 0.0f;
|
||
float maxSpeed = 4000.0f;
|
||
float accel = 6000.0f;
|
||
float homingSpeed = 500.0f;
|
||
```
|
||
|
||
To:
|
||
|
||
```cpp
|
||
long minPos = 0;
|
||
long maxPos = 0;
|
||
long homingBackoffSteps = 0;
|
||
|
||
float velocity = 0.0f;
|
||
float maxSpeed = 0.0f;
|
||
float accel = 0.0f;
|
||
float homingSpeed = 0.0f;
|
||
```
|
||
|
||
These will be populated from `gaugeConfigs[i]` in `setup()` (Step 5).
|
||
|
||
- [ ] **Step 4: Update `gaugePins` → `gaugeConfigs` references outside `setup()`**
|
||
|
||
Three functions reference `gaugePins`. Update each one:
|
||
|
||
**`writeDirectionPin` (~line 106):**
|
||
```cpp
|
||
// Before
|
||
bool level = gaugePins[id].dirInverted ? !forward : forward;
|
||
|
||
// After
|
||
bool level = gaugeConfigs[id].dirInverted ? !forward : forward;
|
||
```
|
||
|
||
**`writeStepPin` (~line 111):**
|
||
```cpp
|
||
// Before
|
||
bool level = gaugePins[id].stepActiveHigh ? active : !active;
|
||
|
||
// After
|
||
bool level = gaugeConfigs[id].stepActiveHigh ? active : !active;
|
||
```
|
||
|
||
**`configureStepperHardware` (~line 152):**
|
||
```cpp
|
||
// Before
|
||
stepperHardware[id].stepPort = portOutputRegister(digitalPinToPort(gaugePins[id].stepPin));
|
||
stepperHardware[id].stepMask = digitalPinToBitMask(gaugePins[id].stepPin);
|
||
stepperHardware[id].dirPort = portOutputRegister(digitalPinToPort(gaugePins[id].dirPin));
|
||
stepperHardware[id].dirMask = digitalPinToBitMask(gaugePins[id].dirPin);
|
||
|
||
// After
|
||
stepperHardware[id].stepPort = portOutputRegister(digitalPinToPort(gaugeConfigs[id].stepPin));
|
||
stepperHardware[id].stepMask = digitalPinToBitMask(gaugeConfigs[id].stepPin);
|
||
stepperHardware[id].dirPort = portOutputRegister(digitalPinToPort(gaugeConfigs[id].dirPin));
|
||
stepperHardware[id].dirMask = digitalPinToBitMask(gaugeConfigs[id].dirPin);
|
||
```
|
||
|
||
**`setEnable` (~line 291):**
|
||
```cpp
|
||
// Before
|
||
int8_t pin = gaugePins[id].enablePin;
|
||
if (pin < 0) return;
|
||
bool level = gaugePins[id].enableActiveLow ? !en : en;
|
||
|
||
// After
|
||
int8_t pin = gaugeConfigs[id].enablePin;
|
||
if (pin < 0) return;
|
||
bool level = gaugeConfigs[id].enableActiveLow ? !en : en;
|
||
```
|
||
|
||
- [ ] **Step 5: Update `setup()` — pin references and add motion default init**
|
||
|
||
In `setup()`, the `for` loop currently reads:
|
||
|
||
```cpp
|
||
for (uint8_t i = 0; i < GAUGE_COUNT; i++) {
|
||
pinMode(gaugePins[i].dirPin, OUTPUT);
|
||
pinMode(gaugePins[i].stepPin, OUTPUT);
|
||
configureStepperHardware(i);
|
||
|
||
digitalWrite(gaugePins[i].dirPin, LOW);
|
||
digitalWrite(gaugePins[i].stepPin, gaugePins[i].stepActiveHigh ? LOW : HIGH);
|
||
|
||
if (gaugePins[i].enablePin >= 0) {
|
||
pinMode(gaugePins[i].enablePin, OUTPUT);
|
||
setEnable(i, true);
|
||
}
|
||
|
||
gauges[i].lastUpdateMicros = micros();
|
||
}
|
||
```
|
||
|
||
Replace it with:
|
||
|
||
```cpp
|
||
for (uint8_t i = 0; i < GAUGE_COUNT; i++) {
|
||
pinMode(gaugeConfigs[i].dirPin, OUTPUT);
|
||
pinMode(gaugeConfigs[i].stepPin, OUTPUT);
|
||
configureStepperHardware(i);
|
||
|
||
digitalWrite(gaugeConfigs[i].dirPin, LOW);
|
||
digitalWrite(gaugeConfigs[i].stepPin, gaugeConfigs[i].stepActiveHigh ? LOW : HIGH);
|
||
|
||
if (gaugeConfigs[i].enablePin >= 0) {
|
||
pinMode(gaugeConfigs[i].enablePin, OUTPUT);
|
||
setEnable(i, true);
|
||
}
|
||
|
||
gauges[i].minPos = gaugeConfigs[i].minPos;
|
||
gauges[i].maxPos = gaugeConfigs[i].maxPos;
|
||
gauges[i].homingBackoffSteps = gaugeConfigs[i].homingBackoffSteps;
|
||
gauges[i].maxSpeed = (float)gaugeConfigs[i].maxSpeed;
|
||
gauges[i].accel = (float)gaugeConfigs[i].accel;
|
||
gauges[i].homingSpeed = (float)gaugeConfigs[i].homingSpeed;
|
||
|
||
gauges[i].lastUpdateMicros = micros();
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 6: Compile and verify clean**
|
||
|
||
```bash
|
||
arduino-cli compile --fqbn arduino:avr:mega Gaugecontroller
|
||
```
|
||
|
||
Expected: zero errors, zero warnings about `gaugePins` or `GAUGE_COUNT`. If the compiler reports "use of undeclared identifier 'gaugePins'", grep for any remaining reference:
|
||
|
||
```bash
|
||
grep -n "gaugePins" Gaugecontroller/Gaugecontroller.ino
|
||
```
|
||
|
||
Should return nothing.
|
||
|
||
- [ ] **Step 7: Commit**
|
||
|
||
```bash
|
||
git add Gaugecontroller/gauge_config.h Gaugecontroller/Gaugecontroller.ino
|
||
git commit -m "refactor: centralise gauge config in gauge_config.h"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 3: Rewrite `parseSpeed`, `parseAccel`, `parseSweep` to use `sscanf`
|
||
|
||
**Files:**
|
||
- Modify: `Gaugecontroller/Gaugecontroller.ino`
|
||
|
||
- [ ] **Step 1: Replace `parseSpeed`**
|
||
|
||
Find and replace the entire `parseSpeed` function:
|
||
|
||
```cpp
|
||
// Before (~15 lines)
|
||
bool parseSpeed(const String& line) {
|
||
int firstSpace = line.indexOf(' ');
|
||
int secondSpace = line.indexOf(' ', firstSpace + 1);
|
||
if (firstSpace < 0 || secondSpace < 0) return false;
|
||
if (line.substring(0, firstSpace) != "SPEED") return false;
|
||
|
||
int id = line.substring(firstSpace + 1, secondSpace).toInt();
|
||
float speed = line.substring(secondSpace + 1).toFloat();
|
||
|
||
if (id < 0 || id >= GAUGE_COUNT) {
|
||
sendReply("ERR BAD_ID");
|
||
return true;
|
||
}
|
||
if (speed <= 0.0f) {
|
||
sendReply("ERR BAD_SPEED");
|
||
return true;
|
||
}
|
||
|
||
gauges[id].maxSpeed = speed;
|
||
sendReply("OK");
|
||
return true;
|
||
}
|
||
```
|
||
|
||
```cpp
|
||
// After
|
||
bool parseSpeed(const String& line) {
|
||
int id; float speed;
|
||
if (sscanf(line.c_str(), "SPEED %d %f", &id, &speed) == 2) {
|
||
if (id < 0 || id >= GAUGE_COUNT) { sendReply("ERR BAD_ID"); return true; }
|
||
if (speed <= 0.0f) { sendReply("ERR BAD_SPEED"); return true; }
|
||
gauges[id].maxSpeed = speed;
|
||
sendReply("OK");
|
||
return true;
|
||
}
|
||
return false;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Replace `parseAccel`**
|
||
|
||
```cpp
|
||
// Before (~15 lines)
|
||
bool parseAccel(const String& line) {
|
||
int firstSpace = line.indexOf(' ');
|
||
int secondSpace = line.indexOf(' ', firstSpace + 1);
|
||
if (firstSpace < 0 || secondSpace < 0) return false;
|
||
if (line.substring(0, firstSpace) != "ACCEL") return false;
|
||
|
||
int id = line.substring(firstSpace + 1, secondSpace).toInt();
|
||
float accel = line.substring(secondSpace + 1).toFloat();
|
||
|
||
if (id < 0 || id >= GAUGE_COUNT) {
|
||
sendReply("ERR BAD_ID");
|
||
return true;
|
||
}
|
||
if (accel <= 0.0f) {
|
||
sendReply("ERR BAD_ACCEL");
|
||
return true;
|
||
}
|
||
|
||
gauges[id].accel = accel;
|
||
sendReply("OK");
|
||
return true;
|
||
}
|
||
```
|
||
|
||
```cpp
|
||
// After
|
||
bool parseAccel(const String& line) {
|
||
int id; float accel;
|
||
if (sscanf(line.c_str(), "ACCEL %d %f", &id, &accel) == 2) {
|
||
if (id < 0 || id >= GAUGE_COUNT) { sendReply("ERR BAD_ID"); return true; }
|
||
if (accel <= 0.0f) { sendReply("ERR BAD_ACCEL"); return true; }
|
||
gauges[id].accel = accel;
|
||
sendReply("OK");
|
||
return true;
|
||
}
|
||
return false;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: Replace `parseSweep`**
|
||
|
||
```cpp
|
||
// Before (~20 lines)
|
||
bool parseSweep(const String& line) {
|
||
int firstSpace = line.indexOf(' ');
|
||
int secondSpace = line.indexOf(' ', firstSpace + 1);
|
||
int thirdSpace = line.indexOf(' ', secondSpace + 1);
|
||
|
||
if (firstSpace < 0 || secondSpace < 0 || thirdSpace < 0) return false;
|
||
if (line.substring(0, firstSpace) != "SWEEP") return false;
|
||
|
||
int id = line.substring(firstSpace + 1, secondSpace).toInt();
|
||
float accel = line.substring(secondSpace + 1, thirdSpace).toFloat();
|
||
float speed = line.substring(thirdSpace + 1).toFloat();
|
||
|
||
if (id < 0 || id >= GAUGE_COUNT) {
|
||
sendReply("ERR BAD_ID");
|
||
return true;
|
||
}
|
||
|
||
Gauge& g = gauges[id];
|
||
|
||
if (accel <= 0.0f || speed <= 0.0f) {
|
||
g.sweepEnabled = false;
|
||
g.velocity = 0.0f;
|
||
stopTimerStepping(id);
|
||
sendReply("OK");
|
||
return true;
|
||
}
|
||
|
||
g.accel = accel;
|
||
g.maxSpeed = speed;
|
||
g.sweepEnabled = true;
|
||
g.sweepTowardMax = true;
|
||
atomicWriteLong(g.targetPos, g.maxPos);
|
||
sendReply("OK");
|
||
return true;
|
||
}
|
||
```
|
||
|
||
```cpp
|
||
// After
|
||
bool parseSweep(const String& line) {
|
||
int id; float accel, speed;
|
||
if (sscanf(line.c_str(), "SWEEP %d %f %f", &id, &accel, &speed) == 3) {
|
||
if (id < 0 || id >= GAUGE_COUNT) { sendReply("ERR BAD_ID"); return true; }
|
||
Gauge& g = gauges[id];
|
||
if (accel <= 0.0f || speed <= 0.0f) {
|
||
g.sweepEnabled = false;
|
||
g.velocity = 0.0f;
|
||
stopTimerStepping(id);
|
||
sendReply("OK");
|
||
return true;
|
||
}
|
||
g.accel = accel;
|
||
g.maxSpeed = speed;
|
||
g.sweepEnabled = true;
|
||
g.sweepTowardMax = true;
|
||
atomicWriteLong(g.targetPos, g.maxPos);
|
||
sendReply("OK");
|
||
return true;
|
||
}
|
||
return false;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: Verify no `indexOf`/`substring` remain in any `parse*` function**
|
||
|
||
```bash
|
||
grep -n "indexOf\|substring" Gaugecontroller/Gaugecontroller.ino
|
||
```
|
||
|
||
Expected: no output. If any lines appear, check which function still uses the old pattern and redo that step.
|
||
|
||
- [ ] **Step 5: Compile and verify clean**
|
||
|
||
```bash
|
||
arduino-cli compile --fqbn arduino:avr:mega Gaugecontroller
|
||
```
|
||
|
||
Expected: zero errors.
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```bash
|
||
git add Gaugecontroller/Gaugecontroller.ino
|
||
git commit -m "refactor: uniform sscanf parsing in parseSpeed, parseAccel, parseSweep"
|
||
```
|
||
|
||
---
|
||
|
||
## Optional hardware smoke-test (when board is available)
|
||
|
||
After uploading, send these commands over serial and confirm expected replies:
|
||
|
||
```
|
||
PING → PONG
|
||
HOMEALL → OK (then each gauge homes; HOMED 0..3 appear on debug port)
|
||
POS? → POS 0 0 0 1 0 0 (×4, one per gauge)
|
||
SET 0 1000 → OK
|
||
SPEED 0 2000 → OK
|
||
ACCEL 0 8000 → OK
|
||
SWEEP 0 6000 4000 → OK
|
||
SWEEP 0 0 0 → OK (stops sweep)
|
||
```
|
||
|
||
No new error codes were introduced; all existing commands should behave identically to v1.
|