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.

CHANGELOG.md

@@ -4,6 +4,59 @@ 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

CLAUDE.md

@@ -118,21 +118,29 @@ S3→BW (response):
 Both differences confirmed by reproducing Blastware's exact wire bytes from the 1-2-26
 BW TX capture. All 10 frames verified.
 
-### SUB 5A — chunk counter is monotonic (CORRECTED 2026-04-06)
+### SUB 5A — chunk counter formula (FINAL CORRECTION 2026-04-26)
 
-**Chunk counters are `chunk_num * 0x0400` for ALL chunks including chunk 1.**
+**Chunk counter = `max(key4[2:4], 0x0400) + (chunk_num - 1) * 0x0400` for ALL chunks.**
 
-The 4-2-26 BW TX capture showed `counter=0x1004` for chunk 1 of event key `01110000`, which
-led to `_CHUNK1_COUNTER = 0x1004` being hardcoded as a special case. This was a Blastware
-artifact, not a protocol requirement. Empirical test 2026-04-06: with `counter=0x1004` for
-chunk 1 the device times out (120 s); with `counter=0x0400` (= `1 * 0x0400`) it responds
-immediately and streams all frames correctly.
+where `key4[2:4] = (key4[2] << 8) | key4[3]` is the event's circular-buffer base offset.
 
-The 4-3-26 capture confirms the pattern for a second event (key `0111245a`):
-chunk 1 = `0x245A`, chunk 2 = `0x285A`, chunk 3 = `0x2C5A` (each +0x0400). Blastware's
-true formula is `key4[2:4] + n * 0x0400` — but since `key4[2:4]` of the first event is
-`0x0000`, `n * 0x0400` produces the right result. The device does not strictly validate the
-counter and streams data for any valid 5A request; using `chunk_num * 0x0400` is correct.
+The `max(..., 0x0400)` guard is critical for events at the start of the circular buffer
+(key4[2:4] == 0x0000, e.g. key `01110000`). Without it, chunk 1 gets counter=0x0000, which
+is the same address as the probe frame — the device re-returns the STRT record data instead
+of waveform payload. With the guard, chunk 1 gets counter=0x0400, which is confirmed correct
+from the empirical live-device test 2026-04-06 (`counter=0x0400 → responds immediately and
+streams all frames correctly`).
+
+The 4-3-26 capture confirms the pattern for a second event (key `0111245a`, key4[2:4]=0x245a):
+chunk 1 = `0x245A`, chunk 2 = `0x285A`, chunk 3 = `0x2C5A` (each +0x0400).
+`max(0x245a, 0x0400) = 0x245a` → formula works correctly for non-zero base offset too.
+
+**History:**
+- Original: `_CHUNK1_COUNTER = 0x1004` hardcoded (Blastware capture artifact — WRONG).
+- 2026-04-06: Corrected to `chunk_num * 0x0400` (worked for key 01110000 only).
+- 2026-04-24: Corrected to `key4[2:4] + (chunk_num-1) * 0x0400` (fixed non-zero offsets,
+  but accidentally broke key 01110000 — counter=0x0000 sends probe address again).
+- 2026-04-26: Final formula: `max(key4[2:4], 0x0400) + (chunk_num-1) * 0x0400`.
 
 ### SUB 5A — params are 11 bytes for chunk frames, 10 for termination
 
@@ -339,6 +347,36 @@ Do NOT use fixed absolute offsets for sample_rate or record_time.
   Quiet Mode enabled. Parser handles this — do not strip it manually before feeding to
   `S3FrameParser`.
 
+**SUB 5A (bulk waveform) TCP frame splitting — confirmed 2026-04-27:**
+
+Over TCP via cellular modem, each 5A chunk request that produces a single ~1100-byte
+A5 response over direct RS-232 may arrive as **two separate, complete S3 frames** of
+~550 bytes each ("2-frame mode").  The modem's Data Forwarding Timeout (~100-150 ms)
+can split the RS-232 response into two TCP segments, each parsed as a complete S3 frame.
+Under different modem/timing conditions the full ~1100-byte response arrives as **one
+S3 frame** ("1-frame mode").
+
+**Both modes require `extra_chunks_after_metadata=1`** (the extra chunk at metadata_counter
++ 0x0400).  The device's waveform footer data lives at circular-buffer address 0x1C00 for
+this event; the terminator frame must be sent at 0x1C00 (not 0x1800) to receive it.
+
+Example for a 2-second Continuous event (BE11529, key=01110000) via TCP:
+- **2-frame mode:** 1 probe frame (554 B) + 5 chunks × 2 frames (556-573 B) + 1 extra chunk × 2 frames + 1 terminator (208 B) = **14 A5 frames** → 6864-byte file
+- **1-frame mode:** 1 probe frame (~1097 B) + 5 chunks × 1 frame (~1079-1113 B) + 1 extra chunk × 1 frame (smaller, tail of event) + 1 terminator → **8 A5 frames** → 6864-byte file
+- All frames contribute body data; using all of them gives the correct file.
+
+**Fix (confirmed 2026-04-27):**  `_recv_5a_batch()` in `protocol.py` collects ALL
+A5 frames per chunk request before the next request is sent, using a 0.5 s batch
+timeout after the first frame to catch the ~150 ms delayed second frame.  `write_blastware_file()`
+includes ALL body frames without skipping — the extra chunk's frames are part of the
+body data, NOT padding to be discarded.
+
+**WRONG earlier hypothesis (do not re-introduce):** An attempt was made to auto-detect
+1-frame vs 2-frame mode from the probe frame size and skip the extra chunk when
+`probe_data_len >= 700`.  This was wrong — the extra chunk is always needed to advance
+the device's internal state to the footer address.  The `_probe_is_large` branch was
+removed 2026-04-27.
+
 ### Required ACEmanager settings (Sierra Wireless RV50/RV55)
 
 | Setting | Value | Why |
@@ -386,7 +424,9 @@ bytes `\x01\x2c` = 300 (5-minute default histogram interval); changes when inter
 
 | Offset | Field | Format | Notes |
 |---|---|---|---|
-| anchor − 7 (write) / anchor − 8 (read) | recording_mode | uint8 | E5 read has extra `0x10` at anchor−7 |
+| anchor − 9 | mode_prefix | uint8 | `0x00` for Single Shot / Continuous; `0x10` for Histogram (DLE prefix in E5 encoding) and Histogram+Continuous (actual config byte). See "compliance_raw DLE encoding" note below. |
+| anchor − 8 | recording_mode | uint8 | **Same offset for both read and write** — confirmed 2026-04-21. `_encode_compliance_config` writes `buf[anc-8]`. NOTE: for Histogram (0x03), E5 encodes the value as `0x10 0x03` so compliance_raw[anc-9]=0x10, compliance_raw[anc-8]=0x03. |
+| anchor − 7 | constant | `0x10` | Always `0x10` in both E5 read and BW write payloads (not a DLE marker — it is part of the sample_rate field area). Do NOT overwrite. |
 | anchor − 6 | sample_rate | uint16 BE | same in read & write |
 | anchor − 4 | histogram_interval_sec | uint16 BE | seconds; same in read & write ✅ 2026-04-20 |
 | anchor − 2 | `0x00 0x00` | padding | |
@@ -395,15 +435,42 @@ bytes `\x01\x2c` = 300 (5-minute default histogram interval); changes when inter
 
 **recording_mode enum** (confirmed 2026-04-20 from 4-20-26 captures):
 
-| Value | Mode |
-|---|---|
-| `0x00` | Single Shot |
-| `0x01` | Continuous |
-| `0x02` | ❓ not observed |
-| `0x03` | Histogram |
-| `0x04` | Histogram + Continuous |
+| Value | Mode | anchor-9 in compliance_raw |
+|---|---|---|
+| `0x00` | Single Shot | `0x00` |
+| `0x01` | Continuous | `0x00` |
+| `0x02` | ❓ not observed | ❓ |
+| `0x03` | Histogram | `0x10` (DLE prefix from E5 wire encoding of 0x03) |
+| `0x04` | Histogram + Continuous | `0x10` (actual config byte for this mode) |
 
-**DLE escaping in write frames — CONFIRMED 2026-04-20:** Write frame data payloads DO escape `0x03` (ETX) bytes with a `0x10` DLE prefix. For histogram_interval = 900 (0x0384), the wire carries `10 03 84` — the `0x03` high byte is preceded by a DLE escape. After DLE destuffing (`10 XX → XX`), the logical field value is correctly `03 84` = 900. The CLAUDE.md claim that write frame data is "written RAW" was incorrect; at minimum ETX (0x03) bytes are escaped. S3FrameParser handles this transparently so the decoded `compliance_raw` always contains logical (destuffed) bytes.
+**compliance_raw DLE encoding — IMPORTANT (confirmed 2026-04-21 from 4-20-26 captures):**
+`compliance_raw` (returned by `read_compliance_config()`) is NOT purely logical bytes — it is
+the wire-encoded representation where `0x03` bytes in the config are preceded by a `0x10` DLE
+prefix (because S3FrameParser preserves DLE+ETX inner-frame pairs as two literal bytes).
+
+Consequences:
+- When recording_mode = `0x03` (Histogram), `compliance_raw[anc-9] = 0x10` (DLE prefix) and
+  `compliance_raw[anc-8] = 0x03` (the value). The anchor position is +1 compared to modes
+  without `0x03` bytes before the anchor.
+- For Histogram+Continuous (`0x04`), `compliance_raw[anc-9] = 0x10` for a different reason:
+  it is an actual stored config byte, not a DLE prefix.
+- The anchor search (`buf.find(b'\xbe\x80\x00\x00\x00\x00', 0, 150)`) correctly locates
+  the anchor regardless of these mode-dependent shifts.
+- When SFM writes recording_mode and round-trips the rest verbatim, the byte at `anc-9` is
+  preserved from the previous read. This means transitioning Histogram→other modes via SFM
+  leaves a `0x10` at `anc-9`. The device stores it as a literal byte; it does not affect
+  recording mode operation (which is at `anc-8`), but differs from what BW writes. This is a
+  known minor discrepancy that does not impact device behavior.
+- **Histogram recording mode (0x03) write via SFM**: untested. When starting from a mode with
+  `anc-9 = 0x00`, SFM writes bare `0x03` at anc-8. BW would write `0x10 0x03`. Device likely
+  accepts both (write frames probably use offset/length for framing, not ETX scanning).
+
+**DLE escaping in write frames — confirmed 2026-04-20:** Blastware escapes `0x03` bytes in
+write frame data as `0x10 0x03` on the wire (defensive ETX escaping). Our `build_bw_write_frame`
+does NOT do this escaping — it sends data bytes raw. Device acceptance of bare `0x03` bytes
+in write frame data is confirmed for the tested modes (Single Shot, Continuous, Histogram+Continuous
+where `0x10 0x03` already appears from round-tripping). Histogram mode (bare `0x03` write from
+non-Histogram starting state) has not been directly tested.
 
 ### SUB 0C — Waveform Record (210 bytes = data[11:11+0xD2])
 
@@ -1067,9 +1134,53 @@ body) because writing a dial string may require DLE escaping for embedded contro
 
 - **Database** — SQLite store for events + monitor log entries; dedup by key; queryable
 - **Histograms** — decode histogram-mode A5 data (noise floor tracking)
+- **Blastware-compatible file output** — `write_blastware_file()` and `write_mlg()` implemented. `blastware_filename()` generates correct Blastware filenames (AB0 for direct, AB0W/AB0H for ACH). **Confirmed working for Continuous mode events (2026-04-23):** SFM-generated file opens in Blastware, shows correct PPV/waveform/timestamp. File is ~200 bytes shorter than BW (missing last ADC tail slice) — all measurements correct. Histogram+Continuous mode deferred (5A stream for those events embeds histogram interval records that create spurious STRT markers in the body). Extension mapping: **CONFIRMED FALSE 2026-04-21** — extensions encode timestamp (AB0T for ACH, AB0 for direct), NOT recording mode. Filename format: `<prefix_letter><serial3><4-char-base36-stem><ext>`
+
+  **Serial encoding (CONFIRMED 2026-04-22):** `prefix_letter = chr(ord('B') + floor(serial_numeric / 1000))`, `serial3 = f"{serial_numeric % 1000:03d}"`. Examples: BE6907→H907, BE11529→M529, BE14036→P036, BE17353→S353, BE18003→T003. The prefix letter encodes the production generation (batch of 1000 units).
+
+  **Stem encoding (FULLY CONFIRMED 2026-04-22):** stem = 4-char base-36 of `floor(total_seconds / 1296)` where `total_seconds = (event_local_time − 1985-01-01T00:00:00_local)` in seconds. Epoch = `1985-01-01 00:00:00` device local time — confirmed against 3,248 files from 10-year production archive with zero errors. Decode: `event_time = datetime(1985,1,1) + timedelta(seconds=stem_int*1296 + ab_int)`. Example: P036L318.C80H → BE14036, 2025-05-26 15:00:08, Full Histogram.
+- **Blastware filename extension — NEW FIRMWARE FULLY DECODED (confirmed 2026-04-21, further confirmed 2026-04-22 from 10-year production archive frequency analysis):**
+
+  Extension format = `AB0T` (4 chars):
+  - `AB` = 2-char base-36 encoding of `total_seconds % 1296` (seconds within the 21.6-min window, 0–1295); `A = value // 36`, `B = value % 36`
+  - `0` = always literal digit zero (third character, invariant)
+  - `T` = event type: `W` = Full Waveform, `H` = Full Histogram
+
+  Combined with the 4-char stem, the full filename encodes a complete second-resolution timestamp. Verified against three S353L4H0.{3M0W,8S0H,9X0W} events (all match to the second) plus large-scale frequency analysis of a 10-year archive.
+
+  **3-day cycle property (confirmed 2026-04-22):** A unit recording at a fixed daily time cycles through exactly **3 extensions** with a 3-day period. Each calendar day shifts `total_seconds % 1296` by 864 (since `86400 % 1296 = 864`). The cycle repeats every 3 days because `gcd(1296, 864) = 432` and `1296 / 432 = 3`. The three extension values are spaced 432 seconds apart. Confirmed from 10-year archive: the top 3 extensions overall were `CE0H` (95 files), `0E0H` (93), `OE0H` (91) — all three are the 3-day cycle of a 06:00:14 daily call-in time (seconds-in-window = 14, 446, 878; all three have `E` as second character because `14 = E` in base-36 and adding 864 never changes `value % 36` since `864 = 24 × 36`).
+
+  **B character invariance:** For a unit recording at a fixed time of day, the second character `B` of the extension (`value % 36`) **never changes** — only the first character `A` cycles through 3 values. This means same-time-of-day files from different dates all share the same `B` character.
+
+  **Old firmware (S338, 3-char extensions ending in `0`):** encoding unknown. Extension is NOT recording mode. `blastware_filename()` returns `.N00` as a placeholder for old-firmware units.
+
+  **Micromate Series 4** uses a different extension format entirely (observed: `IDFH`, `IDFW`). The `AB0T` formula applies only to MiniMate Plus / V10.72 firmware.
 - Compliance config encoder — build raw write payloads from a `ComplianceConfig` object
+- **Test Histogram recording mode (0x03) write via SFM** — confirmed working for Single Shot / Continuous / Histogram+Continuous; Histogram (0x03) needs a live test from a non-Histogram starting state (bare 0x03 in write vs BW's DLE-escaped `10 03`)
+- **Compliance write anchor-9 cleanup** — when changing recording_mode via SFM, the byte at anchor-9 is not explicitly managed. A spurious `0x10` may persist after Histogram→other mode transitions. Does not affect device operation but differs from BW's byte-perfect output.
 - Locate "Sensor Check" byte in compliance config (need capture with Disabled vs Before-monitoring)
 - Call Home — map time slots 3/4 offsets; add dial_string write support; confirm `modem_power_relay_enabled`
 - Modem manager — push RV50/RV55 configs via Sierra Wireless API
 - RV55 DCD/DTR issue — newer RV55 firmware doesn't assert DCD by default; units don't
-  resume monitoring after call-home disconnect (`--restart-monitoring` flag deferred)
+  resume monitoring after call-home disconnect (`--restart-monitoring` flag deferred)
+
+## BW capture reference
+
+`bridges/captures/` contains the following BW TX + S3 response captures for protocol analysis:
+
+| Folder / File | Contents |
+|---|---|
+| `3-11-26/raw_bw_20260311_170151.bin` | Full compliance write + event download (SUBs 68→83 confirmed, frames 102–112) |
+| `4-20-26/raw_bw_*_recording_mode_*.bin` | Recording mode changes: Continuous→Single Shot, →Histogram, →Histogram+Continuous |
+| `4-20-26/histogram interval/` | Histogram interval changes: 1min, 5min, 15min, 15sec |
+| `4-20-26/geo sensitivity/` | Geo sensitivity changes: 1.25 in/s (Sensitive), 10 in/s (Normal) |
+| `4-20-26/call home settings/` | Call home config read/write captures |
+| `4-8-26/` | Monitor status read, start/stop monitoring, SESSION_RESET signal, sensor check |
+| `4-3-26-multi_event/` | Browse-mode S3 capture with 2+ events (1E/0A/1F iteration confirmed) |
+| `4-2-26/` | Download-mode BW TX capture (5A bulk stream, POLL×3 requirement confirmed) |
+| `3-31-26/` | Single-event download (148 BW / 147 S3 frames) |
+| `mitm/ach_mitm_20260411_001912/` | Full ACH call-home MITM (erase protocol, 0xA3/0x06/0xA2 confirmed) |
+
+To parse BW TX captures: use `bridges/captures/` scripts or adapt the `find_write_frames()` pattern
+in `/tmp/analyze_write_payload.py` — it correctly handles `0x10 0x03` DLE-escaped ETX bytes
+inside write frame data (the naive parser terminates early at the escaped `0x03`).

bridges/ach_server.py

@@ -35,6 +35,7 @@ Output per session
     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
@@ -172,16 +173,24 @@ class AchSession:
         transport = SocketTransport(self.sock, peer=self.peer)
 
         # Collect raw bytes in memory until startup succeeds, then flush to disk.
-        raw_buf: list[bytes] = []
-        _orig_read = transport.read
+        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_buf.append(data)
+                raw_rx_buf.append(data)
             return data
 
-        transport.read = tapped_read  # type: ignore[method-assign]
+        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
 
@@ -201,23 +210,35 @@ class AchSession:
         # 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_path = session_dir / f"raw_rx_{ts}.bin"
+        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 raw bytes to file and switch to direct file writes.
-        raw_fh = open(raw_path, "wb")
-        for chunk in raw_buf:
-            raw_fh.write(chunk)
-        raw_buf.clear()
+        # 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_fh.write(data)
-                raw_fh.flush()
+                raw_rx_fh.write(data)
+                raw_rx_fh.flush()
             return data
 
-        transport.read = tapped_read_file  # type: ignore[method-assign]
+        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")
@@ -530,7 +551,8 @@ class AchSession:
                     log.warning("  [WARN] Failed to restart monitoring: %s", exc)
 
         finally:
-            raw_fh.close()
+            raw_rx_fh.close()
+            raw_tx_fh.close()
             client.close()  # closes transport / socket cleanly
             root_logger.removeHandler(fh)
             fh.close()

bridges/gui_bridge.py

@@ -58,16 +58,24 @@ class BridgeGUI(tk.Tk):
         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
-        self.raw_bw_var = tk.StringVar(value="")
-        self.raw_s3_var = tk.StringVar(value="")
-        tk.Checkbutton(self, text="Save BW->S3 raw", command=self._toggle_raw_bw, onvalue="1", offvalue="").grid(row=2, column=0, sticky="w", **pad)
-        tk.Entry(self, textvariable=self.raw_bw_var, width=28).grid(row=2, column=1, columnspan=3, sticky="we", **pad)
-        tk.Button(self, text="...", command=lambda: self._choose_file(self.raw_bw_var, "bw")).grid(row=2, column=4, **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="Save S3->BW raw", command=self._toggle_raw_s3, onvalue="1", offvalue="").grid(row=3, column=0, sticky="w", **pad)
-        tk.Entry(self, textvariable=self.raw_s3_var, width=28).grid(row=3, column=1, columnspan=3, sticky="we", **pad)
-        tk.Button(self, text="...", command=lambda: self._choose_file(self.raw_s3_var, "s3")).grid(row=3, column=4, **pad)
+        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")
@@ -102,13 +110,11 @@ class BridgeGUI(tk.Tk):
             var.set(filename)
 
     def _toggle_raw_bw(self) -> None:
-        if not self.raw_bw_var.get():
-            # default name
-            self.raw_bw_var.set(os.path.join(self.logdir_var.get(), "raw_bw.bin"))
+        # Checkbox toggled — no path action needed; enabled state drives the flag.
+        pass
 
     def _toggle_raw_s3(self) -> None:
-        if not self.raw_s3_var.get():
-            self.raw_s3_var.set(os.path.join(self.logdir_var.get(), "raw_s3.bin"))
+        pass
 
     def start_bridge(self) -> None:
         if self.process and self.process.poll() is None:
@@ -126,23 +132,22 @@ class BridgeGUI(tk.Tk):
 
         args = [sys.executable, BRIDGE_PATH, "--bw", bw, "--s3", s3, "--baud", baud, "--logdir", logdir]
 
-        ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+        # 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()
 
-        raw_bw = self.raw_bw_var.get().strip()
-        raw_s3 = self.raw_s3_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 the user left the default generic name, replace with a timestamped one
-        # so each session gets its own file.
-        if raw_bw:
-            if os.path.basename(raw_bw) in ("raw_bw.bin", "raw_bw"):
-                raw_bw = os.path.join(os.path.dirname(raw_bw) or logdir, f"raw_bw_{ts}.bin")
-                self.raw_bw_var.set(raw_bw)
-            args += ["--raw-bw", raw_bw]
-        if raw_s3:
-            if os.path.basename(raw_s3) in ("raw_s3.bin", "raw_s3"):
-                raw_s3 = os.path.join(os.path.dirname(raw_s3) or logdir, f"raw_s3_{ts}.bin")
-                self.raw_s3_var.set(raw_s3)
-            args += ["--raw-s3", raw_s3]
+        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(

bridges/s3-bridge/s3_bridge.py

@@ -390,8 +390,14 @@ def main() -> int:
     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=None, help="Optional file to append raw bytes sent from BW->S3 (no headers)")
-    ap.add_argument("--raw-s3", default=None, help="Optional file to append raw bytes sent from S3->BW (no headers)")
+    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()
@@ -414,12 +420,16 @@ def main() -> int:
     # 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).
-    raw_bw_path = args.raw_bw
-    raw_s3_path = args.raw_s3
-    if raw_bw_path in (None, "", "auto"):
-        raw_bw_path = os.path.join(args.logdir, f"raw_bw_{ts}.bin") if args.raw_bw is not None else None
-    if raw_s3_path in (None, "", "auto"):
-        raw_s3_path = os.path.join(args.logdir, f"raw_s3_{ts}.bin") if args.raw_s3 is not None else None
+    # 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)
 

docs/instantel_protocol_reference.md

@@ -104,7 +104,10 @@
 | 2026-04-11 | §7.11 (NEW) | **NEW — §7.11 Erase-All Protocol added.** Full wire sequence, SUB 0x06 storage range payload layout, post-erase key counter reset (resets to `0x01110000`). Confirmed from 4-11-26 MITM capture of live Blastware ACH session. |
 | 2026-04-11 | §14.6 | **RESOLVED — ACH Session Lifecycle is no longer "Future".** `bridges/ach_server.py` fully implements inbound ACH: POLL handshake, device info, event download. State tracked via `ach_state.json` (key-based, with `max_downloaded_key` for post-erase detection). `--clear-after-download` flag added for the standard delete-after-upload workflow. |
 | 2026-04-17 | §7.6.2, §14 | **RESOLVED — Float 6.206053 at channel_label+28 is the ADC-to-velocity scale factor.** Confirmed from Series III Interface Handbook §4.5 formula: `Range (×1) = 1.61133 V / Sensitivity (V/unit)`. For the standard Instantel geophone at Normal range (10.000 in/s): Sensitivity = 1.61133 / 10 = 0.161133 V/(in/s). The stored value is the **inverse sensitivity** = 1/0.161133 = **6.206053 (in/s)/V**. Cross-check: 1.61133 V × 6.206053 = 10.000 in/s ✅. The firmware uses it as: `PPV (in/s) = ADC_voltage (V) × 6.206053`. Value is identical on all Instantel standard geophones — it is a hardware/firmware constant, NOT a user-configurable setting. Do NOT write this field. Open question §14 item "Max Geo Range float 6.2061" is now **RESOLVED**. |
-| 2026-04-20 | §7.6.4 (NEW), §7.9, Appendix B | **CONFIRMED — Recording Mode byte location.** Three targeted captures (4-20-26) confirmed `recording_mode` at **`cfg[5]`** in the SUB 71 write payload (3-chunk compliance write). Method: single Blastware session, one initial E5 config pull, then three sequential "Send to unit" writes changing Recording Mode only. Diff of SUB 71 chunk-1 payloads: only `cfg[5]` and `cfg[1024]` changed; `cfg[1024]` delta exactly equals `cfg[5]` delta (chunk running checksum). In the E5 read response (sub-frame 1, page=0x0010), the field is at **`data[17]`** (= **anchor − 4** from the 10-byte anchor), one position earlier than in the write payload due to an extra `0x10` byte at `data[18]` present only in the read format. Enum: `0x00`=Single Shot, `0x01`=Continuous, `0x03`=Histogram, `0x04`=Histogram+Continuous. `0x02` value not yet observed. See §7.6.4 for full details. |
+| 2026-04-20 | §7.6.4 (NEW), §7.9, Appendix B | **CONFIRMED — Recording Mode byte location.** Three targeted captures (4-20-26) confirmed `recording_mode` at anchor−8 in both the E5 read payload and the BW write payload (6-byte anchor `\xbe\x80\x00\x00\x00\x00`). BW write payload and E5 read payload are **byte-identical** around the anchor region — Blastware round-trips the wire-encoded E5 bytes verbatim with only the target field modified. Anchor position varies by ±1 depending on whether recording_mode = 0x03 (Histogram), because E5 wire-encodes `0x03` as the inner DLE+ETX pair `\x10\x03` (2 bytes), which S3FrameParser preserves as two literal bytes in `compliance_raw`. Enum: `0x00`=Single Shot, `0x01`=Continuous, `0x03`=Histogram, `0x04`=Histogram+Continuous. `0x02` value not yet observed. The byte at anchor−9 is `0x00` for Single Shot / Continuous, and `0x10` for Histogram (DLE prefix from E5 encoding) and Histogram+Continuous (actual config byte). See §7.6.4 for full details. |
+| 2026-04-21 | Appendix D (NEW) | **NEW — Blastware .N00 and .MLG file formats fully decoded.** `minimateplus/blastware_file.py` implements `write_n00()` and `write_mlg()`. N00 file format confirmed: 22B header + 21B STRT record + variable body + 26B footer. Body reconstructed from A5 bulk waveform stream frames with per-frame skip amounts (probe=7+strt_pos+21, A5[1]=13, A5[2+]=12, terminator=11) and DLE strip rule (strip `0x10` before `{0x02,0x03,0x04}`, keep following byte). Footer extracted verbatim from terminator frame's last 26 bytes. Split-pair edge case: when `frame.data[-1]==0x10` and `chk_byte∈{0x02,0x03,0x04}`, reunite both bytes before stripping and always remove trailing chk_byte (`stripped[:-1]`) — chk_byte is checksum, not payload. STRT record must be copied verbatim from A5[0]; bytes [10:20] are device-specific and cannot be reconstructed from Event fields. `write_n00` verified byte-perfect against `M529LIY6.N00` from 4-3-26-multi_event capture. MLG format: 308B header + N×292B records; CRC algorithm unknown (write as 0x0000). |
+| 2026-04-21 | Appendix D §D.5 (NEW) | **NEW — Blastware filename encoding fully decoded.** Serial prefix: `chr(ord('B') + floor(serial/1000))` + last 3 digits zero-padded. Stem: 4-char base-36 of `floor(total_seconds/1296)`. Extension: `AB0` for manual/direct downloads (3 chars), `AB0W` or `AB0H` for ACH/call-home downloads (4 chars), where `AB` = 2-char base-36 of `total_seconds % 1296` and W/H = waveform/histogram. Epoch = 1985-01-01 00:00:00 device local time. Confirmed against 3,248 files from 10-year production archive with zero errors. 3-day cycle property: same daily recording time cycles through 3 extensions (864s/day shift, period=3 days). `blastware_filename(event, serial, ach=False)` implements full formula. |
+| 2026-04-21 | §7.6.2, §5.3 | **CORRECTED — compliance_raw contains wire-encoded bytes, NOT logical bytes.** S3FrameParser appends DLE+ETX inner-frame pairs as two literal bytes to the frame body. Any `0x03` values in the compliance config appear in `compliance_raw` as `\x10\x03` (two bytes), not as a single `0x03`. The previous claim "S3FrameParser handles this transparently so compliance_raw contains logical (destuffed) bytes" was wrong. Consequence: `compliance_raw` is the wire-encoded E5 payload; anchor-relative reads work correctly because the anchor position automatically accounts for any DLE-encoded bytes before it. For write-back, round-tripping `compliance_raw` verbatim sends the correct wire bytes to the device. **DLE ETX escaping in write frames:** Blastware escapes `0x03` bytes in write frame data as `\x10\x03` on wire; our `build_bw_write_frame` does not (writes data raw). Device is confirmed to accept raw writes for all tested modes — likely uses the offset/length field for write frame framing, not ETX scanning. |
 | 2026-04-20 | §7.6.2, §7.9, Appendix B | **CONFIRMED — Geophone maximum range / sensitivity selector byte location.** Two targeted captures (4-20-26, geo sensitivity folder): one at Normal 10.000 in/s, one at Sensitive 1.250 in/s. E5 read payload diff: exactly 3 bytes differ at channel_label+33 for Tran/Vert/Long. Values: `0x00`=Normal 10.000 in/s, `0x01`=Sensitive 1.250 in/s. Same offset applies to the SUB 71 write payload (which is the same 2126-byte E5-format buffer round-tripped verbatim). **`channel_label+20` reads `0x01` in ALL captures regardless of range setting — it is NOT this field.** Previous hypothesis (uint8 at Tran+20, 0x01=Normal) was WRONG. Stored as `geo_range` in `ComplianceConfig`. Encoded to all three geo channel blocks (Tran/Vert/Long) at label+33. |
 | 2026-04-20 | §5.1, §5.3, §7.12 (NEW) | **NEW — Auto Call Home config protocol confirmed from 4-20-26 call home settings captures.** SUB 0x2C (Call Home Config READ, response 0xD3, data offset 0x7C=124) and SUB 0x7E/0x7F (WRITE + CONFIRM, response 0x81/0x80) confirmed. Write payload = read payload (125 bytes) + `\x00\x00` (127 bytes total). **DLE-escaped ETX at raw[117:119]:** the device returns logical value 0x03 (num_retries=3) as `\x10\x03` on the wire — S3FrameParser preserves both bytes as two literals, causing a +1 byte shift for all subsequent fields. Write frame sends these bytes verbatim (device interprets `\x10\x03` as literal value 3). Field map confirmed from 10-frame BW TX diff. See §7.12 for full layout. |
 
@@ -1228,26 +1231,52 @@ Two critical differences from `build_bw_frame`:
 | Frame | offset_word | counter | params | Purpose |
 |---|---|---|---|---|
 | Probe | `0x1004` | `0x0000` | 10 bytes (`bulk_waveform_params(0)`) | Initiate transfer |
-| Chunk 1 | `0x1004` | `0x0400` | 11 bytes | First data chunk |
-| Chunk 2 | `0x1004` | `0x0800` | 11 bytes | Second chunk |
-| Chunk N | `0x1004` | `N * 0x0400` | 11 bytes | Nth chunk |
+| Chunk 1 | `0x1004` | `max(key4[2:4], 0x0400)` | 11 bytes | First data chunk |
+| Chunk 2 | `0x1004` | `max(key4[2:4], 0x0400) + 0x0400` | 11 bytes | Second chunk |
+| Chunk N | `0x1004` | `max(key4[2:4], 0x0400) + (N-1) * 0x0400` | 11 bytes | Nth chunk |
 | … | … | … | … | … |
-| Termination | `0x005A` | `last + 0x0400` | 10 bytes | End transfer |
+| Termination | `0x005A` | `max(key4[2:4], 0x0400) + N * 0x0400` | 10 bytes | End transfer |
 
-> ⚠️ **2026-04-06 CORRECTED — chunk counter is monotonic for ALL chunks.**
-> The 4-2-26 BW TX capture showed counter=0x1004 for chunk 1, which was hardcoded as a
-> special case. This was a Blastware artifact. Empirically confirmed: counter=0x0400 for
-> chunk 1 works correctly; counter=0x1004 causes the device to time out. The device does
-> NOT strictly validate the counter value — it streams data for any valid 5A request for
-> the given key. Use `chunk_num * 0x0400` (monotonic) for all chunks.
-> BW's true internal formula is `key4[2:4] + n * 0x0400`. For event 1 (key `01110000`)
-> this equals `n * 0x0400` since `key4[2:4] = 0x0000`. The monotonic formula is correct
-> for all keys encountered on this device.
+> ⚠️ **2026-04-06 CORRECTED — chunk counter is `key4[2:4] + (N-1) * 0x0400`.**
+> The 4-2-26 BW TX capture showed counter=0x1004 for chunk 1 of key `01110000`, leading to
+> an interim "monotonic n * 0x0400" formula.  This was accidentally correct because
+> `key4[2:4] == 0x0000` for that event.
+>
+> **2026-04-24 CORRECTION:** The counter is an absolute circular-buffer address.
+> BW's true formula is `key4[2:4] + (chunk_num - 1) * 0x0400` where `key4[2:4]` is the
+> event's storage base offset (`(key4[2]<<8) | key4[3]`).  For keys where
+> `key4[2:4] != 0x0000` (e.g. key `01111884`), using `n * 0x0400` sends requests into the
+> wrong buffer region — the device returns data from a completely different event.
+>
+> **2026-04-26 FINAL CORRECTION:** The formula `key4[2:4] + (N-1) * 0x0400` is wrong when
+> `key4[2:4] == 0x0000` (e.g. event key `01110000`, the very first event after a device erase).
+> Counter=0x0000 for chunk 1 is the same address as the probe frame — the device re-returns
+> the STRT record data instead of waveform payload (frame 1 has len=1097, same as probe, and
+> contains `b"STRT\xff\xfe"`, contributing zero waveform bytes).
+> Final formula: `max(key4[2:4], 0x0400) + (chunk_num - 1) * 0x0400`.
+> For key `01110000`: chunk 1 = 0x0400 (confirmed working, empirical test 2026-04-06).
+> For key `0111245a`: chunk 1 = 0x245a (unchanged, confirmed from 4-3-26 capture).
 
 The `stop_after_metadata=True` flag causes the loop to stop as soon as `b"Project:"` is
-found in the accumulated A5 frame data, typically after 7–9 chunks.  A termination frame
+found in the accumulated A5 frame data, typically after 4–9 chunks.  A termination frame
 is always sent before returning.
 
+**IMPORTANT — one extra chunk required after "Project:" for valid file footer (confirmed 2026-04-23):**
+When writing a Blastware-compatible waveform file, stopping immediately at "Project:" and
+sending termination produces an empty termination response with no footer bytes (`0e 08`
+marker missing).  Blastware downloads exactly **one more chunk** after finding "Project:"
+before sending termination — that extra chunk primes the device to return valid footer
+bytes (monitoring start/stop timestamps) in the termination response.
+
+`read_bulk_waveform_stream(stop_after_metadata=True)` implements this: after the "Project:"
+chunk is received, one additional chunk is requested before breaking.  The termination
+response (`include_terminator=True`) then contains the correct `0e 08` footer.
+
+**do NOT use `full_waveform=True` for Blastware file writing** — for events with long
+post-event silence (35 chunks), the silence chunks contain embedded device-internal
+pointer structures that produce spurious STRT markers in the file body.  Blastware only
+downloads 4–5 chunks (metadata + one signal chunk) regardless of event length.
+
 #### 7.8.3 A5 Frame Layout
 
 Each A5 response frame contains a chunk of raw bulk data. Frame 7 of the stream carries the
@@ -2244,6 +2273,279 @@ Semantic Interpretation           <- settings, events, responses
 
 ---
 
+---
+
+## Appendix D — Blastware Binary File Formats (.N00 / .MLG / others)
+
+> ✅ CONFIRMED 2026-04-21 — all fields verified by binary diff of reconstructed vs reference
+> files from the 4-3-26-multi_event capture (M529LIY6.N00, BE11529.MLG).
+>
+> ⚠️ EXTENSION MAPPING REFUTED 2026-04-21 — earlier assumption that extension encodes
+> recording mode is **FALSE**. A continuous-mode event produced `.EI0`, not `.9T0`.
+> Extension encoding algorithm is unknown. Do not use extension to infer recording mode.
+
+### D.1 Common File Header (22 bytes)
+
+All Blastware files (regardless of type) share an 18-byte prefix followed by a 4-byte type tag.
+
+| Offset | Length | Value | Description |
+|---|---|---|---|
+| 0x00 | 6 | `10 00 01 80 00 00` | Fixed prefix |
+| 0x06 | 10 | `Instantel\x00` | ASCII string |
+| 0x10 | 2 | `07 2c` | Fixed suffix |
+| 0x12 | 4 | varies | File type tag (see below) |
+
+**Total header: 22 bytes.**
+
+**Type tags:**
+
+| Extension | Type tag | Description |
+|---|---|---|
+| `.N00` | `00 12 03 00` | Waveform event (confirmed) |
+| `.9T0` | `00 12 03 00` | Waveform event — same type tag as .N00 (assumed; not independently confirmed) |
+| `.EI0` | `00 12 03 00` | Waveform event — same type tag (assumed; continuous-mode event observed 2026-04-21) |
+| `.MLG` | `22 01 0e a0` | Monitor log |
+
+**Extension encoding — new firmware (V10.72+) FULLY DECODED (confirmed 2026-04-22):**
+
+The extension differs depending on how the file was saved:
+
+| Download method | Extension format | Example |
+|---|---|---|
+| Manual / direct (Blastware connected to unit) | `AB0` (3 chars) | `.CE0` |
+| Call-home / ACH | `AB0W` or `AB0H` (4 chars) | `.CE0H` |
+
+Where:
+- `AB` = 2-char base-36 of `total_seconds % 1296`; `A = value // 36`, `B = value % 36`
+- `total_seconds = (event_local_time − 1985-01-01T00:00:00_local)` in seconds
+- `0` = always literal digit zero
+- `W` = Full Waveform, `H` = Full Histogram (ACH only)
+
+Base-36 alphabet: `0–9` = 0–9, `A–Z` = 10–35.
+
+The 10-year production archive contains only ACH files (all end in W or H). Manual Blastware downloads produce the same `AB0` prefix but without the trailing type character.
+
+**3-day cycle property (confirmed 2026-04-22):** A unit recording at a fixed daily time cycles through exactly **3 different extensions** with a 3-day period. Each calendar day shifts `total_seconds % 1296` by 864 (since `86400 % 1296 = 864`). The cycle repeats every 3 days because `gcd(1296, 864) = 432`. Confirmed from archive: top 3 extensions `CE0H` (95), `0E0H` (93), `OE0H` (91) are the 3-day cycle of a 06:00:14 daily call-in (seconds-in-window = 446, 14, 878).
+
+**B character invariance:** `864 = 24 × 36`, so adding one day never changes `value % 36` — the second extension character is invariant for a fixed daily recording time. Only the first character cycles through 3 values.
+
+**Old firmware (S338):** 3-char extensions observed (`.N00`, `.EI0`, etc.) — may simply be manual downloads under the same AB0 scheme, or a different encoding. Not yet confirmed.
+
+**Micromate Series 4** uses a different extension format (observed: `IDFH`, `IDFW`). This formula does NOT apply to Micromate units.
+
+All waveform files share the same `00 12 03 00` type tag regardless of extension. Blastware identifies file type by extension, not by type tag alone.
+
+### D.2 Timestamp Encoding (Blastware files)
+
+All timestamps in N00 and MLG files use an **8-byte big-endian format**:
+
+| Byte | Field |
+|---|---|
+| 0 | day (uint8) |
+| 1 | month (uint8) |
+| 2–3 | year (uint16 BE) |
+| 4 | `0x00` (reserved) |
+| 5 | hour (uint8) |
+| 6 | minute (uint8) |
+| 7 | second (uint8) |
+
+Example: `01 04 07 ea 00 00 1c 08` → April 1, 2026, 00:28:08.
+
+Note: this differs from the 8-byte protocol timestamp (`[day][sub_code][month][year_HI][year_LO][0x00][hour][min][sec]` = 9 bytes) used in the device's on-wire 0C waveform records. The file format uses a compact 8-byte layout without the `sub_code` byte.
+
+### D.3 N00 File Format — Single-Shot Waveform Event
+
+**File layout:** `[22B header] [21B STRT record] [body bytes] [26B footer]`
+
+#### D.3.1 STRT Record (21 bytes)
+
+The STRT record immediately follows the 22-byte header.
+
+| Offset | Length | Field | Notes |
+|---|---|---|---|
+| 0 | 4 | `STRT` | ASCII literal |
+| 4 | 2 | `ff fe` | Fixed |
+| 6 | 4 | event key (key4) | 4-byte waveform key |
+| 10 | 4 | device-specific | NOT a repeat of key4 — device-internal field |
+| 14 | 6 | device-specific | NOT zero-padded — device-internal fields |
+| 20 | 1 | rectime | uint8 seconds |
+
+**Critical:** The STRT record must be copied verbatim from A5[0].data[7+strt_pos:] — bytes [10:20] contain device-specific values that cannot be reconstructed from protocol-level Event fields alone.
+
+#### D.3.2 Body Bytes (variable)
+
+The body is reconstructed from the raw A5 bulk waveform stream frames by stripping DLE framing markers and taking the appropriate slice of each frame's data section.
+
+**Per-frame contribution (from `frame.data`):**
+
+| Frame | Skip amount | Notes |
+|---|---|---|
+| A5[0] (probe) | `7 + strt_pos_in_w0 + 21` | Skip frame.data prefix + STRT record |
+| A5[1] | 13 | 7-byte prefix + 6-byte first-chunk header |
+| A5[2..N] | 12 | 7-byte prefix + 5-byte chunk header |
+| Terminator (page_key=0x0000) | 11 | 7-byte prefix + 4-byte terminator header |
+
+**DLE strip rule:** For each frame's contribution (`frame.data[skip:]`), strip any `0x10` byte immediately followed by `0x02`, `0x03`, or `0x04`. Only the `0x10` is stripped; the following byte is kept as payload.
+
+**Split-pair edge case:** When `frame.data[-1] == 0x10` AND `frame.chk_byte ∈ {0x02, 0x03, 0x04}`, the S3FrameParser split a DLE+XX pair at the payload/checksum boundary. Reunite the bytes before stripping (`relevant + bytes([chk_byte])`), then always remove the trailing chk_byte from the result (`stripped[:-1]`) — chk_byte is the wire checksum, never payload.
+
+**Body/footer split:** Accumulate all frame contributions (data frames + terminator) into `all_bytes`. Then:
+- `body = all_bytes[:-26]` (variable length)
+- `footer = all_bytes[-26:]` (always 26 bytes — extracted from terminator content)
+
+#### D.3.3 Footer (26 bytes)
+
+The footer terminates the N00 file. Its bytes come directly from the terminator A5 frame's inner content — do NOT reconstruct from event metadata.
+
+| Offset | Length | Field | Notes |
+|---|---|---|---|
+| 0 | 2 | `0e 08` | Fixed marker |
+| 2 | 8 | ts1 | Start timestamp (8B big-endian) |
+| 10 | 8 | ts2 | Stop timestamp (8B big-endian) |
+| 18 | 6 | `00 01 00 02 00 00` | Fixed |
+| 24 | 2 | CRC | 2-byte CRC — algorithm unconfirmed |
+
+**CRC:** The 2-byte CRC at footer[24:26] has an unconfirmed algorithm. In M529LIY6.N00 it reads `fe da`. Attempts to match CRC-16/CCITT, CRC-16/IBM, CRC-32 (truncated), and 40+ polynomial/init combinations all failed. The writer copies it verbatim from the terminator frame.
+
+### D.4 MLG File Format — Monitor Log
+
+**File layout:** `[308B header] [N × 292B records]`
+
+#### D.4.1 MLG Header (308 bytes)
+
+| Offset | Length | Field | Notes |
+|---|---|---|---|
+| 0x00 | 22 | common header | prefix + `22 01 0e a0` type tag |
+| 0x16 | 16 | unknown | observed as zeros in BE11529.MLG |
+| 0x2A | 8 | serial number | null-padded ASCII (e.g. `"BE11529"`) |
+| 0x32 | remainder | zero pad | pads to 308 bytes total |
+
+#### D.4.2 MLG Record (292 bytes each)
+
+| Offset | Length | Field | Notes |
+|---|---|---|---|
+| 0 | 2 | CRC | 2-byte CRC — algorithm unconfirmed; write as `00 00` |
+| 2 | 4 | `22 01 0e 80` | Record marker |
+| 6 | 8 | ts1 | Start timestamp (8B big-endian) |
+| 14 | 8 | ts2 | Stop timestamp (8B big-endian); zeros if no stop |
+| 22 | 4 | flags | Record type flags (see below) |
+| 26 | 10 | serial | Null-padded ASCII serial number |
+| 36 | variable | text | Type-dependent content |
+| — | remainder | zero pad | pads to 292 bytes total |
+
+**Record flags:**
+
+| Value | Meaning |
+|---|---|
+| `ff ff 00 00` | Monitoring start with no stop recorded |
+| `01 00 02 00` | Triggered event (has ts1 + ts2) |
+| `02 00 00 00` | Monitoring interval (has ts1 + ts2) |
+
+**Text content for triggered events (`flags = 01 00 02 00`):**
+
+| Byte | Field |
+|---|---|
+| 0 | `0x08` |
+| 1–8 | ts1 copy (8B big-endian) |
+| 9+ | `"Geo: X.XXX in/s\x00"` ASCII geo threshold |
+
+#### D.4.3 MLG CRC
+
+The 2-byte CRC at record[0:2] uses an unconfirmed algorithm. Tested against CRC-16/CCITT, CRC-16/IBM, CRC-32 (truncated), word sums, XOR variants, and 40+ polynomial/init combinations — none matched. The writer emits `00 00`. Blastware may reject files with incorrect CRCs (impact on import unknown — TODO: test).
+
+### D.5 Filename Encoding ✅ PARTIALLY CONFIRMED 2026-04-22
+
+Blastware assigns waveform filenames of the form `<prefix_letter><serial3><stem><ext>`, where:
+
+#### D.5.1 Serial Prefix ✅ CONFIRMED 2026-04-22
+
+The first 4 characters of the filename encode the full device serial number:
+
+```
+prefix_letter = chr(ord('B') + floor(serial_numeric / 1000))
+serial3       = f"{serial_numeric % 1000:03d}"   (last 3 digits, zero-padded)
+```
+
+Where `serial_numeric` is the integer after the "BE" device-type prefix.
+
+Examples (all confirmed from archive):
+
+| Serial | serial_numeric / 1000 | prefix_letter | serial3 | Filename prefix |
+|--------|----------------------|---------------|---------|-----------------|
+| BE6907 | 6 | H | 907 | H907 |
+| BE7145 | 7 | I | 145 | I145 |
+| BE11529 | 11 | M | 529 | M529 |
+| BE14036 | 14 | P | 036 | P036 |
+| BE17353 | 17 | S | 353 | S353 |
+| BE18003 | 18 | T | 003 | T003 |
+| BE18191 | 18 | T | 191 | T191 |
+| BE18676 | 18 | T | 676 | T676 |
+
+**Interpretation:** The prefix letter encodes the production generation (batch of 1000 units). B=generation 0 (serials 0–999), C=generation 1 (1000–1999), etc. No units with prefix A have been observed — the earliest known units start around serial 2000+ (prefix D).
+
+**Note:** The "BE" device-type prefix is implicit. The filename only encodes the numeric part of the serial. Other Instantel device types (Micromate, Blastmate) may use a different scheme.
+
+#### D.5.2 Stem + Extension — full timestamp encoding ✅ FULLY CONFIRMED 2026-04-22
+
+The stem (4 chars) and AB extension (2 chars) together form a 6-digit base-36 number encoding a complete second-resolution timestamp:
+
+```python
+total_seconds = stem_int * 1296 + ab_int
+event_local_time = datetime(1985, 1, 1) + timedelta(seconds=total_seconds)
+```
+
+- **Epoch:** `1985-01-01 00:00:00` **device local time** ✅ CONFIRMED — verified against 3,248 files from a 10-year production archive; zero errors (only 2 mismatches were Micromate `IDFH`/`IDFW` files which use a completely different naming scheme)
+- **Unit:** 1296 seconds = 36² ≈ 21.6 minutes per stem increment
+- **Alphabet:** `"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"` (digits then uppercase letters)
+- **Collision:** Events within the same 21.6-minute window share a stem; extension distinguishes them
+
+**Decoding example — `P036L318.C80H` (BE14036, Full Histogram):**
+```
+stem  L318 = 21×36³ + 3×36² + 1×36 + 8 = 983,708
+AB    C8   = 12×36  + 8               =     440
+total_sec  = 983,708 × 1296 + 440     = 1,274,886,008
+event_time = 1985-01-01 + 1,274,886,008s = 2025-05-26 15:00:08 local
+```
+
+**Note on local time:** The device's onboard clock is set to the local timezone of the deployment site. The epoch and all timestamps are in that same local time — there is no UTC conversion. Files moved between timezones will decode to the original deployment timezone.
+
+#### D.5.3 Extension taxonomy
+
+Third character of extension is always `'0'`.  File type is identified by extension, not by the type tag in the header (all waveform extensions share type tag `00 12 03 00`).
+
+| Extension | Recording mode | Sample rate | Status |
+|---|---|---|---|
+| `.N00` | Single Shot (0x00) | 1024 sps | ✅ CONFIRMED |
+| `.9T0` | Continuous (0x01) | 1024 sps | ✅ CONFIRMED |
+| `.490` | ? | ? | ❓ observed from M529LJ8V.490 |
+| `.5K0` | ? | ? | ❓ observed from M529LJDY.5K0 |
+| `.980` | ? | ? | ❓ observed from M529LJDY.980 |
+| `.ML0` | ? | ? | ❓ observed from M529LJDY.ML0 (167s duration; possibly Histogram) |
+
+**Why 5 extensions for "Continuous"?** Binary analysis of all 6 example files shows that `.9T0`, `.490`, `.5K0`, `.980`, `.ML0` are byte-for-byte identical in all metadata regions (compliance anchor block, channel descriptor blocks `Tran/Vert/Long/MicL`). The A5 frame 7 body reflects the **session-start** compliance config, not the per-event capture config. All 5 files show recording_mode=0x01 and sample_rate=1024 in the body. The extension must therefore encode the **capture-time** compliance state — likely a combination of recording mode, sample rate, and possibly mic units or other options. This cannot be determined from file body alone without capture-time compliance data from the 0C record sub_code and the actual waveform sample count.
+
+**DLE-shift offset note for reading recording_mode from N00/9T0 body:**
+
+The compliance block in the file body has been through `_strip_inner_frame_dles`. The 0x10 constant at logical `anchor−7` (between recording_mode and sample_rate_HI) gets stripped when sample_rate_HI = `0x04` (1024 sps), because `0x10` precedes `0x04 ∈ {0x02,0x03,0x04}`. After stripping, the anchor shifts left by 1, so:
+
+| 1024 sps (strip occurs) | 2048 or 4096 sps (no strip) |
+|---|---|
+| `file[anc−7]` = recording_mode | `file[anc−8]` = recording_mode |
+| `file[anc−6:anc−4]` = sample_rate | `file[anc−6:anc−4]` = sample_rate |
+
+For 1024 sps files, the expected file bytes around the anchor are:
+```
+file[anc−9]: mode_prefix (0x00 for Single Shot/Continuous; 0x10 for Histogram)
+file[anc−8]: 0x00 (was recording_mode, but shifted away — now reads 0x00 for mode_prefix)
+file[anc−7]: recording_mode (0x00=Single Shot, 0x01=Continuous, etc.)
+file[anc−6]: 0x04  (sample_rate_HI for 1024 sps)
+file[anc−5]: 0x00  (sample_rate_LO)
+file[anc−4]: histogram_interval_HI
+file[anc−3]: histogram_interval_LO
+```
+
+---
+
 *All findings reverse-engineered from live RS-232 bridge captures.*  
 *Cross-referenced from 2026-03-02 with Instantel MiniMate Plus Operator Manual (716U0101 Rev 15).*  
 *This is a living document — append changelog entries and timestamps as new findings are confirmed or corrected.*

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/client.py

@@ -449,7 +449,7 @@ class MiniMateClient:
         proto.confirm_erase_all()
         log.info("delete_all_events: erase confirmed — device memory cleared")
 
-    def get_events(self, full_waveform: bool = False, debug: bool = False, stop_after_index: Optional[int] = None, skip_waveform_for_keys: Optional[set] = None) -> list[Event]:
+    def get_events(self, full_waveform: bool = False, debug: bool = False, stop_after_index: Optional[int] = None, skip_waveform_for_keys: Optional[set] = None, extra_chunks_after_metadata: int = 1) -> list[Event]:
         """
         Download all stored events from the device using the confirmed
         1E → 0A → 0C → 5A → 1F event-iterator protocol.
@@ -604,10 +604,12 @@ class MiniMateClient:
                             "get_events: 5A full waveform download for key=%s", cur_key.hex()
                         )
                         a5_frames = proto.read_bulk_waveform_stream(
-                            cur_key, stop_after_metadata=False, max_chunks=128
+                            cur_key, stop_after_metadata=False, max_chunks=128,
+                            include_terminator=True,
                         )
                         if a5_frames:
                             a5_ok = True
+                            ev._a5_frames = a5_frames   # store for write_blastware_file
                             _decode_a5_metadata_into(a5_frames, ev)
                             _decode_a5_waveform(a5_frames, ev)
                             log.info(
@@ -619,10 +621,14 @@ class MiniMateClient:
                             "get_events: 5A metadata-only download for key=%s", cur_key.hex()
                         )
                         a5_frames = proto.read_bulk_waveform_stream(
-                            cur_key, stop_after_metadata=True
+                            cur_key, stop_after_metadata=True,
+                            include_terminator=True,
+                            extra_chunks_after_metadata=extra_chunks_after_metadata,
+                            max_chunks=128,
                         )
                         if a5_frames:
                             a5_ok = True
+                            ev._a5_frames = a5_frames   # store for write_blastware_file
                             _decode_a5_metadata_into(a5_frames, ev)
                             log.debug(
                                 "get_events: 5A metadata  client=%r  operator=%r",
@@ -776,6 +782,39 @@ class MiniMateClient:
         else:
             log.warning("download_waveform: waveform decode produced no samples")
 
+        return a5_frames
+
+    def save_blastware_file(self, event: "Event", path: "Union[str, Path]", serial: str) -> None:
+        """
+        Download the full waveform for *event* and save it as a Blastware-
+        compatible Blastware waveform file at *path*.
+
+        This is a convenience wrapper that calls download_waveform() (which
+        performs the complete SUB 5A BULK_WAVEFORM_STREAM download) and then
+        calls write_blastware_file() from blastware_file.py to encode the result.
+
+        Args:
+            event:  Event object with waveform key populated (from get_events()).
+            path:   Destination file path.  Caller should use blastware_filename()
+                    to pick the correct extension via blastware_filename().
+            serial: Device serial number (e.g. "BE11529") — passed to
+                    blastware_filename() for reference, but the caller supplies
+                    the final path.
+        """
+        from pathlib import Path as _Path
+        from .blastware_file import write_blastware_file as _write_blastware_file
+
+        a5_frames = self.download_waveform(event)
+        if not a5_frames:
+            raise RuntimeError(
+                f"save_blastware_file: no A5 frames received for event#{event.index}"
+            )
+        _write_blastware_file(event, a5_frames, path)
+        log.info(
+            "save_blastware_file: wrote %s (%d A5 frames)",
+            path, len(a5_frames),
+        )
+
     # ── Write commands ────────────────────────────────────────────────────────
 
     def push_config_raw(
@@ -1324,7 +1363,7 @@ def _decode_waveform_record_into(data: bytes, event: Event) -> None:
         log.warning("waveform record project strings decode failed: %s", exc)
 
 
-def _decode_a5_metadata_into(frames_data: list[bytes], event: Event) -> None:
+def _decode_a5_metadata_into(frames_data: list[S3Frame], event: Event) -> None:
     """
     Search A5 (BULK_WAVEFORM_STREAM) frame data for event-time metadata strings
     and populate event.project_info.
@@ -1352,7 +1391,7 @@ def _decode_a5_metadata_into(frames_data: list[bytes], event: Event) -> None:
 
     Modifies event in-place.
     """
-    combined = b"".join(frames_data)
+    combined = b"".join(f.data for f in frames_data)
 
     def _find_string_after(needle: bytes, max_len: int = 64) -> Optional[str]:
         pos = combined.find(needle)
@@ -1376,7 +1415,7 @@ def _decode_a5_metadata_into(frames_data: list[bytes], event: Event) -> None:
     notes    = _find_string_after(b"Extended Notes")
 
     if not any([project, client, operator, location, notes]):
-        log.debug("a5 metadata: no project strings found in %d frames", len(frames_data))
+        log.debug("a5 metadata: no project strings found in %d frames (%d bytes)", len(frames_data), len(combined))
         return
 
     if event.project_info is None:
@@ -1402,7 +1441,7 @@ def _decode_a5_metadata_into(frames_data: list[bytes], event: Event) -> None:
 
 
 def _decode_a5_waveform(
-    frames_data: list[bytes],
+    frames_data: list[S3Frame],
     event: Event,
 ) -> None:
     """
@@ -1463,7 +1502,7 @@ def _decode_a5_waveform(
         return
 
     # ── Parse STRT record from A5[0] ────────────────────────────────────────
-    w0 = frames_data[0][7:]   # db[7:] for A5[0]
+    w0 = frames_data[0].data[7:]   # frame.data[7:] for A5[0]
     strt_pos = w0.find(b"STRT")
     if strt_pos < 0:
         log.warning("_decode_a5_waveform: STRT record not found in A5[0]")
@@ -1499,7 +1538,7 @@ def _decode_a5_waveform(
     global_offset = 0
 
     for fi, db in enumerate(frames_data):
-        w = db[7:]
+        w = db.data[7:]   # frame.data[7:]
 
         # A5[0]: waveform begins after the 21-byte STRT record and 6-byte preamble.
         # Layout: STRT(21B) + null-pad(2B) + 0xFF sentinel(4B) = 27 bytes total.
@@ -1770,10 +1809,13 @@ def _encode_compliance_config(
     DLE-jitter shifts):
 
       Anchor: b'\\xbe\\x80\\x00\\x00\\x00\\x00'  (confirmed stable, both BE11529 and BE18189)
-        recording_mode       → uint8 at anchor_pos - 7  (write payload)
+        recording_mode       → uint8 at anchor_pos - 8  (BOTH read and write)
                                Values: 0x00=Single Shot, 0x01=Continuous, 0x03=Histogram, 0x04=Histogram+Continuous
-                               NOTE: In the E5 read response (decode) field is at anchor_pos - 8 due to an
-                               extra 0x10 byte at read anchor_pos - 7.  Write payload has no extra byte.
+                               NOTE: The byte at anchor_pos - 7 is always 0x10 (a DLE marker regenerated by
+                               device firmware in every E5 response).  It must NOT be overwritten during
+                               write — doing so causes anchor drift (+1 per write cycle).
+                               CORRECTION 2026-04-21: previous doc stated anchor-7 for write; empirically
+                               confirmed wrong — writing to anchor-7 shifts the anchor by 1 on every cycle.
         sample_rate          → uint16 BE at anchor_pos - 6
         histogram_interval_sec → uint16 BE at anchor_pos - 4  (seconds; mode-gated to Histogram/Histogram+Continuous)
                                Valid values: 2, 5, 15, 60, 300, 900 (= 2s, 5s, 15s, 1m, 5m, 15m)
@@ -1833,13 +1875,40 @@ def _encode_compliance_config(
     _ANC = b'\xbe\x80\x00\x00\x00\x00'
     _anc = buf.find(_ANC, 0, 150)
 
+    # Log anchor position every time so we can detect unexpected shifts due to
+    # DLE jitter or firmware differences.  Expected position is ~15.
+    if _anc < 0:
+        log.warning(
+            "_encode_compliance_config: anchor NOT FOUND in cfg[0:150] "
+            "(buf len=%d) — all anchor-relative writes will be skipped",
+            len(buf),
+        )
+    else:
+        log.info(
+            "_encode_compliance_config: anchor at cfg[%d]  buf_len=%d  "
+            "(recording_mode@%d  DLE_marker@%d  sample_rate@%d:%d  "
+            "histogram_interval@%d:%d  record_time@%d:%d)",
+            _anc, len(buf),
+            _anc - 8,
+            _anc - 7,
+            _anc - 6, _anc - 4,
+            _anc - 4, _anc - 2,
+            _anc + 6, _anc + 10,
+        )
+
     if recording_mode is not None:
-        if _anc < 7:
+        if _anc < 8:
             log.warning("_encode_compliance_config: anchor not found — cannot write recording_mode")
         else:
-            buf[_anc - 7] = recording_mode & 0xFF
+            # Write to anchor-8, same physical position as the E5 read format.
+            # The byte at anchor-7 is a DLE marker (0x10) that the device firmware
+            # regenerates in every E5 response — it must NOT be overwritten.
+            # Writing to anchor-7 causes the device to add an extra byte on the
+            # next read-back, drifting the anchor by +1 on every write cycle.
+            # (CLAUDE.md "anchor-7 write" was incorrect — confirmed 2026-04-21)
+            buf[_anc - 8] = recording_mode & 0xFF
             log.debug("_encode_compliance_config: recording_mode=0x%02X -> offset %d",
-                      recording_mode, _anc - 7)
+                      recording_mode, _anc - 8)
 
     if sample_rate is not None:
         if _anc < 6:
@@ -2001,6 +2070,27 @@ def _decode_compliance_config_into(data: bytes, info: DeviceInfo) -> None:
     #   _anchor + 6 : record_time        (float32 BE)
     _ANCHOR = b'\xbe\x80\x00\x00\x00\x00'
     _anchor = data.find(_ANCHOR, 0, 150)
+
+    # Log anchor position on every decode so we can compare read vs write and
+    # catch unexpected shifts from DLE jitter or firmware differences.
+    # Expected position is ~15 for the E5 read payload (anchor - 8 = recording_mode).
+    if _anchor < 0:
+        log.warning(
+            "_decode_compliance_config_into: anchor NOT FOUND in data[0:150] (len=%d)",
+            len(data),
+        )
+    else:
+        log.info(
+            "_decode_compliance_config_into: anchor at data[%d]  data_len=%d  "
+            "(expected ~15; recording_mode@%d  sample_rate@%d:%d  "
+            "histogram_interval@%d:%d  record_time@%d:%d)",
+            _anchor, len(data),
+            _anchor - 8,
+            _anchor - 6, _anchor - 4,
+            _anchor - 4, _anchor - 2,
+            _anchor + 6, _anchor + 10,
+        )
+
     if _anchor >= 8 and _anchor + 10 <= len(data):
         try:
             config.recording_mode = data[_anchor - 8]

minimateplus/framing.py

@@ -457,6 +457,11 @@ class S3Frame:
     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:
@@ -592,9 +597,10 @@ class S3FrameParser:
             return None
 
         return S3Frame(
-            sub           = raw_payload[2],
-            page_hi       = raw_payload[3],
-            page_lo       = raw_payload[4],
-            data          = raw_payload[5:],
+            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

@@ -493,6 +493,10 @@ class Event:
     # 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 = ""

minimateplus/protocol.py

@@ -126,10 +126,12 @@ DATA_LENGTHS: dict[int, int] = {
 _BULK_CHUNK_OFFSET = 0x1004   # offset field for probe + all regular chunk requests ✅
 _BULK_TERM_OFFSET  = 0x005A   # offset field for termination request ✅
 _BULK_COUNTER_STEP = 0x0400   # chunk counter increment per chunk ✅
-# Chunk counter formula: chunk_num * 0x0400 for ALL chunks including chunk 1.
-# Earlier captures showed 0x1004 for chunk 1 — that was a Blastware artifact, not a
-# protocol requirement.  Confirmed 2026-04-06: 0x0400 for chunk 1 works; 0x1004
-# causes a 120-second device timeout.  Formula n * 0x0400 is used for all chunks.
+# Chunk counter formula: key4[2:4] + (chunk_num - 1) * 0x0400
+# where key4[2:4] is the event's circular-buffer base offset ((key4[2]<<8)|key4[3]).
+# Earlier captures showed 0x1004 for chunk 1 of key 01110000 — that was a Blastware
+# artifact.  For keys where key4[2:4] != 0x0000 (e.g. key 01111884) the old
+# "n * 0x0400" formula sends counters from the wrong buffer region and the device
+# returns data from a different event.  Confirmed correct 2026-04-24.
 
 # Default timeout values (seconds).
 # MiniMate Plus is a slow device — keep these generous.
@@ -526,7 +528,9 @@ class MiniMateProtocol:
         *,
         stop_after_metadata: bool = True,
         max_chunks: int = 32,
-    ) -> list[bytes]:
+        include_terminator: bool = False,
+        extra_chunks_after_metadata: int = 1,
+    ) -> list[S3Frame]:
         """
         Download the SUB 5A (BULK_WAVEFORM_STREAM) A5 frames for one event.
 
@@ -542,7 +546,9 @@ class MiniMateProtocol:
           4. Termination (offset=_BULK_TERM_OFFSET, counter=last+_BULK_COUNTER_STEP)
              Device responds with a final A5 frame (page_key=0x0000).
 
-        The termination frame (page_key=0x0000) is NOT included in the returned list.
+        By default the termination frame (page_key=0x0000) is NOT included in the
+        returned list.  Pass include_terminator=True to append it; the blastware_file
+        writer needs the terminator frame's body to reconstruct the waveform file footer.
 
         Args:
             key4:                4-byte waveform key from EVENT_HEADER (1E).
@@ -552,11 +558,16 @@ class MiniMateProtocol:
                                  hundred KB).  Set False to download everything.
             max_chunks:          Safety cap on the number of chunk requests sent
                                  (default 32; a typical event uses 9 large frames).
+            include_terminator:  If True, append the terminator A5 frame
+                                 (page_key=0x0000) to the returned list.  The
+                                 terminator carries the waveform file footer bytes.
+                                 Default False preserves existing caller behaviour.
 
         Returns:
-            List of raw data bytes from each A5 response frame (not including
-            the terminator frame).  Frame indices match the request sequence:
-            index 0 = probe response, index 1 = first chunk, etc.
+            List of S3Frame objects from each A5 response frame.  Frame indices
+            match the request sequence: index 0 = probe response, index 1 = first
+            chunk, etc.  If include_terminator=True, the last element is the
+            terminator frame (page_key=0x0000).
 
         Raises:
             ProtocolError: on timeout, bad checksum, or unexpected SUB.
@@ -571,16 +582,24 @@ class MiniMateProtocol:
             raise ValueError(f"waveform key must be 4 bytes, got {len(key4)}")
 
         rsp_sub = _expected_rsp_sub(SUB_BULK_WAVEFORM)   # 0xFF - 0x5A = 0xA5
-        frames_data: list[bytes] = []
+        frames_data: list[S3Frame] = []
         counter = 0
 
+        # BW counter formula (confirmed from 4-3-26 capture for key 0111245a,
+        # and empirical live-device test 2026-04-06 for key 01110000):
+        #   counter for chunk n = max(key4[2:4], 0x0400) + (n - 1) * 0x0400
+        # key4[2:4] is the event's circular-buffer base offset.  The max() guard
+        # ensures chunk 1 never uses counter=0x0000 (which equals the probe address
+        # and causes the device to re-return STRT record data for the first chunk).
+        _key4_offset = (key4[2] << 8) | key4[3]
+
         # ── Step 1: probe ────────────────────────────────────────────────────
-        log.debug("5A probe  key=%s", key4.hex())
+        log.debug("5A probe  key=%s  key4_offset=0x%04X", key4.hex(), _key4_offset)
         params = bulk_waveform_params(key4, 0, is_probe=True)
         self._send(build_5a_frame(_BULK_CHUNK_OFFSET, params))
         self._parser.reset()        # reset bytes_fed counter before probe recv
         try:
-            rsp = self._recv_one(expected_sub=rsp_sub, reset_parser=False)
+            probe_batch = self._recv_5a_batch(rsp_sub)
         except TimeoutError:
             log.warning(
                 "5A probe TIMED OUT for key=%s — "
@@ -588,23 +607,54 @@ class MiniMateProtocol:
                 key4.hex(), self._parser.bytes_fed,
             )
             raise
-        frames_data.append(rsp.data)
-        log.debug("5A A5[0]  page_key=0x%04X  %d bytes", rsp.page_key, len(rsp.data))
+        frames_data.extend(probe_batch)
+        log.debug(
+            "5A probe: %d frame(s)  page_keys=%s",
+            len(probe_batch),
+            [f"0x{f.page_key:04X}" for f in probe_batch],
+        )
+
+        # Log probe frame size for diagnostics.
+        # The device always needs extra_chunks_after_metadata chunks after the
+        # metadata frame before termination to prime the valid waveform footer.
+        # This holds regardless of TCP frame size (1-frame vs 2-frame mode).
+        _effective_extra_chunks = extra_chunks_after_metadata
+        log.warning(
+            "5A probe data_len=%d  effective_extra_chunks=%d",
+            len(probe_batch[0].data),
+            _effective_extra_chunks,
+        )
 
         # ── Step 2: chunk loop ───────────────────────────────────────────────
-        # Chunk counters are monotonic: chunk_num * 0x0400 for all chunks.
-        # The 4-2-26 BW TX capture showed 0x1004 for chunk 1, but this is a
-        # Blastware artifact — the device accepts any counter value and streams
-        # data regardless.  Empirically confirmed 2026-04-06: 0x0400 for chunk 1
-        # works; 0x1004 causes the device to ignore the frame (timeout).
+        # Counter formula: _chunk_base + (chunk_num - 1) * 0x0400
+        # where _chunk_base = max(key4[2:4], 0x0400).
+        #
+        # For events with key4[2:4] != 0 (e.g. key 0111245a, offset 0x245a):
+        #   _chunk_base = 0x245a  →  chunk 1=0x245a, chunk 2=0x285a, ...
+        #   Confirmed from 4-3-26 capture.
+        #
+        # For events with key4[2:4] == 0 (e.g. key 01110000):
+        #   _chunk_base = max(0, 0x0400) = 0x0400
+        #   →  chunk 1=0x0400, chunk 2=0x0800, ... (= old chunk_num*0x0400)
+        #   CRITICAL: counter=0x0000 (same as the probe) causes the device to
+        #   re-return the STRT record data for chunk 1, making frame 1 look like
+        #   a second probe response (confirmed from server log: frame 1 len=1097,
+        #   contains STRT\xff\xfe, contributes zero body bytes after DLE-strip).
+        #   counter=0x0400 for chunk 1 confirmed working (empirical test 2026-04-06).
+        _chunk_base = max(_key4_offset, _BULK_COUNTER_STEP)
         for chunk_num in range(1, max_chunks + 1):
-            counter = chunk_num * _BULK_COUNTER_STEP
+            counter = _chunk_base + (chunk_num - 1) * _BULK_COUNTER_STEP
             params  = bulk_waveform_params(key4, counter)
             log.debug("5A chunk %d  counter=0x%04X", chunk_num, counter)
             self._send(build_5a_frame(_BULK_CHUNK_OFFSET, params))
             self._parser.reset()        # reset bytes_fed for accurate per-chunk count
             try:
-                rsp = self._recv_one(expected_sub=rsp_sub, reset_parser=False, timeout=10.0)
+                # Collect ALL frames from this chunk response.
+                # Over TCP via modem, a single large A5 device response (~1100 bytes
+                # RS-232) is split across ~2 TCP segments, each parsed as its own
+                # complete S3 frame.  _recv_5a_batch gathers all of them so that
+                # every subsequent chunk request is paired with the correct response.
+                batch = self._recv_5a_batch(rsp_sub, first_timeout=10.0)
             except TimeoutError:
                 raw = self._parser.bytes_fed
                 log.warning(
@@ -623,20 +673,51 @@ class MiniMateProtocol:
                     break
                 raise
 
-            log.warning(
-                "5A RX chunk=%d page_key=0x%04X data_len=%d contains_Project=%s",
-                chunk_num, rsp.page_key, len(rsp.data), b"Project:" in rsp.data,
-            )
+            # Process all frames from this batch.
+            metadata_found = False
+            for rsp in batch:
+                log.warning(
+                    "5A RX chunk=%d page_key=0x%04X data_len=%d contains_Project=%s",
+                    chunk_num, rsp.page_key, len(rsp.data), b"Project:" in rsp.data,
+                )
+                if rsp.page_key == 0x0000:
+                    # Device unexpectedly terminated mid-stream.
+                    log.debug("5A page_key=0x0000 — device terminated early")
+                    if include_terminator:
+                        frames_data.append(rsp)
+                    return frames_data
+                frames_data.append(rsp)
+                if stop_after_metadata and b"Project:" in rsp.data:
+                    metadata_found = True
 
-            if rsp.page_key == 0x0000:
-                # Device unexpectedly terminated mid-stream (no termination needed).
-                log.debug("5A A5[%d] page_key=0x0000 — device terminated early", chunk_num)
-                return frames_data
-
-            frames_data.append(rsp.data)
-
-            if stop_after_metadata and b"Project:" in rsp.data:
-                log.debug("5A A5[%d] metadata found — stopping early", chunk_num)
+            if metadata_found:
+                # Download extra_chunks_after_metadata more chunks after metadata.
+                # This primes the device to return the valid waveform footer in the
+                # termination response — without it the terminator carries too few bytes
+                # (confirmed 2026-04-23).  The extra chunk data also belongs in the
+                # file body (confirmed from TCP capture analysis 2026-04-27).
+                log.debug("5A metadata found — fetching %d more chunk(s)",
+                          _effective_extra_chunks)
+                for _extra_n in range(_effective_extra_chunks):
+                    chunk_num += 1
+                    counter = _chunk_base + (chunk_num - 1) * _BULK_COUNTER_STEP
+                    params = bulk_waveform_params(key4, counter)
+                    self._send(build_5a_frame(_BULK_CHUNK_OFFSET, params))
+                    try:
+                        extra_batch = self._recv_5a_batch(rsp_sub, first_timeout=10.0)
+                        for ef in extra_batch:
+                            log.debug(
+                                "5A extra chunk page_key=0x%04X data_len=%d",
+                                ef.page_key, len(ef.data),
+                            )
+                            if ef.page_key == 0x0000:
+                                if include_terminator:
+                                    frames_data.append(ef)
+                                return frames_data
+                            frames_data.append(ef)
+                    except TimeoutError:
+                        log.debug("5A extra chunk %d timed out — end of stream", _extra_n + 1)
+                        break
                 break
         else:
             log.warning(
@@ -658,6 +739,8 @@ class MiniMateProtocol:
                 "5A termination response  page_key=0x%04X  %d bytes",
                 term_rsp.page_key, len(term_rsp.data),
             )
+            if include_terminator:
+                frames_data.append(term_rsp)
         except TimeoutError:
             log.debug("5A no termination response — device may have already closed")
 
@@ -1320,6 +1403,63 @@ class MiniMateProtocol:
         log.debug("TX %d bytes: %s", len(frame), frame.hex())
         self._transport.write(frame)
 
+    def _recv_5a_batch(
+        self,
+        expected_sub: int,
+        first_timeout: float = 10.0,
+        batch_timeout: float = 0.5,
+    ) -> list[S3Frame]:
+        """
+        Collect all S3 frames that arrive as part of one device response.
+
+        Over TCP via cellular modem, a single device A5 response (~1100 bytes of
+        RS-232 data) is forwarded in multiple TCP segments due to the modem's
+        data-forwarding timeout (~100-150 ms per segment).  Each TCP segment
+        contains a complete, valid S3 frame (~550 bytes).  Calling _recv_one()
+        once returns only the first segment's frame and misses the rest, causing
+        the chunk request/response pairing to cascade out of alignment.
+
+        This helper collects ALL frames before returning, by trying additional
+        short-timeout receives after the first frame arrives.
+
+        The caller must call self._parser.reset() before this method to ensure
+        bytes_fed is accurate; this method always uses reset_parser=False.
+
+        Args:
+            expected_sub:   Expected SUB byte for validation.
+            first_timeout:  Timeout for the mandatory first frame.  Should be
+                            generous (default 10 s) since the device may be slow.
+            batch_timeout:  Short timeout for subsequent frames.  Default 0.5 s
+                            — comfortably longer than the modem forwarding gap
+                            (~150 ms) but short enough to avoid stalling when
+                            only one frame is expected (probe, terminator).
+
+        Returns:
+            List of S3Frame objects in arrival order (at least one).
+
+        Raises:
+            TimeoutError:       If no frame arrives within first_timeout.
+            UnexpectedResponse: If any frame has the wrong SUB byte.
+        """
+        frames: list[S3Frame] = []
+        first = self._recv_one(
+            expected_sub=expected_sub,
+            reset_parser=False,
+            timeout=first_timeout,
+        )
+        frames.append(first)
+        while True:
+            try:
+                extra = self._recv_one(
+                    expected_sub=expected_sub,
+                    reset_parser=False,
+                    timeout=batch_timeout,
+                )
+                frames.append(extra)
+            except TimeoutError:
+                break
+        return frames
+
     def _recv_one(
         self,
         expected_sub: Optional[int] = None,

sfm/server.py

@@ -61,6 +61,7 @@ from minimateplus import MiniMateClient
 from minimateplus.protocol import ProtocolError
 from minimateplus.models import CallHomeConfig, ComplianceConfig, DeviceInfo, Event, PeakValues, ProjectInfo, Timestamp
 from minimateplus.transport import TcpTransport, DEFAULT_TCP_PORT
+from minimateplus.blastware_file import write_blastware_file, blastware_filename
 from sfm.cache import SFMCache, get_cache
 from sfm.database import SeismoDb
 
@@ -848,6 +849,109 @@ def device_event_waveform(
     return result
 
 
+@app.get("/device/event/{index}/blastware_file")
+def device_event_blastware_file(
+    index:    int,
+    port:     Optional[str] = Query(None,             description="Serial port (e.g. COM5)"),
+    baud:     int           = Query(38400,             description="Serial baud rate"),
+    host:     Optional[str] = Query(None,             description="TCP host — modem IP or ACH relay"),
+    tcp_port: int           = Query(DEFAULT_TCP_PORT, description=f"TCP port (default {DEFAULT_TCP_PORT})"),
+) -> FileResponse:
+    """
+    Download the waveform for a single event (0-based index) and return it
+    as a Blastware-compatible binary file with a correct Blastware filename.
+
+    Supply either *port* (serial) or *host* (TCP/modem).
+
+    The file is written to /tmp and streamed back as a binary download.
+    Blastware can open it directly — filename encodes serial + timestamp.
+
+    Filename format: <prefix><serial3><stem><AB>0<W|H>
+      - prefix letter = chr(ord('B') + floor(serial_numeric / 1000))
+      - stem + AB     = second-resolution timestamp since 1985-01-01 local
+      - W / H         = Full Waveform / Full Histogram (defaults to W for
+                        triggered events; histogram requires recording_mode
+                        to be populated from compliance config)
+
+    Performs: POLL startup → get_events(full_waveform=False, extra_chunks=1,
+    stop_after_index=index) → write_blastware_file() → FileResponse.
+    """
+    log.info(
+        "GET /device/event/%d/blastware_file  port=%s host=%s",
+        index, port, host,
+    )
+
+    try:
+        def _do():
+            with _build_client(port, baud, host, tcp_port, timeout=120.0) as client:
+                info = client.connect()
+                # Use stop_after_metadata=True (full_waveform=False) with 1 extra
+                # chunk after "Project:".  The extra chunk primes the device so that
+                # the termination response carries the full waveform footer bytes.
+                # Without it the terminator returns only ~90 bytes (no useful footer).
+                #
+                # The extra chunk's ADC data IS part of the Blastware file body —
+                # confirmed from 4-27-26 TCP capture: all 14 A5 frames (including the
+                # extra chunk's 2 TCP sub-frames) contribute to the correct 6864-byte
+                # output.  write_blastware_file() includes all frames unconditionally.
+                #
+                # full_waveform=True (natural end-of-stream) downloads ALL chunks
+                # including post-event silence (35+ chunks for a 9-sec event at
+                # 1024 sps) — this produces 24KB+ files that Blastware rejects.
+                events = client.get_events(
+                    full_waveform=False,
+                    stop_after_index=index,
+                    extra_chunks_after_metadata=1,
+                )
+                matching = [ev for ev in events if ev.index == index]
+                return matching[0] if matching else None, info
+        ev, info = _run_with_retry(_do, is_tcp=_is_tcp(host))
+    except HTTPException:
+        raise
+    except ProtocolError as exc:
+        log.error("blastware_file: protocol error: %s", exc, exc_info=True)
+        raise HTTPException(status_code=502, detail=f"Protocol error: {exc}") from exc
+    except OSError as exc:
+        log.error("blastware_file: connection error: %s", exc, exc_info=True)
+        raise HTTPException(status_code=502, detail=f"Connection error: {exc}") from exc
+    except Exception as exc:
+        log.error("blastware_file: unexpected error: %s", exc, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Device error: {exc}") from exc
+
+    if ev is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Event index {index} not found on device",
+        )
+
+    a5_frames = getattr(ev, "_a5_frames", None)
+    if not a5_frames:
+        raise HTTPException(
+            status_code=502,
+            detail=f"No waveform data received for event index {index} — 5A download failed",
+        )
+
+    # Determine serial number from device info
+    serial = getattr(info, "serial", None) or "UNKNOWN"
+
+    # Build filename using the same algorithm Blastware uses
+    filename = blastware_filename(ev, serial)
+
+    # Write to /tmp so FastAPI can stream it back
+    out_path = Path("/tmp") / filename
+    write_blastware_file(ev, a5_frames, out_path)
+    log.info(
+        "blastware_file: wrote %s (%d A5 frames, serial=%s)",
+        out_path, len(a5_frames), serial,
+    )
+
+    return FileResponse(
+        path=str(out_path),
+        filename=filename,
+        media_type="application/octet-stream",
+    )
+
+
 # ── Write endpoints ───────────────────────────────────────────────────────────
 
 class DeviceConfigBody(BaseModel):