From b3e46fac2f8b9c285c3ecb261a5d67edf68db32e Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Mon, 7 Sep 2026 17:15:49 -0400
Subject: [PATCH 1/3] =?UTF-8?q?feat(console):=20analog-input=20calibration?=
 =?UTF-8?q?=20UI=20in=20the=20Analog=20In=20panel=20(two-point,=20deadband?=
 =?UTF-8?q?,=20clear,=20read)=20+=20wire=200xA5/0xA6/0xA7=20+=20ai=5Fcal?=
 =?UTF-8?q?=20capability=20(S2)=20=E2=80=94=20Studio=20v0.75?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Studio half S2 of docs/development/analog-input-plan.md § 4. Stacked on S1
(feat/console-analog-in). Pairs with firmware F2 (feat/ai-calibration).

- js/arena-wire-g6.js: OPCODES SET_ANALOG_CAL 0xA5 / GET_ANALOG_CAL 0xA6 /
  GET_ANALOG_IN_RAW 0xA7; ANALOG_CAL_ACTIONS {sampleGround 0, sampleOpen 1,
  setDeadband 2, clear 0xFF}; encodeSetAnalogCal(ch, action, mv) with range
  checks, encodeGetAnalogCal, encodeGetAnalogInRaw; decodeAnalogCal (18-byte
  record -> {version, adcBits, source, sdMirrorOk, channels[{valid, rawOpen,
  rawGnd, deadbandMv, gainMvPerCount, offsetMv}]}), decodeAnalogInRaw;
  CAPABILITY_BITS bit 6 'ai_cal'. Tests 186 -> 204.
- js/studio-analog-in.js: nominalMv, calLine, calMv, calStepsText,
  describeCalSource, calTableRows.
- arena_studio.html: "calibrate" row in the Analog In panel — channel select,
  Read (0xA6 + 0xA7 -> table with both points, mV/count, offset, deadband, live
  raw on the calibrated and nominal scales), "1 · Sample +10 V (open)",
  "2 · Sample 0 V (ground cap)", deadband Set, Clear (confirm). Writes are
  advanced-only (SAFE_BLOCKED_CMDS) and gated on the ai_cal capability; every
  write is logged to the Console and to the bridge run log (event analog_cal),
  and refreshes the 0xA4 flags text. Warns when the +10 V point reads low
  (BNC not open / un-reworked board). HELP text updated; footer v0.75.
- tests/test-studio-analog-in.js 105 -> 148: calibration math + wiring incl.
  the safe-mode set (writes blocked, read allowed) and the ai_cal gate.
- Release notes v0.75.

Not bench-tested (no hardware). Browser check offline: panel renders, handlers
wired; the real two-point flow needs a board with ai_cal firmware.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 arena_studio.html                             |  85 +++++++++++++-
 .../development/arena-studio-release-notes.md |  11 ++
 js/arena-wire-g6.js                           | 107 +++++++++++++++++-
 js/studio-analog-in.js                        |  87 +++++++++++++-
 tests/test-arena-wire-g6.js                   |  71 ++++++++++++
 tests/test-studio-analog-in.js                |  84 ++++++++++++++
 6 files changed, 439 insertions(+), 6 deletions(-)

diff --git a/arena_studio.html b/arena_studio.html
index fba4fcd6..4b3b8c93 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -2830,6 +2830,16 @@ <h2 id="modalTitle">Import error</h2>
             <button class="pill" id="cAiSweepCsv" data-cmd="caisweepcsv" disabled title="Copy the last sweep (ao_mv, ai1_mv, ai2_mv) to the clipboard as CSV">Copy CSV</button>
             <span class="dim" id="cAiSweepSum"></span></div>
           <div class="crow" id="cAiSweepRow" style="display:none"><table class="ai-table" id="cAiSweepTable"></table></div>
+          <div class="crow"><span class="lbl" title="Per-board two-point calibration (needs ai_cal firmware): with nothing on the BNC the input reads the +10 V reference; with a BNC ground cap it reads 0 V. The controller samples each point (256 averaged reads), stores the record in its EEPROM, mirrors it to the SD card, and uses it for GET_ANALOG_IN and Mode 4.">calibrate</span>
+            <label title="Which input to calibrate">channel <select id="cAiCalCh"><option value="1">Analog In 1</option><option value="2">Analog In 2</option></select></label>
+            <button class="pill" data-cmd="caicalread" title="GET_ANALOG_CAL 0xA6 + GET_ANALOG_IN_RAW 0xA7 — show the stored record for both channels and the live raw counts on both scales">Read</button>
+            <button class="pill" data-cmd="caicalopen" title="Step 1 — unplug the BNC so the input floats at the +10 V reference, then click: the controller averages 256 reads and stores them as the +10 V point (SET_ANALOG_CAL 0xA5 action 1)">1 · Sample +10 V (open)</button>
+            <button class="pill" data-cmd="caicalgnd" title="Step 2 — fit the BNC ground cap, then click: the controller averages 256 reads and stores them as the 0 V point (action 0); with both points the channel becomes calibrated">2 · Sample 0 V (ground cap)</button>
+            <label title="Mode 4 zero band — inputs within this many mV of the calibrated 0 V give 0 frames/s, so a static input does not creep the pattern (0–2000 mV)">deadband <input id="cAiDeadband" type="number" min="0" max="2000" step="1" value="20" style="width:56px"> mV</label>
+            <button class="pill" data-cmd="caicaldb" title="Store the deadband for the selected channel (SET_ANALOG_CAL 0xA5 action 2)">Set</button>
+            <button class="pill led-off" data-cmd="caicalclear" title="Forget the selected channel's two points — back to the nominal ±10 V scale (the deadband is kept)">Clear</button>
+            <span class="dim" id="cAiCalSum" title="Where the record lives and its state"></span></div>
+          <div class="crow" id="cAiCalTableRow" style="display:none"><table class="ai-table" id="cAiCalTable"></table></div>
           <div class="crow" style="margin-bottom:0"><span class="dim" style="font-size:10.5px" title="Status of the analog-input path (docs/development/analog-input-plan.md)">±10 V front end · nominal scale, per-board calibration not yet applied · a board without the LAB-209 resistor rework reads ≈ +10 V for any input above 0 V · needs io_ext firmware</span></div>
           </div>
         </section>
@@ -2953,7 +2963,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.74 | 2026-09-10 16:50 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub: source, issues, and release notes (docs/development/arena-studio-release-notes.md)">GitHub</a></span>
+  <span class="foot-left">Arena Studio v0.75 | 2026-09-10 18:38 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub: source, issues, and release notes (docs/development/arena-studio-release-notes.md)">GitHub</a></span>
   <!-- Course-repo quick-links: open protocols / logs / patterns in a new tab.
        Hrefs built from the configured repo + bench id (updateGhQuickLinks). -->
   <span id="ghQuickLinks" title="Open the course repo on GitHub (new tab)">
@@ -3721,7 +3731,9 @@ <h2 id="modalTitle">Import error</h2>
         // program panels / firmware
         'cispbatch', 'cfwpick', 'cfwflash',
         // change controller / advanced settings
-        'setpanelmode', 'setrate', 'setspi', 'sysreset'
+        'setpanelmode', 'setrate', 'setspi', 'sysreset',
+        // analog-input calibration (writes the controller's EEPROM record)
+        'caicalopen', 'caicalgnd', 'caicaldb', 'caicalclear'
     ]);
     // Exposed on Studio for the ConsoleView dispatcher (separate IIFE/script) —
     // referencing the bare const there threw a ReferenceError, which killed EVERY
@@ -5162,6 +5174,64 @@ <h2 id="modalTitle">Import error</h2>
         }
     }
 
+    // ---- Analog In calibration (analog-input-plan § 4 S2; firmware F2 ai_cal) ----
+    function aiHasCal() {
+        return Array.isArray(Studio.capabilities) && Studio.capabilities.includes('ai_cal');
+    }
+    function aiCalRenderTable(rec, raws) {
+        const row = $('cAiCalTableRow');
+        const tbl = $('cAiCalTable');
+        const sum = $('cAiCalSum');
+        if (!row || !tbl || !AI) return;
+        if (sum) sum.textContent = AI.describeCalSource(rec);
+        const esc = (t) => String(t).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+        const f = (v, d) => (v === null || v === undefined || Number.isNaN(v) ? '—' : typeof v === 'number' ? v.toFixed(d || 0) : String(v));
+        let html = '<tr><th>ch</th><th>state</th><th>raw +10 V</th><th>raw 0 V</th><th>mV/count</th><th>offset mV</th><th>deadband</th><th>raw now</th><th>mV cal</th><th>mV nominal</th></tr>';
+        for (const r of AI.calTableRows(rec, raws)) {
+            html += '<tr><td>' + r.ch + '</td><td class="' + (r.valid ? '' : 'bad') + '">' + esc(AI.calStepsText(rec.channels[r.ch - 1])) + '</td><td>' + f(r.rawOpen) + '</td><td>' + f(r.rawGnd) + '</td><td>' + f(r.a, 4) + '</td><td>' + f(r.b, 0) + '</td><td>' + f(r.deadbandMv) + ' mV</td><td>' + f(r.rawNow) + '</td><td>' + f(r.mvCal, 0) + '</td><td>' + f(r.mvNominal, 0) + '</td></tr>';
+        }
+        tbl.innerHTML = html;
+        row.style.display = '';
+    }
+    async function aiCalRead(quiet) {
+        if (!session || !session.connected) { if (!quiet) clog('analog cal: not connected', 'err'); return null; }
+        if (!aiHasCal()) {
+            if (!quiet) clog('analog cal: controller lacks ai_cal (0xC2 bit 6) — needs firmware feat/ai-calibration or later', 'warn');
+            const sum = $('cAiCalSum'); if (sum) sum.textContent = 'needs ai_cal firmware';
+            return null;
+        }
+        const r1 = await send(Wire.encodeGetAnalogCal(), 'GET_ANALOG_CAL 0xA6');
+        const rec = r1 && Wire.decodeAnalogCal(r1);
+        if (!rec) { clog('analog cal: bad GET_ANALOG_CAL reply', 'err'); return null; }
+        const r2 = await send(Wire.encodeGetAnalogInRaw(), 'GET_ANALOG_IN_RAW 0xA7');
+        const raws = r2 && Wire.decodeAnalogInRaw(r2);
+        aiCalRenderTable(rec, raws);
+        return rec;
+    }
+    async function aiCalAction(action, mv) {
+        if (!session || !session.connected) { clog('analog cal: not connected', 'err'); return; }
+        if (!aiHasCal()) { clog('analog cal: controller lacks ai_cal (0xC2 bit 6) — needs firmware feat/ai-calibration or later', 'warn'); return; }
+        const ch = Number(($('cAiCalCh') || {}).value) === 2 ? 2 : 1;
+        let bytes;
+        try { bytes = Wire.encodeSetAnalogCal(ch, action, mv); }
+        catch (e) { clog('analog cal: ' + (e.message || e), 'err'); return; }
+        const label = 'SET_ANALOG_CAL 0xA5 ch ' + ch + ' ' + action + (action === 'setDeadband' ? ' ' + mv + ' mV' : '');
+        const resp = await send(bytes, label);
+        const rec = resp && Wire.decodeAnalogCal(resp);
+        if (!rec) return;
+        const c = rec.channels[ch - 1];
+        const line = AI.calLine(c);
+        clog('analog cal ch ' + ch + ': ' + AI.calStepsText(c) + (line ? ' · ' + line.a.toFixed(4) + ' mV/count · offset ' + Math.round(line.b) + ' mV' : '') + ' · deadband ' + c.deadbandMv + ' mV · ' + AI.describeCalSource(rec),
+             c.valid || action === 'clear' || action === 'setDeadband' ? 'info' : 'warn');
+        if (action === 'sampleOpen' && c.rawOpen < 3000) clog('analog cal: the +10 V point reads low (' + c.rawOpen + ' counts) — is the BNC really open? On a board without the LAB-209 rework both points saturate and the channel stays invalid', 'warn');
+        const bridge = Studio.session && Studio.session.bridge;
+        if (bridge && bridge.log) bridge.log({ event: 'analog_cal', channel: ch, action: action, deadband_mv: mv, record: rec });
+        const r2 = await send(Wire.encodeGetAnalogInRaw(), 'GET_ANALOG_IN_RAW 0xA7');
+        aiCalRenderTable(rec, r2 && Wire.decodeAnalogInRaw(r2));
+        aiUser.lastFlags = undefined; // force the flags text to refresh on the next sample
+        if (aiPoller) aiPoller.tick();
+    }
+
     // ---- command dispatch ----
     const handlers = {
         // display essentials
@@ -5367,6 +5437,15 @@ <h2 id="modalTitle">Import error</h2>
                 clog('clipboard unavailable — sweep CSV:\n' + csv, 'warn');
             }
         },
+        // Analog In calibration (S2) — writes are advanced-only (SAFE_BLOCKED_CMDS)
+        caicalread: () => { aiCalRead(false); },
+        caicalopen: () => guardDestructive(() => { aiCalAction('sampleOpen'); }),
+        caicalgnd: () => guardDestructive(() => { aiCalAction('sampleGround'); }),
+        caicaldb: () => guardDestructive(() => { aiCalAction('setDeadband', Math.round(num('cAiDeadband'))); }),
+        caicalclear: () => guardDestructive(() => {
+            if (!confirm('Forget the selected channel\'s calibration points? GET_ANALOG_IN and Mode 4 fall back to the nominal ±10 V scale.')) return;
+            aiCalAction('clear');
+        }),
         cioget: async () => {
             if (!Studio.capabilities || !Studio.capabilities.includes('io_ext')) {
                 clog('dio roles: controller lacks io_ext (0xC2 bit 5) — needs fw feat/dio-roles-ao-modes or later', 'warn');
@@ -15277,7 +15356,7 @@ <h2 id="modalTitle">Import error</h2>
     step: 'Load the selected pattern, then walk through it frame by frame — good for checking exactly what each frame shows.',
     test: 'Built-in test figures (full field, panel map, orientation, checker) and files streamed straight from this computer.',
     io: 'Read the analog input, set the analog output, and drive the two digital connectors.',
-    ai: 'Both analog inputs, live. Cable Analog Out to an input and run the loopback sweep to check the wiring end to end; polling pauses by itself during a run.',
+    ai: 'Both analog inputs, live. Cable Analog Out to an input and run the loopback sweep to check the wiring; calibrate a channel in two steps (BNC open, then ground cap) so the readings and closed loop use this board’s true scale. Polling pauses by itself during a run.',
     fw: 'Check what firmware the panels run, and program new firmware into every panel from here.',
     fictrac: 'Closed loop: connect the bridge, load a pattern in Step frames, set the gain, then Activate — the fly steers the pattern.'
   };
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index 3bb53c4f..ecea170b 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -4,6 +4,17 @@ The Studio's footer used to carry the full changelog inline; it now shows one li
 history lives here. Newest first. (Per-session engineering detail stays in
 `arena-studio-handover.md` and the design docs — this file is the user-facing what-changed list.)
 
+## v0.75 (2026-09-07) · Analog-input calibration from the Console
+
+- **Calibrate the analog inputs in two clicks** (Analog In panel → calibrate; needs a
+  controller with the `ai_cal` firmware). Unplug the BNC and sample the +10 V point,
+  fit the ground cap and sample the 0 V point — the controller averages 256 reads per
+  point, stores the record in its own memory (mirrored to the SD card), and from then
+  on both the live readout and Mode 4 closed loop use the board's true scale. Read shows
+  the stored record with the live raw counts on both scales; Clear returns a channel to
+  the nominal scale; a **deadband** (default 20 mV) stops a static input from creeping
+  the pattern in Mode 4. Writes are advanced-mode only and are recorded in the run log.
+
 ## v0.74 (2026-09-07) · Console "Analog In" panel — live readout + loopback self-test
 
 - **New Console tool: Analog In.** A left-rail button opens a live readout of both
diff --git a/js/arena-wire-g6.js b/js/arena-wire-g6.js
index dce2a3b1..08fa3dbb 100644
--- a/js/arena-wire-g6.js
+++ b/js/arena-wire-g6.js
@@ -69,7 +69,10 @@ const ArenaWireG6 = (function () {
         SET_AO_VOLTAGE: 0xa0, // [03 A0 mv_lo mv_hi] set analog output (BNC J27) 0–5000 mV
         GET_AO_VOLTAGE: 0xa1, // [01 A1] returns last commanded AO level as uint16 LE mV
         SET_AO_MODE: 0xa3, // [02 A3 mode] 0=programmable | 1=frame_number (io_ext fw)
-        GET_ANALOG_IN: 0xa4, // [01 A4] returns Analog In 1+2 as two int16 LE mV (io_ext fw)
+        GET_ANALOG_IN: 0xa4, // [01 A4] returns Analog In 1+2 as two int16 LE mV (+ flags byte, F1 fw)
+        SET_ANALOG_CAL: 0xa5, // [len A5 ch action (mv_lo mv_hi)] two-point calibration / deadband / clear (ai_cal fw)
+        GET_ANALOG_CAL: 0xa6, // [01 A6] → 18-byte calibration record (ai_cal fw)
+        GET_ANALOG_IN_RAW: 0xa7, // [01 A7] → raw ADC counts of both inputs, two uint16 LE (ai_cal fw)
         SET_DIGITAL_OUT: 0xaa, // [03 AA ch state] DO1 (ch=1, J3/D37) or DO2 (ch=2, J4/D35)
         GET_DIGITAL_OUT: 0xab, // [01 AB] returns current state of DO1 and DO2 as two bytes
         SET_DIO_ROLE: 0xac, // [03 AC port role] "Digital IO 1/2 (5V)" role (io_ext fw)
@@ -115,9 +118,19 @@ const ArenaWireG6 = (function () {
         // Extended I/O command set (#135): SET_DIO_ROLE 0xAC / GET_DIO_ROLE
         // 0xAD / SET_AO_MODE 0xA3 / GET_ANALOG_IN 0xA4 — hosts detect the
         // DIO-role machinery by this bit, not by firmware-version guessing.
-        [5, 'io_ext']
+        [5, 'io_ext'],
+        // Per-board analog-input calibration (analog-input-plan F2): SET_ANALOG_CAL
+        // 0xA5 / GET_ANALOG_CAL 0xA6 / GET_ANALOG_IN_RAW 0xA7, record in EEPROM.
+        [6, 'ai_cal']
     ];
 
+    // SET_ANALOG_CAL (0xA5) actions — the host orchestrates Will's two-point
+    // recipe (open input = +10 V from the reference, BNC ground cap = 0 V); the
+    // controller samples, validates, stores (EEPROM + SD mirror) and applies.
+    const ANALOG_CAL_ACTIONS = { sampleGround: 0, sampleOpen: 1, setDeadband: 2, clear: 0xff };
+    const ANALOG_CAL_DEADBAND_MAX_MV = 2000;
+    const ANALOG_CAL_REF_MV = 10000; // the open-input point
+
     // ───────────────────────── validation helpers ─────────────────────────
 
     function requireInt(value, name) {
@@ -603,6 +616,41 @@ const ArenaWireG6 = (function () {
         return frame(OPCODES.GET_ANALOG_IN); // 01 A4
     }
 
+    /**
+     * set-analog-cal (0xA5) — one calibration action on channel 1|2:
+     * 'sampleGround' (0 V point, ground cap on), 'sampleOpen' (+10 V point, BNC
+     * open), 'setDeadband' (needs mv 0..2000), 'clear'. Names or codes accepted.
+     */
+    function encodeSetAnalogCal(ch, action, mv) {
+        if (ch !== 1 && ch !== 2) throw new RangeError('ch must be 1 or 2, got ' + ch);
+        const code = typeof action === 'string' ? ANALOG_CAL_ACTIONS[action] : action;
+        const known = Object.values(ANALOG_CAL_ACTIONS);
+        if (!known.includes(code)) {
+            throw new RangeError(
+                'action must be one of ' +
+                    Object.keys(ANALOG_CAL_ACTIONS).join('/') +
+                    ', got ' +
+                    action
+            );
+        }
+        if (code === ANALOG_CAL_ACTIONS.setDeadband) {
+            requireInt(mv, 'deadband mv');
+            if (mv < 0 || mv > ANALOG_CAL_DEADBAND_MAX_MV) {
+                throw new RangeError(
+                    'deadband must be 0..' + ANALOG_CAL_DEADBAND_MAX_MV + ' mV, got ' + mv
+                );
+            }
+            return frame(OPCODES.SET_ANALOG_CAL, [ch, code, mv & 0xff, (mv >> 8) & 0xff]); // 05 A5 ch 02 lo hi
+        }
+        return frame(OPCODES.SET_ANALOG_CAL, [ch, code]); // 03 A5 ch action
+    }
+    function encodeGetAnalogCal() {
+        return frame(OPCODES.GET_ANALOG_CAL); // 01 A6
+    }
+    function encodeGetAnalogInRaw() {
+        return frame(OPCODES.GET_ANALOG_IN_RAW); // 01 A7
+    }
+
     // ───────────────────────────── decoders ───────────────────────────────
 
     /**
@@ -786,6 +834,55 @@ const ArenaWireG6 = (function () {
         };
     }
 
+    /**
+     * get/set-analog-cal (0xA6 / 0xA5) reply: [version adc_bits source flags] then per
+     * channel [valid][raw_open u16 LE][raw_gnd u16 LE][deadband_mv u16 LE] (18 B).
+     * Adds the line each valid channel implies: mV = a·raw + b with
+     * a = 10000 / (raw_open − raw_gnd), b = −a·raw_gnd (null when not valid).
+     */
+    function decodeAnalogCal(resp) {
+        const r = asResponse(resp);
+        if (!r || !r.ok || r.payload.length < 18) return null;
+        const p = r.payload;
+        const u16 = (i) => p[i] | (p[i + 1] << 8);
+        const sourceCode = p[2];
+        const channels = [];
+        for (let i = 0; i < 2; i++) {
+            const o = 4 + i * 7;
+            const valid = p[o] === 1;
+            const rawOpen = u16(o + 1);
+            const rawGnd = u16(o + 3);
+            const span = rawOpen - rawGnd;
+            const a = valid && span > 0 ? ANALOG_CAL_REF_MV / span : null;
+            channels.push({
+                ch: i + 1,
+                valid,
+                rawOpen,
+                rawGnd,
+                deadbandMv: u16(o + 5),
+                gainMvPerCount: a,
+                offsetMv: a === null ? null : -a * rawGnd
+            });
+        }
+        return {
+            version: p[0],
+            adcBits: p[1],
+            sourceCode,
+            source: sourceCode === 1 ? 'eeprom' : sourceCode === 0 ? 'none' : 'source' + sourceCode,
+            sdMirrorOk: !!(p[3] & 0x01),
+            channels
+        };
+    }
+    // get-analog-in-raw (0xA7) reply: two uint16 LE ADC counts.
+    function decodeAnalogInRaw(resp) {
+        const r = asResponse(resp);
+        if (!r || !r.ok || r.payload.length < 4) return null;
+        return {
+            raw1: r.payload[0] | (r.payload[1] << 8),
+            raw2: r.payload[2] | (r.payload[3] << 8)
+        };
+    }
+
     // set-firmware-file (0xE0) reply: uint32 LE CRC-32 of the stored image.
     function decodeSetFirmwareFileResponse(resp) {
         const r = asResponse(resp);
@@ -882,6 +979,10 @@ const ArenaWireG6 = (function () {
         encodeGetDioRole,
         encodeSetAoMode,
         encodeGetAnalogIn,
+        encodeSetAnalogCal,
+        encodeGetAnalogCal,
+        encodeGetAnalogInRaw,
+        ANALOG_CAL_ACTIONS,
 
         // Decoders
         decodeResponse,
@@ -899,6 +1000,8 @@ const ArenaWireG6 = (function () {
         decodeDigitalOut,
         decodeDioRole,
         decodeAnalogIn,
+        decodeAnalogCal,
+        decodeAnalogInRaw,
         decodeSetFirmwareFileResponse,
         decodeFirmwareInfo,
         decodeProgramPanelResponse
diff --git a/js/studio-analog-in.js b/js/studio-analog-in.js
index d26f16f1..0f1015f0 100644
--- a/js/studio-analog-in.js
+++ b/js/studio-analog-in.js
@@ -270,6 +270,85 @@
         };
     }
 
+    // ── calibration record helpers (firmware F2, decodeAnalogCal shape) ─────────
+    /** Nominal ±10 V scale for a raw count at the given ADC width (no calibration). */
+    function nominalMv(raw, bits) {
+        const full = Math.pow(2, isNum(bits) ? bits : 12) - 1;
+        if (!isNum(raw)) return NaN;
+        return (raw / full - 0.5) * 2 * FULL_SCALE_MV;
+    }
+    /** {a, b} of mV = a·raw + b for a decoded channel record, or null when not valid. */
+    function calLine(chRec) {
+        if (!chRec || !chRec.valid) return null;
+        const span = chRec.rawOpen - chRec.rawGnd;
+        if (!(span > 0)) return null;
+        const a = FULL_SCALE_MV / span;
+        return { a, b: -a * chRec.rawGnd };
+    }
+    /** Calibrated mV for a raw count (falls back to the nominal scale). */
+    function calMv(chRec, raw, bits) {
+        const line = calLine(chRec);
+        if (!line || !isNum(raw)) return nominalMv(raw, bits);
+        return line.a * raw + line.b;
+    }
+    /** 'both points ✓' / '+10 V point ✓ · 0 V point —' / 'no points' for the UI. */
+    function calStepsText(chRec) {
+        if (!chRec) return '—';
+        const open = chRec.rawOpen > 0;
+        const gnd = chRec.rawGnd > 0 || (chRec.valid && chRec.rawGnd === 0);
+        if (chRec.valid) return 'calibrated (both points)';
+        if (!open && !gnd) return 'no points';
+        return (
+            (open ? '+10 V point ✓' : '+10 V point —') +
+            ' · ' +
+            (gnd ? '0 V point ✓' : '0 V point —')
+        );
+    }
+    function describeCalSource(rec) {
+        if (!rec) return '—';
+        const src =
+            rec.source === 'eeprom'
+                ? 'stored in EEPROM'
+                : rec.source === 'none'
+                  ? 'no record (nominal scale)'
+                  : rec.source;
+        return (
+            src +
+            (rec.source === 'eeprom'
+                ? rec.sdMirrorOk
+                    ? ' · SD mirror ok'
+                    : ' · SD mirror not written'
+                : '') +
+            ' · ' +
+            rec.adcBits +
+            '-bit'
+        );
+    }
+    /**
+     * Rows for the calibration table: one per channel, with the live raw count
+     * (from 0xA7, may be null) evaluated on both scales so the user sees what the
+     * calibration changes.
+     */
+    function calTableRows(rec, raws) {
+        if (!rec) return [];
+        return rec.channels.map((c, i) => {
+            const raw = raws ? (i === 0 ? raws.raw1 : raws.raw2) : null;
+            const line = calLine(c);
+            return {
+                ch: c.ch,
+                valid: c.valid,
+                rawOpen: c.rawOpen,
+                rawGnd: c.rawGnd,
+                a: line ? line.a : null,
+                b: line ? line.b : null,
+                deadbandMv: c.deadbandMv,
+                rawNow: isNum(raw) ? raw : null,
+                mvCal: isNum(raw) && line ? line.a * raw + line.b : null,
+                mvNominal: isNum(raw) ? nominalMv(raw, rec.adcBits) : null
+            };
+        });
+    }
+
     // ── loopback sweep ─────────────────────────────────────────────────────────
     /** Inclusive AO levels from..to by step, clamped to 0..5000 mV, integers. */
     function sweepPlan(fromMv, toMv, stepMv) {
@@ -446,7 +525,13 @@
         fitLinear,
         summarizeSweep,
         sweepCsv,
-        drawStripChart
+        drawStripChart,
+        nominalMv,
+        calLine,
+        calMv,
+        calStepsText,
+        describeCalSource,
+        calTableRows
     };
 
     if (typeof module !== 'undefined' && module.exports) module.exports = StudioAnalogIn;
diff --git a/tests/test-arena-wire-g6.js b/tests/test-arena-wire-g6.js
index 6fe51bbf..25a6b153 100644
--- a/tests/test-arena-wire-g6.js
+++ b/tests/test-arena-wire-g6.js
@@ -118,6 +118,77 @@ checkThrows('ao mode 2 throws', () => Wire.encodeSetAoMode(2));
         Wire.decodeDioRole(Uint8Array.from([0x06, 0x01, 0xad, 0x02, 0x01, 0x01, 0x00])) === null
     );
 }
+// analog-input calibration (0xA5/0xA6/0xA7, ai_cal fw)
+checkBytes(
+    'encodeSetAnalogCal(1, sampleOpen)',
+    Wire.encodeSetAnalogCal(1, 'sampleOpen'),
+    '03 a5 01 01'
+);
+checkBytes(
+    'encodeSetAnalogCal(2, sampleGround) numeric',
+    Wire.encodeSetAnalogCal(2, 0),
+    '03 a5 02 00'
+);
+checkBytes('encodeSetAnalogCal(1, clear)', Wire.encodeSetAnalogCal(1, 'clear'), '03 a5 01 ff');
+checkBytes(
+    'encodeSetAnalogCal(2, setDeadband, 300)',
+    Wire.encodeSetAnalogCal(2, 'setDeadband', 300),
+    '05 a5 02 02 2c 01'
+);
+checkBytes('encodeGetAnalogCal', Wire.encodeGetAnalogCal(), '01 a6');
+checkBytes('encodeGetAnalogInRaw', Wire.encodeGetAnalogInRaw(), '01 a7');
+checkThrows('encodeSetAnalogCal rejects ch 3', () => Wire.encodeSetAnalogCal(3, 'clear'));
+checkThrows('encodeSetAnalogCal rejects unknown action', () => Wire.encodeSetAnalogCal(1, 'bogus'));
+checkThrows('encodeSetAnalogCal deadband > 2000 rejected', () =>
+    Wire.encodeSetAnalogCal(1, 'setDeadband', 2001)
+);
+checkThrows('encodeSetAnalogCal deadband needs an integer', () =>
+    Wire.encodeSetAnalogCal(1, 'setDeadband')
+);
+{
+    // record: v1, 12-bit, source eeprom, mirror ok; ch1 valid open=3700 gnd=100 db=20; ch2 invalid db=50
+    const rec = Wire.decodeAnalogCal(
+        Uint8Array.from([
+            0x14, 0x00, 0xa6, 1, 12, 1, 1, 1, 0x74, 0x0e, 0x64, 0x00, 0x14, 0x00, 0, 0, 0, 0, 0,
+            0x32, 0x00
+        ])
+    );
+    check(
+        'decodeAnalogCal header',
+        String([rec.version, rec.adcBits, rec.source, rec.sdMirrorOk]),
+        '1,12,eeprom,true'
+    );
+    check(
+        'decodeAnalogCal ch1 points',
+        String([
+            rec.channels[0].valid,
+            rec.channels[0].rawOpen,
+            rec.channels[0].rawGnd,
+            rec.channels[0].deadbandMv
+        ]),
+        'true,3700,100,20'
+    );
+    check('decodeAnalogCal ch1 line a', Math.round(rec.channels[0].gainMvPerCount * 1000), 2778); // 10000/3600
+    check('decodeAnalogCal ch1 line b', Math.round(rec.channels[0].offsetMv), -278);
+    check(
+        'decodeAnalogCal ch2 invalid → no line',
+        String([rec.channels[1].valid, rec.channels[1].gainMvPerCount, rec.channels[1].deadbandMv]),
+        'false,,50'
+    );
+    check(
+        'decodeAnalogCal short payload → null',
+        Wire.decodeAnalogCal(Uint8Array.from([0x05, 0x00, 0xa6, 1, 12, 1, 0])),
+        null
+    );
+    const raw = Wire.decodeAnalogInRaw(Uint8Array.from([0x06, 0x00, 0xa7, 0x74, 0x0e, 0x64, 0x00]));
+    check('decodeAnalogInRaw', String([raw.raw1, raw.raw2]), '3700,100');
+}
+checkBool(
+    'capability bit 6 is ai_cal',
+    Wire.decodeControllerInfo(Uint8Array.from([0x04, 0x00, 0xc2, 1, 0x63])).capabilities.join(','),
+    'g6_mode,v2_local_storage,io_ext,ai_cal'
+);
+
 // decodeAnalogIn: int16 LE pair — -7263 mV = 0xE3A1, +1234 mV = 0x04D2.
 {
     const a = Wire.decodeAnalogIn(Uint8Array.from([0x06, 0x00, 0xa4, 0xa1, 0xe3, 0xd2, 0x04]));
diff --git a/tests/test-studio-analog-in.js b/tests/test-studio-analog-in.js
index e6db928a..a93f7778 100644
--- a/tests/test-studio-analog-in.js
+++ b/tests/test-studio-analog-in.js
@@ -270,6 +270,52 @@ async function main() {
             'ao_mv,ai1_mv,ai2_mv\n0,15,40\n1000,1035,40\n'
         );
     }
+    console.log('=== calibration record helpers ===');
+    {
+        const ch1 = { ch: 1, valid: true, rawOpen: 3700, rawGnd: 100, deadbandMv: 20 };
+        const ch2 = { ch: 2, valid: false, rawOpen: 3650, rawGnd: 0, deadbandMv: 50 };
+        const rec = {
+            version: 1,
+            adcBits: 12,
+            source: 'eeprom',
+            sdMirrorOk: true,
+            channels: [ch1, ch2]
+        };
+        approx('nominalMv midscale 12-bit = 0', AI.nominalMv(2047.5, 12), 0);
+        approx('nominalMv 0 counts = −10 V', AI.nominalMv(0, 12), -10000);
+        approx('nominalMv 10-bit full scale = +10 V', AI.nominalMv(1023, 10), 10000);
+        const line = AI.calLine(ch1);
+        approx('calLine a = 10000/3600', line.a, 10000 / 3600, 1e-9);
+        approx('calLine b = −a·gnd', line.b, -(10000 / 3600) * 100, 1e-9);
+        check('calLine invalid channel → null', AI.calLine(ch2), null);
+        approx('calMv at the ground point = 0', AI.calMv(ch1, 100), 0, 1e-9);
+        approx('calMv at the open point = +10 000', AI.calMv(ch1, 3700), 10000, 1e-9);
+        approx('calMv falls back to nominal when invalid', AI.calMv(ch2, 2047.5, 12), 0, 1e-9);
+        check('calStepsText valid', AI.calStepsText(ch1), 'calibrated (both points)');
+        check('calStepsText one point', AI.calStepsText(ch2), '+10 V point ✓ · 0 V point —');
+        check(
+            'calStepsText none',
+            AI.calStepsText({ valid: false, rawOpen: 0, rawGnd: 0 }),
+            'no points'
+        );
+        check(
+            'describeCalSource eeprom + mirror',
+            AI.describeCalSource(rec),
+            'stored in EEPROM · SD mirror ok · 12-bit'
+        );
+        check(
+            'describeCalSource none',
+            AI.describeCalSource({ source: 'none', adcBits: 12 }),
+            'no record (nominal scale) · 12-bit'
+        );
+        const rows = AI.calTableRows(rec, { raw1: 1900, raw2: 2047 });
+        check('calTableRows count', rows.length, 2);
+        approx('calTableRows ch1 mV cal', rows[0].mvCal, (10000 / 3600) * (1900 - 100), 1e-6);
+        approx('calTableRows ch1 mV nominal', rows[0].mvNominal, (1900 / 4095 - 0.5) * 20000, 1e-6);
+        check('calTableRows ch2 no line', String([rows[1].a, rows[1].mvCal]), String([null, null]));
+        check('calTableRows without raws', AI.calTableRows(rec, null)[0].rawNow, null);
+    }
+
     check('drawStripChart without a canvas → false', AI.drawStripChart(null, []), false);
     check('drawStripChart with a non-canvas → false', AI.drawStripChart({}, []), false);
 
@@ -350,6 +396,44 @@ async function main() {
     );
     checkBool('footer bumped past v0.71', !/Arena Studio v0\.71 \|/.test(studioHtml), 'footer');
     checkBool('sweep restores the previous AO level', /\(restore\)/.test(studioHtml), 'restore');
+    console.log('=== calibration wiring (S2) ===');
+    for (const id of ['cAiCalCh', 'cAiDeadband', 'cAiCalSum', 'cAiCalTable', 'cAiCalTableRow'])
+        checkBool(`panel element #${id}`, new RegExp(`id="${id}"`).test(studioHtml), id);
+    for (const cmd of ['caicalread', 'caicalopen', 'caicalgnd', 'caicaldb', 'caicalclear']) {
+        checkBool(
+            `button data-cmd="${cmd}"`,
+            new RegExp(`data-cmd="${cmd}"`).test(studioHtml),
+            cmd
+        );
+        checkBool(`handler ${cmd}:`, new RegExp(`^\\s+${cmd}: `, 'm').test(studioHtml), cmd);
+    }
+    {
+        const start = studioHtml.indexOf('const SAFE_BLOCKED_CMDS = new Set([');
+        const body = studioHtml.slice(start, studioHtml.indexOf(']);', start));
+        for (const cmd of ['caicalopen', 'caicalgnd', 'caicaldb', 'caicalclear'])
+            checkBool(`safe mode blocks ${cmd}`, body.includes(`'${cmd}'`), 'SAFE_BLOCKED_CMDS');
+        checkBool(
+            'safe mode does NOT block the read',
+            !body.includes("'caicalread'"),
+            'read allowed'
+        );
+    }
+    checkBool(
+        'calibration gated on the ai_cal capability',
+        /Studio\.capabilities\.includes\('ai_cal'\)/.test(studioHtml),
+        'ai_cal gate'
+    );
+    checkBool(
+        'calibration actions logged to the run log',
+        /event: 'analog_cal'/.test(studioHtml),
+        'analog_cal event'
+    );
+    checkBool(
+        'clear asks for confirmation',
+        /Forget the selected channel/.test(studioHtml),
+        'confirm'
+    );
+    checkBool('footer at v0.75', /Arena Studio v0\.75 \|/.test(studioHtml), 'footer');
 
     console.log('\n=== Summary ===');
     console.log(`${total - failures} / ${total} checks passed`);

From 28b17f0b0c331f054ab8d4facfb2c7a666374b38 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Mon, 7 Sep 2026 17:43:13 -0400
Subject: [PATCH 2/3] =?UTF-8?q?wire/console:=20reassign=20calibration=20op?=
 =?UTF-8?q?codes=20to=20the=200xA=5F=20block=20layout=20=E2=80=94=200xA5?=
 =?UTF-8?q?=20get-analog-in-raw,=200xA6=20set-analog-cal,=200xA7=20get-ana?=
 =?UTF-8?q?log-cal=20(matches=20firmware=20feat/ai-calibration)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 arena_studio.html           | 14 +++++++-------
 js/arena-wire-g6.js         | 29 ++++++++++++++++-------------
 tests/test-arena-wire-g6.js | 20 ++++++++++----------
 3 files changed, 33 insertions(+), 30 deletions(-)

diff --git a/arena_studio.html b/arena_studio.html
index 4b3b8c93..16a9484c 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -2832,11 +2832,11 @@ <h2 id="modalTitle">Import error</h2>
           <div class="crow" id="cAiSweepRow" style="display:none"><table class="ai-table" id="cAiSweepTable"></table></div>
           <div class="crow"><span class="lbl" title="Per-board two-point calibration (needs ai_cal firmware): with nothing on the BNC the input reads the +10 V reference; with a BNC ground cap it reads 0 V. The controller samples each point (256 averaged reads), stores the record in its EEPROM, mirrors it to the SD card, and uses it for GET_ANALOG_IN and Mode 4.">calibrate</span>
             <label title="Which input to calibrate">channel <select id="cAiCalCh"><option value="1">Analog In 1</option><option value="2">Analog In 2</option></select></label>
-            <button class="pill" data-cmd="caicalread" title="GET_ANALOG_CAL 0xA6 + GET_ANALOG_IN_RAW 0xA7 — show the stored record for both channels and the live raw counts on both scales">Read</button>
-            <button class="pill" data-cmd="caicalopen" title="Step 1 — unplug the BNC so the input floats at the +10 V reference, then click: the controller averages 256 reads and stores them as the +10 V point (SET_ANALOG_CAL 0xA5 action 1)">1 · Sample +10 V (open)</button>
+            <button class="pill" data-cmd="caicalread" title="GET_ANALOG_CAL 0xA7 + GET_ANALOG_IN_RAW 0xA5 — show the stored record for both channels and the live raw counts on both scales">Read</button>
+            <button class="pill" data-cmd="caicalopen" title="Step 1 — unplug the BNC so the input floats at the +10 V reference, then click: the controller averages 256 reads and stores them as the +10 V point (SET_ANALOG_CAL 0xA6 action 1)">1 · Sample +10 V (open)</button>
             <button class="pill" data-cmd="caicalgnd" title="Step 2 — fit the BNC ground cap, then click: the controller averages 256 reads and stores them as the 0 V point (action 0); with both points the channel becomes calibrated">2 · Sample 0 V (ground cap)</button>
             <label title="Mode 4 zero band — inputs within this many mV of the calibrated 0 V give 0 frames/s, so a static input does not creep the pattern (0–2000 mV)">deadband <input id="cAiDeadband" type="number" min="0" max="2000" step="1" value="20" style="width:56px"> mV</label>
-            <button class="pill" data-cmd="caicaldb" title="Store the deadband for the selected channel (SET_ANALOG_CAL 0xA5 action 2)">Set</button>
+            <button class="pill" data-cmd="caicaldb" title="Store the deadband for the selected channel (SET_ANALOG_CAL 0xA6 action 2)">Set</button>
             <button class="pill led-off" data-cmd="caicalclear" title="Forget the selected channel's two points — back to the nominal ±10 V scale (the deadband is kept)">Clear</button>
             <span class="dim" id="cAiCalSum" title="Where the record lives and its state"></span></div>
           <div class="crow" id="cAiCalTableRow" style="display:none"><table class="ai-table" id="cAiCalTable"></table></div>
@@ -5200,10 +5200,10 @@ <h2 id="modalTitle">Import error</h2>
             const sum = $('cAiCalSum'); if (sum) sum.textContent = 'needs ai_cal firmware';
             return null;
         }
-        const r1 = await send(Wire.encodeGetAnalogCal(), 'GET_ANALOG_CAL 0xA6');
+        const r1 = await send(Wire.encodeGetAnalogCal(), 'GET_ANALOG_CAL 0xA7');
         const rec = r1 && Wire.decodeAnalogCal(r1);
         if (!rec) { clog('analog cal: bad GET_ANALOG_CAL reply', 'err'); return null; }
-        const r2 = await send(Wire.encodeGetAnalogInRaw(), 'GET_ANALOG_IN_RAW 0xA7');
+        const r2 = await send(Wire.encodeGetAnalogInRaw(), 'GET_ANALOG_IN_RAW 0xA5');
         const raws = r2 && Wire.decodeAnalogInRaw(r2);
         aiCalRenderTable(rec, raws);
         return rec;
@@ -5215,7 +5215,7 @@ <h2 id="modalTitle">Import error</h2>
         let bytes;
         try { bytes = Wire.encodeSetAnalogCal(ch, action, mv); }
         catch (e) { clog('analog cal: ' + (e.message || e), 'err'); return; }
-        const label = 'SET_ANALOG_CAL 0xA5 ch ' + ch + ' ' + action + (action === 'setDeadband' ? ' ' + mv + ' mV' : '');
+        const label = 'SET_ANALOG_CAL 0xA6 ch ' + ch + ' ' + action + (action === 'setDeadband' ? ' ' + mv + ' mV' : '');
         const resp = await send(bytes, label);
         const rec = resp && Wire.decodeAnalogCal(resp);
         if (!rec) return;
@@ -5226,7 +5226,7 @@ <h2 id="modalTitle">Import error</h2>
         if (action === 'sampleOpen' && c.rawOpen < 3000) clog('analog cal: the +10 V point reads low (' + c.rawOpen + ' counts) — is the BNC really open? On a board without the LAB-209 rework both points saturate and the channel stays invalid', 'warn');
         const bridge = Studio.session && Studio.session.bridge;
         if (bridge && bridge.log) bridge.log({ event: 'analog_cal', channel: ch, action: action, deadband_mv: mv, record: rec });
-        const r2 = await send(Wire.encodeGetAnalogInRaw(), 'GET_ANALOG_IN_RAW 0xA7');
+        const r2 = await send(Wire.encodeGetAnalogInRaw(), 'GET_ANALOG_IN_RAW 0xA5');
         aiCalRenderTable(rec, r2 && Wire.decodeAnalogInRaw(r2));
         aiUser.lastFlags = undefined; // force the flags text to refresh on the next sample
         if (aiPoller) aiPoller.tick();
diff --git a/js/arena-wire-g6.js b/js/arena-wire-g6.js
index 08fa3dbb..c96302d5 100644
--- a/js/arena-wire-g6.js
+++ b/js/arena-wire-g6.js
@@ -70,9 +70,12 @@ const ArenaWireG6 = (function () {
         GET_AO_VOLTAGE: 0xa1, // [01 A1] returns last commanded AO level as uint16 LE mV
         SET_AO_MODE: 0xa3, // [02 A3 mode] 0=programmable | 1=frame_number (io_ext fw)
         GET_ANALOG_IN: 0xa4, // [01 A4] returns Analog In 1+2 as two int16 LE mV (+ flags byte, F1 fw)
-        SET_ANALOG_CAL: 0xa5, // [len A5 ch action (mv_lo mv_hi)] two-point calibration / deadband / clear (ai_cal fw)
-        GET_ANALOG_CAL: 0xa6, // [01 A6] → 18-byte calibration record (ai_cal fw)
-        GET_ANALOG_IN_RAW: 0xa7, // [01 A7] → raw ADC counts of both inputs, two uint16 LE (ai_cal fw)
+        // 0xA_ block: A0–A3 analog OUT, A4–A9 analog IN (A8/A9 reserved for the
+        // sampled block stream), AA–AF digital; set/get pairs on adjacent even/odd
+        // opcodes. G4 never used 0xA0–0xAF (g6_03 § G4 opcode compatibility).
+        GET_ANALOG_IN_RAW: 0xa5, // [01 A5] → raw ADC counts of both inputs, two uint16 LE (ai_cal fw)
+        SET_ANALOG_CAL: 0xa6, // [len A6 ch action (mv_lo mv_hi)] two-point calibration / deadband / clear (ai_cal fw)
+        GET_ANALOG_CAL: 0xa7, // [01 A7] → 18-byte calibration record (ai_cal fw)
         SET_DIGITAL_OUT: 0xaa, // [03 AA ch state] DO1 (ch=1, J3/D37) or DO2 (ch=2, J4/D35)
         GET_DIGITAL_OUT: 0xab, // [01 AB] returns current state of DO1 and DO2 as two bytes
         SET_DIO_ROLE: 0xac, // [03 AC port role] "Digital IO 1/2 (5V)" role (io_ext fw)
@@ -119,12 +122,12 @@ const ArenaWireG6 = (function () {
         // 0xAD / SET_AO_MODE 0xA3 / GET_ANALOG_IN 0xA4 — hosts detect the
         // DIO-role machinery by this bit, not by firmware-version guessing.
         [5, 'io_ext'],
-        // Per-board analog-input calibration (analog-input-plan F2): SET_ANALOG_CAL
-        // 0xA5 / GET_ANALOG_CAL 0xA6 / GET_ANALOG_IN_RAW 0xA7, record in EEPROM.
+        // Per-board analog-input calibration (analog-input-plan F2): GET_ANALOG_IN_RAW
+        // 0xA5 / SET_ANALOG_CAL 0xA6 / GET_ANALOG_CAL 0xA7, record in EEPROM.
         [6, 'ai_cal']
     ];
 
-    // SET_ANALOG_CAL (0xA5) actions — the host orchestrates Will's two-point
+    // SET_ANALOG_CAL (0xA6) actions — the host orchestrates Will's two-point
     // recipe (open input = +10 V from the reference, BNC ground cap = 0 V); the
     // controller samples, validates, stores (EEPROM + SD mirror) and applies.
     const ANALOG_CAL_ACTIONS = { sampleGround: 0, sampleOpen: 1, setDeadband: 2, clear: 0xff };
@@ -617,7 +620,7 @@ const ArenaWireG6 = (function () {
     }
 
     /**
-     * set-analog-cal (0xA5) — one calibration action on channel 1|2:
+     * set-analog-cal (0xA6) — one calibration action on channel 1|2:
      * 'sampleGround' (0 V point, ground cap on), 'sampleOpen' (+10 V point, BNC
      * open), 'setDeadband' (needs mv 0..2000), 'clear'. Names or codes accepted.
      */
@@ -640,15 +643,15 @@ const ArenaWireG6 = (function () {
                     'deadband must be 0..' + ANALOG_CAL_DEADBAND_MAX_MV + ' mV, got ' + mv
                 );
             }
-            return frame(OPCODES.SET_ANALOG_CAL, [ch, code, mv & 0xff, (mv >> 8) & 0xff]); // 05 A5 ch 02 lo hi
+            return frame(OPCODES.SET_ANALOG_CAL, [ch, code, mv & 0xff, (mv >> 8) & 0xff]); // 05 A6 ch 02 lo hi
         }
-        return frame(OPCODES.SET_ANALOG_CAL, [ch, code]); // 03 A5 ch action
+        return frame(OPCODES.SET_ANALOG_CAL, [ch, code]); // 03 A6 ch action
     }
     function encodeGetAnalogCal() {
-        return frame(OPCODES.GET_ANALOG_CAL); // 01 A6
+        return frame(OPCODES.GET_ANALOG_CAL); // 01 A7
     }
     function encodeGetAnalogInRaw() {
-        return frame(OPCODES.GET_ANALOG_IN_RAW); // 01 A7
+        return frame(OPCODES.GET_ANALOG_IN_RAW); // 01 A5
     }
 
     // ───────────────────────────── decoders ───────────────────────────────
@@ -835,7 +838,7 @@ const ArenaWireG6 = (function () {
     }
 
     /**
-     * get/set-analog-cal (0xA6 / 0xA5) reply: [version adc_bits source flags] then per
+     * get/set-analog-cal (0xA7 / 0xA6) reply: [version adc_bits source flags] then per
      * channel [valid][raw_open u16 LE][raw_gnd u16 LE][deadband_mv u16 LE] (18 B).
      * Adds the line each valid channel implies: mV = a·raw + b with
      * a = 10000 / (raw_open − raw_gnd), b = −a·raw_gnd (null when not valid).
@@ -873,7 +876,7 @@ const ArenaWireG6 = (function () {
             channels
         };
     }
-    // get-analog-in-raw (0xA7) reply: two uint16 LE ADC counts.
+    // get-analog-in-raw (0xA5) reply: two uint16 LE ADC counts.
     function decodeAnalogInRaw(resp) {
         const r = asResponse(resp);
         if (!r || !r.ok || r.payload.length < 4) return null;
diff --git a/tests/test-arena-wire-g6.js b/tests/test-arena-wire-g6.js
index 25a6b153..65545d44 100644
--- a/tests/test-arena-wire-g6.js
+++ b/tests/test-arena-wire-g6.js
@@ -118,25 +118,25 @@ checkThrows('ao mode 2 throws', () => Wire.encodeSetAoMode(2));
         Wire.decodeDioRole(Uint8Array.from([0x06, 0x01, 0xad, 0x02, 0x01, 0x01, 0x00])) === null
     );
 }
-// analog-input calibration (0xA5/0xA6/0xA7, ai_cal fw)
+// analog-input calibration (0xA5 raw / 0xA6 set-cal / 0xA7 get-cal, ai_cal fw)
 checkBytes(
     'encodeSetAnalogCal(1, sampleOpen)',
     Wire.encodeSetAnalogCal(1, 'sampleOpen'),
-    '03 a5 01 01'
+    '03 a6 01 01'
 );
 checkBytes(
     'encodeSetAnalogCal(2, sampleGround) numeric',
     Wire.encodeSetAnalogCal(2, 0),
-    '03 a5 02 00'
+    '03 a6 02 00'
 );
-checkBytes('encodeSetAnalogCal(1, clear)', Wire.encodeSetAnalogCal(1, 'clear'), '03 a5 01 ff');
+checkBytes('encodeSetAnalogCal(1, clear)', Wire.encodeSetAnalogCal(1, 'clear'), '03 a6 01 ff');
 checkBytes(
     'encodeSetAnalogCal(2, setDeadband, 300)',
     Wire.encodeSetAnalogCal(2, 'setDeadband', 300),
-    '05 a5 02 02 2c 01'
+    '05 a6 02 02 2c 01'
 );
-checkBytes('encodeGetAnalogCal', Wire.encodeGetAnalogCal(), '01 a6');
-checkBytes('encodeGetAnalogInRaw', Wire.encodeGetAnalogInRaw(), '01 a7');
+checkBytes('encodeGetAnalogCal', Wire.encodeGetAnalogCal(), '01 a7');
+checkBytes('encodeGetAnalogInRaw', Wire.encodeGetAnalogInRaw(), '01 a5');
 checkThrows('encodeSetAnalogCal rejects ch 3', () => Wire.encodeSetAnalogCal(3, 'clear'));
 checkThrows('encodeSetAnalogCal rejects unknown action', () => Wire.encodeSetAnalogCal(1, 'bogus'));
 checkThrows('encodeSetAnalogCal deadband > 2000 rejected', () =>
@@ -149,7 +149,7 @@ checkThrows('encodeSetAnalogCal deadband needs an integer', () =>
     // record: v1, 12-bit, source eeprom, mirror ok; ch1 valid open=3700 gnd=100 db=20; ch2 invalid db=50
     const rec = Wire.decodeAnalogCal(
         Uint8Array.from([
-            0x14, 0x00, 0xa6, 1, 12, 1, 1, 1, 0x74, 0x0e, 0x64, 0x00, 0x14, 0x00, 0, 0, 0, 0, 0,
+            0x14, 0x00, 0xa7, 1, 12, 1, 1, 1, 0x74, 0x0e, 0x64, 0x00, 0x14, 0x00, 0, 0, 0, 0, 0,
             0x32, 0x00
         ])
     );
@@ -177,10 +177,10 @@ checkThrows('encodeSetAnalogCal deadband needs an integer', () =>
     );
     check(
         'decodeAnalogCal short payload → null',
-        Wire.decodeAnalogCal(Uint8Array.from([0x05, 0x00, 0xa6, 1, 12, 1, 0])),
+        Wire.decodeAnalogCal(Uint8Array.from([0x05, 0x00, 0xa7, 1, 12, 1, 0])),
         null
     );
-    const raw = Wire.decodeAnalogInRaw(Uint8Array.from([0x06, 0x00, 0xa7, 0x74, 0x0e, 0x64, 0x00]));
+    const raw = Wire.decodeAnalogInRaw(Uint8Array.from([0x06, 0x00, 0xa5, 0x74, 0x0e, 0x64, 0x00]));
     check('decodeAnalogInRaw', String([raw.raw1, raw.raw2]), '3700,100');
 }
 checkBool(

From 846df075df116874d5a9c81e0c839aae685c9dc5 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Wed, 9 Sep 2026 09:43:45 -0400
Subject: [PATCH 3/3] feat(console analog cal): 2 s timeout on calibration
 commands; one calibration action at a time
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Codex review item 6: the calibration writes used the transport's 500 ms
default while the controller averages 256 reads (~10 ms) and writes EEPROM +
the SD mirror — a slow card would have tripped the timeout and left the UI
stale; use 2 s like the rig-I/O apply path. Repeated clicks queued further
EEPROM writes behind the first; a calibrating flag now refuses them with a note.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 arena_studio.html                             | 19 ++++++++++++++-----
 .../development/arena-studio-release-notes.md |  1 +
 2 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/arena_studio.html b/arena_studio.html
index 16a9484c..bbcef085 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -5022,7 +5022,7 @@ <h2 id="modalTitle">Import error</h2>
     // firmware, user pause, a run in progress, or a sweep in flight.
     const AI = window.StudioAnalogIn;
     const aiMon = AI ? AI.createMonitor({ windowMs: 30000 }) : null;
-    const aiUser = { enabled: true, sweeping: false, lastSweep: null, lastFlags: undefined };
+    const aiUser = { enabled: true, sweeping: false, calibrating: false, lastSweep: null, lastFlags: undefined };
     function aiPanelOpen() {
         const p = document.querySelector('.panel[data-panel="ai"]');
         return !!(p && p.classList.contains('open'));
@@ -5200,15 +5200,22 @@ <h2 id="modalTitle">Import error</h2>
             const sum = $('cAiCalSum'); if (sum) sum.textContent = 'needs ai_cal firmware';
             return null;
         }
-        const r1 = await send(Wire.encodeGetAnalogCal(), 'GET_ANALOG_CAL 0xA7');
+        const r1 = await send(Wire.encodeGetAnalogCal(), 'GET_ANALOG_CAL 0xA7', { timeoutMs: 2000 });
         const rec = r1 && Wire.decodeAnalogCal(r1);
         if (!rec) { clog('analog cal: bad GET_ANALOG_CAL reply', 'err'); return null; }
-        const r2 = await send(Wire.encodeGetAnalogInRaw(), 'GET_ANALOG_IN_RAW 0xA5');
+        const r2 = await send(Wire.encodeGetAnalogInRaw(), 'GET_ANALOG_IN_RAW 0xA5', { timeoutMs: 2000 });
         const raws = r2 && Wire.decodeAnalogInRaw(r2);
         aiCalRenderTable(rec, raws);
         return rec;
     }
     async function aiCalAction(action, mv) {
+        // One calibration write at a time: the transport serialises bytes, but a
+        // double-click would queue a second EEPROM write behind the first.
+        if (aiUser.calibrating) { clog('analog cal: the previous calibration action is still in progress — wait for it', 'warn'); return; }
+        aiUser.calibrating = true;
+        try { await aiCalActionInner(action, mv); } finally { aiUser.calibrating = false; }
+    }
+    async function aiCalActionInner(action, mv) {
         if (!session || !session.connected) { clog('analog cal: not connected', 'err'); return; }
         if (!aiHasCal()) { clog('analog cal: controller lacks ai_cal (0xC2 bit 6) — needs firmware feat/ai-calibration or later', 'warn'); return; }
         const ch = Number(($('cAiCalCh') || {}).value) === 2 ? 2 : 1;
@@ -5216,7 +5223,9 @@ <h2 id="modalTitle">Import error</h2>
         try { bytes = Wire.encodeSetAnalogCal(ch, action, mv); }
         catch (e) { clog('analog cal: ' + (e.message || e), 'err'); return; }
         const label = 'SET_ANALOG_CAL 0xA6 ch ' + ch + ' ' + action + (action === 'setDeadband' ? ' ' + mv + ' mV' : '');
-        const resp = await send(bytes, label);
+        // 2 s: the controller averages 256 reads (~10 ms), writes EEPROM and the SD
+        // mirror — a slow card must not trip the 500 ms default and leave the UI stale.
+        const resp = await send(bytes, label, { timeoutMs: 2000 });
         const rec = resp && Wire.decodeAnalogCal(resp);
         if (!rec) return;
         const c = rec.channels[ch - 1];
@@ -5226,7 +5235,7 @@ <h2 id="modalTitle">Import error</h2>
         if (action === 'sampleOpen' && c.rawOpen < 3000) clog('analog cal: the +10 V point reads low (' + c.rawOpen + ' counts) — is the BNC really open? On a board without the LAB-209 rework both points saturate and the channel stays invalid', 'warn');
         const bridge = Studio.session && Studio.session.bridge;
         if (bridge && bridge.log) bridge.log({ event: 'analog_cal', channel: ch, action: action, deadband_mv: mv, record: rec });
-        const r2 = await send(Wire.encodeGetAnalogInRaw(), 'GET_ANALOG_IN_RAW 0xA5');
+        const r2 = await send(Wire.encodeGetAnalogInRaw(), 'GET_ANALOG_IN_RAW 0xA5', { timeoutMs: 2000 });
         aiCalRenderTable(rec, r2 && Wire.decodeAnalogInRaw(r2));
         aiUser.lastFlags = undefined; // force the flags text to refresh on the next sample
         if (aiPoller) aiPoller.tick();
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index ecea170b..147e6a99 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -14,6 +14,7 @@ history lives here. Newest first. (Per-session engineering detail stays in
   the stored record with the live raw counts on both scales; Clear returns a channel to
   the nominal scale; a **deadband** (default 20 mV) stops a static input from creeping
   the pattern in Mode 4. Writes are advanced-mode only and are recorded in the run log.
+- Calibration commands use a 2 s timeout (the controller averages 256 reads and writes EEPROM + the SD mirror) and only one calibration action runs at a time (a second click while one is in flight is refused with a note).
 
 ## v0.74 (2026-09-07) · Console "Analog In" panel — live readout + loopback self-test