From ba1cd1ddcfbf0bb971c288ed1944dde2bebf82bb Mon Sep 17 00:00:00 2001 From: "James Bateman (hp-laptop)" Date: Fri, 2 Oct 2026 14:21:56 +0100 Subject: [PATCH] Make the pump-1 1 W clamp overridable up to the 8000 mA protocol max Adds a Pump Limit Override: the pump-1 current command is clamped to a soft 4000 mA ceiling (the 1 W diode rating) by default, liftable to the 8000 mA hard protocol max only while the new amp_pump_override switch is ON. Fail-safe: the override defaults OFF on every boot, and switching it OFF immediately re-clamps a running setpoint back down to 4000 mA so the booster cannot stay parked above 1 W. The HA pump-1 number now spans 0..8000 mA; values above 4000 take effect only with the override on. PUMP_CURRENT_MAX_MA is split into PUMP_CURRENT_SOFT_MAX_MA (4000) and PUMP_CURRENT_HARD_MAX_MA (8000). README/BOM updated. Builds clean (flash 59.3%); not yet flashed (ESP32 needs USB, no OTA). Co-Authored-By: Claude Opus 4.8 (1M context) --- BOM.md | 2 +- README.md | 8 +++++--- include/config.h | 16 ++++++++++++---- src/main.cpp | 35 ++++++++++++++++++++++++++++++++--- 4 files changed, 50 insertions(+), 11 deletions(-) diff --git a/BOM.md b/BOM.md index 871b1d8..c7c2c2d 100644 --- a/BOM.md +++ b/BOM.md @@ -57,4 +57,4 @@ Both instrument links are 3V3 logic at 115200 8N1 (the CTL200 is 5V-tolerant). U ## Safety -Class 4, >1 W, invisible 1550 nm. The firmware current clamps (`SEED_CURRENT_MAX_MA`, `PUMP_CURRENT_MAX_MA`) are guardrails, not interlocks. Always drop the pump to 0 before unmating any fibre, ramp the pump gradually (it overshoots ~2× on a step up and settles in 2–4 s), and terminate the output in a power meter or beam dump. See the repo README for the measured pump-current vs output-power curve. +Class 4, >1 W, invisible 1550 nm. The firmware current clamps (`SEED_CURRENT_MAX_MA`, and the soft/hard pump-1 ceilings `PUMP_CURRENT_SOFT_MAX_MA` / `PUMP_CURRENT_HARD_MAX_MA`, the latter reachable only with the Pump Limit Override switch on) are guardrails, not interlocks. Always drop the pump to 0 before unmating any fibre, ramp the pump gradually (it overshoots ~2× on a step up and settles in 2–4 s), and terminate the output in a power meter or beam dump. See the repo README for the measured pump-current vs output-power curve. diff --git a/README.md b/README.md index 0f178fe..f6328ef 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ The unit (factory APC setpoint 30 dBm) comfortably exceeds 1 W: 1.22 W at 4500 m > **Internal PD vs external power meter:** at 4500 mA the internal PD reported 1.22 W while a Thorlabs meter measured **1.05 W** at the output (~0.6 dB high / residual loss). Treat the `amp/output*_power_dbm` telemetry as indicative, ~0.5–0.6 dB optimistic, not a calibrated power reading. (The earlier lab notes saw the opposite sign through a different connection, so the offset is path-dependent.) -> **Safety:** Class 4, >1 W, invisible 1550 nm. The firmware clamps pump-1 to `PUMP_CURRENT_MAX_MA` (4000 mA ≈ the 1 W rating) and seed current to `SEED_CURRENT_MAX_MA` — guardrails against accidental over-drive, **not interlocks**. Above 1 W the Agiltron manual requires matched high-power connectors or a splice on the output, else the output fibre/amplifier can be damaged. Always drop the pump to 0 before unmating any fibre. Treat the output as hazardous unless it terminates in a power meter / beam dump. +> **Safety:** Class 4, >1 W, invisible 1550 nm. The firmware clamps pump-1 to a soft 4000 mA ceiling (≈ the 1 W rating, `PUMP_CURRENT_SOFT_MAX_MA`), liftable to the 8000 mA hard protocol max (`PUMP_CURRENT_HARD_MAX_MA`) only while the Pump Limit Override switch is on, and seed current to `SEED_CURRENT_MAX_MA` — guardrails against accidental over-drive, **not interlocks**. Above 1 W the Agiltron manual requires matched high-power connectors or a splice on the output, else the output fibre/amplifier can be damaged. Always drop the pump to 0 before unmating any fibre. Treat the output as hazardous unless it terminates in a power meter / beam dump. ## Hardware @@ -101,7 +101,7 @@ Copy `include/secrets.example.h` → `include/secrets.h` (git-ignored) and fill - [x] **2 — WiFi + MQTT + HA discovery.** Joins WiFi, connects to broker with an LWT availability topic, publishes diagnostic entities (uptime, RSSI, IP). - [x] **3 — Seed telemetry (read-only).** UART2 → Koheron `lason`/`ilaser`/`vlaser`/`rtset`/`rtact`/`itec`/`vtec`/`tboard`/`iphd`/`err`; published under `seed/...` as HA sensors. Verified live against CTL200 fw v0.21 (echo + value + `>>` framing, parsed correctly). - [x] **4 — Amp telemetry (read-only).** UART1 → Agiltron `get_status` (binary 0x55AA, ported from `edfa.py`); publishes module/pre-amp temp, pre-amp & pump-1 currents, input/pre-amp/output dBm, warnings under `amp/...`. Verified against the live unit (SN Y4022708, PN EDFA-1C51113331111, device ID 0x0000006F). `amp/pump_enabled` reads the authoritative `get_settings` field. -- [x] **5 — control.** `set/...` for seed (`lason`, `ilaser`) and amp (pump on/off, pump-1 ACC current) as HA switch/number entities, with firmware current clamps. Verified end-to-end: MQTT command → seed lasing → booster ramp to 27 dBm. Seed TEC setpoint (`rtset`, in ohms) is also settable, with a read-only °C readout derived from the thermistor. (Future: seed `tecon`, amp APC power, Koheron `save`.) +- [x] **5 — control.** `set/...` for seed (`lason`, `ilaser`) and amp (pump on/off, pump-1 ACC current) as HA switch/number entities, with firmware current clamps. Verified end-to-end: MQTT command → seed lasing → booster ramp to 27 dBm. Seed TEC setpoint (`rtset`, in ohms) is also settable, with a read-only °C readout derived from the thermistor. A **Pump Limit Override** switch (`set/amp/pump_override`) lifts the pump-1 clamp from the soft 4000 mA (1 W) guardrail to the 8000 mA protocol max for supervised over-rating; it defaults off on every boot and re-clamps a running pump back to 4000 mA when switched off. (Future: seed `tecon`, amp APC power, Koheron `save`.) ## MQTT interface @@ -124,6 +124,7 @@ State topics retained under `lab/laser/butterfly_edfa_rack/`: | `amp/pump1_current_ma`, `amp/pump1_set_ma` | booster pump actual / setpoint | | `amp/input_power_dbm`, `amp/output1_power_dbm`, `amp/output2_power_dbm` | optical powers | | `amp/pump_enabled`, `amp/warnings` | booster state, decoded warnings | +| `amp/pump_override` | pump-1 limit override on (1/0) | Command topics (publish to `lab/laser/butterfly_edfa_rack/set/`): @@ -133,4 +134,5 @@ Command topics (publish to `lab/laser/butterfly_edfa_rack/set/`): | `seed/current_ma` | mA | Koheron `ilaser` (clamped ≤ `SEED_CURRENT_MAX_MA`) | | `seed/rt_setpoint_ohm` | Ω | Koheron `rtset`, seed TEC setpoint (clamped `SEED_RT_SETPOINT_MIN/MAX_OHM`) | | `amp/pump` | `1` / `0` | Agiltron pump on / off | -| `amp/pump1_current_ma` | mA | set ACC mode + pump-1 current (clamped ≤ `PUMP_CURRENT_MAX_MA`) | +| `amp/pump1_current_ma` | mA | set ACC mode + pump-1 current (clamped ≤ soft 4000 mA, or ≤ hard 8000 mA when override on) | +| `amp/pump_override` | `1` / `0` | lift the pump-1 clamp from soft (4000 mA / 1 W) to hard (8000 mA). Default off; switching off re-clamps a running pump to soft | diff --git a/include/config.h b/include/config.h index f6cd667..f138756 100644 --- a/include/config.h +++ b/include/config.h @@ -26,10 +26,18 @@ // HA number sliders are capped here. The hardware allows 8000 mA pump, but // the lab notes report ~2500 mA pump-1 -> ~27 dBm (~515 mW). Keep a margin. #define SEED_CURRENT_MAX_MA 300 // CTL200 ilmax default is 1000; seed DFB is low-power -// Pump-1 clamp = the 1 W rated operating point (~4000 mA, measured 2026-06-17). -// Raise deliberately only for supervised over-rating characterisation; it is a -// guardrail against accidental over-drive, not a safety interlock. -#define PUMP_CURRENT_MAX_MA 4000 +// Pump-1 current clamp. Two ceilings: +// SOFT (default) = the 1 W rated operating point (~4000 mA, measured +// 2026-06-17). Guards against accidental over-drive. NOT a safety interlock. +// HARD = the Agiltron protocol / hardware maximum (8000 mA). Reachable only +// while the "Pump limit override" switch is ON (set/amp/pump_override), for +// supervised over-rating characterisation. Driving the 1 W-rated pump diode +// toward 8000 mA trades diode lifetime (and risks damage) for extra power. +// The HA number slider spans 0..HARD; a command above SOFT is clamped to SOFT +// unless the override is ON. Turning the override OFF re-clamps a running +// setpoint back down to SOFT immediately. +#define PUMP_CURRENT_SOFT_MAX_MA 4000 +#define PUMP_CURRENT_HARD_MAX_MA 8000 // Seed thermistor setpoint (CTL200 `rtset`) clamp, in ohms. The CTL200 has no // native °C setpoint; it regulates the seed TEC to hold the thermistor at this diff --git a/src/main.cpp b/src/main.cpp index c0eb5ef..36fb1f4 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -22,6 +22,13 @@ static Koheron koheron(Serial2, KOHERON_RX_PIN, KOHERON_TX_PIN, KOHERON_BA static const uint8_t kAmpDevId[4] = {AGILTRON_DEV_ID}; static Agiltron agiltron(Serial1, AGILTRON_RX_PIN, AGILTRON_TX_PIN, AGILTRON_BAUD, kAmpDevId); +// Pump-1 limit override. false => clamp pump-1 commands to the SOFT (1 W) +// ceiling; true => allow up to the HARD (protocol) ceiling. Defaults OFF on +// every boot (fail-safe). pump1SetMa tracks the last commanded setpoint so the +// override can re-clamp a running pump down when it is switched back off. +static bool pumpOverride = false; +static int pump1SetMa = 0; + // Probe each instrument link once per boot to reveal its framing. #define KOHERON_RAW_PROBE 1 #define AGILTRON_PROBE 1 @@ -152,7 +159,10 @@ static void publishDiscovery() { // Amp controls switchDiscovery("amp_pump", "Amp Pump", "amp/pump_enabled", "amp/pump", "1", "0", "mdi:flash"); numberDiscovery("amp_set_pump_current", "Amp Pump Current", "amp/pump1_set_ma", "amp/pump1_current_ma", - 0, PUMP_CURRENT_MAX_MA, 10, "mA", "mdi:current-dc"); + 0, PUMP_CURRENT_HARD_MAX_MA, 10, "mA", "mdi:current-dc"); + // Override the soft (1 W) pump-1 clamp up to the hard protocol ceiling. + switchDiscovery("amp_pump_override", "Amp Pump Limit Override", "amp/pump_override", "amp/pump_override", + "1", "0", "mdi:lock-open-variant"); } // ── State publishing ──────────────────────────────────────────────── @@ -211,6 +221,7 @@ static void pub(const char *sub, const String &v) { static void publishAmp() { AmpStatus s = agiltron.getStatus(); mqtt.publish(TOPIC_BASE "/amp/link", s.valid ? AVAIL_ONLINE : AVAIL_OFFLINE, true); + pub("amp/pump_override", pumpOverride ? "1" : "0"); // reflect override state if (!s.valid) return; pub("amp/module_temp_c", String(s.module_temp_c, 1)); pub("amp/preamp_temp_c", String(s.preamp_temp_c, 1)); @@ -262,11 +273,29 @@ static void onMqtt(char *topic, byte *payload, unsigned int len) { } else if (t == TOPIC_CMD "/amp/pump1_current_ma") { int ma = (int)p.toFloat(); if (ma < 0) ma = 0; - if (ma > PUMP_CURRENT_MAX_MA) ma = PUMP_CURRENT_MAX_MA; // firmware clamp + int cap = pumpOverride ? PUMP_CURRENT_HARD_MAX_MA : PUMP_CURRENT_SOFT_MAX_MA; + if (ma > cap) ma = cap; // firmware clamp (soft unless overridden) agiltron.setPump1Mode(Agiltron::ACC); // current-control mode (lab note: avoid APC steps) bool ok = agiltron.setPump1Current(ma); - Serial.printf("[cmd] amp pump1 = %d mA -> %s\n", ma, ok ? "ack" : "NO-ACK"); + pump1SetMa = ma; + Serial.printf("[cmd] amp pump1 = %d mA (cap %d) -> %s\n", ma, cap, ok ? "ack" : "NO-ACK"); pub("amp/pump1_set_ma", String(ma)); + + } else if (t == TOPIC_CMD "/amp/pump_override") { + bool on = (p == "1" || p.equalsIgnoreCase("on") || p.equalsIgnoreCase(AVAIL_ONLINE)); + pumpOverride = on; + Serial.printf("[cmd] pump limit override -> %s\n", + on ? "ON (hard 8000 mA)" : "OFF (soft 4000 mA)"); + // Disabling the override must not leave the booster parked above 1 W: if the + // running setpoint is above the soft cap, re-clamp it down immediately. + if (!on && pump1SetMa > PUMP_CURRENT_SOFT_MAX_MA) { + pump1SetMa = PUMP_CURRENT_SOFT_MAX_MA; + agiltron.setPump1Mode(Agiltron::ACC); + agiltron.setPump1Current(pump1SetMa); + pub("amp/pump1_set_ma", String(pump1SetMa)); + Serial.printf("[cmd] override off: re-clamped pump1 to %d mA\n", pump1SetMa); + } + pub("amp/pump_override", on ? "1" : "0"); } }