charging-dashboard: self-updating Slack TUI from Pecan accumulator

Adds a charging dashboard that posts one self-updating Slack message
(post once, chat.update every 5s, like the file-uploader) while charging
the accumulator via the Kvaser bridge on the internal (pecan-dev) build.

Bot (server/installer/slackbot):
- charge_dashboard.py: TUI renderer (SoC bar, pack/cell/temp/alert lines,
  per-module sparkline + stats), per-session manager, stdlib HTTP receiver
  (POST /charging/state behind CF Zero Trust + shared-token auth), heartbeat
  staleness.
- soc_model.py: data-derived SOC/ETA from the wfr26 audit. PackCurrent/BMS
  SOC are dead sentinels and PackVoltage is absent, so SOC is an OCV->SOC
  lookup on the limiting cell and ETA integrates a CV taper; phase is from
  the voltage trend.
- Wired into slack_bot.py __main__; compose port/env; Dockerfile.
- unittests: 17 (renderer, formatters, session updates, HTTP auth, model).

Pecan:
- chargingSnapshot.ts: pure, mockable snapshot builder mirroring the
  accumulator page; sentinel-guards the dead signals; derives pack voltage
  from the series-cell sum.
- useChargingDashboard.ts: 5s poster, gated on VITE_INTERNAL + live Kvaser
  source (:9081). Never broadcasts the demo relay or replay data.
- vitest: 15 (aggregation, alert chips, dead-signal guards, broadcast gate).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: wfr-data-acquisition

pecan/src/lib/chargingSnapshot.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from 'vitest';
+import {
+  buildChargingSnapshot,
+  chipHigh,
+  chipLow,
+  type SignalReader,
+} from './chargingSnapshot';
+import {
+  MODULE_IDS,
+  CELLS_PER_MODULE,
+  getCellSignalInfo,
+  getThermistorSignalInfo,
+  type ModuleId,
+} from '../components/accumulator/AccumulatorTypes';
+
+interface ReaderOpts {
+  current?: number;
+  soc?: number;
+  packV?: number;
+  cells?: Partial<Record<ModuleId, number[]>>;
+  temps?: Partial<Record<ModuleId, number[]>>;
+}
+
+function makeReader(opts: ReaderOpts): SignalReader {
+  const map = new Map<string, number>();
+  const put = (msgId: string, sig: string, v: number) => map.set(`${msgId}::${sig}`, v);
+
+  if (opts.current !== undefined) put('512', 'PackCurrent', opts.current);
+  if (opts.soc !== undefined) put('512', 'StateOfCharge', opts.soc);
+  if (opts.packV !== undefined) put('512', 'PackVoltage', opts.packV);
+
+  for (const id of MODULE_IDS) {
+    (opts.cells?.[id] ?? []).forEach((v, idx) => {
+      const { msgId, signalName } = getCellSignalInfo(id, idx + 1);
+      put(msgId, signalName, v);
+    });
+    (opts.temps?.[id] ?? []).forEach((t, idx) => {
+      const { msgId, signalName } = getThermistorSignalInfo(id, idx + 1);
+      put(msgId, signalName, t);
+    });
+  }
+
+  return {
+    getSignal(msgID, signalName) {
+      const v = map.get(`${msgID}::${signalName}`);
+      return v === undefined ? undefined : { sensorReading: v };
+    },
+  };
+}
+
+const flat = (v: number) => Array(CELLS_PER_MODULE).fill(v);
+
+describe('chipHigh / chipLow', () => {
+  it('chipHigh escalates with value', () => {
+    expect(chipHigh(null, 0.1, 0.2)).toBe('ok');
+    expect(chipHigh(0.05, 0.1, 0.2)).toBe('ok');
+    expect(chipHigh(0.1, 0.1, 0.2)).toBe('warn');
+    expect(chipHigh(0.25, 0.1, 0.2)).toBe('crit');
+  });
+  it('chipLow escalates as value drops', () => {
+    expect(chipLow(null, 3.2, 3.0)).toBe('ok');
+    expect(chipLow(3.5, 3.2, 3.0)).toBe('ok');
+    expect(chipLow(3.2, 3.2, 3.0)).toBe('warn');
+    expect(chipLow(2.9, 3.2, 3.0)).toBe('crit');
+  });
+});
+
+describe('buildChargingSnapshot — aggregation', () => {
+  const cells: Partial<Record<ModuleId, number[]>> = {
+    M1: flat(3.85),
+    M2: (() => {
+      const a = flat(3.84);
+      a[0] = 3.99; // global max cell → M2·C1
+      return a;
+    })(),
+    M3: (() => {
+      const a = flat(3.83);
+      a[9] = 3.65; // global min cell → M3·C10
+      return a;
+    })(),
+    M4: flat(3.86),
+    M5: flat(3.86),
+  };
+  const temps: Partial<Record<ModuleId, number[]>> = {
+    M1: [30, 31],
+    M4: [56], // critical temp → M4·T1
+  };
+
+  const reader = makeReader({ current: -12.4, soc: 67, cells, temps });
+  const snap = buildChargingSnapshot(reader, { session: 's1', startMs: 1_000, now: 61_000 });
+
+  it('reports five modules with correct per-module stats', () => {
+    expect(snap.modules.map((m) => m.id)).toEqual([...MODULE_IDS]);
+    const m3 = snap.modules.find((m) => m.id === 'M3')!;
+    expect(m3.min).toBeCloseTo(3.65, 5);
+    expect(m3.max).toBeCloseTo(3.83, 5);
+    expect(m3.delta_mv).toBe(180);
+    const m1 = snap.modules.find((m) => m.id === 'M1')!;
+    expect(m1.delta_mv).toBe(0);
+    expect(m1.avg).toBeCloseTo(3.85, 5);
+  });
+
+  it('finds pack-wide min/max cells with labels', () => {
+    expect(snap.min_cell).toEqual({ v: 3.65, label: 'M3·C10' });
+    expect(snap.max_cell).toEqual({ v: 3.99, label: 'M2·C1' });
+    expect(snap.delta_mv).toBe(340); // (3.99 - 3.65) * 1000
+  });
+
+  it('derives pack voltage as the series-cell sum (no PackVoltage signal)', () => {
+    const expected =
+      3.85 * 20 + (3.84 * 19 + 3.99) + (3.83 * 19 + 3.65) + 3.86 * 20 + 3.86 * 20;
+    expect(snap.pack_v).toBeCloseTo(expected, 3);
+  });
+
+  it('maps temps and alert chips', () => {
+    expect(snap.max_temp).toEqual({ c: 56, label: 'M4·T1' });
+    expect(snap.min_temp.c).toBe(30);
+    expect(snap.alerts.voltdelta).toBe('crit'); // 0.34 V ≥ 0.2
+    expect(snap.alerts.temp).toBe('crit'); // 56 ≥ 55
+    expect(snap.alerts.low).toBe('ok'); // 3.65 > 3.2
+  });
+
+  it('computes elapsed seconds and passes through valid current/soc', () => {
+    expect(snap.elapsed_s).toBe(60);
+    expect(snap.current_a).toBe(-12.4);
+    expect(snap.soc).toBe(67);
+    expect(snap.state).toBe('charging');
+  });
+});
+
+describe('buildChargingSnapshot — dead-signal guards', () => {
+  it('nulls the dead PackCurrent sentinel and the dead 0 SOC', () => {
+    const reader = makeReader({ current: -3276, soc: 0, cells: { M1: flat(3.8) } });
+    const snap = buildChargingSnapshot(reader, { session: 's', startMs: 0 });
+    expect(snap.current_a).toBeNull();
+    expect(snap.soc).toBeNull();
+    expect(snap.state).toBe('standby'); // unknown current → not charging/discharging
+    expect(snap.pack_v).toBeCloseTo(3.8 * 20, 5); // still derived from cells
+  });
+
+  it('classifies discharging when current is positive and valid', () => {
+    const reader = makeReader({ current: 12, cells: { M1: flat(3.8) } });
+    const snap = buildChargingSnapshot(reader, { session: 's', startMs: 0 });
+    expect(snap.state).toBe('discharging');
+  });
+});

pecan/src/lib/chargingSnapshot.ts

@@ -0,0 +1,205 @@
+/**
+ * Charging snapshot builder
+ *
+ * Pure functions that read the current accumulator state and produce the JSON
+ * snapshot POSTed to the slackbot charging dashboard. Mirrors the data shown on
+ * the Accumulator page (MasterAlertPanel pack stats + per-module ModuleStats).
+ *
+ * Kept dependency-injectable (`SignalReader`) so it is unit-testable without the
+ * live DataStore.
+ */
+
+import {
+  MODULE_IDS,
+  CELLS_PER_MODULE,
+  THERMISTORS_PER_MODULE,
+  ALERT_THRESHOLDS,
+  getCellSignalInfo,
+  getThermistorSignalInfo,
+  type ModuleId,
+} from '../components/accumulator/AccumulatorTypes';
+
+/** Minimal surface of DataStore needed here — easy to mock in tests. */
+export interface SignalReader {
+  getSignal(msgID: string, signalName: string): { sensorReading: number } | undefined;
+}
+
+const BMS_STATUS_ID = '512';
+const CHARGING_THRESHOLD = -0.5; // A — negative current = charging (per BatteryStatus.tsx)
+const DISCHARGING_THRESHOLD = 0.5; // A
+
+// Telemetry reality (wfr26 audit): PackCurrent reads a dead -3276 sentinel, BMS SOC
+// reads constant 0, and there is no PackVoltage signal. We sentinel-guard those so a
+// dead value is sent as null (the slackbot's soc_model derives SOC/phase from cell
+// voltages instead), and we derive pack voltage from the series-cell sum.
+const PLAUSIBLE_CURRENT_A = 1000; // |PackCurrent| beyond this ⇒ treat as invalid/dead
+
+export type AlertChip = 'ok' | 'warn' | 'crit';
+export type ChargeState = 'charging' | 'discharging' | 'standby';
+
+export interface ModuleSnapshot {
+  id: ModuleId;
+  cells: (number | null)[];
+  avg: number | null;
+  min: number | null;
+  max: number | null;
+  delta_mv: number | null;
+  tmax: number | null;
+}
+
+export interface ChargingSnapshot {
+  session: string;
+  state: ChargeState;
+  elapsed_s: number;
+  soc: number | null;
+  pack_v: number | null;
+  current_a: number | null;
+  avg_v: number | null;
+  delta_mv: number | null;
+  min_cell: { v: number; label: string } | null;
+  max_cell: { v: number; label: string } | null;
+  max_temp: { c: number; label: string } | null;
+  min_temp: { c: number | null };
+  alerts: { voltdelta: AlertChip; temp: AlertChip; bal: AlertChip; low: AlertChip };
+  modules: ModuleSnapshot[];
+  source: string;
+  env: string;
+}
+
+function read(reader: SignalReader, msgID: string, name: string): number | null {
+  const s = reader.getSignal(msgID, name);
+  return s ? s.sensorReading : null;
+}
+
+function avg(xs: number[]): number | null {
+  return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : null;
+}
+
+export interface BuildOptions {
+  session: string;
+  startMs: number;
+  now?: number;
+  source?: string;
+  env?: string;
+}
+
+export function buildChargingSnapshot(reader: SignalReader, opts: BuildOptions): ChargingSnapshot {
+  const now = opts.now ?? Date.now();
+
+  const rawCurrent = read(reader, BMS_STATUS_ID, 'PackCurrent');
+  const current = rawCurrent !== null && Math.abs(rawCurrent) <= PLAUSIBLE_CURRENT_A ? rawCurrent : null;
+  const rawSoc = read(reader, BMS_STATUS_ID, 'StateOfCharge') ?? read(reader, BMS_STATUS_ID, 'SOC');
+  const soc = rawSoc !== null && rawSoc > 0 && rawSoc <= 100 ? rawSoc : null;
+
+  // Pack-wide extremes (with cell/thermistor labels), per-module aggregates.
+  let minCell: { v: number; label: string } | null = null;
+  let maxCell: { v: number; label: string } | null = null;
+  let maxTemp: { c: number; label: string } | null = null;
+  let minTemp: number | null = null;
+  const allCellValues: number[] = [];
+  const moduleAvgs: number[] = [];
+
+  const modules: ModuleSnapshot[] = MODULE_IDS.map((id) => {
+    const cells: (number | null)[] = [];
+    const cellValues: number[] = [];
+    for (let i = 1; i <= CELLS_PER_MODULE; i++) {
+      const { msgId, signalName } = getCellSignalInfo(id, i);
+      const v = read(reader, msgId, signalName);
+      cells.push(v);
+      if (v !== null) {
+        cellValues.push(v);
+        allCellValues.push(v);
+        const label = `${id}·C${i}`;
+        if (minCell === null || v < minCell.v) minCell = { v, label };
+        if (maxCell === null || v > maxCell.v) maxCell = { v, label };
+      }
+    }
+
+    let tmax: number | null = null;
+    for (let i = 1; i <= THERMISTORS_PER_MODULE; i++) {
+      const { msgId, signalName } = getThermistorSignalInfo(id, i);
+      const t = read(reader, msgId, signalName);
+      if (t !== null) {
+        const label = `${id}·T${i}`;
+        if (tmax === null || t > tmax) tmax = t;
+        if (maxTemp === null || t > maxTemp.c) maxTemp = { c: t, label };
+        if (minTemp === null || t < minTemp) minTemp = t;
+      }
+    }
+
+    const mAvg = avg(cellValues);
+    if (mAvg !== null) moduleAvgs.push(mAvg);
+    const mMin = cellValues.length ? Math.min(...cellValues) : null;
+    const mMax = cellValues.length ? Math.max(...cellValues) : null;
+    return {
+      id,
+      cells,
+      avg: mAvg,
+      min: mMin,
+      max: mMax,
+      delta_mv: mMin !== null && mMax !== null ? Math.round((mMax - mMin) * 1000) : null,
+      tmax,
+    };
+  });
+
+  // PackVoltage signal is absent in telemetry → derive the stack voltage as the sum
+  // of the (series) cell voltages. Prefer a real PackVoltage signal if one ever appears.
+  const rawPackV = read(reader, BMS_STATUS_ID, 'PackVoltage');
+  const packV =
+    rawPackV !== null && rawPackV > 0
+      ? rawPackV
+      : allCellValues.length
+        ? allCellValues.reduce((a, b) => a + b, 0)
+        : null;
+
+  const packDelta =
+    minCell !== null && maxCell !== null ? (maxCell as { v: number }).v - (minCell as { v: number }).v : null;
+  const imbalance =
+    moduleAvgs.length > 1 ? Math.max(...moduleAvgs) - Math.min(...moduleAvgs) : null;
+
+  let state: ChargeState = 'standby';
+  if (current !== null) {
+    if (current < CHARGING_THRESHOLD) state = 'charging';
+    else if (current > DISCHARGING_THRESHOLD) state = 'discharging';
+  }
+
+  return {
+    session: opts.session,
+    state,
+    elapsed_s: Math.max(0, Math.round((now - opts.startMs) / 1000)),
+    soc,
+    pack_v: packV,
+    current_a: current,
+    avg_v: avg(allCellValues),
+    delta_mv: packDelta !== null ? Math.round(packDelta * 1000) : null,
+    min_cell: minCell,
+    max_cell: maxCell,
+    max_temp: maxTemp,
+    min_temp: { c: minTemp },
+    alerts: {
+      voltdelta: chipHigh(packDelta, ALERT_THRESHOLDS.voltageDiff.warning, ALERT_THRESHOLDS.voltageDiff.critical),
+      temp: chipHigh(maxTemp ? (maxTemp as { c: number }).c : null, ALERT_THRESHOLDS.overTemp.warning, ALERT_THRESHOLDS.overTemp.critical),
+      bal: chipHigh(imbalance, ALERT_THRESHOLDS.moduleImbalance.warning, ALERT_THRESHOLDS.moduleImbalance.critical),
+      low: chipLow(minCell ? (minCell as { v: number }).v : null, ALERT_THRESHOLDS.lowVoltage.warning, ALERT_THRESHOLDS.lowVoltage.critical),
+    },
+    modules,
+    source: opts.source ?? 'kvaser-bridge',
+    env: opts.env ?? 'pecan-dev',
+  };
+}
+
+/** Higher value = worse (delta, temp, imbalance). */
+export function chipHigh(value: number | null, warn: number, crit: number): AlertChip {
+  if (value === null) return 'ok';
+  if (value >= crit) return 'crit';
+  if (value >= warn) return 'warn';
+  return 'ok';
+}
+
+/** Lower value = worse (min cell voltage). */
+export function chipLow(value: number | null, warn: number, crit: number): AlertChip {
+  if (value === null) return 'ok';
+  if (value <= crit) return 'crit';
+  if (value <= warn) return 'warn';
+  return 'ok';
+}

pecan/src/lib/useChargingDashboard.test.ts

@@ -0,0 +1,40 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach } from 'vitest';
+import { isKvaserSource } from './useChargingDashboard';
+
+beforeEach(() => {
+  localStorage.clear();
+  sessionStorage.clear();
+});
+
+describe('isKvaserSource — broadcast gate', () => {
+  it('is true when connected to the Kvaser bridge (:9081)', () => {
+    sessionStorage.setItem('pecan-ws-last-ok', 'wss://localhost:9081');
+    expect(isKvaserSource()).toBe(true);
+  });
+
+  it('honours a configured custom bridge URL when nothing is connected yet', () => {
+    localStorage.setItem('custom-ws-url', 'ws://127.0.0.1:9081');
+    expect(isKvaserSource()).toBe(true);
+  });
+
+  it('NEVER broadcasts the public demo relay (fake/generated data)', () => {
+    sessionStorage.setItem('pecan-ws-last-ok', 'wss://ws-demo.westernformularacing.org');
+    expect(isKvaserSource()).toBe(false);
+  });
+
+  it('excludes the demo relay even if it is the configured custom URL', () => {
+    localStorage.setItem('custom-ws-url', 'wss://ws-demo.westernformularacing.org');
+    sessionStorage.setItem('pecan-ws-last-ok', 'wss://ws-demo.westernformularacing.org');
+    expect(isKvaserSource()).toBe(false);
+  });
+
+  it('does not broadcast the base-station bridge (:9080) or production', () => {
+    sessionStorage.setItem('pecan-ws-last-ok', 'ws://10.0.0.5:9080');
+    expect(isKvaserSource()).toBe(false);
+  });
+
+  it('is false with no source configured', () => {
+    expect(isKvaserSource()).toBe(false);
+  });
+});