fix(protocol): remove auto-detection of frame mode and ensure extra chunks are always used for valid waveform footer

Frame 0 is always the probe; frames 1+ are always data (waveform ADC
chunks, compliance config, compliance continuation).  Gating on
classify_frame() at fi>0 produces false positives: ADC binary data
can coincidentally contain b"STRT\xff\xfe", causing frames 1 and 5
to be silently dropped from the body (confirmed from live capture on
event key=01110000).  Remove all type-based filtering; include every
frame unconditionally with the standard index-based skip amounts.

.gitignore

@@ -0,0 +1,33 @@
+/bridges/captures/
+/example-events/
+
+/manuals/
+
+# Python build artifacts
+*.egg-info/
+dist/
+build/
+
+# Python bytecode
+__pycache__/
+*.py[cod]
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Editor / OS
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db
+
+# Analyzer outputs
+*.report
+claude_export_*.md
+
+# Frame database
+*.db
+*.db-wal
+*.db-shm

CHANGELOG.md

@@ -0,0 +1,532 @@
+# Changelog
+
+All notable changes to seismo-relay are documented here.
+
+---
+
+## v0.12.5 — 2026-04-21
+
+### Changed
+
+- **`s3_bridge.py` — raw captures always-on by default** — `--raw-bw` and `--raw-s3` now
+  default to `"auto"` instead of `None`. Every bridge session automatically generates
+  timestamped `raw_bw_<ts>.bin` and `raw_s3_<ts>.bin` files alongside the `.bin`/`.log`
+  session files. Pass `--raw-bw ""` (explicit empty string) to disable if needed.
+
+- **`gui_bridge.py` — raw capture checkboxes pre-checked** — Both "BW→S3 raw" and
+  "S3→BW raw" checkboxes start checked. Path fields are empty by default (bridge auto-names
+  the files). Unchecking a box passes `--raw-bw ""` to explicitly disable capture.
+
+- **`ach_server.py` — TX capture added (`raw_tx_<ts>.bin`)** — Every ACH inbound session
+  now saves both directions: `raw_rx_<ts>.bin` (device → us, S3 side, as before) and
+  `raw_tx_<ts>.bin` (us → device, BW side). Both files are usable in the Analyzer.
+  TX bytes are buffered in memory until startup handshake succeeds (same as RX), preventing
+  scanner probes from creating empty files.
+
+---
+
+## v0.12.4 — 2026-04-21 (protocol analysis / docs only — no code changes)
+
+### Discovered
+
+- **compliance_raw is wire-encoded, not logical bytes** — `read_compliance_config()` returns
+  bytes that include DLE prefix bytes (`0x10`) before any `0x03` values (because S3FrameParser
+  preserves DLE+ETX inner-frame pairs as two literal bytes). The previous CLAUDE.md claim that
+  "S3FrameParser handles this transparently so compliance_raw contains logical bytes" was wrong.
+
+- **anchor-9 behavior per recording mode** (confirmed from 4-20-26 BW write captures):
+  - Single Shot (0x00) / Continuous (0x01): anchor-9 = `0x00`
+  - Histogram (0x03): anchor-9 = `0x10` — the E5 DLE prefix for the `0x03` recording_mode byte
+  - Histogram+Continuous (0x04): anchor-9 = `0x10` — an actual stored config byte for this mode
+  Anchor position shifts by ±1 when recording_mode = `0x03` due to the extra DLE byte; the
+  dynamic anchor search (`buf.find(ANCHOR, 0, 150)`) handles this correctly without code changes.
+
+- **Write frame ETX escaping** — BW escapes `0x03` bytes in write frame data as `0x10 0x03`
+  on the wire. Our `build_bw_write_frame` sends data bytes raw without ETX escaping. Device
+  accepts our raw writes for all tested modes. Hypothesis: device write parser uses the
+  offset/length field for frame boundaries, not ETX scanning, making ETX escaping optional.
+  Histogram mode (recording_mode = 0x03) write via SFM from a non-Histogram starting state
+  not yet tested.
+
+- **BW write payload vs E5 read payload are byte-identical** around the anchor region (confirmed
+  by comparing 3-11-26 BW TX and S3 captures). BW does NOT strip DLE prefix bytes before writing;
+  it round-trips the wire-encoded bytes verbatim with only the modified fields changed.
+
+- **Capture folder content catalogued** — see CLAUDE.md "BW capture reference" table for a
+  summary of all available protocol captures and their contents.
+
+---
+
+## v0.12.3 — 2026-04-20
+
+### Added
+
+- **Auto Call Home config protocol** — Full read/write/decode/encode pipeline for the
+  device's Remote Access → Setup Unit ACH settings, confirmed from 4-20-26 call home
+  settings captures.
+
+  **Protocol (new):**
+  - `SUB 0x2C` — Call Home Config READ (response `0xD3`); two-step read; data offset
+    `0x7C` = 124; raw payload 125 bytes (1-byte longer than DATA_LENGTH due to DLE-escaped
+    `\x10\x03` at raw[117:119] representing num_retries = 3)
+  - `SUB 0x7E` — Call Home Config WRITE (response `0x81`); 127-byte payload (125-byte read
+    payload + `\x00\x00`); offset = `data[1]+2 = 0x7E`; write format (DLE-aware checksum)
+  - `SUB 0x7F` — Call Home WRITE CONFIRM (response `0x80`); no data
+
+  **Field map (confirmed from 10-frame BW TX diff):**
+  - `raw[5]` — auto_call_home_enabled (bool)
+  - `raw[6:46]` — dial_string (40-byte null-padded ASCII)
+  - `raw[87]` — after_event_recorded (bool)
+  - `raw[91]` — at_specified_times (bool)
+  - `raw[93]` — time1_enabled / `raw[101]` — time1_hour / `raw[102]` — time1_min
+  - `raw[95]` — time2_enabled / `raw[105]` — time2_hour / `raw[106]` — time2_min
+  - `raw[117:119]` — `\x10\x03` (DLE-escaped 0x03 = num_retries value 3)
+  - `raw[120]` — time_between_retries_sec / `raw[122]` — wait_for_connection_sec / `raw[124]` — warm_up_time_sec
+
+  **Library (`minimateplus/`):**
+  - `models.py` — `CallHomeConfig` dataclass (14 fields; `raw` bytes preserved for
+    round-trip writes)
+  - `protocol.py` — `SUB_CALL_HOME = 0x2C`, `SUB_CALL_HOME_WRITE = 0x7E`,
+    `SUB_CALL_HOME_CONFIRM = 0x7F`; `read_call_home_config()`, `write_call_home_config()`
+  - `client.py` — `get_call_home_config()`, `set_call_home_config()`,
+    `_decode_call_home_config()` (handles DLE prefix at raw[117]),
+    `_encode_call_home_config()` (patches in-place; raises `ValueError` if hour/min = 3)
+
+  **REST API (`sfm/server.py`):**
+  - `GET /device/call_home` — reads and decodes call home config from device
+  - `POST /device/call_home` — reads, patches specified fields, writes back to device
+  - `CallHomeConfigBody` Pydantic model with 9 optional writable fields
+
+  **Web UI (`sfm/sfm_webapp.html`):**
+  - New "Call Home" tab with enable flag, dial string (read-only), after-event trigger,
+    at-specified-times flag, two time slots (enable + HH:MM each), and read-only retry
+    settings (num_retries, time_between_retries_sec, wait_for_connection_sec,
+    warm_up_time_sec)
+  - "Read from Device", "Write to Device", "Clear Form" action buttons
+  - Client-side guard: rejects hour or minute value equal to 3 with a clear message
+    explaining the DLE-encoding limitation
+
+---
+
+## v0.12.2 — 2026-04-20
+
+### Added / Fixed
+
+- **Geophone sensitivity / maximum range field confirmed** — 4-20-26 geo sensitivity
+  captures (1.25 in/s vs 10 in/s) diffed across all three SUB 71 write chunks and both
+  E5 read payloads. The `geo_range` uint8 field per channel is now fully confirmed:
+  - E5 read offset: `channel_label + 33`; SUB 71 write offset: `channel_label + 29`
+  - `0x00` = Normal 10.000 in/s (standard gain); `0x01` = Sensitive 1.250 in/s (high gain)
+  - **Correction:** previous hypothesis (`channel_label+20`, `0x01`=Normal) was wrong.
+    `channel_label+20` reads `0x01` on ALL captures regardless of range — not this field.
+  - `_decode_compliance_config_into`: read offset corrected from `tran_pos+20` → `tran_pos+33`
+  - `_encode_compliance_config`: added `geo_range` parameter; writes to Tran/Vert/Long at `+29`
+  - `apply_config`: added `geo_range` parameter
+  - `POST /device/config`: added `geo_range` to `DeviceConfigBody`
+  - Web UI Config tab: added "Maximum Range — Geo" select (Normal / Sensitive)
+  - Web UI Device tab: added "Max Range (geo)" row to compliance table
+
+- **`recording_mode` + `histogram_interval_sec` confirmed and implemented** (4-20-26 captures)
+  - `recording_mode`: uint8 at anchor−8 (E5 read) / anchor−7 (write); enum: 0x00=Single Shot,
+    0x01=Continuous, 0x03=Histogram, 0x04=Histogram+Continuous
+  - `histogram_interval_sec`: uint16 BE seconds at anchor−4; same offset in read & write;
+    valid: 2, 5, 15, 60, 300, 900 (matching Blastware dropdown: 2s, 5s, 15s, 1m, 5m, 15m)
+  - Both fields added to `ComplianceConfig`, `_decode_compliance_config_into`,
+    `_encode_compliance_config`, `apply_config`, REST API body, and web UI
+
+---
+
+## v0.12.1 — 2026-04-16
+
+### Added
+
+- **`sfm/server.py` — `_LiveCache`** — in-memory live device cache that eliminates
+  redundant TCP round-trips between web requests.  Plain Python dict +
+  `threading.Lock`, no extra dependencies.
+
+  Cache strategy per endpoint:
+
+  | Endpoint | Strategy |
+  |---|---|
+  | `GET /device/info` | Indefinite; invalidated by `POST /device/config` |
+  | `GET /device/events` | Count-probe fast path — `poll()+count_events()` (~2 s); returns cached data if event count is unchanged; full download only when new events are detected |
+  | `GET /device/monitor/status` | 30-second TTL; invalidated immediately on monitor start/stop |
+  | `GET /device/event/{idx}/waveform` | Permanent per-index (waveforms are immutable once recorded) |
+
+- **`?force=true`** query param on all cached endpoints — bypasses cache and forces
+  a fresh read from the device.
+
+- **Cache invalidation hooks** — `POST /device/config` marks device info and events
+  stale; `POST /device/monitor/start` and `/stop` evict the monitor status entry
+  immediately so the next status poll reflects the actual device state.
+
+---
+
+## v0.12.0 — 2026-04-13
+
+### Added
+
+- **`sfm/server.py` — `_LiveCache`** — in-memory live device cache, eliminating
+  redundant TCP round-trips between requests.  No extra dependencies (plain Python
+  dict + threading.Lock).  Replaces the SQLAlchemy-based `sfm/cache.py` experiment
+  from the `feature/intelligent-caching` branch.
+
+  Cache behaviour by endpoint:
+
+  | Endpoint | Cache strategy |
+  |---|---|
+  | `GET /device/info` | Indefinite; invalidated by `POST /device/config` |
+  | `GET /device/events` | Count-probe fast path: quick `poll()+count_events()` (~2s); return cache if count matches; full download only when new events detected |
+  | `GET /device/monitor/status` | 30-second TTL; invalidated by monitor start/stop |
+  | `GET /device/event/{idx}/waveform` | Permanent per-index (waveforms are immutable) |
+
+- **`?force=true` param** on all four cached endpoints — bypasses cache and re-reads
+  from device.
+
+- **`POST /device/config` cache invalidation** — marks device info + events dirty so
+  the next read reflects the new compliance config.
+
+- **`POST /device/monitor/start` / `stop` cache invalidation** — evicts the monitor
+  status cache entry immediately so the next poll returns the updated state.
+
+### Removed
+
+- `sfm/cache.py` — SQLAlchemy-based cache from the experimental caching branch.
+  Its logic has been ported to the sqlite3-native `_LiveCache` class above.
+  `sqlalchemy` is no longer a dependency.
+
+---
+
+## v0.11.0 — 2026-04-13
+
+### Added
+
+- **`sfm/database.py` — SeismoDb** — SQLite persistence layer for all ACH data.
+  Three tables, all unit-keyed by serial number:
+  - `ach_sessions` — one row per inbound call-home: serial, timestamp, peer IP,
+    events_downloaded, monitor_entries, duration_seconds
+  - `events` — one row per triggered waveform event: serial, waveform_key (dedup),
+    timestamp, Tran/Vert/Long/VectorSum/Mic PPV, project/client/operator/sensor_location
+    strings, sample_rate, record_type, false_trigger flag
+  - `monitor_log` — one row per monitoring interval: serial, waveform_key (dedup),
+    start_time, stop_time, duration_seconds, geo_threshold_ips
+  - WAL mode, per-request connections — safe for the single-writer / occasional-reader
+    ACH server pattern
+  - Deduplication by `(serial, waveform_key)` UNIQUE constraint — re-runs and repeat
+    call-homes never produce duplicate rows
+
+- **`ach_server.py` — DB integration** — after each successful call-home, writes new
+  events and monitor log entries to `seismo_relay.db` then records the session in
+  `ach_sessions`.  DB write failures are logged as warnings and do not abort the session.
+
+- **`sfm/server.py` — DB read endpoints**:
+  - `GET /db/units` — distinct serials with last_seen, total_events, total_monitor_entries
+  - `GET /db/events` — query events with serial / date range / false_trigger filters
+  - `GET /db/monitor_log` — query monitoring intervals
+  - `GET /db/sessions` — query ACH call-home sessions
+  - `PATCH /db/events/{id}/false_trigger` — flag/unflag false triggers (for review UI)
+
+### Architecture
+
+- seismo-relay DB is unit-keyed only — no project concepts.  Project aggregation is
+  terra-view's responsibility via `UnitAssignment` / `DeploymentRecord` + date range
+  queries against the SFM DB endpoints.
+- DB file lives at `bridges/captures/seismo_relay.db` by default.
+
+---
+
+## v0.10.0 — 2026-04-11
+
+### Added
+
+- **`MiniMateClient.get_monitor_log_entries(skip_keys=None)`** — browse-mode walk
+  (`1E → 0A → 1F`) that collects partial records (`0x2C` record type) from the device's
+  event list without triggering a full waveform download (no 0C or 5A).  Returns
+  `list[MonitorLogEntry]`.  Each entry represents one continuous monitoring interval where
+  no threshold was exceeded.
+
+- **`_decode_0a_partial_header(raw_data, index, key4)`** in `client.py` — decodes a SUB
+  0x0A response payload whose record type is `0x2C`.  Extracts:
+  - `start_time` / `stop_time` — two consecutive timestamps; auto-detects 9-byte
+    (sub_code=0x10, single-shot) vs 10-byte (sub_code=0x03, continuous) format from
+    `raw_data[11]`.  Handles a 1-byte gap between the two timestamps that occurs when
+    ts1 and ts2 share the same minute:second.
+  - `serial` — device serial string found via `b"BE"` anchor scan.
+  - `geo_threshold_ips` — trigger level found via `b"Geo: "` anchor scan.
+
+- **`MonitorLogEntry` dataclass** in `models.py` — new model for partial records:
+  `index`, `key`, `start_time`, `stop_time`, `serial`, `geo_threshold_ips`,
+  `raw_header`, and a `duration_seconds` property.
+
+- **`read_waveform_header()` return value extended** — now returns `(data_rsp.data, length)`
+  (full payload) instead of `(data_rsp.data[11:11+length], length)`.  Callers get the
+  complete payload including the record-type byte at position 0.  Full records use
+  `raw_data[11:11+length]` as before; partial records are detected by `raw_data[0] == 0x2C`.
+
+- **ACH server: monitor log collection** — after `get_events()`, calls
+  `get_monitor_log_entries(skip_keys=seen_keys)` and saves new entries to
+  `monitor_log.json` in the session directory.  Monitor log keys are included in
+  `downloaded_keys` for state persistence (no re-processing on next call-home).
+
+- **`_monitor_log_entry_to_dict()`** in `ach_server.py` — serialises a `MonitorLogEntry`
+  to a JSON-compatible dict with ISO-format timestamps.
+
+### Protocol / Documentation
+
+- **SUB 0x0A partial record (0x2C) format confirmed** (✅ 4-11-26 MITM capture, 12 frames):
+  - Record type `0x2C` at `raw_data[0]`; length < 64 bytes.
+  - Two timestamps at `raw_data[11:]` — start and stop of the monitoring interval.
+  - ASCII metadata region after timestamps: `BE<serial>\x00Geo: <float> in/s`.
+  - Edge case: 1-byte separator between timestamps when ts1 and ts2 share minute:second.
+  - 10-byte timestamp format (sub_code=0x03) signalled by `raw_data[11] == 0x10`.
+
+- **Key reuse detection for monitor log entries** — monitor log keys are tracked alongside
+  event keys in `ach_state.json` so the ACH server does not re-process them after a
+  call-home cycle.
+
+---
+
+## v0.9.0 — 2026-04-11
+
+### Added
+
+- **`MiniMateClient.list_event_keys()`** — fast browse-mode walk (1E → 0A → 1F, no waveform
+  download) that returns the list of event key hex strings currently stored on the device.
+  Used by the ACH server as a cheap pre-check before deciding whether to call `get_events()`.
+
+- **`get_events(skip_waveform_for_keys=set(...))`** — new optional parameter.  For any key in
+  the set the function performs only 0A + 1F(browse) instead of the full
+  1E-arm → 0C → POLL×3 → 5A sequence.  Eliminates redundant waveform downloads on repeat
+  call-homes when the device still holds previously downloaded events.
+
+- **`MiniMateClient.delete_all_events()`** — erases all events from device memory using the
+  confirmed 4-step sequence:
+  - SUB 0xA3 `begin_erase_all` — initiate erase (token=0xFE) → ack 0x5C
+  - SUB 0x1C `read_monitor_status` — intermediate status read (Blastware-required)
+  - SUB 0x06 `read_event_storage_range` — verify storage state (token=0xFE) → 36-byte response
+  - SUB 0xA2 `confirm_erase_all` — commit erase (token=0xFE) → ack 0x5D
+
+  All four steps confirmed from 4-11-26 MITM capture of a live Blastware ACH session.
+  After a successful call, the device's event counter resets to `0x01110000`.
+
+- **`MiniMateProtocol` erase methods**: `begin_erase_all()`, `confirm_erase_all()`,
+  `read_event_storage_range()` added to `protocol.py` with documented SUB constants
+  `SUB_ERASE_ALL_BEGIN = 0xA3` and `SUB_ERASE_ALL_CONFIRM = 0xA2`.
+
+- **`bridges/ach_mitm.py`** — transparent TCP-to-TCP MITM proxy.  Listens for inbound unit
+  connections, connects upstream to a real Blastware ACH server, and saves both directions
+  to `raw_bw_<ts>.bin` / `raw_s3_<ts>.bin` files matching the existing capture format.
+  Used to capture the 4-11-26 Blastware ACH session including event deletion.
+  Usage: `python bridges/ach_mitm.py --bw-host 127.0.0.1 --bw-port 9999 --listen-port 9998`
+
+- **ACH server: key-based state tracking** — `ach_state.json` now stores
+  `downloaded_keys: [hex_strings]` and `max_downloaded_key: hex_string` per unit instead of
+  `event_count: N`.  This correctly handles the standard workflow where events are deleted
+  from the device after upload — a count-based approach would see `count=0` on the next
+  call-home and silently skip new events.
+
+- **ACH server: `--clear-after-download` flag** — after a successful download (at least one
+  new event saved), erases all events from the device using `delete_all_events()`.  Mirrors
+  the standard Blastware ACH workflow.  On success, `downloaded_keys` and
+  `max_downloaded_key` are reset to empty so the next session starts fresh.
+
+- **ACH server: post-erase key-reuse detection** — after an external erase (Blastware or
+  manual), device keys restart from `0x01110000`, colliding with previously downloaded keys.
+  On each browse walk, if `max(device_keys) < max_downloaded_key` (device counter rolled
+  back), all device keys are treated as new regardless of `seen_keys`.  This also catches
+  erases performed by Blastware between our sessions.
+
+### Protocol / Documentation
+
+- **SUB 0xA3 / SUB 0xA2 — erase-all sequence confirmed** (✅ 4-11-26 MITM capture):
+  Both frames use `token=0xFE` at `params[7]` and are standard `build_bw_frame` requests
+  (not write-format).  Response SUBs follow the standard formula: 0x5C and 0x5D.
+  The intermediate 0x1C + 0x06 reads between them are required by Blastware.
+
+- **SUB 0x06 — event storage range read confirmed** (✅ 4-11-26 MITM capture):
+  Two-step read, data offset = 0x24 (36 bytes).  The last 8 bytes of the response contain
+  the first and last stored event keys (4 bytes each).  After a successful erase, both keys
+  read as `01110000` (device-empty state).
+
+- **Event key counter resets to `0x01110000` after erase** — confirmed by observing key
+  `01110000` on the device immediately after the MITM erase session.
+
+---
+
+## v0.8.0 — 2026-04-07
+
+### Added
+
+- **Write pipeline end-to-end** — `push_config_raw(event_index_data, compliance_data,
+  trigger_data, waveform_data)` on `MiniMateClient` orchestrates the full
+  `68→73 | 71×3→72 | 82→83 | 69→74→72` write sequence.
+
+- **`build_bw_write_frame(sub, data, *, offset, params)`** in `framing.py` — dedicated frame
+  builder for write commands (SUBs 0x68–0x83).  Doubles only the BW_CMD byte; all other
+  bytes including offset, params, data, and checksum are written raw.  Uses the large-frame
+  DLE-aware checksum (`sum(b for b in payload[2:] if b != 0x10) + 0x10) & 0xFF`).
+
+- **`MiniMateProtocol` write methods** — `write_event_index()`, `write_compliance()`,
+  `write_trigger_config()`, `write_waveform_data()`, `write_confirm()`,
+  `start_monitoring()`, `stop_monitoring()`.
+
+- **`AchSession` inbound server** (`bridges/ach_server.py`) — accepts call-home TCP
+  connections, runs the full handshake + device-info + event-download sequence, saves
+  `device_info.json` + `events.json` per session.
+
+### Protocol / Documentation
+
+- **Write frame format confirmed** (✅ 3-11-26 BW TX capture, all 11 frames): only BW_CMD
+  byte `0x10` is doubled; all other bytes sent raw.  Standard `build_bw_frame` DLE-stuffing
+  is incorrect for write commands.
+- **Write ack responses** confirmed as 17-byte zero-data S3 frames.
+- **Monitoring SUBs 0x96/0x97** confirmed from 4-8-26 capture.
+- **SESSION_RESET signal** (`41 03`) required before POLL for monitoring units.
+- **SUB 0x1C monitoring flag** at `section[1]`: `0x00` = idle, `0x10` = monitoring.
+  Confirmed by byte-diff of all 144 data frames in 4-8-26/2ndtry capture.
+
+---
+
+## v0.7.0 — 2026-04-03
+
+### Added
+- **Raw ADC waveform decode — `_decode_a5_waveform(frames_data, event)`** in `client.py`.
+  Parses the complete set of SUB 5A A5 response frames into per-channel time-series:
+  - Reads the STRT record from A5[0] (bytes 7+): extracts `total_samples` (BE uint16 at +8),
+    `pretrig_samples` (BE uint16 at +16), and `rectime_seconds` (uint8 at +18) into
+    `event.total_samples / pretrig_samples / rectime_seconds`.
+  - Skips the 6-byte preamble (`00 00 ff ff ff ff`) that follows the 21-byte STRT header;
+    waveform data begins at `strt_pos + 27`.
+  - Strips the 8-byte per-frame counter header from A5[1–6, 8] before appending waveform bytes.
+  - Skips A5[7] (metadata-only) and A5[9] (terminator).
+  - **Cross-frame alignment correction**: accumulates `running_offset % 8` across all frames
+    and discards `(8 − align) % 8` leading bytes per frame to re-align to a T/V/L/M boundary.
+    Required because individual frame waveform payloads are not always multiples of 8 bytes.
+  - Decodes as 4-channel interleaved signed 16-bit LE at 8 bytes per sample-set:
+    bytes 0–1 = Tran, 2–3 = Vert, 4–5 = Long, 6–7 = Mic.
+  - Stores result in `event.raw_samples = {"Tran": [...], "Vert": [...], "Long": [...], "Mic": [...]}`.
+- **`download_waveform(event)` public method** on `MiniMateClient`.
+  Issues a full SUB 5A stream with `stop_after_metadata=False`, then calls
+  `_decode_a5_waveform()` to populate `event.raw_samples` and `event.total_samples /
+  pretrig_samples / rectime_seconds`. Previously only metadata frames were fetched during
+  `get_events()`; raw waveform data is now available on demand.
+- **`Event` model new fields** (`models.py`): `total_samples`, `pretrig_samples`,
+  `rectime_seconds` (from STRT record), and `_waveform_key` (4-byte key stored during
+  `get_events()` for later use by `download_waveform()`).
+
+### Protocol / Documentation
+- **SUB 5A A5[0] STRT record layout confirmed** (✅ 2026-04-03, 4-2-26 blast capture):
+  - STRT header is 21 bytes: `b"STRT"` + length fields + `total_samples` (BE uint16 at +8) +
+    `pretrig_samples` (BE uint16 at +16) + `rectime_seconds` (uint8 at +18).
+  - Followed by 6-byte preamble: `00 00 ff ff ff ff`. Waveform begins at `strt_pos + 27`.
+  - Confirmed: 4-2-26 blast → `total_samples=9306`, `pretrig_samples=298`, `rectime_seconds=70`.
+- **Blast/waveform mode A5 format confirmed** (✅ 2026-04-03, 4-2-26 blast capture):
+  4-channel interleaved int16 LE at 8 bytes per sample-set; cross-frame alignment correction
+  required. 948 of 9306 total sample-sets captured via `stop_after_metadata=True` (10 frames).
+- **Noise/histogram mode A5 format — endianness corrected** (✅ 2026-04-03, 3-31-26 capture):
+  32-byte block samples are signed 16-bit **little-endian** (previously documented as BE).
+  `0a 00` → LE int16 = 10 (correct noise floor); BE would give 2560 (wrong).
+- Protocol reference §7.6 rewritten — split into §7.6.1 (Blast/Waveform mode) and §7.6.2
+  (Noise/Histogram mode), each with confirmed field layouts and open questions noted.
+
+---
+
+## v0.6.0 — 2026-04-02
+
+### Added
+- **True event-time metadata via SUB 5A bulk waveform stream** — `get_events()` now issues a SUB 5A request after each SUB 0C download, reads the A5 response frames, and extracts the `Client:`, `User Name:`, and `Seis Loc:` fields as they existed at the moment the event was recorded. Previously these fields were backfilled from the current compliance config (SUB 1A), which reflects today's setup, not the setup active when the event triggered.
+  - `build_5a_frame(offset_word, raw_params)` in `framing.py` — reproduces Blastware's exact wire format for SUB 5A requests: raw (non-DLE-stuffed) `offset_hi`, DLE-stuffed params, and a DLE-aware checksum where `10 XX` pairs count only `XX`.
+  - `bulk_waveform_params()` returns 11 bytes (extra trailing `0x00` confirmed from 1-2-26 BW wire capture).
+  - `read_bulk_waveform_stream(key4, *, stop_after_metadata=True, max_chunks=32)` in `protocol.py` — loops sending chunk requests (counter increments `0x0400` per chunk), stops early when `b"Project:"` is found, then sends a termination frame.
+  - `_decode_a5_metadata_into(frames_data, event)` in `client.py` — needle-searches A5 frame data for `Project:`, `Client:`, `User Name:`, `Seis Loc:`, `Extended Notes` and overwrites `event.project_info`.
+- **`get_events()` sequence extended** — now `1E → 0A → 0C → 5A → 1F` per event.
+
+### Fixed
+- **Compliance config (SUB 1A) channel block missing** — orphaned `self._send(build_bw_frame(SUB_COMPLIANCE, 0x2A, _DATA_PARAMS))` before the B/C/D receive loop had no corresponding `recv_one()`, shifting all subsequent receives one step behind and leaving frame D's channel-block data (trigger_level_geo, alarm_level_geo, max_range_geo) unread. Removed the orphaned send. Total config bytes received now correctly ~2126 (was ~1071).
+- **Compliance config anchor search range** — `_decode_compliance_config_into()` searched `cfg[40:100]` for the sample-rate/record-time anchor. With the orphaned-send bug fixed the 44-byte padding it had been adding is gone, and the anchor now appears at `cfg[11]`. Search widened to `cfg[0:150]` to be robust to future layout shifts.
+- Removed byte-content deduplication from `read_compliance_config()` — was masking the real receive-ordering bug.
+
+### Protocol / Documentation
+- **SUB 5A frame format confirmed** — `offset_hi` byte (`0x10`) must be sent raw (not DLE-stuffed); checksum is DLE-aware (only the second byte of a `10 XX` pair is summed). Standard `build_bw_frame` DLE-stuffs `0x10` incorrectly for 5A — a dedicated `build_5a_frame` is required.
+- **Event-time metadata source confirmed** — `Client:`, `User Name:`, and `Seis Loc:` strings are present in A5 frame 7 of the bulk waveform stream (SUB 5A), not in the 210-byte SUB 0C waveform record. They reflect the compliance setup as it was when the event was stored on the device.
+
+---
+
+## v0.5.0 — 2026-03-31
+
+### Added
+- **Console tab in `seismo_lab.py`** — direct device connection without the bridge subprocess.
+  - Serial and TCP transport selectable via radio buttons.
+  - Four one-click commands: POLL, Serial #, Full Config, Event Index.
+  - Colour-coded scrolling output: TX (blue), RX raw hex (teal), parsed/decoded (green), errors (red).
+  - Save Log and Send to Analyzer buttons; logs auto-saved to `bridges/captures/console_<ts>.log`.
+  - Queue/`after(100)` pattern — no UI blocking or performance impact.
+- **`minimateplus` package** — clean Python client library for the MiniMate Plus S3 protocol.
+  - `SerialTransport` and `TcpTransport` (for Sierra Wireless RV50/RV55 cellular modems).
+  - `MiniMateProtocol` — DLE frame parser/builder, two-step paged reads, checksum validation.
+  - `MiniMateClient` — high-level client: `connect()`, `get_serial()`, `get_config()`, `get_events()`.
+- **TCP/cellular transport** (`TcpTransport`) — connect to field units via Sierra Wireless RV50/RV55 modems over cellular.
+  - `read_until_idle(idle_gap=1.5s)` to handle modem data-forwarding buffer delay.
+  - Confirmed working end-to-end: TCP → RV50/RV55 → RS-232 → MiniMate Plus.
+- **`bridges/tcp_serial_bridge.py`** — local TCP-to-serial bridge for bench testing `TcpTransport` without a cellular modem.
+- **SFM REST server** (`sfm/server.py`) — FastAPI server with device info, event list, and event record endpoints over both serial and TCP.
+
+### Fixed
+- `protocol.py` `startup()` was using a hardcoded `POLL_RECV_TIMEOUT = 10.0` constant, ignoring the configurable `self._recv_timeout`. Fixed to use `self._recv_timeout` throughout.
+- `sfm/server.py` now retries once on `ProtocolError` for TCP connections to handle cold-boot timing on first connect.
+
+### Protocol / Documentation
+- **Sierra Wireless RV50/RV55 modem config** — confirmed required ACEmanager settings: Quiet Mode = Enable, Data Forwarding Timeout = 1, TCP Connect Response Delay = 0. Quiet Mode disabled causes modem to inject `RING\r\nCONNECT\r\n` onto the serial line, breaking the S3 handshake.
+- **Calibration year** confirmed at SUB FE (Full Config) destuffed payload offset 0x56–0x57 (uint16 BE). `0x07E7` = 2023, `0x07E9` = 2025.
+- **`"Operating System"` boot string** — 16-byte UART boot message captured on cold-start before unit enters DLE-framed mode. Parser handles correctly by scanning for DLE+STX.
+- RV50/RV55 sends `RING`/`CONNECT` over TCP to the calling client even with Quiet Mode enabled — this is normal behaviour, parser discards it.
+
+---
+
+## v0.4.0 — 2026-03-12
+
+### Added
+- **`seismo_lab.py`** — combined Bridge + Analyzer GUI. Single window with two tabs; bridge start auto-wires live mode in the Analyzer.
+- **`frame_db.py`** — SQLite frame database. Captures accumulate over time; Query DB tab searches across all sessions.
+- **`bridges/s3-bridge/proxy.py`** — bridge proxy module.
+- Large BW→S3 write frame checksum algorithm confirmed and implemented (`SUM8` of payload `[2:-1]` skipping `0x10` bytes, plus constant `0x10`, mod 256).
+- SUB `A4` identified as composite container frame with embedded inner frames; `_extract_a4_inner_frames()` and `_diff_a4_payloads()` reduce diff noise from 2300 → 17 meaningful entries.
+
+### Fixed
+- BAD CHK false positives on BW POLL frames — BW frame terminator `03 41` was being included in the de-stuffed payload. Fixed to strip correctly.
+- Aux Trigger read location confirmed at SUB FE offset `0x0109`.
+
+---
+
+## v0.3.0 — 2026-03-09
+
+### Added
+- Record time confirmed at SUB E5 page2 offset `+0x28` as float32 BE.
+- Trigger Sample Width confirmed at BW→S3 write frame SUB `0x82`, destuffed payload offset `[22]`.
+- Mode-gating documented: several settings only appear on the wire when the appropriate mode is active.
+
+### Fixed
+- `0x082A` mystery resolved — fixed-size E5 payload length (2090 bytes), not a record-time field.
+
+---
+
+## v0.2.0 — 2026-03-01
+
+### Added
+- Channel config float layout fully confirmed: trigger level, alarm level, and unit string per channel (IEEE 754 BE floats).
+- Blastware `.set` file format decoded — little-endian binary struct mirroring the wire payload.
+- Operator manual (716U0101 Rev 15) added as cross-reference source.
+
+---
+
+## v0.1.0 — 2026-02-26
+
+### Added
+- Initial `s3_bridge.py` serial bridge — transparent RS-232 tap between Blastware and MiniMate Plus.
+- `s3_parser.py` — deterministic DLE state machine frame extractor.
+- `s3_analyzer.py` — session parser, frame differ, Claude export.
+- `gui_bridge.py` and `gui_analyzer.py` — Tkinter GUIs.
+- DLE framing confirmed: `DLE+STX` / `DLE+ETX`, `0x41` = ACK (not STX), DLE stuffing rule.
+- Response SUB rule confirmed: `response_SUB = 0xFF - request_SUB`.
+- Year `0x07CB` = 1995 confirmed as MiniMate factory RTC default.
+- Full write command family documented (SUBs `68`–`83`).

README.md

@@ -0,0 +1,268 @@
+# seismo-relay  `v0.12.1`
+
+A ground-up replacement for **Blastware** — Instantel's aging Windows-only
+software for managing MiniMate Plus seismographs.
+
+Built in Python. Runs on Windows, Linux, or macOS. Connects to instruments
+over direct RS-232 or cellular modem (Sierra Wireless RV50 / RV55).
+
+> **Status:** Active development. Full read + write + erase + monitoring
+> pipeline working end-to-end over TCP/cellular. ACH Auto Call Home server
+> handles inbound unit connections, downloads events, and persists everything
+> to a SQLite database. SFM REST API exposes device control and DB queries.
+> See [CHANGELOG.md](CHANGELOG.md) for full version history.
+
+---
+
+## What's in here
+
+```
+seismo-relay/
+├── seismo_lab.py              ← Main GUI (Bridge + Analyzer + Console tabs)
+│
+├── minimateplus/              ← MiniMate Plus client library
+│   ├── transport.py           ←   SerialTransport, TcpTransport, SocketTransport
+│   ├── protocol.py            ←   DLE frame layer, SUB command dispatch
+│   ├── client.py              ←   High-level client (connect, get_events, push_config, …)
+│   ├── framing.py             ←   Frame builders, DLE codec, S3FrameParser
+│   └── models.py              ←   DeviceInfo, Event, ComplianceConfig, MonitorLogEntry, …
+│
+├── sfm/                       ← SFM REST API server (FastAPI, port 8200)
+│   ├── server.py              ←   All device + DB endpoints
+│   ├── database.py            ←   SeismoDb — SQLite persistence layer
+│   └── sfm_webapp.html        ←   Embedded web UI (served at /)
+│
+├── bridges/
+│   ├── ach_server.py          ←   Inbound ACH call-home server (main production server)
+│   ├── ach_mitm.py            ←   Transparent MITM proxy for capturing BW sessions
+│   ├── s3-bridge/             ←   RS-232 serial bridge (capture tool)
+│   ├── tcp_serial_bridge.py   ←   Local TCP↔serial bridge (bench testing)
+│   ├── gui_bridge.py          ←   Standalone bridge GUI
+│   └── raw_capture.py         ←   Simple raw capture tool
+│
+├── parsers/
+│   ├── s3_analyzer.py         ←   Session parser, differ, Claude export
+│   ├── gui_analyzer.py        ←   Standalone analyzer GUI
+│   └── frame_db.py            ←   SQLite frame database
+│
+└── docs/
+    └── instantel_protocol_reference.md  ← Reverse-engineered protocol spec
+```
+
+---
+
+## Quick start
+
+### ACH inbound server (production)
+
+Listens for inbound unit call-homes, downloads all new events and monitor log
+entries, and writes everything to `bridges/captures/seismo_relay.db`.
+
+```bash
+python bridges/ach_server.py --port 12345 --output bridges/captures/
+```
+
+Point the unit's ACEmanager **Remote Host** to this machine's IP and **Remote Port** to `12345`.
+
+Options:
+```
+--port N            Listen port (default 12345)
+--output DIR        Capture directory (default bridges/captures/)
+--allow-ip IP       Allowlist an IP (repeat for multiple; default: accept all)
+--max-events N      Safety cap for first run (default: unlimited)
+--clear-after-download  Erase device memory after successful download
+--verbose           Debug logging
+```
+
+### SFM REST server
+
+Exposes device control and DB queries as a REST API. Proxied by terra-view.
+
+```bash
+python sfm/server.py               # default: 0.0.0.0:8200
+python -m uvicorn sfm.server:app --host 0.0.0.0 --port 8200 --reload
+```
+
+Open `http://localhost:8200` for the embedded web UI, or `http://localhost:8200/docs`
+for the interactive API docs.
+
+### Seismo Lab GUI
+
+```bash
+python seismo_lab.py
+```
+
+---
+
+## SFM REST API
+
+### Live device endpoints
+
+Each call dials the device, does its work, and closes the connection. TCP
+connections are retried once on `ProtocolError` to handle cold-boot timing.
+
+**Caching** — frequently-polled endpoints are cached in-process to avoid
+redundant TCP round-trips:
+
+| Method | URL | Cache |
+|--------|-----|-------|
+| `GET` | `/device/info` | Indefinite; invalidated by `POST /device/config` |
+| `GET` | `/device/events` | Count-probe fast path (~2s); full download only when new events detected |
+| `GET` | `/device/event/{idx}/waveform` | Permanent per event index |
+| `GET` | `/device/monitor/status` | 30-second TTL |
+| `POST` | `/device/connect` | — |
+| `POST` | `/device/config` | Writes compliance config; invalidates cache |
+| `POST` | `/device/monitor/start` | Sends SUB 0x96 |
+| `POST` | `/device/monitor/stop` | Sends SUB 0x97 |
+
+All cached endpoints accept `?force=true` to bypass the cache.
+
+Transport query params (supply one set):
+```
+Serial:  ?port=COM5&baud=38400
+TCP:     ?host=1.2.3.4&tcp_port=12345
+```
+
+### DB read endpoints
+
+Query the SQLite database written by `ach_server.py`. All read-only except
+`PATCH /db/events/{id}/false_trigger`.
+
+| Method | URL | Description |
+|--------|-----|-------------|
+| `GET` | `/db/units` | All known serials with summary stats |
+| `GET` | `/db/events` | Triggered events (filter by serial, date range, false_trigger) |
+| `GET` | `/db/monitor_log` | Monitoring intervals |
+| `GET` | `/db/sessions` | ACH call-home session history |
+| `PATCH` | `/db/events/{id}/false_trigger?value=true` | Flag / unflag false triggers |
+
+---
+
+## minimateplus library
+
+```python
+from minimateplus import MiniMateClient
+from minimateplus.transport import TcpTransport
+
+# Serial
+client = MiniMateClient(port="COM5")
+
+# TCP (cellular modem)
+client = MiniMateClient(transport=TcpTransport("1.2.3.4", 12345), timeout=30.0)
+
+with client:
+    # Read
+    info    = client.connect()               # DeviceInfo — serial, firmware, compliance config
+    count   = client.count_events()          # Number of stored events
+    keys    = client.list_event_keys()       # Fast browse walk — event keys only, no download
+    events  = client.get_events()            # Full download: headers + peaks + metadata
+    monitor = client.get_monitor_status()    # Battery, memory, is_monitoring flag
+    log     = client.get_monitor_log_entries()  # Monitoring intervals (partial 0x2C records)
+
+    # Write
+    client.apply_config(
+        sample_rate=1024,
+        trigger_level_geo=0.5,
+        project="Bridge Inspection 2026",
+        client_name="City of Portland",
+        operator="B. Harrison",
+    )
+
+    # Control
+    client.start_monitoring()                # SUB 0x96
+    client.stop_monitoring()                 # SUB 0x97
+    client.delete_all_events()              # Erase all (SUB 0xA3 → 0x1C → 0x06 → 0xA2)
+```
+
+`get_events()` runs the full per-event sequence: `1E → 0A → 0C → 5A → 1F`.
+SUB 5A bulk stream provides `client`, `operator`, and `sensor_location` as they
+existed at record time — not backfilled from the current compliance config.
+
+---
+
+## Database
+
+`ach_server.py` writes to `bridges/captures/seismo_relay.db` (SQLite, WAL mode).
+Three tables, all unit-keyed by serial number:
+
+| Table | Key | Contents |
+|-------|-----|----------|
+| `ach_sessions` | UUID | Per-call-home audit record: serial, peer IP, events_downloaded, duration |
+| `events` | UUID, UNIQUE(serial, waveform_key) | Triggered events: timestamp, PPV per channel, project/client/operator strings, false_trigger flag |
+| `monitor_log` | UUID, UNIQUE(serial, waveform_key) | Monitoring intervals: start/stop time, duration, geo threshold |
+
+Deduplication is by `(serial, waveform_key)` — repeat call-homes or re-runs
+never produce duplicate rows. Post-erase key reuse is handled automatically
+via the high-water mark in `ach_state.json`.
+
+---
+
+## Connecting over cellular (RV50 / RV55)
+
+Field units connect via Sierra Wireless RV50 or RV55 cellular modems.
+
+### Required ACEmanager settings
+
+| Setting | Value | Why |
+|---------|-------|-----|
+| Configure Serial Port | `38400,8N1` | Must match MiniMate baud rate |
+| Flow Control | `None` | Hardware FC blocks TX if pins unconnected |
+| **Quiet Mode** | **Enable** | **Critical** — disabled injects `RING`/`CONNECT` onto serial, corrupting the S3 handshake |
+| Data Forwarding Timeout | `1` (= 0.1 s) | Lower latency |
+| TCP Connect Response Delay | `0` | Non-zero silently drops the first POLL frame |
+| TCP Idle Timeout | `2` (minutes) | Prevents premature disconnect |
+| DB9 Serial Echo | `Disable` | Echo corrupts the data stream |
+
+---
+
+## Protocol quick-reference
+
+| Term | Value | Meaning |
+|------|-------|---------|
+| DLE | `0x10` | Data Link Escape |
+| STX | `0x02` | Start of frame |
+| ETX | `0x03` | End of frame |
+| ACK | `0x41` | Frame-start marker sent before every BW frame |
+| DLE stuffing | `10 10` on wire | Literal `0x10` in payload |
+
+**Response SUB rule:** `response_SUB = 0xFF - request_SUB` (no exceptions)
+
+Full protocol documentation: [`docs/instantel_protocol_reference.md`](docs/instantel_protocol_reference.md)
+
+---
+
+## Requirements
+
+```bash
+pip install pyserial fastapi uvicorn
+```
+
+Python 3.10+. Tkinter is included with the standard Python installer on
+Windows (check "tcl/tk and IDLE" during install).
+
+---
+
+## Virtual COM ports (bridge capture)
+
+```
+Blastware → COM4 (virtual) ↔ s3_bridge.py ↔ COM5 (physical) → MiniMate Plus
+```
+
+Use **com0com** or **VSPD** to create the virtual COM pair on Windows.
+
+---
+
+## Roadmap
+
+- [x] Full read pipeline — device info, compliance config, event download with true event-time metadata
+- [x] Write commands — push compliance config, trigger thresholds, project strings to device
+- [x] Erase all events — confirmed erase sequence from live MITM capture
+- [x] Monitor control — start/stop monitoring, read battery/memory/status
+- [x] Monitor log entries — decode partial 0x2C records (continuous monitoring intervals)
+- [x] ACH inbound server — accept call-home connections, download events, dedup by key
+- [x] SQLite persistence — events, monitor log, and session history in `seismo_relay.db`
+- [x] SFM REST API — device control + DB query endpoints, live device cache
+- [ ] Terra-view integration — seismo-relay router, unit detail page, VISON-style event listing
+- [ ] Vibration summary reports — highest legit PPV per project → Word doc (false trigger filtering first)
+- [ ] Compliance config encoder — build raw write payloads from a `ComplianceConfig` object
+- [ ] Modem manager — push RV50/RV55 configs via Sierra Wireless API

bridges/ach_bridge.py

@@ -0,0 +1,627 @@
+#!/usr/bin/env python3
+"""
+ach_bridge.py — Transparent TCP bridge / splitter for Instantel MiniMate Plus
+                call-home (ACH) traffic.
+
+Modes
+-----
+  standalone   Accept connection, capture frames, do NOT forward anywhere.
+               Good for initial discovery with a test unit.
+
+  bridge       Forward to one upstream server while capturing.
+               Use this for the initial discovery phase with your test server.
+
+  splitter     Forward to the PRIMARY upstream (production ACH server) AND
+               mirror a copy to a SECONDARY server simultaneously.
+               The device never knows — it talks to the primary the whole time.
+               If the mirror fails, the primary connection is unaffected.
+
+               Think of it like a headphone splitter: one input, two outputs.
+               Primary → authoritative responses back to device.
+               Mirror  → gets all device bytes, its responses are discarded.
+
+Usage
+-----
+  # Standalone capture (test/discovery — no forwarding)
+  python bridges/ach_bridge.py --standalone [--port 12345]
+
+  # Bridge mode (forward to one server, e.g. your test server)
+  python bridges/ach_bridge.py --upstream HOST:PORT [--port 12345]
+
+  # Splitter mode (production: forward to prod + mirror to your server)
+  python bridges/ach_bridge.py --upstream PROD_HOST:PORT --mirror MY_HOST:PORT [--port 12345]
+
+Setup for discovery (test server, don't touch prod)
+----------------------------------------------------
+1. Stand up your test ACH server, note its IP and port (e.g. 192.168.1.50:12345).
+2. Take ONE test unit.  In ACEmanager → Call Home, point it at:
+     <this machine's LAN IP> : <--port>
+3. Run:  python bridges/ach_bridge.py --upstream TEST_SERVER:12345 --port 12345
+4. Trigger the unit.  Raw frames are saved to bridges/captures/ach_<ts>/.
+5. Revert the unit's ACEmanager setting when done.
+
+Setup for production splitter (when you're ready)
+-------------------------------------------------
+This does NOT touch the units.  Instead you re-route traffic at the network
+layer so that call-home packets arrive at a machine running this script first.
+Typical approach: update the DNS entry / host record your prod ACH server is
+registered under to point at this machine.  The units keep their existing
+ACEmanager settings.
+
+  python bridges/ach_bridge.py \\
+      --upstream PROD_ACH_HOST:12345 \\
+      --mirror   MY_NEW_SERVER:12345 \\
+      --port     12345
+
+Output (each connection gets its own timestamped sub-directory)
+------
+  bridges/captures/ach_<ts>/
+    raw_client_<ts>.bin   — raw bytes from the device (S3 side)
+    raw_server_<ts>.bin   — raw bytes from the primary upstream (BW side)
+    raw_mirror_<ts>.bin   — raw bytes from the mirror upstream (splitter mode only)
+    session_<ts>.log      — human-readable frame parse log
+    session_<ts>.jsonl    — JSON-lines frame log
+
+raw_client / raw_server are byte-for-byte compatible with parse_capture.py.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import datetime
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+# Add project root to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from minimateplus.framing import S3FrameParser, S3Frame
+
+log = logging.getLogger("ach_bridge")
+
+
+# ── Frame label helpers ──────────────────────────────────────────────────────
+
+_KNOWN_RSP_SUBS = {
+    0xA4: "POLL_RSP",
+    0xA5: "BULK_WAVEFORM_RSP",
+    0xE0: "ADVANCE_EVENT_RSP",
+    0xE1: "EVENT_INDEX_FIRST_RSP",
+    0xE3: "MONITOR_STATUS_RSP",
+    0xEA: "SERIAL_NUM_RSP",
+    0xF3: "WAVEFORM_RECORD_RSP",
+    0xF5: "WAVEFORM_HEADER_RSP",
+    0xF7: "EVENT_INDEX_RSP",
+    0xF9: "UNK_06_RSP",
+    0xFE: "DEVICE_INFO_RSP",
+    # Write acks
+    0x97: "EVT_IDX_WRITE_ACK",
+    0x8C: "CONFIRM_B_ACK",
+    0x8E: "COMPLIANCE_WRITE_ACK",
+    0x8D: "CONFIRM_A_ACK",
+    0x7D: "TRIGGER_WRITE_ACK",
+    0x7C: "TRIGGER_CONFIRM_ACK",
+    0x96: "WAVEFORM_WRITE_ACK",
+    0x8B: "CONFIRM_C_ACK",
+    0x69: "START_MONITOR_ACK",
+    0x68: "STOP_MONITOR_ACK",
+}
+
+_KNOWN_REQ_SUBS = {
+    0x5B: "POLL",
+    0x5A: "BULK_WAVEFORM",
+    0x1F: "ADVANCE_EVENT",
+    0x1E: "EVENT_INDEX_FIRST",
+    0x1C: "MONITOR_STATUS",
+    0x15: "SERIAL_NUM",
+    0x0C: "WAVEFORM_RECORD",
+    0x0A: "WAVEFORM_HEADER",
+    0x08: "EVENT_INDEX",
+    0x06: "UNK_06",
+    0x01: "DEVICE_INFO",
+    # Write commands
+    0x68: "EVT_IDX_WRITE",
+    0x73: "CONFIRM_B",
+    0x71: "COMPLIANCE_WRITE",
+    0x72: "CONFIRM_A",
+    0x82: "TRIGGER_WRITE",
+    0x83: "TRIGGER_CONFIRM",
+    0x69: "WAVEFORM_WRITE",
+    0x74: "CONFIRM_C",
+    0x96: "START_MONITOR",
+    0x97: "STOP_MONITOR",
+}
+
+
+def _label_s3_frame(frame: S3Frame) -> str:
+    name = _KNOWN_RSP_SUBS.get(frame.sub, f"UNK_0x{frame.sub:02X}")
+    chk = "✓" if frame.checksum_valid else "✗CHK"
+    return (
+        f"S3→  SUB=0x{frame.sub:02X} ({name}) "
+        f"page=0x{frame.page_key:04X} data={len(frame.data)}B {chk}"
+    )
+
+
+def _label_bw_frame(data: bytes, prefix: str = "  →BW") -> str:
+    """Best-effort label for a raw BW request frame (wire bytes)."""
+    # Wire layout: 41 02 10 10 00 sub ...
+    if len(data) < 6:
+        return f"{prefix}  (short {len(data)}B)"
+    sub = data[5]
+    name = _KNOWN_REQ_SUBS.get(sub, f"UNK_0x{sub:02X}")
+    return f"{prefix}  SUB=0x{sub:02X} ({name}) {len(data)}B"
+
+
+# ── Per-session capture writer ─────────────────────────────────────────────────
+
+class CaptureSession:
+    """Writes raw bytes + parsed log for one TCP connection."""
+
+    def __init__(self, capture_dir: Path, peer: str, *, has_mirror: bool = False):
+        ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+        self.dir = capture_dir / f"ach_{ts}"
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.peer = peer
+
+        self._raw_client = open(self.dir / f"raw_client_{ts}.bin", "wb")
+        self._raw_server = open(self.dir / f"raw_server_{ts}.bin", "wb")
+        self._raw_mirror = (
+            open(self.dir / f"raw_mirror_{ts}.bin", "wb") if has_mirror else None
+        )
+        self._log_fh   = open(self.dir / f"session_{ts}.log",   "w")
+        self._jsonl_fh = open(self.dir / f"session_{ts}.jsonl", "w")
+
+        self._s3_parser = S3FrameParser()
+        self._frame_count       = 0
+        self._byte_count_client = 0
+        self._byte_count_server = 0
+        self._byte_count_mirror = 0
+
+        self._log(
+            f"# ACH capture — peer={peer}  "
+            f"mirror={'yes' if has_mirror else 'no'}  "
+            f"started={datetime.datetime.now().isoformat()}"
+        )
+        self._log(f"# Output dir: {self.dir}")
+        log.info("Capture session opened: %s (peer=%s)", self.dir, peer)
+
+    # ── public API ────────────────────────────────────────────────────────────
+
+    def feed_client(self, data: bytes) -> None:
+        """Bytes FROM the device (S3 response frames)."""
+        self._raw_client.write(data)
+        self._raw_client.flush()
+        self._byte_count_client += len(data)
+
+        for byte in data:
+            frame = self._s3_parser.feed(bytes([byte]))
+            if frame:
+                frames = frame if isinstance(frame, list) else [frame]
+                for f in frames:
+                    self._frame_count += 1
+                    label = _label_s3_frame(f)
+                    self._log(f"[{self._frame_count:04d}] {label}")
+                    self._log(
+                        f"       hex: {f.data[:64].hex()}"
+                        + (" ..." if len(f.data) > 64 else "")
+                    )
+                    self._emit_json("s3", f)
+
+    def feed_server(self, data: bytes) -> None:
+        """Bytes FROM the primary upstream server (BW request frames)."""
+        self._raw_server.write(data)
+        self._raw_server.flush()
+        self._byte_count_server += len(data)
+        label = _label_bw_frame(data, prefix="  →BW[primary]")
+        self._log(f"       {label}")
+
+    def feed_mirror(self, data: bytes) -> None:
+        """Bytes FROM the mirror server (logged, not forwarded to device)."""
+        if self._raw_mirror:
+            self._raw_mirror.write(data)
+            self._raw_mirror.flush()
+        self._byte_count_mirror += len(data)
+        label = _label_bw_frame(data, prefix="  →BW[mirror] ")
+        self._log(f"       {label}  [MIRROR — not sent to device]")
+
+    def close(self, reason: str = "connection closed") -> None:
+        self._log(f"# Session ended: {reason}")
+        self._log(
+            f"# Totals — client={self._byte_count_client}B  "
+            f"server={self._byte_count_server}B  "
+            f"mirror={self._byte_count_mirror}B  "
+            f"s3_frames={self._frame_count}"
+        )
+        handles = [self._raw_client, self._raw_server, self._log_fh, self._jsonl_fh]
+        if self._raw_mirror:
+            handles.append(self._raw_mirror)
+        for fh in handles:
+            try:
+                fh.close()
+            except Exception:
+                pass
+        log.info(
+            "Session closed (%s): %dB client, %dB server, %dB mirror, %d S3 frames → %s",
+            reason,
+            self._byte_count_client, self._byte_count_server,
+            self._byte_count_mirror, self._frame_count,
+            self.dir,
+        )
+
+    # ── internals ─────────────────────────────────────────────────────────────
+
+    def _log(self, msg: str) -> None:
+        print(msg, file=self._log_fh, flush=True)
+        print(msg)
+
+    def _emit_json(self, direction: str, frame: S3Frame) -> None:
+        record = {
+            "dir":            direction,
+            "sub":            frame.sub,
+            "page_key":       frame.page_key,
+            "data_len":       len(frame.data),
+            "data_hex":       frame.data.hex(),
+            "checksum_valid": frame.checksum_valid,
+        }
+        print(json.dumps(record), file=self._jsonl_fh, flush=True)
+
+
+# ── Bridge / splitter connection handler ──────────────────────────────────────
+
+class BridgeHandler:
+    """
+    Handles inbound device connections.
+
+    Modes (determined by which upstreams are configured):
+      standalone  — no upstream_host / no mirror_host
+      bridge      — upstream_host set, no mirror_host
+      splitter    — upstream_host AND mirror_host both set
+    """
+
+    def __init__(
+        self,
+        capture_dir:   Path,
+        upstream_host: Optional[str],
+        upstream_port: Optional[int],
+        mirror_host:   Optional[str] = None,
+        mirror_port:   Optional[int] = None,
+    ):
+        self.capture_dir   = capture_dir
+        self.upstream_host = upstream_host
+        self.upstream_port = upstream_port
+        self.mirror_host   = mirror_host
+        self.mirror_port   = mirror_port
+
+    async def handle(
+        self,
+        client_reader: asyncio.StreamReader,
+        client_writer: asyncio.StreamWriter,
+    ) -> None:
+        peer = client_writer.get_extra_info("peername", ("?", 0))
+        peer_str = f"{peer[0]}:{peer[1]}"
+        log.info("Inbound connection from %s", peer_str)
+
+        has_mirror = bool(self.mirror_host)
+        session = CaptureSession(self.capture_dir, peer_str, has_mirror=has_mirror)
+
+        if not self.upstream_host:
+            # ── Standalone mode ──────────────────────────────────────────────
+            log.info("Standalone mode — recording inbound traffic only")
+            try:
+                while True:
+                    data = await client_reader.read(4096)
+                    if not data:
+                        break
+                    session.feed_client(data)
+            except asyncio.CancelledError:
+                pass
+            except Exception as exc:
+                log.warning("Standalone read error: %s", exc)
+            finally:
+                session.close("standalone capture ended")
+                try:
+                    client_writer.close()
+                    await client_writer.wait_closed()
+                except Exception:
+                    pass
+            return
+
+        # ── Bridge / splitter mode ───────────────────────────────────────────
+        # Connect to primary upstream (required)
+        try:
+            up_reader, up_writer = await asyncio.open_connection(
+                self.upstream_host, self.upstream_port
+            )
+            log.info("Connected to primary %s:%s", self.upstream_host, self.upstream_port)
+        except Exception as exc:
+            log.error("Failed to connect to primary upstream: %s", exc)
+            session.close(f"primary connect failed: {exc}")
+            client_writer.close()
+            return
+
+        # Connect to mirror upstream (optional — failure is non-fatal)
+        mir_reader: Optional[asyncio.StreamReader] = None
+        mir_writer: Optional[asyncio.StreamWriter] = None
+        if self.mirror_host:
+            try:
+                mir_reader, mir_writer = await asyncio.open_connection(
+                    self.mirror_host, self.mirror_port
+                )
+                log.info("Connected to mirror %s:%s", self.mirror_host, self.mirror_port)
+            except Exception as exc:
+                log.warning(
+                    "Mirror connect failed — continuing without mirror: %s", exc
+                )
+                session._log(f"# WARNING: mirror connect failed: {exc}")
+
+        # Build relay tasks
+        #
+        # ┌──────────┐  device bytes  ┌─────────────┐
+        # │  Device  │ ─────────────► │   PRIMARY   │  responses ──► device
+        # └──────────┘                └─────────────┘
+        #      │
+        #      │ device bytes (copy)
+        #      ▼
+        # ┌─────────────┐
+        # │   MIRROR    │  responses discarded (logged only)
+        # └─────────────┘
+        #
+        tasks = [
+            asyncio.create_task(
+                self._relay_device(client_reader, up_writer, mir_writer, session),
+                name="device→upstreams",
+            ),
+            asyncio.create_task(
+                self._relay_simple(up_reader, client_writer, session, "server"),
+                name="primary→device",
+            ),
+        ]
+        if mir_reader is not None:
+            tasks.append(asyncio.create_task(
+                self._relay_drain(mir_reader, session),
+                name="mirror→drain",
+            ))
+
+        try:
+            # Wait for the device-to-upstreams relay to exit first (device
+            # disconnected or primary dropped).  Then cancel the rest.
+            done, pending = await asyncio.wait(
+                tasks,
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            for t in pending:
+                t.cancel()
+                try:
+                    await t
+                except (asyncio.CancelledError, Exception):
+                    pass
+        except Exception as exc:
+            log.warning("Bridge relay error: %s", exc)
+        finally:
+            session.close("relay ended")
+            for writer in filter(None, [client_writer, up_writer, mir_writer]):
+                try:
+                    writer.close()
+                    await writer.wait_closed()
+                except Exception:
+                    pass
+
+    # ── Relay helpers ─────────────────────────────────────────────────────────
+
+    async def _relay_device(
+        self,
+        reader:       asyncio.StreamReader,
+        primary_writer: asyncio.StreamWriter,
+        mirror_writer:  Optional[asyncio.StreamWriter],
+        session:      CaptureSession,
+    ) -> None:
+        """
+        Read bytes from the device, write to the primary server, and also
+        write a copy to the mirror server (if connected).  Mirror write
+        failures are non-fatal — we log and continue.
+        """
+        try:
+            while True:
+                data = await reader.read(4096)
+                if not data:
+                    break
+                session.feed_client(data)
+
+                # Primary write — failure IS fatal (lose primary = lose prod)
+                primary_writer.write(data)
+                await primary_writer.drain()
+
+                # Mirror write — failure is non-fatal
+                if mirror_writer is not None:
+                    try:
+                        mirror_writer.write(data)
+                        await mirror_writer.drain()
+                    except Exception as exc:
+                        log.warning("Mirror write failed (non-fatal): %s", exc)
+                        session._log(f"# WARNING: mirror write failed: {exc}")
+                        mirror_writer = None  # stop trying
+
+        except (asyncio.IncompleteReadError, ConnectionResetError, BrokenPipeError):
+            pass
+
+    async def _relay_simple(
+        self,
+        reader:    asyncio.StreamReader,
+        writer:    asyncio.StreamWriter,
+        session:   CaptureSession,
+        direction: str,
+    ) -> None:
+        """Standard single-pipe relay (primary→device or vice-versa)."""
+        try:
+            while True:
+                data = await reader.read(4096)
+                if not data:
+                    break
+                if direction == "server":
+                    session.feed_server(data)
+                else:
+                    session.feed_client(data)
+                writer.write(data)
+                await writer.drain()
+        except (asyncio.IncompleteReadError, ConnectionResetError, BrokenPipeError):
+            pass
+
+    async def _relay_drain(
+        self,
+        reader:  asyncio.StreamReader,
+        session: CaptureSession,
+    ) -> None:
+        """
+        Read mirror server responses, log them to session, do NOT forward to
+        device.  The device only ever sees primary server responses.
+        """
+        try:
+            while True:
+                data = await reader.read(4096)
+                if not data:
+                    break
+                session.feed_mirror(data)
+        except (asyncio.IncompleteReadError, ConnectionResetError, BrokenPipeError):
+            pass
+
+
+# ── Main ───────────────────────────────────────────────────────────────────────
+
+async def main(args: argparse.Namespace) -> None:
+    capture_dir = Path(__file__).parent / "captures"
+    capture_dir.mkdir(parents=True, exist_ok=True)
+
+    upstream_host: Optional[str] = None
+    upstream_port: Optional[int] = None
+    mirror_host:   Optional[str] = None
+    mirror_port:   Optional[int] = None
+
+    if not args.standalone:
+        if not args.upstream:
+            print("ERROR: --upstream HOST:PORT is required unless --standalone is set.")
+            sys.exit(1)
+        parts = args.upstream.rsplit(":", 1)
+        if len(parts) != 2:
+            print("ERROR: --upstream must be HOST:PORT (e.g. 203.0.113.5:12345)")
+            sys.exit(1)
+        upstream_host = parts[0]
+        upstream_port = int(parts[1])
+
+    if args.mirror:
+        parts = args.mirror.rsplit(":", 1)
+        if len(parts) != 2:
+            print("ERROR: --mirror must be HOST:PORT (e.g. 192.168.1.50:12345)")
+            sys.exit(1)
+        mirror_host = parts[0]
+        mirror_port = int(parts[1])
+
+    handler = BridgeHandler(
+        capture_dir,
+        upstream_host, upstream_port,
+        mirror_host,   mirror_port,
+    )
+
+    server = await asyncio.start_server(
+        handler.handle,
+        host="0.0.0.0",
+        port=args.port,
+    )
+
+    # ── Startup banner ────────────────────────────────────────────────────────
+    if args.standalone:
+        mode = "STANDALONE capture (no forwarding)"
+    elif mirror_host:
+        mode = f"SPLITTER  primary={upstream_host}:{upstream_port}  mirror={mirror_host}:{mirror_port}"
+    else:
+        mode = f"BRIDGE → {upstream_host}:{upstream_port}"
+
+    addrs = ", ".join(str(s.getsockname()) for s in server.sockets)
+    print(f"\n{'='*70}")
+    print(f"  ACH bridge/splitter  listening on {addrs}")
+    print(f"  Mode:  {mode}")
+    print(f"  Captures: {capture_dir}/ach_<timestamp>/")
+    print(f"{'='*70}")
+
+    if upstream_host and not mirror_host:
+        print(f"\n  DISCOVERY PHASE")
+        print(f"  Point your TEST unit's ACEmanager call-home destination to:")
+        print(f"    <this machine's LAN IP> : {args.port}")
+        print(f"  All traffic will be forwarded to {upstream_host}:{upstream_port}")
+    elif mirror_host:
+        print(f"\n  SPLITTER MODE — PRODUCTION SAFE")
+        print(f"  Units connect as normal.  Every byte is forwarded to:")
+        print(f"    PRIMARY (authoritative): {upstream_host}:{upstream_port}")
+        print(f"    MIRROR  (your server):   {mirror_host}:{mirror_port}")
+        print(f"  Only PRIMARY responses reach the device.")
+        print(f"  Mirror failures are logged and do not affect the device.")
+    else:
+        print(f"\n  STANDALONE MODE — capture only, nothing forwarded")
+        print(f"  Point a unit at <this machine's LAN IP> : {args.port}")
+
+    print(f"\n  Waiting for inbound connections...  (Ctrl-C to stop)\n")
+
+    async with server:
+        await server.serve_forever()
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        description=(
+            "Transparent TCP bridge / splitter for Instantel MiniMate Plus "
+            "call-home (ACH) traffic."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    p.add_argument(
+        "--upstream", "-u",
+        metavar="HOST:PORT",
+        help=(
+            "Primary upstream ACH server to forward to "
+            "(e.g. 203.0.113.5:12345). "
+            "Omit with --standalone for capture-only mode."
+        ),
+    )
+    p.add_argument(
+        "--mirror", "-m",
+        metavar="HOST:PORT",
+        help=(
+            "Mirror / secondary server to receive a copy of all device bytes "
+            "(splitter mode).  Mirror responses are logged but NOT forwarded "
+            "to the device.  Mirror failures are non-fatal."
+        ),
+    )
+    p.add_argument(
+        "--port", "-p",
+        type=int,
+        default=12345,
+        help="Local port to listen on (default: 12345).",
+    )
+    p.add_argument(
+        "--standalone", "-s",
+        action="store_true",
+        help="Capture-only mode: accept connection, do not forward anywhere.",
+    )
+    p.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        help="Enable debug logging.",
+    )
+    return p.parse_args()
+
+
+if __name__ == "__main__":
+    args = parse_args()
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s  %(levelname)-7s  %(name)s  %(message)s",
+    )
+    try:
+        asyncio.run(main(args))
+    except KeyboardInterrupt:
+        print("\nStopped.")

bridges/ach_mitm.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""
+ach_mitm.py — TCP man-in-the-middle proxy for capturing Blastware ACH sessions.
+
+The unit calls home to THIS proxy instead of directly to Blastware.  The proxy
+forwards every byte in both directions to the real Blastware ACH server and saves
+the traffic to separate raw capture files that the Analyzer can load directly.
+
+Setup
+-----
+  1.  Start Blastware's ACH server on the BW PC as normal (it listens on its port).
+  2.  Run this proxy on any machine the unit can reach:
+
+        python bridges/ach_mitm.py --bw-host 192.168.1.50 --bw-port 9999
+
+  3.  Point the unit's ACEmanager call-home destination to THIS machine's IP and
+      the --listen-port (default 9999).
+  4.  Trigger a call-home (or wait for the unit to call in).
+  5.  The proxy transparently forwards everything and saves two files per session:
+
+        ach_mitm_<ts>/raw_bw_<ts>.bin   -- bytes Blastware sent to unit (BW TX)
+        ach_mitm_<ts>/raw_s3_<ts>.bin   -- bytes unit sent to Blastware (S3 TX)
+
+  Both files load directly in the Analyzer (File > Open Capture).
+
+  The proxy exits cleanly when either side drops the connection.
+
+Use case: capturing Blastware operations we haven't reverse-engineered yet,
+e.g. event deletion, factory reset, firmware update.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import logging
+import socket
+import sys
+import threading
+from pathlib import Path
+
+log = logging.getLogger("ach_mitm")
+
+
+def _pipe(src: socket.socket, dst: socket.socket, label: str, outfile) -> None:
+    """Forward bytes from src to dst, writing everything to outfile."""
+    try:
+        while True:
+            data = src.recv(4096)
+            if not data:
+                break
+            dst.sendall(data)
+            outfile.write(data)
+            outfile.flush()
+            log.debug("%s  %d bytes", label, len(data))
+    except OSError:
+        pass
+    finally:
+        log.info("%s  pipe closed", label)
+        # Signal the other direction to stop by shutting down our end.
+        try:
+            dst.shutdown(socket.SHUT_WR)
+        except OSError:
+            pass
+
+
+def handle(unit_sock: socket.socket, peer: str, bw_host: str, bw_port: int,
+           output_dir: Path) -> None:
+    ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+    session_dir = output_dir / f"ach_mitm_{ts}"
+    session_dir.mkdir(parents=True, exist_ok=True)
+
+    log.info("Session %s  unit=%s  forwarding to %s:%d", ts, peer, bw_host, bw_port)
+
+    # Connect upstream to Blastware.
+    bw_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        bw_sock.connect((bw_host, bw_port))
+    except OSError as exc:
+        log.error("Cannot reach Blastware at %s:%d: %s", bw_host, bw_port, exc)
+        unit_sock.close()
+        return
+
+    log.info("Connected to Blastware at %s:%d", bw_host, bw_port)
+
+    bw_path   = session_dir / f"raw_bw_{ts}.bin"   # Blastware → unit  (BW TX)
+    s3_path   = session_dir / f"raw_s3_{ts}.bin"   # unit → Blastware  (S3 TX)
+
+    with open(bw_path, "wb") as bw_fh, open(s3_path, "wb") as s3_fh:
+        # Two threads: one per direction.
+        t_bw = threading.Thread(
+            target=_pipe, args=(bw_sock, unit_sock, "BW->unit", bw_fh), daemon=True
+        )
+        t_s3 = threading.Thread(
+            target=_pipe, args=(unit_sock, bw_sock, "unit->BW", s3_fh), daemon=True
+        )
+        t_bw.start()
+        t_s3.start()
+        t_bw.join()
+        t_s3.join()
+
+    bw_bytes = bw_path.stat().st_size
+    s3_bytes = s3_path.stat().st_size
+    log.info(
+        "Session %s done  BW->unit: %d bytes  unit->BW: %d bytes  -> %s",
+        ts, bw_bytes, s3_bytes, session_dir,
+    )
+
+    unit_sock.close()
+    bw_sock.close()
+
+
+def serve(args: argparse.Namespace) -> None:
+    output_dir = Path(args.output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    server.bind(("0.0.0.0", args.listen_port))
+    server.listen(5)
+    server.settimeout(1.0)
+
+    print(f"\n{'='*60}")
+    print(f"  ACH MITM proxy")
+    print(f"  Listening on     0.0.0.0:{args.listen_port}")
+    print(f"  Forwarding to    {args.bw_host}:{args.bw_port}")
+    print(f"  Captures in      {output_dir.resolve()}/ach_mitm_<ts>/")
+    print(f"{'='*60}")
+    print(f"\n  Point the unit's ACEmanager call-home to this machine on port {args.listen_port}")
+    print(f"  Ctrl-C to stop\n")
+
+    try:
+        while True:
+            try:
+                client_sock, addr = server.accept()
+            except socket.timeout:
+                continue
+            peer = f"{addr[0]}:{addr[1]}"
+            log.info("Accepted connection from %s", peer)
+            t = threading.Thread(
+                target=handle,
+                args=(client_sock, peer, args.bw_host, args.bw_port, output_dir),
+                daemon=True,
+            )
+            t.start()
+    except KeyboardInterrupt:
+        print("\nStopping.")
+    finally:
+        server.close()
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--bw-host",     required=True,
+                    help="IP or hostname of the Blastware ACH server")
+    ap.add_argument("--bw-port",     type=int, default=9999,
+                    help="Port Blastware is listening on (default: 9999)")
+    ap.add_argument("--listen-port", type=int, default=9999,
+                    help="Port this proxy listens on (default: 9999)")
+    ap.add_argument("--output",      default="bridges/captures/mitm",
+                    help="Directory for capture files")
+    ap.add_argument("--log-level",   default="INFO",
+                    choices=["DEBUG", "INFO", "WARNING", "ERROR"])
+    args = ap.parse_args()
+
+    logging.basicConfig(
+        level=getattr(logging, args.log_level),
+        format="%(asctime)s  %(levelname)-7s  %(name)s  %(message)s",
+        stream=sys.stdout,
+    )
+
+    serve(args)
+
+
+if __name__ == "__main__":
+    main()

bridges/ach_server.py

@@ -0,0 +1,800 @@
+#!/usr/bin/env python3
+"""
+ach_server.py — Minimal inbound ACH (Auto Call Home) server for MiniMate Plus.
+
+This IS your test server.  Run it on any machine on the same network, point a
+unit's ACEmanager call-home destination at it, and it will speak the full BW
+protocol to the device: handshake, pull device info, download all events, save
+everything as JSON.
+
+The key thing this script tells you that no amount of packet sniffing can:
+  - Does the device speak first (push) or wait for us to send POLL (pull)?
+
+If startup() completes normally → it's pull protocol, same as Blastware.
+If startup() times out → the device sent something first; check raw_rx.bin.
+
+Usage
+-----
+  python bridges/ach_server.py [--port 12345] [--output bridges/captures/]
+
+Setup
+-----
+  1.  Run this script on a machine on your local network.
+  2.  In ACEmanager → Application → ALEOS Application Framework  (or equivalent)
+      find the Call Home / ACH settings.  Set:
+        Remote Host: <this machine's LAN IP>
+        Remote Port: 12345
+  3.  Trigger the unit (wait for a vibration event, or use the manual call-home
+      button if your firmware version has one).
+  4.  The unit connects.  This script handshakes, downloads all events,
+      and saves a timestamped session directory.
+
+Output per session
+------------------
+  bridges/captures/ach_inbound_<ts>/
+    device_info.json   — serial number, firmware version, calibration date, etc.
+    events.json        — all events: timestamp, PPV per channel, peaks, metadata
+    raw_rx_<ts>.bin    — raw bytes from the device (S3 side) for Analyzer
+    raw_tx_<ts>.bin    — raw bytes we sent to the device (BW side) for Analyzer
+    session_<ts>.log   — detailed protocol log
+
+What to look for
+----------------
+  Push vs pull: Check session_<ts>.log.  If the first line after "Connected"
+    shows bytes arriving BEFORE the POLL probe was sent, it's push.  If POLL
+    gets a clean response, it's pull.
+
+  Frequency: Look at raw_rx.bin in the Analyzer.  SUB 5A (0xA5 responses) carry
+    bulk waveform data — if frequency is sent pre-computed there will be float32
+    values before the ADC sample blocks.
+
+  ACH-specific framing: Does the unit send anything extra before the DLE+STX
+    framing starts?  raw_rx.bin will show raw bytes including any preamble.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import logging
+import socket
+import sys
+import threading
+from pathlib import Path
+from typing import Optional
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from minimateplus.transport import SocketTransport
+from minimateplus.client import MiniMateClient
+from minimateplus.models import DeviceInfo, Event, MonitorLogEntry
+from sfm.database import SeismoDb
+
+log = logging.getLogger("ach_server")
+
+# ── Per-unit state (downloaded-key set) ───────────────────────────────────────
+# Persisted as <output_dir>/ach_state.json
+# Format:
+#   {
+#     "BE11529": {
+#       "downloaded_keys":   ["01110000", "0111245a"],  # hex keys already on disk
+#       "max_downloaded_key": "0111245a",               # highest key ever seen
+#       "last_seen": "2026-04-11T01:04:36"
+#     }
+#   }
+#
+# Key-based deduplication works well within a single "key generation" (between
+# erases).  After the device memory is erased the event counter resets to
+# 0x01110000, so the first new event has the SAME key as the very first event
+# we ever downloaded.  We detect this situation with max_downloaded_key:
+#
+#   if max(current_device_keys) < max_downloaded_key
+#       → device was wiped and keys have restarted → treat all device keys as new
+#
+# After our own erase (--clear-after-download) we also explicitly clear
+# downloaded_keys and max_downloaded_key so the next session starts fresh.
+
+_state_lock = threading.Lock()
+
+
+def _load_state(state_path: Path) -> dict:
+    if state_path.exists():
+        try:
+            with open(state_path) as f:
+                return json.load(f)
+        except Exception:
+            pass
+    return {}
+
+
+def _save_state(state_path: Path, state: dict) -> None:
+    with _state_lock:
+        with open(state_path, "w") as f:
+            json.dump(state, f, indent=2)
+
+
+# ── Per-session handler ────────────────────────────────────────────────────────
+
+class AchSession:
+    """
+    Handles one inbound unit connection in its own thread.
+    Wraps the socket in a SocketTransport → MiniMateClient, then runs the
+    standard connect → get_device_info → get_events sequence.
+
+    State tracking (ach_state.json in output_dir):
+      On each successful download we record the SET of event keys downloaded.
+      On the next call-home we compare: if all device keys are already in the
+      set, there's nothing new.  If any key is new (including after the device
+      was wiped and re-recorded), we download and save only those events.
+    """
+
+    def __init__(
+        self,
+        sock: socket.socket,
+        peer: str,
+        output_dir: Path,
+        timeout: float,
+        events_only: bool,
+        max_events: Optional[int],
+        state_path: Path,
+        db: "SeismoDb",
+        clear_after_download: bool = False,
+        restart_monitoring: bool = False,
+    ) -> None:
+        self.sock                 = sock
+        self.peer                 = peer
+        self.output_dir           = output_dir
+        self.timeout              = timeout
+        self.events_only          = events_only
+        self.max_events           = max_events
+        self.state_path           = state_path
+        self.db                   = db
+        self.clear_after_download = clear_after_download
+        self.restart_monitoring   = restart_monitoring
+
+    def run(self) -> None:
+        ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+
+        # Session dir and file handler are created lazily — only after startup
+        # succeeds.  This prevents internet scanners and dropped connections from
+        # littering the output directory with empty session folders.
+        try:
+            self._run_inner(ts)
+        except Exception as exc:
+            log.error("Session failed (%s): %s", self.peer, exc, exc_info=True)
+        finally:
+            try:
+                self.sock.close()
+            except Exception:
+                pass
+
+    def _run_inner(self, ts: str) -> None:
+        transport = SocketTransport(self.sock, peer=self.peer)
+
+        # Collect raw bytes in memory until startup succeeds, then flush to disk.
+        raw_rx_buf: list[bytes] = []   # device → us  (S3 side)
+        raw_tx_buf: list[bytes] = []   # us → device  (BW side)
+        _orig_read  = transport.read
+        _orig_write = transport.write
+
+        def tapped_read(n: int) -> bytes:
+            data = _orig_read(n)
+            if data:
+                raw_rx_buf.append(data)
+            return data
+
+        def tapped_write(data: bytes) -> None:
+            _orig_write(data)
+            if data:
+                raw_tx_buf.append(data)
+
+        transport.read  = tapped_read   # type: ignore[method-assign]
+        transport.write = tapped_write  # type: ignore[method-assign]
+
+        serial: Optional[str] = None
+
+        # ── Step 1: startup handshake ─────────────────────────────────────────
+        # Do this BEFORE creating the session directory so that scanner probes
+        # and dropped connections leave no trace on disk.
+        try:
+            from minimateplus.protocol import MiniMateProtocol
+            client = MiniMateClient(transport=transport, timeout=self.timeout)
+            client.open()
+            proto = MiniMateProtocol(transport, recv_timeout=self.timeout)
+            proto.startup()
+        except Exception as exc:
+            log.warning("Startup failed from %s: %s -- ignoring", self.peer, exc)
+            return  # no session dir created
+
+        # Startup succeeded — this is a real unit.  Create session dir now.
+        session_dir = self.output_dir / f"ach_inbound_{ts}"
+        session_dir.mkdir(parents=True, exist_ok=True)
+        log_path   = session_dir / f"session_{ts}.log"
+        raw_rx_path = session_dir / f"raw_rx_{ts}.bin"   # device → us  (S3 side)
+        raw_tx_path = session_dir / f"raw_tx_{ts}.bin"   # us → device  (BW side)
+
+        # Flush buffered bytes to files and switch to direct file writes.
+        raw_rx_fh = open(raw_rx_path, "wb")
+        raw_tx_fh = open(raw_tx_path, "wb")
+        for chunk in raw_rx_buf:
+            raw_rx_fh.write(chunk)
+        for chunk in raw_tx_buf:
+            raw_tx_fh.write(chunk)
+        raw_rx_buf.clear()
+        raw_tx_buf.clear()
+
+        def tapped_read_file(n: int) -> bytes:
+            data = _orig_read(n)
+            if data:
+                raw_rx_fh.write(data)
+                raw_rx_fh.flush()
+            return data
+
+        def tapped_write_file(data: bytes) -> None:
+            _orig_write(data)
+            if data:
+                raw_tx_fh.write(data)
+                raw_tx_fh.flush()
+
+        transport.read  = tapped_read_file   # type: ignore[method-assign]
+        transport.write = tapped_write_file  # type: ignore[method-assign]
+
+        # Wire up file handler now that the session dir exists.
+        fh = logging.FileHandler(log_path, encoding="utf-8")
+        fh.setFormatter(logging.Formatter("%(asctime)s  %(levelname)-7s  %(name)s  %(message)s"))
+        root_logger = logging.getLogger()
+        root_logger.addHandler(fh)
+
+        try:
+            # ── Step 2: device info ───────────────────────────────────────────
+            device_info = None
+            if not self.events_only:
+                log.info("Step 2/3: reading device info")
+                try:
+                    device_info = client.connect()
+                    serial = device_info.serial
+                    _save_json(session_dir / "device_info.json", _device_info_to_dict(device_info))
+                    log.info(
+                        "  [OK] Device: serial=%s  firmware=%s  model=%s  events=%d",
+                        serial,
+                        device_info.firmware_version,
+                        device_info.model,
+                        device_info.event_count or 0,
+                    )
+                except Exception as exc:
+                    log.error("  [FAIL] Device info failed: %s", exc)
+            else:
+                log.info("Step 2/3: skipping device info (--events-only)")
+
+            # ── Step 3: check for new events by comparing key sets ────────────
+            log.info("Step 3/3: checking for new events")
+
+            state = _load_state(self.state_path)
+            unit_key = serial or self.peer  # fall back to IP if no serial
+            unit_state = state.get(unit_key, {})
+            seen_keys: set[str] = set(unit_state.get("downloaded_keys", []))
+            # Highest event key ever downloaded from this unit (hex string, 8 chars).
+            # Used to detect post-erase key reuse — see comment block above.
+            max_seen_key: str = unit_state.get("max_downloaded_key", "00000000")
+
+            # Walk the event index (browse-mode, no 5A) to get the actual current
+            # key list.  The SUB 08 event_count field is a lifetime "total events
+            # ever recorded" counter that does NOT decrement on erase — confirmed
+            # 2026-04-13.  list_event_keys() via the 1E/1F chain is the only
+            # reliable way to know what is actually stored on the device right now.
+            log.info("  Checking device key list (browse walk, no waveform download)...")
+            try:
+                device_keys = client.list_event_keys()
+            except Exception as exc:
+                log.warning("  list_event_keys failed: %s -- falling back to full download", exc)
+                device_keys = None
+
+            # Use the walk result as our authoritative current count.
+            current_count = len(device_keys) if device_keys is not None else 0
+
+            log.info("  Unit has %d stored event(s); %d key(s) previously downloaded",
+                     current_count, len(seen_keys))
+
+            if device_keys is not None and current_count == 0:
+                log.info("  [OK] No events on device -- nothing to download")
+                log.info("Session complete (no events) -> %s", session_dir)
+                return
+
+            if device_keys is not None:
+                # ── Post-erase detection ──────────────────────────────────────
+                # After the device memory is erased, new events start from key
+                # 01110000 again — the same keys we already downloaded.  Detect
+                # this by comparing the device's current highest key against the
+                # historical maximum.  If the device has rolled back below our
+                # high-water mark, its counter was reset and we must treat all
+                # its keys as new, regardless of what seen_keys contains.
+                if device_keys and max_seen_key != "00000000":
+                    max_device_key = max(device_keys)   # lexicographic; safe because
+                                                        # keys share the same 4-char prefix
+                    if max_device_key < max_seen_key:
+                        log.info(
+                            "  Post-erase reset detected: "
+                            "device max key %s < historical max %s "
+                            "-- treating all device keys as new",
+                            max_device_key, max_seen_key,
+                        )
+                        seen_keys = set()   # discard stale dedup info for this session
+
+                new_key_set = set(device_keys) - seen_keys
+                log.info("  Device has %d key(s): %d new, %d already seen",
+                         len(device_keys), len(new_key_set), len(device_keys) - len(new_key_set))
+                if not new_key_set:
+                    log.info("  [OK] All events already downloaded -- nothing to do")
+                    # Refresh state timestamp; preserve max_seen_key unchanged.
+                    state[unit_key] = {
+                        "downloaded_keys": sorted(seen_keys | set(device_keys)),
+                        "max_downloaded_key": max_seen_key,
+                        "last_seen":         datetime.datetime.now().isoformat(),
+                        "serial":            serial,
+                        "peer":              self.peer,
+                    }
+                    _save_state(self.state_path, state)
+
+                    # ── Erase even when no new events (if requested) ──────────
+                    # Blastware ACH always erases after every session — even when
+                    # nothing new was downloaded.  Without the erase the device
+                    # still sees stored events in its memory and immediately
+                    # retries the call-home, causing the looping we observed.
+                    # Only erase when device actually has events stored; skip
+                    # the erase if device_keys is empty (nothing to erase).
+                    if self.clear_after_download and device_keys:
+                        log.info(
+                            "  Clearing device memory (--clear-after-download, "
+                            "no new events but device has %d stored)...",
+                            len(device_keys),
+                        )
+                        try:
+                            client.delete_all_events()
+                            log.info("  [OK] Device memory cleared")
+                            # Reset state so the next session starts fresh.
+                            state[unit_key] = {
+                                "downloaded_keys":    [],
+                                "max_downloaded_key": "00000000",
+                                "last_seen":          datetime.datetime.now().isoformat(),
+                                "serial":             serial,
+                                "peer":               self.peer,
+                            }
+                            _save_state(self.state_path, state)
+                        except Exception as exc:
+                            log.error(
+                                "  [WARN] Event deletion failed: %s -- events NOT cleared",
+                                exc,
+                            )
+
+                    log.info("Session complete (no new events) -> %s", session_dir)
+                    return
+            else:
+                new_key_set = None  # unknown; proceed with full download
+
+            # Apply max_events cap
+            # stop_idx: when we know the count from list_event_keys, use it as
+            # an upper bound.  When list_event_keys failed (device_keys is None),
+            # pass None — get_events will run until the null sentinel naturally.
+            stop_idx: Optional[int] = (current_count - 1) if device_keys is not None else None
+            if self.max_events is not None:
+                cap = self.max_events - 1
+                stop_idx = cap if stop_idx is None else min(stop_idx, cap)
+                if device_keys is not None and self.max_events < current_count:
+                    log.warning(
+                        "  max_events=%d cap: will download events 0-%d only "
+                        "(unit has %d total)",
+                        self.max_events, stop_idx, current_count,
+                    )
+
+            try:
+                all_events = client.get_events(
+                    full_waveform=True,
+                    stop_after_index=stop_idx,
+                    skip_waveform_for_keys=seen_keys if seen_keys else None,
+                )
+
+                # Filter to events whose keys we haven't saved before.
+                new_events = [
+                    e for e in all_events
+                    if e._waveform_key is None
+                    or e._waveform_key.hex() not in seen_keys
+                ]
+                skipped = len(all_events) - len(new_events)
+
+                log.info("  [OK] Downloaded %d event(s): %d new, %d skipped (already seen)",
+                         len(all_events), len(new_events), skipped)
+                if skipped:
+                    log.info("  (skipped %d already-downloaded event(s))", skipped)
+
+                if new_events:
+                    _save_json(session_dir / "events.json", [_event_to_dict(e) for e in new_events])
+
+                    for ev in new_events:
+                        pv = ev.peak_values
+                        pi = ev.project_info
+                        key_hex = ev._waveform_key.hex() if ev._waveform_key else "????????"
+                        log.info(
+                            "  NEW [%s] %s  Tran=%.4f  Vert=%.4f  Long=%.4f  VS=%.4f  project=%r",
+                            key_hex,
+                            str(ev.timestamp) if ev.timestamp else "?",
+                            pv.tran            if pv else 0,
+                            pv.vert            if pv else 0,
+                            pv.long            if pv else 0,
+                            pv.peak_vector_sum if pv else 0,
+                            pi.project         if pi else "",
+                        )
+                else:
+                    log.info("  [OK] No new events since last call-home -- nothing to save")
+
+                # ── Monitor log entries (partial records / continuous monitoring) ──
+                # Browse walk (0A + 1F only) to collect monitor log entries for
+                # recording intervals where no threshold was crossed.  This is a
+                # second 1E-based pass over the device's record list, separate from
+                # the get_events() download loop above.
+                log.info("  Collecting monitor log entries (browse walk)...")
+                new_monitor_entries: list[MonitorLogEntry] = []
+                try:
+                    new_monitor_entries = client.get_monitor_log_entries(
+                        skip_keys=seen_keys if seen_keys else None,
+                    )
+                    if new_monitor_entries:
+                        _save_json(
+                            session_dir / "monitor_log.json",
+                            [_monitor_log_entry_to_dict(e) for e in new_monitor_entries],
+                        )
+                        log.info(
+                            "  [OK] %d new monitor log entry(s) saved",
+                            len(new_monitor_entries),
+                        )
+                        for ml in new_monitor_entries:
+                            log.info(
+                                "  MONLOG [%s] %s → %s (%s)",
+                                ml.key,
+                                ml.start_time.isoformat() if ml.start_time else "?",
+                                ml.stop_time.isoformat()  if ml.stop_time  else "?",
+                                f"{ml.duration_seconds:.0f}s" if ml.duration_seconds is not None else "?s",
+                            )
+                    else:
+                        log.info("  [OK] No new monitor log entries")
+                except Exception as exc:
+                    log.warning(
+                        "  [WARN] Monitor log collection failed: %s -- continuing",
+                        exc,
+                    )
+
+                # ── Persist to SQLite DB ─────────────────────────────────────
+                _session_start = datetime.datetime.now()
+                try:
+                    _ev_ins, _ev_skip = self.db.insert_events(
+                        new_events, serial=serial or self.peer, session_id=None
+                    )
+                    _ml_ins, _ml_skip = self.db.insert_monitor_log(
+                        new_monitor_entries, session_id=None
+                    )
+                    _session_id = self.db.insert_ach_session(
+                        serial=serial or self.peer,
+                        peer=self.peer,
+                        events_downloaded=_ev_ins,
+                        monitor_entries=_ml_ins,
+                        duration_seconds=(datetime.datetime.now() - _session_start).total_seconds(),
+                        session_time=_session_start,
+                    )
+                    log.info(
+                        "  [DB] session=%s  events +%d (skip %d)  monitor +%d (skip %d)",
+                        _session_id[:8], _ev_ins, _ev_skip, _ml_ins, _ml_skip,
+                    )
+                except Exception as exc:
+                    log.warning("  [WARN] DB write failed: %s -- continuing", exc)
+
+                # ── Optional: erase device memory after successful download ────
+                erased_successfully = False
+                if self.clear_after_download and new_events:
+                    log.info("  Clearing device memory (--clear-after-download)...")
+                    try:
+                        client.delete_all_events()
+                        log.info("  [OK] Device memory cleared")
+                        erased_successfully = True
+                    except Exception as exc:
+                        log.error(
+                            "  [WARN] Event deletion failed: %s -- events NOT cleared",
+                            exc,
+                        )
+
+                # ── Update persistent state ───────────────────────────────────
+                # Include both triggered-event keys and monitor-log keys in the
+                # downloaded set so they are not re-processed on the next call-home.
+                current_event_keys = [
+                    e._waveform_key.hex()
+                    for e in all_events
+                    if e._waveform_key is not None
+                ]
+                current_monitor_keys = [e.key for e in new_monitor_entries]
+                current_keys = current_event_keys + current_monitor_keys
+
+                if erased_successfully:
+                    # Device memory is clear. Reset downloaded_keys and the
+                    # high-water mark so the next call-home starts fresh and
+                    # doesn't mis-identify the recycled key 01110000 as "seen".
+                    updated_keys = []
+                    new_max_key  = "00000000"
+                    log.info(
+                        "  State reset after erase -- next session will download "
+                        "from key 0 (device counter resets after erase)"
+                    )
+                else:
+                    # Normal (no erase): union of previously-seen + all keys on
+                    # device now.  Includes already-seen survivors so we never
+                    # re-download them if the device somehow keeps old records.
+                    updated_keys = sorted(set(seen_keys) | set(current_keys))
+                    new_max_key  = updated_keys[-1] if updated_keys else max_seen_key
+
+                state[unit_key] = {
+                    "downloaded_keys":   updated_keys,
+                    "max_downloaded_key": new_max_key,
+                    "last_seen":          datetime.datetime.now().isoformat(),
+                    "serial":             serial,
+                    "peer":               self.peer,
+                }
+                _save_state(self.state_path, state)
+
+            except Exception as exc:
+                log.error("  [FAIL] Event download failed: %s", exc, exc_info=True)
+
+            # ── Optional: restart monitoring after successful download ─────────
+            if self.restart_monitoring:
+                log.info("  Restarting monitoring on device (--restart-monitoring)...")
+                try:
+                    client.start_monitoring()
+                    log.info("  [OK] Monitoring restarted")
+                except Exception as exc:
+                    log.warning("  [WARN] Failed to restart monitoring: %s", exc)
+
+        finally:
+            raw_rx_fh.close()
+            raw_tx_fh.close()
+            client.close()  # closes transport / socket cleanly
+            root_logger.removeHandler(fh)
+            fh.close()
+
+        log.info("Session complete -> %s", session_dir)
+        log.info("="*60)
+
+
+# ── JSON helpers ───────────────────────────────────────────────────────────────
+
+def _save_json(path: Path, obj: object) -> None:
+    with open(path, "w") as f:
+        json.dump(obj, f, indent=2, default=str)
+    log.debug("Saved %s", path)
+
+
+def _device_info_to_dict(d: DeviceInfo) -> dict:
+    cc = d.compliance_config
+    return {
+        "serial":            d.serial,
+        "firmware_version":  d.firmware_version,
+        "dsp_version":       d.dsp_version,
+        "model":             d.model,
+        "event_count":       d.event_count,
+        # compliance config fields (None if 1A read failed)
+        "setup_name":        cc.setup_name        if cc else None,
+        "sample_rate":       cc.sample_rate        if cc else None,
+        "record_time":       cc.record_time        if cc else None,
+        "trigger_level_geo": cc.trigger_level_geo  if cc else None,
+        "alarm_level_geo":   cc.alarm_level_geo    if cc else None,
+        "geo_adc_scale": cc.geo_adc_scale if cc else None,  # hw scale factor (in/s)/V
+        "geo_range":     cc.geo_range     if cc else None,  # 0x01=Normal 10in/s, 0x00=Sensitive 1.25in/s (unconfirmed)
+        "project":           cc.project            if cc else None,
+        "client":            cc.client             if cc else None,
+        "operator":          cc.operator           if cc else None,
+        "sensor_location":   cc.sensor_location    if cc else None,
+    }
+
+
+def _event_to_dict(e: Event) -> dict:
+    pv = e.peak_values
+    pi = e.project_info
+    peaks = {}
+    if pv:
+        peaks = {
+            "transverse":    pv.tran,
+            "vertical":      pv.vert,
+            "longitudinal":  pv.long,
+            "vector_sum":    pv.peak_vector_sum,
+            "mic":           pv.micl,
+        }
+    samples = {}
+    if e.raw_samples:
+        samples = {
+            ch: vals[:20]  # first 20 sample-sets to keep the file sane
+            for ch, vals in e.raw_samples.items()
+        }
+        samples["__note__"] = "first 20 sample-sets only; see raw_rx.bin for full waveform"
+    return {
+        "timestamp":       str(e.timestamp) if e.timestamp else None,
+        "project":         pi.project         if pi else None,
+        "client":          pi.client          if pi else None,
+        "operator":        pi.operator        if pi else None,
+        "sensor_location": pi.sensor_location if pi else None,
+        "peaks":           peaks,
+        "raw_samples_preview": samples,
+    }
+
+
+def _monitor_log_entry_to_dict(e: MonitorLogEntry) -> dict:
+    return {
+        "key":               e.key,
+        "start_time":        e.start_time.isoformat() if e.start_time else None,
+        "stop_time":         e.stop_time.isoformat()  if e.stop_time  else None,
+        "duration_seconds":  e.duration_seconds,
+        "serial":            e.serial,
+        "geo_threshold_ips": e.geo_threshold_ips,
+    }
+
+
+# ── Main server loop ───────────────────────────────────────────────────────────
+
+def serve(args: argparse.Namespace) -> None:
+    output_dir = Path(args.output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    state_path = output_dir / "ach_state.json"
+    db = SeismoDb(output_dir / "seismo_relay.db")
+
+    server_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    server_sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    server_sock.bind(("0.0.0.0", args.port))
+    server_sock.listen(5)
+    # Wake up every second so Ctrl-C is handled promptly on Windows.
+    # Without this, accept() blocks indefinitely and ignores KeyboardInterrupt.
+    server_sock.settimeout(1.0)
+
+    max_ev = args.max_events
+    print(f"\n{'='*60}")
+    print(f"  ACH inbound server  listening on 0.0.0.0:{args.port}")
+    print(f"  Output:     {output_dir.resolve()}/ach_inbound_<timestamp>/")
+    print(f"  State file: {state_path}")
+    print(f"  Max events per session: {max_ev if max_ev else 'unlimited'}")
+    print(f"  Clear device after download: {'YES' if args.clear_after_download else 'no'}")
+    print(f"  Restart monitoring after download: {'YES' if args.restart_monitoring else 'no'}")
+    print(f"{'='*60}")
+    print(f"\n  Point your test unit's ACEmanager call-home settings to:")
+    print(f"    Remote Host: <this machine's LAN IP>")
+    print(f"    Remote Port: {args.port}")
+    print(f"\n  Waiting for inbound connections...  (Ctrl-C to stop)\n")
+
+    allow_ips = set(args.allow_ips)
+    if allow_ips:
+        print(f"  Allowlist:  {', '.join(sorted(allow_ips))}")
+    else:
+        print("  Allowlist:  NONE -- accepting all IPs (add --allow-ip to restrict)")
+
+    try:
+        while True:
+            try:
+                client_sock, addr = server_sock.accept()
+            except socket.timeout:
+                continue  # no connection this second; loop back and check for Ctrl-C
+            try:
+                peer_ip = addr[0]
+                peer = f"{addr[0]}:{addr[1]}"
+
+                if allow_ips and peer_ip not in allow_ips:
+                    log.info("Rejected connection from %s (not in allowlist)", peer)
+                    client_sock.close()
+                    continue
+
+                log.info("Accepted connection from %s", peer)
+                session = AchSession(
+                    sock=client_sock,
+                    peer=peer,
+                    output_dir=output_dir,
+                    timeout=args.timeout,
+                    events_only=args.events_only,
+                    max_events=max_ev,
+                    state_path=state_path,
+                    db=db,
+                    clear_after_download=args.clear_after_download,
+                    restart_monitoring=args.restart_monitoring,
+                )
+                t = threading.Thread(target=session.run, daemon=True, name=f"ach-{peer}")
+                t.start()
+            except KeyboardInterrupt:
+                raise
+            except Exception as exc:
+                log.error("Accept error: %s", exc)
+    finally:
+        server_sock.close()
+        print("\nServer stopped.")
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        description="Minimal inbound ACH server — speak BW protocol to calling MiniMate Plus units.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    p.add_argument(
+        "--port", "-p",
+        type=int,
+        default=12345,
+        help="Port to listen on (default: 12345).",
+    )
+    p.add_argument(
+        "--output", "-o",
+        default=str(Path(__file__).parent / "captures"),
+        metavar="DIR",
+        help="Directory to write session captures (default: bridges/captures/).",
+    )
+    p.add_argument(
+        "--timeout", "-t",
+        type=float,
+        default=30.0,
+        help="Protocol receive timeout in seconds (default: 30.0).",
+    )
+    p.add_argument(
+        "--events-only",
+        action="store_true",
+        help="Skip the device-info step and go straight to event download.",
+    )
+    p.add_argument(
+        "--max-events",
+        type=int,
+        default=None,
+        metavar="N",
+        help=(
+            "Safety cap: download at most N events per session (default: unlimited). "
+            "Useful if a unit has many old events stored — prevents a very long first run."
+        ),
+    )
+    p.add_argument(
+        "--allow-ip",
+        metavar="IP",
+        action="append",
+        dest="allow_ips",
+        default=[],
+        help=(
+            "Only accept connections from this IP address (repeat for multiple). "
+            "Example: --allow-ip 63.43.212.232  "
+            "If not specified, all IPs are accepted (not recommended for public servers)."
+        ),
+    )
+    p.add_argument(
+        "--restart-monitoring",
+        action="store_true",
+        default=False,
+        help=(
+            "After downloading events, send SUB 0x96 (start monitoring) before "
+            "disconnecting. Required for RV55 units whose firmware does not assert "
+            "DCD on disconnect — without this the unit stays idle after a call-home."
+        ),
+    )
+    p.add_argument(
+        "--clear-after-download",
+        action="store_true",
+        default=False,
+        help=(
+            "After successfully downloading new events, erase all events from the "
+            "device memory (SUB 0xA3 → 0x1C → 0x06 → 0xA2 sequence, confirmed from "
+            "4-11-26 MITM capture). Only fires when at least one new event was saved. "
+            "This mirrors the standard Blastware ACH workflow."
+        ),
+    )
+    p.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        help="Enable debug logging.",
+    )
+    return p.parse_args()
+
+
+if __name__ == "__main__":
+    args = parse_args()
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s  %(levelname)-7s  %(name)s  %(message)s",
+    )
+    try:
+        serve(args)
+    except KeyboardInterrupt:
+        print("\nStopped.")

bridges/gui_bridge.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""
+gui_bridge.py — simple Tk GUI wrapper for s3_bridge.py (Windows-friendly).
+
+Features:
+  - Select BW and S3 COM ports, baud, log directory.
+  - Optional raw taps (BW->S3, S3->BW).
+  - Start/Stop buttons spawn/terminate s3_bridge as a subprocess.
+  - Live stdout view from the bridge process.
+
+Requires only the stdlib (Tkinter is bundled on Windows/Python).
+"""
+
+from __future__ import annotations
+
+import datetime
+import os
+import queue
+import subprocess
+import sys
+import threading
+import tkinter as tk
+from tkinter import filedialog, messagebox, scrolledtext, simpledialog
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+BRIDGE_PATH = os.path.join(SCRIPT_DIR, "s3-bridge", "s3_bridge.py")
+
+
+class BridgeGUI(tk.Tk):
+    def __init__(self) -> None:
+        super().__init__()
+        self.title("S3 Bridge GUI")
+        self.process: subprocess.Popen | None = None
+        self.stdout_q: queue.Queue[str] = queue.Queue()
+        self._build_widgets()
+        self._poll_stdout()
+
+    def _build_widgets(self) -> None:
+        pad = {"padx": 6, "pady": 4}
+
+        # Row 0: Ports
+        tk.Label(self, text="BW COM:").grid(row=0, column=0, sticky="e", **pad)
+        self.bw_var = tk.StringVar(value="COM4")
+        tk.Entry(self, textvariable=self.bw_var, width=10).grid(row=0, column=1, sticky="w", **pad)
+
+        tk.Label(self, text="S3 COM:").grid(row=0, column=2, sticky="e", **pad)
+        self.s3_var = tk.StringVar(value="COM5")
+        tk.Entry(self, textvariable=self.s3_var, width=10).grid(row=0, column=3, sticky="w", **pad)
+
+        # Row 1: Baud
+        tk.Label(self, text="Baud:").grid(row=1, column=0, sticky="e", **pad)
+        self.baud_var = tk.StringVar(value="38400")
+        tk.Entry(self, textvariable=self.baud_var, width=10).grid(row=1, column=1, sticky="w", **pad)
+
+        # Row 1: Logdir chooser
+        tk.Label(self, text="Log dir:").grid(row=1, column=2, sticky="e", **pad)
+        self.logdir_var = tk.StringVar(value=".")
+        tk.Entry(self, textvariable=self.logdir_var, width=24).grid(row=1, column=3, sticky="we", **pad)
+        tk.Button(self, text="Browse", command=self._choose_dir).grid(row=1, column=4, sticky="w", **pad)
+
+        # Row 2: Raw taps — ON by default; "auto" = timestamped name; blank checkbox = disabled
+        self.raw_bw_enabled = tk.IntVar(value=1)
+        self.raw_s3_enabled = tk.IntVar(value=1)
+        # Path fields: empty means "auto" (bridge picks a timestamped name)
+        self.raw_bw_path_var = tk.StringVar(value="")
+        self.raw_s3_path_var = tk.StringVar(value="")
+
+        tk.Checkbutton(self, text="BW→S3 raw (auto)", variable=self.raw_bw_enabled,
+                       command=self._toggle_raw_bw).grid(row=2, column=0, sticky="w", **pad)
+        tk.Entry(self, textvariable=self.raw_bw_path_var, width=28,
+                 fg="grey").grid(row=2, column=1, columnspan=3, sticky="we", **pad)
+        tk.Button(self, text="...", command=lambda: self._choose_file(self.raw_bw_path_var, "bw")).grid(row=2, column=4, **pad)
+
+        tk.Checkbutton(self, text="S3→BW raw (auto)", variable=self.raw_s3_enabled,
+                       command=self._toggle_raw_s3).grid(row=3, column=0, sticky="w", **pad)
+        tk.Entry(self, textvariable=self.raw_s3_path_var, width=28,
+                 fg="grey").grid(row=3, column=1, columnspan=3, sticky="we", **pad)
+        tk.Button(self, text="...", command=lambda: self._choose_file(self.raw_s3_path_var, "s3")).grid(row=3, column=4, **pad)
+
+        # Row 4: Status + buttons
+        self.status_var = tk.StringVar(value="Idle")
+        tk.Label(self, textvariable=self.status_var, anchor="w").grid(row=4, column=0, columnspan=5, sticky="we", **pad)
+
+        tk.Button(self, text="Start", command=self.start_bridge, width=12).grid(row=5, column=0, columnspan=2, **pad)
+        tk.Button(self, text="Stop", command=self.stop_bridge, width=12).grid(row=5, column=2, columnspan=2, **pad)
+        self.mark_btn = tk.Button(self, text="Add Mark", command=self.add_mark, width=12, state="disabled")
+        self.mark_btn.grid(row=5, column=4, **pad)
+
+        # Row 6: Log view
+        self.log_view = scrolledtext.ScrolledText(self, height=20, width=90, state="disabled")
+        self.log_view.grid(row=6, column=0, columnspan=5, sticky="nsew", **pad)
+
+        # Grid weights
+        for c in range(5):
+            self.grid_columnconfigure(c, weight=1)
+        self.grid_rowconfigure(6, weight=1)
+
+    def _choose_dir(self) -> None:
+        path = filedialog.askdirectory()
+        if path:
+            self.logdir_var.set(path)
+
+    def _choose_file(self, var: tk.StringVar, direction: str) -> None:
+        filename = filedialog.asksaveasfilename(
+            title=f"Raw tap file for {direction}",
+            defaultextension=".bin",
+            filetypes=[("Binary", "*.bin"), ("All files", "*.*")]
+        )
+        if filename:
+            var.set(filename)
+
+    def _toggle_raw_bw(self) -> None:
+        # Checkbox toggled — no path action needed; enabled state drives the flag.
+        pass
+
+    def _toggle_raw_s3(self) -> None:
+        pass
+
+    def start_bridge(self) -> None:
+        if self.process and self.process.poll() is None:
+            messagebox.showinfo("Bridge", "Bridge is already running.")
+            return
+
+        bw = self.bw_var.get().strip()
+        s3 = self.s3_var.get().strip()
+        baud = self.baud_var.get().strip()
+        logdir = self.logdir_var.get().strip() or "."
+
+        if not bw or not s3:
+            messagebox.showerror("Error", "Please enter both BW and S3 COM ports.")
+            return
+
+        args = [sys.executable, BRIDGE_PATH, "--bw", bw, "--s3", s3, "--baud", baud, "--logdir", logdir]
+
+        # Raw tap flags.
+        # Checkbox on + empty path → pass "auto" (bridge generates timestamped name).
+        # Checkbox on + explicit path → pass that path.
+        # Checkbox off → pass "" to disable (overrides bridge's auto default).
+        raw_bw_explicit = self.raw_bw_path_var.get().strip()
+        raw_s3_explicit = self.raw_s3_path_var.get().strip()
+
+        if self.raw_bw_enabled.get():
+            args += ["--raw-bw", raw_bw_explicit if raw_bw_explicit else "auto"]
+        else:
+            args += ["--raw-bw", ""]   # explicit disable
+
+        if self.raw_s3_enabled.get():
+            args += ["--raw-s3", raw_s3_explicit if raw_s3_explicit else "auto"]
+        else:
+            args += ["--raw-s3", ""]   # explicit disable
+
+        try:
+            self.process = subprocess.Popen(
+                args,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                stdin=subprocess.PIPE,
+                text=True,
+                bufsize=1,
+            )
+        except Exception as e:
+            messagebox.showerror("Error", f"Failed to start bridge: {e}")
+            return
+
+        threading.Thread(target=self._reader_thread, daemon=True).start()
+        self.status_var.set("Running...")
+        self._append_log("== Bridge started ==\n")
+        self.mark_btn.configure(state="normal")
+
+    def stop_bridge(self) -> None:
+        if self.process and self.process.poll() is None:
+            self.process.terminate()
+            try:
+                self.process.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                self.process.kill()
+        self.status_var.set("Stopped")
+        self._append_log("== Bridge stopped ==\n")
+        self.mark_btn.configure(state="disabled")
+
+    def _reader_thread(self) -> None:
+        if not self.process or not self.process.stdout:
+            return
+        for line in self.process.stdout:
+            self.stdout_q.put(line)
+        self.stdout_q.put("<<process-exit>>")
+
+    def add_mark(self) -> None:
+        if not self.process or not self.process.stdin or self.process.poll() is not None:
+            return
+        label = simpledialog.askstring("Mark", "Enter label for mark:", parent=self)
+        if label is None or label.strip() == "":
+            return
+        try:
+            # Mimic CLI behavior: send 'm' + Enter, then label + Enter
+            self.process.stdin.write("m\n")
+            self.process.stdin.write(label.strip() + "\n")
+            self.process.stdin.flush()
+            self._append_log(f"[GUI] Mark sent: {label.strip()}\n")
+        except Exception as e:
+            messagebox.showerror("Error", f"Failed to send mark: {e}")
+
+    def _poll_stdout(self) -> None:
+        try:
+            while True:
+                line = self.stdout_q.get_nowait()
+                if line == "<<process-exit>>":
+                    self.status_var.set("Stopped")
+                    self.mark_btn.configure(state="disabled")
+                    break
+                self._append_log(line)
+        except queue.Empty:
+            pass
+        finally:
+            self.after(100, self._poll_stdout)
+
+    def _append_log(self, text: str) -> None:
+        self.log_view.configure(state="normal")
+        self.log_view.insert(tk.END, text)
+        self.log_view.see(tk.END)
+        self.log_view.configure(state="disabled")
+
+
+def main() -> int:
+    app = BridgeGUI()
+    app.mainloop()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bridges/raw_capture.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""
+raw_capture.py — minimal serial logger for raw byte collection.
+
+Opens a single COM port, streams all bytes to a timestamped binary file,
+and does no parsing or forwarding. Useful when you just need the raw
+wire data without DLE framing or Blastware bridging.
+
+Record format (little-endian):
+  [ts_us:8][len:4][payload:len]
+Exactly one record type is used, so there is no type byte.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import os
+import signal
+import sys
+import time
+from typing import Optional
+
+import serial
+
+
+def now_ts() -> str:
+    t = _dt.datetime.now()
+    return t.strftime("%H:%M:%S.") + f"{int(t.microsecond/1000):03d}"
+
+
+def pack_u32_le(n: int) -> bytes:
+    return bytes((n & 0xFF, (n >> 8) & 0xFF, (n >> 16) & 0xFF, (n >> 24) & 0xFF))
+
+
+def pack_u64_le(n: int) -> bytes:
+    out = []
+    for i in range(8):
+        out.append((n >> (8 * i)) & 0xFF)
+    return bytes(out)
+
+
+def open_serial(port: str, baud: int, timeout: float) -> serial.Serial:
+    return serial.Serial(
+        port=port,
+        baudrate=baud,
+        bytesize=serial.EIGHTBITS,
+        parity=serial.PARITY_NONE,
+        stopbits=serial.STOPBITS_ONE,
+        timeout=timeout,
+        write_timeout=timeout,
+    )
+
+
+class RawWriter:
+    def __init__(self, path: str):
+        self.path = path
+        self._fh = open(path, "ab", buffering=0)
+
+    def write(self, payload: bytes, ts_us: Optional[int] = None) -> None:
+        if ts_us is None:
+            ts_us = int(time.time() * 1_000_000)
+        header = pack_u64_le(ts_us) + pack_u32_le(len(payload))
+        self._fh.write(header)
+        if payload:
+            self._fh.write(payload)
+
+    def close(self) -> None:
+        try:
+            self._fh.flush()
+        finally:
+            self._fh.close()
+
+
+def capture_loop(port: serial.Serial, writer: RawWriter, stop_flag: "StopFlag", status_every_s: float) -> None:
+    last_status = time.monotonic()
+    bytes_written = 0
+
+    while not stop_flag.is_set():
+        try:
+            n = port.in_waiting
+            chunk = port.read(n if n and n < 4096 else (4096 if n else 1))
+        except serial.SerialException as e:
+            print(f"[{now_ts()}] [ERROR] serial exception: {e!r}", file=sys.stderr)
+            break
+
+        if chunk:
+            writer.write(chunk)
+            bytes_written += len(chunk)
+
+        if status_every_s > 0:
+            now = time.monotonic()
+            if now - last_status >= status_every_s:
+                print(f"[{now_ts()}] captured {bytes_written} bytes", flush=True)
+                last_status = now
+
+        if not chunk:
+            time.sleep(0.002)
+
+
+class StopFlag:
+    def __init__(self):
+        self._set = False
+
+    def set(self):
+        self._set = True
+
+    def is_set(self) -> bool:
+        return self._set
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Raw serial capture to timestamped binary file (no forwarding).")
+    ap.add_argument("--port", default="COM5", help="Serial port to capture (default: COM5)")
+    ap.add_argument("--baud", type=int, default=38400, help="Baud rate (default: 38400)")
+    ap.add_argument("--timeout", type=float, default=0.05, help="Serial read timeout in seconds (default: 0.05)")
+    ap.add_argument("--logdir", default=".", help="Directory to write captures (default: .)")
+    ap.add_argument("--status-every", type=float, default=5.0, help="Seconds between progress lines (0 disables)")
+    args = ap.parse_args()
+
+    os.makedirs(args.logdir, exist_ok=True)
+    ts = _dt.datetime.now().strftime("%Y%m%d_%H%M%S")
+    bin_path = os.path.join(args.logdir, f"raw_capture_{ts}.bin")
+
+    print(f"[INFO] Opening {args.port} @ {args.baud}...")
+    try:
+        ser = open_serial(args.port, args.baud, args.timeout)
+    except Exception as e:
+        print(f"[ERROR] failed to open port: {e!r}", file=sys.stderr)
+        return 2
+
+    writer = RawWriter(bin_path)
+    print(f"[INFO] Writing raw bytes to {bin_path}")
+    print("[INFO] Press Ctrl+C to stop.")
+
+    stop = StopFlag()
+
+    def handle_sigint(sig, frame):
+        stop.set()
+
+    signal.signal(signal.SIGINT, handle_sigint)
+
+    try:
+        capture_loop(ser, writer, stop, args.status_every)
+    finally:
+        writer.close()
+        try:
+            ser.close()
+        except Exception:
+            pass
+        print(f"[INFO] Capture stopped. Total bytes written: {os.path.getsize(bin_path)}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bridges/s3-bridge/s3_bridge.py

@@ -1,29 +1,25 @@
 #!/usr/bin/env python3
 """
-s3_bridge.py — S3 <-> Blastware serial bridge with frame-aware session logging
-Version: v0.4.0
+s3_bridge.py — S3 <-> Blastware serial bridge with raw binary capture + DLE-aware text framing
+Version: v0.5.1
 
-Key features:
-- Low CPU: avoids per-byte console printing
-- Forwards bytes immediately (true bridge)
-- Frame-aware logging: buffers per direction until ETX (0x03), then logs full frame on one line
-- Also logs plain ASCII bursts (e.g., "Operating System") cleanly
-- Dual log output: hex text log (.log) AND raw binary log (.bin) written simultaneously
-- Interactive annotation: type 'm' + Enter to stamp a [MARK] into both logs mid-capture
-- Binary sentinel markers: out-of-band FF FF FF FF <len> <label> in .bin for programmatic correlation
-- Auto-marks on session start and end
+What’s new vs v0.4.0:
+- .bin is now a TRUE raw capture stream with direction + timestamps (record container format).
+- .log remains human-friendly and frame-oriented, but frame detection is now DLE-aware:
+    - frame start = 0x10 0x02 (DLE STX)
+    - frame end   = 0x10 0x03 (DLE ETX)
+  (No longer splits on bare 0x03.)
+- Marks/Info are stored as proper record types in .bin (no unsafe sentinel bytes).
+- Optional raw taps: use --raw-bw / --raw-s3 to also dump byte-for-byte traffic per direction
+  with no headers (for tools that just need a flat stream).
 
-Usage examples:
-  python s3_bridge.py
-  python s3_bridge.py --bw COM5 --s3 COM4 --baud 38400
-  python s3_bridge.py --quiet
-
-Annotation:
-  While running, type 'm' and press Enter. You will be prompted for a label.
-  The mark is written to the .log as:
-      [HH:MM:SS.mmm] >>> MARK: your label here
-  And to the .bin as an out-of-band sentinel (never valid frame data):
-      FF FF FF FF <1-byte length> <label bytes>
+BIN record format (little-endian):
+  [type:1][ts_us:8][len:4][payload:len]
+Types:
+  0x01 BW->S3 bytes
+  0x02 S3->BW bytes
+  0x03 MARK (utf-8)
+  0x04 INFO (utf-8)
 """
 
 from __future__ import annotations
@@ -39,68 +35,134 @@ from typing import Optional
 
 import serial
 
+VERSION = "v0.5.1"
 
-VERSION = "v0.4.0"
+DLE = 0x10
+STX = 0x02
+ETX = 0x03
+ACK = 0x41
 
-# Sentinel prefix for binary markers. Four 0xFF bytes can never appear in
-# valid Instantel DLE-framed data (0xFF is not a legal protocol byte in any
-# framing position), so this sequence is unambiguously out-of-band.
-BIN_MARK_SENTINEL = b"\xFF\xFF\xFF\xFF"
+REC_BW = 0x01
+REC_S3 = 0x02
+REC_MARK = 0x03
+REC_INFO = 0x04
 
 
 def now_ts() -> str:
-    # Local time with milliseconds, like [13:37:06.239]
     t = _dt.datetime.now()
     return t.strftime("%H:%M:%S.") + f"{int(t.microsecond/1000):03d}"
 
 
+def now_us() -> int:
+    # Wall-clock microseconds (fine for correlation). If you want monotonic, we can switch.
+    return int(time.time() * 1_000_000)
+
+
 def bytes_to_hex(b: bytes) -> str:
     return " ".join(f"{x:02X}" for x in b)
 
 
 def looks_like_text(b: bytes) -> bool:
-    # Heuristic: mostly printable ASCII plus spaces
     if not b:
         return False
     printable = 0
     for x in b:
-        if x in (9, 10, 13):  # \t \n \r
+        if x in (9, 10, 13):
             printable += 1
         elif 32 <= x <= 126:
             printable += 1
     return (printable / len(b)) >= 0.90
 
 
+def pack_u32_le(n: int) -> bytes:
+    return bytes((n & 0xFF, (n >> 8) & 0xFF, (n >> 16) & 0xFF, (n >> 24) & 0xFF))
+
+
+def pack_u64_le(n: int) -> bytes:
+    out = []
+    for i in range(8):
+        out.append((n >> (8 * i)) & 0xFF)
+    return bytes(out)
+
+
 class SessionLogger:
-    def __init__(self, path: str, bin_path: str):
+    def __init__(self, path: str, bin_path: str, raw_bw_path: Optional[str] = None, raw_s3_path: Optional[str] = None):
         self.path = path
         self.bin_path = bin_path
         self._fh = open(path, "a", buffering=1, encoding="utf-8", errors="replace")
         self._bin_fh = open(bin_path, "ab", buffering=0)
         self._lock = threading.Lock()
+        # Optional pure-byte taps (no headers). BW=Blastware tx, S3=device tx.
+        # These can be opened/closed on demand via start_raw_capture/stop_raw_capture.
+        self._raw_bw = open(raw_bw_path, "ab", buffering=0) if raw_bw_path else None
+        self._raw_s3 = open(raw_s3_path, "ab", buffering=0) if raw_s3_path else None
+        self._cap_bw_path: Optional[str] = raw_bw_path
+        self._cap_s3_path: Optional[str] = raw_s3_path
 
     def log_line(self, line: str) -> None:
         with self._lock:
             self._fh.write(line + "\n")
 
-    def log_raw(self, data: bytes) -> None:
-        """Write raw bytes directly to the binary log."""
+    def bin_write_record(self, rec_type: int, payload: bytes, ts_us: Optional[int] = None) -> None:
+        if ts_us is None:
+            ts_us = now_us()
+        header = bytes([rec_type]) + pack_u64_le(ts_us) + pack_u32_le(len(payload))
         with self._lock:
-            self._bin_fh.write(data)
+            self._bin_fh.write(header)
+            if payload:
+                self._bin_fh.write(payload)
+            # Raw taps: write only the payload bytes (no headers)
+            if rec_type == REC_BW and self._raw_bw:
+                self._raw_bw.write(payload)
+            if rec_type == REC_S3 and self._raw_s3:
+                self._raw_s3.write(payload)
 
     def log_mark(self, label: str) -> None:
-        """
-        Write an annotation mark to both logs simultaneously.
-
-        .log  — visually distinct line: [TS] >>> MARK: label
-        .bin  — out-of-band sentinel: FF FF FF FF <len> <label utf-8, max 255 bytes>
-        """
         ts = now_ts()
-        label_bytes = label.encode("utf-8", errors="replace")[:255]
-        sentinel = BIN_MARK_SENTINEL + bytes([len(label_bytes)]) + label_bytes
+        self.log_line(f"[{ts}] >>> MARK: {label}")
+        self.bin_write_record(REC_MARK, label.encode("utf-8", errors="replace"))
+
+    def log_info(self, msg: str) -> None:
+        ts = now_ts()
+        self.log_line(f"[{ts}] [INFO] {msg}")
+        self.bin_write_record(REC_INFO, msg.encode("utf-8", errors="replace"))
+
+    def start_raw_capture(self, label: str, logdir: str) -> tuple:
+        """Open new raw tap files for a named capture.  Returns (bw_path, s3_path)."""
+        ts = _dt.datetime.now().strftime("%Y%m%d_%H%M%S")
+        safe = "".join(c if c.isalnum() or c in "-_" else "_" for c in label)[:40] if label else ""
+        suffix = f"_{safe}" if safe else ""
+        bw_path = os.path.join(logdir, f"raw_bw_{ts}{suffix}.bin")
+        s3_path = os.path.join(logdir, f"raw_s3_{ts}{suffix}.bin")
         with self._lock:
-            self._fh.write(f"[{ts}] >>> MARK: {label}\n")
-            self._bin_fh.write(sentinel)
+            # Close any previously open taps first
+            if self._raw_bw:
+                self._raw_bw.close()
+            if self._raw_s3:
+                self._raw_s3.close()
+            self._raw_bw = open(bw_path, "ab", buffering=0)
+            self._raw_s3 = open(s3_path, "ab", buffering=0)
+            self._cap_bw_path = bw_path
+            self._cap_s3_path = s3_path
+        self.log_info(f"raw capture started: label={label!r} bw={bw_path} s3={s3_path}")
+        return bw_path, s3_path
+
+    def stop_raw_capture(self) -> tuple:
+        """Close raw tap files.  Returns (bw_path, s3_path) for the capture just closed."""
+        with self._lock:
+            bw = self._cap_bw_path
+            s3 = self._cap_s3_path
+            if self._raw_bw:
+                self._raw_bw.close()
+                self._raw_bw = None
+            if self._raw_s3:
+                self._raw_s3.close()
+                self._raw_s3 = None
+            self._cap_bw_path = None
+            self._cap_s3_path = None
+        if bw:
+            self.log_info(f"raw capture stopped: bw={bw} s3={s3}")
+        return bw, s3
 
     def close(self) -> None:
         with self._lock:
@@ -110,53 +172,93 @@ class SessionLogger:
             finally:
                 self._fh.close()
                 self._bin_fh.close()
+                if self._raw_bw:
+                    self._raw_bw.close()
+                if self._raw_s3:
+                    self._raw_s3.close()
 
 
-class FrameAssembler:
+class DLEFrameSniffer:
     """
-    Maintains a rolling buffer of bytes for one direction and emits complete frames.
-    We treat ETX=0x03 as an end-of-frame marker.
+    DLE-aware sniffer for logging only.
+    Extracts:
+      - ACK bytes (0x41) as single-byte events
+      - DLE-framed blocks starting at 10 02 and ending at 10 03
+      - Occasional ASCII bursts (e.g. "Operating System") outside framing
+    It does NOT modify bytes; it just segments them for the .log.
     """
     def __init__(self):
         self.buf = bytearray()
 
-    def push(self, chunk: bytes) -> list[bytes]:
+    def push(self, chunk: bytes) -> list[tuple[str, bytes]]:
         if chunk:
             self.buf.extend(chunk)
 
-        frames: list[bytes] = []
+        events: list[tuple[str, bytes]] = []
+
+        # Opportunistically peel off leading ACK(s) when idle-ish.
+        # We do this only when an ACK is not inside a frame (frames start with DLE).
+        while self.buf and self.buf[0] == ACK:
+            events.append(("ACK", bytes([ACK])))
+            del self.buf[0]
+
+        # Try to parse frames: find DLE STX then scan for DLE ETX
         while True:
-            try:
-                etx_i = self.buf.index(0x03)
-            except ValueError:
+            # Find start of frame
+            start = self._find_dle_stx(self.buf)
+            if start is None:
+                # No frame start. Maybe text?
+                txt = bytes(self.buf)
+                if looks_like_text(txt):
+                    events.append(("TEXT", txt))
+                    self.buf.clear()
                 break
 
-            # include ETX byte
-            frame = bytes(self.buf[: etx_i + 1])
-            del self.buf[: etx_i + 1]
+            # Emit any leading text before the frame
+            if start > 0:
+                leading = bytes(self.buf[:start])
+                if looks_like_text(leading):
+                    events.append(("TEXT", leading))
+                else:
+                    # Unknown junk; still preserve in log as RAW so you can see it
+                    events.append(("RAW", leading))
+                del self.buf[:start]
 
-            # ignore empty noise
-            if frame:
-                frames.append(frame)
+            # Now buf starts with DLE STX
+            end = self._find_dle_etx(self.buf)
+            if end is None:
+                break  # need more bytes
 
-        return frames
+            frame = bytes(self.buf[:end])
+            del self.buf[:end]
 
-    def drain_as_text_if_any(self) -> Optional[bytes]:
-        """
-        If buffer contains non-framed data (no ETX) and looks like text, emit it.
-        Useful for things like "Operating System" that come as raw ASCII.
-        """
-        if not self.buf:
+            events.append(("FRAME", frame))
+
+            # peel off any ACKs that may immediately follow
+            while self.buf and self.buf[0] == ACK:
+                events.append(("ACK", bytes([ACK])))
+                del self.buf[0]
+
+        return events
+
+    @staticmethod
+    def _find_dle_stx(b: bytearray) -> Optional[int]:
+        for i in range(len(b) - 1):
+            if b[i] == DLE and b[i + 1] == STX:
+                return i
         return None
-        b = bytes(self.buf)
-        if looks_like_text(b):
-            self.buf.clear()
-            return b
+
+    @staticmethod
+    def _find_dle_etx(b: bytearray) -> Optional[int]:
+        # Find first occurrence of DLE ETX after the initial DLE STX.
+        # Return index *after* ETX (slice end).
+        for i in range(2, len(b) - 1):
+            if b[i] == DLE and b[i + 1] == ETX:
+                return i + 2
         return None
 
 
 def open_serial(port: str, baud: int) -> serial.Serial:
-    # timeout keeps read() from blocking forever, enabling clean Ctrl+C shutdown
     return serial.Serial(
         port=port,
         baudrate=baud,
@@ -170,6 +272,7 @@ def open_serial(port: str, baud: int) -> serial.Serial:
 
 def forward_loop(
     name: str,
+    rec_type: int,
     src: serial.Serial,
     dst: serial.Serial,
     logger: SessionLogger,
@@ -177,22 +280,24 @@ def forward_loop(
     quiet: bool,
     status_every_s: float,
 ) -> None:
-    assembler = FrameAssembler()
+    sniffer = DLEFrameSniffer()
     last_status = time.monotonic()
 
     while not stop.is_set():
         try:
             n = src.in_waiting
-            if n:
-                chunk = src.read(n if n < 4096 else 4096)
-            else:
-                chunk = src.read(1)  # will return b"" after timeout
+            chunk = src.read(n if n and n < 4096 else (4096 if n else 1))
         except serial.SerialException as e:
             logger.log_line(f"[{now_ts()}] [ERROR] {name} serial exception: {e!r}")
             break
 
         if chunk:
-            # forward immediately
+            ts = now_us()
+
+            # 1) RAW BIN CAPTURE (absolute truth)
+            logger.bin_write_record(rec_type, chunk, ts_us=ts)
+
+            # 2) Forward immediately (bridge behavior)
             try:
                 dst.write(chunk)
             except serial.SerialTimeoutException:
@@ -201,57 +306,68 @@ def forward_loop(
                 logger.log_line(f"[{now_ts()}] [ERROR] {name} dst write exception: {e!r}")
                 break
 
-            # frame-aware logging
-            frames = assembler.push(chunk)
-            for frame in frames:
-                # Some devices send leading STX separately; we still log as-is.
-                logger.log_line(f"[{now_ts()}] [{name}] {bytes_to_hex(frame)}")
-                logger.log_raw(frame)
-
-            # If we have non-ETX data that looks like text, flush it as TEXT
-            text = assembler.drain_as_text_if_any()
-            if text is not None:
+            # 3) Human-friendly .log segmentation (DLE-aware)
+            for kind, payload in sniffer.push(chunk):
+                if kind == "ACK":
+                    logger.log_line(f"[{now_ts()}] [{name}] [ACK] 41")
+                elif kind == "FRAME":
+                    logger.log_line(f"[{now_ts()}] [{name}] {bytes_to_hex(payload)}")
+                elif kind == "TEXT":
                     try:
-                    s = text.decode("ascii", errors="replace").strip("\r\n")
+                        s = payload.decode("ascii", errors="replace").strip("\r\n")
                     except Exception:
-                    s = repr(text)
+                        s = repr(payload)
                     logger.log_line(f"[{now_ts()}] [{name}] [TEXT] {s}")
-                logger.log_raw(text)
+                else:  # RAW
+                    logger.log_line(f"[{now_ts()}] [{name}] [RAW] {bytes_to_hex(payload)}")
 
-        # minimal console heartbeat (cheap)
         if not quiet and status_every_s > 0:
             now = time.monotonic()
             if (now - last_status) >= status_every_s:
                 print(f"[{now_ts()}] {name} alive")
                 last_status = now
 
-        # tiny sleep only when idle to avoid spin
         if not chunk:
             time.sleep(0.002)
 
 
-def annotation_loop(logger: SessionLogger, stop: threading.Event) -> None:
+def annotation_loop(logger: SessionLogger, logdir: str, stop: threading.Event) -> None:
     """
-    Runs on the main thread (or a dedicated thread) reading stdin.
-    Type 'm' + Enter to trigger an annotation prompt.
-    Any other non-empty input is ignored with a hint.
-    Bare Enter (empty line) is silently ignored to prevent accidental marks.
+    Reads stdin commands while the bridge runs.
+
+    Commands:
+      m                      — prompt for a mark label (interactive)
+      CAP_START:<label>      — begin a raw tap capture with the given label
+      CAP_STOP               — stop the current raw tap capture
+    Responses (printed to stdout, parsed by the GUI):
+      [CAP_START] <bw_path>\\t<s3_path>
+      [CAP_STOP]  <bw_path>\\t<s3_path>
     """
-    print("[MARK] Type 'm' + Enter to annotate the capture. Ctrl+C to stop.")
     while not stop.is_set():
         try:
             line = input()
-        except EOFError:
-            # stdin closed (e.g. piped input exhausted)
-            break
-        except KeyboardInterrupt:
+        except (EOFError, KeyboardInterrupt):
             break
 
         line = line.strip()
         if not line:
-            continue  # bare Enter — ignore silently
+            continue
 
-        if line.lower() == "m":
+        if line.startswith("CAP_START:"):
+            label = line[10:].strip()
+            bw_path, s3_path = logger.start_raw_capture(label, logdir)
+            print(f"[CAP_START] {bw_path}\t{s3_path}")
+            sys.stdout.flush()
+
+        elif line == "CAP_STOP":
+            bw_path, s3_path = logger.stop_raw_capture()
+            if bw_path:
+                print(f"[CAP_STOP] {bw_path}\t{s3_path}")
+            else:
+                print("[CAP_STOP] no active capture")
+            sys.stdout.flush()
+
+        elif line.lower() == "m":
             try:
                 sys.stdout.write("  Label: ")
                 sys.stdout.flush()
@@ -263,16 +379,25 @@ def annotation_loop(logger: SessionLogger, stop: threading.Event) -> None:
                 print(f"  [MARK written] {label}")
             else:
                 print("  (empty label — mark cancelled)")
+
         else:
-            print("  (type 'm' + Enter to annotate)")
+            print(f"  (unknown command: {line!r})")
 
 
 def main() -> int:
     ap = argparse.ArgumentParser()
-    ap.add_argument("--bw", default="COM5", help="Blastware-side COM port (default: COM5)")
-    ap.add_argument("--s3", default="COM4", help="S3-side COM port (default: COM4)")
+    ap.add_argument("--bw", default="COM4", help="Blastware-side COM port (default: COM4)")
+    ap.add_argument("--s3", default="COM5", help="S3-side COM port (default: COM5)")
     ap.add_argument("--baud", type=int, default=38400, help="Baud rate (default: 38400)")
     ap.add_argument("--logdir", default=".", help="Directory to write session logs into (default: .)")
+    ap.add_argument("--raw-bw", default="auto",
+                    help="File to append raw bytes sent from BW->S3 (no headers). "
+                         "Default 'auto' generates a timestamped name in --logdir. "
+                         "Pass an empty string to disable.")
+    ap.add_argument("--raw-s3", default="auto",
+                    help="File to append raw bytes sent from S3->BW (no headers). "
+                         "Default 'auto' generates a timestamped name in --logdir. "
+                         "Pass an empty string to disable.")
     ap.add_argument("--quiet", action="store_true", help="No console heartbeat output")
     ap.add_argument("--status-every", type=float, default=0.0, help="Seconds between console heartbeat lines (default: 0 = off)")
     args = ap.parse_args()
@@ -291,12 +416,32 @@ def main() -> int:
     ts = _dt.datetime.now().strftime("%Y%m%d_%H%M%S")
     log_path = os.path.join(args.logdir, f"s3_session_{ts}.log")
     bin_path = os.path.join(args.logdir, f"s3_session_{ts}.bin")
-    logger = SessionLogger(log_path, bin_path)
+
+    # If raw tap flags were passed without a path (bare --raw-bw / --raw-s3),
+    # or if the sentinel value "auto" is used, generate a timestamped name.
+    # If a specific path was provided, use it as-is (caller's responsibility).
+    # Resolve raw tap paths.
+    # "auto" (default) → timestamped file in logdir (always captured).
+    # Explicit path     → use verbatim.
+    # None or ""        → disabled (pass --raw-bw "" to suppress capture).
+    raw_bw_path: Optional[str] = args.raw_bw if args.raw_bw else None
+    raw_s3_path: Optional[str] = args.raw_s3 if args.raw_s3 else None
+    if raw_bw_path == "auto":
+        raw_bw_path = os.path.join(args.logdir, f"raw_bw_{ts}.bin")
+    if raw_s3_path == "auto":
+        raw_s3_path = os.path.join(args.logdir, f"raw_s3_{ts}.bin")
+
+    logger = SessionLogger(log_path, bin_path, raw_bw_path=raw_bw_path, raw_s3_path=raw_s3_path)
+
     print(f"[LOG] Writing hex log to  {log_path}")
     print(f"[LOG] Writing binary log to {bin_path}")
+    if raw_bw_path:
+        print(f"[LOG] Raw tap BW->S3  -> {raw_bw_path}")
+    if raw_s3_path:
+        print(f"[LOG] Raw tap S3->BW -> {raw_s3_path}")
 
-    logger.log_line(f"[{now_ts()}] [INFO] s3_bridge {VERSION} start")
-    logger.log_line(f"[{now_ts()}] [INFO] BW={args.bw} S3={args.s3} baud={args.baud}")
+    logger.log_info(f"s3_bridge {VERSION} start")
+    logger.log_info(f"BW={args.bw} S3={args.s3} baud={args.baud}")
     logger.log_mark(f"SESSION START — BW={args.bw} S3={args.s3} baud={args.baud}")
 
     stop = threading.Event()
@@ -309,20 +454,19 @@ def main() -> int:
     t1 = threading.Thread(
         target=forward_loop,
         name="BW_to_S3",
-        args=("BW->S3", bw, s3, logger, stop, args.quiet, args.status_every),
+        args=("BW->S3", REC_BW, bw, s3, logger, stop, args.quiet, args.status_every),
         daemon=True,
     )
     t2 = threading.Thread(
         target=forward_loop,
         name="S3_to_BW",
-        args=("S3->BW", s3, bw, logger, stop, args.quiet, args.status_every),
+        args=("S3->BW", REC_S3, s3, bw, logger, stop, args.quiet, args.status_every),
         daemon=True,
     )
-    # Annotation loop runs in its own daemon thread so it doesn't block shutdown
     t_ann = threading.Thread(
         target=annotation_loop,
         name="Annotator",
-        args=(logger, stop),
+        args=(logger, args.logdir, stop),
         daemon=True,
     )
 
@@ -335,12 +479,11 @@ def main() -> int:
             time.sleep(0.05)
     finally:
         print("\n[INFO] Ctrl+C detected, shutting down...")
-        logger.log_line(f"[{now_ts()}] [INFO] shutdown requested")
+        logger.log_info("shutdown requested")
 
         stop.set()
         t1.join(timeout=1.0)
         t2.join(timeout=1.0)
-        # t_ann is daemon — don't join, it may be blocked on input()
 
         try:
             bw.close()
@@ -352,8 +495,7 @@ def main() -> int:
             pass
 
         logger.log_mark("SESSION END")
-        logger.log_line(f"[{now_ts()}] [INFO] ports closed, session end")
-        print("[LOG] Closing session log")
+        logger.log_info("ports closed, session end")
         logger.close()
 
     return 0

bridges/serial_watch.py

@@ -0,0 +1,435 @@
+#!/usr/bin/env python3
+"""
+serial_watch.py — Instantel Series-3 serial monitor with S3 frame parsing.
+
+Taps the RS-232 line between the MiniMate Plus and its modem (RV50/RV55).
+Saves raw binary captures compatible with the rest of the analysis toolchain,
+plus a human-readable frame log.
+
+Usage
+-----
+  python bridges/serial_watch.py                        # interactive COM picker
+  python bridges/serial_watch.py --port COM3            # specify port
+  python bridges/serial_watch.py --port COM3 --ack-ok   # reply OK to AT commands
+                                                         # (useful if modem is absent
+                                                         #  and you want the device to
+                                                         #  proceed past AT negotiation)
+  python bridges/serial_watch.py --list                  # list available ports
+
+Output
+------
+  bridges/captures/serial_<ISO-timestamp>/
+    raw_s3_<ts>.bin    — raw bytes from device (feeds directly into S3FrameParser)
+    session_<ts>.log   — human-readable frame + control-line log
+    session_<ts>.jsonl — JSON-lines frame log
+
+The raw_s3_*.bin file is byte-for-byte compatible with the existing capture
+format used by bridges/parse_capture.py and all analysis scripts.
+
+What to look for in a call-home capture
+----------------------------------------
+1. Does the device talk first after CONNECT, or does it wait?
+   - If raw_s3_*.bin has bytes before any AT/POLL exchange → PUSH protocol
+   - If it stays silent → PULL protocol (same as Blastware manual download)
+
+2. Look for "Operating System" ASCII at the start — the device sends this 16-byte
+   boot string on cold start before entering DLE-framed mode.
+
+3. RING/CONNECT from the modem appear as ASCII before the DLE frames — the parser
+   handles these automatically (scans forward to DLE+STX).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import threading
+import time
+from datetime import datetime
+from pathlib import Path
+
+try:
+    import serial
+    from serial.tools import list_ports
+except ModuleNotFoundError:
+    print(
+        "pyserial not found. Install with:\n  python -m pip install pyserial",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+# Add project root so we can import the frame parser
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from minimateplus.framing import S3FrameParser, S3Frame
+
+import json
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _ts() -> str:
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+
+
+def _hexdump(b: bytes) -> str:
+    return " ".join(f"{x:02X}" for x in b)
+
+
+def _printable(b: bytes) -> str:
+    return b.decode("latin1", errors="replace")
+
+
+_KNOWN_SUBS = {
+    0xA4: "POLL_RSP",        0xA5: "BULK_WAVEFORM_RSP", 0xE0: "ADVANCE_EVENT_RSP",
+    0xE1: "EVENT_IDX_FIRST_RSP", 0xE3: "MONITOR_STATUS_RSP", 0xEA: "SERIAL_NUM_RSP",
+    0xF3: "WAVEFORM_RECORD_RSP", 0xF5: "WAVEFORM_HEADER_RSP", 0xF7: "EVENT_INDEX_RSP",
+    0xF9: "UNK_06_RSP",      0xFE: "DEVICE_INFO_RSP",
+    0x69: "START_MONITOR_ACK", 0x68: "STOP_MONITOR_ACK",
+    0x97: "EVT_IDX_WRITE_ACK", 0x8C: "CONFIRM_B_ACK",  0x8E: "COMPLIANCE_WRITE_ACK",
+    0x8D: "CONFIRM_A_ACK",   0x7D: "TRIGGER_WRITE_ACK", 0x7C: "TRIGGER_CONFIRM_ACK",
+    0x96: "WAVEFORM_WRITE_ACK", 0x8B: "CONFIRM_C_ACK",
+}
+
+
+def _label_frame(frame: S3Frame) -> str:
+    name = _KNOWN_SUBS.get(frame.sub, f"UNK_0x{frame.sub:02X}")
+    chk  = "✓" if frame.checksum_valid else "✗ BAD_CHK"
+    peek = frame.data[:24].hex() + ("…" if len(frame.data) > 24 else "")
+    return (
+        f"S3 SUB=0x{frame.sub:02X} ({name:<22})  "
+        f"page=0x{frame.page_key:04X}  data={len(frame.data):4d}B  {chk}  {peek}"
+    )
+
+
+# ── Logger ────────────────────────────────────────────────────────────────────
+
+class Logger:
+    def __init__(self, log_path: Path, jsonl_path: Path, raw_path: Path) -> None:
+        self._log  = log_path.open("a", encoding="utf-8", newline="")
+        self._jl   = jsonl_path.open("a", encoding="utf-8", newline="")
+        self._raw  = raw_path.open("ab")
+        self._lock = threading.Lock()
+        self._frame_count = 0
+
+    def info(self, msg: str) -> None:
+        line = f"[{_ts()}] INFO  | {msg}"
+        with self._lock:
+            print(line)
+            print(line, file=self._log, flush=True)
+
+    def ctrl(self, msg: str) -> None:
+        line = f"[{_ts()}] CTRL  | {msg}"
+        with self._lock:
+            print(line)
+            print(line, file=self._log, flush=True)
+
+    def data_hex(self, msg: str) -> None:
+        line = f"[{_ts()}] HEX   | {msg}"
+        with self._lock:
+            print(line)
+            print(line, file=self._log, flush=True)
+
+    def data_ascii(self, msg: str) -> None:
+        line = f"[{_ts()}] DATA  | {msg}"
+        with self._lock:
+            print(line)
+            print(line, file=self._log, flush=True)
+
+    def frame(self, f: S3Frame) -> None:
+        with self._lock:
+            self._frame_count += 1
+            label = f"[{_ts()}] FRAME | #{self._frame_count:04d}  {_label_frame(f)}"
+            print(label)
+            print(label, file=self._log, flush=True)
+            record = {
+                "frame": self._frame_count,
+                "sub": f.sub,
+                "page_key": f.page_key,
+                "data_len": len(f.data),
+                "data_hex": f.data.hex(),
+                "checksum_valid": f.checksum_valid,
+            }
+            print(json.dumps(record), file=self._jl, flush=True)
+
+    def write_raw(self, data: bytes) -> None:
+        with self._lock:
+            self._raw.write(data)
+            self._raw.flush()
+
+    def close(self) -> None:
+        with self._lock:
+            for fh in (self._log, self._jl, self._raw):
+                try:
+                    fh.flush()
+                    fh.close()
+                except Exception:
+                    pass
+
+
+# ── Control-line monitor thread ───────────────────────────────────────────────
+
+def _monitor_control_lines(
+    ser: serial.Serial,
+    logger: Logger,
+    stop: threading.Event,
+    interval: float,
+) -> None:
+    prev = dict(CTS=None, DSR=None, DCD=None, RI=None)
+    try:
+        prev.update(CTS=ser.cts, DSR=ser.dsr, DCD=ser.cd)
+        try:
+            prev["RI"] = ser.ri
+        except Exception:
+            pass
+    except Exception as exc:
+        logger.ctrl(f"Init error: {exc}")
+        return
+
+    logger.ctrl(
+        f"Initial: CTS={prev['CTS']} DSR={prev['DSR']} DCD={prev['DCD']} RI={prev['RI']}"
+    )
+    while not stop.is_set():
+        try:
+            cur = dict(CTS=ser.cts, DSR=ser.dsr, DCD=ser.cd, RI=None)
+            try:
+                cur["RI"] = ser.ri
+            except Exception:
+                pass
+            for name, val in cur.items():
+                if val != prev[name]:
+                    logger.ctrl(f"{name} → {val}")
+                    prev[name] = val
+        except serial.SerialException as exc:
+            logger.ctrl(f"Poll error: {exc}")
+            break
+        stop.wait(interval)
+
+
+# ── Serial open ───────────────────────────────────────────────────────────────
+
+_PARITY = {
+    "N": serial.PARITY_NONE, "E": serial.PARITY_EVEN, "O": serial.PARITY_ODD,
+    "M": serial.PARITY_MARK, "S": serial.PARITY_SPACE,
+}
+_STOPBITS = {
+    1: serial.STOPBITS_ONE, 1.5: serial.STOPBITS_ONE_POINT_FIVE, 2: serial.STOPBITS_TWO,
+}
+
+
+def _open_serial(args: argparse.Namespace, logger: Logger) -> serial.Serial | None:
+    for attempt in range(1, args.open_retries + 2):
+        logger.info(
+            f"Opening {args.port} @ {args.baud},{args.bytesize}{args.parity}{args.stopbits} "
+            f"rtscts={args.rtscts} xonxoff={args.xonxoff} dsrdtr={args.dsrdtr} "
+            f"(attempt {attempt})"
+        )
+        try:
+            ser = serial.Serial(
+                port=args.port,
+                baudrate=args.baud,
+                bytesize=args.bytesize,
+                parity=_PARITY[args.parity],
+                stopbits=_STOPBITS[args.stopbits],
+                timeout=args.timeout,
+                xonxoff=args.xonxoff,
+                rtscts=args.rtscts,
+                dsrdtr=args.dsrdtr,
+                write_timeout=0,
+            )
+            try:
+                ser.setDTR(args.dtr == "on")
+                ser.setRTS(args.rts == "on")
+                logger.ctrl(f"Set DTR={args.dtr} RTS={args.rts}")
+            except Exception as exc:
+                logger.ctrl(f"DTR/RTS set failed: {exc}")
+
+            if args.send_break > 0:
+                try:
+                    ser.break_condition = True
+                    time.sleep(args.send_break / 1000.0)
+                    ser.break_condition = False
+                    logger.ctrl(f"BREAK held {args.send_break} ms")
+                except Exception as exc:
+                    logger.ctrl(f"BREAK failed: {exc}")
+
+            return ser
+
+        except serial.SerialException as exc:
+            logger.info(f"Open failed: {exc}")
+            if attempt <= args.open_retries:
+                time.sleep(args.open_retry_delay)
+
+    return None
+
+
+# ── Port picker ───────────────────────────────────────────────────────────────
+
+def _list_ports() -> list:
+    ports = list(list_ports.comports())
+    if not ports:
+        print("No serial ports found.")
+        return []
+    print("Available serial ports:")
+    for i, p in enumerate(ports, 1):
+        print(f"  {i:2d})  {p.device:<12}  {p.description or ''}")
+    return ports
+
+
+def _pick_port() -> str:
+    ports = _list_ports()
+    if not ports:
+        sys.exit(1)
+    if len(ports) == 1:
+        print(f"Auto-selecting: {ports[0].device}")
+        return ports[0].device
+    while True:
+        sel = input("Select port (number or name, e.g. COM3): ").strip()
+        if sel.isdigit() and 1 <= int(sel) <= len(ports):
+            return ports[int(sel) - 1].device
+        for p in ports:
+            if p.device.upper() == sel.upper():
+                return p.device
+        print("Not recognised. Enter list number or exact port name.")
+
+
+# ── Main loop ─────────────────────────────────────────────────────────────────
+
+def main() -> None:
+    ap = argparse.ArgumentParser(
+        description="Monitor Instantel Series-3 serial traffic with S3 frame parsing."
+    )
+    ap.add_argument("--port", "-p",
+                    help="COM port (e.g. COM3). Omit to be prompted.")
+    ap.add_argument("--baud", "-b", type=int, default=38400)
+    ap.add_argument("--bytesize", type=int, choices=[5, 6, 7, 8], default=8)
+    ap.add_argument("--parity", choices=["N", "E", "O", "M", "S"], default="N")
+    ap.add_argument("--stopbits", type=float, choices=[1, 1.5, 2], default=1)
+    ap.add_argument("--rtscts", action="store_true")
+    ap.add_argument("--xonxoff", action="store_true")
+    ap.add_argument("--dsrdtr", action="store_true")
+    ap.add_argument("--dtr", choices=["on", "off"], default="on")
+    ap.add_argument("--rts", choices=["on", "off"], default="on")
+    ap.add_argument("--send-break", type=int, default=0,
+                    help="Hold BREAK for N ms after open.")
+    ap.add_argument("--show", choices=["ascii", "hex", "both", "frames"],
+                    default="frames",
+                    help="'frames' (default) shows only parsed S3 frames. "
+                         "'ascii'/'hex'/'both' also show raw bytes.")
+    ap.add_argument("--encoding", default="latin1")
+    ap.add_argument("--read-chunk", type=int, default=4096)
+    ap.add_argument("--timeout", type=float, default=0.05)
+    ap.add_argument("--poll-lines-interval", type=float, default=0.2)
+    ap.add_argument("--open-retries", type=int, default=0)
+    ap.add_argument("--open-retry-delay", type=float, default=0.8)
+    ap.add_argument("--ack-ok", action="store_true",
+                    help="Auto-reply OK to AT* commands (except ATDT). "
+                         "Useful for testing without a real modem.")
+    ap.add_argument("--list", action="store_true",
+                    help="List available serial ports and exit.")
+    args = ap.parse_args()
+
+    if args.list:
+        _list_ports()
+        return
+
+    args.port = args.port or _pick_port()
+
+    # Build output paths
+    ts_str = datetime.now().strftime("%Y%m%d_%H%M%S")
+    out_dir = Path(__file__).parent / "captures" / f"serial_{ts_str}"
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    log_path   = out_dir / f"session_{ts_str}.log"
+    jsonl_path = out_dir / f"session_{ts_str}.jsonl"
+    raw_path   = out_dir / f"raw_s3_{ts_str}.bin"
+
+    logger = Logger(log_path, jsonl_path, raw_path)
+    logger.info(f"Output directory: {out_dir}")
+    logger.info(f"raw_s3 → {raw_path.name}  (compatible with parse_capture.py)")
+
+    ser = _open_serial(args, logger)
+    if ser is None:
+        logger.info("Could not open serial port. Exiting.")
+        logger.close()
+        sys.exit(1)
+
+    s3_parser = S3FrameParser()
+    rx_buf    = bytearray()
+    stop_evt  = threading.Event()
+
+    ctrl_thread = threading.Thread(
+        target=_monitor_control_lines,
+        args=(ser, logger, stop_evt, args.poll_lines_interval),
+        daemon=True,
+    )
+    ctrl_thread.start()
+    logger.info("Monitoring started. Waiting for call-home. Press Ctrl+C to stop.")
+
+    try:
+        while True:
+            try:
+                data = ser.read(args.read_chunk)
+            except serial.SerialException as exc:
+                logger.info(f"Read error: {exc}")
+                break
+
+            if not data:
+                continue
+
+            # 1. Save raw bytes
+            logger.write_raw(data)
+
+            # 2. Optional raw display
+            if args.show in ("ascii", "both"):
+                txt = _printable(data)
+                for line in txt.splitlines():
+                    logger.data_ascii(line)
+            if args.show in ("hex", "both"):
+                logger.data_hex(_hexdump(data))
+
+            # 3. Parse S3 frames
+            for byte in data:
+                result = s3_parser.feed(bytes([byte]))
+                if result:
+                    frames = result if isinstance(result, list) else [result]
+                    for f in frames:
+                        logger.frame(f)
+
+            # 4. AT command handling for --ack-ok
+            if args.ack_ok:
+                rx_buf.extend(data)
+                while b"\r" in rx_buf or b"\n" in rx_buf:
+                    for sep in (b"\r", b"\n"):
+                        idx = rx_buf.find(sep)
+                        if idx != -1:
+                            line_bytes = bytes(rx_buf[:idx])
+                            del rx_buf[:idx + 1]
+                            break
+                    else:
+                        break
+
+                    line_str = line_bytes.decode("latin1", errors="ignore").strip().upper()
+                    if line_str.startswith("AT") and not line_str.startswith("ATDT"):
+                        try:
+                            ser.write(b"\r\nOK\r\n")
+                            ser.flush()
+                            logger.info(f"AT ack: {line_str!r} → OK")
+                        except Exception as exc:
+                            logger.info(f"AT ack write failed: {exc}")
+
+    except KeyboardInterrupt:
+        logger.info("Ctrl+C — stopping.")
+
+    finally:
+        stop_evt.set()
+        try:
+            ser.close()
+        except Exception:
+            pass
+        ctrl_thread.join(timeout=1.0)
+        logger.info(f"Capture saved to: {out_dir}")
+        logger.close()
+
+
+if __name__ == "__main__":
+    main()

bridges/tcp_serial_bridge.py

@@ -0,0 +1,205 @@
+"""
+tcp_serial_bridge.py — Local TCP-to-serial bridge for bench testing TcpTransport.
+
+Listens on a TCP port and, when a client connects, opens a serial port and
+bridges bytes bidirectionally.  This lets you test the SFM server's TCP
+endpoint (?host=127.0.0.1&tcp_port=12345) against a locally-attached MiniMate
+Plus without needing a field modem.
+
+The bridge simulates an RV55 cellular modem in transparent TCP passthrough mode:
+  - No handshake bytes on connect
+  - Raw bytes forwarded in both directions
+  - One connection at a time (new connection closes any existing serial session)
+
+Usage:
+    python bridges/tcp_serial_bridge.py --serial COM5 --tcp-port 12345
+
+Then in another window:
+    python -m uvicorn sfm.server:app --port 8200
+    curl "http://localhost:8200/device/info?host=127.0.0.1&tcp_port=12345"
+
+Or just hit http://localhost:8200/device/info?host=127.0.0.1&tcp_port=12345
+in a browser.
+
+Requirements:
+    pip install pyserial
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import select
+import socket
+import sys
+import threading
+import time
+
+try:
+    import serial  # type: ignore
+except ImportError:
+    print("pyserial required: pip install pyserial", file=sys.stderr)
+    sys.exit(1)
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(levelname)-7s  %(message)s",
+    datefmt="%H:%M:%S",
+)
+log = logging.getLogger("tcp_serial_bridge")
+
+# ── Constants ─────────────────────────────────────────────────────────────────
+
+DEFAULT_BAUD     = 38_400
+DEFAULT_TCP_PORT = 12345
+CHUNK            = 256          # bytes per read call
+SERIAL_TIMEOUT   = 0.02         # serial read timeout (s) — non-blocking in practice
+TCP_TIMEOUT      = 0.02         # socket recv timeout (s)
+BOOT_DELAY       = 8.0          # seconds to wait after opening serial port before
+                                # forwarding data — unit cold-boot (beep + OS init)
+                                # takes 5-10s from first RS-232 line assertion.
+                                # Set to 0 if unit was already running before connect.
+
+
+# ── Bridge session ─────────────────────────────────────────────────────────────
+
+def _pipe_tcp_to_serial(sock: socket.socket, ser: serial.Serial, stop: threading.Event) -> None:
+    """Forward bytes from TCP socket → serial port."""
+    sock.settimeout(TCP_TIMEOUT)
+    while not stop.is_set():
+        try:
+            data = sock.recv(CHUNK)
+            if not data:
+                log.info("TCP peer closed connection")
+                stop.set()
+                break
+            log.debug("TCP→SER %d bytes: %s", len(data), data.hex())
+            ser.write(data)
+        except socket.timeout:
+            pass
+        except OSError as exc:
+            if not stop.is_set():
+                log.warning("TCP read error: %s", exc)
+            stop.set()
+            break
+
+
+def _pipe_serial_to_tcp(sock: socket.socket, ser: serial.Serial, stop: threading.Event) -> None:
+    """Forward bytes from serial port → TCP socket."""
+    while not stop.is_set():
+        try:
+            data = ser.read(CHUNK)
+            if data:
+                log.debug("SER→TCP %d bytes: %s", len(data), data.hex())
+                try:
+                    sock.sendall(data)
+                except OSError as exc:
+                    if not stop.is_set():
+                        log.warning("TCP send error: %s", exc)
+                    stop.set()
+                    break
+        except serial.SerialException as exc:
+            if not stop.is_set():
+                log.warning("Serial read error: %s", exc)
+            stop.set()
+            break
+
+
+def _run_session(conn: socket.socket, addr: tuple, serial_port: str, baud: int, boot_delay: float) -> None:
+    """Handle one TCP client connection."""
+    peer = f"{addr[0]}:{addr[1]}"
+    log.info("Connection from %s", peer)
+
+    try:
+        ser = serial.Serial(
+            port     = serial_port,
+            baudrate = baud,
+            bytesize = 8,
+            parity   = "N",
+            stopbits = 1,
+            timeout  = SERIAL_TIMEOUT,
+        )
+    except serial.SerialException as exc:
+        log.error("Cannot open serial port %s: %s", serial_port, exc)
+        conn.close()
+        return
+
+    log.info("Opened %s at %d baud — waiting %.1fs for unit boot", serial_port, baud, boot_delay)
+    ser.reset_input_buffer()
+    ser.reset_output_buffer()
+
+    if boot_delay > 0:
+        time.sleep(boot_delay)
+        ser.reset_input_buffer()   # discard any boot noise
+
+    log.info("Bridge active: TCP %s ↔ %s", peer, serial_port)
+
+    stop = threading.Event()
+    t_tcp_to_ser = threading.Thread(
+        target=_pipe_tcp_to_serial, args=(conn, ser, stop), daemon=True
+    )
+    t_ser_to_tcp = threading.Thread(
+        target=_pipe_serial_to_tcp, args=(conn, ser, stop), daemon=True
+    )
+    t_tcp_to_ser.start()
+    t_ser_to_tcp.start()
+
+    stop.wait()   # block until either thread sets the stop flag
+
+    log.info("Session ended, cleaning up")
+    try:
+        conn.close()
+    except OSError:
+        pass
+    try:
+        ser.close()
+    except OSError:
+        pass
+
+    t_tcp_to_ser.join(timeout=2.0)
+    t_ser_to_tcp.join(timeout=2.0)
+    log.info("Session with %s closed", peer)
+
+
+# ── Server ────────────────────────────────────────────────────────────────────
+
+def run_bridge(serial_port: str, baud: int, tcp_port: int, boot_delay: float) -> None:
+    """Accept TCP connections forever and bridge each one to the serial port."""
+    srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    srv.bind(("0.0.0.0", tcp_port))
+    srv.listen(1)
+    log.info(
+        "Listening on TCP :%d — will bridge to %s at %d baud",
+        tcp_port, serial_port, baud,
+    )
+    log.info("Send test: curl 'http://localhost:8200/device/info?host=127.0.0.1&tcp_port=%d'", tcp_port)
+
+    try:
+        while True:
+            conn, addr = srv.accept()
+            # Handle one session at a time (synchronous) — matches modem behaviour
+            _run_session(conn, addr, serial_port, baud, boot_delay)
+    except KeyboardInterrupt:
+        log.info("Shutting down")
+    finally:
+        srv.close()
+
+
+# ── Entry point ────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    ap = argparse.ArgumentParser(description="TCP-to-serial bridge for bench testing TcpTransport")
+    ap.add_argument("--serial",     default="COM5",          help="Serial port (default: COM5)")
+    ap.add_argument("--baud",       type=int, default=DEFAULT_BAUD, help="Baud rate (default: 38400)")
+    ap.add_argument("--tcp-port",   type=int, default=DEFAULT_TCP_PORT, help="TCP listen port (default: 12345)")
+    ap.add_argument("--boot-delay", type=float, default=BOOT_DELAY,
+                    help="Seconds to wait after opening serial before forwarding (default: 2.0). "
+                         "Set to 0 if unit is already powered on.")
+    ap.add_argument("--debug",      action="store_true", help="Show individual byte transfers")
+    args = ap.parse_args()
+
+    if args.debug:
+        logging.getLogger().setLevel(logging.DEBUG)
+
+    run_bridge(args.serial, args.baud, args.tcp_port, args.boot_delay)

docs/device_config_schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://terra-mechanics.com/schemas/seismo-relay/device-config/v1",
+  "title": "MiniMate Plus Device Config",
+  "description": "Writable configuration fields for an Instantel MiniMate Plus seismograph, as exposed by the seismo-relay SFM API (POST /device/config). All fields are optional — only supplied fields are written; all others are round-tripped from the device.",
+  "type": "object",
+  "additionalProperties": false,
+
+  "properties": {
+
+    "sample_rate": {
+      "title": "Sample Rate",
+      "description": "ADC sample rate in samples per second. Must be one of the three supported rates.",
+      "type": "integer",
+      "enum": [1024, 2048, 4096],
+      "examples": [1024]
+    },
+
+    "record_time": {
+      "title": "Record Time",
+      "description": "Waveform record duration in seconds. Typical values are 1.0–15.0 s. The device stores this as a 32-bit IEEE 754 float.",
+      "type": "number",
+      "exclusiveMinimum": 0,
+      "maximum": 60.0,
+      "examples": [3.0]
+    },
+
+    "trigger_level_geo": {
+      "title": "Trigger Level (Geo)",
+      "description": "Geophone trigger threshold in in/s. Event recording begins when any geo channel exceeds this level.",
+      "type": "number",
+      "exclusiveMinimum": 0,
+      "examples": [0.5]
+    },
+
+    "alarm_level_geo": {
+      "title": "Alarm Level (Geo)",
+      "description": "Geophone alarm threshold in in/s. An alarm is flagged when any geo channel exceeds this level.",
+      "type": "number",
+      "exclusiveMinimum": 0,
+      "examples": [1.0]
+    },
+
+    "max_range_geo": {
+      "title": "Max Range (Geo)",
+      "description": "Full-scale calibration constant for geo channels in in/s. This is a factory-calibrated value — only modify if you have a calibration certificate. Default for MiniMate Plus is approximately 6.206 in/s.",
+      "type": "number",
+      "exclusiveMinimum": 0,
+      "examples": [6.206]
+    },
+
+    "project": {
+      "title": "Project",
+      "description": "Project name or description. Stored in the compliance config block and echoed on event reports. Max 41 ASCII characters.",
+      "type": "string",
+      "maxLength": 41,
+      "examples": ["Bridge Inspection 2026"]
+    },
+
+    "client_name": {
+      "title": "Client",
+      "description": "Client or company name. Max 41 ASCII characters.",
+      "type": "string",
+      "maxLength": 41,
+      "examples": ["City of Portland"]
+    },
+
+    "operator": {
+      "title": "Operator",
+      "description": "Operator or technician name. Stored as 'User Name:' in the device. Max 41 ASCII characters.",
+      "type": "string",
+      "maxLength": 41,
+      "examples": ["Brian Harrison"]
+    },
+
+    "seis_loc": {
+      "title": "Sensor Location",
+      "description": "Sensor location description. Stored as 'Seis Loc:' in the device. Max 41 ASCII characters.",
+      "type": "string",
+      "maxLength": 41,
+      "examples": ["South Abutment — 3 m from blast"]
+    },
+
+    "notes": {
+      "title": "Extended Notes",
+      "description": "Free-form notes. Stored as 'Extended Notes' in the device. Max 41 ASCII characters.",
+      "type": "string",
+      "maxLength": 41,
+      "examples": ["Pre-blast baseline, no charges"]
+    }
+
+  },
+
+  "examples": [
+    {
+      "project": "Bridge Inspection 2026",
+      "client_name": "City of Portland",
+      "operator": "Brian Harrison",
+      "seis_loc": "South Abutment",
+      "notes": "Pre-blast baseline"
+    },
+    {
+      "sample_rate": 1024,
+      "record_time": 3.0,
+      "trigger_level_geo": 0.5,
+      "alarm_level_geo": 1.0
+    },
+    {
+      "sample_rate": 2048,
+      "record_time": 5.0,
+      "trigger_level_geo": 0.25,
+      "alarm_level_geo": 0.75,
+      "project": "Quarry Blast Monitoring",
+      "client_name": "Acme Quarry LLC",
+      "operator": "Brian Harrison",
+      "seis_loc": "Nearest Structure — East Wall",
+      "notes": "Production blast series B"
+    }
+  ]
+}

docs/instantel_protocol_session_summary_2-26_3-1.md

@@ -0,0 +1,139 @@
+# Instantel MiniMate Plus — RS-232 Protocol RE
+**Session Summary: Chat Compacted 2026-03-01**  
+Device: MiniMate Plus S/N BE18189  
+FW S338.17 / DSP 10.72  
+Capture: 38400 baud, COM4/COM5  
+
+---
+
+# Session 1 — Protocol Foundations & Write Command Discovery  
+**2026-02-27**
+
+## Frame Structure Confirmed
+- DLE framing: `ACK (0x41)` + `DLE+STX (0x10 0x02)` … payload … checksum … `DLE+ETX (0x10 0x03)`
+- DLE byte stuffing: `0x10` in payload → `0x10 0x10` on wire
+- Checksum: 8-bit sum of de-stuffed payload bytes, mod 256
+- Payload structure:  
+  `CMD | DLE | ADDR | FLAGS | SUB | OFFSET_HI | OFFSET_LO | data…`
+- All BW→S3 requests use `CMD=0x02`
+- All responses use CMD matching the DLE prefix
+- Response `SUB = 0xFF − Request SUB`
+
+## Session Startup Sequence
+Device boot prints ASCII **“Operating System”** before binary protocol mode.
+
+Blastware init sequence:
+1. POLL (SUB 5B)
+2. Channel config (06)
+3. Serial (15)
+4. Full config (01)
+5. Event index (08)
+6. Event headers (1E)
+7. Waveform records (0C)
+8. Bulk stream (5A)
+
+## Write Commands Discovered
+
+| SUB (Req) | SUB (Resp) | Function |
+|---|---|---|
+| 0x71 | 0x8E | Trigger config write |
+| 0x72 | 0x8D | Trigger config page 2 |
+| 0x73 | 0x8C | Unknown write |
+| 0x74 | 0x8B | Unknown write |
+| 0x82 | 0x7D | Unknown write (post config) |
+| 0x83 | 0x7C | Unknown write (terminal) |
+| 0x68 | 0x97 | Event index write? |
+| 0x09 | 0xF6 | Unknown read |
+| 0x1A | 0xE5 | Unknown multi-page read |
+| 0x2E | 0xD1 | Unknown short read |
+
+---
+
+# Session 2 — Trigger & Alarm Level Floats  
+**2026-03-01 ~20:51**
+
+## Key Findings
+- Trigger & alarm levels are IEEE‑754 single‑precision **big‑endian floats**
+- Trigger level change verified (0.5 → 0.2 in/s)
+- Alarm level verified (1.0 → 2.0 in/s)
+- Unit strings embedded inline (`"psi"`, `"in./s"`)
+- `0x082A` ruled out as trigger candidate
+
+## SUB 71 Float Offsets
+
+| Offset | Field | Value | Encoding |
+|---|---|---|---|
+| d[32..35] | MicL trigger | 0.0450 psi | IEEE754 BE |
+| d[38..41] | MicL low thresh | 0.0100 psi | IEEE754 BE |
+| d[46..49] | MicL alarm | 0.0210 psi | IEEE754 BE |
+| d[42..44] | Units | psi\0 | ASCII |
+
+---
+
+# Session 3 — Multi‑Parameter Capture  
+**2026-03-01 ~20:53**
+
+| Parameter | Change | Result |
+|---|---|---|
+| Alarm level | 2.0 in/s | Confirmed |
+| Trigger level | 0.6 in/s | Confirmed |
+| Record time | 3s | Confirmed |
+| Sentinels | FF FF FF FF | Write boundaries confirmed |
+
+---
+
+# Session 4 — .set File Decode  
+**2026-03-01 ~20:55**
+
+## .set Format
+- Binary per‑channel structs
+- Backlight field at **+0x0C**
+- MicL units confirmed as **psi**
+- Record time offset confirmed
+
+Unknown uint16 fields:
+- +0x0A = 80
+- +0x0E = 40
+- +0x10 = 21
+
+## Backlight / Power Saving Tests
+Changes tested:
+- Backlight 15 → 30
+- Power save 2 → 5
+- Mic dB toggle
+
+Result:
+- SUB 71 frames identical
+- No new writes after sentinels
+- Device confirmed to support settings → offsets unknown
+
+---
+
+# Current State — Pending Capture
+
+Next capture targets:
+- Backlight = 250 → search `0xFA`
+- Power saving = 10 → search `0x0A`
+- Possible encodings:
+  - uint16 BE
+  - uint32 BE
+  - Little‑endian variants
+
+---
+
+# Open Questions
+
+| Question | Priority | Status |
+|---|---|---|
+| Timestamp byte 3 | MEDIUM | Open |
+| Serial response trailing bytes | MEDIUM | Open |
+| Channel ID mapping | MEDIUM | Open |
+| Write config coverage | MEDIUM | Partial |
+| Backlight offsets | HIGH | Active |
+| MicL units | LOW | Resolved |
+| SUB 24/25 vs 5A | LOW | Open |
+| 0x07E7 config field | LOW | Open |
+
+---
+
+All findings reverse‑engineered from RS‑232 captures. No vendor docs used.

docs/parse_0x1c_response.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""
+Parse SUB 0x1C (monitoring status) response frames.
+
+SUB 0x1C returns device monitoring status with different payload sizes depending on state:
+  - IDLE (not monitoring): 58 bytes with full details
+  - MONITORING (actively streaming): 12 bytes condensed format
+"""
+
+import struct
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class MonitoringStatus:
+    """Parsed SUB 0x1C response fields."""
+
+    monitor_mode: int  # 0x2c = OFF, 0x00 = ON
+    day: int           # 1–31
+    hour: int          # 0–23
+    month: int         # 1–12
+    year: int          # 2000–2100
+    minute: int        # 0–59 (uncertain encoding)
+    second: int        # 0–59 (uncertain encoding)
+    battery_voltage_v: float  # Volts (6–8V typical)
+    memory_total_kb: float    # Kilobytes
+    memory_free_kb: float     # Kilobytes
+    raw_payload: bytes
+
+    def __str__(self) -> str:
+        mode_str = "OFF" if self.monitor_mode == 0x2c else "ON"
+        date_str = f"{self.year:04d}-{self.month:02d}-{self.day:02d}"
+        time_str = f"{self.hour:02d}:{self.minute:02d}:{self.second:02d}"
+        return (
+            f"MonitoringStatus(\n"
+            f"  mode={mode_str} (0x{self.monitor_mode:02x})\n"
+            f"  datetime={date_str} {time_str}\n"
+            f"  battery={self.battery_voltage_v:.2f}V\n"
+            f"  memory=total {self.memory_total_kb:.1f} KB, "
+            f"free {self.memory_free_kb:.1f} KB\n"
+            f")"
+        )
+
+
+def parse_0x1c_response(data: bytes) -> Optional[MonitoringStatus]:
+    """
+    Parse a SUB 0x1C response payload (after S3 header removed).
+
+    Args:
+        data: Destuffed payload bytes (without the 5-byte S3 header)
+
+    Returns:
+        MonitoringStatus object, or None if parse fails
+    """
+
+    if len(data) < 39:
+        # Minimum size for idle response
+        print(f"[!] Payload too short: {len(data)} bytes (need >=39)")
+        return None
+
+    try:
+        monitor_mode = data[0x00]
+
+        day = data[0x0d]
+        hour = data[0x0e]
+        month = data[0x0f]
+        year = struct.unpack('>H', data[0x10:0x12])[0]
+        minute = data[0x12]
+        second = data[0x13]
+
+        # Battery voltage: uint16 BE, divide by 100
+        # At offset [2f:31]
+        voltage_raw = struct.unpack('>H', data[0x2f:0x31])[0]
+        battery_voltage_v = voltage_raw / 100.0
+
+        # Memory total: uint32 BE, in bytes
+        # At offset [31:35]
+        memory_total_bytes = struct.unpack('>I', data[0x31:0x35])[0]
+        memory_total_kb = memory_total_bytes / 1024.0
+
+        # Memory free: uint32 BE, in bytes
+        # At offset [35:39]
+        memory_free_bytes = struct.unpack('>I', data[0x35:0x39])[0]
+        memory_free_kb = memory_free_bytes / 1024.0
+
+        return MonitoringStatus(
+            monitor_mode=monitor_mode,
+            day=day,
+            hour=hour,
+            month=month,
+            year=year,
+            minute=minute,
+            second=second,
+            battery_voltage_v=battery_voltage_v,
+            memory_total_kb=memory_total_kb,
+            memory_free_kb=memory_free_kb,
+            raw_payload=data
+        )
+
+    except (struct.error, IndexError) as e:
+        print(f"[!] Parse error: {e}")
+        return None
+
+
+def hex_dump(data: bytes, offset: int = 0) -> str:
+    """Pretty-print hex dump of binary data."""
+    lines = []
+    for i in range(0, len(data), 16):
+        chunk = data[i:i+16]
+        hex_str = ' '.join(f'{b:02x}' for b in chunk)
+        ascii_str = ''.join(chr(b) if 32 <= b < 127 else '.' for b in chunk)
+        lines.append(f"  {offset+i:04x}: {hex_str:<48} {ascii_str}")
+    return '\n'.join(lines)
+
+
+if __name__ == '__main__':
+    import sys
+
+    if len(sys.argv) < 2:
+        print("Usage: parse_0x1c_response.py <hex_string_or_file>")
+        print()
+        print("Example (hex string):")
+        print("  python3 parse_0x1c_response.py 2c00000000000000000000000008100407ea00013b2d...")
+        print()
+        print("Example (from capture file, idle frame):")
+        print("  Idle response (58 bytes):")
+        idle_hex = (
+            "2c00000000000000000000000008100407ea00013b2d000000000000"
+            "010107cb00060000010107cb0015000000001002a8000efff2000e9e52ef"
+        )
+        status = parse_0x1c_response(bytes.fromhex(idle_hex))
+        print(hex_dump(bytes.fromhex(idle_hex)))
+        print()
+        if status:
+            print(status)
+
+        sys.exit(0)
+
+    # Parse input
+    input_str = sys.argv[1]
+
+    try:
+        payload = bytes.fromhex(input_str)
+    except ValueError:
+        print(f"[!] Invalid hex string: {input_str}")
+        sys.exit(1)
+
+    print(f"Parsing {len(payload)} bytes:")
+    print(hex_dump(payload))
+    print()
+
+    status = parse_0x1c_response(payload)
+    if status:
+        print(status)
+    else:
+        print("[!] Failed to parse")
+        sys.exit(1)

docs/sub_0x1c_analysis.md

@@ -0,0 +1,274 @@
+# SUB 0x1C — Monitoring Status Response Format
+
+**Capture file:** `/sessions/intelligent-nice-wright/mnt/seismo-relay/bridges/captures/4-8-26/2ndtry/raw_s3_20260408_015927.bin`
+
+**Analysis date:** 2026-04-08
+
+---
+
+## Overview
+
+SUB 0x1C is a monitoring status query that returns different sized responses depending on device state:
+
+- **IDLE/OFF (unit not monitoring):** 58-byte response with detailed fields
+- **MONITORING/ON (unit actively monitoring):** 12-byte response with condensed format
+
+The key fields CONFIRMED from wire capture analysis:
+
+| Field | Offset | Format | Value (Idle) | Notes |
+|-------|--------|--------|-------------|-------|
+| **Monitor Mode** | [00] | uint8 | 0x2c (OFF) | 0x2c = Idle, 0x00 = Monitoring |
+| **Day** | [0d] | uint8 | 0x08 | 1–31 |
+| **Hour** | [0e] | uint8 | 0x10 | 0–23 (16 = 4 PM) |
+| **Month** | [0f] | uint8 | 0x04 | 1–12 (April) |
+| **Year** | [10:12] | uint16 BE | 0x07ea | 2026 |
+| **Minute** | [12] | uint8 | 0x00 | 0–59 |
+| **Second** | [13] | uint8 | 0x01 | 0–59 (but this seems off) |
+| **Battery Voltage** | [2f:31] | uint16 BE, ÷100 | 0x02a8 | 680 → 6.80V |
+| **Memory Total** | [31:35] | uint32 BE | 0x000efff2 | 983,026 bytes = 960.0 KB |
+| **Memory Free** | [35:39] | uint32 BE | 0x000e9e52 | 958,034 bytes = 935.6 KB |
+
+---
+
+## Idle Frame (58 bytes) — Full Hex Dump
+
+```
+  00: 2c 00 00 00 00 00 00 00 00 00 00 00 00 08 10 04  ,...............
+  10: 07 ea 00 01 3b 2d 00 00 00 00 00 00 01 01 07 cb  ....;-..........
+  20: 00 06 00 00 01 01 07 cb 00 15 00 00 00 00 10 02  ................
+  30: a8 00 0e ff f2 00 0e 9e 52 ef                    ........R.
+```
+
+### Field Breakdown
+
+**[00:01] = Monitor Mode**
+```
+Offset 00: 0x2c = 44 (decimal)
+           Interpretation: Unit is NOT currently monitoring (idle/off state)
+           Counter-example in monitoring frame: 0x00 (ON state)
+```
+
+**[01:0d] = Padding/Reserved (12 bytes of zeros)**
+```
+Offsets 01-0c: all 0x00
+```
+
+**[0d:12] = Timestamp (5 bytes)**
+```
+Offset 0d: 0x08 = 8  → DAY
+Offset 0e: 0x10 = 16 → HOUR (4 PM)
+Offset 0f: 0x04 = 4  → MONTH (April)
+Offset 10-11: 0x07ea → YEAR (big-endian: 2026)
+            = 2026-04-08, 16:??:??
+```
+
+**[12:14] = Time (minute/second, ambiguous)**
+```
+Offset 12: 0x00 = 0  → Likely MINUTE
+Offset 13: 0x01 = 1  → Likely SECOND
+           But this seems too low; may be wrong interpretation
+```
+
+**[14:16] = Unknown (2 bytes)**
+```
+Offset 14: 0x3b = 59 (decimal) - could be seconds?
+Offset 15: 0x2d = 45 (decimal)
+```
+
+**[16:2f] = Unknown/Filler (25 bytes)**
+```
+Contains various device-specific configuration or state bytes.
+Some patterns suggest repeating data structures (e.g., 01 01 07 cb appears twice).
+```
+
+**[2f:31] = Battery Voltage (2 bytes, uint16 BE, divide by 100)**
+```
+Offset 2f-30: 0x02a8
+              = 680 (decimal)
+              ÷ 100 = 6.80 volts
+              Expected: ~6.8V ✓ CONFIRMED
+```
+
+**[31:35] = Memory Total (4 bytes, uint32 BE)**
+```
+Offset 31-34: 0x000efff2
+              = 983,026 (decimal, bytes)
+              ÷ 1024 = 960.0 KB ✓ CONFIRMED
+              (Device spec: ~960 KB)
+```
+
+**[35:39] = Memory Free (4 bytes, uint32 BE)**
+```
+Offset 35-38: 0x000e9e52
+              = 958,034 (decimal, bytes)
+              ÷ 1024 = 935.6 KB ✓ CONFIRMED
+              (Expected: ~936 KB)
+```
+
+**[39:3a] = Trailing byte**
+```
+Offset 39: 0xef = 239
+```
+
+---
+
+## Monitoring Frame (12 bytes) — Condensed Response
+
+When the unit is actively monitoring, the response shrinks to 12 bytes:
+
+```
+  00: 00 00 00 00 2c 00 00 00 00 00 00 1f  ....,.......
+```
+
+### Changes from Idle
+
+| Field | Idle Frame | Monitoring Frame | Note |
+|-------|------------|------------------|------|
+| Monitor Mode | [00] = 0x2c | [04] = 0x2c → may shift or invert | Moved to offset [04]? |
+| Size | 58 bytes | 12 bytes | Truncated response; only status, no detail |
+| [0b] | varies | 0x1f | New/different byte at end |
+
+**Interpretation:**
+- The response layout changes based on monitoring state
+- In monitoring mode, many detailed fields are suppressed
+- The monitor_mode indicator may move or encode differently
+
+---
+
+## Date/Time Interpretation
+
+The timestamp at [0d:12] uses this layout (confirmed from capture):
+
+```
+[0d] = DAY   (1–31)   = 0x08 = 8
+[0e] = HOUR  (0–23)   = 0x10 = 16 (4 PM)
+[0f] = MONTH (1–12)   = 0x04 = 4 (April)
+[10:12] = YEAR (uint16 BE) = 0x07ea = 2026
+```
+
+**Timestamp extracted:** 2026-04-08 16:??:??
+
+Minutes and seconds are less clear:
+- [12] = 0x00 → possibly minute
+- [13] = 0x01 → possibly second (but unusually low)
+- [14] = 0x3b = 59 (redundant second marker?)
+
+---
+
+## Voltage Encoding
+
+Battery voltage is stored as **uint16 big-endian, divide by 100:**
+
+```
+[2f:31] = 0x02a8
+Raw value: 680
+Voltage: 680 / 100 = 6.80 V
+Expected: ~6.8V ✓
+```
+
+Other attempted decodings (all ruled out):
+- `÷1000`: 0.680V (too low)
+- `÷10`: 68V (too high)
+- float32 BE/LE: no match in range 6–8V
+- Fixed-point: no other range matched
+
+---
+
+## Memory Encoding
+
+Both fields use **uint32 big-endian, in bytes:**
+
+```
+Memory Total:
+  [31:35] = 0x000efff2 = 983,026 bytes = 960.0 KB
+
+Memory Free:
+  [35:39] = 0x000e9e52 = 958,034 bytes = 935.6 KB
+
+Sanity check: free < total ✓
+Free percentage: 935.6 / 960.0 = 97.5% (plausible)
+```
+
+---
+
+## Monitor Mode Field Transitions
+
+**Idle/OFF State:**
+```
+[00] = 0x2c (decimal 44)
+```
+
+**Monitoring/ON State (response shrinks to 12 bytes):**
+```
+Byte layout shifts; [04] carries 0x2c or another value
+Possible interpretation: the byte moves, or encoding inverts
+```
+
+**Confirmed behavior:**
+- When idle: byte [00] = 0x2c, response is 58 bytes
+- When monitoring: byte position shifts to [04], response is 12 bytes
+- Value 0x2c appears to mean "OFF" or "not actively streaming"
+- Value 0x00 appears to mean "ON" or "actively streaming"
+
+---
+
+## Unknown Fields (for future analysis)
+
+The following regions have been observed but their purpose is unclear:
+
+| Range | Hex (Idle) | Notes |
+|-------|----------|-------|
+| [01:0d] | all 0x00 | Padding or reserved? |
+| [14:16] | 3b 2d | 59, 45 — possibly countdown timers or other state |
+| [16:2f] | mixed | Appears to contain device configuration snapshots; pattern repeats suggest sub-structures (e.g., trigger levels, calibration dates) |
+
+---
+
+## Wire Frame Structure (S3 Format)
+
+Raw S3 response for SUB 0x1C (response SUB = 0xE3):
+
+```
+[DLE=0x10][STX=0x02][destuffed_payload+chk][bare ETX=0x03]
+
+Destuffed payload:
+  [0] CMD    = 0x00
+  [1] flags  = 0x10
+  [2] SUB    = 0xE3 (response)
+  [3] PAGE_HI = 0x00
+  [4] PAGE_LO = 0x00
+  [5+] data  = 58 or 12 bytes (depending on mode)
+```
+
+---
+
+## Summary Table (Idle/OFF State)
+
+| Field | Bytes | Value | Interpretation |
+|-------|-------|-------|------------------|
+| Monitor Mode | [00] | 0x2c | Device idle (not streaming) |
+| Reserved | [01:0d] | 0x00×12 | Padding |
+| **Date/Time** | — | — | — |
+| Day | [0d] | 0x08 | 8th |
+| Hour | [0e] | 0x10 | 16 (4 PM) |
+| Month | [0f] | 0x04 | April |
+| Year | [10:12] | 0x07ea | 2026 |
+| Minute | [12] | 0x00 | 00 (uncertain) |
+| Second | [13] | 0x01 | 01 (uncertain) |
+| Unknown | [14:2f] | — | 27 bytes of mixed data |
+| **Battery** | — | — | — |
+| Voltage | [2f:31] | 0x02a8 | 6.80 V (BE ÷100) |
+| **Memory** | — | — | — |
+| Total | [31:35] | 0x000efff2 | 960.0 KB (BE) |
+| Free | [35:39] | 0x000e9e52 | 935.6 KB (BE) |
+| Trailer | [39:3a] | 0xef | Unknown (1 byte) |
+
+---
+
+## Next Steps
+
+1. **Verify minute/second fields** — Compare against multiple captures to confirm [12:14] layout
+2. **Decode unknown region [16:2f]** — Likely contains trigger levels, calibration dates, alarm thresholds
+3. **Monitoring mode byte position** — Confirm whether it truly moves to [04] in the monitoring response or if response layout is completely different
+4. **Min/max voltage limits** — Check if voltage ever deviates from 6.8V to validate encoding
+5. **Memory dynamics** — Track total/free across sessions to understand flash layout

docs/sub_0x1c_field_locations.txt

@@ -0,0 +1,225 @@
+SUB 0x1C MONITORING STATUS RESPONSE — FINAL FIELD LOCATIONS
+============================================================
+
+Source: raw_s3_20260408_015927.bin (2ndtry capture)
+Frames analyzed: 
+  - IDLE (OFF):       Frame 90 at file offset 4115 (58-byte response)
+  - MONITORING (ON):  Frame 106 at file offset 4922 (12-byte response)
+
+================================================================================
+IDLE/OFF RESPONSE (58 bytes) — COMPLETE FIELD MAP
+================================================================================
+
+HEX DUMP:
+  00: 2c 00 00 00 00 00 00 00 00 00 00 00 00 08 10 04
+  10: 07 ea 00 01 3b 2d 00 00 00 00 00 00 01 01 07 cb
+  20: 00 06 00 00 01 01 07 cb 00 15 00 00 00 00 10 02
+  30: a8 00 0e ff f2 00 0e 9e 52 ef
+
+CONFIRMED FIELDS:
+─────────────────────────────────────────────────────────────────
+
+[00]                    MONITOR_MODE
+                        Value: 0x2c (44 decimal)
+                        Meaning: Device is IDLE (not monitoring)
+                        When ON: 0x00
+
+[0d]                    DAY
+                        Value: 0x08 (8 decimal)
+                        Range: 1–31
+                        Date: 8th
+
+[0e]                    HOUR
+                        Value: 0x10 (16 decimal)
+                        Range: 0–23
+                        Interpretation: 4:00 PM (16:00)
+
+[0f]                    MONTH
+                        Value: 0x04 (4 decimal)
+                        Range: 1–12
+                        Meaning: April
+
+[10:12]                 YEAR (uint16 BE)
+                        Value: 0x07ea
+                        Decimal: 2026
+                        Full date: 2026-04-08
+
+[12]                    MINUTE
+                        Value: 0x00 (0 decimal)
+                        Range: 0–59
+                        Note: May have different encoding in other captures
+
+[13]                    SECOND
+                        Value: 0x01 (1 decimal)
+                        Range: 0–59
+                        Note: Unusually low; likely indicates sampling at minute turn-over
+
+[2f:31]                 BATTERY_VOLTAGE (uint16 BE, ÷100)
+                        Raw bytes: 0x02a8
+                        Raw decimal: 680
+                        Voltage: 680 ÷ 100 = 6.80 V
+                        ✓ CONFIRMED: Expected ~6.8V
+                        Alternative encodings tested and ruled out:
+                          - BE/1000: 0.68V (too low)
+                          - BE/10: 68V (too high)
+                          - float32 BE/LE: no match
+                          - Fixed-point variations: no match
+
+[31:35]                 MEMORY_TOTAL (uint32 BE, in bytes)
+                        Raw bytes: 0x000efff2
+                        Decimal: 983,026 bytes
+                        Kilobytes: 983,026 ÷ 1024 = 960.0 KB
+                        ✓ CONFIRMED: Expected ~960 KB
+
+[35:39]                 MEMORY_FREE (uint32 BE, in bytes)
+                        Raw bytes: 0x000e9e52
+                        Decimal: 958,034 bytes
+                        Kilobytes: 958,034 ÷ 1024 = 935.6 KB
+                        ✓ CONFIRMED: Expected ~936 KB
+                        Sanity check: 935.6 / 960.0 = 97.5% (plausible)
+
+UNIDENTIFIED REGIONS:
+─────────────────────────────────────────────────────────────────
+
+[01:0d]                 PADDING/RESERVED (12 bytes)
+                        All zeros: 00 00 00 00 00 00 00 00 00 00 00 00
+
+[14:16]                 UNKNOWN (2 bytes)
+                        Value: 0x3b2d (59, 45)
+                        Possibly event countdown or state field
+
+[16:2f]                 CONFIGURATION SNAPSHOT (25 bytes)
+                        Contains repeating patterns suggesting sub-structures:
+                          - Possibly trigger levels
+                          - Possibly calibration data
+                          - Possibly alarm settings
+
+[39]                    TRAILER (1 byte)
+                        Value: 0xef (239)
+                        Purpose unknown
+
+================================================================================
+MONITORING/ON RESPONSE (12 bytes) — CONDENSED FORMAT
+================================================================================
+
+HEX DUMP:
+  00: 00 00 00 00 2c 00 00 00 00 00 00 1f
+
+INTERPRETATION:
+─────────────────────────────────────────────────────────────────
+
+When the unit is actively monitoring, the response shrinks to 12 bytes.
+Response layout appears different from idle format.
+
+[04]                    POSSIBLE MONITOR_MODE (shifted position?)
+                        Value: 0x2c
+                        Note: In idle response this was at [00]
+
+[0b]                    TRAILER (1 byte)
+                        Value: 0x1f (31 decimal)
+                        Different from idle trailer (0xef at [39])
+
+All other bytes: 0x00 padding
+
+HYPOTHESIS:
+  When monitoring, the device suppresses detailed fields and returns only:
+  - Monitor mode status (position may shift)
+  - A condensed state indicator
+
+================================================================================
+TIME FIELD SUMMARY (3 INTERPRETATIONS)
+================================================================================
+
+OBSERVED BYTES:
+  [0d] = 0x08 (day)
+  [0e] = 0x10 (hour)
+  [0f] = 0x04 (month)
+  [10:12] = 0x07ea (year)
+  [12] = 0x00 (minute)
+  [13] = 0x01 (second)
+
+INTERPRETATION #1 (MOST LIKELY):
+  2026-04-08 16:00:01
+
+INTERPRETATION #2 (IF BYTES ARE SWAPPED):
+  Could be 2026-04-08 04:10:?? (but less likely)
+
+INTERPRETATION #3 (IF TIME IS ELSEWHERE):
+  Bytes at [14:16] = 0x3b2d could indicate 59 seconds, 45 ???
+  But structure is unclear
+
+CONFIDENCE: MEDIUM
+  The date part (day/month/year) is confirmed at 2026-04-08.
+  The hour=16 (4 PM) seems reasonable.
+  Minute=00 and second=01 seem offset but may reflect the sample time.
+
+================================================================================
+VOLTAGE ENCODING VERIFICATION
+================================================================================
+
+Test: uint16 BE ÷ 100
+  Raw bytes: 0x02a8
+  As BE uint16: 680
+  After ÷100: 6.80 V
+  Expected: ~6.8V ✓ MATCH
+
+Eliminated alternatives:
+  ÷1000:     0.68V ✗ (too low)
+  ÷10:       68V ✗ (too high)
+  float32 BE: no 6.8V match ✗
+  float32 LE: no 6.8V match ✗
+  Fixed-point 8.8: no match ✗
+  Fixed-point 16.0: no match ✗
+
+CONCLUSION: uint16 BE ÷ 100 is correct encoding.
+
+================================================================================
+MEMORY ENCODING VERIFICATION
+================================================================================
+
+Test: uint32 BE (bytes), convert to KB
+  
+  Memory Total:
+    Raw bytes: 0x000efff2
+    As BE uint32: 983,026
+    In KB: 983,026 ÷ 1024 = 960.0 KB
+    Spec: ~960 KB ✓ MATCH
+
+  Memory Free:
+    Raw bytes: 0x000e9e52
+    As BE uint32: 958,034
+    In KB: 958,034 ÷ 1024 = 935.6 KB
+    Spec: ~936 KB ✓ MATCH
+
+  Sanity check: free (935.6) < total (960.0) ✓
+  Usage: (960.0 - 935.6) / 960.0 = 2.5% (plausible)
+
+CONCLUSION: uint32 BE (in bytes), divide by 1024 for KB.
+
+================================================================================
+PYTHON PARSING REFERENCE
+================================================================================
+
+    from struct import unpack
+    
+    data = bytes.fromhex("2c00000000000000000000000008100407ea00013b2d...")
+    
+    monitor_mode = data[0x00]
+    day = data[0x0d]
+    hour = data[0x0e]
+    month = data[0x0f]
+    year = unpack('>H', data[0x10:0x12])[0]
+    minute = data[0x12]
+    second = data[0x13]
+    
+    voltage_v = unpack('>H', data[0x2f:0x31])[0] / 100.0
+    memory_total_kb = unpack('>I', data[0x31:0x35])[0] / 1024.0
+    memory_free_kb = unpack('>I', data[0x35:0x39])[0] / 1024.0
+    
+    print(f"Monitor: {['ON', 'OFF'][monitor_mode == 0x2c]}")
+    print(f"Date: {year:04d}-{month:02d}-{day:02d}")
+    print(f"Time: {hour:02d}:{minute:02d}:{second:02d}")
+    print(f"Battery: {voltage_v:.2f} V")
+    print(f"Memory: {memory_total_kb:.1f} KB total, {memory_free_kb:.1f} KB free")
+
+================================================================================

experiments.py

@@ -0,0 +1,634 @@
+#!/usr/bin/env python3
+"""
+experiments.py — Protocol minimization experiments for MiniMate Plus.
+
+Goal: figure out which steps in Blastware's sequences are truly required vs.
+cargo-culted, so we can build a faster, smarter client.
+
+Each experiment is self-contained (opens its own TCP connection) and reports
+PASS / FAIL / INCONCLUSIVE with timing and notes.
+
+Usage:
+    python experiments.py [--host IP] [--port PORT] [exp1 exp2 ...]
+
+    Run all:       python experiments.py
+    Run specific:  python experiments.py cold_status fast_event_count no_5a
+
+Available experiments
+---------------------
+  cold_status       EXP1  Monitor status (1C) with NO prior POLL
+  fast_event_count  EXP2  Event count via POLL+08 only — skip identity reads
+  no_5a             EXP3  Event record (0C) without bulk waveform stream (5A)
+  skip_1e           EXP4  0A/0C directly with cached key — skip initial 1E
+  fewer_polls       EXP5  Only 1 POLL before 5A instead of Blastware's 3
+  compliance_only   EXP6  Write compliance ONLY (71x3→72), skip event index+trigger+waveform
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import struct
+import sys
+import time
+from dataclasses import dataclass, field
+from typing import Optional
+
+logging.basicConfig(
+    level=logging.WARNING,          # experiment output is via print(); set DEBUG for wire trace
+    format="%(asctime)s  %(levelname)-7s  %(name)-20s  %(message)s",
+    datefmt="%H:%M:%S",
+)
+log = logging.getLogger("experiments")
+
+# ── Imports ───────────────────────────────────────────────────────────────────
+
+from minimateplus.transport import TcpTransport
+from minimateplus.protocol import (
+    MiniMateProtocol,
+    ProtocolError,
+    TimeoutError as ProtoTimeout,
+    SUB_MONITOR_STATUS,
+    SUB_SERIAL_NUMBER,
+    SUB_FULL_CONFIG,
+    SUB_EVENT_INDEX,
+    SUB_COMPLIANCE,
+    SUB_WRITE_CONFIRM_A,
+    SUB_WRITE_CONFIRM_B,
+)
+from minimateplus.framing import build_bw_frame, SESSION_RESET
+from minimateplus.client import (
+    MiniMateClient,
+    _decode_compliance_config_into,
+    _encode_compliance_config,
+)
+from minimateplus.models import DeviceInfo
+
+
+DEFAULT_HOST = "63.43.212.232"
+DEFAULT_PORT = 9034
+
+
+# ── Result container ──────────────────────────────────────────────────────────
+
+@dataclass
+class Result:
+    name:     str
+    outcome:  str        # "PASS" | "FAIL" | "INCONCLUSIVE"
+    elapsed:  float = 0.0
+    notes:    str   = ""
+    details:  dict  = field(default_factory=dict)
+
+    def __str__(self) -> str:
+        sym = {"PASS": "✅", "FAIL": "❌", "INCONCLUSIVE": "⚠️ "}.get(self.outcome, "?")
+        lines = [f"  {sym}  {self.outcome:13s}  {self.name}  ({self.elapsed:.1f}s)"]
+        if self.notes:
+            lines.append(f"       {self.notes}")
+        for k, v in self.details.items():
+            lines.append(f"       {k}: {v}")
+        return "\n".join(lines)
+
+
+# ── Connection helpers ────────────────────────────────────────────────────────
+
+def connect_proto(host: str, port: int, timeout: float = 15.0) -> tuple[TcpTransport, MiniMateProtocol]:
+    """Open a raw TCP connection and return (transport, proto) without any handshake."""
+    t = TcpTransport(host, port)
+    t.connect()
+    proto = MiniMateProtocol(t, recv_timeout=timeout)
+    return t, proto
+
+
+def connect_client(host: str, port: int, timeout: float = 30.0) -> tuple[MiniMateClient, DeviceInfo]:
+    """Open a MiniMateClient and run the full connect() handshake."""
+    transport = TcpTransport(host, port)
+    client = MiniMateClient(transport=transport, timeout=timeout)
+    client.open()
+    info = client.connect()
+    return client, info
+
+
+# ── Experiment runner ─────────────────────────────────────────────────────────
+
+def run(name: str, fn, *args, **kwargs) -> Result:
+    print(f"\n{'─'*60}")
+    print(f"  Running: {name}")
+    print(f"{'─'*60}")
+    t0 = time.time()
+    try:
+        outcome, notes, details = fn(*args, **kwargs)
+    except Exception as exc:
+        outcome = "FAIL"
+        notes   = f"Uncaught exception: {exc}"
+        details = {}
+        log.exception("Experiment %s raised:", name)
+    elapsed = time.time() - t0
+    r = Result(name=name, outcome=outcome, elapsed=elapsed, notes=notes, details=details)
+    print(str(r))
+    return r
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  EXP1 — Monitor status (1C) with NO prior POLL
+# ══════════════════════════════════════════════════════════════════════════════
+#
+#  Blastware always does a full POLL handshake before any other command.
+#  We want to know: can we query SUB 1C (battery, memory, monitoring state)
+#  cold, with only a SESSION_RESET signal and no POLL at all?
+#
+#  If PASS: status checks become near-instant (no ~1s POLL round-trip).
+#  If FAIL: we need POLL first, but maybe we can cache it.
+
+def exp_cold_status(host: str, port: int) -> tuple[str, str, dict]:
+    """SUB 1C without any POLL — just SESSION_RESET + 1C probe + 1C data."""
+    t, proto = connect_proto(host, port)
+    try:
+        print("  Sending SESSION_RESET only (no POLL)")
+        t.write(SESSION_RESET)
+        time.sleep(0.1)
+
+        print("  Sending SUB 1C probe (no POLL first)…")
+        rsp_sub = (0xFF - SUB_MONITOR_STATUS) & 0xFF   # 0xE3
+        t.write(build_bw_frame(SUB_MONITOR_STATUS, 0x00))
+        probe = proto._recv_one(expected_sub=rsp_sub, timeout=8.0)
+        print(f"  1C probe OK  page_key=0x{probe.page_key:04X}  data={probe.data.hex()}")
+
+        t.write(build_bw_frame(SUB_MONITOR_STATUS, 0x2C))
+        data_rsp = proto._recv_one(expected_sub=rsp_sub, timeout=8.0)
+
+        section = data_rsp.data
+        print(f"  1C data OK  {len(section)} bytes  hex: {section.hex()}")
+
+        # Decode battery + memory from the end of the section
+        details = {"raw_bytes": len(section)}
+        if len(section) >= 10:
+            batt_raw = struct.unpack_from(">H", section, len(section) - 10)[0]
+            mem_total = struct.unpack_from(">I", section, len(section) - 8)[0]
+            mem_free  = struct.unpack_from(">I", section, len(section) - 4)[0]
+            is_monitoring = (section[1] == 0x10)
+            details["battery_v"]     = f"{batt_raw / 100:.2f} V"
+            details["memory_total"]  = f"{mem_total:,} bytes"
+            details["memory_free"]   = f"{mem_free:,} bytes"
+            details["monitoring"]    = is_monitoring
+            print(f"  battery={batt_raw/100:.2f}V  mem_free={mem_free:,}  monitoring={is_monitoring}")
+
+        return "PASS", "SUB 1C responded without any POLL — cold status read works!", details
+
+    except ProtoTimeout:
+        return "FAIL", "Device did not respond to 1C without POLL (timeout)", {}
+    except ProtocolError as exc:
+        return "FAIL", f"Protocol error: {exc}", {}
+    finally:
+        t.disconnect()
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  EXP2 — Fast event count: POLL + SUB 08 only (skip identity reads)
+# ══════════════════════════════════════════════════════════════════════════════
+#
+#  Blastware's connect() does: POLL → 15 → 01 → 1A → 08
+#  We want to know: can we skip 15/01/1A and go straight from POLL to 08?
+#
+#  Reading identity (15, 01) and full compliance (1A, ~2126 bytes over TCP)
+#  takes several seconds each connect. If we only need event count, skipping
+#  them would be a huge win.
+#
+#  If PASS: fast status poll = POLL + 08 only (~2 round trips vs ~8+).
+
+def exp_fast_event_count(host: str, port: int) -> tuple[str, str, dict]:
+    """POLL startup → SUB 08 only, skip serial/config/compliance reads."""
+    t, proto = connect_proto(host, port)
+    try:
+        print("  Running startup (POLL only)…")
+        proto.startup()
+        print("  POLL OK — now reading SUB 08 (event index) directly…")
+
+        idx_raw = proto.read_event_index()
+        print(f"  SUB 08 OK  {len(idx_raw)} bytes")
+
+        # Try to decode event count from SUB 08 payload
+        # The raw block is 88 bytes; bytes [3:7] may be a count (uint32 BE)
+        details = {"idx_raw_len": len(idx_raw)}
+        if len(idx_raw) >= 7:
+            count_candidate = struct.unpack_from(">I", idx_raw, 3)[0]
+            details["count_candidate"] = count_candidate
+            print(f"  idx[3:7] as uint32 BE = {count_candidate} (may or may not be event count)")
+
+        # Also verify we can read 1E without the identity reads having been done
+        print("  Reading 1E (event header) to confirm event access works…")
+        key4, data8 = proto.read_event_first()
+        is_empty = data8[4:8] == b"\x00\x00\x00\x00"
+        details["first_key"] = key4.hex()
+        details["is_empty"]  = is_empty
+        print(f"  1E OK  key={key4.hex()}  empty={is_empty}")
+
+        return "PASS", "POLL+08+1E all work without identity reads (15/01/1A skipped)", details
+
+    except ProtocolError as exc:
+        return "FAIL", f"Protocol error: {exc}", {}
+    finally:
+        t.disconnect()
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  EXP3 — Get event record (0C) without bulk waveform stream (5A)
+# ══════════════════════════════════════════════════════════════════════════════
+#
+#  Blastware's event download = 1E → 0A → 1E-arm → 0C → 1F(dl) → POLL×3 → 5A → 1F(browse)
+#
+#  The 5A bulk stream is the slow part (several large frames, ~1s+ per event).
+#  We only need 5A for: client, operator, seis_loc, notes (not in 0C).
+#  If you don't need those fields, can we do: 1E → 0A → 0C → 1F(browse) ?
+#
+#  Two variants tested:
+#    3a: Skip 1E-arm AND 5A — just 0A → 0C → 1F(browse)
+#    3b: Include 1E-arm but skip 5A+POLL — 0A → 1E-arm → 0C → 1F(browse)
+#
+#  If PASS: event peak values available without the slow bulk stream.
+#  If FAIL on 3a but PASS on 3b: 1E-arm required even without 5A.
+
+def exp_no_5a(host: str, port: int) -> tuple[str, str, dict]:
+    """Event record via 0A→0C without 5A or POLL×3. Tests both with and without 1E-arm."""
+    t, proto = connect_proto(host, port)
+    try:
+        print("  Startup (POLL)…")
+        proto.startup()
+
+        # Get the first event key via 1E
+        key4, data8 = proto.read_event_first()
+        if data8[4:8] == b"\x00\x00\x00\x00":
+            return "INCONCLUSIVE", "Device has no stored events — cannot test", {}
+        print(f"  First event key: {key4.hex()}")
+
+        details: dict = {"key": key4.hex()}
+
+        # ── Variant 3a: 0A → 0C → 1F(browse), no 1E-arm ─────────────────────
+        print("\n  [3a] 0A → 0C → 1F(browse)  (NO 1E-arm, NO 5A)")
+        try:
+            _hdr, rec_len = proto.read_waveform_header(key4)
+            print(f"  0A OK  rec_len=0x{rec_len:02X}")
+            record_3a = proto.read_waveform_record(key4)
+            print(f"  0C OK  {len(record_3a)} bytes")
+            # Check for recognizable content
+            has_tran = b"Tran" in record_3a
+            has_vert = b"Vert" in record_3a
+            has_long = b"Long" in record_3a
+            print(f"  0C content check: Tran={has_tran}  Vert={has_vert}  Long={has_long}")
+            details["3a_0c_bytes"] = len(record_3a)
+            details["3a_has_peaks"] = has_tran and has_vert and has_long
+
+            # Now try browse 1F without any 5A
+            key4_next, data8_next = proto.advance_event(browse=True)
+            null_sentinel = data8_next[4:8] == b"\x00\x00\x00\x00"
+            print(f"  1F(browse) → key={key4_next.hex()}  null={null_sentinel}")
+            details["3a_1f_ok"]   = True
+            details["3a_outcome"] = "PASS"
+        except ProtocolError as exc:
+            print(f"  3a FAILED: {exc}")
+            details["3a_outcome"] = f"FAIL: {exc}"
+            # Try to recover by reconnecting for 3b
+            t.disconnect()
+            t2, proto2 = connect_proto(host, port)
+            proto2.startup()
+            key4, data8 = proto2.read_event_first()
+            if data8[4:8] == b"\x00\x00\x00\x00":
+                return "FAIL", f"3a failed and device empty on retry: {exc}", details
+            t, proto = t2, proto2
+
+        # ── Variant 3b: 0A → 1E-arm → 0C → 1F(browse), no 5A ───────────────
+        print("\n  [3b] 0A → 1E-arm(0xFE) → 0C → 1F(browse)  (NO POLL×3, NO 5A)")
+        try:
+            _hdr, rec_len = proto.read_waveform_header(key4)
+            print(f"  0A OK  rec_len=0x{rec_len:02X}")
+
+            # 1E download-arm (token=0xFE) between 0A and 0C
+            proto.read_event_first(token=0xFE)
+            print("  1E-arm OK")
+
+            record_3b = proto.read_waveform_record(key4)
+            print(f"  0C OK  {len(record_3b)} bytes")
+            has_tran = b"Tran" in record_3b
+            print(f"  0C content check: Tran={has_tran}  Vert={b'Vert' in record_3b}")
+            details["3b_0c_bytes"] = len(record_3b)
+            details["3b_has_peaks"] = has_tran
+
+            # Browse 1F without 5A / POLL×3
+            key4_next2, data8_next2 = proto.advance_event(browse=True)
+            null_sentinel2 = data8_next2[4:8] == b"\x00\x00\x00\x00"
+            print(f"  1F(browse) → key={key4_next2.hex()}  null={null_sentinel2}")
+            details["3b_1f_ok"]   = True
+            details["3b_outcome"] = "PASS"
+        except ProtocolError as exc:
+            print(f"  3b FAILED: {exc}")
+            details["3b_outcome"] = f"FAIL: {exc}"
+
+        # Summarize
+        a_ok = details.get("3a_outcome") == "PASS"
+        b_ok = details.get("3b_outcome") == "PASS"
+        if a_ok:
+            return "PASS", "3a: 0A→0C works with NO 1E-arm and NO 5A. Huge speedup possible!", details
+        elif b_ok:
+            return "PASS", "3b: 0A→1E-arm→0C works without 5A (1E-arm still needed before 0C)", details
+        else:
+            return "FAIL", "Both 3a and 3b failed — 5A may be required for device state", details
+
+    except ProtocolError as exc:
+        return "FAIL", f"Protocol error during setup: {exc}", {}
+    finally:
+        try:
+            t.disconnect()
+        except Exception:
+            pass
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  EXP4 — Skip initial 1E if we already know the event key
+# ══════════════════════════════════════════════════════════════════════════════
+#
+#  In Blastware, every session starts with 1E to discover the first key.
+#  But if we already fetched and cached the event keys from a previous session,
+#  can we skip 1E entirely and go straight to 0A(cached_key)?
+#
+#  Practical use case: we poll the device every N minutes. We already know
+#  all the event keys from last time. On re-connect, can we go direct to 0A?
+#
+#  If PASS: subsequent polls that don't add new events can skip 1E discovery.
+
+def exp_skip_1e(host: str, port: int) -> tuple[str, str, dict]:
+    """Get the first event key, disconnect, reconnect, go straight to 0A (skip 1E)."""
+    # Phase 1: get the key
+    t, proto = connect_proto(host, port)
+    try:
+        proto.startup()
+        key4, data8 = proto.read_event_first()
+        if data8[4:8] == b"\x00\x00\x00\x00":
+            return "INCONCLUSIVE", "No events stored — cannot test", {}
+        print(f"  Phase 1: got event key = {key4.hex()}")
+    finally:
+        t.disconnect()
+    time.sleep(0.5)
+
+    # Phase 2: fresh connection, skip 1E, go straight to 0A with cached key
+    t2, proto2 = connect_proto(host, port)
+    try:
+        print("  Phase 2: fresh connection — startup + 0A directly (no 1E)")
+        proto2.startup()
+
+        _hdr, rec_len = proto2.read_waveform_header(key4)
+        print(f"  0A OK  rec_len=0x{rec_len:02X}")
+
+        record = proto2.read_waveform_record(key4)
+        has_peaks = b"Tran" in record
+        print(f"  0C OK  {len(record)} bytes  has_peaks={has_peaks}")
+
+        details = {
+            "cached_key":  key4.hex(),
+            "0c_bytes":    len(record),
+            "has_peaks":   has_peaks,
+        }
+        return "PASS", "0A works with cached key — 1E discovery can be skipped on known sessions", details
+
+    except ProtocolError as exc:
+        return "FAIL", f"0A failed with cached key (device needs 1E first?): {exc}", {"key": key4.hex()}
+    finally:
+        t2.disconnect()
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  EXP5 — Fewer POLLs before 5A (try POLL×1 instead of Blastware's POLL×3)
+# ══════════════════════════════════════════════════════════════════════════════
+#
+#  Blastware always sends 3 full POLL probe+data cycles between 1F and 5A.
+#  Each POLL is a round trip. Can we get away with just 1?
+#
+#  WARNING: If POLL×1 fails, the device may be in a bad state. We try to
+#  recover with an extra POLL×2 and a fresh 5A attempt. Even on failure we
+#  try to leave the device in a usable state.
+#
+#  Strategy: run the full event sequence up to 1F(download), then try 5A
+#  with only 1 POLL. If 5A responds → PASS. If timeout → try 2 more POLLs
+#  and check if the device recovers.
+
+def exp_fewer_polls(host: str, port: int) -> tuple[str, str, dict]:
+    """Full sequence to 1F, then only 1 POLL before 5A (Blastware does 3)."""
+    t, proto = connect_proto(host, port)
+    try:
+        proto.startup()
+
+        key4, data8 = proto.read_event_first()
+        if data8[4:8] == b"\x00\x00\x00\x00":
+            return "INCONCLUSIVE", "No events stored — cannot test", {}
+        print(f"  Event key: {key4.hex()}")
+
+        # Full setup: 0A → 1E-arm → 0C → 1F(download)
+        _hdr, rec_len = proto.read_waveform_header(key4)
+        print(f"  0A OK  rec_len=0x{rec_len:02X}")
+        proto.read_event_first(token=0xFE)   # 1E-arm
+        print("  1E-arm OK")
+        proto.read_waveform_record(key4)
+        print("  0C OK")
+        arm_key4, _ = proto.advance_event(browse=False)  # 1F(download) — arms 5A
+        print(f"  1F(download) OK  arm_key={arm_key4.hex()}")
+
+        # Only 1 POLL (Blastware does 3)
+        print("  Sending 1 POLL (instead of 3)…")
+        proto.poll()
+        print("  POLL ok — now probing 5A…")
+
+        try:
+            frames = proto.read_bulk_waveform_stream(key4, stop_after_metadata=True, max_chunks=12)
+            print(f"  5A OK after 1 POLL  — {len(frames)} frames received")
+            details = {"poll_count": 1, "frames": len(frames)}
+            return "PASS", "5A works with only 1 POLL (saved 2 round-trips per event)!", details
+
+        except ProtoTimeout:
+            print("  5A timed out after 1 POLL — device needs more POLLs")
+            # Attempt recovery: send 2 more POLLs and see if 5A then works
+            print("  Attempting recovery: 2 more POLLs…")
+            try:
+                proto.poll()
+                proto.poll()
+                frames2 = proto.read_bulk_waveform_stream(key4, stop_after_metadata=True, max_chunks=12)
+                print(f"  5A worked after total 3 POLLs ({len(frames2)} frames)")
+                return "FAIL", "5A needs 3 POLLs — 1 is not enough (recovery confirmed 3 still works)", {
+                    "poll_count_tried": 1, "recovery_polls": 3, "recovery_frames": len(frames2)
+                }
+            except ProtocolError as exc2:
+                return "FAIL", f"5A failed even after 3 total POLLs — device may need reconnect: {exc2}", {}
+
+    except ProtocolError as exc:
+        return "FAIL", f"Setup failed: {exc}", {}
+    finally:
+        t.disconnect()
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  EXP6 — Compliance-only write (71×3→72), skip event index + trigger + waveform
+# ══════════════════════════════════════════════════════════════════════════════
+#
+#  Blastware's full write sequence: 68→73 | 71×3→72 | 82→83 | 69→74→72
+#  We want to know: can we write ONLY the compliance block (71×3→72)?
+#
+#  Test procedure:
+#    1. Read current compliance config (SUB 1A)
+#    2. Patch the "notes" field to a test marker
+#    3. Write ONLY 71×3→72 (skip 68, 73, 82, 83, 69, 74, final 72)
+#    4. Read back (SUB 1A) and verify the change was written
+#    5. Restore original value
+#
+#  If PASS: we can push individual config fields without touching event index,
+#           trigger config, or waveform data — huge simplification.
+#  If FAIL: the device needs the full write sequence (may reject partial write).
+#
+#  SAFETY: We restore original data in a finally block. If the restore write
+#  fails, the device will have the test marker in "notes" — harmless but visible.
+
+_EXP6_MARKER = "[exp6-test]"
+
+def exp_compliance_only(host: str, port: int) -> tuple[str, str, dict]:
+    """Write compliance block alone (71×3→72), verify, and restore."""
+    client, info = connect_client(host, port)
+    original_raw: Optional[bytes] = None
+    try:
+        proto = client._proto
+        if proto is None:
+            return "FAIL", "Could not get protocol handle from client", {}
+
+        # 1. Read current compliance
+        print("  Reading current compliance config (SUB 1A)…")
+        original_raw = proto.read_compliance_config()
+        print(f"  Got {len(original_raw)} bytes of compliance config")
+
+        # Find current notes value for display
+        info_obj = DeviceInfo()
+        _decode_compliance_config_into(original_raw, info_obj)
+        cc = info_obj.compliance_config
+        orig_notes = cc.notes if cc else "(unknown)"
+        print(f"  Current notes field: {orig_notes!r}")
+
+        # 2. Build modified payload with test marker in notes
+        test_notes = _EXP6_MARKER
+        modified_raw = _encode_compliance_config(
+            original_raw,
+            notes=test_notes,
+        )
+        print(f"  Encoded modified compliance payload ({len(modified_raw)} bytes)")
+        print(f"  Patching notes: {orig_notes!r} → {test_notes!r}")
+
+        # 3. Write ONLY the compliance block: 71×3 → 72
+        print("  Writing compliance ONLY (71×3→72) — skipping 68/73/82/83/69/74…")
+        proto.write_compliance_config_raw(modified_raw)
+        print("  Write complete — device acked 71×3→72")
+
+        # 4. Read back and verify
+        print("  Reading back compliance config to verify…")
+        readback_raw = proto.read_compliance_config()
+        readback_info = DeviceInfo()
+        _decode_compliance_config_into(readback_raw, readback_info)
+        rb_cc = readback_info.compliance_config
+        readback_notes = rb_cc.notes if rb_cc else "(decode failed)"
+        print(f"  Read-back notes: {readback_notes!r}")
+
+        write_worked = (readback_notes == test_notes)
+        print(f"  Write verified: {write_worked}")
+
+        details = {
+            "original_notes":  orig_notes,
+            "written_notes":   test_notes,
+            "readback_notes":  readback_notes,
+            "write_verified":  write_worked,
+        }
+
+        if write_worked:
+            return "PASS", "Compliance-only write works! No event index or trigger writes needed.", details
+        else:
+            return "FAIL", f"Write was not reflected in read-back (got {readback_notes!r})", details
+
+    except ProtocolError as exc:
+        return "FAIL", f"Protocol error: {exc}", {}
+
+    finally:
+        # Restore original compliance data regardless of outcome
+        if original_raw is not None:
+            print("  Restoring original compliance config…")
+            try:
+                proto2 = client._proto
+                if proto2:
+                    proto2.write_compliance_config_raw(
+                        _encode_compliance_config(original_raw)  # no-op patch = verbatim
+                    )
+                    print("  Restore complete")
+                else:
+                    print("  WARNING: protocol handle gone — could not restore")
+            except Exception as exc_r:
+                print(f"  WARNING: restore failed: {exc_r}")
+        client.close()
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+#  Registry + main
+# ══════════════════════════════════════════════════════════════════════════════
+
+EXPERIMENTS = {
+    "cold_status":        ("EXP1", exp_cold_status,        "Monitor status (1C) with no POLL"),
+    "fast_event_count":   ("EXP2", exp_fast_event_count,   "Event count via POLL+08, skip identity reads"),
+    "no_5a":              ("EXP3", exp_no_5a,              "Event record (0C) without bulk waveform (5A)"),
+    "skip_1e":            ("EXP4", exp_skip_1e,            "0A/0C with cached key — skip initial 1E"),
+    "fewer_polls":        ("EXP5", exp_fewer_polls,        "1 POLL before 5A instead of Blastware's 3"),
+    "compliance_only":    ("EXP6", exp_compliance_only,    "Compliance-only write (71×3→72), no other blocks"),
+}
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="MiniMate Plus protocol minimization experiments")
+    ap.add_argument("--host", default=DEFAULT_HOST)
+    ap.add_argument("--port", type=int, default=DEFAULT_PORT)
+    ap.add_argument("--debug", action="store_true", help="Enable DEBUG wire logging")
+    ap.add_argument("experiments", nargs="*",
+                    help=f"Which to run (default: all). Choices: {', '.join(EXPERIMENTS)}")
+    args = ap.parse_args()
+
+    if args.debug:
+        logging.getLogger().setLevel(logging.DEBUG)
+
+    which = args.experiments or list(EXPERIMENTS.keys())
+    unknown = [e for e in which if e not in EXPERIMENTS]
+    if unknown:
+        print(f"Unknown experiments: {unknown}")
+        print(f"Available: {', '.join(EXPERIMENTS)}")
+        sys.exit(1)
+
+    print(f"\n{'═'*60}")
+    print(f"  MiniMate Plus Protocol Minimization Experiments")
+    print(f"  Target: {args.host}:{args.port}")
+    print(f"  Running: {', '.join(which)}")
+    print(f"{'═'*60}")
+
+    results: list[Result] = []
+    for key in which:
+        tag, fn, desc = EXPERIMENTS[key]
+        label = f"{tag}: {desc}"
+        r = run(label, fn, args.host, args.port)
+        results.append(r)
+        time.sleep(1.5)   # brief pause between experiments — let device settle
+
+    print(f"\n\n{'═'*60}")
+    print("  SUMMARY")
+    print(f"{'═'*60}")
+    for r in results:
+        sym = {"PASS": "✅", "FAIL": "❌", "INCONCLUSIVE": "⚠️ "}.get(r.outcome, "?")
+        print(f"  {sym}  {r.outcome:13s}  {r.name}")
+    print(f"{'═'*60}")
+
+    passed = sum(1 for r in results if r.outcome == "PASS")
+    failed = sum(1 for r in results if r.outcome == "FAIL")
+    skipped = sum(1 for r in results if r.outcome == "INCONCLUSIVE")
+    print(f"  {passed} passed  {failed} failed  {skipped} inconclusive")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        print("\nInterrupted.")
+        sys.exit(0)

minimateplus/__init__.py

@@ -0,0 +1,27 @@
+"""
+minimateplus — Instantel MiniMate Plus protocol library.
+
+Provides a clean Python API for communicating with MiniMate Plus seismographs
+over RS-232 serial (direct cable) or TCP (modem / ACH Auto Call Home).
+
+Typical usage (serial):
+    from minimateplus import MiniMateClient
+
+    with MiniMateClient("COM5") as device:
+        info   = device.connect()
+        events = device.get_events()
+
+Typical usage (TCP / modem):
+    from minimateplus import MiniMateClient
+    from minimateplus.transport import TcpTransport
+
+    with MiniMateClient(transport=TcpTransport("203.0.113.5", 12345)) as device:
+        info = device.connect()
+"""
+
+from .client import MiniMateClient
+from .models import DeviceInfo, Event, MonitorLogEntry
+from .transport import SerialTransport, TcpTransport
+
+__version__ = "0.1.0"
+__all__ = ["MiniMateClient", "DeviceInfo", "Event", "MonitorLogEntry", "SerialTransport", "TcpTransport"]

minimateplus/blastware_file.py

@@ -0,0 +1,949 @@
+"""
+blastware_file.py — Blastware binary file codec for bidirectional interoperability.
+
+Reads and writes the proprietary Instantel/Blastware file formats:
+  Waveform events (.CE0W, .VM0H, .440, .7M0, etc.) (extension encoding UNKNOWN — see below)
+  .MLG                        — Monitor log (monitoring session history)
+
+All waveform formats share a common 22-byte file header prefix and identical
+internal binary structure (same type tag 00 12 03 00, same STRT record layout).
+Blastware identifies the file type by extension, not by a magic marker.
+
+EXTENSION ENCODING — V10.72 firmware FULLY CONFIRMED 2026-04-22:
+
+  Direct / manual download:   AB0    (3-char, no type character)
+  Call-home (ACH) download:   AB0W or AB0H  (4-char, W=waveform H=histogram)
+
+  AB = 2-char base-36 of (total_seconds % 1296), where
+  total_seconds = (event_local_time − 1985-01-01T00:00:00_local).
+  0 = always literal digit zero.
+  Verified against 3,248 call-home files from a 10-year production archive.
+
+  The 10-year archive contains only ACH files (all end in W or H).
+  Manual Blastware downloads produce 3-char AB0 extensions — same encoding
+  but without the trailing type character.
+
+  Old firmware (S338, 3-char extensions): encoding unknown / same as manual?
+  Micromate Series 4 uses a different scheme (literal datetime in filename).
+
+─── File structure overview ─────────────────────────────────────────────────────
+
+Waveform file structure (confirmed from example-events/4-3-26-multi/M529LIY6 (example event)):
+
+  [22B header] [21B STRT record] [body bytes] [26B footer]
+
+  Header (22 bytes):
+    10 00 01 80 00 00  — fixed prefix
+    49 6e 73 74 61 6e 74 65 6c 00  — b'Instantel\x00'
+    07 2c              — fixed
+    00 12 03 00        — waveform file type tag (shared by all waveform extensions)
+
+  STRT record (21 bytes, immediately follows header):
+    53 54 52 54  — b'STRT'
+    ff fe        — fixed (2 bytes)
+    [key4]       — 4-byte waveform event key
+    [key4]       — 4-byte waveform event key (repeated)
+    [zeros]      — 7 bytes padding
+    [rectime]    — uint8 record time in seconds
+
+  Body (variable — reconstructed from A5 frame data):
+    The body bytes are derived from the raw A5 frame wire content, specifically
+    from the DLE-decoded representation of each frame's contribution.  See the
+    _frame_body_bytes() helper for the exact algorithm.
+
+  Footer (26 bytes):
+    0e 08
+    [ts1: 8B big-endian timestamp]  — start timestamp
+    [ts2: 8B big-endian timestamp]  — stop timestamp
+    00 01 00 02 00 00
+    [crc: 2B]  — CRC (algorithm unconfirmed; written as 0x00 0x00 placeholder)
+
+  Timestamp format (big-endian, 8 bytes):
+    [day] [month] [year_HI] [year_LO] [0x00] [hour] [min] [sec]
+
+MLG (monitor log, confirmed from example-events/4-3-26-multi/BE11529.MLG):
+
+  [308B header] [N × 292B records]
+
+  Header (308 bytes):
+    Offset 0x00: 10 00 01 80 00 00 Instantel\x00 07 2c 22 01 0e a0  — fixed (16B)
+    Offset 0x10: ... (unknown structure, written as zeros + serial)
+    Offset 0x2A: serial number (8 bytes, null-padded ASCII, e.g. "BE11529")
+    ... zero-padded to 308 bytes total
+
+  Record (292 bytes each):
+    [2B CRC]  — unknown algorithm; written as 0x00 0x00
+    22 01 0e 80  — record marker
+    [ts1: 8B big-endian timestamp]  — start time
+    [ts2: 8B big-endian timestamp]  — stop time (zeros if no stop)
+    [4B flags]  — see MLG_FLAGS_* constants below
+    [10B serial]  — null-padded serial number ASCII
+    [text]  — for trigger records: [0x08][8B ts1_copy] then ASCII "Geo: X.XXX in/s"
+             for monitoring records: b'' (or minimal separator)
+    [zero-padded to 292 bytes]
+
+─── Critical implementation notes ──────────────────────────────────────────────
+
+Waveform body reconstruction algorithm (confirmed 2026-04-21 from verification against
+M529LIY6 (example event) using raw_s3_20260403_153508.bin capture):
+
+  The waveform body bytes come from the A5 frame content, stripped of DLE-framing
+  artifacts.  Each A5 frame contributes a different slice of its data section,
+  with DLE+{0x02,0x03,0x04} byte pairs stripped.
+
+  Skip amounts per frame index (offsets into frame.data):
+    A5[0] (probe):     data[strt_pos + 21 + 7]  (skip header + STRT record)
+                       strt_pos found by searching frame.data[7:] for b'STRT';
+                       the contribution starts at strt_pos + 21 within data[7:]
+                       which equals strt_pos + 21 + 7 within frame.data.
+    A5[1]:             data[13]   (skip 7-byte frame.data prefix + 6 header bytes)
+    A5[2..N]:          data[12]   (skip 7-byte frame.data prefix + 5 header bytes)
+    Terminator A5:     data[11]   (1 byte less than chunk frames; terminator inner header
+                                   is 4 bytes instead of 5 — confirmed 2026-04-21)
+
+  DLE strip rule (applied AFTER slicing):
+    Strip any 0x10 byte that is immediately followed by 0x02, 0x03, or 0x04.
+    This undoes the DLE-escape that S3FrameParser preserves as literal pairs.
+    Applied to frame.data[skip:] + bytes([frame.chk_byte]) together, then
+    conditionally exclude the trailing chk_byte from the output.
+
+  chk_byte absorption:
+    When frame.data[-1] == 0x10 AND frame.chk_byte ∈ {0x02, 0x03, 0x04},
+    the last byte of frame.data is the DLE prefix of a split DLE+chk pair.
+    Including chk_byte in the strip buffer allows the pair to be stripped as
+    a unit.  After stripping, the trailing chk_byte is ALWAYS removed — because
+    _strip_inner_frame_dles keeps the byte after the DLE (the chk_byte value),
+    and that value is the checksum, never payload.  This applies to all three
+    cases (chk ∈ {0x02, 0x03, 0x04}) identically.
+
+MLG CRC:
+  The algorithm that produces the 2-byte CRC at the start of each MLG record
+  is unknown.  All examined records use non-zero values that do not match
+  CRC-16/CCITT, CRC-16/IBM, CRC-32 (truncated), word sums, XOR variants, or
+  any of the 40+ polynomial/init combinations tested.  The writer emits 0x0000.
+  This produces files that Blastware may reject or display without the CRC check —
+  the exact impact on BW import is unknown (TODO: test).
+
+─── Public API ──────────────────────────────────────────────────────────────────
+
+  blastware_filename(event, serial)
+      Return the correct Blastware filename for an event (e.g. "M529LIY6.CE0W").
+      Full AB0T extension encoding confirmed 2026-04-22 against 3,248 archive files.
+      Extension matches what Blastware itself would generate for the same event.
+
+  write_blastware_file(event, a5_frames, path)
+      Create a Blastware waveform file from an Event and the full A5 frame list.
+      All waveform extensions share the same binary format — the extension is set
+      by blastware_filename() based on the event timestamp and type.
+
+  read_blastware_file(path) → Event
+      Parse a Blastware waveform file into an Event object with waveform data populated.
+      (Not yet implemented — placeholder raises NotImplementedError.)
+
+  write_mlg(entries, serial, path)
+      Create a .MLG file from a list of MonitorLogEntry objects.
+
+  read_mlg(path) → list[MonitorLogEntry]
+      Parse a .MLG file into MonitorLogEntry objects.
+      (Not yet implemented — placeholder raises NotImplementedError.)
+"""
+
+from __future__ import annotations
+
+import datetime
+import logging
+import struct
+from pathlib import Path
+from typing import Optional, Union
+
+from .framing import S3Frame
+from .models import Event, MonitorLogEntry, Timestamp
+
+log = logging.getLogger(__name__)
+
+# ── File header constants ─────────────────────────────────────────────────────
+
+# Common 16-byte prefix shared by waveform files and MLG (confirmed from binary inspection).
+_FILE_HEADER_PREFIX = bytes.fromhex("1000018000004973") + b"tantel\x00\x07\x2c"
+# = 10 00 01 80 00 00 49 73 74 61 6e 74 65 6c 00 07 2c  (17 bytes)
+# Confirmed breakdown: 10 00 01 80 00 00 = fixed; "Instantel\x00" = 10B; 07 2c = fixed
+
+# Simpler construction:
+_FILE_HEADER_PREFIX = b"\x10\x00\x01\x80\x00\x00Instantel\x00\x07\x2c"  # 17 bytes
+
+# Waveform file type tag (4 bytes after common prefix) — shared by ALL waveform extensions
+_WAVEFORM_TYPE_TAG = b"\x00\x12\x03\x00"   # confirmed from M529LIY6 (example event) — same tag for .CE0W, .VM0H, etc.
+
+# MLG type tag (4 bytes after common prefix)
+_MLG_TYPE_TAG = b"\x22\x01\x0e\xa0"   # confirmed from BE11529.MLG  offset 0x11..0x14
+
+# Total header sizes
+_WAVEFORM_HEADER_SIZE = 22    # 17 + 4 = 21... wait. Let me recalculate.
+# From binary: first 22 bytes = header, then STRT at byte 22.
+# 17-byte common prefix + 4-byte type tag = 21 bytes. But observed header is 22B.
+# Checking: 6 fixed + 10 "Instantel\x00" + 2 "07 2c" = 18B prefix, then 4B type tag = 22B.
+# Re-count: b"\x10\x00\x01\x80\x00\x00" = 6B + b"Instantel\x00" = 10B + b"\x07\x2c" = 2B = 18B prefix.
+_FILE_HEADER_PREFIX = b"\x10\x00\x01\x80\x00\x00Instantel\x00\x07\x2c"  # 18 bytes
+_WAVEFORM_HEADER_SIZE = 22    # 18 + 4 = 22 bytes ✅
+_MLG_HEADER_SIZE = 308   # confirmed from BE11529.MLG
+
+# MLG record marker (4 bytes after 2-byte CRC at start of each record)
+_MLG_RECORD_MARKER = b"\x22\x01\x0e\x80"
+_MLG_RECORD_SIZE   = 292   # bytes per record (confirmed from BE11529.MLG)
+
+# MLG record flags (4 bytes at record[22:26])
+# Confirmed from BE11529.MLG binary inspection:
+MLG_FLAGS_START_ONLY = b"\xff\xff\x00\x00"   # monitoring start with no stop
+MLG_FLAGS_TRIGGER    = b"\x01\x00\x02\x00"   # triggered event (has ts1 + ts2)
+MLG_FLAGS_INTERVAL   = b"\x02\x00\x00\x00"   # monitoring interval (has ts1 + ts2)
+
+
+# ── Timestamp helpers ─────────────────────────────────────────────────────────
+
+def _encode_ts_be(ts: Optional[datetime.datetime]) -> bytes:
+    """
+    Encode a datetime as an 8-byte big-endian Blastware timestamp.
+
+    Format (waveform file and MLG record timestamps):
+      [day][month][year_HI][year_LO][0x00][hour][min][sec]
+
+    Big-endian year confirmed from M529LIY6 (example event) footer:
+      footer bytes [2..9] = 01 04 07 ea 00 00 1c 08
+      → day=1 month=4 year=0x07ea=2026 hour=0 min=28 sec=8  ✅
+
+    Returns 8 zero bytes if ts is None.
+    """
+    if ts is None:
+        return bytes(8)
+    return bytes([
+        ts.day,
+        ts.month,
+        (ts.year >> 8) & 0xFF,
+        ts.year & 0xFF,
+        0x00,
+        ts.hour,
+        ts.minute,
+        ts.second,
+    ])
+
+
+def _decode_ts_be(raw: bytes) -> Optional[datetime.datetime]:
+    """
+    Decode an 8-byte big-endian Blastware timestamp.
+
+    Returns None if the bytes are all zero or structurally invalid.
+    """
+    if len(raw) < 8 or raw == bytes(8):
+        return None
+    day   = raw[0]
+    month = raw[1]
+    year  = (raw[2] << 8) | raw[3]
+    hour  = raw[5]
+    minute = raw[6]
+    sec   = raw[7]
+    try:
+        return datetime.datetime(year, month, day, hour, minute, sec)
+    except ValueError:
+        return None
+
+
+def _ts_from_model(ts: Optional[Timestamp]) -> Optional[datetime.datetime]:
+    """Convert a models.Timestamp to datetime.datetime, or None."""
+    if ts is None:
+        return None
+    try:
+        return datetime.datetime(ts.year, ts.month, ts.day, ts.hour, ts.minute, ts.second)
+    except (ValueError, TypeError):
+        return None
+
+
+# ── DLE strip helper ──────────────────────────────────────────────────────────
+
+def _strip_inner_frame_dles(data: bytes) -> bytes:
+    """
+    Strip DLE (0x10) framing markers from A5 inner-frame content.
+
+    The A5 (bulk waveform stream) response body contains DLE-encoded sub-frame
+    structure.  S3FrameParser preserves DLE+XX pairs as two literal bytes in
+    frame.data.  Only the DLE marker byte needs to be removed; the following
+    byte is actual payload content.
+
+    Rule: when 0x10 is immediately followed by {0x02, 0x03, 0x04}, strip the
+    0x10 (DLE marker) and keep the following byte as payload.
+
+    Lone 0x10 bytes not followed by {0x02, 0x03, 0x04} are kept as-is.
+
+    Confirmed correct by verifying reconstructed waveform body against M529LIY6 (example event):
+      - 0x10 0x02 in terminator → 0x02 kept ✓
+      - 0x10 0x04 in terminator (month byte) → 0x04 kept ✓
+    """
+    out = bytearray()
+    i = 0
+    while i < len(data):
+        b = data[i]
+        if b == 0x10 and i + 1 < len(data) and data[i + 1] in {0x02, 0x03, 0x04}:
+            # Strip the DLE marker; the next byte is payload and will be appended
+            # in the next loop iteration.
+            i += 1
+            continue
+        out.append(b)
+        i += 1
+    return bytes(out)
+
+
+def _frame_body_bytes(frame: S3Frame, skip: int) -> bytes:
+    """
+    Extract the waveform body contribution from one A5 S3Frame.
+
+    The contribution is frame.data[skip:] with inner-frame DLE pairs stripped
+    per _strip_inner_frame_dles().  The chk_byte is temporarily appended before
+    stripping to handle the split-pair edge case where a DLE at the end of
+    frame.data is paired with chk_byte.
+
+    Split-pair edge case (confirmed for A5[8] of M529LIY6 (example event), 2026-04-21):
+
+    S3FrameParser appends DLE+XX pairs as two literal bytes when XX ∉ {DLE, ETX}.
+    When the LAST occurrence of such a pair straddles the payload/checksum boundary
+    (i.e., DLE is the last byte of raw_payload and XX is the checksum), the parser
+    splits them:
+      - DLE ends up as the last byte of frame.data  (frame.data[-1] == 0x10)
+      - XX is stored as frame.chk_byte
+
+    To strip the pair correctly, we reunite the bytes before calling the strip
+    function.  Since chk_byte is the checksum (not payload data), it is excluded
+    from the final output regardless of whether it was part of a pair.
+
+    Post-strip chk_byte removal (ALL cases):
+      _strip_inner_frame_dles strips the 0x10 and KEEPS chk_byte in all cases.
+      Chk_byte is always the checksum (not payload), so always strip it off.
+
+    Args:
+        frame: S3Frame with frame.data and frame.chk_byte populated.
+        skip:  Number of leading bytes in frame.data to exclude (frame header).
+
+    Returns:
+        bytes — the waveform body contribution for this frame.
+    """
+    if skip >= len(frame.data):
+        return b""
+
+    relevant = frame.data[skip:]
+
+    # Detect split DLE+chk pair at the frame boundary.
+    has_split_pair = (
+        len(relevant) > 0
+        and relevant[-1] == 0x10
+        and frame.chk_byte in {0x02, 0x03, 0x04}
+    )
+
+    if has_split_pair:
+        # Reunite the split pair so the strip function sees both bytes together.
+        buf = relevant + bytes([frame.chk_byte])
+        stripped = _strip_inner_frame_dles(buf)
+        # _strip_inner_frame_dles strips the DLE (0x10) and KEEPS chk_byte.
+        # chk_byte is the received checksum — never payload — so remove it.
+        # This is correct for all values in {0x02, 0x03, 0x04}.
+        if stripped:
+            stripped = stripped[:-1]
+        return stripped
+    else:
+        return _strip_inner_frame_dles(relevant)
+
+
+# ── Filename helper ───────────────────────────────────────────────────────────
+
+_INSTANTEL_EPOCH = datetime.datetime(1985, 1, 1, 0, 0, 0)
+"""
+Instantel timestamp epoch — January 1, 1985, 00:00:00 local time.
+Confirmed 2026-04-21: stem values for 6 independent events (April 1–9, 2026)
+all converge to this epoch when decoded as floor(seconds_since_epoch / 1296).
+1985 is the year Instantel was founded.
+"""
+
+_STEM_UNIT_SEC = 1296  # = 36^2 seconds ≈ 21.6 minutes per stem unit
+
+_STEM_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+
+# ── Waveform file extension encoding ─────────────────────────────────────────
+#
+# NEW FIRMWARE (V10.72+) — FULLY DECODED (confirmed 2026-04-21, 10-year archive):
+#
+#   Extension format: AB0T  (4 characters)
+#     AB = 2-char base-36 encoding of (seconds_since_epoch % 1296)
+#          i.e. the number of seconds into the current 21.6-minute stem window
+#          Range: 0 ("00") to 1295 ("ZZ")
+#     0  = always literal '0'
+#     T  = event type:  'W' = Full Waveform,  'H' = Full Histogram
+#
+#   Combined with the 4-char stem (which encodes seconds_since_epoch // 1296),
+#   the FULL filename gives a second-resolution timestamp:
+#     total_seconds = stem_val * 1296 + ab_val
+#     timestamp = EPOCH + timedelta(seconds=total_seconds)
+#
+#   Verified against three S353L4H0 events (all three match to the second):
+#     S353L4H0.3M0W  Full Waveform   2025-06-23 13:57:22  AB=3M=130  ✓
+#     S353L4H0.8S0H  Full Histogram  2025-06-23 14:00:28  AB=8S=316  ✓
+#     S353L4H0.9X0W  Full Waveform   2025-06-23 14:01:09  AB=9X=357  ✓
+#
+# OLD FIRMWARE (S338, 3-char extensions ending in '0') — UNKNOWN:
+#   Observed (old firmware / manual downloads): .440, .470, .7M0, .9T0, .EI0, etc.
+#   The V10.72 formula does NOT apply to these.
+#   Extension is NOT recording mode (refuted 2026-04-21: continuous → .EI0, not .9T0).
+#   blastware_filename() computes the correct AB0 extension for V10.72 firmware.
+#
+# WRONG earlier assumption (do not re-introduce):
+#   Extension was believed to encode recording mode × sample rate.
+#   Refuted by continuous-mode event producing .EI0 instead of .9T0.
+
+
+def _make_stem(ts_local: datetime.datetime) -> str:
+    """
+    Encode a local timestamp as a 4-character uppercase base-36 stem.
+
+    Algorithm (confirmed 2026-04-21 from 6 known file/timestamp pairs):
+      stem_int = floor((ts_local - Jan_1_1985_midnight_local) / 1296_seconds)
+      stem = 4-char uppercase base-36 encoding of stem_int
+
+    Unit = 36² = 1296 seconds ≈ 21.6 minutes.  Events within the same 1296-second
+    window receive the same stem; their extension distinguishes them.
+    """
+    delta_sec = int((ts_local - _INSTANTEL_EPOCH).total_seconds())
+    n = delta_sec // _STEM_UNIT_SEC
+    s = ""
+    for _ in range(4):
+        s = _STEM_CHARS[n % 36] + s
+        n //= 36
+    return s
+
+
+def blastware_filename(event: Event, serial: str, ach: bool = False) -> str:
+    """
+    Return the correct Blastware filename for an event.
+
+    CONFIRMED 2026-04-22 — verified against 3,248 files from a 10-year archive.
+
+    Filename format: <prefix_letter><serial3><stem><AB>0[T]
+    where:
+
+      prefix_letter = chr(ord('B') + floor(serial_numeric / 1000))
+        — encodes the production generation (batch of 1000 units)
+        — e.g. BE6907→H, BE11529→M, BE14036→P, BE18003→T
+
+      serial3 = f"{serial_numeric % 1000:03d}"
+        — last 3 digits of numeric serial, zero-padded
+
+      stem = 4-char base-36 of floor(total_seconds / 1296)
+        — encodes which 21.6-minute window the event fell in
+
+      AB = 2-char base-36 of (total_seconds % 1296)
+        — encodes seconds within the window (0–1295)
+
+      0 = always literal digit zero
+
+      T = 'W' or 'H' — ONLY appended for call-home (ACH) downloads (ach=True).
+        Manual / direct downloads produce a 3-char extension (AB0) with no type char.
+        Call-home downloads produce a 4-char extension (AB0W or AB0H).
+
+      total_seconds = (event_local_time − 1985-01-01T00:00:00_local) in seconds
+
+    The 10-year production archive contains only call-home files (all end in W or H).
+    Manual Blastware downloads produce 3-char extensions — the same AB0 prefix but
+    without the trailing type character.
+
+    Micromate Series 4 uses a completely different naming scheme (literal datetime
+    in filename); this function does not apply to Micromate units.
+
+    Args:
+        event:  Event object with timestamp set.
+        serial: Device serial number string (e.g. "BE11529").
+        ach:    If True, append W/H type character (call-home style).
+                If False (default), omit type character (direct download style).
+
+    Returns:
+        Filename string, e.g. "M529LIY6.CE0" (direct) or "M529LIY6.CE0H" (ACH).
+    """
+    # ── Serial prefix ──────────────────────────────────────────────────────────
+    serial_digits = "".join(c for c in serial if c.isdigit())
+    if len(serial_digits) >= 1:
+        serial_numeric = int(serial_digits)
+        generation = serial_numeric // 1000
+        prefix_letter = chr(ord('B') + generation)
+        serial3 = f"{serial_numeric % 1000:03d}"
+    else:
+        prefix_letter = "M"   # fallback
+        serial3 = "000"
+    prefix = prefix_letter + serial3
+
+    # ── Stem + AB extension from timestamp ────────────────────────────────────
+    if event.timestamp is not None:
+        try:
+            ts_local = datetime.datetime(
+                event.timestamp.year, event.timestamp.month, event.timestamp.day,
+                event.timestamp.hour, event.timestamp.minute, event.timestamp.second,
+            )
+            delta_sec = int((ts_local - _INSTANTEL_EPOCH).total_seconds())
+            stem = _make_stem(ts_local)
+            ab_val = delta_sec % _STEM_UNIT_SEC
+            ab_str = _STEM_CHARS[ab_val // 36] + _STEM_CHARS[ab_val % 36]
+        except (ValueError, TypeError, AttributeError):
+            stem = "0000"
+            ab_str = "00"
+    else:
+        stem = "0000"
+        ab_str = "00"
+
+    # ── Type character (ACH only) ─────────────────────────────────────────────
+    if ach:
+        if getattr(event, 'recording_mode', None) in (3, 4):  # Histogram / Hist+Cont
+            type_char = 'H'
+        else:
+            type_char = 'W'
+        ext = f".{ab_str}0{type_char}"
+    else:
+        ext = f".{ab_str}0"
+
+    return prefix + stem + ext
+
+
+# ── A5 frame classifier ───────────────────────────────────────────────────────────
+
+# ASCII markers that identify a compliance-config / metadata frame.
+# These strings appear in the A5 bulk stream as part of the device's
+# compliance setup payload.  They should NEVER appear in raw ADC waveform
+# frames (which are binary-heavy, < 20 % printable ASCII).
+_METADATA_FRAME_MARKERS = (
+    b"Project:",
+    b"Client:",
+    b"Standard Recording Setup",
+    b"Extended Notes",
+    b"User Name:",
+    b"Seis Loc:",
+)
+
+
+def classify_frame(frame: S3Frame) -> str:
+    """
+    Classify an A5 bulk waveform stream frame by its content.
+
+    Returns one of:
+        "terminator"    — page_key == 0x0000
+        "probe_or_strt" — data contains b"STRT\xff\xfe" (the initial probe response)
+        "metadata"      — data contains ASCII compliance-config markers
+        "waveform"      — predominantly binary (< 20 % printable ASCII)
+        "unknown"       — none of the above criteria matched
+
+    Used by write_blastware_file() to filter non-waveform frames out of
+    the reconstructed body so that metadata blocks (Project:, Client:, …)
+    and spurious STRT records do not corrupt the output file.
+    """
+    if frame.page_key == 0x0000:
+        return "terminator"
+    data = bytes(frame.data)
+    if b"STRT\xff\xfe" in data:
+        return "probe_or_strt"
+    if any(m in data for m in _METADATA_FRAME_MARKERS):
+        return "metadata"
+    if len(data) > 0:
+        printable = sum(1 for b in data if 32 <= b < 127)
+        if printable / len(data) < 0.20:
+            return "waveform"
+    return "unknown"
+
+
+# ── Waveform file writer ───────────────────────────────────────────────────────────
+
+def write_blastware_file(
+    event: Event,
+    a5_frames: list[S3Frame],
+    path: Union[str, Path],
+) -> None:
+    """
+    Write a Blastware waveform file from a downloaded event.
+
+    Args:
+        event:     Event object (populated by get_events() or download_waveform()).
+                   Used for the STRT record (key, rectime) and footer timestamps.
+        a5_frames: Complete A5 frame list INCLUDING the terminator frame
+                   (page_key=0x0000).  Pass include_terminator=True to
+                   read_bulk_waveform_stream() when collecting frames.
+                   Must have at least 2 frames (probe + terminator).
+        path:      Destination file path.  Parent directory must exist.
+                   Extension should be set via blastware_filename().
+
+    File layout:
+        [22B header] [21B STRT] [body bytes] [26B footer]
+
+    Raises:
+        ValueError: if a5_frames is empty or has no terminator (page_key=0).
+        OSError: if the file cannot be written.
+
+    Confirmed correct waveform body reconstruction against M529LIY6 (example event) (2026-04-21).
+    """
+    if not a5_frames:
+        raise ValueError("a5_frames must not be empty")
+
+    path = Path(path)
+
+    # ── Extract STRT record from probe frame ────────────────────────────────
+    # The STRT record (21 bytes) lives verbatim inside A5[0].data[7:].
+    # It is stored as-is in the waveform file — do NOT reconstruct it from Event
+    # fields, as bytes [10:14] and [14:20] contain device-specific values
+    # (not simply key4 repeated or zero-padded).  Confirmed 2026-04-21.
+    #
+    # STRT layout (21 bytes, observed in M529LIY6 files):
+    #   [0:4]   b'STRT'
+    #   [4:6]   0xff 0xfe (fixed)
+    #   [6:10]  key4 (event key)
+    #   [10:14] device-specific field (NOT a key4 repeat)
+    #   [14:20] device-specific fields (NOT zeros)
+    #   [20]    rectime uint8 seconds
+    # Extract STRT from the DLE-stripped probe frame.
+    #
+    # frame.data[7:] is the raw wire representation; it may contain DLE+{02,03,04}
+    # inner-frame pairs that S3FrameParser preserves as two literal bytes.  The
+    # Blastware file stores the stripped form, so we must strip before extracting.
+    #
+    # Example (M529LK0Y, 2026-04-21): STRT contains value 0x02 encoded as [10 02]
+    # on the wire.  Without stripping, STRT is 22 raw bytes → write_blastware_file writes the
+    # DLE prefix into the file AND begins the body 1 byte too early (probe_skip off
+    # by 1).  Stripping fixes both.
+    #
+    # probe_skip must be computed in the RAW frame.data domain (it is used as the
+    # `skip` argument to _frame_body_bytes which operates on raw frame.data).
+    # We walk the raw bytes counting stripped bytes until we have passed
+    # strt_pos + 21 stripped bytes, giving the raw offset of the first body byte.
+    w0_raw = bytes(a5_frames[0].data[7:])
+    w0_stripped = _strip_inner_frame_dles(w0_raw)
+    strt_pos_stripped = w0_stripped.find(b"STRT")
+
+    if strt_pos_stripped >= 0:
+        strt = bytes(w0_stripped[strt_pos_stripped : strt_pos_stripped + 21])
+
+        # Walk raw bytes to find the raw-domain end of the STRT (= body start).
+        target_stripped = strt_pos_stripped + 21
+        stripped_so_far = 0
+        raw_i = 0
+        while stripped_so_far < target_stripped and raw_i < len(w0_raw):
+            if (w0_raw[raw_i] == 0x10
+                    and raw_i + 1 < len(w0_raw)
+                    and w0_raw[raw_i + 1] in {0x02, 0x03, 0x04}):
+                raw_i += 2   # DLE pair → 1 stripped byte, 2 raw bytes
+            else:
+                raw_i += 1   # normal byte → 1 stripped byte, 1 raw byte
+            stripped_so_far += 1
+        probe_skip = 7 + raw_i  # raw bytes to skip: 7 header + raw STRT length
+    else:
+        # Fallback: construct a minimal STRT if probe frame lacks it
+        key4 = event._waveform_key if hasattr(event, '_waveform_key') and event._waveform_key else bytes(4)
+        rectime = event.rectime_seconds if event.rectime_seconds is not None else 0
+        strt = b"STRT" + b"\xff\xfe" + key4 + bytes(14) + bytes([rectime & 0xFF])
+        probe_skip = 7 + 21
+
+    log.warning(
+        "write_blastware_file: strt_pos_stripped=%d  probe_skip=%d  "
+        "probe_data_len=%d  strt_hex=%s",
+        strt_pos_stripped if strt_pos_stripped >= 0 else -1,
+        probe_skip,
+        len(a5_frames[0].data),
+        strt.hex() if len(strt) >= 4 else "(short)",
+    )
+
+    if len(strt) != 21:
+        raise ValueError(f"STRT record must be 21 bytes, got {len(strt)}")
+
+    # ── Build waveform file header ─────────────────────────────────────────────────────
+    header = _FILE_HEADER_PREFIX + _WAVEFORM_TYPE_TAG
+    assert len(header) == _WAVEFORM_HEADER_SIZE, f"Waveform header must be {_WAVEFORM_HEADER_SIZE} bytes"
+
+    # ── Build body from A5 frames ────────────────────────────────────────────
+    # The waveform body is reconstructed from ALL A5 frames (data + terminator).
+    # The terminator frame's contribution includes the 26-byte footer at its end.
+    #
+    # Reconstruction layout (confirmed from M529LIY6 captures, 2026-04-21):
+    #   all_bytes = contributions from A5[0..N] + terminator_contribution
+    #   body      = all_bytes[:-26]   (everything except the last 26 bytes)
+    #   footer    = all_bytes[-26:]   (last 26 bytes = the waveform file footer)
+    #
+    # The footer bytes come directly from the terminator frame's inner content —
+    # using them verbatim ensures timestamps match the device's recorded values.
+
+    # Separate terminator from data frames.
+    # Search from the FRONT for the first terminator (page_key == 0x0000).
+    # Do NOT use a5_frames[-1] — if _a5_frames contains stray frames from a
+    # subsequent event (a known get_events side-effect), the last frame will
+    # not be the terminator and the footer will be mis-identified.
+    term_idx: Optional[int] = None
+    for _i, _f in enumerate(a5_frames):
+        if _f.page_key == 0x0000:
+            term_idx = _i
+            break
+
+    if term_idx is not None:
+        body_frames = a5_frames[:term_idx]
+        term_frame  = a5_frames[term_idx]
+    else:
+        body_frames = a5_frames
+        term_frame  = None
+
+    log.warning(
+        "write_blastware_file: %d body_frames  term_idx=%s",
+        len(body_frames),
+        str(term_idx) if term_idx is not None else "None",
+    )
+
+    all_bytes = bytearray()
+
+    for fi, frame in enumerate(body_frames):
+        # All body frames contribute to the waveform body — no frames are skipped.
+        #
+        # Over TCP via cellular modem, _recv_5a_batch() correctly collects all
+        # A5 frames per chunk request (the device's ~1100-byte RS-232 response
+        # is forwarded as ~2 TCP segments of ~550 bytes each, each parsed as a
+        # separate S3 frame).  ALL of these frames contain ADC body data and
+        # must be included in the file — confirmed from 4-27-26 TCP capture
+        # analysis: contributions from all 14 frames → 6821 bytes → file 6864 bytes.
+        #
+        # Skip amounts (offsets into frame.data):
+        #   fi=0 (probe): probe_skip — skips the type_tag header + STRT record
+        #   fi=1:         13         — 7-byte frame.data prefix + 6 inner header bytes
+        #   fi>=2:        12         — 7-byte frame.data prefix + 5 inner header bytes
+        if fi == 0:
+            skip = probe_skip
+        elif fi == 1:
+            skip = 13
+        else:
+            skip = 12
+
+        contribution = _frame_body_bytes(frame, skip)
+        log.warning("write_blastware_file: fi=%d skip=%d raw_data=%d contribution=%d",
+                    fi, skip, len(frame.data), len(contribution))
+        all_bytes.extend(contribution)
+
+    # Terminator contributes its content, which ends with the 26-byte footer.
+    # skip=11 (not 12) because the terminator's inner frame header is 4 bytes,
+    # one shorter than chunk frames' 5-byte inner header.  Confirmed 2026-04-21.
+    if term_frame is not None:
+        term_contribution = _frame_body_bytes(term_frame, 11)
+        log.warning(
+            "write_blastware_file: term_frame data_len=%d  skip=11  "
+            "contribution_len=%d  first8=%s",
+            len(term_frame.data),
+            len(term_contribution),
+            term_contribution[:8].hex() if len(term_contribution) >= 8 else term_contribution.hex(),
+        )
+        all_bytes.extend(term_contribution)
+
+    log.warning(
+        "write_blastware_file: all_bytes total=%d  last28=%s",
+        len(all_bytes),
+        bytes(all_bytes[-28:]).hex() if len(all_bytes) >= 28 else bytes(all_bytes).hex(),
+    )
+
+    if len(all_bytes) >= 26:
+        body   = bytes(all_bytes[:-26])
+        footer = bytes(all_bytes[-26:])
+    else:
+        # Fallback: no terminator or very short stream → build footer from event metadata
+        body = bytes(all_bytes)
+        start_dt = _ts_from_model(event.timestamp)
+        stop_dt: Optional[datetime.datetime] = None
+        if start_dt is not None and event.rectime_seconds:
+            stop_dt = start_dt + datetime.timedelta(seconds=event.rectime_seconds)
+        footer = (
+            b"\x0e\x08"
+            + _encode_ts_be(start_dt)
+            + _encode_ts_be(stop_dt)
+            + b"\x00\x01\x00\x02\x00\x00"
+            + b"\x00\x00"   # CRC placeholder
+        )
+
+    # ── Write file ───────────────────────────────────────────────────────────
+    with open(path, "wb") as f:
+        f.write(header)
+        f.write(strt)
+        f.write(body)
+        f.write(footer)
+
+
+def read_blastware_file(path: Union[str, Path]) -> Event:
+    """
+    Parse a Blastware waveform file into an Event object.
+
+    NOT YET IMPLEMENTED.
+
+    Args:
+        path: Path to the waveform file.
+
+    Returns:
+        Event object with waveform data populated.
+
+    Raises:
+        NotImplementedError: always (pending implementation).
+    """
+    raise NotImplementedError("read_blastware_file() is not yet implemented")
+
+
+# ── MLG file writer ───────────────────────────────────────────────────────────
+
+def _build_mlg_header(serial: str) -> bytes:
+    """
+    Build the 308-byte MLG file header.
+
+    Header structure (confirmed from BE11529.MLG binary inspection):
+      Offset 0x00: 10 00 01 80 00 00 Instantel\x00 07 2c 22 01 0e a0  (22B)
+      Offset 0x16: ... (16B unknown — observed as zeros in BE11529.MLG)
+      Offset 0x2A: serial number (8 bytes, null-padded ASCII)
+      ... rest zero-padded to 308 bytes
+
+    The serial string "BE11529" appears at offset 0x2A (42 decimal).
+    """
+    buf = bytearray(_MLG_HEADER_SIZE)
+
+    # Common prefix + MLG type tag
+    prefix = _FILE_HEADER_PREFIX + _MLG_TYPE_TAG  # 22 bytes
+    buf[0:len(prefix)] = prefix
+
+    # Serial number at offset 0x2A
+    serial_bytes = serial.encode("ascii", errors="replace")[:8]
+    serial_padded = serial_bytes.ljust(8, b"\x00")
+    buf[0x2A : 0x2A + 8] = serial_padded
+
+    return bytes(buf)
+
+
+def _build_mlg_record(
+    entry: MonitorLogEntry,
+    serial: str,
+) -> bytes:
+    """
+    Build one 292-byte MLG record from a MonitorLogEntry.
+
+    Record layout (confirmed from BE11529.MLG binary inspection):
+      [0:2]    CRC         — 2-byte CRC (algorithm unknown; written as 0x0000)
+      [2:6]    marker      — 22 01 0e 80
+      [6:14]   ts1         — 8B big-endian start timestamp
+      [14:22]  ts2         — 8B big-endian stop timestamp
+      [22:26]  flags       — 4B record flags (see MLG_FLAGS_* constants)
+      [26:36]  serial      — 10B null-padded serial number
+      [36:]    text        — for triggered events: [0x08][8B ts1_copy]["Geo: X.XXX in/s"]
+                             for monitoring intervals: b"" or minimal separator
+      [... zero-padded to 292 bytes]
+
+    Flags based on entry type:
+      - MonitorLogEntry with start_time only (no stop_time): MLG_FLAGS_START_ONLY
+      - MonitorLogEntry with both times and geo_threshold_ips set: MLG_FLAGS_TRIGGER
+      - MonitorLogEntry with both times (monitoring interval): MLG_FLAGS_INTERVAL
+
+    The triggered-event text block (flags = MLG_FLAGS_TRIGGER):
+      [0x08] [ts1: 8B] [ASCII "Geo: X.XXX in/s\x00"]
+    Confirmed from BE11529.MLG records at offset 0x0134 and 0x0258.
+    """
+    buf = bytearray(_MLG_RECORD_SIZE)
+
+    start_dt = (
+        datetime.datetime(
+            entry.start_time.year, entry.start_time.month, entry.start_time.day,
+            entry.start_time.hour, entry.start_time.minute, entry.start_time.second,
+        )
+        if entry.start_time else None
+    )
+    stop_dt = (
+        datetime.datetime(
+            entry.stop_time.year, entry.stop_time.month, entry.stop_time.day,
+            entry.stop_time.hour, entry.stop_time.minute, entry.stop_time.second,
+        )
+        if entry.stop_time else None
+    )
+
+    # [0:2] CRC placeholder
+    buf[0:2] = b"\x00\x00"
+
+    # [2:6] Record marker
+    buf[2:6] = _MLG_RECORD_MARKER
+
+    # [6:14] ts1
+    buf[6:14] = _encode_ts_be(start_dt)
+
+    # [14:22] ts2
+    buf[14:22] = _encode_ts_be(stop_dt)
+
+    # [22:26] flags
+    if stop_dt is None:
+        flags = MLG_FLAGS_START_ONLY
+    elif entry.geo_threshold_ips is not None:
+        flags = MLG_FLAGS_TRIGGER
+    else:
+        flags = MLG_FLAGS_INTERVAL
+    buf[22:26] = flags
+
+    # [26:36] serial (10B null-padded)
+    serial_bytes = serial.encode("ascii", errors="replace")[:10]
+    buf[26 : 26 + len(serial_bytes)] = serial_bytes
+
+    # [36:] text content
+    pos = 36
+    if flags == MLG_FLAGS_TRIGGER:
+        # Extra ts1 copy: [0x08][ts1: 8B]
+        buf[pos] = 0x08
+        pos += 1
+        buf[pos : pos + 8] = _encode_ts_be(start_dt)
+        pos += 8
+
+    if entry.geo_threshold_ips is not None:
+        geo_text = f"Geo: {entry.geo_threshold_ips:.3f} in/s\x00".encode("ascii")
+        buf[pos : pos + len(geo_text)] = geo_text
+        pos += len(geo_text)
+
+    return bytes(buf)
+
+
+def write_mlg(
+    entries: list[MonitorLogEntry],
+    serial: str,
+    path: Union[str, Path],
+) -> None:
+    """
+    Write a Blastware .MLG monitor log file.
+
+    Args:
+        entries: List of MonitorLogEntry objects (from get_monitor_log_entries()).
+                 Each entry produces one 292-byte record in the file.
+        serial:  Device serial number string (e.g. "BE11529").
+                 Written to the file header and each record.
+        path:    Destination file path.  Extension is not enforced — use ".MLG".
+
+    File layout:
+        [308B header] [N × 292B records]
+
+    Note: The 2-byte CRC at the start of each record is written as 0x0000.
+    The CRC algorithm is unknown (see module docstring).
+
+    Raises:
+        OSError: if the file cannot be written.
+    """
+    path = Path(path)
+    header = _build_mlg_header(serial)
+
+    with open(path, "wb") as f:
+        f.write(header)
+        for entry in entries:
+            record = _build_mlg_record(entry, serial)
+            f.write(record)
+
+
+def read_mlg(path: Union[str, Path]) -> list[MonitorLogEntry]:
+    """
+    Parse a Blastware .MLG file into a list of MonitorLogEntry objects.
+
+    NOT YET IMPLEMENTED.
+
+    Args:
+        path: Path to the .MLG file.
+
+    Returns:
+        List of MonitorLogEntry objects.
+
+    Raises:
+        NotImplementedError: always (pending implementation).
+    """
+    raise NotImplementedError("read_mlg() is not yet implemented")

minimateplus/framing.py

@@ -0,0 +1,606 @@
+"""
+framing.py — DLE frame codec for the Instantel MiniMate Plus RS-232 protocol.
+
+Wire format:
+  BW→S3 (our requests):  [ACK=0x41] [STX=0x02] [stuffed payload+chk] [ETX=0x03]
+  S3→BW (device replies): [DLE=0x10] [STX=0x02] [stuffed payload+chk] [DLE=0x10] [ETX=0x03]
+
+  The ACK 0x41 byte often precedes S3 frames too — it is silently discarded
+  by the streaming parser.
+
+De-stuffed payload layout:
+  BW→S3 request frame:
+    [0] CMD      0x10 (BW request marker)
+    [1] flags    0x00
+    [2] SUB      command sub-byte
+    [3] 0x00     always zero in captured frames
+    [4] 0x00     always zero in captured frames
+    [5] OFFSET   two-step offset: 0x00 = length-probe, DATA_LEN = data-request
+    [6-15]       zero padding (total de-stuffed payload = 16 bytes)
+
+  S3→BW response frame:
+    [0] CMD      0x00 (S3 response marker)
+    [1] flags    0x10
+    [2] SUB      response sub-byte (= 0xFF - request SUB)
+    [3] PAGE_HI  high byte of page address (always 0x00 in observed frames)
+    [4] PAGE_LO  low byte                  (always 0x00 in observed frames)
+    [5+] data    payload data section (composite inner frames for large responses)
+
+DLE stuffing rule: any 0x10 byte in the payload is doubled on the wire (0x10 → 0x10 0x10).
+This applies to the checksum byte too.
+
+Confirmed from live captures (s3_parser.py validation + raw_bw.bin / raw_s3.bin).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+# ── Protocol byte constants ───────────────────────────────────────────────────
+
+DLE = 0x10   # Data Link Escape
+STX = 0x02   # Start of text
+ETX = 0x03   # End of text
+ACK = 0x41   # Acknowledgement / frame-start marker (BW side)
+
+BW_CMD  = 0x10   # CMD byte value in BW→S3 frames
+S3_CMD  = 0x00   # CMD byte value in S3→BW frames
+S3_FLAGS = 0x10  # flags byte value in S3→BW frames
+
+# BW read-command payload size: 5 header bytes + 11 padding bytes = 16 total.
+# Confirmed from captured raw_bw.bin: all read-command frames carry exactly 16
+# de-stuffed bytes (excluding the appended checksum).
+_BW_PAYLOAD_SIZE = 16
+
+
+# ── DLE stuffing / de-stuffing ────────────────────────────────────────────────
+
+def dle_stuff(data: bytes) -> bytes:
+    """Escape literal 0x10 bytes: 0x10 → 0x10 0x10."""
+    out = bytearray()
+    for b in data:
+        if b == DLE:
+            out.append(DLE)
+        out.append(b)
+    return bytes(out)
+
+
+def dle_unstuff(data: bytes) -> bytes:
+    """Remove DLE stuffing: 0x10 0x10 → 0x10."""
+    out = bytearray()
+    i = 0
+    while i < len(data):
+        b = data[i]
+        if b == DLE and i + 1 < len(data) and data[i + 1] == DLE:
+            out.append(DLE)
+            i += 2
+        else:
+            out.append(b)
+            i += 1
+    return bytes(out)
+
+
+# ── Checksum ─────────────────────────────────────────────────────────────────
+
+def checksum(payload: bytes) -> int:
+    """SUM8: sum of all de-stuffed payload bytes, mod 256."""
+    return sum(payload) & 0xFF
+
+
+# ── BW→S3 frame builder ───────────────────────────────────────────────────────
+
+# SUB byte for 5A — used by build_5a_frame below (protocol.py has the full
+# constant set; defined here to avoid a circular import).
+SUB_5A = 0x5A
+
+
+def build_5a_frame(offset_word: int, raw_params: bytes) -> bytes:
+    """
+    Build a BW→S3 frame for SUB 5A (BULK_WAVEFORM_STREAM) that exactly
+    matches Blastware's wire output.
+
+    SUB 5A uses a DIFFERENT frame format from all other read commands:
+      1. The offset field (bytes [4:6]) is written RAW — the 0x10 in
+         offset_hi=0x10 is NOT DLE-stuffed, unlike build_bw_frame().
+      2. The checksum uses a DLE-aware sum: for each 0x10 XX pair in the
+         stuffed section, only XX contributes; lone bytes contribute normally.
+         This differs from the standard SUM8 checksum on the unstuffed payload.
+
+    Both differences are confirmed from the 1-2-26 BW TX capture (all 10 frames
+    verified against this algorithm on 2026-04-02).
+
+    Args:
+        offset_word: 16-bit offset (0x1004 for probe/chunks, 0x005A for term).
+        raw_params:  10 or 11 params bytes (from bulk_waveform_params or
+                     bulk_waveform_term_params). 0x10 bytes in params are
+                     written RAW — NOT DLE-stuffed. Confirmed 2026-04-06 by
+                     comparing wire bytes: BW sends bare `10 04` for chunk 1
+                     (counter=0x1004), not stuffed `10 10 04`. Device reads
+                     params at fixed byte positions; stuffing shifts the bytes
+                     and corrupts the counter, causing device to ignore the frame.
+
+    Returns:
+        Complete frame bytes: [ACK][STX][stuffed_section][chk][ETX]
+    """
+    if len(raw_params) not in (10, 11):
+        raise ValueError(f"raw_params must be 10 or 11 bytes, got {len(raw_params)}")
+
+    # Build stuffed section between STX and checksum
+    s = bytearray()
+    s += b"\x10\x10"                            # DLE-stuffed BW_CMD
+    s += b"\x00"                                 # flags
+    s += bytes([SUB_5A])                         # sub = 0x5A
+    s += b"\x00"                                 # field3
+    s += bytes([(offset_word >> 8) & 0xFF,       # offset_hi — raw, NOT stuffed
+                 offset_word & 0xFF])            # offset_lo
+    for b in raw_params:                         # params — NOT DLE-stuffed (raw bytes, match BW wire format)
+        s.append(b)
+
+    # DLE-aware checksum: for 0x10 XX pairs count XX; for lone bytes count them
+    chk, i = 0, 0
+    while i < len(s):
+        if s[i] == DLE and i + 1 < len(s):
+            chk = (chk + s[i + 1]) & 0xFF
+            i += 2
+        else:
+            chk = (chk + s[i]) & 0xFF
+            i += 1
+
+    return bytes([ACK, STX]) + bytes(s) + bytes([chk, ETX])
+
+
+def build_bw_frame(sub: int, offset: int = 0, params: bytes = bytes(10)) -> bytes:
+    """
+    Build a BW→S3 read-command frame.
+
+    The payload is always 16 de-stuffed bytes:
+      [BW_CMD, 0x00, sub, 0x00, 0x00, offset] + params(10 bytes)
+
+    Confirmed from BW capture analysis: payload[3] and payload[4] are always
+    0x00 across all observed read commands.  The two-step offset lives at
+    payload[5]: 0x00 for the length-probe step, DATA_LEN for the data-fetch step.
+
+    The 10 params bytes (payload[6..15]) are zero for standard reads.  For
+    keyed reads (SUBs 0A, 0C) the 4-byte waveform key lives at params[4..7]
+    (= payload[10..13]).  For token-based reads (SUBs 1E, 1F) a single token
+    byte lives at params[6] (= payload[12]).  Use waveform_key_params() and
+    token_params() helpers to build these safely.
+
+    Wire output: [ACK] [STX] dle_stuff(payload + checksum) [ETX]
+
+    Args:
+        sub:    SUB command byte (e.g. 0x01 = FULL_CONFIG_READ)
+        offset: Value placed at payload[5].
+                Pass 0 for the probe step; pass DATA_LENGTHS[sub] for the data step.
+        params: 10 bytes placed at payload[6..15].  Default: all zeros.
+
+    Returns:
+        Complete frame bytes ready to write to the serial port / socket.
+    """
+    if len(params) != 10:
+        raise ValueError(f"params must be exactly 10 bytes, got {len(params)}")
+    if offset > 0xFFFF:
+        raise ValueError(f"offset must fit in uint16, got {offset:#06x}")
+    # offset is a uint16 split across bytes [4] (high) and [5] (low).
+    # For all standard reads (offset ≤ 0xFF), byte[4] = 0x00 — consistent with
+    # every captured BW frame.  For large payloads (e.g. SUB 1A / E5 at 0x082A),
+    # byte[4] carries the high byte.  🔶 INFERRED — confirm once E5 is captured.
+    offset_hi = (offset >> 8) & 0xFF
+    offset_lo = offset & 0xFF
+    payload = bytes([BW_CMD, 0x00, sub, 0x00, offset_hi, offset_lo]) + params
+    chk = checksum(payload)
+    wire = bytes([ACK, STX]) + dle_stuff(payload + bytes([chk])) + bytes([ETX])
+    return wire
+
+
+def build_bw_write_frame(
+    sub: int,
+    data: bytes,
+    *,
+    offset: int = 0,
+    params: bytes = bytes(10),
+) -> bytes:
+    """
+    Build a BW→S3 write-command frame.
+
+    Write frames extend the standard 16-byte read header with a variable-length
+    data payload.  They use a different checksum formula from read frames.
+
+    **CRITICAL: Write frames use minimal DLE stuffing.**
+
+    Unlike read frames (build_bw_frame), write frames do NOT apply full DLE
+    stuffing to the payload.  Only the BW_CMD byte (0x10) at position [0] is
+    doubled to 0x10 0x10 on the wire.  All other bytes — flags, sub, offset,
+    params, data, and checksum — are written RAW with no stuffing, even if they
+    contain 0x10 bytes (e.g. offset_hi=0x10 for compliance chunks, or 0x10
+    bytes in the write data payload).
+
+    Confirmed from 3-11-26 BW TX capture (frames 102–112): all 11 write frames
+    match the rule "double BW_CMD only; everything else raw."  ✅ 2026-04-07.
+
+    Wire layout:
+      [41]       ACK
+      [02]       STX
+      [10 10]    BW_CMD doubled (the ONLY DLE stuffing applied)
+      [00]       flags
+      [sub]      write command byte (0x68–0x83)
+      [00]       always zero
+      [hi][lo]   offset as uint16 BE (raw; NOT stuffed even if hi=0x10)
+      [params]   10 bytes (raw)
+      [data]     variable-length write payload (raw; NOT stuffed)
+      [chk]      checksum byte (raw; NOT stuffed even if 0x10)
+      [03]       ETX
+
+    De-stuffed payload (for checksum computation):
+      [0]     BW_CMD  0x10
+      [1]     flags   0x00
+      [2]     SUB     write command byte
+      [3]     0x00    always zero
+      [4]     offset_hi
+      [5]     offset_lo
+      [6:16]  params  10 bytes
+      [16:]   data    write payload
+      [-1]    chk
+
+    **Checksum formula (confirmed 2026-03-12 from 3-11-26 BW TX capture):**
+      chk = (sum(b for b in payload[2:] if b != 0x10) + 0x10) % 256
+    where payload = destuffed content BEFORE appending chk.
+    This skips all 0x10 bytes in payload[2:] (sub onwards), including any
+    0x10 bytes in the offset, params, data, and the checksum byte itself.
+
+    The offset field [4:6] meaning per write SUB:
+      - SUBs 68, 69, 82 (single-chunk writes): offset = data[1] + 2, where
+            data[1] is an embedded length field in the write payload.
+            Confirmed from capture: 68→0x5A (data[1]=0x58+2), 82→0x1C
+            (data[1]=0x1A+2), 69→0xCA (data[1]=0xC8+2).
+      - SUB 71 (multi-chunk compliance): 0x1004 for full chunks, 0x002C
+            for the final partial chunk.
+      - Confirm frames (72, 73, 74, 83): offset=0, no data.
+
+    Args:
+        sub:    Write command SUB byte.
+        data:   Write payload (variable length; empty for confirm frames).
+        offset: 16-bit value placed at [4:6].  See per-SUB notes above.
+        params: 10 bytes placed at [6:16].  All-zero for most writes; compliance
+                chunk writes use chunk-specific values.
+
+    Returns:
+        Complete frame bytes ready to write to the transport.
+    """
+    if len(params) != 10:
+        raise ValueError(f"params must be exactly 10 bytes, got {len(params)}")
+    if offset > 0xFFFF:
+        raise ValueError(f"offset must fit in uint16, got {offset:#06x}")
+
+    offset_hi = (offset >> 8) & 0xFF
+    offset_lo = offset & 0xFF
+
+    # Destuffed payload (used only for checksum; not sent directly)
+    payload_no_chk = bytes([BW_CMD, 0x00, sub, 0x00, offset_hi, offset_lo]) + params + data
+
+    # Large-frame checksum: sum payload[2:] skipping all 0x10 bytes, add 0x10.
+    # Applied to the destuffed representation — confirms correctly against
+    # all 11 write frames in the 3-11-26/170151 BW TX capture. ✅
+    chk = (sum(b for b in payload_no_chk[2:] if b != 0x10) + 0x10) & 0xFF
+
+    # Wire construction: only BW_CMD is doubled; everything else is raw.
+    # Do NOT use dle_stuff() here — that would incorrectly double 0x10 bytes
+    # in the offset, params, and data sections.
+    wire = (
+        bytes([ACK, STX])          # Frame prefix (not part of payload)
+        + bytes([BW_CMD, BW_CMD])  # BW_CMD doubled (only DLE stuffing applied)
+        + payload_no_chk[1:]       # flags, sub, offset, params, data — RAW
+        + bytes([chk])             # checksum — RAW
+        + bytes([ETX])             # Frame terminator
+    )
+    return wire
+
+
+def waveform_key_params(key4: bytes) -> bytes:
+    """
+    Build the 10-byte params block that carries a 4-byte waveform key.
+
+    Used for SUBs 0A (WAVEFORM_HEADER) and 0C (WAVEFORM_RECORD).
+    The key goes at params[4..7], which maps to payload[10..13].
+
+    Confirmed from 3-31-26 capture: 0A and 0C request frames carry the
+    4-byte record address at payload[10..13].  Probe and data-fetch steps
+    carry the same key in both frames.
+
+    Args:
+        key4: exactly 4 bytes — the opaque waveform record address returned
+              by the EVENT_HEADER (1E) or EVENT_ADVANCE (1F) response.
+
+    Returns:
+        10-byte params block with key embedded at positions [4..7].
+    """
+    if len(key4) != 4:
+        raise ValueError(f"waveform key must be 4 bytes, got {len(key4)}")
+    p = bytearray(10)
+    p[4:8] = key4
+    return bytes(p)
+
+
+def token_params(token: int = 0) -> bytes:
+    """
+    Build the 10-byte params block that carries a single token byte.
+
+    Used for SUBs 1E (EVENT_HEADER) and 1F (EVENT_ADVANCE).
+    The token goes at params[7], which maps to payload[13].
+
+    Confirmed from BOTH 3-31-26 and 4-3-26 BW TX captures:
+      raw params bytes: 00 00 00 00 00 00 00 fe 00 00
+      token is at index 7 (not 6 — that was wrong).
+
+      - token=0x00: first-event read / browse mode (no download marking)
+      - token=0xfe: download mode (causes 1F to skip partial bins and
+                    advance to the next full record)
+
+    The device echoes the token at data[8] of the S3 response (payload[13]),
+    distinct from the next-event key at data[11:15] (payload[16:20]).
+
+    Args:
+        token: single byte to place at params[7] / payload[13].
+
+    Returns:
+        10-byte params block with token at position [7].
+    """
+    p = bytearray(10)
+    p[7] = token
+    return bytes(p)
+
+
+def bulk_waveform_params(key4: bytes, counter: int, *, is_probe: bool = False) -> bytes:
+    """
+    Build the 10-byte params block for SUB 5A (BULK_WAVEFORM_STREAM) requests.
+
+    Confirmed 2026-04-02 from 1-2-26 BW TX capture analysis:
+
+    Probe / first request (is_probe=True, counter=0):
+      params[0]   = 0x00
+      params[1:5] = key4  (all 4 key bytes; counter overlaps key4[2:4] = 0x0000)
+      params[5:]  = zeros
+
+    Regular chunk requests (is_probe=False):
+      params[0]   = 0x00
+      params[1:3] = key4[0:2]           (first 2 key bytes as session handle)
+      params[3:5] = counter (BE uint16)  (chunk position, increments by 0x0400)
+      params[5:]  = zeros
+
+    Termination request:  DO NOT use this helper — see bulk_waveform_term_params().
+
+    Args:
+        key4:     4-byte waveform key from EVENT_HEADER (1E) response.
+        counter:  Chunk position counter (uint16 BE).  Pass 0 for probe.
+        is_probe: If True, embed full key4 (probe step only).
+
+    Returns:
+        11-byte params block.  (BW confirmed: chunk frames carry 11 params bytes,
+        not 10; the extra trailing 0x00 was confirmed from 1-2-26 wire capture
+        on 2026-04-02.)
+    """
+    if len(key4) != 4:
+        raise ValueError(f"waveform key must be 4 bytes, got {len(key4)}")
+    p = bytearray(11)   # 11 bytes confirmed from BW wire capture
+    p[0] = 0x00
+    p[1] = key4[0]
+    p[2] = key4[1]
+    if is_probe:
+        # Full key4; counter=0 is implied (overlaps with key4[2:4] which must be 0x0000)
+        p[3] = key4[2]
+        p[4] = key4[3]
+    else:
+        p[3] = (counter >> 8) & 0xFF
+        p[4] = counter & 0xFF
+    return bytes(p)
+
+
+def bulk_waveform_term_params(key4: bytes, counter: int) -> bytes:
+    """
+    Build the 10-byte params block for the SUB 5A termination request.
+
+    The termination request uses offset=0x005A and a DIFFERENT params layout —
+    the leading 0x00 byte is dropped, key4[0:2] shifts to params[0:2], and the
+    counter high byte is at params[2]:
+
+      params[0]   = key4[0]
+      params[1]   = key4[1]
+      params[2]   = (counter >> 8) & 0xFF
+      params[3:]  = zeros
+
+    Counter for the termination request = last_regular_counter + 0x0400.
+
+    Confirmed from 1-2-26 BW TX capture: final request (frame 83) uses
+    offset=0x005A, params[0:3] = key4[0:2] + term_counter_hi.
+
+    Args:
+        key4:    4-byte waveform key.
+        counter: Termination counter (= last regular counter + 0x0400).
+
+    Returns:
+        10-byte params block.
+    """
+    if len(key4) != 4:
+        raise ValueError(f"waveform key must be 4 bytes, got {len(key4)}")
+    p = bytearray(10)
+    p[0] = key4[0]
+    p[1] = key4[1]
+    p[2] = (counter >> 8) & 0xFF
+    return bytes(p)
+
+
+# ── Pre-built POLL frames ─────────────────────────────────────────────────────
+#
+# POLL (SUB 0x5B) uses the same two-step pattern as all other reads — the
+# hardcoded length 0x30 lives at payload[5], exactly as in build_bw_frame().
+
+POLL_PROBE = build_bw_frame(0x5B, 0x00)   # length-probe POLL  (offset = 0)
+POLL_DATA  = build_bw_frame(0x5B, 0x30)   # data-request POLL  (offset = 0x30)
+
+# Session-reset signal (ACK + ETX, no STX/payload).
+# Confirmed from 4-8-26 BW TX captures: Blastware sends this 2-byte sequence
+# immediately before the first POLL probe, and again between the POLL probe
+# and the POLL data request.  Required to wake a unit that is actively
+# monitoring — without it the unit does not respond to POLL over TCP.
+# Harmless for idle units (they respond to POLL regardless).
+SESSION_RESET = bytes([0x41, 0x03])
+
+
+# ── S3 response dataclass ─────────────────────────────────────────────────────
+
+@dataclass
+class S3Frame:
+    """A fully parsed and de-stuffed S3→BW response frame."""
+    sub: int            # response SUB byte (e.g. 0xA4 = POLL_RESPONSE)
+    page_hi: int        # PAGE_HI from header (= data length on step-2 length response)
+    page_lo: int        # PAGE_LO from header
+    data: bytes         # payload data section (payload[5:], checksum already stripped)
+    checksum_valid: bool
+    chk_byte: int = 0   # actual checksum byte received from wire (body[-1])
+                        # needed for waveform file reconstruction: when the last data byte
+                        # is 0x10 and chk_byte ∈ {0x02, 0x03, 0x04}, the DLE+chk pair
+                        # must be included in the DLE-strip operation to correctly
+                        # reconstruct the Blastware binary body.
+
+    @property
+    def page_key(self) -> int:
+        """Combined 16-bit page address / length: (page_hi << 8) | page_lo."""
+        return (self.page_hi << 8) | self.page_lo
+
+
+# ── Streaming S3 frame parser ─────────────────────────────────────────────────
+
+class S3FrameParser:
+    """
+    Incremental byte-stream parser for S3→BW response frames.
+
+    Feed incoming bytes with feed().  Complete, valid frames are returned
+    immediately and also accumulated in self.frames.
+
+    State machine:
+        IDLE             — scanning for DLE (0x10)
+        SEEN_DLE         — saw DLE, waiting for STX (0x02) to start a frame
+        IN_FRAME         — collecting de-stuffed payload bytes; bare ETX ends frame
+        IN_FRAME_DLE     — inside frame, saw DLE; DLE continues stuffing;
+                           DLE+ETX is treated as literal data (NOT a frame end),
+                           which lets inner-frame terminators pass through intact
+
+    Wire format confirmed from captures:
+        [DLE=0x10] [STX=0x02] [stuffed payload+chk] [bare ETX=0x03]
+    The ETX is NOT preceded by a DLE on the wire.  DLE+ETX sequences that
+    appear inside the payload are inner-frame terminators and must be
+    treated as literal data.
+
+    ACK (0x41) bytes and arbitrary non-DLE bytes in IDLE state are silently
+    discarded (covers device boot string "Operating System" and keepalive ACKs).
+    """
+
+    _IDLE         = 0
+    _SEEN_DLE     = 1
+    _IN_FRAME     = 2
+    _IN_FRAME_DLE = 3
+
+    def __init__(self) -> None:
+        self._state  = self._IDLE
+        self._body   = bytearray()   # accumulates de-stuffed frame bytes
+        self.frames: list[S3Frame] = []
+        self.bytes_fed: int = 0       # cumulative raw bytes fed since last reset
+
+    def reset(self) -> None:
+        self._state    = self._IDLE
+        self._body.clear()
+        self.bytes_fed = 0
+
+    def feed(self, data: bytes) -> list[S3Frame]:
+        """
+        Process a chunk of incoming bytes.
+
+        Returns a list of S3Frame objects completed during this call.
+        All completed frames are also appended to self.frames.
+        """
+        self.bytes_fed += len(data)
+        completed: list[S3Frame] = []
+        for b in data:
+            frame = self._step(b)
+            if frame is not None:
+                completed.append(frame)
+                self.frames.append(frame)
+        return completed
+
+    def _step(self, b: int) -> Optional[S3Frame]:
+        """Process one byte. Returns a completed S3Frame or None."""
+
+        if self._state == self._IDLE:
+            if b == DLE:
+                self._state = self._SEEN_DLE
+            # ACK, boot strings, garbage — silently ignored
+
+        elif self._state == self._SEEN_DLE:
+            if b == STX:
+                self._body.clear()
+                self._state = self._IN_FRAME
+            else:
+                # Stray DLE not followed by STX — back to idle
+                self._state = self._IDLE
+
+        elif self._state == self._IN_FRAME:
+            if b == DLE:
+                self._state = self._IN_FRAME_DLE
+            elif b == ETX:
+                # Bare ETX = real frame terminator (confirmed from captures)
+                frame = self._finalise()
+                self._state = self._IDLE
+                return frame
+            else:
+                self._body.append(b)
+
+        elif self._state == self._IN_FRAME_DLE:
+            if b == DLE:
+                # DLE DLE → literal 0x10 in payload
+                self._body.append(DLE)
+                self._state = self._IN_FRAME
+            elif b == ETX:
+                # DLE+ETX inside a frame is an inner-frame terminator, NOT
+                # the outer frame end.  Treat as literal data and continue.
+                self._body.append(DLE)
+                self._body.append(ETX)
+                self._state = self._IN_FRAME
+            else:
+                # Unexpected DLE + byte — treat both as literal data and continue
+                self._body.append(DLE)
+                self._body.append(b)
+                self._state = self._IN_FRAME
+
+        return None
+
+    def _finalise(self) -> Optional[S3Frame]:
+        """
+        Called when DLE+ETX is seen.  Validates checksum and builds S3Frame.
+        Returns None if the frame is too short or structurally invalid.
+        """
+        body = bytes(self._body)
+
+        # Minimum valid frame: 5-byte header + at least 1 checksum byte = 6
+        if len(body) < 6:
+            return None
+
+        raw_payload = body[:-1]   # everything except the trailing checksum byte
+        chk_received = body[-1]
+        chk_computed  = checksum(raw_payload)
+
+        if len(raw_payload) < 5:
+            return None
+
+        # Validate CMD byte — we only accept S3→BW response frames here
+        if raw_payload[0] != S3_CMD:
+            return None
+
+        return S3Frame(
+            sub            = raw_payload[2],
+            page_hi        = raw_payload[3],
+            page_lo        = raw_payload[4],
+            data           = raw_payload[5:],
+            checksum_valid = (chk_received == chk_computed),
+            chk_byte       = chk_received,
+        )

minimateplus/models.py

@@ -0,0 +1,593 @@
+"""
+models.py — Plain-Python data models for the MiniMate Plus protocol library.
+
+All models are intentionally simple dataclasses with no protocol logic.
+They represent *decoded* device data — the client layer translates raw frame
+bytes into these objects, and the SFM API layer serialises them to JSON.
+
+Notes on certainty:
+  Fields marked ✅ are confirmed from captured data.
+  Fields marked 🔶 are strongly inferred but not formally proven.
+  Fields marked ❓ are present in the captured payload but not yet decoded.
+  See docs/instantel_protocol_reference.md for full derivation details.
+"""
+
+from __future__ import annotations
+
+import datetime
+import struct
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ── Timestamp ─────────────────────────────────────────────────────────────────
+
+@dataclass
+class Timestamp:
+    """
+    Event timestamp decoded from the MiniMate Plus wire format.
+
+    Two source formats exist:
+
+    1. 6-byte format (from event index / 1E header — not yet decoded in client):
+         [flag:1] [year:2 BE] [unknown:1] [month:1] [day:1]
+       Use Timestamp.from_bytes().
+
+    2. 9-byte format (from Full Waveform Record / 0C, bytes 0–8) ✅ CONFIRMED:
+         [day:1] [sub_code:1] [month:1] [year:2 BE] [unknown:1] [hour:1] [min:1] [sec:1]
+       Use Timestamp.from_waveform_record().
+
+       Confirmed 2026-04-01 against Blastware event report (BE11529 thump event):
+         raw bytes: 01 10 04 07 ea 00 00 1c 0c
+         → day=1, sub_code=0x10 (Waveform mode), month=4, year=2026,
+           hour=0, minute=28, second=12  ← matches Blastware "00:28:12 April 1, 2026"
+
+       The sub_code at byte[1] is the record-mode indicator:
+         0x10 → Waveform (continuous / single-shot) ✅
+         other → Histogram (code not yet captured ❓)
+
+    The year 1995 is the device's factory-default RTC date — it appears
+    whenever the battery has been disconnected.  Treat 1995 as "clock not set".
+    """
+    raw: bytes                          # raw bytes for round-tripping
+    flag: int                           # byte 0 of 6-byte format, or sub_code from 9-byte format
+    year: int                           # ✅
+    unknown_byte: int                   # separator byte (purpose unclear ❓)
+    month: int                          # ✅
+    day: int                            # ✅
+
+    # Time fields — populated only from the 9-byte waveform-record format
+    hour: Optional[int] = None          # ✅ (waveform record format)
+    minute: Optional[int] = None        # ✅ (waveform record format)
+    second: Optional[int] = None        # ✅ (waveform record format)
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "Timestamp":
+        """
+        Decode a 6-byte timestamp (6-byte event-index format).
+
+        Args:
+            data: exactly 6 bytes from the device payload.
+
+        Returns:
+            Decoded Timestamp (no time fields).
+
+        Raises:
+            ValueError: if data is not exactly 6 bytes.
+        """
+        if len(data) != 6:
+            raise ValueError(f"Timestamp requires exactly 6 bytes, got {len(data)}")
+        flag = data[0]
+        year = struct.unpack_from(">H", data, 1)[0]
+        unknown_byte = data[3]
+        month = data[4]
+        day = data[5]
+        return cls(
+            raw=bytes(data),
+            flag=flag,
+            year=year,
+            unknown_byte=unknown_byte,
+            month=month,
+            day=day,
+        )
+
+    @classmethod
+    def from_waveform_record(cls, data: bytes) -> "Timestamp":
+        """
+        Decode a 9-byte timestamp from the first bytes of a 210-byte waveform
+        record (SUB 0C / Full Waveform Record response).
+
+        Wire layout (✅ CONFIRMED 2026-04-01 against Blastware event report):
+          byte[0]: day                   (uint8)
+          byte[1]: sub_code / mode flag  (0x10 = Waveform single-shot)
+          byte[2]: month                 (uint8)
+          bytes[3–4]: year               (big-endian uint16)
+          byte[5]: unknown               (0x00 in all observed samples)
+          byte[6]: hour                  (uint8)
+          byte[7]: minute                (uint8)
+          byte[8]: second                (uint8)
+
+        Used for sub_code=0x10 records only.  For sub_code=0x03 (continuous
+        mode) use from_continuous_record() — the layout is shifted by 1 byte.
+
+        Args:
+            data: at least 9 bytes; only the first 9 are consumed.
+
+        Returns:
+            Decoded Timestamp with hour/minute/second populated.
+
+        Raises:
+            ValueError: if data is fewer than 9 bytes.
+        """
+        if len(data) < 9:
+            raise ValueError(
+                f"Waveform record timestamp requires at least 9 bytes, got {len(data)}"
+            )
+        day          = data[0]
+        sub_code     = data[1]   # 0x10 = Waveform single-shot
+        month        = data[2]
+        year         = struct.unpack_from(">H", data, 3)[0]
+        unknown_byte = data[5]
+        hour         = data[6]
+        minute       = data[7]
+        second       = data[8]
+        return cls(
+            raw=bytes(data[:9]),
+            flag=sub_code,
+            year=year,
+            unknown_byte=unknown_byte,
+            month=month,
+            day=day,
+            hour=hour,
+            minute=minute,
+            second=second,
+        )
+
+    @classmethod
+    def from_continuous_record(cls, data: bytes) -> "Timestamp":
+        """
+        Decode a 10-byte timestamp from the first bytes of a sub_code=0x03
+        (Waveform Continuous) 210-byte record.
+
+        Wire layout (✅ CONFIRMED 2026-04-03 against Blastware event report,
+        event recorded at 15:20:17 April 3 2026, raw: 10 03 10 04 07 ea 00 0f 14 11):
+          byte[0]: unknown_a   (0x10 observed — meaning TBD)
+          byte[1]: day         (uint8)
+          byte[2]: unknown_b   (0x10 observed — meaning TBD)
+          bytes[3]: month      (uint8)
+          bytes[4–5]: year     (big-endian uint16)
+          byte[6]: unknown     (0x00 in all observed samples)
+          byte[7]: hour        (uint8)
+          byte[8]: minute      (uint8)
+          byte[9]: second      (uint8)
+
+        This is the sub_code=0x10 layout shifted forward by 1 byte, with two
+        extra unknown bytes at [0] and [2].  The sub_code (0x03) itself is at
+        byte[1] in the raw record, which also encodes the day — but the day
+        value (3 = April 3rd) happens to differ from the sub_code (0x03) only
+        in semantics; the byte is shared.
+
+        Args:
+            data: at least 10 bytes; only the first 10 are consumed.
+
+        Returns:
+            Decoded Timestamp with hour/minute/second populated.
+
+        Raises:
+            ValueError: if data is fewer than 10 bytes.
+        """
+        if len(data) < 10:
+            raise ValueError(
+                f"Continuous record timestamp requires at least 10 bytes, got {len(data)}"
+            )
+        unknown_a    = data[0]   # 0x10 observed; meaning unknown
+        day          = data[1]   # doubles as the sub_code byte (0x03) — day=3 on Apr 3
+        unknown_b    = data[2]   # 0x10 observed; meaning unknown
+        month        = data[3]
+        year         = struct.unpack_from(">H", data, 4)[0]
+        unknown_byte = data[6]
+        hour         = data[7]
+        minute       = data[8]
+        second       = data[9]
+        return cls(
+            raw=bytes(data[:10]),
+            flag=unknown_a,
+            year=year,
+            unknown_byte=unknown_byte,
+            month=month,
+            day=day,
+            hour=hour,
+            minute=minute,
+            second=second,
+        )
+
+    @property
+    def clock_set(self) -> bool:
+        """False when year == 1995 (factory default / battery-lost state)."""
+        return self.year != 1995
+
+    def __str__(self) -> str:
+        if not self.clock_set:
+            return f"CLOCK_NOT_SET ({self.year}-{self.month:02d}-{self.day:02d})"
+        date_str = f"{self.year}-{self.month:02d}-{self.day:02d}"
+        if self.hour is not None:
+            return f"{date_str} {self.hour:02d}:{self.minute:02d}:{self.second:02d}"
+        return date_str
+
+
+# ── Device identity ───────────────────────────────────────────────────────────
+
+@dataclass
+class DeviceInfo:
+    """
+    Combined device identity information gathered during the startup sequence.
+
+    Populated from three response SUBs:
+    - SUB EA (SERIAL_NUMBER_RESPONSE):  serial, firmware_minor
+    - SUB FE (FULL_CONFIG_RESPONSE):    serial (repeat), firmware_version,
+                                         dsp_version, manufacturer, model
+    - SUB A4 (POLL_RESPONSE):           manufacturer (repeat), model (repeat)
+
+    All string fields are stripped of null padding before storage.
+    """
+
+    # ── From SUB EA (SERIAL_NUMBER_RESPONSE) ─────────────────────────────────
+    serial: str                     # e.g. "BE18189" ✅
+    firmware_minor: int             # 0x11 = 17 for S337.17 ✅
+    serial_trail_0: Optional[int] = None   # unit-specific byte — purpose unknown ❓
+
+    # ── From SUB FE (FULL_CONFIG_RESPONSE) ────────────────────────────────────
+    firmware_version: Optional[str] = None  # e.g. "S337.17" ✅
+    dsp_version: Optional[str] = None       # e.g. "10.72" ✅
+    manufacturer: Optional[str] = None      # e.g. "Instantel" ✅
+    model: Optional[str] = None             # e.g. "MiniMate Plus" ✅
+
+    # ── From SUB 1A (COMPLIANCE_CONFIG_RESPONSE) ──────────────────────────────
+    compliance_config: Optional["ComplianceConfig"] = None  # E5 response, read in connect()
+
+    # ── From SUB 08 (EVENT_INDEX_RESPONSE) ────────────────────────────────────
+    event_count: Optional[int] = None  # stored event count from F7 response 🔶
+
+    def __str__(self) -> str:
+        fw = self.firmware_version or f"?.{self.firmware_minor}"
+        mdl = self.model or "MiniMate Plus"
+        return f"{mdl} S/N:{self.serial} FW:{fw}"
+
+
+# ── Channel threshold / scaling ───────────────────────────────────────────────
+
+@dataclass
+class ChannelConfig:
+    """
+    Per-channel threshold and scaling values from SUB E5 / SUB 71.
+
+    Floats are stored in the device in imperial units (in/s for geo channels,
+    psi for MicL).  Unit strings embedded in the payload confirm this.
+
+    Certainty: ✅ CONFIRMED for trigger_level, alarm_level, unit strings.
+    """
+    label: str                  # e.g. "Tran", "Vert", "Long", "MicL" ✅
+    trigger_level: float        # in/s (geo) or psi (MicL) ✅
+    alarm_level: float          # in/s (geo) or psi (MicL) ✅
+    max_range: float            # hardware/firmware sensitivity constant (e.g. 6.206053) ✅ confirmed same on all units
+    unit_label: str             # e.g. "in./s" or "psi" ✅
+
+
+# ── Peak values for one event ─────────────────────────────────────────────────
+
+@dataclass
+class PeakValues:
+    """
+    Per-channel peak particle velocity / pressure for a single event, plus the
+    scalar Peak Vector Sum.
+
+    Extracted from the Full Waveform Record (SUB F3 / 0C response), stored as
+    IEEE 754 big-endian floats in the device's native units (in/s / psi).
+
+    Per-channel PPV location (✅ CONFIRMED 2026-04-01):
+      Found by searching for the 4-byte channel label string ("Tran", "Vert",
+      "Long", "MicL") and reading the float at label_offset + 6.
+
+    Peak Vector Sum (✅ CONFIRMED 2026-04-01):
+      Fixed offset 87 in the 210-byte record.
+      = √(Tran² + Vert² + Long²) at the sample instant of maximum combined
+        geo motion.  NOT the vector sum of the three per-channel peak values
+        (those may occur at different times).
+      Matches Blastware's "Peak Vector Sum" display exactly.
+    """
+    tran: Optional[float] = None             # Transverse PPV (in/s) ✅
+    vert: Optional[float] = None             # Vertical PPV (in/s) ✅
+    long: Optional[float] = None             # Longitudinal PPV (in/s) ✅
+    micl: Optional[float] = None             # Air overpressure (psi) 🔶 (units uncertain)
+    peak_vector_sum: Optional[float] = None  # Scalar geo PVS (in/s) ✅
+
+
+# ── Project / operator metadata ───────────────────────────────────────────────
+
+@dataclass
+class ProjectInfo:
+    """
+    Operator-supplied project and location strings from the Full Waveform
+    Record (SUB F3) and compliance config block (SUB E5 / SUB 71).
+
+    All fields are optional — they may be blank if the operator did not fill
+    them in through Blastware.
+    """
+    setup_name: Optional[str] = None       # "Standard Recording Setup"
+    project: Optional[str] = None          # project description
+    client: Optional[str] = None           # client name ✅ confirmed offset
+    operator: Optional[str] = None         # operator / user name
+    sensor_location: Optional[str] = None  # sensor location string
+    notes: Optional[str] = None            # extended notes
+
+
+# ── Compliance Config ──────────────────────────────────────────────────────────
+
+@dataclass
+class ComplianceConfig:
+    """
+    Device compliance and recording configuration from SUB 1A (response E5).
+
+    Contains device-wide settings like record time, trigger/alarm thresholds,
+    and operator-supplied strings. This is read once during connect() and
+    cached in DeviceInfo.
+
+    All fields are optional — some may not be decoded yet or may be absent
+    from the device configuration.
+    """
+    raw: Optional[bytes] = None            # full 2090-byte payload (for debugging)
+
+    # Recording parameters (✅ CONFIRMED from §7.6)
+    recording_mode: Optional[int] = None  # uint8: 0x00=Single Shot, 0x01=Continuous,
+                                           # 0x03=Histogram, 0x04=Histogram+Continuous ✅ confirmed 2026-04-20
+                                           # Read (E5): data[anchor_pos - 8] (6-byte anchor)
+                                           # Write (SUB 71): data[anchor_pos - 7]
+    sample_rate: Optional[int] = None     # sps (1024, 2048, 4096)
+    histogram_interval_sec: Optional[int] = None  # uint16 BE, seconds ✅ confirmed 2026-04-20
+                                                   # anchor_pos - 4 (same offset in read & write)
+                                                   # Valid values: 2, 5, 15, 60, 300, 900
+                                                   # Mode-gated: only active in Histogram/Histogram+Continuous
+    record_time: Optional[float] = None   # seconds (e.g. 3.0, 5.0, 8.0, 10.0)
+
+    # Trigger/alarm levels (✅ CONFIRMED per-channel at §7.6)
+    # For now we store the first geo channel (Transverse) as representatives;
+    # full per-channel data would require structured Channel objects.
+    trigger_level_geo: Optional[float] = None    # in/s (first geo channel) ✅
+    alarm_level_geo: Optional[float] = None      # in/s (first geo channel) ✅
+    geo_adc_scale: Optional[float] = None        # ADC-to-velocity scale factor (float32 at Tran+28) ✅
+                                                 # = inverse sensitivity = 1/sensitivity (in/s per V)
+                                                 # Formula (Interface Handbook §4.5): Range = 1.61133 V × scale_factor
+                                                 #   → 1.61133 × 6.206053 = 10.000 in/s (Normal range) ✅
+                                                 # Firmware uses: PPV (in/s) = ADC_voltage (V) × 6.206053
+                                                 # Identical on BE11529 and BE18189 — same Instantel geophone hardware.
+                                                 # NOT a user-configurable setting. Must NOT be written.
+    geo_range: Optional[int] = None             # range/sensitivity selector — CONFIRMED 2026-04-20
+                                                 # 0x00 = Normal    10.000 in/s  (standard gain)
+                                                 # 0x01 = Sensitive  1.250 in/s  (high gain)
+                                                 # Offset: Tran+33 in both E5 read and SUB 71 write payloads
+                                                 # (same 2126-byte buffer is round-tripped; applied to Tran/Vert/Long)
+
+    # Project/setup strings (sourced from E5 / SUB 71 write payload)
+    # These are the FULL project metadata from compliance config,
+    # complementing the sparse ProjectInfo found in the waveform record (SUB 0C).
+    setup_name: Optional[str] = None       # "Standard Recording Setup"
+    project: Optional[str] = None          # project description
+    client: Optional[str] = None           # client name
+    operator: Optional[str] = None         # operator / user name
+    sensor_location: Optional[str] = None  # sensor location string
+    notes: Optional[str] = None            # extended notes / additional info
+
+
+# ── Call Home Config ──────────────────────────────────────────────────────────
+
+@dataclass
+class CallHomeConfig:
+    """
+    Auto Call Home (ACH) configuration from SUB 0x2C (response 0xD3).
+
+    Read with a standard two-step protocol (probe offset=0x00, data offset=0x7C).
+    Written via SUB 0x7E (write, 127-byte payload) + SUB 0x7F (confirm).
+
+    Confirmed from 4-20-26 call home settings captures (11 BW + S3 capture pairs).
+
+    Raw payload layout (data[11:] from S3 response, 125 bytes):
+      [0]     0x00           header byte
+      [1]     0x7C = 124     inner length (= offset for SUB 0x7E write - 2)
+      [2]     0xDC           constant
+      [3:5]   0x00 0x00      padding
+      [5]     auto_call_home_enabled  (0x00=off, 0x01=on) ✅
+      [6:46]  dial_string             40-byte null-padded ASCII ✅
+      [46:87] auto_answer_raw         AT command strings (not decoded) ✅ present
+      [87]    after_event_recorded    (0x01=on, 0x00=off) ✅
+      [91]    at_specified_times      (0x01=on, 0x00=off) ✅
+      [93]    time1_enabled           (0x01=on, 0x00=off) ✅
+      [95]    time2_enabled           (0x01=on, 0x00=off) ✅
+      [101]   time1_hour              uint8 decimal 0-23 ✅
+      [102]   time1_min               uint8 decimal 0-59 ✅
+      [105]   time2_hour              uint8 decimal 0-23 ✅
+      [106]   time2_min               uint8 decimal 0-59 ✅
+      [117]   DLE prefix (0x10)       ┐ DLE-escaped num_retries=3 (0x03)
+      [118]   0x03                    ┘ device stores/returns 0x03 DLE-escaped ✅
+      [120]   time_between_retries_sec uint8 (= 0x0F = 15 s default) ✅
+      [122]   wait_for_connection_sec  uint8 (= 0x3C = 60 s default) ✅
+      [124]   warm_up_time_sec         uint8 (= 0x3C = 60 s default) ✅
+
+    Write payload = raw 125 bytes + b'\\x00\\x00' (2 trailing zeros) = 127 bytes.
+    Offset for SUB 0x7E: data[1] + 2 = 0x7C + 2 = 0x7E = 126.
+
+    Note on DLE-escaped 0x03:  The device's S3 response DLE-escapes ETX (0x03)
+    bytes as \\x10\\x03.  The S3FrameParser preserves both bytes in frame.data.
+    Subsequent fields after offset 117 are therefore at raw_offset = logical+1.
+    The raw payload must be round-tripped verbatim in write; do NOT reapply DLE
+    destuffing or stripping.
+    """
+    raw: Optional[bytes] = None          # raw 125-byte read payload (for round-trip write)
+
+    # ── Main enable ──────────────────────────────────────────────────────────
+    auto_call_home_enabled: Optional[bool] = None    # raw[5] ✅
+
+    # ── Dial string ──────────────────────────────────────────────────────────
+    dial_string: Optional[str] = None                # raw[6:46] 40-byte null-padded ASCII ✅
+
+    # ── When to call ─────────────────────────────────────────────────────────
+    after_event_recorded: Optional[bool] = None      # raw[87] ✅
+    at_specified_times: Optional[bool] = None        # raw[91] ✅
+
+    # ── Time slot 1 ──────────────────────────────────────────────────────────
+    time1_enabled: Optional[bool] = None             # raw[93] ✅
+    time1_hour: Optional[int] = None                 # raw[101]  0-23 ✅
+    time1_min: Optional[int] = None                  # raw[102]  0-59 ✅
+
+    # ── Time slot 2 ──────────────────────────────────────────────────────────
+    time2_enabled: Optional[bool] = None             # raw[95] ✅
+    time2_hour: Optional[int] = None                 # raw[105]  0-23 ✅
+    time2_min: Optional[int] = None                  # raw[106]  0-59 ✅
+
+    # ── Retry / timeout settings (read-only; not writable via set_call_home_config) ──
+    num_retries: Optional[int] = None                # raw[117:119]=10 03 → value 3 ✅
+    time_between_retries_sec: Optional[int] = None   # raw[120] (shifted +1 by DLE) ✅
+    wait_for_connection_sec: Optional[int] = None    # raw[122] ✅
+    warm_up_time_sec: Optional[int] = None           # raw[124] ✅
+
+
+# ── Event ─────────────────────────────────────────────────────────────────────
+
+@dataclass
+class Event:
+    """
+    A single seismic event record downloaded from the device.
+
+    Populated progressively across several request/response pairs:
+    1. SUB 1E (EVENT_HEADER) → index, timestamp, sample_rate
+    2. SUB 0C (FULL_WAVEFORM_RECORD) → peak_values, project_info, record_type
+    3. SUB 5A (BULK_WAVEFORM_STREAM) → raw_samples  (downloaded on demand)
+
+    Fields not yet retrieved are None.
+    """
+    # ── Identity ──────────────────────────────────────────────────────────────
+    index: int                              # 0-based event number on device
+
+    # ── From EVENT_HEADER (SUB 1E) ────────────────────────────────────────────
+    timestamp: Optional[Timestamp] = None   # 6-byte timestamp ✅
+    sample_rate: Optional[int] = None       # samples/sec (e.g. 1024) 🔶
+
+    # ── From FULL_WAVEFORM_RECORD (SUB F3) ───────────────────────────────────
+    peak_values: Optional[PeakValues] = None
+    project_info: Optional[ProjectInfo] = None
+    record_type: Optional[str] = None       # e.g. "Histogram", "Waveform" 🔶
+
+    # ── From BULK_WAVEFORM_STREAM (SUB 5A) ───────────────────────────────────
+    # Raw ADC samples keyed by channel label.  Not fetched unless explicitly
+    # requested (large data transfer — up to several MB per event).
+    raw_samples: Optional[dict] = None      # {"Tran": [...], "Vert": [...], ...}
+    total_samples: Optional[int] = None     # from STRT record: expected total sample-sets
+    pretrig_samples: Optional[int] = None   # from STRT record: pre-trigger sample count
+    rectime_seconds: Optional[int] = None   # from STRT record: record duration (seconds)
+
+    # ── Debug / introspection ─────────────────────────────────────────────────
+    # Raw 210-byte waveform record bytes, set when debug mode is active.
+    # Exposed by the SFM server via ?debug=true so field layouts can be verified.
+    _raw_record: Optional[bytes] = field(default=None, repr=False)
+
+    # 4-byte waveform key used to request this event via SUB 5A.
+    # Set by get_events(); required by download_waveform().
+    _waveform_key: Optional[bytes] = field(default=None, repr=False)
+
+    # Raw A5 frames from the full bulk waveform download (full_waveform=True).
+    # Populated by get_events() when full_waveform=True; used by write_blastware_file().
+    _a5_frames: Optional[list] = field(default=None, repr=False)
+
+    def __str__(self) -> str:
+        ts = str(self.timestamp) if self.timestamp else "no timestamp"
+        ppv = ""
+        if self.peak_values:
+            pv = self.peak_values
+            parts = []
+            if pv.tran is not None:
+                parts.append(f"T={pv.tran:.4f}")
+            if pv.vert is not None:
+                parts.append(f"V={pv.vert:.4f}")
+            if pv.long is not None:
+                parts.append(f"L={pv.long:.4f}")
+            if pv.micl is not None:
+                parts.append(f"M={pv.micl:.6f}")
+            ppv = " [" + ", ".join(parts) + " in/s]"
+        return f"Event#{self.index} {ts}{ppv}"
+
+
+# ── MonitorLogEntry ───────────────────────────────────────────────────────────
+
+@dataclass
+class MonitorLogEntry:
+    """
+    A monitor log entry decoded from a SUB 0x0A (WAVEFORM_HEADER) response
+    whose first byte is 0x2C (partial record, recording mode = continuous
+    monitoring without a triggered event).
+
+    These are the "partial bins" that Blastware stores between triggered events.
+    Each entry represents one monitoring interval — the span of time during
+    which the unit was actively monitoring but no threshold crossing occurred.
+
+    Confirmed from 4-11-26 MITM capture analysis (2026-04-11):
+
+    Header layout (full response data[0:]):
+      data[0]    = 0x2C  (partial record type / data length in probe response)
+      data[1:5]  = 0x00 × 4
+      data[5:9]  = event key (4 bytes, big-endian hex)
+      data[9:11] = 0x00 × 2
+      data[11:]  = timestamp_start (9 or 10 bytes depending on recording mode)
+                   + timestamp_stop (same format)
+                   + separator (4–5 bytes, variable)
+                   + serial null-terminated (e.g. "BE11529\\0")
+                   + "Geo: X.XXX in/s\\0"  (trigger threshold string)
+
+    Timestamp format detection:
+      data[11] == 0x10  →  10-byte sub_code=0x03 (continuous) format
+      data[12] == 0x10  →  9-byte sub_code=0x10 (single-shot) format
+
+    In contrast to Event (triggered records, type 0x46), MonitorLogEntry
+    records do NOT have a waveform record (SUB 0x0C) or bulk waveform stream
+    (SUB 5A).  All available metadata is in the 0x0A header alone.
+    """
+    index: int                                      # 0-based position in device record list
+    key: str                                        # 8-hex event key (e.g. "01114290") ✅
+
+    start_time: Optional[datetime.datetime] = None  # monitoring session start ✅
+    stop_time: Optional[datetime.datetime] = None   # monitoring session stop ✅
+    serial: Optional[str] = None                    # device serial (e.g. "BE11529") ✅
+    geo_threshold_ips: Optional[float] = None       # trigger level from "Geo: X.XXX in/s" ✅
+
+    # Raw bytes for debugging / future decoding
+    raw_header: Optional[bytes] = field(default=None, repr=False)
+
+    @property
+    def duration_seconds(self) -> Optional[float]:
+        """Duration of monitoring interval in seconds, or None if times unavailable."""
+        if self.start_time and self.stop_time:
+            return (self.stop_time - self.start_time).total_seconds()
+        return None
+
+    def __str__(self) -> str:
+        start = self.start_time.isoformat() if self.start_time else "?"
+        stop  = self.stop_time.isoformat()  if self.stop_time  else "?"
+        dur   = f" ({self.duration_seconds:.0f}s)" if self.duration_seconds is not None else ""
+        return f"MonitorLog#{self.index} key={self.key} {start}→{stop}{dur}"
+
+
+# ── MonitorStatus ─────────────────────────────────────────────────────────────
+
+@dataclass
+class MonitorStatus:
+    """
+    Current monitoring state decoded from SUB 0x1C response.
+
+    Confirmed field locations from 4-8-26/2ndtry BW capture:
+      battery_v   : data[11 + 0x2F : 11 + 0x31]  uint16 BE ÷ 100   e.g. 680 → 6.80 V
+      memory_total: data[11 + 0x31 : 11 + 0x35]  uint32 BE bytes    e.g. 983040 → 960 KB
+      memory_free : data[11 + 0x35 : 11 + 0x39]  uint32 BE bytes    (subset of total)
+      is_monitoring: inferred from payload length — idle = 44 bytes, monitoring = 12 bytes
+    """
+    is_monitoring: bool             # True if unit is actively recording ✅
+    battery_v:     Optional[float] = None   # Battery voltage in volts ✅
+    memory_total:  Optional[int]   = None   # Total flash memory in bytes ✅
+    memory_free:   Optional[int]   = None   # Free flash memory in bytes ✅

minimateplus/transport.py

@@ -0,0 +1,456 @@
+"""
+transport.py — Serial and TCP transport layer for the MiniMate Plus protocol.
+
+Provides a thin I/O abstraction so that protocol.py never imports pyserial or
+socket directly.  Two concrete implementations:
+
+  SerialTransport — direct RS-232 cable connection (pyserial)
+  TcpTransport    — TCP socket to a modem or ACH relay (stdlib socket)
+
+The MiniMate Plus protocol bytes are identical over both transports.  TCP is used
+when field units call home via the ACH (Auto Call Home) server, or when SFM
+"calls up" a unit by connecting to the modem's IP address directly.
+
+Field hardware: Sierra Wireless RV55 / RX55 (4G LTE) cellular modem, replacing
+the older 3G-only Raven X (now decommissioned).  All run ALEOS firmware with an
+ACEmanager web UI.  Serial port must be configured 38400,8N1, no flow control,
+Data Forwarding Timeout = 1 s.
+
+Typical usage:
+    from minimateplus.transport import SerialTransport, TcpTransport
+
+    # Direct serial connection
+    with SerialTransport("COM5") as t:
+        t.write(frame_bytes)
+
+    # Modem / ACH TCP connection (Blastware port 12345)
+    with TcpTransport("192.168.1.50", 12345) as t:
+        t.write(frame_bytes)
+"""
+
+from __future__ import annotations
+
+import socket
+import time
+from abc import ABC, abstractmethod
+from typing import Optional
+
+# pyserial is the only non-stdlib dependency in this project.
+# Import lazily so unit-tests that mock the transport can run without it.
+try:
+    import serial  # type: ignore
+except ImportError:  # pragma: no cover
+    serial = None  # type: ignore
+
+
+# ── Abstract base ─────────────────────────────────────────────────────────────
+
+class BaseTransport(ABC):
+    """Common interface for all transport implementations."""
+
+    @abstractmethod
+    def connect(self) -> None:
+        """Open the underlying connection."""
+
+    @abstractmethod
+    def disconnect(self) -> None:
+        """Close the underlying connection."""
+
+    @property
+    @abstractmethod
+    def is_connected(self) -> bool:
+        """True while the connection is open."""
+
+    @abstractmethod
+    def write(self, data: bytes) -> None:
+        """Write *data* bytes to the wire."""
+
+    @abstractmethod
+    def read(self, n: int) -> bytes:
+        """
+        Read up to *n* bytes.  Returns immediately with whatever is available
+        (may return fewer than *n* bytes, or b"" if nothing is ready).
+        """
+
+    # ── Context manager ───────────────────────────────────────────────────────
+
+    def __enter__(self) -> "BaseTransport":
+        self.connect()
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.disconnect()
+
+    # ── Higher-level read helpers ─────────────────────────────────────────────
+
+    def read_until_idle(
+        self,
+        timeout: float = 2.0,
+        idle_gap: float = 0.05,
+        chunk: int = 256,
+    ) -> bytes:
+        """
+        Read bytes until the line goes quiet.
+
+        Keeps reading in *chunk*-sized bursts.  Returns when either:
+        - *timeout* seconds have elapsed since the first byte arrived, or
+        - *idle_gap* seconds pass with no new bytes (line went quiet).
+
+        This mirrors how Blastware behaves: it waits for the seismograph to
+        stop transmitting rather than counting bytes.
+
+        Args:
+            timeout:  Hard deadline (seconds) from the moment read starts.
+            idle_gap: How long to wait after the last byte before declaring done.
+            chunk:    How many bytes to request per low-level read() call.
+
+        Returns:
+            All bytes received as a single bytes object (may be b"" if nothing
+            arrived within *timeout*).
+        """
+        buf = bytearray()
+        deadline = time.monotonic() + timeout
+        last_rx = None
+
+        while time.monotonic() < deadline:
+            got = self.read(chunk)
+            if got:
+                buf.extend(got)
+                last_rx = time.monotonic()
+            else:
+                # Nothing ready — check idle gap
+                if last_rx is not None and (time.monotonic() - last_rx) >= idle_gap:
+                    break
+                time.sleep(0.005)
+
+        return bytes(buf)
+
+    def read_exact(self, n: int, timeout: float = 2.0) -> bytes:
+        """
+        Read exactly *n* bytes or raise TimeoutError.
+
+        Useful when the caller already knows the expected response length
+        (e.g. fixed-size ACK packets).
+        """
+        buf = bytearray()
+        deadline = time.monotonic() + timeout
+        while len(buf) < n:
+            if time.monotonic() >= deadline:
+                raise TimeoutError(
+                    f"read_exact: wanted {n} bytes, got {len(buf)} "
+                    f"after {timeout:.1f}s"
+                )
+            got = self.read(n - len(buf))
+            if got:
+                buf.extend(got)
+            else:
+                time.sleep(0.005)
+        return bytes(buf)
+
+
+# ── Serial transport ──────────────────────────────────────────────────────────
+
+# Default baud rate confirmed from Blastware / MiniMate Plus documentation.
+DEFAULT_BAUD = 38_400
+
+# pyserial serial port config matching the MiniMate Plus RS-232 spec:
+# 8 data bits, no parity, 1 stop bit (8N1).
+_SERIAL_BYTESIZE = 8   # serial.EIGHTBITS
+_SERIAL_PARITY   = "N" # serial.PARITY_NONE
+_SERIAL_STOPBITS = 1   # serial.STOPBITS_ONE
+
+
+class SerialTransport(BaseTransport):
+    """
+    pyserial-backed transport for a direct RS-232 cable connection.
+
+    The port is opened with a very short read timeout (10 ms) so that
+    read() returns quickly and the caller can implement its own framing /
+    timeout logic without blocking the whole process.
+
+    Args:
+        port:    COM port name (e.g. "COM5" on Windows, "/dev/ttyUSB0" on Linux).
+        baud:    Baud rate (default 38400).
+        rts_cts: Enable RTS/CTS hardware flow control (default False — MiniMate
+                 typically uses no flow control).
+    """
+
+    # Internal read timeout (seconds).  Short so read() is non-blocking in practice.
+    _READ_TIMEOUT = 0.01
+
+    def __init__(
+        self,
+        port: str,
+        baud: int = DEFAULT_BAUD,
+        rts_cts: bool = False,
+    ) -> None:
+        if serial is None:
+            raise ImportError(
+                "pyserial is required for SerialTransport. "
+                "Install it with: pip install pyserial"
+            )
+        self.port    = port
+        self.baud    = baud
+        self.rts_cts = rts_cts
+        self._ser: Optional[serial.Serial] = None
+
+    # ── BaseTransport interface ───────────────────────────────────────────────
+
+    def connect(self) -> None:
+        """Open the serial port.  Raises serial.SerialException on failure."""
+        if self._ser and self._ser.is_open:
+            return  # Already open — idempotent
+        self._ser = serial.Serial(
+            port      = self.port,
+            baudrate  = self.baud,
+            bytesize  = _SERIAL_BYTESIZE,
+            parity    = _SERIAL_PARITY,
+            stopbits  = _SERIAL_STOPBITS,
+            timeout   = self._READ_TIMEOUT,
+            rtscts    = self.rts_cts,
+            xonxoff   = False,
+            dsrdtr    = False,
+        )
+        # Flush any stale bytes left in device / OS buffers from a previous session
+        self._ser.reset_input_buffer()
+        self._ser.reset_output_buffer()
+
+    def disconnect(self) -> None:
+        """Close the serial port.  Safe to call even if already closed."""
+        if self._ser:
+            try:
+                self._ser.close()
+            except Exception:
+                pass
+            self._ser = None
+
+    @property
+    def is_connected(self) -> bool:
+        return bool(self._ser and self._ser.is_open)
+
+    def write(self, data: bytes) -> None:
+        """
+        Write *data* to the serial port.
+
+        Raises:
+            RuntimeError: if not connected.
+            serial.SerialException: on I/O error.
+        """
+        if not self.is_connected:
+            raise RuntimeError("SerialTransport.write: not connected")
+        self._ser.write(data)  # type: ignore[union-attr]
+        self._ser.flush()      # type: ignore[union-attr]
+
+    def read(self, n: int) -> bytes:
+        """
+        Read up to *n* bytes from the serial port.
+
+        Returns b"" immediately if no data is available (non-blocking in
+        practice thanks to the 10 ms read timeout).
+
+        Raises:
+            RuntimeError: if not connected.
+        """
+        if not self.is_connected:
+            raise RuntimeError("SerialTransport.read: not connected")
+        return self._ser.read(n)  # type: ignore[union-attr]
+
+    # ── Extras ────────────────────────────────────────────────────────────────
+
+    def flush_input(self) -> None:
+        """Discard any unread bytes in the OS receive buffer."""
+        if self.is_connected:
+            self._ser.reset_input_buffer()  # type: ignore[union-attr]
+
+    def __repr__(self) -> str:
+        state = "open" if self.is_connected else "closed"
+        return f"SerialTransport({self.port!r}, baud={self.baud}, {state})"
+
+
+# ── TCP transport ─────────────────────────────────────────────────────────────
+
+# Default TCP port for Blastware modem communications / ACH relay.
+# Confirmed from field setup: Blastware → Communication Setup → TCP/IP uses 12345.
+DEFAULT_TCP_PORT = 12345
+
+
+class TcpTransport(BaseTransport):
+    """
+    TCP socket transport for MiniMate Plus units in the field.
+
+    The protocol bytes over TCP are identical to RS-232 — TCP is simply a
+    different physical layer.  The modem (Sierra Wireless RV55 / RX55, or older
+    Raven X) bridges the unit's RS-232 serial port to a TCP socket transparently.
+    No application-layer handshake or framing is added.
+
+    Two usage scenarios:
+
+      "Call up" (outbound): SFM connects to the unit's modem IP directly.
+          TcpTransport(host="203.0.113.5", port=12345)
+
+      "Call home" / ACH relay: The unit has already dialled in to the office
+          ACH server, which bridged the modem to a TCP socket.  In this case
+          the host/port identifies the relay's listening socket, not the modem.
+          (ACH inbound mode is handled by a separate AchServer — not this class.)
+
+    IMPORTANT — modem data forwarding delay:
+    Sierra Wireless (and Raven) modems buffer RS-232 bytes for up to 1 second
+    before forwarding them as a TCP segment ("Data Forwarding Timeout" in
+    ACEmanager).  read_until_idle() is overridden to use idle_gap=1.5 s rather
+    than the serial default of 0.05 s — without this, the parser would declare
+    a frame complete mid-stream during the modem's buffering pause.
+
+    Args:
+        host:            IP address or hostname of the modem / ACH relay.
+        port:            TCP port number (default 12345).
+        connect_timeout: Seconds to wait for the TCP handshake (default 10.0).
+    """
+
+    # Internal recv timeout — short so read() returns promptly if no data.
+    _RECV_TIMEOUT = 0.01
+
+    def __init__(
+        self,
+        host: str,
+        port: int = DEFAULT_TCP_PORT,
+        connect_timeout: float = 10.0,
+    ) -> None:
+        self.host            = host
+        self.port            = port
+        self.connect_timeout = connect_timeout
+        self._sock: Optional[socket.socket] = None
+
+    # ── BaseTransport interface ───────────────────────────────────────────────
+
+    def connect(self) -> None:
+        """
+        Open a TCP connection to host:port.
+
+        Idempotent — does nothing if already connected.
+
+        Raises:
+            OSError / socket.timeout: if the connection cannot be established.
+        """
+        if self._sock is not None:
+            return  # Already connected — idempotent
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(self.connect_timeout)
+        sock.connect((self.host, self.port))
+        # Switch to short timeout so read() is non-blocking in practice
+        sock.settimeout(self._RECV_TIMEOUT)
+        self._sock = sock
+
+    def disconnect(self) -> None:
+        """Close the TCP socket.  Safe to call even if already closed."""
+        if self._sock:
+            try:
+                self._sock.shutdown(socket.SHUT_RDWR)
+            except OSError:
+                pass
+            try:
+                self._sock.close()
+            except OSError:
+                pass
+            self._sock = None
+
+    @property
+    def is_connected(self) -> bool:
+        return self._sock is not None
+
+    def write(self, data: bytes) -> None:
+        """
+        Send all bytes to the peer.
+
+        Raises:
+            RuntimeError: if not connected.
+            OSError: on network I/O error.
+        """
+        if not self.is_connected:
+            raise RuntimeError("TcpTransport.write: not connected")
+        self._sock.sendall(data)  # type: ignore[union-attr]
+
+    def read(self, n: int) -> bytes:
+        """
+        Read up to *n* bytes from the socket.
+
+        Returns b"" immediately if no data is available (non-blocking in
+        practice thanks to the short socket timeout).
+
+        Raises:
+            RuntimeError: if not connected.
+        """
+        if not self.is_connected:
+            raise RuntimeError("TcpTransport.read: not connected")
+        try:
+            return self._sock.recv(n)  # type: ignore[union-attr]
+        except socket.timeout:
+            return b""
+
+    def read_until_idle(
+        self,
+        timeout: float = 2.0,
+        idle_gap: float = 1.5,
+        chunk: int = 256,
+    ) -> bytes:
+        """
+        TCP-aware version of read_until_idle.
+
+        Overrides the BaseTransport default to use a much longer idle_gap (1.5 s
+        vs 0.05 s for serial).  This is necessary because the Raven modem (and
+        similar cellular modems) buffer serial-port bytes for up to 1 second
+        before forwarding them over TCP ("Data Forwarding Timeout" setting).
+
+        If read_until_idle returned after a 50 ms quiet period, it would trigger
+        mid-frame when the modem is still accumulating bytes — causing frame
+        parse failures on every call.
+
+        Args:
+            timeout:  Hard deadline from first byte (default 2.0 s — callers
+                      typically pass a longer value for S3 frames).
+            idle_gap: Quiet-line threshold (default 1.5 s to survive modem
+                      buffering).  Pass a smaller value only if you are
+                      connecting directly to a unit's Ethernet port with no
+                      modem buffering in the path.
+            chunk:    Bytes per low-level recv() call.
+        """
+        return super().read_until_idle(timeout=timeout, idle_gap=idle_gap, chunk=chunk)
+
+    def __repr__(self) -> str:
+        state = "connected" if self.is_connected else "disconnected"
+        return f"TcpTransport({self.host!r}, port={self.port}, {state})"
+
+
+# ── Inbound / accepted-socket transport ───────────────────────────────────────
+
+class SocketTransport(TcpTransport):
+    """
+    Like TcpTransport but wraps an already-accepted inbound socket.
+
+    Used by the ACH inbound server (bridges/ach_server.py) — the device dials
+    IN to us, so by the time we create this transport the socket is already live.
+    connect() is a no-op; everything else (read, write, read_until_idle, …) is
+    inherited unchanged from TcpTransport.
+
+    Args:
+        sock: An already-connected socket.socket returned by server_socket.accept().
+        peer: Human-readable peer label for repr / logging (e.g. "203.0.113.5:54321").
+    """
+
+    def __init__(self, sock: socket.socket, peer: str = "inbound") -> None:
+        # Bypass TcpTransport.__init__ — we already have a live socket.
+        self.host            = peer
+        self.port            = 0
+        self.connect_timeout = 0.0
+        self._sock           = sock
+        sock.settimeout(self._RECV_TIMEOUT)
+
+    def connect(self) -> None:
+        """No-op — socket was already accepted inbound."""
+        pass  # Already have a live socket; nothing to open.
+
+    @property
+    def is_connected(self) -> bool:
+        return self._sock is not None
+
+    def __repr__(self) -> str:
+        return f"SocketTransport(peer={self.host!r})"

parsers/README_s3_parser.md

@@ -0,0 +1,125 @@
+# s3_parser.py
+
+## Purpose
+
+`s3_parser.py` extracts complete DLE-framed packets from raw serial
+capture files produced by the `s3_bridge` logger.
+
+It operates strictly at the **framing layer**. It does **not** decode
+higher-level protocol structures.
+
+This parser is designed specifically for Instantel / Series 3--style
+serial traffic using:
+
+-   `DLE STX` (`0x10 0x02`) to start a frame
+-   `DLE ETX` (`0x10 0x03`) to end a frame
+-   DLE byte stuffing (`0x10 0x10` → literal `0x10`)
+
+------------------------------------------------------------------------
+
+## Design Philosophy
+
+This parser:
+
+-   Uses a deterministic state machine (no regex, no global scanning).
+-   Assumes raw wire framing is preserved (`DLE+ETX` is present).
+-   Does **not** attempt auto-detection of framing style.
+-   Extracts only complete `STX → ETX` frame pairs.
+-   Safely ignores incomplete trailing frames at EOF.
+
+Separation of concerns is intentional:
+
+-   **Parser = framing extraction**
+-   **Decoder = protocol interpretation (future layer)**
+
+Do not add message-level logic here.
+
+------------------------------------------------------------------------
+
+## Input
+
+Raw binary `.bin` files captured from:
+
+-   `--raw-bw` tap (Blastware → S3)
+-   `--raw-s3` tap (S3 → Blastware)
+
+These must preserve raw serial bytes.
+
+------------------------------------------------------------------------
+
+## Usage
+
+Basic frame extraction:
+
+``` bash
+python s3_parser.py raw_s3.bin --trailer-len 2
+```
+
+Options:
+
+-   `--trailer-len N`
+    -   Number of bytes to capture after `DLE ETX`
+    -   Often `2` (CRC16)
+-   `--crc`
+    -   Attempts CRC16 validation against first 2 trailer bytes
+    -   Tries several common CRC16 variants
+-   `--crc-endian {little|big}`
+    -   Endianness for interpreting trailer bytes (default: little)
+-   `--out frames.jsonl`
+    -   Writes full JSONL output instead of printing summary
+
+------------------------------------------------------------------------
+
+## Output Format
+
+Each extracted frame produces:
+
+``` json
+{
+  "index": 0,
+  "start_offset": 20,
+  "end_offset": 4033,
+  "payload_len": 3922,
+  "payload_hex": "...",
+  "trailer_hex": "000f",
+  "crc_match": null
+}
+```
+
+Where:
+
+-   `payload_hex` = unescaped payload bytes (DLE stuffing removed)
+-   `trailer_hex` = bytes immediately following `DLE ETX`
+-   `crc_match` = matched CRC algorithm (if `--crc` enabled)
+
+------------------------------------------------------------------------
+
+## Known Behavior
+
+-   Frames that start but never receive a matching `DLE ETX` before EOF
+    are discarded.
+-   Embedded `0x10 0x02` inside payload does not trigger a new frame
+    (correct behavior).
+-   Embedded `0x10 0x10` is correctly unescaped to a single `0x10`.
+
+------------------------------------------------------------------------
+
+## What This Parser Does NOT Do
+
+-   It does not decode Instantel message structure.
+-   It does not interpret block IDs or message types.
+-   It does not validate protocol-level fields.
+-   It does not reconstruct multi-frame logical responses.
+
+That is the responsibility of a higher-level decoder.
+
+------------------------------------------------------------------------
+
+## Status
+
+Framing layer verified against:
+
+-   raw_bw.bin (command/control direction)
+-   raw_s3.bin (device response direction)
+
+State machine validated via start/end instrumentation.

parsers/bw_frames.jsonl

@@ -0,0 +1,98 @@
+{"index": 0, "start_offset": 0, "end_offset": 21, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 1, "start_offset": 21, "end_offset": 42, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 2, "start_offset": 42, "end_offset": 63, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 3, "start_offset": 63, "end_offset": 84, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 4, "start_offset": 84, "end_offset": 105, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 5, "start_offset": 105, "end_offset": 126, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 6, "start_offset": 126, "end_offset": 147, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 7, "start_offset": 147, "end_offset": 168, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 8, "start_offset": 168, "end_offset": 189, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 9, "start_offset": 189, "end_offset": 210, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 10, "start_offset": 210, "end_offset": 231, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 11, "start_offset": 231, "end_offset": 252, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 12, "start_offset": 252, "end_offset": 273, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 13, "start_offset": 273, "end_offset": 294, "payload_len": 17, "payload_hex": "1000150000000000000000000000000025", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 14, "start_offset": 294, "end_offset": 315, "payload_len": 17, "payload_hex": "10001500000a000000000000000000002f", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 15, "start_offset": 315, "end_offset": 427, "payload_len": 108, "payload_hex": "10006800005a00000000000000000000005809000000010107cb00061e00010107cb00140000000000173b00000000000000000000000000000100000000000100000000000000010001000000000000000000000000000000000064000000000000001effdc0000100200c8", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 16, "start_offset": 427, "end_offset": 448, "payload_len": 17, "payload_hex": "1000730000000000000000000000000083", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 17, "start_offset": 448, "end_offset": 1497, "payload_len": 1045, "payload_hex": "1000710010040000000000000000000000082a6400001004100400003c0000be800000000040400000001003000f000000073dbb457a3db956e1000100015374616e64617264205265636f7264696e672053657475702e7365740000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000050726f6a6563743a0000000000000000000000000000544553542000000000000000000000000000000000000000000000000000000000000000000000000000436c69656e743a000000000000000000000000000000436c6175646520746573743200000000000000000000000000000000000000000000000000000000000055736572204e616d653a00000000000000000000000054657272612d4d656368616e69637320496e632e202d20422e204861727269736f6e000000000000000053656973204c6f633a000000000000000000000000004c6f636174696f6e202331202d20427269616e7320486f75736500000000000000000000000000000000457874656e646564204e6f74657300000000000000000a000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000007", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 18, "start_offset": 1497, "end_offset": 2574, "payload_len": 1073, "payload_hex": "1000710010040000001004000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000015472616e000000010050000f0028001510021003011004001003000040c697fd00003f19999a696e2e00400000002f730000000156657274000000010050000f0028001510021003011004001003000040c697fd00003f19999a696e2e00400000002f73000000014c6f6e67000000010050000f0028001510021003011004001003000040c697fd00003f19999a696e2e00400000002f73000000004d69634c000000100200c80032000a000a1002d501db000500003d38560800003c1374bc707369003cac0831284c29000010025472616e320000010050000f0028001510021003011004001003000040c697fd00003f000000696e2e00400000002f73000000100256657274320000010050000f0028001510021003011004001003000040c697fd00003f000000696e2e00400000002f7300000010024c6f6e67320000010050000f0028001510021003011004001003000040c697fd00003f000000696e2e00400000002f73000000004d69634c1002", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 19, "start_offset": 2574, "end_offset": 2641, "payload_len": 63, "payload_hex": "10007100002c00000800000000000000320000100200c80032000a000a1002d501db000500003d38560800003c23d70a707369003cac0831284c29007cea32", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 20, "start_offset": 2641, "end_offset": 2662, "payload_len": 17, "payload_hex": "1000720000000000000000000000000082", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 21, "start_offset": 2662, "end_offset": 2711, "payload_len": 45, "payload_hex": "10008200001c00000000000000000000001ad5000001080affffffffffffffffffffffffffffffffffff00009e", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 22, "start_offset": 2711, "end_offset": 2732, "payload_len": 17, "payload_hex": "1000830000000000000000000000000093", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 23, "start_offset": 2732, "end_offset": 2957, "payload_len": 221, "payload_hex": "1000690000ca0000000000000000000000c8080000010001000100010001000100010010020001001e0010020001000a000a4576656e742053756d6d617279205265706f7274000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002580000801018c76af", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 24, "start_offset": 2957, "end_offset": 2978, "payload_len": 17, "payload_hex": "1000740000000000000000000000000084", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 25, "start_offset": 2978, "end_offset": 2999, "payload_len": 17, "payload_hex": "1000720000000000000000000000000082", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 26, "start_offset": 2999, "end_offset": 3020, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 27, "start_offset": 3020, "end_offset": 3041, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 28, "start_offset": 3041, "end_offset": 3062, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 29, "start_offset": 3062, "end_offset": 3083, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 30, "start_offset": 3083, "end_offset": 3104, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 31, "start_offset": 3104, "end_offset": 3125, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 32, "start_offset": 3125, "end_offset": 3146, "payload_len": 17, "payload_hex": "1000150000000000000000000000000025", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 33, "start_offset": 3146, "end_offset": 3167, "payload_len": 17, "payload_hex": "10001500000a000000000000000000002f", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 34, "start_offset": 3167, "end_offset": 3188, "payload_len": 17, "payload_hex": "1000010000000000000000000000000011", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 35, "start_offset": 3188, "end_offset": 3209, "payload_len": 17, "payload_hex": "10000100009800000000000000000000a9", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 36, "start_offset": 3209, "end_offset": 3230, "payload_len": 17, "payload_hex": "1000080000000000000000000000000018", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 37, "start_offset": 3230, "end_offset": 3251, "payload_len": 17, "payload_hex": "1000080000580000000000000000000070", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 38, "start_offset": 3251, "end_offset": 3272, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 39, "start_offset": 3272, "end_offset": 3293, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 40, "start_offset": 3293, "end_offset": 3314, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 41, "start_offset": 3314, "end_offset": 3335, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 42, "start_offset": 3335, "end_offset": 3356, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 43, "start_offset": 3356, "end_offset": 3377, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 44, "start_offset": 3377, "end_offset": 3398, "payload_len": 17, "payload_hex": "1000010000000000000000000000000011", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 45, "start_offset": 3398, "end_offset": 3419, "payload_len": 17, "payload_hex": "10000100009800000000000000000000a9", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 46, "start_offset": 3419, "end_offset": 3440, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 47, "start_offset": 3440, "end_offset": 3461, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 48, "start_offset": 3461, "end_offset": 3482, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 49, "start_offset": 3482, "end_offset": 3503, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 50, "start_offset": 3503, "end_offset": 3524, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 51, "start_offset": 3524, "end_offset": 3545, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 52, "start_offset": 3545, "end_offset": 3566, "payload_len": 17, "payload_hex": "1000150000000000000000000000000025", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 53, "start_offset": 3566, "end_offset": 3587, "payload_len": 17, "payload_hex": "10001500000a000000000000000000002f", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 54, "start_offset": 3587, "end_offset": 3608, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 55, "start_offset": 3608, "end_offset": 3629, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 56, "start_offset": 3629, "end_offset": 3650, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 57, "start_offset": 3650, "end_offset": 3671, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 58, "start_offset": 3671, "end_offset": 3692, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 59, "start_offset": 3692, "end_offset": 3713, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 60, "start_offset": 3713, "end_offset": 3734, "payload_len": 17, "payload_hex": "1000150000000000000000000000000025", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 61, "start_offset": 3734, "end_offset": 3755, "payload_len": 17, "payload_hex": "10001500000a000000000000000000002f", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 62, "start_offset": 3755, "end_offset": 3776, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 63, "start_offset": 3776, "end_offset": 3797, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 64, "start_offset": 3797, "end_offset": 3818, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 65, "start_offset": 3818, "end_offset": 3839, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 66, "start_offset": 3839, "end_offset": 3860, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 67, "start_offset": 3860, "end_offset": 3881, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 68, "start_offset": 3881, "end_offset": 3902, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 69, "start_offset": 3902, "end_offset": 3923, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 70, "start_offset": 3923, "end_offset": 3944, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 71, "start_offset": 3944, "end_offset": 3965, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 72, "start_offset": 3965, "end_offset": 3986, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 73, "start_offset": 3986, "end_offset": 4007, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 74, "start_offset": 4007, "end_offset": 4028, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 75, "start_offset": 4028, "end_offset": 4049, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 76, "start_offset": 4049, "end_offset": 4070, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 77, "start_offset": 4070, "end_offset": 4091, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 78, "start_offset": 4091, "end_offset": 4112, "payload_len": 17, "payload_hex": "10005b000000000000000000000000006b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 79, "start_offset": 4112, "end_offset": 4133, "payload_len": 17, "payload_hex": "10005b000030000000000000000000009b", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 80, "start_offset": 4133, "end_offset": 4154, "payload_len": 17, "payload_hex": "1000010000000000000000000000000011", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 81, "start_offset": 4154, "end_offset": 4175, "payload_len": 17, "payload_hex": "10000100009800000000000000000000a9", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 82, "start_offset": 4175, "end_offset": 4196, "payload_len": 17, "payload_hex": "10002e000000000000000000000000003e", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 83, "start_offset": 4196, "end_offset": 4217, "payload_len": 17, "payload_hex": "10002e00001a0000000000000000000058", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 84, "start_offset": 4217, "end_offset": 4238, "payload_len": 17, "payload_hex": "1000010000000000000000000000000011", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 85, "start_offset": 4238, "end_offset": 4259, "payload_len": 17, "payload_hex": "10000100009800000000000000000000a9", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 86, "start_offset": 4259, "end_offset": 4280, "payload_len": 17, "payload_hex": "10001a000000000000000000006400008e", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 87, "start_offset": 4280, "end_offset": 4302, "payload_len": 18, "payload_hex": "10001a001004000000000000000064000092", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 88, "start_offset": 4302, "end_offset": 4325, "payload_len": 19, "payload_hex": "10001a00100400000010040000000064000096", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 89, "start_offset": 4325, "end_offset": 4346, "payload_len": 17, "payload_hex": "10001a00002a00000800000000640000c0", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 90, "start_offset": 4346, "end_offset": 4367, "payload_len": 17, "payload_hex": "1000090000000000000000000000000019", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 91, "start_offset": 4367, "end_offset": 4388, "payload_len": 17, "payload_hex": "1000090000ca00000000000000000000e3", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 92, "start_offset": 4388, "end_offset": 4409, "payload_len": 17, "payload_hex": "1000080000000000000000000000000018", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 93, "start_offset": 4409, "end_offset": 4430, "payload_len": 17, "payload_hex": "1000080000580000000000000000000070", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 94, "start_offset": 4430, "end_offset": 4451, "payload_len": 17, "payload_hex": "1000010000000000000000000000000011", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 95, "start_offset": 4451, "end_offset": 4472, "payload_len": 17, "payload_hex": "10000100009800000000000000000000a9", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 96, "start_offset": 4472, "end_offset": 4493, "payload_len": 17, "payload_hex": "1000080000000000000000000000000018", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}
+{"index": 97, "start_offset": 4493, "end_offset": 4514, "payload_len": 17, "payload_hex": "1000080000580000000000000000000070", "trailer_hex": "", "checksum_valid": null, "checksum_type": null, "checksum_hex": null}

parsers/frame_db.py

@@ -0,0 +1,337 @@
+#!/usr/bin/env python3
+"""
+frame_db.py — SQLite frame database for Instantel protocol captures.
+
+Schema:
+  captures   — one row per ingested capture pair (deduped by SHA256)
+  frames     — one row per parsed frame
+  byte_values — one row per (frame, offset, value) for fast indexed queries
+
+Usage:
+  db = FrameDB()               # opens default DB at ~/.seismo_lab/frames.db
+  db = FrameDB(path)           # custom path
+  cap_id = db.ingest(sessions, s3_path, bw_path)
+  rows = db.query_frames(sub=0xF7, direction="S3")
+  rows = db.query_by_byte(offset=85, value=0x0A)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import sqlite3
+import struct
+from pathlib import Path
+from typing import Optional
+
+# ─────────────────────────────────────────────────────────────────────────────
+# DB location
+# ─────────────────────────────────────────────────────────────────────────────
+
+DEFAULT_DB_DIR = Path.home() / ".seismo_lab"
+DEFAULT_DB_PATH = DEFAULT_DB_DIR / "frames.db"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Schema
+# ─────────────────────────────────────────────────────────────────────────────
+
+_DDL = """
+PRAGMA journal_mode=WAL;
+PRAGMA foreign_keys=ON;
+
+CREATE TABLE IF NOT EXISTS captures (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    timestamp    TEXT    NOT NULL,          -- ISO-8601 ingest time
+    s3_path      TEXT,
+    bw_path      TEXT,
+    capture_hash TEXT    NOT NULL UNIQUE,   -- SHA256 of s3_blob+bw_blob
+    notes        TEXT    DEFAULT ''
+);
+
+CREATE TABLE IF NOT EXISTS frames (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    capture_id   INTEGER NOT NULL REFERENCES captures(id) ON DELETE CASCADE,
+    session_idx  INTEGER NOT NULL,
+    direction    TEXT    NOT NULL,   -- 'BW' or 'S3'
+    sub          INTEGER,            -- NULL if malformed
+    page_key     INTEGER,
+    sub_name     TEXT,
+    payload      BLOB    NOT NULL,
+    payload_len  INTEGER NOT NULL,
+    checksum_ok  INTEGER             -- 1/0/NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_frames_capture  ON frames(capture_id);
+CREATE INDEX IF NOT EXISTS idx_frames_sub      ON frames(sub);
+CREATE INDEX IF NOT EXISTS idx_frames_page_key ON frames(page_key);
+CREATE INDEX IF NOT EXISTS idx_frames_dir      ON frames(direction);
+
+CREATE TABLE IF NOT EXISTS byte_values (
+    id       INTEGER PRIMARY KEY AUTOINCREMENT,
+    frame_id INTEGER NOT NULL REFERENCES frames(id) ON DELETE CASCADE,
+    offset   INTEGER NOT NULL,
+    value    INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_bv_frame  ON byte_values(frame_id);
+CREATE INDEX IF NOT EXISTS idx_bv_offset ON byte_values(offset);
+CREATE INDEX IF NOT EXISTS idx_bv_value  ON byte_values(value);
+CREATE INDEX IF NOT EXISTS idx_bv_off_val ON byte_values(offset, value);
+"""
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Helpers
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _sha256_blobs(s3_blob: bytes, bw_blob: bytes) -> str:
+    h = hashlib.sha256()
+    h.update(s3_blob)
+    h.update(bw_blob)
+    return h.hexdigest()
+
+
+def _interp_bytes(data: bytes, offset: int) -> dict:
+    """
+    Return multi-interpretation dict for 1–4 bytes starting at offset.
+    Used in the GUI's byte interpretation panel.
+    """
+    result: dict = {}
+    remaining = len(data) - offset
+    if remaining <= 0:
+        return result
+
+    b1 = data[offset]
+    result["uint8"] = b1
+    result["int8"]  = b1 if b1 < 128 else b1 - 256
+
+    if remaining >= 2:
+        u16be = struct.unpack_from(">H", data, offset)[0]
+        u16le = struct.unpack_from("<H", data, offset)[0]
+        result["uint16_be"] = u16be
+        result["uint16_le"] = u16le
+
+    if remaining >= 4:
+        f32be = struct.unpack_from(">f", data, offset)[0]
+        f32le = struct.unpack_from("<f", data, offset)[0]
+        u32be = struct.unpack_from(">I", data, offset)[0]
+        u32le = struct.unpack_from("<I", data, offset)[0]
+        result["float32_be"] = round(f32be, 6)
+        result["float32_le"] = round(f32le, 6)
+        result["uint32_be"]  = u32be
+        result["uint32_le"]  = u32le
+
+    return result
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# FrameDB class
+# ─────────────────────────────────────────────────────────────────────────────
+
+class FrameDB:
+    def __init__(self, path: Optional[Path] = None) -> None:
+        if path is None:
+            path = DEFAULT_DB_PATH
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self.path = path
+        self._con = sqlite3.connect(str(path), check_same_thread=False)
+        self._con.row_factory = sqlite3.Row
+        self._init_schema()
+
+    def _init_schema(self) -> None:
+        self._con.executescript(_DDL)
+        self._con.commit()
+
+    def close(self) -> None:
+        self._con.close()
+
+    # ── Ingest ────────────────────────────────────────────────────────────
+
+    def ingest(
+        self,
+        sessions: list,             # list[Session] from s3_analyzer
+        s3_path: Optional[Path],
+        bw_path: Optional[Path],
+        notes: str = "",
+    ) -> Optional[int]:
+        """
+        Ingest a list of sessions into the DB.
+        Returns capture_id, or None if already ingested (duplicate hash).
+        """
+        import datetime
+
+        s3_blob = s3_path.read_bytes() if s3_path and s3_path.exists() else b""
+        bw_blob = bw_path.read_bytes() if bw_path and bw_path.exists() else b""
+        cap_hash = _sha256_blobs(s3_blob, bw_blob)
+
+        # Dedup check
+        row = self._con.execute(
+            "SELECT id FROM captures WHERE capture_hash=?", (cap_hash,)
+        ).fetchone()
+        if row:
+            return None  # already in DB
+
+        ts = datetime.datetime.now().isoformat(timespec="seconds")
+        cur = self._con.execute(
+            "INSERT INTO captures (timestamp, s3_path, bw_path, capture_hash, notes) "
+            "VALUES (?, ?, ?, ?, ?)",
+            (ts, str(s3_path) if s3_path else None,
+                 str(bw_path) if bw_path else None,
+                 cap_hash, notes)
+        )
+        cap_id = cur.lastrowid
+
+        for sess in sessions:
+            for af in sess.all_frames:
+                frame_id = self._insert_frame(cap_id, af)
+                self._insert_byte_values(frame_id, af.frame.payload)
+
+        self._con.commit()
+        return cap_id
+
+    def _insert_frame(self, cap_id: int, af) -> int:
+        """Insert one AnnotatedFrame; return its rowid."""
+        sub      = af.header.sub      if af.header else None
+        page_key = af.header.page_key if af.header else None
+        chk_ok   = None
+        if af.frame.checksum_valid is True:
+            chk_ok = 1
+        elif af.frame.checksum_valid is False:
+            chk_ok = 0
+
+        cur = self._con.execute(
+            "INSERT INTO frames "
+            "(capture_id, session_idx, direction, sub, page_key, sub_name, payload, payload_len, checksum_ok) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (cap_id, af.session_idx, af.source,
+             sub, page_key, af.sub_name,
+             af.frame.payload, len(af.frame.payload), chk_ok)
+        )
+        return cur.lastrowid
+
+    def _insert_byte_values(self, frame_id: int, payload: bytes) -> None:
+        """Insert one row per byte in payload into byte_values."""
+        rows = [(frame_id, i, b) for i, b in enumerate(payload)]
+        self._con.executemany(
+            "INSERT INTO byte_values (frame_id, offset, value) VALUES (?, ?, ?)",
+            rows
+        )
+
+    # ── Queries ───────────────────────────────────────────────────────────
+
+    def list_captures(self) -> list[sqlite3.Row]:
+        return self._con.execute(
+            "SELECT id, timestamp, s3_path, bw_path, notes, "
+            "       (SELECT COUNT(*) FROM frames WHERE capture_id=captures.id) AS frame_count "
+            "FROM captures ORDER BY id DESC"
+        ).fetchall()
+
+    def query_frames(
+        self,
+        capture_id: Optional[int] = None,
+        direction:  Optional[str] = None,   # "BW" or "S3"
+        sub:        Optional[int] = None,
+        page_key:   Optional[int] = None,
+        limit:      int = 500,
+    ) -> list[sqlite3.Row]:
+        """
+        Query frames table with optional filters.
+        Returns rows with: id, capture_id, session_idx, direction, sub, page_key,
+                           sub_name, payload, payload_len, checksum_ok
+        """
+        clauses = []
+        params  = []
+
+        if capture_id is not None:
+            clauses.append("capture_id=?"); params.append(capture_id)
+        if direction is not None:
+            clauses.append("direction=?");  params.append(direction)
+        if sub is not None:
+            clauses.append("sub=?");        params.append(sub)
+        if page_key is not None:
+            clauses.append("page_key=?");   params.append(page_key)
+
+        where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
+        sql = f"SELECT * FROM frames {where} ORDER BY id LIMIT ?"
+        params.append(limit)
+
+        return self._con.execute(sql, params).fetchall()
+
+    def query_by_byte(
+        self,
+        offset:     int,
+        value:      Optional[int] = None,
+        capture_id: Optional[int] = None,
+        direction:  Optional[str] = None,
+        sub:        Optional[int] = None,
+        limit:      int = 500,
+    ) -> list[sqlite3.Row]:
+        """
+        Return frames that have a specific byte at a specific offset.
+        Joins byte_values -> frames for indexed lookup.
+        """
+        clauses = ["bv.offset=?"]
+        params  = [offset]
+
+        if value is not None:
+            clauses.append("bv.value=?"); params.append(value)
+        if capture_id is not None:
+            clauses.append("f.capture_id=?"); params.append(capture_id)
+        if direction is not None:
+            clauses.append("f.direction=?"); params.append(direction)
+        if sub is not None:
+            clauses.append("f.sub=?"); params.append(sub)
+
+        where = "WHERE " + " AND ".join(clauses)
+        sql = (
+            f"SELECT f.*, bv.offset AS q_offset, bv.value AS q_value "
+            f"FROM byte_values bv "
+            f"JOIN frames f ON f.id=bv.frame_id "
+            f"{where} "
+            f"ORDER BY f.id LIMIT ?"
+        )
+        params.append(limit)
+        return self._con.execute(sql, params).fetchall()
+
+    def get_frame_payload(self, frame_id: int) -> Optional[bytes]:
+        row = self._con.execute(
+            "SELECT payload FROM frames WHERE id=?", (frame_id,)
+        ).fetchone()
+        return bytes(row["payload"]) if row else None
+
+    def get_distinct_subs(self, capture_id: Optional[int] = None) -> list[int]:
+        if capture_id is not None:
+            rows = self._con.execute(
+                "SELECT DISTINCT sub FROM frames WHERE capture_id=? AND sub IS NOT NULL ORDER BY sub",
+                (capture_id,)
+            ).fetchall()
+        else:
+            rows = self._con.execute(
+                "SELECT DISTINCT sub FROM frames WHERE sub IS NOT NULL ORDER BY sub"
+            ).fetchall()
+        return [r[0] for r in rows]
+
+    def get_distinct_offsets(self, capture_id: Optional[int] = None) -> list[int]:
+        if capture_id is not None:
+            rows = self._con.execute(
+                "SELECT DISTINCT bv.offset FROM byte_values bv "
+                "JOIN frames f ON f.id=bv.frame_id WHERE f.capture_id=? ORDER BY bv.offset",
+                (capture_id,)
+            ).fetchall()
+        else:
+            rows = self._con.execute(
+                "SELECT DISTINCT offset FROM byte_values ORDER BY offset"
+            ).fetchall()
+        return [r[0] for r in rows]
+
+    def interpret_offset(self, payload: bytes, offset: int) -> dict:
+        """Return multi-format interpretation of bytes starting at offset."""
+        return _interp_bytes(payload, offset)
+
+    def get_stats(self) -> dict:
+        captures = self._con.execute("SELECT COUNT(*) FROM captures").fetchone()[0]
+        frames   = self._con.execute("SELECT COUNT(*) FROM frames").fetchone()[0]
+        bv_rows  = self._con.execute("SELECT COUNT(*) FROM byte_values").fetchone()[0]
+        return {"captures": captures, "frames": frames, "byte_value_rows": bv_rows}

parsers/gui_analyzer.py

@@ -0,0 +1,940 @@
+#!/usr/bin/env python3
+"""
+gui_analyzer.py — Tkinter GUI for s3_analyzer.
+
+Layout:
+  ┌─────────────────────────────────────────────────────────┐
+  │  [S3 file: ___________ Browse]  [BW file: ___ Browse]  │
+  │  [Analyze]  [Live mode toggle]  Status: Idle            │
+  ├──────────────────┬──────────────────────────────────────┤
+  │  Session list    │  Detail panel (tabs)                 │
+  │  ─ Session 0     │    Inventory | Hex Dump | Diff       │
+  │    └ POLL (BW)   │                                      │
+  │    └ POLL_RESP   │  (content of selected tab)           │
+  │  ─ Session 1     │                                      │
+  │    └ ...         │                                      │
+  └──────────────────┴──────────────────────────────────────┘
+  │  Status bar                                             │
+  └─────────────────────────────────────────────────────────┘
+"""
+
+from __future__ import annotations
+
+import queue
+import sys
+import threading
+import time
+import tkinter as tk
+from pathlib import Path
+from tkinter import filedialog, font, messagebox, ttk
+from typing import Optional
+
+sys.path.insert(0, str(Path(__file__).parent))
+from s3_analyzer import (  # noqa: E402
+    AnnotatedFrame,
+    FrameDiff,
+    Session,
+    annotate_frames,
+    diff_sessions,
+    format_hex_dump,
+    parse_bw,
+    parse_s3,
+    render_session_report,
+    split_into_sessions,
+    write_claude_export,
+)
+from frame_db import FrameDB, DEFAULT_DB_PATH  # noqa: E402
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Colour palette (dark-ish terminal feel)
+# ──────────────────────────────────────────────────────────────────────────────
+BG       = "#1e1e1e"
+BG2      = "#252526"
+BG3      = "#2d2d30"
+FG       = "#d4d4d4"
+FG_DIM   = "#6a6a6a"
+ACCENT   = "#569cd6"
+ACCENT2  = "#4ec9b0"
+RED      = "#f44747"
+YELLOW   = "#dcdcaa"
+GREEN    = "#4caf50"
+ORANGE   = "#ce9178"
+
+COL_BW   = "#9cdcfe"   # BW frames
+COL_S3   = "#4ec9b0"   # S3 frames
+COL_DIFF = "#f44747"   # Changed bytes
+COL_KNOW = "#4caf50"   # Known-field annotations
+COL_HEAD = "#569cd6"   # Section headers
+
+MONO = ("Consolas", 9)
+MONO_SM = ("Consolas", 8)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# State container
+# ──────────────────────────────────────────────────────────────────────────────
+
+class AnalyzerState:
+    def __init__(self) -> None:
+        self.sessions: list[Session] = []
+        self.diffs: list[Optional[list[FrameDiff]]] = []   # diffs[i] = diff of session i vs i-1
+        self.s3_path: Optional[Path] = None
+        self.bw_path: Optional[Path] = None
+        self.last_capture_id: Optional[int] = None
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Main GUI
+# ──────────────────────────────────────────────────────────────────────────────
+
+class AnalyzerGUI(tk.Tk):
+    def __init__(self) -> None:
+        super().__init__()
+        self.title("S3 Protocol Analyzer")
+        self.configure(bg=BG)
+        self.minsize(1050, 600)
+
+        self.state = AnalyzerState()
+        self._live_thread: Optional[threading.Thread] = None
+        self._live_stop = threading.Event()
+        self._live_q: queue.Queue[str] = queue.Queue()
+        self._db = FrameDB()
+
+        self._build_widgets()
+        self._poll_live_queue()
+
+    # ── widget construction ────────────────────────────────────────────────
+
+    def _build_widgets(self) -> None:
+        self._build_toolbar()
+        self._build_panes()
+        self._build_statusbar()
+
+    def _build_toolbar(self) -> None:
+        bar = tk.Frame(self, bg=BG2, pady=4)
+        bar.pack(side=tk.TOP, fill=tk.X)
+
+        pad = {"padx": 5, "pady": 2}
+
+        # S3 file
+        tk.Label(bar, text="S3 raw:", bg=BG2, fg=FG, font=MONO).pack(side=tk.LEFT, **pad)
+        self.s3_var = tk.StringVar()
+        tk.Entry(bar, textvariable=self.s3_var, width=28, bg=BG3, fg=FG,
+                 insertbackground=FG, relief="flat", font=MONO).pack(side=tk.LEFT, **pad)
+        tk.Button(bar, text="Browse", bg=BG3, fg=FG, relief="flat",
+                  activebackground=ACCENT, cursor="hand2",
+                  command=lambda: self._browse_file(self.s3_var, "raw_s3.bin")
+                  ).pack(side=tk.LEFT, **pad)
+
+        tk.Label(bar, text="  BW raw:", bg=BG2, fg=FG, font=MONO).pack(side=tk.LEFT, **pad)
+        self.bw_var = tk.StringVar()
+        tk.Entry(bar, textvariable=self.bw_var, width=28, bg=BG3, fg=FG,
+                 insertbackground=FG, relief="flat", font=MONO).pack(side=tk.LEFT, **pad)
+        tk.Button(bar, text="Browse", bg=BG3, fg=FG, relief="flat",
+                  activebackground=ACCENT, cursor="hand2",
+                  command=lambda: self._browse_file(self.bw_var, "raw_bw.bin")
+                  ).pack(side=tk.LEFT, **pad)
+
+        # Buttons
+        tk.Frame(bar, bg=BG2, width=10).pack(side=tk.LEFT)
+        self.analyze_btn = tk.Button(bar, text="Analyze", bg=ACCENT, fg="#ffffff",
+                                     relief="flat", padx=10, cursor="hand2",
+                                     font=("Consolas", 9, "bold"),
+                                     command=self._run_analyze)
+        self.analyze_btn.pack(side=tk.LEFT, **pad)
+
+        self.live_btn = tk.Button(bar, text="Live: OFF", bg=BG3, fg=FG,
+                                  relief="flat", padx=10, cursor="hand2",
+                                  font=MONO, command=self._toggle_live)
+        self.live_btn.pack(side=tk.LEFT, **pad)
+
+        self.export_btn = tk.Button(bar, text="Export for Claude", bg=ORANGE, fg="#000000",
+                                    relief="flat", padx=10, cursor="hand2",
+                                    font=("Consolas", 9, "bold"),
+                                    command=self._run_export, state="disabled")
+        self.export_btn.pack(side=tk.LEFT, **pad)
+
+        self.status_var = tk.StringVar(value="Idle")
+        tk.Label(bar, textvariable=self.status_var, bg=BG2, fg=FG_DIM,
+                 font=MONO, anchor="w").pack(side=tk.LEFT, padx=10)
+
+    def _build_panes(self) -> None:
+        pane = tk.PanedWindow(self, orient=tk.HORIZONTAL, bg=BG,
+                              sashwidth=4, sashrelief="flat")
+        pane.pack(fill=tk.BOTH, expand=True, padx=0, pady=0)
+
+        # ── Left: session/frame tree ──────────────────────────────────────
+        left = tk.Frame(pane, bg=BG2, width=260)
+        pane.add(left, minsize=200)
+
+        tk.Label(left, text="Sessions", bg=BG2, fg=ACCENT,
+                 font=("Consolas", 9, "bold"), anchor="w", padx=6).pack(fill=tk.X)
+
+        tree_frame = tk.Frame(left, bg=BG2)
+        tree_frame.pack(fill=tk.BOTH, expand=True)
+
+        style = ttk.Style()
+        style.theme_use("clam")
+        style.configure("Treeview",
+                         background=BG2, foreground=FG, fieldbackground=BG2,
+                         font=MONO_SM, rowheight=18, borderwidth=0)
+        style.configure("Treeview.Heading",
+                         background=BG3, foreground=ACCENT, font=MONO_SM)
+        style.map("Treeview", background=[("selected", BG3)],
+                  foreground=[("selected", "#ffffff")])
+
+        self.tree = ttk.Treeview(tree_frame, columns=("info",), show="tree headings",
+                                  selectmode="browse")
+        self.tree.heading("#0", text="Frame")
+        self.tree.heading("info", text="Info")
+        self.tree.column("#0", width=160, stretch=True)
+        self.tree.column("info", width=80, stretch=False)
+
+        vsb = ttk.Scrollbar(tree_frame, orient="vertical", command=self.tree.yview)
+        self.tree.configure(yscrollcommand=vsb.set)
+        vsb.pack(side=tk.RIGHT, fill=tk.Y)
+        self.tree.pack(fill=tk.BOTH, expand=True)
+
+        self.tree.tag_configure("session",   foreground=ACCENT, font=("Consolas", 9, "bold"))
+        self.tree.tag_configure("bw_frame",  foreground=COL_BW)
+        self.tree.tag_configure("s3_frame",  foreground=COL_S3)
+        self.tree.tag_configure("bad_chk",   foreground=RED)
+        self.tree.tag_configure("malformed", foreground=RED)
+
+        self.tree.bind("<<TreeviewSelect>>", self._on_tree_select)
+
+        # ── Right: detail notebook ────────────────────────────────────────
+        right = tk.Frame(pane, bg=BG)
+        pane.add(right, minsize=600)
+
+        style.configure("TNotebook",        background=BG2, borderwidth=0)
+        style.configure("TNotebook.Tab",    background=BG3, foreground=FG,
+                         font=MONO, padding=[8, 2])
+        style.map("TNotebook.Tab",          background=[("selected", BG)],
+                                            foreground=[("selected", ACCENT)])
+
+        self.nb = ttk.Notebook(right)
+        self.nb.pack(fill=tk.BOTH, expand=True)
+
+        # Tab: Inventory
+        self.inv_text = self._make_text_tab("Inventory")
+        # Tab: Hex Dump
+        self.hex_text = self._make_text_tab("Hex Dump")
+        # Tab: Diff
+        self.diff_text = self._make_text_tab("Diff")
+        # Tab: Full Report (raw text)
+        self.report_text = self._make_text_tab("Full Report")
+        # Tab: Query (DB)
+        self._build_query_tab()
+
+        # Tag colours for rich text in all tabs
+        for w in (self.inv_text, self.hex_text, self.diff_text, self.report_text):
+            w.tag_configure("head",    foreground=COL_HEAD, font=("Consolas", 9, "bold"))
+            w.tag_configure("bw",      foreground=COL_BW)
+            w.tag_configure("s3",      foreground=COL_S3)
+            w.tag_configure("changed", foreground=COL_DIFF)
+            w.tag_configure("known",   foreground=COL_KNOW)
+            w.tag_configure("dim",     foreground=FG_DIM)
+            w.tag_configure("normal",  foreground=FG)
+            w.tag_configure("warn",    foreground=YELLOW)
+            w.tag_configure("addr",    foreground=ORANGE)
+
+    def _make_text_tab(self, title: str) -> tk.Text:
+        frame = tk.Frame(self.nb, bg=BG)
+        self.nb.add(frame, text=title)
+        w = tk.Text(frame, bg=BG, fg=FG, font=MONO, state="disabled",
+                    relief="flat", wrap="none", insertbackground=FG,
+                    selectbackground=BG3, selectforeground="#ffffff")
+        vsb = ttk.Scrollbar(frame, orient="vertical", command=w.yview)
+        hsb = ttk.Scrollbar(frame, orient="horizontal", command=w.xview)
+        w.configure(yscrollcommand=vsb.set, xscrollcommand=hsb.set)
+        vsb.pack(side=tk.RIGHT, fill=tk.Y)
+        hsb.pack(side=tk.BOTTOM, fill=tk.X)
+        w.pack(fill=tk.BOTH, expand=True)
+        return w
+
+    def _build_query_tab(self) -> None:
+        """Build the Query tab: filter controls + results table + interpretation panel."""
+        frame = tk.Frame(self.nb, bg=BG)
+        self.nb.add(frame, text="Query DB")
+
+        # ── Filter row ────────────────────────────────────────────────────
+        filt = tk.Frame(frame, bg=BG2, pady=4)
+        filt.pack(side=tk.TOP, fill=tk.X)
+
+        pad = {"padx": 4, "pady": 2}
+
+        # Capture filter
+        tk.Label(filt, text="Capture:", bg=BG2, fg=FG, font=MONO_SM).grid(row=0, column=0, sticky="e", **pad)
+        self._q_capture_var = tk.StringVar(value="All")
+        self._q_capture_cb = ttk.Combobox(filt, textvariable=self._q_capture_var,
+                                           width=18, font=MONO_SM, state="readonly")
+        self._q_capture_cb.grid(row=0, column=1, sticky="w", **pad)
+
+        # Direction filter
+        tk.Label(filt, text="Dir:", bg=BG2, fg=FG, font=MONO_SM).grid(row=0, column=2, sticky="e", **pad)
+        self._q_dir_var = tk.StringVar(value="All")
+        self._q_dir_cb = ttk.Combobox(filt, textvariable=self._q_dir_var,
+                                       values=["All", "BW", "S3"],
+                                       width=6, font=MONO_SM, state="readonly")
+        self._q_dir_cb.grid(row=0, column=3, sticky="w", **pad)
+
+        # SUB filter
+        tk.Label(filt, text="SUB:", bg=BG2, fg=FG, font=MONO_SM).grid(row=0, column=4, sticky="e", **pad)
+        self._q_sub_var = tk.StringVar(value="All")
+        self._q_sub_cb = ttk.Combobox(filt, textvariable=self._q_sub_var,
+                                       width=12, font=MONO_SM, state="readonly")
+        self._q_sub_cb.grid(row=0, column=5, sticky="w", **pad)
+
+        # Byte offset filter
+        tk.Label(filt, text="Offset:", bg=BG2, fg=FG, font=MONO_SM).grid(row=0, column=6, sticky="e", **pad)
+        self._q_offset_var = tk.StringVar(value="")
+        tk.Entry(filt, textvariable=self._q_offset_var, width=8, bg=BG3, fg=FG,
+                 font=MONO_SM, insertbackground=FG, relief="flat").grid(row=0, column=7, sticky="w", **pad)
+
+        # Value filter
+        tk.Label(filt, text="Value:", bg=BG2, fg=FG, font=MONO_SM).grid(row=0, column=8, sticky="e", **pad)
+        self._q_value_var = tk.StringVar(value="")
+        tk.Entry(filt, textvariable=self._q_value_var, width=8, bg=BG3, fg=FG,
+                 font=MONO_SM, insertbackground=FG, relief="flat").grid(row=0, column=9, sticky="w", **pad)
+
+        # Run / Refresh buttons
+        tk.Button(filt, text="Run Query", bg=ACCENT, fg="#ffffff", relief="flat",
+                  padx=8, cursor="hand2", font=("Consolas", 8, "bold"),
+                  command=self._run_db_query).grid(row=0, column=10, padx=8)
+        tk.Button(filt, text="Refresh dropdowns", bg=BG3, fg=FG, relief="flat",
+                  padx=6, cursor="hand2", font=MONO_SM,
+                  command=self._refresh_query_dropdowns).grid(row=0, column=11, padx=4)
+
+        # DB stats label
+        self._q_stats_var = tk.StringVar(value="DB: —")
+        tk.Label(filt, textvariable=self._q_stats_var, bg=BG2, fg=FG_DIM,
+                 font=MONO_SM).grid(row=0, column=12, padx=12, sticky="w")
+
+        # ── Results table ─────────────────────────────────────────────────
+        res_frame = tk.Frame(frame, bg=BG)
+        res_frame.pack(side=tk.TOP, fill=tk.BOTH, expand=True)
+
+        # Results treeview
+        cols = ("cap", "sess", "dir", "sub", "sub_name", "page", "len", "chk")
+        self._q_tree = ttk.Treeview(res_frame, columns=cols,
+                                     show="headings", selectmode="browse")
+        col_cfg = [
+            ("cap",      "Cap",       40),
+            ("sess",     "Sess",      40),
+            ("dir",      "Dir",       40),
+            ("sub",      "SUB",       50),
+            ("sub_name", "Name",     160),
+            ("page",     "Page",      60),
+            ("len",      "Len",       50),
+            ("chk",      "Chk",       50),
+        ]
+        for cid, heading, width in col_cfg:
+            self._q_tree.heading(cid, text=heading, anchor="w")
+            self._q_tree.column(cid, width=width, stretch=(cid == "sub_name"))
+
+        q_vsb = ttk.Scrollbar(res_frame, orient="vertical",   command=self._q_tree.yview)
+        q_hsb = ttk.Scrollbar(res_frame, orient="horizontal",  command=self._q_tree.xview)
+        self._q_tree.configure(yscrollcommand=q_vsb.set, xscrollcommand=q_hsb.set)
+        q_vsb.pack(side=tk.RIGHT,  fill=tk.Y)
+        q_hsb.pack(side=tk.BOTTOM, fill=tk.X)
+        self._q_tree.pack(side=tk.LEFT, fill=tk.BOTH, expand=True)
+
+        self._q_tree.tag_configure("bw_row", foreground=COL_BW)
+        self._q_tree.tag_configure("s3_row", foreground=COL_S3)
+        self._q_tree.tag_configure("bad_row", foreground=RED)
+
+        # ── Interpretation panel (below results) ──────────────────────────
+        interp_frame = tk.Frame(frame, bg=BG2, height=120)
+        interp_frame.pack(side=tk.BOTTOM, fill=tk.X)
+        interp_frame.pack_propagate(False)
+
+        tk.Label(interp_frame, text="Byte interpretation (click a row, enter offset):",
+                 bg=BG2, fg=ACCENT, font=MONO_SM, anchor="w", padx=6).pack(fill=tk.X)
+
+        interp_inner = tk.Frame(interp_frame, bg=BG2)
+        interp_inner.pack(fill=tk.X, padx=6, pady=2)
+
+        tk.Label(interp_inner, text="Offset:", bg=BG2, fg=FG, font=MONO_SM).pack(side=tk.LEFT)
+        self._interp_offset_var = tk.StringVar(value="5")
+        tk.Entry(interp_inner, textvariable=self._interp_offset_var,
+                 width=6, bg=BG3, fg=FG, font=MONO_SM,
+                 insertbackground=FG, relief="flat").pack(side=tk.LEFT, padx=4)
+        tk.Button(interp_inner, text="Interpret", bg=BG3, fg=FG, relief="flat",
+                  cursor="hand2", font=MONO_SM,
+                  command=self._run_interpret).pack(side=tk.LEFT, padx=4)
+
+        self._interp_text = tk.Text(interp_frame, bg=BG2, fg=FG, font=MONO_SM,
+                                     height=4, relief="flat", state="disabled",
+                                     insertbackground=FG)
+        self._interp_text.pack(fill=tk.X, padx=6, pady=2)
+        self._interp_text.tag_configure("label", foreground=FG_DIM)
+        self._interp_text.tag_configure("value", foreground=YELLOW)
+
+        # Store frame rows by tree iid -> db row
+        self._q_rows: dict[str, object] = {}
+        self._q_capture_rows: list = [None]
+        self._q_sub_values:   list = [None]
+        self._q_tree.bind("<<TreeviewSelect>>", self._on_q_select)
+
+        # Init dropdowns
+        self._refresh_query_dropdowns()
+
+    def _refresh_query_dropdowns(self) -> None:
+        """Reload capture and SUB dropdowns from the DB."""
+        try:
+            captures = self._db.list_captures()
+            cap_labels = ["All"] + [
+                f"#{r['id']} {r['timestamp'][:16]} ({r['frame_count']} frames)"
+                for r in captures
+            ]
+            self._q_capture_cb["values"] = cap_labels
+            self._q_capture_rows = [None] + [r["id"] for r in captures]
+
+            subs = self._db.get_distinct_subs()
+            sub_labels = ["All"] + [f"0x{s:02X}" for s in subs]
+            self._q_sub_cb["values"] = sub_labels
+            self._q_sub_values = [None] + subs
+
+            stats = self._db.get_stats()
+            self._q_stats_var.set(
+                f"DB: {stats['captures']} captures | {stats['frames']} frames"
+            )
+        except Exception as exc:
+            self._q_stats_var.set(f"DB error: {exc}")
+
+    def _parse_hex_or_int(self, s: str) -> Optional[int]:
+        """Parse '0x1F', '31', or '' into int or None."""
+        s = s.strip()
+        if not s:
+            return None
+        try:
+            return int(s, 0)
+        except ValueError:
+            return None
+
+    def _run_db_query(self) -> None:
+        """Execute query with current filter values and populate results tree."""
+        # Resolve capture_id
+        cap_idx = self._q_capture_cb.current()
+        cap_id  = self._q_capture_rows[cap_idx] if cap_idx > 0 else None
+
+        # Direction
+        dir_val = self._q_dir_var.get()
+        direction = dir_val if dir_val != "All" else None
+
+        # SUB
+        sub_idx = self._q_sub_cb.current()
+        sub = self._q_sub_values[sub_idx] if sub_idx > 0 else None
+
+        # Offset / value
+        offset = self._parse_hex_or_int(self._q_offset_var.get())
+        value  = self._parse_hex_or_int(self._q_value_var.get())
+
+        try:
+            if offset is not None:
+                rows = self._db.query_by_byte(
+                    offset=offset, value=value,
+                    capture_id=cap_id, direction=direction, sub=sub
+                )
+            else:
+                rows = self._db.query_frames(
+                    capture_id=cap_id, direction=direction, sub=sub
+                )
+        except Exception as exc:
+            messagebox.showerror("Query error", str(exc))
+            return
+
+        # Populate tree
+        self._q_tree.delete(*self._q_tree.get_children())
+        self._q_rows.clear()
+
+        for row in rows:
+            sub_hex  = f"0x{row['sub']:02X}"  if row["sub"]  is not None else "—"
+            page_hex = f"0x{row['page_key']:04X}" if row["page_key"] is not None else "—"
+            chk_str  = {1: "OK", 0: "BAD", None: "—"}.get(row["checksum_ok"], "—")
+            tag = "bw_row" if row["direction"] == "BW" else "s3_row"
+            if row["checksum_ok"] == 0:
+                tag = "bad_row"
+
+            iid = str(row["id"])
+            self._q_tree.insert("", tk.END, iid=iid, tags=(tag,), values=(
+                row["capture_id"],
+                row["session_idx"],
+                row["direction"],
+                sub_hex,
+                row["sub_name"] or "",
+                page_hex,
+                row["payload_len"],
+                chk_str,
+            ))
+            self._q_rows[iid] = row
+
+        self.sb_var.set(f"Query returned {len(rows)} rows")
+
+    def _on_q_select(self, _event: tk.Event) -> None:
+        """When a DB result row is selected, auto-run interpret at current offset."""
+        self._run_interpret()
+
+    def _run_interpret(self) -> None:
+        """Show multi-format byte interpretation for the selected row + offset."""
+        sel = self._q_tree.selection()
+        if not sel:
+            return
+        iid = sel[0]
+        row = self._q_rows.get(iid)
+        if row is None:
+            return
+
+        offset = self._parse_hex_or_int(self._interp_offset_var.get())
+        if offset is None:
+            return
+
+        payload = bytes(row["payload"])
+        interp  = self._db.interpret_offset(payload, offset)
+
+        w = self._interp_text
+        w.configure(state="normal")
+        w.delete("1.0", tk.END)
+
+        sub_hex  = f"0x{row['sub']:02X}" if row["sub"] is not None else "??"
+        w.insert(tk.END, f"Frame #{row['id']}  [{row['direction']}]  SUB={sub_hex}  "
+                         f"offset={offset} (0x{offset:04X})\n", "label")
+
+        label_order = [
+            ("uint8",      "uint8      "),
+            ("int8",       "int8       "),
+            ("uint16_be",  "uint16 BE  "),
+            ("uint16_le",  "uint16 LE  "),
+            ("uint32_be",  "uint32 BE  "),
+            ("uint32_le",  "uint32 LE  "),
+            ("float32_be", "float32 BE "),
+            ("float32_le", "float32 LE "),
+        ]
+        line = ""
+        for key, label in label_order:
+            if key in interp:
+                val = interp[key]
+                if isinstance(val, float):
+                    val_str = f"{val:.6g}"
+                else:
+                    val_str = str(val)
+                    if key.startswith("uint") or key.startswith("int"):
+                        val_str += f"  (0x{int(val) & 0xFFFFFFFF:X})"
+                chunk = f"{label}: {val_str}"
+                line += f"  {chunk:<30}"
+                if len(line) > 80:
+                    w.insert(tk.END, line + "\n", "value")
+                    line = ""
+        if line:
+            w.insert(tk.END, line + "\n", "value")
+
+        w.configure(state="disabled")
+
+    def _build_statusbar(self) -> None:
+        bar = tk.Frame(self, bg=BG3, height=20)
+        bar.pack(side=tk.BOTTOM, fill=tk.X)
+        self.sb_var = tk.StringVar(value="Ready")
+        tk.Label(bar, textvariable=self.sb_var, bg=BG3, fg=FG_DIM,
+                 font=MONO_SM, anchor="w", padx=6).pack(fill=tk.X)
+
+    # ── file picking ───────────────────────────────────────────────────────
+
+    def _browse_file(self, var: tk.StringVar, default_name: str) -> None:
+        path = filedialog.askopenfilename(
+            title=f"Select {default_name}",
+            filetypes=[("Binary files", "*.bin"), ("All files", "*.*")],
+            initialfile=default_name,
+        )
+        if path:
+            var.set(path)
+
+    # ── analysis ──────────────────────────────────────────────────────────
+
+    def _run_analyze(self) -> None:
+        s3_path = Path(self.s3_var.get().strip()) if self.s3_var.get().strip() else None
+        bw_path = Path(self.bw_var.get().strip()) if self.bw_var.get().strip() else None
+
+        if not s3_path or not bw_path:
+            messagebox.showerror("Missing files", "Please select both S3 and BW raw files.")
+            return
+        if not s3_path.exists():
+            messagebox.showerror("File not found", f"S3 file not found:\n{s3_path}")
+            return
+        if not bw_path.exists():
+            messagebox.showerror("File not found", f"BW file not found:\n{bw_path}")
+            return
+
+        self.state.s3_path = s3_path
+        self.state.bw_path = bw_path
+        self._do_analyze(s3_path, bw_path)
+
+    def _run_export(self) -> None:
+        if not self.state.sessions:
+            messagebox.showinfo("Export", "Run Analyze first.")
+            return
+
+        outdir = self.state.s3_path.parent if self.state.s3_path else Path(".")
+        out_path = write_claude_export(
+            self.state.sessions,
+            self.state.diffs,
+            outdir,
+            self.state.s3_path,
+            self.state.bw_path,
+        )
+
+        self.sb_var.set(f"Exported: {out_path.name}")
+        if messagebox.askyesno(
+            "Export complete",
+            f"Saved to:\n{out_path}\n\nOpen the folder?",
+        ):
+            import subprocess
+            subprocess.Popen(["explorer", str(out_path.parent)])
+
+    def _do_analyze(self, s3_path: Path, bw_path: Path) -> None:
+        self.status_var.set("Parsing...")
+        self.update_idletasks()
+
+        s3_blob = s3_path.read_bytes()
+        bw_blob = bw_path.read_bytes()
+
+        s3_frames = annotate_frames(parse_s3(s3_blob, trailer_len=0), "S3")
+        bw_frames = annotate_frames(parse_bw(bw_blob, trailer_len=0, validate_checksum=True), "BW")
+
+        sessions = split_into_sessions(bw_frames, s3_frames)
+
+        diffs: list[Optional[list[FrameDiff]]] = [None]
+        for i in range(1, len(sessions)):
+            diffs.append(diff_sessions(sessions[i - 1], sessions[i]))
+
+        self.state.sessions = sessions
+        self.state.diffs = diffs
+
+        n_s3 = sum(len(s.s3_frames) for s in sessions)
+        n_bw = sum(len(s.bw_frames) for s in sessions)
+        self.status_var.set(
+            f"{len(sessions)} sessions  |  BW: {n_bw} frames  S3: {n_s3} frames"
+        )
+        self.sb_var.set(f"Loaded: {s3_path.name} + {bw_path.name}")
+
+        self.export_btn.configure(state="normal")
+        self._rebuild_tree()
+
+        # Auto-ingest into DB (deduped by SHA256 — fast no-op on re-analyze)
+        try:
+            cap_id = self._db.ingest(sessions, s3_path, bw_path)
+            if cap_id is not None:
+                self.state.last_capture_id = cap_id
+                self._refresh_query_dropdowns()
+                # Pre-select this capture in the Query tab
+                cap_labels = list(self._q_capture_cb["values"])
+                # Find label that starts with #<cap_id>
+                for i, lbl in enumerate(cap_labels):
+                    if lbl.startswith(f"#{cap_id} "):
+                        self._q_capture_cb.current(i)
+                        break
+            # else: already ingested — no change to dropdown selection
+        except Exception as exc:
+            self.sb_var.set(f"DB ingest error: {exc}")
+
+    # ── tree building ──────────────────────────────────────────────────────
+
+    def _rebuild_tree(self) -> None:
+        self.tree.delete(*self.tree.get_children())
+
+        for sess in self.state.sessions:
+            is_complete = any(
+                af.header is not None and af.header.sub == 0x74
+                for af in sess.bw_frames
+            )
+            label = f"Session {sess.index}"
+            if not is_complete:
+                label += " [partial]"
+            n_diff = len(self.state.diffs[sess.index] or [])
+            diff_info = f"{n_diff} changes" if n_diff > 0 else ""
+            sess_id = self.tree.insert("", tk.END, text=label,
+                                       values=(diff_info,), tags=("session",))
+
+            for af in sess.all_frames:
+                src_tag = "bw_frame" if af.source == "BW" else "s3_frame"
+                sub_hex = f"{af.header.sub:02X}" if af.header else "??"
+                label_text = f"[{af.source}] {sub_hex} {af.sub_name}"
+                extra = ""
+                tags = (src_tag,)
+                if af.frame.checksum_valid is False:
+                    extra = "BAD CHK"
+                    tags = ("bad_chk",)
+                elif af.header is None:
+                    tags = ("malformed",)
+                    label_text = f"[{af.source}] MALFORMED"
+                self.tree.insert(sess_id, tk.END, text=label_text,
+                                 values=(extra,), tags=tags,
+                                 iid=f"frame_{sess.index}_{af.frame.index}_{af.source}")
+
+        # Expand all sessions
+        for item in self.tree.get_children():
+            self.tree.item(item, open=True)
+
+    # ── tree selection → detail panel ─────────────────────────────────────
+
+    def _on_tree_select(self, _event: tk.Event) -> None:
+        sel = self.tree.selection()
+        if not sel:
+            return
+        iid = sel[0]
+
+        # Determine if it's a session node or a frame node
+        if iid.startswith("frame_"):
+            # frame_<sessidx>_<frameidx>_<source>
+            parts = iid.split("_")
+            sess_idx = int(parts[1])
+            frame_idx = int(parts[2])
+            source = parts[3]
+            self._show_frame_detail(sess_idx, frame_idx, source)
+        else:
+            # Session node — show session summary
+            # Find session index from text
+            text = self.tree.item(iid, "text")
+            try:
+                idx = int(text.split()[1])
+                self._show_session_detail(idx)
+            except (IndexError, ValueError):
+                pass
+
+    def _find_frame(self, sess_idx: int, frame_idx: int, source: str) -> Optional[AnnotatedFrame]:
+        if sess_idx >= len(self.state.sessions):
+            return None
+        sess = self.state.sessions[sess_idx]
+        pool = sess.bw_frames if source == "BW" else sess.s3_frames
+        for af in pool:
+            if af.frame.index == frame_idx:
+                return af
+        return None
+
+    # ── detail renderers ──────────────────────────────────────────────────
+
+    def _clear_all_tabs(self) -> None:
+        for w in (self.inv_text, self.hex_text, self.diff_text, self.report_text):
+            self._text_clear(w)
+
+    def _show_session_detail(self, sess_idx: int) -> None:
+        if sess_idx >= len(self.state.sessions):
+            return
+        sess = self.state.sessions[sess_idx]
+        diffs = self.state.diffs[sess_idx]
+
+        self._clear_all_tabs()
+
+        # ── Inventory tab ────────────────────────────────────────────────
+        w = self.inv_text
+        self._text_clear(w)
+        self._tw(w, f"SESSION {sess.index}", "head"); self._tn(w)
+        n_bw, n_s3 = len(sess.bw_frames), len(sess.s3_frames)
+        self._tw(w, f"Frames: {n_bw + n_s3}  (BW: {n_bw}, S3: {n_s3})\n", "normal")
+        if n_bw != n_s3:
+            self._tw(w, "  WARNING: BW/S3 count mismatch\n", "warn")
+        self._tn(w)
+
+        for seq_i, af in enumerate(sess.all_frames):
+            src_tag = "bw" if af.source == "BW" else "s3"
+            sub_hex = f"{af.header.sub:02X}" if af.header else "??"
+            page_str = f" (page {af.header.page_key:04X})" if af.header and af.header.page_key != 0 else ""
+            chk = ""
+            if af.frame.checksum_valid is False:
+                chk = "  [BAD CHECKSUM]"
+            elif af.frame.checksum_valid is True:
+                chk = f"  [{af.frame.checksum_type}]"
+            self._tw(w, f"  [{af.source}] #{seq_i:<3}  ", src_tag)
+            self._tw(w, f"SUB={sub_hex}  ", "addr")
+            self._tw(w, f"{af.sub_name:<30}", src_tag)
+            self._tw(w, f"{page_str}  len={len(af.frame.payload)}", "dim")
+            if chk:
+                self._tw(w, chk, "warn" if af.frame.checksum_valid is False else "dim")
+            self._tn(w)
+
+        # ── Diff tab ─────────────────────────────────────────────────────
+        w = self.diff_text
+        self._text_clear(w)
+        if diffs is None:
+            self._tw(w, "(No previous session to diff against)\n", "dim")
+        elif not diffs:
+            self._tw(w, f"DIFF vs SESSION {sess_idx - 1}\n", "head"); self._tn(w)
+            self._tw(w, "  No changes detected.\n", "dim")
+        else:
+            self._tw(w, f"DIFF vs SESSION {sess_idx - 1}\n", "head"); self._tn(w)
+            for fd in diffs:
+                page_str = f" (page {fd.page_key:04X})" if fd.page_key != 0 else ""
+                self._tw(w, f"\n  SUB {fd.sub:02X} ({fd.sub_name}){page_str}:\n", "addr")
+                for bd in fd.diffs:
+                    before_s = f"{bd.before:02x}" if bd.before >= 0 else "--"
+                    after_s  = f"{bd.after:02x}"  if bd.after  >= 0 else "--"
+                    self._tw(w, f"    [{bd.payload_offset:3d}]  0x{bd.payload_offset:04X}:  ", "dim")
+                    self._tw(w, f"{before_s} -> {after_s}", "changed")
+                    if bd.field_name:
+                        self._tw(w, f"  [{bd.field_name}]", "known")
+                    self._tn(w)
+
+        # ── Full Report tab ───────────────────────────────────────────────
+        report_text = render_session_report(sess, diffs, sess_idx - 1 if sess_idx > 0 else None)
+        w = self.report_text
+        self._text_clear(w)
+        self._tw(w, report_text, "normal")
+
+        # Switch to Inventory tab
+        self.nb.select(0)
+
+    def _show_frame_detail(self, sess_idx: int, frame_idx: int, source: str) -> None:
+        af = self._find_frame(sess_idx, frame_idx, source)
+        if af is None:
+            return
+
+        self._clear_all_tabs()
+        src_tag = "bw" if source == "BW" else "s3"
+        sub_hex = f"{af.header.sub:02X}" if af.header else "??"
+
+        # ── Inventory tab — single frame summary ─────────────────────────
+        w = self.inv_text
+        self._tw(w, f"[{af.source}] Frame #{af.frame.index}\n", src_tag)
+        self._tw(w, f"Session {sess_idx}  |  ", "dim")
+        self._tw(w, f"SUB={sub_hex}  {af.sub_name}\n", "addr")
+        if af.header:
+            self._tw(w, f"  OFFSET: {af.header.page_key:04X}  ", "dim")
+            self._tw(w, f"CMD={af.header.cmd:02X}  FLAGS={af.header.flags:02X}\n", "dim")
+        self._tn(w)
+        self._tw(w, f"Payload bytes: {len(af.frame.payload)}\n", "dim")
+        if af.frame.checksum_valid is False:
+            self._tw(w, "  BAD CHECKSUM\n", "warn")
+        elif af.frame.checksum_valid is True:
+            self._tw(w, f"  Checksum: {af.frame.checksum_type}  {af.frame.checksum_hex}\n", "dim")
+        self._tn(w)
+
+        # Protocol header breakdown
+        p = af.frame.payload
+        if len(p) >= 5:
+            self._tw(w, "Header breakdown:\n", "head")
+            self._tw(w, f"  [0] CMD        = {p[0]:02x}\n", "dim")
+            self._tw(w, f"  [1] ?          = {p[1]:02x}\n", "dim")
+            self._tw(w, f"  [2] SUB        = {p[2]:02x}  ({af.sub_name})\n", src_tag)
+            self._tw(w, f"  [3] OFFSET_HI  = {p[3]:02x}\n", "dim")
+            self._tw(w, f"  [4] OFFSET_LO  = {p[4]:02x}\n", "dim")
+            if len(p) > 5:
+                self._tw(w, f"  [5..] data     = {len(p) - 5} bytes\n", "dim")
+
+        # ── Hex Dump tab ─────────────────────────────────────────────────
+        w = self.hex_text
+        self._tw(w, f"[{af.source}] SUB={sub_hex}  {af.sub_name}\n", src_tag)
+        self._tw(w, f"Payload ({len(af.frame.payload)} bytes):\n", "dim")
+        self._tn(w)
+        dump_lines = format_hex_dump(af.frame.payload, indent="  ")
+        self._tw(w, "\n".join(dump_lines) + "\n", "normal")
+
+        # Annotate known field offsets within this frame
+        diffs_for_sess = self.state.diffs[sess_idx] if sess_idx < len(self.state.diffs) else None
+        if diffs_for_sess and af.header:
+            page_key = af.header.page_key
+            matching = [fd for fd in diffs_for_sess
+                        if fd.sub == af.header.sub and fd.page_key == page_key]
+            if matching:
+                self._tn(w)
+                self._tw(w, "Changed bytes in this frame (vs prev session):\n", "head")
+                for bd in matching[0].diffs:
+                    before_s = f"{bd.before:02x}" if bd.before >= 0 else "--"
+                    after_s  = f"{bd.after:02x}"  if bd.after  >= 0 else "--"
+                    self._tw(w, f"  [{bd.payload_offset:3d}] 0x{bd.payload_offset:04X}: ", "dim")
+                    self._tw(w, f"{before_s} -> {after_s}", "changed")
+                    if bd.field_name:
+                        self._tw(w, f"  [{bd.field_name}]", "known")
+                    self._tn(w)
+
+        # Switch to Hex Dump tab for frame selection
+        self.nb.select(1)
+
+    # ── live mode ─────────────────────────────────────────────────────────
+
+    def _toggle_live(self) -> None:
+        if self._live_thread and self._live_thread.is_alive():
+            self._live_stop.set()
+            self.live_btn.configure(text="Live: OFF", bg=BG3, fg=FG)
+            self.status_var.set("Live stopped")
+        else:
+            s3_path = Path(self.s3_var.get().strip()) if self.s3_var.get().strip() else None
+            bw_path = Path(self.bw_var.get().strip()) if self.bw_var.get().strip() else None
+            if not s3_path or not bw_path:
+                messagebox.showerror("Missing files", "Select both raw files before starting live mode.")
+                return
+            self.state.s3_path = s3_path
+            self.state.bw_path = bw_path
+            self._live_stop.clear()
+            self._live_thread = threading.Thread(
+                target=self._live_worker, args=(s3_path, bw_path), daemon=True)
+            self._live_thread.start()
+            self.live_btn.configure(text="Live: ON", bg=GREEN, fg="#000000")
+            self.status_var.set("Live mode running...")
+
+    def _live_worker(self, s3_path: Path, bw_path: Path) -> None:
+        s3_buf = bytearray()
+        bw_buf = bytearray()
+        s3_pos = bw_pos = 0
+
+        while not self._live_stop.is_set():
+            changed = False
+            if s3_path.exists():
+                with s3_path.open("rb") as fh:
+                    fh.seek(s3_pos)
+                    nb = fh.read()
+                if nb:
+                    s3_buf.extend(nb); s3_pos += len(nb); changed = True
+            if bw_path.exists():
+                with bw_path.open("rb") as fh:
+                    fh.seek(bw_pos)
+                    nb = fh.read()
+                if nb:
+                    bw_buf.extend(nb); bw_pos += len(nb); changed = True
+
+            if changed:
+                self._live_q.put("refresh")
+
+            time.sleep(0.1)
+
+    def _poll_live_queue(self) -> None:
+        try:
+            while True:
+                msg = self._live_q.get_nowait()
+                if msg == "refresh" and self.state.s3_path and self.state.bw_path:
+                    self._do_analyze(self.state.s3_path, self.state.bw_path)
+        except queue.Empty:
+            pass
+        finally:
+            self.after(150, self._poll_live_queue)
+
+    # ── text helpers ──────────────────────────────────────────────────────
+
+    def _text_clear(self, w: tk.Text) -> None:
+        w.configure(state="normal")
+        w.delete("1.0", tk.END)
+        # leave enabled for further inserts
+
+    def _tw(self, w: tk.Text, text: str, tag: str = "normal") -> None:
+        """Insert text with a colour tag."""
+        w.configure(state="normal")
+        w.insert(tk.END, text, tag)
+
+    def _tn(self, w: tk.Text) -> None:
+        """Insert newline."""
+        w.configure(state="normal")
+        w.insert(tk.END, "\n")
+        w.configure(state="disabled")
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Entry point
+# ──────────────────────────────────────────────────────────────────────────────
+
+def main() -> None:
+    app = AnalyzerGUI()
+    app.mainloop()
+
+
+if __name__ == "__main__":
+    main()

parsers/s3_parser.py

@@ -0,0 +1,431 @@
+#!/usr/bin/env python3
+"""
+s3_parser.py — Unified Instantel frame parser (S3 + BW).
+
+Modes:
+- s3: DLE STX (10 02) ... DLE ETX (10 03)
+- bw: ACK+STX (41 02) ... ETX (03)
+
+Stuffing:
+- Literal 0x10 in payload is stuffed as 10 10 in both directions.
+
+Checksums:
+- BW frames appear to use more than one checksum style depending on message type.
+  Small frames often validate with 1-byte SUM8.
+  Large config/write frames appear to use a 2-byte CRC16 variant.
+
+In BW mode we therefore validate candidate ETX positions using AUTO checksum matching:
+- SUM8 (1 byte)
+- CRC16 variants (2 bytes), both little/big endian
+If any match, we accept the ETX as a real frame terminator.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Tuple
+
+DLE = 0x10
+STX = 0x02
+ETX = 0x03
+ACK = 0x41
+
+__version__ = "0.2.3"
+
+
+@dataclass
+class Frame:
+    index: int
+    start_offset: int
+    end_offset: int
+    payload_raw: bytes     # de-stuffed bytes between STX..ETX (includes checksum bytes at end)
+    payload: bytes         # payload without checksum bytes
+    trailer: bytes
+    checksum_valid: Optional[bool]
+    checksum_type: Optional[str]
+    checksum_hex: Optional[str]
+
+
+# ------------------------
+# Checksum / CRC helpers
+# ------------------------
+
+def checksum8_sum(data: bytes) -> int:
+    """SUM8: sum(payload) & 0xFF"""
+    return sum(data) & 0xFF
+
+
+def crc16_ibm(data: bytes) -> int:
+    # CRC-16/IBM (aka ARC) poly=0xA001, init=0x0000, refin/refout true
+    crc = 0x0000
+    for b in data:
+        crc ^= b
+        for _ in range(8):
+            crc = (crc >> 1) ^ 0xA001 if (crc & 1) else (crc >> 1)
+    return crc & 0xFFFF
+
+
+def crc16_ccitt_false(data: bytes) -> int:
+    # CRC-16/CCITT-FALSE poly=0x1021, init=0xFFFF, refin/refout false
+    crc = 0xFFFF
+    for b in data:
+        crc ^= (b << 8)
+        for _ in range(8):
+            crc = ((crc << 1) ^ 0x1021) & 0xFFFF if (crc & 0x8000) else (crc << 1) & 0xFFFF
+    return crc
+
+
+def crc16_x25(data: bytes) -> int:
+    # CRC-16/X-25 poly=0x8408 (reflected), init=0xFFFF, xorout=0xFFFF
+    crc = 0xFFFF
+    for b in data:
+        crc ^= b
+        for _ in range(8):
+            crc = (crc >> 1) ^ 0x8408 if (crc & 1) else (crc >> 1)
+    return (crc ^ 0xFFFF) & 0xFFFF
+
+
+CRC16_FUNCS: Dict[str, Callable[[bytes], int]] = {
+    "CRC16_IBM": crc16_ibm,
+    "CRC16_CCITT_FALSE": crc16_ccitt_false,
+    "CRC16_X25": crc16_x25,
+}
+
+
+def _try_validate_sum8(body: bytes) -> Optional[Tuple[bytes, bytes, str]]:
+    """
+    body = payload + chk8
+    Returns (payload, chk_bytes, type) if valid, else None
+    """
+    if len(body) < 1:
+        return None
+    payload = body[:-1]
+    chk = body[-1]
+    if checksum8_sum(payload) == chk:
+        return payload, bytes([chk]), "SUM8"
+    return None
+
+
+def _try_validate_sum8_large(body: bytes) -> Optional[Tuple[bytes, bytes, str]]:
+    """
+    Large BW->S3 write frame checksum (SUBs 68, 69, 71, 82, 1A with data).
+
+    Formula: (sum(b for b in payload[2:-1] if b != 0x10) + 0x10) & 0xFF
+    - Starts from byte [2], skipping CMD (0x10) and DLE (0x10) at [0][1]
+    - Skips all 0x10 bytes in the covered range
+    - Adds 0x10 as a constant offset
+    - body[-1] is the checksum byte
+
+    Confirmed across 20 frames from two independent captures (2026-03-12).
+    """
+    if len(body) < 3:
+        return None
+    payload = body[:-1]
+    chk = body[-1]
+    calc = (sum(b for b in payload[2:] if b != 0x10) + 0x10) & 0xFF
+    if calc == chk:
+        return payload, bytes([chk]), "SUM8_LARGE"
+    return None
+
+
+def _try_validate_crc16(body: bytes) -> Optional[Tuple[bytes, bytes, str]]:
+    """
+    body = payload + crc16(2 bytes)
+    Try multiple CRC16 types and both endian interpretations.
+    Returns (payload, chk_bytes, type) if valid, else None
+    """
+    if len(body) < 2:
+        return None
+    payload = body[:-2]
+    chk_bytes = body[-2:]
+
+    given_le = int.from_bytes(chk_bytes, "little", signed=False)
+    given_be = int.from_bytes(chk_bytes, "big", signed=False)
+
+    for name, fn in CRC16_FUNCS.items():
+        calc = fn(payload)
+        if calc == given_le:
+            return payload, chk_bytes, f"{name}_LE"
+        if calc == given_be:
+            return payload, chk_bytes, f"{name}_BE"
+    return None
+
+
+def validate_bw_body_auto(body: bytes) -> Optional[Tuple[bytes, bytes, str]]:
+    """
+    Try to interpret the tail of body as a checksum in several ways.
+    Return (payload, checksum_bytes, checksum_type) if any match; else None.
+    """
+    # Prefer plain SUM8 first (small frames: POLL, read commands)
+    hit = _try_validate_sum8(body)
+    if hit:
+        return hit
+
+    # Large BW->S3 write frames (SUBs 68, 69, 71, 82, 1A with data)
+    hit = _try_validate_sum8_large(body)
+    if hit:
+        return hit
+
+    # Then CRC16 variants
+    hit = _try_validate_crc16(body)
+    if hit:
+        return hit
+
+    return None
+
+
+# ------------------------
+# S3 MODE (DLE framed)
+# ------------------------
+
+def parse_s3(blob: bytes, trailer_len: int) -> List[Frame]:
+    frames: List[Frame] = []
+
+    IDLE = 0
+    IN_FRAME = 1
+    AFTER_DLE = 2
+
+    state = IDLE
+    body = bytearray()
+    start_offset = 0
+    idx = 0
+
+    i = 0
+    n = len(blob)
+
+    while i < n:
+        b = blob[i]
+
+        if state == IDLE:
+            if b == DLE and i + 1 < n and blob[i + 1] == STX:
+                start_offset = i
+                body.clear()
+                state = IN_FRAME
+                i += 2
+                continue
+
+        elif state == IN_FRAME:
+            if b == DLE:
+                state = AFTER_DLE
+                i += 1
+                continue
+            body.append(b)
+
+        else:  # AFTER_DLE
+            if b == DLE:
+                body.append(DLE)
+                state = IN_FRAME
+                i += 1
+                continue
+
+            if b == ETX:
+                end_offset = i + 1
+                trailer_start = i + 1
+                trailer_end = trailer_start + trailer_len
+                trailer = blob[trailer_start:trailer_end]
+
+                chk_valid = None
+                chk_type = None
+                chk_hex = None
+                payload = bytes(body)
+
+                if len(body) >= 1:
+                    received_chk = body[-1]
+                    computed_chk = checksum8_sum(bytes(body[:-1]))
+                    if computed_chk == received_chk:
+                        chk_valid = True
+                        chk_type = "SUM8"
+                        chk_hex = f"{received_chk:02x}"
+                        payload = bytes(body[:-1])
+                    else:
+                        chk_valid = False
+
+                frames.append(Frame(
+                    index=idx,
+                    start_offset=start_offset,
+                    end_offset=end_offset,
+                    payload_raw=bytes(body),
+                    payload=payload,
+                    trailer=trailer,
+                    checksum_valid=chk_valid,
+                    checksum_type=chk_type,
+                    checksum_hex=chk_hex
+                ))
+
+                idx += 1
+                state = IDLE
+                i = trailer_end
+                continue
+
+            # Unexpected DLE + byte → treat as literal data
+            body.append(DLE)
+            body.append(b)
+            state = IN_FRAME
+            i += 1
+            continue
+
+        i += 1
+
+    return frames
+
+
+# ------------------------
+# BW MODE (ACK+STX framed, bare ETX)
+# ------------------------
+
+def parse_bw(blob: bytes, trailer_len: int, validate_checksum: bool) -> List[Frame]:
+    frames: List[Frame] = []
+
+    IDLE = 0
+    IN_FRAME = 1
+    AFTER_DLE = 2
+
+    state = IDLE
+    body = bytearray()
+    start_offset = 0
+    idx = 0
+
+    i = 0
+    n = len(blob)
+
+    while i < n:
+        b = blob[i]
+
+        if state == IDLE:
+            # Frame start signature: ACK + STX
+            if b == ACK and i + 1 < n and blob[i + 1] == STX:
+                start_offset = i
+                body.clear()
+                state = IN_FRAME
+                i += 2
+                continue
+            i += 1
+            continue
+
+        if state == IN_FRAME:
+            if b == DLE:
+                state = AFTER_DLE
+                i += 1
+                continue
+
+            if b == ETX:
+                # Candidate end-of-frame.
+                # Skip any SESSION_RESET (41 03) sequences — sent before POLL to wake
+                # monitoring units — to find the real next frame start (ACK+STX).
+                j = i + 1
+                while j + 1 < n and blob[j] == ACK and blob[j + 1] == ETX:
+                    j += 2
+                next_is_start = (j + 1 < n and blob[j] == ACK and blob[j + 1] == STX)
+                at_eof = (i == n - 1) or (j >= n)
+
+                if not (next_is_start or at_eof):
+                    # Not a real boundary -> payload byte
+                    body.append(ETX)
+                    i += 1
+                    continue
+
+                trailer_start = i + 1
+                trailer_end = trailer_start + trailer_len
+                trailer = blob[trailer_start:trailer_end]
+
+                chk_valid = None
+                chk_type = None
+                chk_hex = None
+                payload = bytes(body)
+
+                if validate_checksum:
+                    hit = validate_bw_body_auto(payload)
+                    if hit:
+                        payload, chk_bytes, chk_type = hit
+                        chk_valid = True
+                        chk_hex = chk_bytes.hex()
+                    else:
+                        chk_valid = False
+
+                frames.append(Frame(
+                    index=idx,
+                    start_offset=start_offset,
+                    end_offset=i + 1,
+                    payload_raw=bytes(body),
+                    payload=payload,
+                    trailer=trailer,
+                    checksum_valid=chk_valid,
+                    checksum_type=chk_type,
+                    checksum_hex=chk_hex
+                ))
+                idx += 1
+                state = IDLE
+                i = trailer_end
+                continue
+
+            # Normal byte
+            body.append(b)
+            i += 1
+            continue
+
+        # AFTER_DLE: DLE XX => literal XX for any XX (full DLE stuffing)
+        body.append(b)
+        state = IN_FRAME
+        i += 1
+
+    return frames
+
+
+# ------------------------
+# CLI
+# ------------------------
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Parse Instantel S3/BW binary captures.")
+    ap.add_argument("binfile", type=Path)
+    ap.add_argument("--mode", choices=["s3", "bw"], default="s3")
+    ap.add_argument("--trailer-len", type=int, default=0)
+    ap.add_argument("--no-checksum", action="store_true")
+    ap.add_argument("--out", type=Path, default=None)
+
+    args = ap.parse_args()
+
+    print(f"s3_parser v{__version__}")
+
+    blob = args.binfile.read_bytes()
+
+    if args.mode == "s3":
+        frames = parse_s3(blob, args.trailer_len)
+    else:
+        frames = parse_bw(blob, args.trailer_len, validate_checksum=not args.no_checksum)
+
+    print("Frames found:", len(frames))
+
+    def to_hex(b: bytes) -> str:
+        return b.hex()
+
+    lines = []
+    for f in frames:
+        obj = {
+            "index": f.index,
+            "start_offset": f.start_offset,
+            "end_offset": f.end_offset,
+            "payload_len": len(f.payload),
+            "payload_hex": to_hex(f.payload),
+            "trailer_hex": to_hex(f.trailer),
+            "checksum_valid": f.checksum_valid,
+            "checksum_type": f.checksum_type,
+            "checksum_hex": f.checksum_hex,
+        }
+        lines.append(json.dumps(obj))
+
+    if args.out:
+        args.out.write_text("\n".join(lines) + "\n", encoding="utf-8")
+        print(f"Wrote: {args.out}")
+    else:
+        for line in lines[:10]:
+            print(line)
+        if len(lines) > 10:
+            print(f"... ({len(lines) - 10} more)")
+
+
+if __name__ == "__main__":
+    main()

poc_set_project.py

@@ -0,0 +1,68 @@
+"""
+poc_set_project.py — POC test for set_project_info() against a live MiniMate Plus.
+
+Usage:
+    python poc_set_project.py [--host IP] [--port PORT]
+
+Default target: BE11529 at 63.43.212.232:9034
+"""
+
+import argparse
+import logging
+import sys
+
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s  %(levelname)-7s  %(name)s  %(message)s",
+    datefmt="%H:%M:%S",
+)
+log = logging.getLogger("poc_set_project")
+
+from minimateplus import MiniMateClient
+from minimateplus.transport import TcpTransport
+
+
+DEFAULT_HOST = "63.43.212.232"
+DEFAULT_PORT = 9034
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="POC: write project info to MiniMate Plus")
+    ap.add_argument("--host", default=DEFAULT_HOST, help="Modem IP address")
+    ap.add_argument("--port", type=int, default=DEFAULT_PORT, help="TCP port")
+    ap.add_argument("--project",     default="POC Write Test")
+    ap.add_argument("--client-name", default="Terra-Mechanics Inc.")
+    ap.add_argument("--operator",    default="B. Harrison")
+    ap.add_argument("--seis-loc",    default="Lab Bench - POC")
+    ap.add_argument("--notes",       default="set_project_info POC 2026-04-07")
+    args = ap.parse_args()
+
+    log.info("Connecting to %s:%d", args.host, args.port)
+    transport = TcpTransport(args.host, port=args.port)
+
+    with MiniMateClient(transport=transport, timeout=60.0) as client:
+        log.info("Performing POLL handshake + identity read …")
+        info = client.connect()
+        log.info("Connected: serial=%s firmware=%s", info.serial, info.firmware_version)
+
+        log.info("Calling set_project_info() …")
+        client.set_project_info(
+            project=args.project,
+            client_name=args.client_name,
+            operator=args.operator,
+            seis_loc=args.seis_loc,
+            notes=args.notes,
+        )
+        log.info("set_project_info() returned — write sequence complete")
+
+    log.info("Done.  Reconnect Blastware to verify the fields were written.")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        sys.exit(0)
+    except Exception as exc:
+        log.exception("Fatal: %s", exc)
+        sys.exit(1)

pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seismo-relay"
+version = "0.12.0"
+description = "Python client and REST server for MiniMate Plus seismographs"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.104",
+    "uvicorn[standard]>=0.24",
+    "pyserial>=3.5",
+    "sqlalchemy>=2.0",
+]
+
+[tool.setuptools.packages.find]
+# Auto-discovers minimateplus/, sfm/, bridges/ as packages
+where = ["."]
+include = ["minimateplus*", "sfm*", "bridges*"]

requirements.txt

@@ -0,0 +1,4 @@
+fastapi
+uvicorn
+sqlalchemy
+pyserial

sfm/cache.py

@@ -0,0 +1,376 @@
+"""
+sfm/cache.py — Persistent SQLite cache for SFM device data.
+
+Caching strategy
+----------------
++------------------+----------------------------------+-------------------------+
+| Data             | Mutability                       | Invalidation            |
++------------------+----------------------------------+-------------------------+
+| Device info      | Effectively immutable (firmware, | Manual clear / force    |
+| (serial, model,  | serial never change)             | refresh query param     |
+| compliance cfg)  |                                  |                         |
++------------------+----------------------------------+-------------------------+
+| Event headers    | Append-only (new events added,   | Fetch new ones when     |
+| (peaks, ts,      | old never modified)              | device event count >    |
+| project info)    |                                  | cached count            |
++------------------+----------------------------------+-------------------------+
+| Full waveforms   | Immutable once recorded          | Never (permanent cache) |
+| (raw ADC samples)|                                  |                         |
++------------------+----------------------------------+-------------------------+
+| Monitor status   | Frequently changing              | TTL = 30 seconds        |
+| (battery, memory)|                                  |                         |
++------------------+----------------------------------+-------------------------+
+
+Keys
+----
+All cached rows are keyed by (host, tcp_port) for TCP connections, or (port, baud)
+for serial connections.  Within a device, events are keyed by index (0-based).
+
+The device serial number is stored once we learn it, and used for display / debugging
+only — the network address is the primary routing key (same as how the rest of the SFM
+code operates).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Optional
+
+try:
+    import sqlalchemy as sa
+    from sqlalchemy import orm
+except ImportError:
+    raise ImportError(
+        "sqlalchemy is required for the SFM cache.\n"
+        "Install it with:  pip install sqlalchemy"
+    )
+
+log = logging.getLogger("sfm.cache")
+
+# ── Schema ────────────────────────────────────────────────────────────────────
+
+Base = orm.declarative_base()
+
+_MONITOR_STATUS_TTL = 30  # seconds
+
+
+class CachedDevice(Base):
+    """
+    Device identity + compliance config, keyed by connection address.
+
+    Stores the full serialised JSON blob returned by /device/info so the
+    endpoint can return it verbatim on a cache hit without re-connecting.
+    """
+    __tablename__ = "cached_devices"
+
+    # Connection key — either TCP (host+port) or serial (port+baud)
+    conn_key   = sa.Column(sa.String, primary_key=True)  # e.g. "tcp:1.2.3.4:12345"
+    serial     = sa.Column(sa.String, nullable=True)      # e.g. "BE11529"
+    info_json  = sa.Column(sa.Text,   nullable=False)     # full /device/info response JSON
+    updated_at = sa.Column(sa.Float,  nullable=False)     # Unix timestamp of last write
+
+    # When a config write happens we set this flag so the next /device/info call
+    # fetches fresh data instead of serving stale compliance config.
+    config_dirty = sa.Column(sa.Boolean, default=False, nullable=False)
+
+
+class CachedEvent(Base):
+    """
+    Per-event header + peak values + project info, keyed by (conn_key, index).
+
+    Events are immutable once recorded on the device; once we have an event in
+    the cache it never needs to be re-downloaded unless explicitly requested.
+    """
+    __tablename__ = "cached_events"
+
+    conn_key   = sa.Column(sa.String, primary_key=True)
+    index      = sa.Column(sa.Integer, primary_key=True)
+    event_json = sa.Column(sa.Text,   nullable=False)  # serialised Event dict
+    cached_at  = sa.Column(sa.Float,  nullable=False)  # Unix timestamp
+
+
+class CachedWaveform(Base):
+    """
+    Full raw ADC waveform for a single event (SUB 5A full download).
+
+    These are large (up to several MB) and expensive to fetch over cellular.
+    Once downloaded they are immutable and cached permanently.
+    """
+    __tablename__ = "cached_waveforms"
+
+    conn_key      = sa.Column(sa.String, primary_key=True)
+    index         = sa.Column(sa.Integer, primary_key=True)
+    waveform_json = sa.Column(sa.Text,   nullable=False)  # full /device/event/{idx}/waveform response JSON
+    cached_at     = sa.Column(sa.Float,  nullable=False)
+
+
+class CachedMonitorStatus(Base):
+    """
+    Monitor status (battery, memory, is_monitoring) with a short TTL.
+
+    These change frequently during field operations so we keep them only for
+    MONITOR_STATUS_TTL seconds before re-fetching from the device.
+    """
+    __tablename__ = "cached_monitor_status"
+
+    conn_key    = sa.Column(sa.String, primary_key=True)
+    status_json = sa.Column(sa.Text,  nullable=False)
+    cached_at   = sa.Column(sa.Float, nullable=False)
+
+
+# ── Cache store ───────────────────────────────────────────────────────────────
+
+class SFMCache:
+    """
+    SQLite-backed cache for SFM device data.
+
+    Usage
+    -----
+    cache = SFMCache()          # stores in sfm/data/sfm_cache.db by default
+    cache = SFMCache(":memory:") # in-memory (tests / ephemeral mode)
+
+    All public methods accept a *conn_key* string — use make_conn_key() to
+    build a consistent key from the transport parameters.
+    """
+
+    def __init__(self, db_path: str | Path | None = None) -> None:
+        in_memory = (db_path == ":memory:")
+        if db_path is None:
+            # Default: alongside this file in sfm/data/
+            db_path = Path(__file__).parent / "data" / "sfm_cache.db"
+        if not in_memory:
+            db_path = Path(db_path)
+            db_path.parent.mkdir(parents=True, exist_ok=True)
+
+        url = "sqlite:///:memory:" if in_memory else f"sqlite:///{db_path}"
+        engine = sa.create_engine(url, connect_args={"check_same_thread": False})
+        Base.metadata.create_all(engine)
+        self._Session = orm.sessionmaker(bind=engine)
+        log.info("SFM cache opened: %s", db_path)
+
+    # ── Connection key ────────────────────────────────────────────────────────
+
+    @staticmethod
+    def make_conn_key(
+        host: Optional[str],
+        tcp_port: int,
+        port: Optional[str],
+        baud: int,
+    ) -> str:
+        """Return a stable string key for this transport configuration."""
+        if host:
+            return f"tcp:{host}:{tcp_port}"
+        return f"serial:{port}:{baud}"
+
+    # ── Device info ───────────────────────────────────────────────────────────
+
+    def get_device_info(self, conn_key: str) -> Optional[dict]:
+        """
+        Return cached device info dict, or None if not cached / config_dirty.
+        """
+        with self._Session() as s:
+            row = s.get(CachedDevice, conn_key)
+            if row is None or row.config_dirty:
+                return None
+            return json.loads(row.info_json)
+
+    def set_device_info(self, conn_key: str, info: dict) -> None:
+        """Store device info and clear any dirty flag."""
+        with self._Session() as s:
+            row = s.get(CachedDevice, conn_key)
+            serial = info.get("serial")
+            if row is None:
+                row = CachedDevice(
+                    conn_key=conn_key,
+                    serial=serial,
+                    info_json=json.dumps(info),
+                    updated_at=time.time(),
+                    config_dirty=False,
+                )
+                s.add(row)
+            else:
+                row.serial = serial
+                row.info_json = json.dumps(info)
+                row.updated_at = time.time()
+                row.config_dirty = False
+            s.commit()
+        log.debug("cached device info for %s (serial=%s)", conn_key, serial)
+
+    def mark_config_dirty(self, conn_key: str) -> None:
+        """
+        Called after a successful POST /device/config write.
+
+        Forces the next /device/info call to re-read compliance config from the
+        device instead of serving the now-stale cached version.
+        """
+        with self._Session() as s:
+            row = s.get(CachedDevice, conn_key)
+            if row:
+                row.config_dirty = True
+                s.commit()
+        log.debug("marked config dirty for %s", conn_key)
+
+    # ── Events ────────────────────────────────────────────────────────────────
+
+    def get_cached_event_count(self, conn_key: str) -> int:
+        """Return the number of events we have cached for this device."""
+        with self._Session() as s:
+            return s.query(CachedEvent).filter_by(conn_key=conn_key).count()
+
+    def get_all_events(self, conn_key: str) -> Optional[list[dict]]:
+        """
+        Return all cached events as a list of dicts, sorted by index.
+        Returns None if nothing is cached yet.
+        """
+        with self._Session() as s:
+            rows = (
+                s.query(CachedEvent)
+                .filter_by(conn_key=conn_key)
+                .order_by(CachedEvent.index)
+                .all()
+            )
+            if not rows:
+                return None
+            return [json.loads(r.event_json) for r in rows]
+
+    def get_event(self, conn_key: str, index: int) -> Optional[dict]:
+        """Return a single cached event by index, or None if not cached."""
+        with self._Session() as s:
+            row = s.get(CachedEvent, (conn_key, index))
+            return json.loads(row.event_json) if row else None
+
+    def set_events(self, conn_key: str, events: list[dict]) -> None:
+        """
+        Upsert a list of event dicts.  Existing rows are updated; new rows are
+        inserted.  This is used to add newly-discovered events to the cache.
+        """
+        now = time.time()
+        with self._Session() as s:
+            for ev in events:
+                idx = ev["index"]
+                row = s.get(CachedEvent, (conn_key, idx))
+                if row is None:
+                    row = CachedEvent(
+                        conn_key=conn_key,
+                        index=idx,
+                        event_json=json.dumps(ev),
+                        cached_at=now,
+                    )
+                    s.add(row)
+                    log.debug("cached new event %d for %s", idx, conn_key)
+                else:
+                    # Refresh in case project_info was backfilled after initial store
+                    row.event_json = json.dumps(ev)
+            s.commit()
+
+    # ── Waveforms ─────────────────────────────────────────────────────────────
+
+    def get_waveform(self, conn_key: str, index: int) -> Optional[dict]:
+        """Return a cached full waveform response dict, or None if not cached."""
+        with self._Session() as s:
+            row = s.get(CachedWaveform, (conn_key, index))
+            if row is None:
+                return None
+            log.debug("waveform cache hit: %s event %d", conn_key, index)
+            return json.loads(row.waveform_json)
+
+    def set_waveform(self, conn_key: str, index: int, waveform: dict) -> None:
+        """Store a full waveform response dict permanently."""
+        with self._Session() as s:
+            row = s.get(CachedWaveform, (conn_key, index))
+            if row is None:
+                row = CachedWaveform(
+                    conn_key=conn_key,
+                    index=index,
+                    waveform_json=json.dumps(waveform),
+                    cached_at=time.time(),
+                )
+                s.add(row)
+            else:
+                row.waveform_json = json.dumps(waveform)
+                row.cached_at = time.time()
+            s.commit()
+        log.debug("cached waveform for %s event %d", conn_key, index)
+
+    # ── Monitor status ────────────────────────────────────────────────────────
+
+    def get_monitor_status(self, conn_key: str) -> Optional[dict]:
+        """Return cached monitor status if it's within TTL, else None."""
+        with self._Session() as s:
+            row = s.get(CachedMonitorStatus, conn_key)
+            if row is None:
+                return None
+            age = time.time() - row.cached_at
+            if age > _MONITOR_STATUS_TTL:
+                log.debug("monitor status expired (age=%.1fs) for %s", age, conn_key)
+                return None
+            return json.loads(row.status_json)
+
+    def set_monitor_status(self, conn_key: str, status: dict) -> None:
+        """Store monitor status."""
+        with self._Session() as s:
+            row = s.get(CachedMonitorStatus, conn_key)
+            if row is None:
+                row = CachedMonitorStatus(
+                    conn_key=conn_key,
+                    status_json=json.dumps(status),
+                    cached_at=time.time(),
+                )
+                s.add(row)
+            else:
+                row.status_json = json.dumps(status)
+                row.cached_at = time.time()
+            s.commit()
+
+    def invalidate_monitor_status(self, conn_key: str) -> None:
+        """
+        Called after start/stop monitoring so the next status poll re-reads from device.
+        """
+        with self._Session() as s:
+            row = s.get(CachedMonitorStatus, conn_key)
+            if row:
+                s.delete(row)
+                s.commit()
+
+    # ── Cache management ──────────────────────────────────────────────────────
+
+    def clear_device(self, conn_key: str) -> dict:
+        """
+        Remove all cached data for a device.  Returns counts of deleted rows.
+        """
+        counts = {}
+        with self._Session() as s:
+            counts["device_info"] = s.query(CachedDevice).filter_by(conn_key=conn_key).delete()
+            counts["events"] = s.query(CachedEvent).filter_by(conn_key=conn_key).delete()
+            counts["waveforms"] = s.query(CachedWaveform).filter_by(conn_key=conn_key).delete()
+            counts["monitor_status"] = s.query(CachedMonitorStatus).filter_by(conn_key=conn_key).delete()
+            s.commit()
+        log.info("cleared cache for %s: %s", conn_key, counts)
+        return counts
+
+    def stats(self) -> dict:
+        """Return row counts for all cache tables (for /cache/stats endpoint)."""
+        with self._Session() as s:
+            return {
+                "devices":         s.query(CachedDevice).count(),
+                "events":          s.query(CachedEvent).count(),
+                "waveforms":       s.query(CachedWaveform).count(),
+                "monitor_status":  s.query(CachedMonitorStatus).count(),
+            }
+
+
+# ── Module-level singleton ────────────────────────────────────────────────────
+# Instantiated once when the module is imported; shared across all requests.
+
+_cache: Optional[SFMCache] = None
+
+
+def get_cache() -> SFMCache:
+    """Return the module-level cache singleton, initialising it on first call."""
+    global _cache
+    if _cache is None:
+        _cache = SFMCache()
+    return _cache

sfm/database.py

@@ -0,0 +1,486 @@
+"""
+sfm/database.py — SQLite persistence layer for seismo-relay.
+
+Three tables, all keyed by unit serial number:
+
+  ach_sessions   — one row per inbound ACH call-home
+  events         — one row per triggered waveform event (deduped by serial+timestamp)
+  monitor_log    — one row per monitoring interval (deduped by serial+start_time)
+
+The DB file lives at:
+  <output_dir>/seismo_relay.db     (default: bridges/captures/seismo_relay.db)
+
+Usage
+-----
+  from sfm.database import SeismoDb
+
+  db = SeismoDb("bridges/captures/seismo_relay.db")
+
+  # Write a call-home session
+  session_id = db.insert_ach_session(serial="BE11529", peer="1.2.3.4:51920",
+                                     events_downloaded=3, monitor_entries=2,
+                                     duration_seconds=47.3)
+
+  # Write events (silently skips duplicates)
+  db.insert_events(events, serial="BE11529", session_id=session_id)
+
+  # Write monitor log entries
+  db.insert_monitor_log(entries, session_id=session_id)
+
+  # Query
+  rows = db.query_events(serial="BE11529", from_dt=datetime(...), to_dt=datetime(...))
+"""
+
+from __future__ import annotations
+
+import datetime
+import logging
+import sqlite3
+import uuid
+from pathlib import Path
+from typing import Optional
+
+from minimateplus.models import Event, MonitorLogEntry
+
+log = logging.getLogger("sfm.database")
+
+# ── Schema ─────────────────────────────────────────────────────────────────────
+
+_SCHEMA = """
+PRAGMA journal_mode = WAL;
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS ach_sessions (
+    id                      TEXT PRIMARY KEY,       -- UUID
+    serial                  TEXT NOT NULL,
+    session_time            TEXT NOT NULL,          -- ISO-8601 UTC
+    peer                    TEXT,                   -- "ip:port"
+    events_downloaded       INTEGER NOT NULL DEFAULT 0,
+    monitor_entries         INTEGER NOT NULL DEFAULT 0,
+    duration_seconds        REAL,
+    created_at              TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+);
+CREATE INDEX IF NOT EXISTS idx_ach_sessions_serial ON ach_sessions(serial);
+CREATE INDEX IF NOT EXISTS idx_ach_sessions_time   ON ach_sessions(session_time);
+
+CREATE TABLE IF NOT EXISTS events (
+    id                      TEXT PRIMARY KEY,       -- UUID
+    serial                  TEXT NOT NULL,
+    waveform_key            TEXT NOT NULL,          -- 8-hex device key (dedup field)
+    session_id              TEXT,                   -- FK → ach_sessions.id
+    timestamp               TEXT,                   -- ISO-8601 local time from device
+    tran_ppv                REAL,                   -- in/s
+    vert_ppv                REAL,                   -- in/s
+    long_ppv                REAL,                   -- in/s
+    peak_vector_sum         REAL,                   -- in/s
+    mic_ppv                 REAL,                   -- psi or dB depending on setup
+    project                 TEXT,
+    client                  TEXT,
+    operator                TEXT,
+    sensor_location         TEXT,
+    sample_rate             INTEGER,
+    record_type             TEXT,                   -- "single_shot" | "continuous"
+    false_trigger           INTEGER NOT NULL DEFAULT 0,  -- 0=no, 1=yes (manual flag)
+    created_at              TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+    UNIQUE(serial, timestamp)
+);
+CREATE INDEX IF NOT EXISTS idx_events_serial    ON events(serial);
+CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(timestamp);
+CREATE INDEX IF NOT EXISTS idx_events_session   ON events(session_id);
+
+CREATE TABLE IF NOT EXISTS monitor_log (
+    id                      TEXT PRIMARY KEY,       -- UUID
+    serial                  TEXT NOT NULL,
+    waveform_key            TEXT NOT NULL,          -- 8-hex device key (dedup field)
+    session_id              TEXT,                   -- FK → ach_sessions.id
+    start_time              TEXT,                   -- ISO-8601
+    stop_time               TEXT,                   -- ISO-8601
+    duration_seconds        REAL,
+    geo_threshold_ips       REAL,                   -- in/s
+    created_at              TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+    UNIQUE(serial, start_time)
+);
+CREATE INDEX IF NOT EXISTS idx_monitor_log_serial ON monitor_log(serial);
+CREATE INDEX IF NOT EXISTS idx_monitor_log_start  ON monitor_log(start_time);
+CREATE INDEX IF NOT EXISTS idx_monitor_log_session ON monitor_log(session_id);
+"""
+
+
+# ── SeismoDb class ─────────────────────────────────────────────────────────────
+
+class SeismoDb:
+    """
+    Thin SQLite wrapper for seismo-relay persistence.
+
+    Thread-safe: each call opens, uses, and closes a connection with
+    check_same_thread=False and WAL mode enabled.  For the ACH server's
+    single-writer / occasional-reader pattern this is more than sufficient.
+    """
+
+    def __init__(self, db_path: str | Path) -> None:
+        self.db_path = Path(db_path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_schema()
+        log.info("SeismoDb initialised at %s", self.db_path)
+
+    # ── Internal helpers ───────────────────────────────────────────────────────
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(str(self.db_path), check_same_thread=False)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA journal_mode = WAL")
+        conn.execute("PRAGMA foreign_keys = ON")
+        return conn
+
+    def _init_schema(self) -> None:
+        with self._connect() as conn:
+            conn.executescript(_SCHEMA)
+            self._migrate(conn)
+
+    def _migrate(self, conn: sqlite3.Connection) -> None:
+        """Apply in-place schema migrations for existing databases."""
+
+        # Migration 1: change events UNIQUE from (serial, waveform_key) [or any
+        # waveform_key-based variant] to (serial, timestamp).
+        # Rationale: device key counter resets to 01110000 after every erase, so
+        # waveform_key is not a stable dedup field across erase cycles.  The event
+        # timestamp (from the device clock) is the correct natural key.
+        row = conn.execute(
+            "SELECT sql FROM sqlite_master WHERE type='table' AND name='events'"
+        ).fetchone()
+        if row and "UNIQUE(serial, timestamp)" not in row[0]:
+            log.info("_migrate: rebuilding events table — UNIQUE(serial, timestamp)")
+            conn.executescript("""
+                ALTER TABLE events RENAME TO events_old;
+
+                CREATE TABLE events (
+                    id                      TEXT PRIMARY KEY,
+                    serial                  TEXT NOT NULL,
+                    waveform_key            TEXT NOT NULL,
+                    session_id              TEXT,
+                    timestamp               TEXT,
+                    tran_ppv                REAL,
+                    vert_ppv                REAL,
+                    long_ppv                REAL,
+                    peak_vector_sum         REAL,
+                    mic_ppv                 REAL,
+                    project                 TEXT,
+                    client                  TEXT,
+                    operator                TEXT,
+                    sensor_location         TEXT,
+                    sample_rate             INTEGER,
+                    record_type             TEXT,
+                    false_trigger           INTEGER NOT NULL DEFAULT 0,
+                    created_at              TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+                    UNIQUE(serial, timestamp)
+                );
+
+                INSERT OR IGNORE INTO events SELECT * FROM events_old;
+                DROP TABLE events_old;
+
+                CREATE INDEX IF NOT EXISTS idx_events_serial    ON events(serial);
+                CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(timestamp);
+                CREATE INDEX IF NOT EXISTS idx_events_session   ON events(session_id);
+            """)
+            log.info("_migrate: events table rebuilt OK")
+
+        # Migration 2: change monitor_log UNIQUE from (serial, waveform_key) to
+        # (serial, start_time) — same reasoning as events.
+        row = conn.execute(
+            "SELECT sql FROM sqlite_master WHERE type='table' AND name='monitor_log'"
+        ).fetchone()
+        if row and "UNIQUE(serial, start_time)" not in row[0]:
+            log.info("_migrate: rebuilding monitor_log table — UNIQUE(serial, start_time)")
+            conn.executescript("""
+                ALTER TABLE monitor_log RENAME TO monitor_log_old;
+
+                CREATE TABLE monitor_log (
+                    id                      TEXT PRIMARY KEY,
+                    serial                  TEXT NOT NULL,
+                    waveform_key            TEXT NOT NULL,
+                    session_id              TEXT,
+                    start_time              TEXT,
+                    stop_time               TEXT,
+                    duration_seconds        REAL,
+                    geo_threshold_ips       REAL,
+                    created_at              TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
+                    UNIQUE(serial, start_time)
+                );
+
+                INSERT OR IGNORE INTO monitor_log SELECT * FROM monitor_log_old;
+                DROP TABLE monitor_log_old;
+
+                CREATE INDEX IF NOT EXISTS idx_monitor_log_serial  ON monitor_log(serial);
+                CREATE INDEX IF NOT EXISTS idx_monitor_log_start   ON monitor_log(start_time);
+                CREATE INDEX IF NOT EXISTS idx_monitor_log_session ON monitor_log(session_id);
+            """)
+            log.info("_migrate: monitor_log table rebuilt OK")
+
+    @staticmethod
+    def _iso(dt: Optional[datetime.datetime]) -> Optional[str]:
+        return dt.isoformat() if dt is not None else None
+
+    @staticmethod
+    def _new_id() -> str:
+        return str(uuid.uuid4())
+
+    # ── ACH sessions ──────────────────────────────────────────────────────────
+
+    def insert_ach_session(
+        self,
+        *,
+        serial: str,
+        peer: Optional[str] = None,
+        events_downloaded: int = 0,
+        monitor_entries: int = 0,
+        duration_seconds: Optional[float] = None,
+        session_time: Optional[datetime.datetime] = None,
+    ) -> str:
+        """Insert a new ACH session row. Returns the new session UUID."""
+        sid = self._new_id()
+        ts  = self._iso(session_time or datetime.datetime.utcnow())
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO ach_sessions
+                    (id, serial, session_time, peer,
+                     events_downloaded, monitor_entries, duration_seconds)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+                """,
+                (sid, serial, ts, peer,
+                 events_downloaded, monitor_entries, duration_seconds),
+            )
+        log.debug("ach_session inserted: %s serial=%s events=%d monitor=%d",
+                  sid, serial, events_downloaded, monitor_entries)
+        return sid
+
+    def get_sessions(
+        self,
+        serial: Optional[str] = None,
+        limit: int = 50,
+    ) -> list[dict]:
+        """Return recent ACH sessions, newest first."""
+        with self._connect() as conn:
+            if serial:
+                rows = conn.execute(
+                    "SELECT * FROM ach_sessions WHERE serial=? "
+                    "ORDER BY session_time DESC LIMIT ?",
+                    (serial, limit),
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    "SELECT * FROM ach_sessions ORDER BY session_time DESC LIMIT ?",
+                    (limit,),
+                ).fetchall()
+        return [dict(r) for r in rows]
+
+    # ── Events ────────────────────────────────────────────────────────────────
+
+    def insert_events(
+        self,
+        events: list[Event],
+        *,
+        serial: str,
+        session_id: Optional[str] = None,
+    ) -> tuple[int, int]:
+        """
+        Insert triggered events. Silently skips duplicates (serial+timestamp).
+        Returns (inserted, skipped).
+        """
+        inserted = skipped = 0
+        with self._connect() as conn:
+            for ev in events:
+                key = ev._waveform_key.hex() if ev._waveform_key else None
+                if key is None:
+                    skipped += 1
+                    continue
+
+                ts  = None
+                if ev.timestamp:
+                    try:
+                        ts = datetime.datetime(
+                            ev.timestamp.year, ev.timestamp.month, ev.timestamp.day,
+                            ev.timestamp.hour, ev.timestamp.minute, ev.timestamp.second,
+                        ).isoformat()
+                    except Exception:
+                        ts = str(ev.timestamp)
+
+                pv  = ev.peak_values
+                pi  = ev.project_info
+
+                try:
+                    conn.execute(
+                        """
+                        INSERT INTO events
+                            (id, serial, waveform_key, session_id, timestamp,
+                             tran_ppv, vert_ppv, long_ppv, peak_vector_sum, mic_ppv,
+                             project, client, operator, sensor_location,
+                             sample_rate, record_type)
+                        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                        """,
+                        (
+                            self._new_id(), serial, key, session_id, ts,
+                            pv.tran  if pv else None,
+                            pv.vert  if pv else None,
+                            pv.long  if pv else None,
+                            pv.peak_vector_sum if pv else None,
+                            pv.micl  if pv else None,
+                            pi.project         if pi else None,
+                            pi.client          if pi else None,
+                            pi.operator        if pi else None,
+                            pi.sensor_location if pi else None,
+                            ev.sample_rate,
+                            ev.record_type,
+                        ),
+                    )
+                    inserted += 1
+                except sqlite3.IntegrityError:
+                    skipped += 1
+
+        log.debug("insert_events serial=%s inserted=%d skipped=%d",
+                  serial, inserted, skipped)
+        return inserted, skipped
+
+    def query_events(
+        self,
+        serial: Optional[str] = None,
+        from_dt: Optional[datetime.datetime] = None,
+        to_dt: Optional[datetime.datetime] = None,
+        false_trigger: Optional[bool] = None,
+        limit: int = 500,
+        offset: int = 0,
+    ) -> list[dict]:
+        """Query events with optional filters. Returns newest first."""
+        clauses: list[str] = []
+        params:  list      = []
+
+        if serial:
+            clauses.append("serial = ?")
+            params.append(serial)
+        if from_dt:
+            clauses.append("timestamp >= ?")
+            params.append(from_dt.isoformat())
+        if to_dt:
+            clauses.append("timestamp <= ?")
+            params.append(to_dt.isoformat())
+        if false_trigger is not None:
+            clauses.append("false_trigger = ?")
+            params.append(1 if false_trigger else 0)
+
+        where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
+        params += [limit, offset]
+
+        with self._connect() as conn:
+            rows = conn.execute(
+                f"SELECT * FROM events {where} "
+                f"ORDER BY timestamp DESC LIMIT ? OFFSET ?",
+                params,
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    def set_false_trigger(self, event_id: str, value: bool) -> bool:
+        """Set or clear the false_trigger flag on an event. Returns True if found."""
+        with self._connect() as conn:
+            cur = conn.execute(
+                "UPDATE events SET false_trigger=? WHERE id=?",
+                (1 if value else 0, event_id),
+            )
+        return cur.rowcount > 0
+
+    # ── Monitor log ───────────────────────────────────────────────────────────
+
+    def insert_monitor_log(
+        self,
+        entries: list[MonitorLogEntry],
+        *,
+        session_id: Optional[str] = None,
+    ) -> tuple[int, int]:
+        """
+        Insert monitor log entries. Silently skips duplicates (serial+start_time).
+        Returns (inserted, skipped).
+        """
+        inserted = skipped = 0
+        with self._connect() as conn:
+            for e in entries:
+                try:
+                    conn.execute(
+                        """
+                        INSERT INTO monitor_log
+                            (id, serial, waveform_key, session_id,
+                             start_time, stop_time, duration_seconds,
+                             geo_threshold_ips)
+                        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                        """,
+                        (
+                            self._new_id(),
+                            e.serial or "",
+                            e.key,
+                            session_id,
+                            self._iso(e.start_time),
+                            self._iso(e.stop_time),
+                            e.duration_seconds,
+                            e.geo_threshold_ips,
+                        ),
+                    )
+                    inserted += 1
+                except sqlite3.IntegrityError:
+                    skipped += 1
+
+        log.debug("insert_monitor_log inserted=%d skipped=%d", inserted, skipped)
+        return inserted, skipped
+
+    def query_monitor_log(
+        self,
+        serial: Optional[str] = None,
+        from_dt: Optional[datetime.datetime] = None,
+        to_dt: Optional[datetime.datetime] = None,
+        limit: int = 500,
+        offset: int = 0,
+    ) -> list[dict]:
+        """Query monitor log entries with optional filters. Returns newest first."""
+        clauses: list[str] = []
+        params:  list      = []
+
+        if serial:
+            clauses.append("serial = ?")
+            params.append(serial)
+        if from_dt:
+            clauses.append("start_time >= ?")
+            params.append(from_dt.isoformat())
+        if to_dt:
+            clauses.append("start_time <= ?")
+            params.append(to_dt.isoformat())
+
+        where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
+        params += [limit, offset]
+
+        with self._connect() as conn:
+            rows = conn.execute(
+                f"SELECT * FROM monitor_log {where} "
+                f"ORDER BY start_time DESC LIMIT ? OFFSET ?",
+                params,
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    # ── Fleet overview ────────────────────────────────────────────────────────
+
+    def query_units(self) -> list[dict]:
+        """
+        Return one row per known serial with summary stats:
+        last_seen, total_events, total_monitor_entries.
+        """
+        with self._connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT
+                    s.serial,
+                    MAX(s.session_time)  AS last_seen,
+                    SUM(s.events_downloaded)  AS total_events,
+                    SUM(s.monitor_entries)    AS total_monitor_entries,
+                    COUNT(*)                  AS total_sessions
+                FROM ach_sessions s
+                GROUP BY s.serial
+                ORDER BY last_seen DESC
+                """
+            ).fetchall()
+        return [dict(r) for r in rows]

sfm/waveform_viewer.html

@@ -0,0 +1,602 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>SFM Waveform Viewer</title>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.1/chart.umd.min.js"></script>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      background: #0d1117;
+      color: #c9d1d9;
+      font-family: 'Segoe UI', system-ui, sans-serif;
+      font-size: 13px;
+    }
+
+    header {
+      background: #161b22;
+      border-bottom: 1px solid #30363d;
+      padding: 12px 20px;
+      display: flex;
+      align-items: center;
+      gap: 16px;
+      flex-wrap: wrap;
+    }
+
+    header h1 {
+      font-size: 15px;
+      font-weight: 600;
+      color: #f0f6fc;
+      white-space: nowrap;
+      margin-right: 8px;
+    }
+
+    .conn-group {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      flex-wrap: wrap;
+    }
+
+    label { color: #8b949e; font-size: 12px; }
+
+    input[type="text"], input[type="number"] {
+      background: #0d1117;
+      border: 1px solid #30363d;
+      border-radius: 6px;
+      color: #c9d1d9;
+      padding: 5px 8px;
+      font-size: 13px;
+      width: 100px;
+    }
+    input[type="number"] { width: 70px; }
+    input:focus { outline: none; border-color: #388bfd; }
+
+    button {
+      background: #1f6feb;
+      border: none;
+      border-radius: 6px;
+      color: #fff;
+      cursor: pointer;
+      font-size: 13px;
+      font-weight: 500;
+      padding: 5px 14px;
+      transition: background 0.15s;
+    }
+    button:hover  { background: #388bfd; }
+    button:active { background: #1158c7; }
+    button:disabled { background: #21262d; color: #484f58; cursor: not-allowed; }
+
+    #status-bar {
+      background: #161b22;
+      border-bottom: 1px solid #21262d;
+      padding: 5px 20px;
+      font-size: 12px;
+      color: #8b949e;
+      min-height: 26px;
+      display: flex;
+      align-items: center;
+      gap: 20px;
+    }
+    #status-bar.error  { color: #f85149; }
+    #status-bar.ok     { color: #3fb950; }
+    #status-bar.loading { color: #d29922; }
+
+    .meta-pill {
+      background: #21262d;
+      border-radius: 4px;
+      padding: 2px 8px;
+      color: #c9d1d9;
+      font-family: monospace;
+    }
+
+    #charts {
+      padding: 12px 16px;
+      display: flex;
+      flex-direction: column;
+      gap: 10px;
+    }
+
+    .chart-wrap {
+      background: #161b22;
+      border: 1px solid #21262d;
+      border-radius: 8px;
+      padding: 10px 12px 8px;
+    }
+
+    .chart-label {
+      font-size: 11px;
+      font-weight: 600;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      margin-bottom: 4px;
+    }
+
+    .chart-canvas-wrap { position: relative; height: 130px; }
+
+    #empty-state {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      height: 60vh;
+      color: #484f58;
+      gap: 8px;
+    }
+    #empty-state svg { opacity: 0.3; }
+    #empty-state p { font-size: 14px; }
+
+    .ch-tran { color: #58a6ff; }
+    .ch-vert { color: #3fb950; }
+    .ch-long { color: #d29922; }
+    .ch-mic  { color: #bc8cff; }
+
+    #unit-bar {
+      background: #0d1117;
+      border-bottom: 1px solid #21262d;
+      padding: 8px 20px;
+      display: flex;
+      align-items: center;
+      gap: 16px;
+      flex-wrap: wrap;
+      font-size: 12px;
+    }
+
+    .unit-field { display: flex; flex-direction: column; gap: 1px; }
+    .unit-field .uf-label { color: #484f58; font-size: 10px; text-transform: uppercase; letter-spacing: 0.05em; }
+    .unit-field .uf-value { color: #c9d1d9; font-family: monospace; font-size: 13px; }
+    .unit-field .uf-value.highlight { color: #58a6ff; font-weight: 600; }
+
+    .event-chips {
+      display: flex;
+      gap: 5px;
+      flex-wrap: wrap;
+      margin-left: 8px;
+    }
+
+    .event-chip {
+      background: #21262d;
+      border: 1px solid #30363d;
+      border-radius: 5px;
+      color: #8b949e;
+      cursor: pointer;
+      font-size: 12px;
+      padding: 3px 10px;
+      transition: all 0.12s;
+    }
+    .event-chip:hover   { background: #1f6feb; border-color: #1f6feb; color: #fff; }
+    .event-chip.active  { background: #1f6feb; border-color: #388bfd; color: #fff; font-weight: 600; }
+
+    #connect-btn {
+      background: #238636;
+      margin-left: auto;
+    }
+    #connect-btn:hover { background: #2ea043; }
+    #connect-btn:disabled { background: #21262d; color: #484f58; }
+  </style>
+</head>
+<body>
+
+<header>
+  <h1>SFM Waveform Viewer</h1>
+  <div class="conn-group">
+    <label>API</label>
+    <input type="text" id="api-base" style="width:180px" />
+  </div>
+  <div class="conn-group">
+    <label>Device host</label>
+    <input type="text" id="dev-host" value="" placeholder="e.g. 10.0.0.5" />
+    <label>TCP port</label>
+    <input type="number" id="dev-tcp-port" value="9034" />
+  </div>
+  <button id="connect-btn" onclick="connectUnit()">Connect</button>
+  <button id="load-btn" onclick="loadWaveform()" disabled>Load Waveform</button>
+  <button id="prev-btn" onclick="stepEvent(-1)" disabled>◀ Prev</button>
+  <button id="next-btn" onclick="stepEvent(+1)" disabled>Next ▶</button>
+</header>
+
+<!-- Unit info bar — hidden until connected -->
+<div id="unit-bar" style="display:none">
+  <div class="unit-field">
+    <span class="uf-label">Serial</span>
+    <span class="uf-value" id="u-serial">—</span>
+  </div>
+  <div class="unit-field">
+    <span class="uf-label">Firmware</span>
+    <span class="uf-value" id="u-fw">—</span>
+  </div>
+  <div class="unit-field">
+    <span class="uf-label">Sample rate</span>
+    <span class="uf-value" id="u-sr">—</span>
+  </div>
+  <div class="unit-field">
+    <span class="uf-label">Events</span>
+    <span class="uf-value highlight" id="u-count">—</span>
+  </div>
+  <div class="event-chips" id="event-chips"></div>
+</div>
+
+<div id="status-bar">Ready — enter device host and click Connect.</div>
+
+<div id="empty-state">
+  <svg width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+    <polyline points="22 12 18 12 15 21 9 3 6 12 2 12"/>
+  </svg>
+  <p>No waveform loaded</p>
+</div>
+
+<div id="charts" style="display:none"></div>
+
+<script>
+  const CHANNEL_COLORS = {
+    Tran: '#58a6ff',
+    Vert: '#3fb950',
+    Long: '#d29922',
+    Mic:  '#bc8cff',
+  };
+
+  let charts = {};
+  let lastData = null;
+  let unitInfo = null;
+  let geoAdcScale = 10.0;       // in/s full-scale for geo channels; updated on connect
+  let eventList = [];        // populated from /device/events after connect
+  let currentEventIndex = 0;
+
+  function setStatus(msg, cls = '') {
+    const bar = document.getElementById('status-bar');
+    bar.textContent = msg;
+    bar.className = cls;
+  }
+
+  function appendMeta(label, value) {
+    const bar = document.getElementById('status-bar');
+    const pill = document.createElement('span');
+    pill.className = 'meta-pill';
+    pill.textContent = `${label}: ${value}`;
+    bar.appendChild(pill);
+  }
+
+  async function connectUnit() {
+    const apiBase = document.getElementById('api-base').value.replace(/\/$/, '');
+    const devHost = document.getElementById('dev-host').value.trim();
+    const tcpPort = document.getElementById('dev-tcp-port').value;
+
+    if (!devHost) { setStatus('Enter a device host first.', 'error'); return; }
+
+    const btn = document.getElementById('connect-btn');
+    btn.disabled = true;
+    btn.textContent = 'Connecting…';
+    setStatus('Connecting to unit…', 'loading');
+
+    const url = `${apiBase}/device/info?host=${encodeURIComponent(devHost)}&tcp_port=${tcpPort}`;
+    try {
+      const resp = await fetch(url);
+      if (!resp.ok) {
+        const err = await resp.json().catch(() => ({ detail: resp.statusText }));
+        throw new Error(err.detail || resp.statusText);
+      }
+      unitInfo = await resp.json();
+      geoAdcScale = unitInfo.compliance_config?.geo_adc_scale ?? 10.0;
+    } catch (e) {
+      setStatus(`Error: ${e.message}`, 'error');
+      btn.disabled = false;
+      btn.textContent = 'Connect';
+      return;
+    }
+
+    // Populate unit bar from /device/info
+    document.getElementById('u-serial').textContent = unitInfo.serial || '—';
+    document.getElementById('u-fw').textContent     = unitInfo.firmware_version || '—';
+    const sr = unitInfo.compliance_config?.sample_rate;
+    document.getElementById('u-sr').textContent     = sr ? `${sr} sps` : '—';
+
+    // Fetch real event list from /device/events — SUB 08 count is unreliable
+    setStatus('Fetching event list…', 'loading');
+    const eventsUrl = `${apiBase}/device/events?host=${encodeURIComponent(devHost)}&tcp_port=${tcpPort}`;
+    try {
+      const evResp = await fetch(eventsUrl);
+      if (!evResp.ok) {
+        const err = await evResp.json().catch(() => ({ detail: evResp.statusText }));
+        throw new Error(err.detail || evResp.statusText);
+      }
+      const evData = await evResp.json();
+      eventList = evData.events || [];
+    } catch (e) {
+      setStatus(`Error fetching events: ${e.message}`, 'error');
+      btn.disabled = false;
+      btn.textContent = 'Reconnect';
+      return;
+    }
+
+    const count = eventList.length;
+    document.getElementById('u-count').textContent = count;
+
+    // Build event chips with timestamps
+    const chipsEl = document.getElementById('event-chips');
+    chipsEl.innerHTML = '';
+    eventList.forEach((ev, i) => {
+      const chip = document.createElement('button');
+      chip.className = 'event-chip' + (i === 0 ? ' active' : '');
+      const label = ev.timestamp?.display ?? `Event ${ev.index}`;
+      chip.textContent = label;
+      chip.title = ev.record_type || '';
+      chip.onclick = () => selectEvent(i);
+      chipsEl.appendChild(chip);
+    });
+
+    document.getElementById('unit-bar').style.display = 'flex';
+    document.getElementById('load-btn').disabled  = count === 0;
+    document.getElementById('prev-btn').disabled  = true;
+    document.getElementById('next-btn').disabled  = count <= 1;
+
+    btn.disabled = false;
+    btn.textContent = 'Reconnect';
+
+    if (count === 0) {
+      setStatus('Connected — no events stored on device.', 'ok');
+    } else {
+      setStatus(`Connected — ${count} event${count !== 1 ? 's' : ''} stored. Select an event or click Load Waveform.`, 'ok');
+    }
+  }
+
+  function selectEvent(idx) {
+    currentEventIndex = idx;
+    // Update chip highlight
+    document.querySelectorAll('.event-chip').forEach((c, i) => {
+      c.classList.toggle('active', i === idx);
+    });
+    document.getElementById('prev-btn').disabled = idx <= 0;
+    document.getElementById('next-btn').disabled = idx >= eventList.length - 1;
+    loadWaveform();
+  }
+
+  async function loadWaveform() {
+    const apiBase = document.getElementById('api-base').value.replace(/\/$/, '');
+    const devHost = document.getElementById('dev-host').value.trim();
+    const tcpPort = document.getElementById('dev-tcp-port').value;
+    const evIndex = currentEventIndex;
+
+    if (!devHost) { setStatus('Enter a device host first.', 'error'); return; }
+
+    const btn = document.getElementById('load-btn');
+    btn.disabled = true;
+    setStatus('Fetching waveform…', 'loading');
+
+    const url = `${apiBase}/device/event/${evIndex}/waveform?host=${encodeURIComponent(devHost)}&tcp_port=${tcpPort}`;
+
+    let data;
+    try {
+      const resp = await fetch(url);
+      if (!resp.ok) {
+        const err = await resp.json().catch(() => ({ detail: resp.statusText }));
+        throw new Error(err.detail || resp.statusText);
+      }
+      data = await resp.json();
+    } catch (e) {
+      setStatus(`Error: ${e.message}`, 'error');
+      btn.disabled = false;
+      return;
+    }
+
+    lastData = data;
+    renderWaveform(data);
+    btn.disabled = false;
+  }
+
+  function stepEvent(delta) {
+    const count = eventList.length;
+    const next = Math.max(0, Math.min(count - 1, currentEventIndex + delta));
+    selectEvent(next);
+  }
+
+  function renderWaveform(data) {
+    const sr        = data.sample_rate  || 1024;
+    const pretrig   = data.pretrig_samples || 0;
+    const decoded   = data.samples_decoded || 0;
+    const total     = data.total_samples   || decoded;
+    const channels  = data.channels || {};
+    const recType   = data.record_type || 'Unknown';
+
+    // Status bar
+    const bar = document.getElementById('status-bar');
+    bar.innerHTML = '';
+    bar.className = 'ok';
+    const ts = data.timestamp;
+    if (ts) {
+      bar.textContent = `Event #${data.index}  —  ${ts.display}    `;
+    } else {
+      bar.textContent = `Event #${data.index}    `;
+    }
+    appendMeta('type', recType);
+    appendMeta('sr', `${sr} sps`);
+    appendMeta('samples', `${decoded.toLocaleString()} / ${total.toLocaleString()}`);
+    appendMeta('pretrig', pretrig);
+    appendMeta('rectime', `${data.rectime_seconds ?? '?'}s`);
+
+    // No waveform data — show a clear reason instead of empty charts
+    if (decoded === 0) {
+      document.getElementById('empty-state').style.display = 'flex';
+      document.getElementById('empty-state').querySelector('p').textContent =
+        recType === 'Waveform'
+          ? 'Waveform decode returned no samples — check server logs'
+          : `Record type "${recType}" — waveform decode not yet supported for this mode`;
+      document.getElementById('charts').style.display = 'none';
+      Object.values(charts).forEach(c => c.destroy());
+      charts = {};
+      return;
+    }
+
+    // Build time axis (ms)
+    const times = Array.from({ length: decoded }, (_, i) =>
+      ((i - pretrig) / sr * 1000).toFixed(2)
+    );
+
+    // Show charts area
+    document.getElementById('empty-state').style.display = 'none';
+    const chartsDiv = document.getElementById('charts');
+    chartsDiv.style.display = 'flex';
+    chartsDiv.innerHTML = '';
+
+    // Destroy old Chart instances
+    Object.values(charts).forEach(c => c.destroy());
+    charts = {};
+
+    // Mic peak PSI from 0C waveform record — used to scale raw mic counts
+    const micPeakPsi = data.peak_values?.micl_psi ?? null;
+    const DBL_REF_PSI = 2.9e-9; // 20 µPa in psi
+
+    for (const [ch, color] of Object.entries(CHANNEL_COLORS)) {
+      const samples = channels[ch];
+      if (!samples || samples.length === 0) continue;
+
+      // Convert raw ADC counts to physical units
+      const isGeo = ch !== 'Mic';
+      let plotSamples, peakLabel, yUnit, tooltipFmt, tickFmt;
+
+      if (isGeo) {
+        // Geo channels: counts × (range / 32767) → in/s
+        const scale = geoAdcScale / 32767;
+        plotSamples = samples.map(c => c * scale);
+        const peakIns = Math.max(...plotSamples.map(Math.abs));
+        peakLabel  = `${peakIns.toFixed(5)} in/s`;
+        yUnit      = 'in/s';
+        tooltipFmt = v => `${ch}: ${v.toFixed(5)} in/s`;
+        tickFmt    = v => v.toFixed(4);
+      } else {
+        // Mic: derive psi/count scale from the 0C peak value, display as psi; show dBL in header
+        const peakCounts = Math.max(...samples.map(Math.abs));
+        const micScale   = (micPeakPsi !== null && peakCounts > 0)
+          ? Math.abs(micPeakPsi) / peakCounts
+          : 1.0;
+        plotSamples = samples.map(c => c * micScale);
+        const peakPsi = Math.max(...plotSamples.map(Math.abs));
+        const peakDbl = peakPsi > 0 ? 20 * Math.log10(peakPsi / DBL_REF_PSI) : -Infinity;
+        peakLabel  = `${peakDbl.toFixed(1)} dBL  (${peakPsi.toExponential(3)} psi)`;
+        yUnit      = 'psi';
+        tooltipFmt = v => `${ch}: ${v.toExponential(3)} psi`;
+        tickFmt    = v => v.toExponential(1);
+      }
+
+      const wrap = document.createElement('div');
+      wrap.className = 'chart-wrap';
+
+      const lbl = document.createElement('div');
+      lbl.className = `chart-label ch-${ch.toLowerCase()}`;
+      lbl.textContent = `${ch}  —  peak ${peakLabel}`;
+      wrap.appendChild(lbl);
+
+      const canvasWrap = document.createElement('div');
+      canvasWrap.className = 'chart-canvas-wrap';
+      const canvas = document.createElement('canvas');
+      canvasWrap.appendChild(canvas);
+      wrap.appendChild(canvasWrap);
+      chartsDiv.appendChild(wrap);
+
+      // Downsample for rendering if very long (keep chart responsive)
+      const MAX_POINTS = 4000;
+      let renderTimes = times;
+      let renderData  = plotSamples;
+      if (plotSamples.length > MAX_POINTS) {
+        const step = Math.ceil(plotSamples.length / MAX_POINTS);
+        renderTimes = times.filter((_, i) => i % step === 0);
+        renderData  = plotSamples.filter((_, i) => i % step === 0);
+      }
+
+      const chart = new Chart(canvas, {
+        type: 'line',
+        data: {
+          labels: renderTimes,
+          datasets: [{
+            data: renderData,
+            borderColor: color,
+            borderWidth: 1,
+            pointRadius: 0,
+            tension: 0,
+          }],
+        },
+        options: {
+          animation: false,
+          responsive: true,
+          maintainAspectRatio: false,
+          plugins: {
+            legend: { display: false },
+            tooltip: {
+              mode: 'index',
+              intersect: false,
+              callbacks: {
+                title: items => `t = ${items[0].label} ms`,
+                label: item => tooltipFmt(item.raw),
+              },
+            },
+          },
+          scales: {
+            x: {
+              type: 'category',
+              ticks: {
+                color: '#484f58',
+                maxTicksLimit: 10,
+                maxRotation: 0,
+                callback: (val, i) => renderTimes[i] + ' ms',
+              },
+              grid: { color: '#21262d' },
+            },
+            y: {
+              ticks: {
+                color: '#484f58',
+                maxTicksLimit: 5,
+                callback: v => tickFmt(v),
+              },
+              grid: { color: '#21262d' },
+              title: {
+                display: true,
+                text: yUnit,
+                color: '#484f58',
+                font: { size: 10 },
+              },
+            },
+          },
+        },
+        plugins: [{
+          // Draw trigger line at t=0
+          id: 'triggerLine',
+          afterDraw(chart) {
+            const ctx   = chart.ctx;
+            const xAxis = chart.scales.x;
+            const yAxis = chart.scales.y;
+
+            // Find index of t=0
+            const zeroIdx = renderTimes.findIndex(t => parseFloat(t) >= 0);
+            if (zeroIdx < 0) return;
+
+            const x = xAxis.getPixelForValue(zeroIdx);
+            ctx.save();
+            ctx.beginPath();
+            ctx.moveTo(x, yAxis.top);
+            ctx.lineTo(x, yAxis.bottom);
+            ctx.strokeStyle = 'rgba(248, 81, 73, 0.7)';
+            ctx.lineWidth = 1.5;
+            ctx.setLineDash([4, 3]);
+            ctx.stroke();
+            ctx.restore();
+          },
+        }],
+      });
+
+      charts[ch] = chart;
+    }
+  }
+
+  // Auto-detect API base from wherever this page was served from
+  document.getElementById('api-base').value = window.location.origin;
+
+  // Allow Enter key on connection inputs to trigger connect
+  ['api-base', 'dev-host', 'dev-tcp-port'].forEach(id => {
+    document.getElementById(id).addEventListener('keydown', e => {
+      if (e.key === 'Enter') connectUnit();
+    });
+  });
+</script>
+</body>
+</html>

tests/test_write_frames.py

@@ -0,0 +1,436 @@
+"""
+test_write_frames.py — Verify write frame construction against BW capture.
+
+Validates that build_bw_write_frame() reproduces the exact wire bytes that
+Blastware sent during the 3-11-26/170151 compliance-config write session.
+
+Frames tested (BW TX frame indices 102–112):
+  102 — SUB 0x68 event index write
+  103 — SUB 0x73 confirm B
+  104 — SUB 0x71 compliance write chunk 1
+  105 — SUB 0x71 compliance write chunk 2
+  106 — SUB 0x71 compliance write chunk 3
+  107 — SUB 0x72 confirm A
+  108 — SUB 0x82 trigger config write
+  109 — SUB 0x83 trigger confirm
+  110 — SUB 0x69 waveform data write
+  111 — SUB 0x74 confirm C
+  112 — SUB 0x72 confirm A (end of sequence)
+
+Run:
+    python -m pytest tests/test_write_frames.py -v
+or:
+    python tests/test_write_frames.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import pytest
+
+# Allow running from the project root without installation
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from minimateplus.framing import build_bw_write_frame
+
+
+# ── Capture loading ────────────────────────────────────────────────────────────
+
+CAPTURE_PATH = os.path.join(
+    os.path.dirname(__file__),
+    "..",
+    "bridges",
+    "captures",
+    "3-11-26",
+    "raw_bw_20260311_170151.bin",
+)
+
+
+def _load_bw_frames(path: str) -> list[bytes]:
+    """
+    Parse a raw BW capture file into a list of BW frames.
+
+    BW frames start with ACK=0x41 followed by STX=0x02.  The frame boundary is
+    the position of the NEXT 0x41 0x02 sequence (the ETX=0x03 terminator is the
+    last byte before the next frame start).
+
+    NOTE: A naive scan for ETX=0x03 fails because 0x03 can appear inside the
+    DLE-stuffed payload.  This parser uses consecutive 0x41 0x02 starts as
+    boundaries, which is safe because the ACK byte (0x41) is never DLE-stuffed.
+    """
+    with open(path, "rb") as f:
+        raw = f.read()
+
+    boundaries: list[int] = []
+    i = 0
+    while i < len(raw) - 1:
+        if raw[i] == 0x41 and raw[i + 1] == 0x02:
+            boundaries.append(i)
+        i += 1
+    boundaries.append(len(raw))
+
+    frames = []
+    for k in range(len(boundaries) - 1):
+        frames.append(raw[boundaries[k] : boundaries[k + 1]])
+    return frames
+
+
+def _destuff(data: bytes) -> bytes:
+    """Undo DLE stuffing: replace every 0x10 0x10 pair with a single 0x10."""
+    result = bytearray()
+    k = 0
+    while k < len(data):
+        if data[k] == 0x10 and k + 1 < len(data) and data[k + 1] == 0x10:
+            result.append(0x10)
+            k += 2
+        else:
+            result.append(data[k])
+            k += 1
+    return bytes(result)
+
+
+def _decode_bw_frame(wire: bytes) -> tuple[int, int, bytes, bytes, int]:
+    """
+    Decode a BW wire frame into its components.
+
+    Returns:
+        (sub, offset, params, data, chk)
+          sub    — SUB byte (payload[2])
+          offset — uint16 from payload[4:6]
+          params — 10-byte params field (payload[6:16])
+          data   — write payload bytes (payload[16:-1])
+          chk    — checksum byte (payload[-1])
+    """
+    inner = wire[2:-1]          # strip ACK+STX and trailing ETX
+    payload = _destuff(inner)
+    sub    = payload[2]
+    offset = (payload[4] << 8) | payload[5]
+    params = payload[6:16]
+    data   = payload[16:-1]
+    chk    = payload[-1]
+    return sub, offset, params, data, chk
+
+
+# ── Test fixtures ──────────────────────────────────────────────────────────────
+
+@pytest.fixture(scope="module")
+def bw_frames() -> list[bytes]:
+    if not os.path.exists(CAPTURE_PATH):
+        pytest.skip(f"Capture file not found: {CAPTURE_PATH}")
+    return _load_bw_frames(CAPTURE_PATH)
+
+
+# ── Individual frame tests ─────────────────────────────────────────────────────
+
+class TestWriteFrameReconstruction:
+    """Verify build_bw_write_frame() reproduces the exact wire bytes from the capture."""
+
+    def test_frame_102_event_index_write_sub68(self, bw_frames: list[bytes]) -> None:
+        """SUB 0x68 — event index write (frame 102)."""
+        cap_wire = bw_frames[102]
+        sub_cap, offset_cap, params_cap, data_cap, chk_cap = _decode_bw_frame(cap_wire)
+
+        assert sub_cap == 0x68
+        assert params_cap == bytes(10)
+
+        # Reconstruct using build_bw_write_frame with the same data and offset
+        built = build_bw_write_frame(0x68, data_cap, offset=offset_cap, params=params_cap)
+        assert built == cap_wire, (
+            f"SUB 0x68 wire mismatch\n"
+            f"  built: {built.hex()}\n"
+            f"  capt:  {cap_wire.hex()}"
+        )
+
+    def test_frame_103_confirm_b_sub73(self, bw_frames: list[bytes]) -> None:
+        """SUB 0x73 — confirm B (zero-data confirm frame 103)."""
+        cap_wire = bw_frames[103]
+        sub_cap, offset_cap, params_cap, data_cap, _ = _decode_bw_frame(cap_wire)
+
+        assert sub_cap == 0x73
+        assert data_cap == b""
+        assert offset_cap == 0x0000
+
+        built = build_bw_write_frame(0x73, b"")
+        assert built == cap_wire
+
+    def test_frame_104_compliance_chunk1_sub71(self, bw_frames: list[bytes]) -> None:
+        """SUB 0x71 chunk 1 — 1027-byte compliance write (frame 104)."""
+        cap_wire = bw_frames[104]
+        sub_cap, offset_cap, params_cap, data_cap, _ = _decode_bw_frame(cap_wire)
+
+        assert sub_cap == 0x71
+        assert offset_cap == 0x1004
+        assert params_cap == bytes(10)
+        assert len(data_cap) == 1027
+
+        built = build_bw_write_frame(
+            0x71, data_cap,
+            offset=0x1004,
+            params=bytes(10),
+        )
+        assert built == cap_wire
+
+    def test_frame_105_compliance_chunk2_sub71(self, bw_frames: list[bytes]) -> None:
+        """SUB 0x71 chunk 2 — 1055-byte compliance write (frame 105)."""
+        cap_wire = bw_frames[105]
+        sub_cap, offset_cap, params_cap, data_cap, _ = _decode_bw_frame(cap_wire)
+
+        _CHUNK2_PARAMS = bytes([0x00, 0x00, 0x00, 0x10, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00])
+
+        assert sub_cap == 0x71
+        assert offset_cap == 0x1004
+        assert params_cap == _CHUNK2_PARAMS
+        assert len(data_cap) == 1055
+
+        built = build_bw_write_frame(
+            0x71, data_cap,
+            offset=0x1004,
+            params=_CHUNK2_PARAMS,
+        )
+        assert built == cap_wire
+
+    def test_frame_106_compliance_chunk3_sub71(self, bw_frames: list[bytes]) -> None:
+        """SUB 0x71 chunk 3 — 46-byte compliance write (frame 106)."""
+        cap_wire = bw_frames[106]
+        sub_cap, offset_cap, params_cap, data_cap, _ = _decode_bw_frame(cap_wire)
+
+        _CHUNK3_PARAMS = bytes([0x00, 0x00, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
+
+        assert sub_cap == 0x71
+        assert offset_cap == 0x002C
+        assert params_cap == _CHUNK3_PARAMS
+        assert len(data_cap) == 46
+
+        built = build_bw_write_frame(
+            0x71, data_cap,
+            offset=0x002C,
+            params=_CHUNK3_PARAMS,
+        )
+        assert built == cap_wire
+
+    def test_frame_107_confirm_a_sub72(self, bw_frames: list[bytes]) -> None:
+        """SUB 0x72 — confirm A after compliance write (frame 107)."""
+        cap_wire = bw_frames[107]
+        sub_cap, offset_cap, params_cap, data_cap, _ = _decode_bw_frame(cap_wire)
+
+        assert sub_cap == 0x72
+        assert data_cap == b""
+        assert offset_cap == 0x0000
+
+        built = build_bw_write_frame(0x72, b"")
+        assert built == cap_wire
+
+    def test_frame_108_trigger_config_write_sub82(self, bw_frames: list[bytes]) -> None:
+        """SUB 0x82 — trigger config write (frame 108)."""
+        cap_wire = bw_frames[108]
+        sub_cap, offset_cap, params_cap, data_cap, _ = _decode_bw_frame(cap_wire)
+
+        assert sub_cap == 0x82
+        assert params_cap == bytes(10)
+        assert len(data_cap) == 29
+
+        # Verify offset formula: data[1] + 2
+        assert offset_cap == data_cap[1] + 2, (
+            f"Trigger write offset formula mismatch: "
+            f"data[1]={data_cap[1]} → expected {data_cap[1]+2}, got {offset_cap}"
+        )
+
+        built = build_bw_write_frame(
+            0x82, data_cap,
+            offset=offset_cap,
+            params=params_cap,
+        )
+        assert built == cap_wire
+
+    def test_frame_109_trigger_confirm_sub83(self, bw_frames: list[bytes]) -> None:
+        """SUB 0x83 — trigger confirm (frame 109)."""
+        cap_wire = bw_frames[109]
+        sub_cap, _, _, data_cap, _ = _decode_bw_frame(cap_wire)
+
+        assert sub_cap == 0x83
+        assert data_cap == b""
+
+        built = build_bw_write_frame(0x83, b"")
+        assert built == cap_wire
+
+    def test_frame_110_waveform_data_write_sub69(self, bw_frames: list[bytes]) -> None:
+        """SUB 0x69 — waveform data write (frame 110)."""
+        cap_wire = bw_frames[110]
+        sub_cap, offset_cap, params_cap, data_cap, _ = _decode_bw_frame(cap_wire)
+
+        assert sub_cap == 0x69
+        assert params_cap == bytes(10)
+        assert len(data_cap) == 204
+
+        # Verify offset formula: data[1] + 2
+        assert offset_cap == data_cap[1] + 2, (
+            f"Waveform write offset formula mismatch: "
+            f"data[1]={data_cap[1]} → expected {data_cap[1]+2}, got {offset_cap}"
+        )
+
+        built = build_bw_write_frame(
+            0x69, data_cap,
+            offset=offset_cap,
+            params=params_cap,
+        )
+        assert built == cap_wire
+
+    def test_frame_111_confirm_c_sub74(self, bw_frames: list[bytes]) -> None:
+        """SUB 0x74 — confirm C after waveform data write (frame 111)."""
+        cap_wire = bw_frames[111]
+        sub_cap, _, _, data_cap, _ = _decode_bw_frame(cap_wire)
+
+        assert sub_cap == 0x74
+        assert data_cap == b""
+
+        built = build_bw_write_frame(0x74, b"")
+        assert built == cap_wire
+
+    def test_frame_112_confirm_a_sub72_end(self, bw_frames: list[bytes]) -> None:
+        """SUB 0x72 — final confirm A at end of write sequence (frame 112)."""
+        cap_wire = bw_frames[112]
+        sub_cap, _, _, data_cap, _ = _decode_bw_frame(cap_wire)
+
+        assert sub_cap == 0x72
+        assert data_cap == b""
+
+        built = build_bw_write_frame(0x72, b"")
+        assert built == cap_wire
+
+
+class TestOffsetFormula:
+    """Verify the offset = data[1] + 2 formula for single-chunk write commands."""
+
+    def test_event_index_offset_formula(self, bw_frames: list[bytes]) -> None:
+        """Frame 102 (SUB 0x68): offset = data[1] + 2."""
+        _, offset_cap, _, data_cap, _ = _decode_bw_frame(bw_frames[102])
+        assert offset_cap == data_cap[1] + 2
+
+    def test_trigger_config_offset_formula(self, bw_frames: list[bytes]) -> None:
+        """Frame 108 (SUB 0x82): offset = data[1] + 2."""
+        _, offset_cap, _, data_cap, _ = _decode_bw_frame(bw_frames[108])
+        assert offset_cap == data_cap[1] + 2
+
+    def test_waveform_data_offset_formula(self, bw_frames: list[bytes]) -> None:
+        """Frame 110 (SUB 0x69): offset = data[1] + 2."""
+        _, offset_cap, _, data_cap, _ = _decode_bw_frame(bw_frames[110])
+        assert offset_cap == data_cap[1] + 2
+
+
+class TestChecksumVerification:
+    """Verify large-frame DLE-aware checksum for all write frames."""
+
+    def _verify_checksum(self, wire: bytes, label: str) -> None:
+        inner = wire[2:-1]
+        payload = _destuff(inner)
+        chk = payload[-1]
+        computed = (sum(b for b in payload[2:-1] if b != 0x10) + 0x10) & 0xFF
+        assert computed == chk, (
+            f"{label}: checksum mismatch — computed=0x{computed:02X}, got=0x{chk:02X}"
+        )
+
+    def test_all_write_frame_checksums(self, bw_frames: list[bytes]) -> None:
+        write_frames = {
+            102: "SUB 0x68 event index write",
+            103: "SUB 0x73 confirm B",
+            104: "SUB 0x71 compliance chunk 1",
+            105: "SUB 0x71 compliance chunk 2",
+            106: "SUB 0x71 compliance chunk 3",
+            107: "SUB 0x72 confirm A",
+            108: "SUB 0x82 trigger config write",
+            109: "SUB 0x83 trigger confirm",
+            110: "SUB 0x69 waveform data write",
+            111: "SUB 0x74 confirm C",
+            112: "SUB 0x72 confirm A (end)",
+        }
+        for idx, label in write_frames.items():
+            self._verify_checksum(bw_frames[idx], f"Frame {idx} ({label})")
+
+
+class TestComplianceChunkSizes:
+    """Verify compliance write chunk sizes and sequence."""
+
+    def test_chunk1_size(self, bw_frames: list[bytes]) -> None:
+        _, _, _, data, _ = _decode_bw_frame(bw_frames[104])
+        assert len(data) == 1027, f"Chunk 1 should be 1027 bytes, got {len(data)}"
+
+    def test_chunk2_size(self, bw_frames: list[bytes]) -> None:
+        _, _, _, data, _ = _decode_bw_frame(bw_frames[105])
+        assert len(data) == 1055, f"Chunk 2 should be 1055 bytes, got {len(data)}"
+
+    def test_chunk3_size(self, bw_frames: list[bytes]) -> None:
+        _, _, _, data, _ = _decode_bw_frame(bw_frames[106])
+        assert len(data) == 46, f"Chunk 3 should be 46 bytes, got {len(data)}"
+
+    def test_total_compliance_data(self, bw_frames: list[bytes]) -> None:
+        total = sum(
+            len(_decode_bw_frame(bw_frames[i])[3]) for i in [104, 105, 106]
+        )
+        assert total == 2128, f"Total compliance write data should be 2128 bytes, got {total}"
+
+    def test_chunk1_params(self, bw_frames: list[bytes]) -> None:
+        _, _, params, _, _ = _decode_bw_frame(bw_frames[104])
+        assert params == bytes(10)
+
+    def test_chunk2_params(self, bw_frames: list[bytes]) -> None:
+        _, _, params, _, _ = _decode_bw_frame(bw_frames[105])
+        assert params == bytes([0x00, 0x00, 0x00, 0x10, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00])
+
+    def test_chunk3_params(self, bw_frames: list[bytes]) -> None:
+        _, _, params, _, _ = _decode_bw_frame(bw_frames[106])
+        assert params == bytes([0x00, 0x00, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
+
+    def test_chunk1_offset(self, bw_frames: list[bytes]) -> None:
+        _, offset, _, _, _ = _decode_bw_frame(bw_frames[104])
+        assert offset == 0x1004
+
+    def test_chunk2_offset(self, bw_frames: list[bytes]) -> None:
+        _, offset, _, _, _ = _decode_bw_frame(bw_frames[105])
+        assert offset == 0x1004
+
+    def test_chunk3_offset(self, bw_frames: list[bytes]) -> None:
+        _, offset, _, _, _ = _decode_bw_frame(bw_frames[106])
+        assert offset == 0x002C
+
+
+# ── Standalone runner ──────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    if not os.path.exists(CAPTURE_PATH):
+        print(f"ERROR: Capture file not found: {CAPTURE_PATH}")
+        sys.exit(1)
+
+    frames = _load_bw_frames(CAPTURE_PATH)
+    print(f"Loaded {len(frames)} BW frames from capture")
+
+    write_frame_indices = list(range(102, 113))
+    all_pass = True
+    print()
+    print(f"{'Frame':>6}  {'SUB':>5}  {'Offset':>8}  {'DataLen':>8}  {'Chk OK':>7}  {'Rebuilt':>8}")
+    print("-" * 60)
+    for idx in write_frame_indices:
+        wire = frames[idx]
+        sub, offset, params, data, chk = _decode_bw_frame(wire)
+        payload = _destuff(wire[2:-1])
+        computed = (sum(b for b in payload[2:-1] if b != 0x10) + 0x10) & 0xFF
+        chk_ok = computed == chk
+
+        built = build_bw_write_frame(sub, data, offset=offset, params=params)
+        rebuilt_ok = built == wire
+
+        status = "✅" if (chk_ok and rebuilt_ok) else "❌"
+        print(
+            f"  {idx:4d}   0x{sub:02X}  0x{offset:04X}  {len(data):8d}  "
+            f"{'✅' if chk_ok else '❌':>7}  {'✅' if rebuilt_ok else '❌':>8}  {status}"
+        )
+        if not (chk_ok and rebuilt_ok):
+            all_pass = False
+
+    print()
+    if all_pass:
+        print("All 11 write frames verified ✅")
+    else:
+        print("FAILURES DETECTED ❌")
+        sys.exit(1)