Add TCP/modem transport (Sierra Wireless RV55/RX55 field units)

- minimateplus/transport.py: add TcpTransport — stdlib socket-based transport
  with same interface as SerialTransport. Overrides read_until_idle() with
  idle_gap=1.5s to absorb the modem's 1-second serial data forwarding buffer.
- minimateplus/client.py: make `port` param optional (default "") so
  MiniMateClient works cleanly when a pre-built transport is injected.
- minimateplus/__init__.py: export SerialTransport and TcpTransport.
- sfm/server.py: add `host` / `tcp_port` query params to all device endpoints.
  New _build_client() helper selects TCP or serial transport automatically.
  OSError (connection refused, timeout) now returns HTTP 502.
- docs/instantel_protocol_reference.md: add changelog entry and full §14
  (TCP/Modem Transport) documenting confirmed transparent passthrough, no ENQ
  on connect, modem forwarding delay, call-up vs ACH modes, and hardware note
  deprecating Raven X in favour of RV55/RX55.

Usage: GET /device/info?host=<modem_ip>&tcp_port=12345

.gitignore

@@ -1,5 +1,7 @@
 /bridges/captures/
 
+/manuals/
+
 # Python bytecode
 __pycache__/
 *.py[cod]

README.md

@@ -0,0 +1,278 @@
+# seismo-relay
+
+Tools for capturing and reverse-engineering the RS-232 serial protocol between
+**Blastware** software and **Instantel MiniMate Plus** seismographs.
+
+Built for Windows, stdlib-only (plus `pyserial` for the bridge).
+
+---
+
+## What's in here
+
+```
+seismo-relay/
+├── bridges/
+│   ├── s3-bridge/
+│   │   └── s3_bridge.py       ← The serial bridge (core capture tool)
+│   ├── gui_bridge.py          ← Tkinter GUI wrapper for s3_bridge
+│   └── raw_capture.py         ← Simpler raw-only capture tool
+└── parsers/
+    ├── s3_parser.py           ← Low-level DLE frame extractor
+    ├── s3_analyzer.py         ← Protocol analyzer (sessions, diffs, exports)
+    ├── gui_analyzer.py        ← Tkinter GUI for the analyzer
+    └── frame_db.py            ← SQLite frame database
+```
+
+---
+
+## How it all fits together
+
+The workflow has two phases: **capture**, then **analyze**.
+
+```
+  Blastware PC
+       │
+  Virtual COM (e.g. COM4)
+       │
+  s3_bridge.py  ←─── sits in the middle, forwards all bytes both ways
+       │              writes raw_bw.bin and raw_s3.bin
+  Physical COM (e.g. COM5)
+       │
+  MiniMate Plus seismograph
+```
+
+After capturing, you point the analyzer at the two `.bin` files to inspect
+what happened.
+
+---
+
+## Part 1 — The Bridge
+
+### `s3_bridge.py` — Serial bridge
+
+Transparently forwards bytes between Blastware and the seismograph while
+logging everything to disk. Blastware operates normally and has no idea the
+bridge is there.
+
+**Run it:**
+```
+python bridges/s3-bridge/s3_bridge.py --bw COM4 --s3 COM5 --logdir captures/
+```
+
+**Key flags:**
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--bw` | required | COM port connected to Blastware |
+| `--s3` | required | COM port connected to the seismograph |
+| `--baud` | 38400 | Baud rate (match your device) |
+| `--logdir` | `.` | Where to write log/bin files |
+| `--raw-bw` | off | Also write a flat raw file for BW→S3 traffic |
+| `--raw-s3` | off | Also write a flat raw file for S3→BW traffic |
+
+**Output files (in `--logdir`):**
+- `s3_session_<timestamp>.bin` — structured binary log with timestamps
+  and direction tags (record format: `[type:1][ts_us:8][len:4][payload]`)
+- `s3_session_<timestamp>.log` — human-readable hex dump (text)
+- `raw_bw.bin` — flat BW→S3 byte stream (if `--raw-bw` used)
+- `raw_s3.bin` — flat S3→BW byte stream (if `--raw-s3` used)
+
+> The analyzer needs `raw_bw.bin` + `raw_s3.bin`. Always use `--raw-bw` and
+> `--raw-s3` when capturing.
+
+**Interactive commands** (type while bridge is running):
+- `m` + Enter → prompts for a label and inserts a MARK record into the log
+- `q` + Enter → quit
+
+---
+
+### `gui_bridge.py` — Bridge GUI
+
+A simple point-and-click wrapper around `s3_bridge.py`. Easier than the
+command line if you don't want to type flags every time.
+
+```
+python bridges/gui_bridge.py
+```
+
+Set your COM ports, log directory, and tick the raw tap checkboxes before
+hitting **Start**. The **Add Mark** button lets you annotate the capture
+at any point (e.g. "changed record time to 13s").
+
+---
+
+## Part 2 — The Analyzer
+
+After capturing, you have `raw_bw.bin` (bytes Blastware sent) and `raw_s3.bin`
+(bytes the seismograph replied with). The analyzer parses these into protocol
+frames, groups them into sessions, and helps you figure out what each byte means.
+
+### What's a "session"?
+
+Each time you open the settings dialog in Blastware and click Apply/OK, that's
+one session — a complete read/modify/write cycle. The bridge detects session
+boundaries by watching for the final write-confirm packet (SUB `0x74`).
+
+Each session contains a sequence of request/response frame pairs:
+- Blastware sends a **request** (BW→S3): "give me your config block"
+- The seismograph sends a **response** (S3→BW): here it is
+- At the end, Blastware sends the modified settings back in a series of write packets
+
+The analyzer lines these up and diffs consecutive sessions to show you exactly
+which bytes changed.
+
+---
+
+### `gui_analyzer.py` — Analyzer GUI
+
+```
+python parsers/gui_analyzer.py
+```
+
+This is the main tool. It has five tabs:
+
+#### Toolbar
+- **S3 raw / BW raw** — browse to your `raw_s3.bin` and `raw_bw.bin` files
+- **Analyze** — parse and load the captures
+- **Live: OFF/ON** — watch the files grow in real time while the bridge is running
+- **Export for Claude** — generate a self-contained `.md` report for AI-assisted analysis
+
+#### Inventory tab
+Shows all frames in the selected session — direction, SUB command, page,
+length, and checksum status. Click any frame in the left tree to drill in.
+
+#### Hex Dump tab
+Full hex dump of the selected frame's payload. If the frame had changed bytes
+vs the previous session, those are listed below the dump with before/after values
+and field names where known.
+
+#### Diff tab
+Side-by-side byte-level diff between the current session and the previous one.
+Only SUBs (command types) that actually changed are shown.
+
+#### Full Report tab
+Raw text version of the session report — useful for copying into notes.
+
+#### Query DB tab
+Search across all your captured sessions using the built-in database.
+
+---
+
+### `s3_analyzer.py` — Analyzer (command line)
+
+If you prefer the terminal:
+
+```
+python parsers/s3_analyzer.py --s3 raw_s3.bin --bw raw_bw.bin
+```
+
+**Flags:**
+| Flag | Description |
+|------|-------------|
+| `--s3` | Path to raw_s3.bin |
+| `--bw` | Path to raw_bw.bin |
+| `--live` | Tail files in real time (poll mode) |
+| `--export` | Also write a `claude_export_<ts>.md` file |
+| `--outdir` | Where to write `.report` files (default: same folder as input) |
+| `--poll` | Live mode poll interval in seconds (default: 0.05) |
+
+Writes one `.report` file per session and prints a summary to the console.
+
+---
+
+## The Frame Database
+
+Every time you click **Analyze**, the frames are automatically saved to a
+SQLite database at:
+
+```
+C:\Users\<you>\.seismo_lab\frames.db
+```
+
+This accumulates captures over time so you can query across sessions and dates.
+
+### Query DB tab
+
+Use the filter bar to search:
+- **Capture** — narrow to a specific capture (timestamp shown)
+- **Dir** — BW (requests) or S3 (responses) only
+- **SUB** — filter by command type (e.g. `0xF7` = EVENT_INDEX_RESPONSE)
+- **Offset** — filter to frames that have a specific byte offset
+- **Value** — combined with Offset: "show frames where byte 85 = 0x0A"
+
+Click any result row, then use the **Byte interpretation** panel at the bottom
+to see what that offset's bytes look like as uint8, int8, uint16 BE/LE,
+uint32 BE/LE, and float32 BE/LE simultaneously.
+
+This is the main tool for mapping unknown fields — if you change one setting in
+Blastware, capture before and after, then query for frames where that offset
+moved, you can pin down exactly which byte controls what.
+
+---
+
+## Export for Claude
+
+The **Export for Claude** button (orange, in the toolbar) generates a single
+`.md` file containing:
+
+1. Protocol background and known field map
+2. Capture summary (session count, frame counts, what changed)
+3. Per-diff tables — before/after bytes for every changed offset, with field
+   names where known
+4. Full hex dumps of all frames in the baseline session
+
+Paste this file into a Claude conversation to get help mapping unknown fields,
+interpreting data structures, or understanding sequences.
+
+---
+
+## Protocol quick-reference
+
+| Term | Value | Meaning |
+|------|-------|---------|
+| DLE | `0x10` | Data Link Escape |
+| STX | `0x02` | Start of frame |
+| ETX | `0x03` | End of frame |
+| ACK | `0x41` | Frame start marker (BW side) |
+| DLE stuffing | `10 10` on wire | Literal `0x10` in payload |
+
+**S3-side frame** (seismograph → Blastware): `DLE STX [payload] DLE ETX`
+**BW-side frame** (Blastware → seismograph): `ACK STX [payload] ETX`
+
+**De-stuffed payload header** (first 5 bytes after de-stuffing):
+```
+[0] CMD        0x10 = BW request, 0x00 = S3 response
+[1] ?          0x00 (BW) or 0x10 (S3)
+[2] SUB        Command/response identifier  ← the key field
+[3] OFFSET_HI  Page address high byte
+[4] OFFSET_LO  Page address low byte
+[5+] DATA      Payload content
+```
+
+**Response SUB rule:** `response_SUB = 0xFF - request_SUB`
+Example: request SUB `0x08` → response SUB `0xF7`
+
+---
+
+## Requirements
+
+```
+pip install pyserial
+```
+
+Python 3.10+. Everything else is stdlib (Tkinter, sqlite3, struct, hashlib).
+
+Tkinter is included with the standard Python installer on Windows. If it's
+missing, reinstall Python and make sure "tcl/tk and IDLE" is checked.
+
+---
+
+## Virtual COM ports
+
+The bridge needs two COM ports on the same PC — one that Blastware connects to,
+and one wired to the actual seismograph. On Windows, use a virtual COM port pair
+(e.g. **com0com** or **VSPD**) to give Blastware a port to talk to while the
+bridge sits in the middle.
+
+```
+Blastware → COM4 (virtual) ↔ s3_bridge ↔ COM5 (physical) → MiniMate
+```

bridges/gui_bridge.py

@@ -13,6 +13,7 @@ Requires only the stdlib (Tkinter is bundled on Windows/Python).
 
 from __future__ import annotations
 
+import datetime
 import os
 import queue
 import subprocess
@@ -125,11 +126,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_bw = self.raw_bw_var.get().strip()
         raw_s3 = self.raw_s3_var.get().strip()
+
+        # 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]
 
         try:

bridges/s3-bridge/s3_bridge.py

@@ -345,14 +345,25 @@ def main() -> int:
     ts = _dt.datetime.now().strftime("%Y%m%d_%H%M%S")
     log_path = os.path.join(args.logdir, f"s3_session_{ts}.log")
     bin_path = os.path.join(args.logdir, f"s3_session_{ts}.bin")
-    logger = SessionLogger(log_path, bin_path, raw_bw_path=args.raw_bw, raw_s3_path=args.raw_s3)
+
+    # 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
+
+    logger = SessionLogger(log_path, bin_path, raw_bw_path=raw_bw_path, raw_s3_path=raw_s3_path)
 
     print(f"[LOG] Writing hex log to  {log_path}")
     print(f"[LOG] Writing binary log to {bin_path}")
-    if args.raw_bw:
+    if raw_bw_path:
-        print(f"[LOG] Raw tap BW->S3  -> {args.raw_bw}")
+        print(f"[LOG] Raw tap BW->S3  -> {raw_bw_path}")
-    if args.raw_s3:
+    if raw_s3_path:
-        print(f"[LOG] Raw tap S3->BW -> {args.raw_s3}")
+        print(f"[LOG] Raw tap S3->BW -> {raw_s3_path}")
 
     logger.log_info(f"s3_bridge {VERSION} start")
     logger.log_info(f"BW={args.bw} S3={args.s3} baud={args.baud}")

docs/instantel_protocol_reference.md

@@ -50,6 +50,15 @@
 | 2026-03-09 | §7.8, §14, Appendix B | **NEW — Trigger Sample Width confirmed:** Located in BW→S3 write frame SUB `0x82`, destuffed payload offset `[22]`, uint8. Confirmed via BW-side capture (`raw_bw.bin`) diffing two sessions: Width=4 → `0x04`, Width=3 → `0x03`. Setting is **transmitted only on BW→S3 write** (SUB `0x82`), invisible in S3-side compliance dumps. |
 | 2026-03-09 | §14, Appendix B | **CONFIRMED — Mode gating is a real protocol behavior:** Several settings are only transmitted (and possibly only interpreted by the device) when the required mode is active. Trigger Sample Width is only sent when in Compliance/Single-Shot/Fixed Record Time mode. Auto Window is only relevant when Record Stop Mode = Auto — attempting to capture it in Fixed mode produced no change on the wire (F7 and D1 blocks identical before/after). This is an architectural property, not a gap in the capture methodology. Future capture attempts for mode-gated settings must first activate the appropriate mode. |
 | 2026-03-09 | §14 | **UPDATED — Auto Window:** Capture attempted (Auto Window 3→9) in Fixed record time mode. No change observed in any S3-side frame (F7, D1, E5 all identical). Confirmed mode-gated behind Record Stop Mode = Auto. Not capturable without switching modes — deferred. |
+| 2026-03-11 | §14, Appendix B | **CONFIRMED — Aux Trigger read location:** SUB `FE` (FULL_CONFIG_RESPONSE), destuffed payload offset `0x0109`, uint8. `0x00` = disabled, `0x01` = enabled. Confirmed via controlled capture: changed Aux Trigger in Blastware, sent to unit, re-read config. FE diff showed clean isolated flip at `0x0109` with only 3 other bytes changing (likely counters/checksums at `0x0033`, `0x00C0`, `0x04ED`). |
+| 2026-03-11 | §14, Appendix B | **PARTIAL — Aux Trigger write path:** Write command not yet isolated. The BW→S3 write appears to occur inside the A4 (POLL_RESPONSE) stream via inner frame handshaking — multiple WRITE_CONFIRM_RESPONSE inner frames (SUBs `7C`, `7D`, `8B`, `8C`, `8D`, `8E`, `96`, `97`) appeared in A4 after the write, and the TRIGGER_CONFIG_RESPONSE (SUB `E3`) inner frames were removed. Write command itself not yet captured in a clean session — likely SUB `15` or embedded in the partial session 0. Write path deferred for a future clean capture. |
+| 2026-03-11 | §4, §14 | **NEW — SUB A4 is a composite container frame:** A4 (POLL_RESPONSE) payload contains multiple embedded inner frames using the same DLE framing (10 02 start, 10 03 end, 10 10 stuffing). Phase-shift diffing issue resolved in s3_analyzer.py by adding `_extract_a4_inner_frames()` and `_diff_a4_payloads()` — diff count reduced from 2300 → 17 meaningful entries. |
+| 2026-03-11 | §14 | **NEW — SUB `6E` response anomaly:** BW sends SUB `1C` (TRIGGER_CONFIG_READ) and S3 responds with SUB `6E` — does NOT follow the `0xFF - SUB` rule (`0xFF - 0x1C = 0xE3`). Only known exception to the response pairing rule observed to date. SUB `6E` payload starts with ASCII string `"Long2"`. |
+| 2026-03-12 | §11 | **CONFIRMED — BW→S3 large-frame checksum algorithm:** SUBs `68`, `69`, `71`, `82`, and `1A` (with data) use: `chk = (sum(b for b in payload[2:-1] if b != 0x10) + 0x10) % 256` — SUM8 of payload bytes `[2:-1]` skipping all `0x10` bytes, plus `0x10` as a constant, mod 256. Validated across 20 frames from two independent captures with differing string content (checksums differ between sessions, both validate correctly). Small frames (POLL, read commands) continue to use plain SUM8 of `payload[0:-1]`. The two formulas are consistent: small frames have exactly one `0x10` (CMD at `[0]`), which the large-frame formula's `[2:]` start and `+0x10` constant account for. |
+| 2026-03-12 | §11 | **RESOLVED — BAD CHK false positives on BW POLL frames:** Parser bug — BW frame terminator (`03 41`, ETX+ACK) was being included in the de-stuffed payload instead of being stripped as framing. BW frames end with bare `0x03` (not `10 03`). Fix: strip trailing `03 41` from BW payloads before checksum computation. |
+| 2026-03-30 | §3, §5.1 | **CONFIRMED — BW→S3 two-step read offset is at payload[5], NOT payload[3:4].** All BW read-command frames have `payload[3] = 0x00` and `payload[4] = 0x00` unconditionally. The two-step offset byte lives at `payload[5]`: `0x00` for the length-probe step, `DATA_LEN` for the data-fetch step. Validated against all captured frames in `bridges/captures/3-11-26/raw_bw_*.bin` — every frame is an exact bit-for-bit match when built with offset at `[5]`. The `page_hi`/`page_lo` framing in the docstring was a misattribution from the S3-side response layout (where `[3]`/`[4]` ARE page bytes). |
+| 2026-03-30 | §4, §5.2 | **CONFIRMED — S3 probe response page_key is always 0x0000.** The S3 response to a length-probe step does NOT carry the data length back in `page_hi`/`page_lo`. Both bytes are `0x00` in every observed probe response. Data lengths for each SUB are fixed constants (see §5.1 table). The `minimateplus` library now uses a hardcoded `DATA_LENGTHS` dict rather than trying to read the length from the probe response. |
+| 2026-03-31 | §12 TCP Transport | **NEW SECTION — TCP/modem transport confirmed transparent from Blastware Operator Manual (714U0301 Rev 22).** Key facts confirmed: (1) Protocol bytes over TCP are bit-for-bit identical to RS-232 — no handshake framing. (2) No ENQ byte on TCP connect (`Enable ENQ on TCP Connect: 0-Disable` in Raven ACEmanager). (3) Raven modem `Data Forwarding Timeout = 1 second` — modem buffers serial bytes up to 1s before forwarding over TCP; `TcpTransport.read_until_idle` uses `idle_gap=1.5s` to compensate. (4) TCP port is user-configurable (12335 in manual example; user's install uses 12345). (5) Baud rate over serial link to modem is 38400,8N1 regardless of TCP path. (6) ACH (Auto Call Home) = INBOUND to server (unit calls home); "call up" = OUTBOUND from client (Blastware/SFM connects to modem IP). `TcpTransport` implements outbound (call-up) mode. |
 
 ---
 
@@ -293,7 +302,9 @@ Write commands are initiated by Blastware (`BW->S3`) and use SUB bytes in the `0
 
 ## 7. Known Data Payloads
 
-### 7.1 Poll Response (SUB A4) — Device Identity Block
+### 7.1 Poll Response (SUB A4) — Device Identity Block / Composite Container
+
+> ⚠️ **SUB A4 is a composite container frame.** The large A4 payload (~3600+ bytes) contains multiple embedded inner sub-frames using the same DLE framing as the outer protocol (`10 02` start, `10 03` end, `10 10` stuffing). Inner frames carry WRITE_CONFIRM_RESPONSE and TRIGGER_CONFIG_RESPONSE sub-frames among others. Flat byte-by-byte diffing of A4 is unreliable due to phase shifting — use inner-frame-aware diffing (`_diff_a4_payloads()` in s3_analyzer.py). Confirmed 2026-03-11.
 
 Two-step read. Data payload = 0x30 bytes.
 
@@ -709,7 +720,32 @@ ESCAPE:
 ---
 
 ## 11. Checksum Reference Implementation
-> ⚠️ **Updated 2026-02-26** — Rewritten for correct DLE framing and byte stuffing.
+> ⚠️ **Updated 2026-03-12** — BW→S3 large-frame checksum algorithm confirmed. Two distinct formulas apply depending on frame direction and size.
+
+### Checksum Overview
+
+| Direction | Frame type | Formula | Coverage |
+|---|---|---|---|
+| S3→BW | All frames | `sum(payload) & 0xFF` | All de-stuffed payload bytes `[0:-1]` |
+| BW→S3 | Small frames (POLL, read cmds) | `sum(payload) & 0xFF` | All de-stuffed payload bytes `[0:-1]` |
+| BW→S3 | Large write frames (SUB `68`,`69`,`71`,`82`,`1A`+data) | See formula below | De-stuffed payload bytes `[2:-1]`, skipping `0x10` bytes, plus constant |
+
+### BW→S3 Large-Frame Checksum Formula
+
+```python
+def calc_checksum_bw_large(payload: bytes) -> int:
+    """
+    Checksum for large BW→S3 write frames (SUB 68, 69, 71, 82, 1A with data).
+    
+    Formula: sum all bytes in payload[2:-1], skipping 0x10 bytes, add 0x10, mod 256.
+    Confirmed across 20 frames from two independent captures (2026-03-12).
+    """
+    return (sum(b for b in payload[2:-1] if b != 0x10) + 0x10) & 0xFF
+```
+
+**Why this formula:** The CMD byte at `payload[0]` is always `0x10` (DLE). The byte at `payload[1]` is always `0x00`. Starting from `payload[2]` skips both. All `0x10` bytes in the data section are excluded from the sum, then `0x10` is added back as a constant — effectively treating DLE as a transparent/invisible byte in the checksum. This is consistent with `0x10` being a framing/control character in the protocol.
+
+**Consistency check:** For small frames, `payload[0]` = `0x10` and there are no other `0x10` bytes in the payload. The large-frame formula applied to a small frame would give `(sum(payload[2:-1]) + 0x10) = sum(payload[0:-1])` — identical to the plain SUM8. The two formulas converge for frames without embedded `0x10` data bytes.
 
 ```python
 DLE = 0x10
@@ -742,14 +778,27 @@ def destuff(data: bytes) -> bytes:
     return bytes(out)
 
 
-def calc_checksum(payload: bytes) -> int:
+def calc_checksum_s3(payload: bytes) -> int:
     """
-    8-bit sum of de-stuffed payload bytes, modulo 256.
+    Standard SUM8: used for all S3→BW frames and small BW→S3 frames.
-    Pass the original (pre-stuff) payload — not the wire bytes.
+    Sum of all payload bytes (excluding the checksum byte itself), mod 256.
     """
     return sum(payload) & 0xFF
 
 
+def calc_checksum_bw_large(payload: bytes) -> int:
+    """
+    Large BW→S3 write frame checksum (SUB 68, 69, 71, 82, 1A with data).
+    Sum payload[2:-1] skipping 0x10 bytes, add 0x10, mod 256.
+    """
+    return (sum(b for b in payload[2:-1] if b != 0x10) + 0x10) & 0xFF
+
+
+# Backwards-compatible alias
+def calc_checksum(payload: bytes) -> int:
+    return calc_checksum_s3(payload)
+
+
 def build_frame(payload: bytes) -> bytes:
     """
     Build a complete on-wire frame from a raw payload.
@@ -841,6 +890,129 @@ Build in this order — each step is independently testable:
 
 ---
 
+## 14. TCP / Modem Transport
+> ✅ **CONFIRMED — 2026-03-31** from Blastware Operator Manual 714U0301 Rev 22 §4.4 and ACEmanager Raven modem configuration screenshots.
+
+The MiniMate Plus protocol is **fully transport-agnostic at the byte level**.  The same DLE-framed S3/BW frame stream that flows over RS-232 is transmitted unmodified over a TCP socket.  No additional framing, handshake bytes, or session tokens are added at the application layer.
+
+---
+
+### 14.1 Two Usage Modes
+
+**"Call Up" (Outbound TCP — SFM connects to modem)**
+
+Blastware or SFM opens a TCP connection to the modem's static IP address on its device port.  The modem bridges the TCP socket to its RS-232 serial port, which is wired directly to the MiniMate Plus.  From the protocol perspective this is identical to a direct serial connection.
+
+```
+SFM ──TCP──► Raven modem ──RS-232──► MiniMate Plus
+             (static IP, port N)      (38400,8N1)
+```
+
+This is the mode implemented by `TcpTransport(host, port)`.  Typical call:
+
+```
+GET /device/info?host=203.0.113.5&tcp_port=12345
+```
+
+**"Call Home" / ACH (Inbound TCP — unit calls the server)**
+
+The MiniMate Plus is configured with an IP address and port.  On an event trigger or scheduled time it powers up its modem, which establishes a TCP connection outbound to the server.  Blastware (or a future SFM ACH listener) accepts the incoming connection.  After the unit connects, the PC has a configurable "Wait for Connection" window to send the first command before the unit times out and hangs up.
+
+```
+MiniMate Plus ──RS-232──► Raven modem ──TCP──► ACH server (listening)
+                                                (static office IP, port N)
+```
+
+`TcpTransport` is a **client** (outbound connect only).  A separate `AchServer` listener component is needed for this mode — not yet implemented.
+
+---
+
+### 14.2 No Application-Layer Handshake on TCP Connect
+
+✅ **Confirmed from ACEmanager configuration screenshot:**
+
+```
+Enable ENQ on TCP Connect: 0-Disable
+```
+
+When a TCP connection is established (in either direction), **no ENQ byte or other handshake marker is sent** by the modem before the protocol stream starts.  The first byte from either side is a raw protocol byte — for SFM-initiated call-up, SFM sends POLL_PROBE immediately after `connect()`.
+
+No banner, no "CONNECT" string, no Telnet negotiation preamble.  The Raven modem's TCP dialog is configured with:
+
+| ACEmanager Setting | Value | Meaning |
+|---|---|---|
+| TCP Auto Answer | 2 — Telnet Server | TCP mode (transparent pass-through, not actually Telnet) |
+| Telnet Echo Mode | 0 — No Echo | No echo of received bytes |
+| Enable ENQ on TCP Connect | 0 — Disable | No ENQ byte on connect |
+| TCP Connect Response Delay | 0 | No delay before first byte |
+| TCP Idle Timeout | 0 | No modem-level idle disconnect |
+
+---
+
+### 14.3 Modem Serial Port Configuration
+
+> **Hardware note:** The Raven X modem shown in the Blastware manual is 3G-only and no longer operational (3G network shutdown).  The current field hardware is the **Sierra Wireless RV55** (and newer RX55).  Both run ALEOS firmware and have an identical ACEmanager web UI — the settings below apply to all three generations.
+
+The modem's RS-232 port (wired to the MiniMate Plus) must be configured as:
+
+| ACEmanager Setting | Value |
+|---|---|
+| Configure Serial Port | **38400,8N1** |
+| Flow Control | None |
+| DB9 Serial Echo | OFF |
+| Data Forwarding Timeout | **1 second** (S50=1) |
+| Data Forwarding Character | 0 (disabled) |
+
+The **Data Forwarding Timeout** is the most protocol-critical setting.  The modem **accumulates bytes from the RS-232 port for up to 1 second** before forwarding them as a TCP segment.  This means:
+
+- A large S3 response frame may arrive as multiple TCP segments with up to 1-second gaps between them.
+- A `read_until_idle` implementation with `idle_gap < 1.0 s` will **incorrectly declare the frame complete mid-stream**.
+- `TcpTransport.read_until_idle` overrides the default `idle_gap=0.05 s` to `idle_gap=1.5 s` to compensate.
+
+If connecting to a unit via a direct Ethernet connection (no serial modem in the path), the 1.5 s idle gap will still work but will feel slower.  In that case you can pass `idle_gap=0.1` explicitly.
+
+---
+
+### 14.4 Connection Timeouts on the Unit Side
+
+The MiniMate Plus firmware has two relevant timeouts configurable via Blastware's Call Home Setup dialog:
+
+| Timeout | Description | Impact |
+|---|---|---|
+| **Wait for Connection** | Seconds after TCP connect during which the unit waits for the first BW frame. If nothing arrives, unit terminates the session. | SFM must send POLL_PROBE within this window after `connect()`. Default appears short (≈15–30 s). |
+| **Serial Idle Time** | Seconds of inactivity after which the unit terminates the connection. | SFM must complete its work and disconnect cleanly — or send periodic keep-alive frames — within this window. |
+
+For our `TcpTransport` + `MiniMateProtocol` stack, both timeouts are satisfied automatically because `connect()` is immediately followed by `protocol.poll()` which sends POLL_PROBE, and the full session (POLL + read + disconnect) typically completes in < 30 seconds.
+
+---
+
+### 14.5 Port Numbers
+
+The TCP port is **user-configurable** in both Blastware and the modem.  There is no universally fixed port.
+
+| Setting location | Value in manual example | Value in user's install |
+|---|---|---|
+| Blastware TCP Communication dialog | 12335 | 12345 |
+| Raven ACEmanager Destination Port | 12349 (UDP example) | varies |
+
+`TcpTransport` defaults to `DEFAULT_TCP_PORT = 12345` which matches the user's install.  This can be overridden by the `port` argument or the `tcp_port` query parameter in the SFM server.
+
+---
+
+### 14.6 ACH Session Lifecycle (Call Home Mode — Future)
+
+When the unit calls home under ACH, the session lifecycle from the unit's perspective is:
+
+1. Unit triggers (event or scheduled time)
+2. Unit powers up modem, dials / connects TCP to server IP:port
+3. Unit waits for "Wait for Connection" window for first BW frame from server
+4. Server sends POLL_PROBE → unit responds with POLL_RESPONSE (same as serial)
+5. Server reads serial number, full config, events as needed
+6. Server disconnects (or unit disconnects on Serial Idle Time expiry)
+7. Unit powers modem down, returns to monitor mode
+
+Step 4 onward is **identical to the serial/call-up protocol**.  The only difference from our perspective is that we are the **listener** rather than the **connector**.  A future `AchServer` class will accept the incoming TCP connection and hand the socket to `TcpTransport` for processing.
+
 ---
 
 ## Appendix A — s3_bridge Capture Format
@@ -883,7 +1055,9 @@ The `.bin` files produced by `s3_bridge` are **not raw wire bytes**. The logger
 | Meaning of `0x07 E7` field in config block | LOW | 2026-02-26 | |
 | **Trigger Sample Width** — **RESOLVED:** BW→S3 write frame SUB `0x82`, destuffed payload offset `[22]`, uint8. Width=4 → `0x04`, Width=3 → `0x03`. Confirmed via BW-side capture diff. Only visible in `raw_bw.bin` write traffic, not in S3-side compliance reads. | RESOLVED | 2026-03-02 | Confirmed 2026-03-09 |
 | **Auto Window** — "1 to 9 seconds" per manual (§3.13.1b). **Mode-gated:** only transmitted/active when Record Stop Mode = Auto. Capture attempted in Fixed mode (3→9 change) — no wire change observed in any frame. Deferred pending mode switch. | LOW | 2026-03-02 | Updated 2026-03-09 |
-| **Auxiliary Trigger** — Enabled/Disabled per manual (§3.13.1d). Location in protocol not yet mapped. | LOW | 2026-03-02 | NEW |
+| **Auxiliary Trigger read location** — **RESOLVED:** SUB `FE` offset `0x0109`, uint8, `0x00`=disabled, `0x01`=enabled. Confirmed 2026-03-11 via controlled toggle capture. | RESOLVED | 2026-03-02 | Resolved 2026-03-11 |
+| **Auxiliary Trigger write path** — Write command not yet captured in a clean session. Inner frame handshake visible in A4 (multiple WRITE_CONFIRM_RESPONSE SUBs appear, TRIGGER_CONFIG_RESPONSE removed), but the BW→S3 write command itself was in a partial session. Likely SUB `15` or similar. Deferred for clean capture. | LOW | 2026-03-11 | NEW |
+| **SUB `6E` response to SUB `1C`** — S3 responds to TRIGGER_CONFIG_READ (SUB `1C`) with SUB `6E`, NOT `0xE3` as the `0xFF - SUB` rule would predict. Only known exception to the response pairing rule observed to date. Payload starts with ASCII `"Long2"`. Purpose unknown. | LOW | 2026-03-11 | NEW |
 | **Max Geo Range float 6.2061 in/s** — NOT a user-selectable range (manual only shows 1.25 and 10.0 in/s). Likely internal ADC full-scale constant or hardware range ceiling. Not worth capturing. | LOW | 2026-02-26 | Downgraded 2026-03-02 |
 | MicL channel units — **RESOLVED: psi**, confirmed from `.set` file unit string `"psi\0"` | RESOLVED | 2026-03-01 | |
 | Backlight offset — **RESOLVED: +4B in event index data**, uint8, seconds | RESOLVED | 2026-03-02 | |
@@ -914,7 +1088,7 @@ The `.bin` files produced by `s3_bridge` are **not raw wire bytes**. The logger
 | Record Mode | §3.8.1 | Unknown | — | Single Shot, Continuous, Manual, Histogram, Histogram Combo |
 | Trigger Sample Width | §3.13.1h | BW→S3 SUB `0x82` write frame, destuffed `[22]`, uint8 | uint8 | Default=2; confirmed 4=`0x04`, 3=`0x03`. **BW-side write only** — not visible in S3 compliance reads. Mode-gated: only sent in Compliance/Single-Shot/Fixed mode. |
 | Auto Window | §3.13.1b | **Mode-gated — NOT YET MAPPED** | uint8? | 1–9 seconds; only active when Record Stop Mode = Auto. Capture in Fixed mode produced no wire change. |
-| Auxiliary Trigger | §3.13.1d | **NOT YET MAPPED** | bool | Enabled/Disabled |
+| Auxiliary Trigger | §3.13.1d | SUB `FE` (FULL_CONFIG_RESPONSE) offset `0x0109` (read); write path not yet isolated | uint8 (bool) | `0x00`=disabled, `0x01`=enabled; confirmed 2026-03-11 |
 | Password | §3.13.1c | Unknown | — | 4-key sequence |
 | Serial Connection | §3.9.11 | Unknown | — | Direct / Via Modem |
 | Baud Rate | §3.9.12 | Unknown | — | 38400 for direct |

minimateplus/__init__.py

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

minimateplus/client.py

@@ -0,0 +1,483 @@
+"""
+client.py — MiniMateClient: the top-level public API for the library.
+
+Combines transport, protocol, and model decoding into a single easy-to-use
+class.  This is the only layer that the SFM server (sfm/server.py) imports
+directly.
+
+Design: stateless per-call (connect → do work → disconnect).
+The client does not hold an open connection between calls.  This keeps the
+first implementation simple and matches Blastware's observed behaviour.
+Persistent connections can be added later without changing the public API.
+
+Example (serial):
+    from minimateplus import MiniMateClient
+
+    with MiniMateClient("COM5") as device:
+        info   = device.connect()          # POLL handshake + identity read
+        events = device.get_events()       # download all events
+
+Example (TCP / modem):
+    from minimateplus import MiniMateClient
+    from minimateplus.transport import TcpTransport
+
+    transport = TcpTransport("203.0.113.5", port=12345)
+    with MiniMateClient(transport=transport) as device:
+        info = device.connect()
+"""
+
+from __future__ import annotations
+
+import logging
+import struct
+from typing import Optional
+
+from .framing import S3Frame
+from .models import (
+    DeviceInfo,
+    Event,
+    PeakValues,
+    ProjectInfo,
+    Timestamp,
+)
+from .protocol import MiniMateProtocol, ProtocolError
+from .protocol import (
+    SUB_SERIAL_NUMBER,
+    SUB_FULL_CONFIG,
+    SUB_EVENT_INDEX,
+    SUB_EVENT_HEADER,
+    SUB_WAVEFORM_RECORD,
+)
+from .transport import SerialTransport, BaseTransport
+
+log = logging.getLogger(__name__)
+
+
+# ── MiniMateClient ────────────────────────────────────────────────────────────
+
+class MiniMateClient:
+    """
+    High-level client for a single MiniMate Plus device.
+
+    Args:
+        port:      Serial port name (e.g. "COM5", "/dev/ttyUSB0").
+                   Not required when a pre-built transport is provided.
+        baud:      Baud rate (default 38400, ignored when transport is provided).
+        timeout:   Per-request receive timeout in seconds (default 15.0).
+        transport: Pre-built transport (SerialTransport or TcpTransport).
+                   If None, a SerialTransport is constructed from port/baud.
+    """
+
+    def __init__(
+        self,
+        port: str = "",
+        baud: int = 38_400,
+        timeout: float = 15.0,
+        transport: Optional[BaseTransport] = None,
+    ) -> None:
+        self.port    = port
+        self.baud    = baud
+        self.timeout = timeout
+        self._transport: Optional[BaseTransport] = transport
+        self._proto: Optional[MiniMateProtocol] = None
+
+    # ── Connection lifecycle ──────────────────────────────────────────────────
+
+    def open(self) -> None:
+        """Open the transport connection."""
+        if self._transport is None:
+            self._transport = SerialTransport(self.port, self.baud)
+        if not self._transport.is_connected:
+            self._transport.connect()
+        self._proto = MiniMateProtocol(self._transport, recv_timeout=self.timeout)
+
+    def close(self) -> None:
+        """Close the transport connection."""
+        if self._transport and self._transport.is_connected:
+            self._transport.disconnect()
+        self._proto = None
+
+    @property
+    def is_open(self) -> bool:
+        return bool(self._transport and self._transport.is_connected)
+
+    # ── Context manager ───────────────────────────────────────────────────────
+
+    def __enter__(self) -> "MiniMateClient":
+        self.open()
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def connect(self) -> DeviceInfo:
+        """
+        Perform the startup handshake and read device identity.
+
+        Opens the connection if not already open.
+
+        Reads:
+          1. POLL handshake (startup)
+          2. SUB 15 — serial number
+          3. SUB 01 — full config block (firmware, model strings)
+
+        Returns:
+            Populated DeviceInfo.
+
+        Raises:
+            ProtocolError: on any communication failure.
+        """
+        if not self.is_open:
+            self.open()
+
+        proto = self._require_proto()
+
+        log.info("connect: POLL startup")
+        proto.startup()
+
+        log.info("connect: reading serial number (SUB 15)")
+        sn_data = proto.read(SUB_SERIAL_NUMBER)
+        device_info = _decode_serial_number(sn_data)
+
+        log.info("connect: reading full config (SUB 01)")
+        cfg_data = proto.read(SUB_FULL_CONFIG)
+        _decode_full_config_into(cfg_data, device_info)
+
+        log.info("connect: %s", device_info)
+        return device_info
+
+    def get_events(self, include_waveforms: bool = True) -> list[Event]:
+        """
+        Download all stored events from the device.
+
+        For each event in the index:
+          1. SUB 1E — event header (timestamp, sample rate)
+          2. SUB 0C — full waveform record (peak values, project strings)
+
+        Raw ADC waveform samples (SUB 5A bulk stream) are NOT downloaded
+        here — they can be large.  Pass include_waveforms=True to also
+        download them (not yet implemented, reserved for a future call).
+
+        Args:
+            include_waveforms: Reserved.  Currently ignored.
+
+        Returns:
+            List of Event objects, one per stored record on the device.
+
+        Raises:
+            ProtocolError: on any communication failure.
+        """
+        proto = self._require_proto()
+
+        log.info("get_events: reading event index (SUB 08)")
+        index_data = proto.read(SUB_EVENT_INDEX)
+        event_count = _decode_event_count(index_data)
+        log.info("get_events: %d event(s) found", event_count)
+
+        events: list[Event] = []
+        for i in range(event_count):
+            log.info("get_events: downloading event %d/%d", i + 1, event_count)
+            ev = self._download_event(proto, i)
+            if ev:
+                events.append(ev)
+
+        return events
+
+    # ── Internal helpers ──────────────────────────────────────────────────────
+
+    def _require_proto(self) -> MiniMateProtocol:
+        if self._proto is None:
+            raise RuntimeError("MiniMateClient is not connected.  Call open() first.")
+        return self._proto
+
+    def _download_event(
+        self, proto: MiniMateProtocol, index: int
+    ) -> Optional[Event]:
+        """Download header + waveform record for one event by index."""
+        ev = Event(index=index)
+
+        # SUB 1E — event header (timestamp, sample rate).
+        #
+        # The two-step event-header read passes the event index at payload[5]
+        # of the data-request frame (consistent with all other reads).
+        # This limits addressing to events 0–255 without a multi-byte scheme;
+        # the MiniMate Plus stores up to ~1000 events, so high indices may need
+        # a revised approach once we have captured event-download frames.
+        try:
+            from .framing import build_bw_frame
+            from .protocol import _expected_rsp_sub, SUB_EVENT_HEADER
+
+            # Step 1 — probe (offset=0)
+            probe_frame = build_bw_frame(SUB_EVENT_HEADER, 0)
+            proto._send(probe_frame)
+            _probe_rsp = proto._recv_one(expected_sub=_expected_rsp_sub(SUB_EVENT_HEADER))
+
+            # Step 2 — data request (offset = event index, clamped to 0xFF)
+            event_offset = min(index, 0xFF)
+            data_frame = build_bw_frame(SUB_EVENT_HEADER, event_offset)
+            proto._send(data_frame)
+            data_rsp = proto._recv_one(expected_sub=_expected_rsp_sub(SUB_EVENT_HEADER))
+
+            _decode_event_header_into(data_rsp.data, ev)
+        except ProtocolError as exc:
+            log.warning("event %d: header read failed: %s", index, exc)
+            return ev  # Return partial event rather than losing it entirely
+
+        # SUB 0C — full waveform record (peak values, project strings).
+        try:
+            wf_data = proto.read(SUB_WAVEFORM_RECORD)
+            _decode_waveform_record_into(wf_data, ev)
+        except ProtocolError as exc:
+            log.warning("event %d: waveform record read failed: %s", index, exc)
+
+        return ev
+
+
+# ── Decoder functions ─────────────────────────────────────────────────────────
+#
+# Pure functions: bytes → model field population.
+# Kept here (not in models.py) to isolate protocol knowledge from data shapes.
+
+def _decode_serial_number(data: bytes) -> DeviceInfo:
+    """
+    Decode SUB EA (SERIAL_NUMBER_RESPONSE) payload into a new DeviceInfo.
+
+    Layout (10 bytes total per §7.2):
+      bytes 0–7:  serial string, null-terminated, null-padded ("BE18189\\x00")
+      byte 8:     unit-specific trailing byte (purpose unknown ❓)
+      byte 9:     firmware minor version (0x11 = 17) ✅
+
+    Returns:
+        New DeviceInfo with serial, firmware_minor, serial_trail_0 populated.
+    """
+    if len(data) < 9:
+        # Short payload — gracefully degrade
+        serial = data.rstrip(b"\x00").decode("ascii", errors="replace")
+        return DeviceInfo(serial=serial, firmware_minor=0)
+
+    serial = data[:8].rstrip(b"\x00").decode("ascii", errors="replace")
+    trail_0 = data[8] if len(data) > 8 else None
+    fw_minor = data[9] if len(data) > 9 else 0
+
+    return DeviceInfo(
+        serial=serial,
+        firmware_minor=fw_minor,
+        serial_trail_0=trail_0,
+    )
+
+
+def _decode_full_config_into(data: bytes, info: DeviceInfo) -> None:
+    """
+    Decode SUB FE (FULL_CONFIG_RESPONSE) payload into an existing DeviceInfo.
+
+    The FE response arrives as a composite S3 outer frame whose data section
+    contains inner DLE-framed sub-frames.  Because of this nesting the §7.3
+    fixed offsets (0x34, 0x3C, 0x44, 0x6D) are unreliable — they assume a
+    clean non-nested payload starting at byte 0.
+
+    Instead we search the whole byte array for known ASCII patterns.  The
+    strings are long enough to be unique in any reasonable payload.
+
+    Modifies info in-place.
+    """
+    def _extract(needle: bytes, max_len: int = 32) -> Optional[str]:
+        """Return the null-terminated ASCII string that starts with *needle*."""
+        pos = data.find(needle)
+        if pos < 0:
+            return None
+        end = pos
+        while end < len(data) and data[end] != 0 and (end - pos) < max_len:
+            end += 1
+        s = data[pos:end].decode("ascii", errors="replace").strip()
+        return s or None
+
+    # ── Manufacturer and model are straightforward literal matches ────────────
+    info.manufacturer = _extract(b"Instantel")
+    info.model        = _extract(b"MiniMate Plus")
+
+    # ── Firmware version: "S3xx.xx" — scan for the 'S3' prefix ───────────────
+    for i in range(len(data) - 5):
+        if data[i] == ord('S') and data[i + 1] == ord('3') and chr(data[i + 2]).isdigit():
+            end = i
+            while end < len(data) and data[end] not in (0, 0x20) and (end - i) < 12:
+                end += 1
+            candidate = data[i:end].decode("ascii", errors="replace").strip()
+            if "." in candidate and len(candidate) >= 5:
+                info.firmware_version = candidate
+                break
+
+    # ── DSP version: numeric "xx.xx" — search for known prefixes ─────────────
+    for prefix in (b"10.", b"11.", b"12.", b"9.", b"8."):
+        pos = data.find(prefix)
+        if pos < 0:
+            continue
+        end = pos
+        while end < len(data) and data[end] not in (0, 0x20) and (end - pos) < 8:
+            end += 1
+        candidate = data[pos:end].decode("ascii", errors="replace").strip()
+        # Accept only strings that look like "digits.digits"
+        if "." in candidate and all(c in "0123456789." for c in candidate):
+            info.dsp_version = candidate
+            break
+
+
+def _decode_event_count(data: bytes) -> int:
+    """
+    Extract stored event count from SUB F7 (EVENT_INDEX_RESPONSE) payload.
+
+    Layout per §7.4 (offsets from data section start):
+      +00:  00 58 09  — total index size or record count ❓
+      +03:  00 00 00 01  — possibly stored event count = 1 ❓
+
+    We use bytes +03..+06 interpreted as uint32 BE as the event count.
+    This is inferred (🔶) — the exact meaning of the first 3 bytes is unclear.
+    """
+    if len(data) < 7:
+        log.warning("event index payload too short (%d bytes), assuming 0 events", len(data))
+        return 0
+
+    # Try the uint32 at +3 first
+    count = struct.unpack_from(">I", data, 3)[0]
+
+    # Sanity check: MiniMate Plus manual says max ~1000 events
+    if count > 1000:
+        log.warning(
+            "event count %d looks unreasonably large — clamping to 0", count
+        )
+        return 0
+
+    return count
+
+
+def _decode_event_header_into(data: bytes, event: Event) -> None:
+    """
+    Decode SUB E1 (EVENT_HEADER_RESPONSE) into an existing Event.
+
+    The 6-byte timestamp is at the start of the data payload.
+    Sample rate location is not yet confirmed — left as None for now.
+
+    Modifies event in-place.
+    """
+    if len(data) < 6:
+        log.warning("event header payload too short (%d bytes)", len(data))
+        return
+    try:
+        event.timestamp = Timestamp.from_bytes(data[:6])
+    except ValueError as exc:
+        log.warning("event header timestamp decode failed: %s", exc)
+
+
+def _decode_waveform_record_into(data: bytes, event: Event) -> None:
+    """
+    Decode SUB F3 (FULL_WAVEFORM_RECORD) data into an existing Event.
+
+    Peak values are stored as IEEE 754 big-endian floats.  Confirmed
+    positions per §7.5 (search for the known float bytes in the payload).
+
+    This decoder is intentionally conservative — it searches for the
+    canonical 4×float32 pattern rather than relying on a fixed offset,
+    since the exact field layout is only partially confirmed.
+
+    Modifies event in-place.
+    """
+    # Attempt to extract four consecutive IEEE 754 BE floats from the
+    # known region of the payload (offsets are 🔶 INFERRED from captured data)
+    try:
+        peak_values = _extract_peak_floats(data)
+        if peak_values:
+            event.peak_values = peak_values
+    except Exception as exc:
+        log.warning("waveform record peak decode failed: %s", exc)
+
+    # Project strings — search for known ASCII labels
+    try:
+        project_info = _extract_project_strings(data)
+        if project_info:
+            event.project_info = project_info
+    except Exception as exc:
+        log.warning("waveform record project strings decode failed: %s", exc)
+
+
+def _extract_peak_floats(data: bytes) -> Optional[PeakValues]:
+    """
+    Scan the waveform record payload for four sequential float32 BE values
+    corresponding to Tran, Vert, Long, MicL peak values.
+
+    The exact offset is not confirmed (🔶), so we do a heuristic scan:
+    look for four consecutive 4-byte groups where each decodes as a
+    plausible PPV value (0 < v < 100 in/s or psi).
+
+    Returns PeakValues if a plausible group is found, else None.
+    """
+    # Require at least 16 bytes for 4 floats
+    if len(data) < 16:
+        return None
+
+    for start in range(0, len(data) - 15, 4):
+        try:
+            vals = struct.unpack_from(">4f", data, start)
+        except struct.error:
+            continue
+
+        # All four values should be non-negative and within plausible PPV range
+        if all(0.0 <= v < 100.0 for v in vals):
+            tran, vert, long_, micl = vals
+            # MicL (psi) is typically much smaller than geo values
+            # Simple sanity: at least two non-zero values
+            if sum(v > 0 for v in vals) >= 2:
+                log.debug(
+                    "peak floats at offset %d: T=%.4f V=%.4f L=%.4f M=%.6f",
+                    start, tran, vert, long_, micl
+                )
+                return PeakValues(
+                    tran=tran, vert=vert, long=long_, micl=micl
+                )
+    return None
+
+
+def _extract_project_strings(data: bytes) -> Optional[ProjectInfo]:
+    """
+    Search the waveform record payload for known ASCII label strings
+    ("Project:", "Client:", "User Name:", "Seis Loc:", "Extended Notes")
+    and extract the associated value strings that follow them.
+
+    Layout (per §7.5): each entry is [label ~16 bytes][value ~32 bytes],
+    null-padded.  We find the label, then read the next non-null chars.
+    """
+    def _find_string_after(needle: bytes, max_value_len: int = 64) -> Optional[str]:
+        pos = data.find(needle)
+        if pos < 0:
+            return None
+        # Skip the label (including null padding) until we find a non-null value
+        # The value starts at pos+len(needle), but may have a gap of null bytes
+        value_start = pos + len(needle)
+        # Skip nulls
+        while value_start < len(data) and data[value_start] == 0:
+            value_start += 1
+        if value_start >= len(data):
+            return None
+        # Read until null terminator or max_value_len
+        end = value_start
+        while end < len(data) and data[end] != 0 and (end - value_start) < max_value_len:
+            end += 1
+        value = data[value_start:end].decode("ascii", errors="replace").strip()
+        return value or None
+
+    project  = _find_string_after(b"Project:")
+    client   = _find_string_after(b"Client:")
+    operator = _find_string_after(b"User Name:")
+    location = _find_string_after(b"Seis Loc:")
+    notes    = _find_string_after(b"Extended Notes")
+
+    if not any([project, client, operator, location, notes]):
+        return None
+
+    return ProjectInfo(
+        project=project,
+        client=client,
+        operator=operator,
+        sensor_location=location,
+        notes=notes,
+    )

minimateplus/framing.py

@@ -0,0 +1,276 @@
+"""
+framing.py — DLE frame codec for the Instantel MiniMate Plus RS-232 protocol.
+
+Wire format:
+  BW→S3 (our requests):  [ACK=0x41] [STX=0x02] [stuffed payload+chk] [ETX=0x03]
+  S3→BW (device replies): [DLE=0x10] [STX=0x02] [stuffed payload+chk] [DLE=0x10] [ETX=0x03]
+
+  The ACK 0x41 byte often precedes S3 frames too — it is silently discarded
+  by the streaming parser.
+
+De-stuffed payload layout:
+  BW→S3 request frame:
+    [0] CMD      0x10 (BW request marker)
+    [1] flags    0x00
+    [2] SUB      command sub-byte
+    [3] 0x00     always zero in captured frames
+    [4] 0x00     always zero in captured frames
+    [5] OFFSET   two-step offset: 0x00 = length-probe, DATA_LEN = data-request
+    [6-15]       zero padding (total de-stuffed payload = 16 bytes)
+
+  S3→BW response frame:
+    [0] CMD      0x00 (S3 response marker)
+    [1] flags    0x10
+    [2] SUB      response sub-byte (= 0xFF - request SUB)
+    [3] PAGE_HI  high byte of page address (always 0x00 in observed frames)
+    [4] PAGE_LO  low byte                  (always 0x00 in observed frames)
+    [5+] data    payload data section (composite inner frames for large responses)
+
+DLE stuffing rule: any 0x10 byte in the payload is doubled on the wire (0x10 → 0x10 0x10).
+This applies to the checksum byte too.
+
+Confirmed from live captures (s3_parser.py validation + raw_bw.bin / raw_s3.bin).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+# ── Protocol byte constants ───────────────────────────────────────────────────
+
+DLE = 0x10   # Data Link Escape
+STX = 0x02   # Start of text
+ETX = 0x03   # End of text
+ACK = 0x41   # Acknowledgement / frame-start marker (BW side)
+
+BW_CMD  = 0x10   # CMD byte value in BW→S3 frames
+S3_CMD  = 0x00   # CMD byte value in S3→BW frames
+S3_FLAGS = 0x10  # flags byte value in S3→BW frames
+
+# BW read-command payload size: 5 header bytes + 11 padding bytes = 16 total.
+# Confirmed from captured raw_bw.bin: all read-command frames carry exactly 16
+# de-stuffed bytes (excluding the appended checksum).
+_BW_PAYLOAD_SIZE = 16
+
+
+# ── DLE stuffing / de-stuffing ────────────────────────────────────────────────
+
+def dle_stuff(data: bytes) -> bytes:
+    """Escape literal 0x10 bytes: 0x10 → 0x10 0x10."""
+    out = bytearray()
+    for b in data:
+        if b == DLE:
+            out.append(DLE)
+        out.append(b)
+    return bytes(out)
+
+
+def dle_unstuff(data: bytes) -> bytes:
+    """Remove DLE stuffing: 0x10 0x10 → 0x10."""
+    out = bytearray()
+    i = 0
+    while i < len(data):
+        b = data[i]
+        if b == DLE and i + 1 < len(data) and data[i + 1] == DLE:
+            out.append(DLE)
+            i += 2
+        else:
+            out.append(b)
+            i += 1
+    return bytes(out)
+
+
+# ── Checksum ─────────────────────────────────────────────────────────────────
+
+def checksum(payload: bytes) -> int:
+    """SUM8: sum of all de-stuffed payload bytes, mod 256."""
+    return sum(payload) & 0xFF
+
+
+# ── BW→S3 frame builder ───────────────────────────────────────────────────────
+
+def build_bw_frame(sub: int, offset: int = 0) -> bytes:
+    """
+    Build a BW→S3 read-command frame.
+
+    The payload is always 16 de-stuffed bytes:
+      [BW_CMD, 0x00, sub, 0x00, 0x00, offset, 0x00 × 10]
+
+    Confirmed from BW capture analysis: payload[3] and payload[4] are always
+    0x00 across all observed read commands.  The two-step offset lives at
+    payload[5]: 0x00 for the length-probe step, DATA_LEN for the data-fetch step.
+
+    Wire output: [ACK] [STX] dle_stuff(payload + checksum) [ETX]
+
+    Args:
+        sub:    SUB command byte (e.g. 0x01 = FULL_CONFIG_READ)
+        offset: Value placed at payload[5].
+                Pass 0 for the probe step; pass DATA_LENGTHS[sub] for the data step.
+
+    Returns:
+        Complete frame bytes ready to write to the serial port / socket.
+    """
+    payload = bytes([BW_CMD, 0x00, sub, 0x00, 0x00, offset]) + bytes(_BW_PAYLOAD_SIZE - 6)
+    chk = checksum(payload)
+    wire = bytes([ACK, STX]) + dle_stuff(payload + bytes([chk])) + bytes([ETX])
+    return wire
+
+
+# ── Pre-built POLL frames ─────────────────────────────────────────────────────
+#
+# POLL (SUB 0x5B) uses the same two-step pattern as all other reads — the
+# hardcoded length 0x30 lives at payload[5], exactly as in build_bw_frame().
+
+POLL_PROBE = build_bw_frame(0x5B, 0x00)   # length-probe POLL  (offset = 0)
+POLL_DATA  = build_bw_frame(0x5B, 0x30)   # data-request POLL  (offset = 0x30)
+
+
+# ── S3 response dataclass ─────────────────────────────────────────────────────
+
+@dataclass
+class S3Frame:
+    """A fully parsed and de-stuffed S3→BW response frame."""
+    sub: int            # response SUB byte (e.g. 0xA4 = POLL_RESPONSE)
+    page_hi: int        # PAGE_HI from header (= data length on step-2 length response)
+    page_lo: int        # PAGE_LO from header
+    data: bytes         # payload data section (payload[5:], checksum already stripped)
+    checksum_valid: bool
+
+    @property
+    def page_key(self) -> int:
+        """Combined 16-bit page address / length: (page_hi << 8) | page_lo."""
+        return (self.page_hi << 8) | self.page_lo
+
+
+# ── Streaming S3 frame parser ─────────────────────────────────────────────────
+
+class S3FrameParser:
+    """
+    Incremental byte-stream parser for S3→BW response frames.
+
+    Feed incoming bytes with feed().  Complete, valid frames are returned
+    immediately and also accumulated in self.frames.
+
+    State machine:
+        IDLE             — scanning for DLE (0x10)
+        SEEN_DLE         — saw DLE, waiting for STX (0x02) to start a frame
+        IN_FRAME         — collecting de-stuffed payload bytes; bare ETX ends frame
+        IN_FRAME_DLE     — inside frame, saw DLE; DLE continues stuffing;
+                           DLE+ETX is treated as literal data (NOT a frame end),
+                           which lets inner-frame terminators pass through intact
+
+    Wire format confirmed from captures:
+        [DLE=0x10] [STX=0x02] [stuffed payload+chk] [bare ETX=0x03]
+    The ETX is NOT preceded by a DLE on the wire.  DLE+ETX sequences that
+    appear inside the payload are inner-frame terminators and must be
+    treated as literal data.
+
+    ACK (0x41) bytes and arbitrary non-DLE bytes in IDLE state are silently
+    discarded (covers device boot string "Operating System" and keepalive ACKs).
+    """
+
+    _IDLE         = 0
+    _SEEN_DLE     = 1
+    _IN_FRAME     = 2
+    _IN_FRAME_DLE = 3
+
+    def __init__(self) -> None:
+        self._state = self._IDLE
+        self._body  = bytearray()   # accumulates de-stuffed frame bytes
+        self.frames: list[S3Frame] = []
+
+    def reset(self) -> None:
+        self._state = self._IDLE
+        self._body.clear()
+
+    def feed(self, data: bytes) -> list[S3Frame]:
+        """
+        Process a chunk of incoming bytes.
+
+        Returns a list of S3Frame objects completed during this call.
+        All completed frames are also appended to self.frames.
+        """
+        completed: list[S3Frame] = []
+        for b in data:
+            frame = self._step(b)
+            if frame is not None:
+                completed.append(frame)
+                self.frames.append(frame)
+        return completed
+
+    def _step(self, b: int) -> Optional[S3Frame]:
+        """Process one byte. Returns a completed S3Frame or None."""
+
+        if self._state == self._IDLE:
+            if b == DLE:
+                self._state = self._SEEN_DLE
+            # ACK, boot strings, garbage — silently ignored
+
+        elif self._state == self._SEEN_DLE:
+            if b == STX:
+                self._body.clear()
+                self._state = self._IN_FRAME
+            else:
+                # Stray DLE not followed by STX — back to idle
+                self._state = self._IDLE
+
+        elif self._state == self._IN_FRAME:
+            if b == DLE:
+                self._state = self._IN_FRAME_DLE
+            elif b == ETX:
+                # Bare ETX = real frame terminator (confirmed from captures)
+                frame = self._finalise()
+                self._state = self._IDLE
+                return frame
+            else:
+                self._body.append(b)
+
+        elif self._state == self._IN_FRAME_DLE:
+            if b == DLE:
+                # DLE DLE → literal 0x10 in payload
+                self._body.append(DLE)
+                self._state = self._IN_FRAME
+            elif b == ETX:
+                # DLE+ETX inside a frame is an inner-frame terminator, NOT
+                # the outer frame end.  Treat as literal data and continue.
+                self._body.append(DLE)
+                self._body.append(ETX)
+                self._state = self._IN_FRAME
+            else:
+                # Unexpected DLE + byte — treat both as literal data and continue
+                self._body.append(DLE)
+                self._body.append(b)
+                self._state = self._IN_FRAME
+
+        return None
+
+    def _finalise(self) -> Optional[S3Frame]:
+        """
+        Called when DLE+ETX is seen.  Validates checksum and builds S3Frame.
+        Returns None if the frame is too short or structurally invalid.
+        """
+        body = bytes(self._body)
+
+        # Minimum valid frame: 5-byte header + at least 1 checksum byte = 6
+        if len(body) < 6:
+            return None
+
+        raw_payload = body[:-1]   # everything except the trailing checksum byte
+        chk_received = body[-1]
+        chk_computed  = checksum(raw_payload)
+
+        if len(raw_payload) < 5:
+            return None
+
+        # Validate CMD byte — we only accept S3→BW response frames here
+        if raw_payload[0] != S3_CMD:
+            return None
+
+        return S3Frame(
+            sub           = raw_payload[2],
+            page_hi       = raw_payload[3],
+            page_lo       = raw_payload[4],
+            data          = raw_payload[5:],
+            checksum_valid = (chk_received == chk_computed),
+        )

minimateplus/models.py

@@ -0,0 +1,215 @@
+"""
+models.py — Plain-Python data models for the MiniMate Plus protocol library.
+
+All models are intentionally simple dataclasses with no protocol logic.
+They represent *decoded* device data — the client layer translates raw frame
+bytes into these objects, and the SFM API layer serialises them to JSON.
+
+Notes on certainty:
+  Fields marked ✅ are confirmed from captured data.
+  Fields marked 🔶 are strongly inferred but not formally proven.
+  Fields marked ❓ are present in the captured payload but not yet decoded.
+  See docs/instantel_protocol_reference.md for full derivation details.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ── Timestamp ─────────────────────────────────────────────────────────────────
+
+@dataclass
+class Timestamp:
+    """
+    6-byte event timestamp decoded from the MiniMate Plus wire format.
+
+    Wire layout: [flag:1] [year:2 BE] [unknown:1] [month:1] [day:1]
+
+    The year 1995 is the device's factory-default RTC date — it appears
+    whenever the battery has been disconnected.  Treat 1995 as "clock not set".
+    """
+    raw: bytes                  # raw 6-byte sequence for round-tripping
+    flag: int                   # byte 0 — validity/type flag (usually 0x01) 🔶
+    year: int                   # bytes 1–2 big-endian uint16 ✅
+    unknown_byte: int           # byte 3 — likely hours/minutes ❓
+    month: int                  # byte 4 ✅
+    day: int                    # byte 5 ✅
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> "Timestamp":
+        """
+        Decode a 6-byte timestamp sequence.
+
+        Args:
+            data: exactly 6 bytes from the device payload.
+
+        Returns:
+            Decoded Timestamp.
+
+        Raises:
+            ValueError: if data is not exactly 6 bytes.
+        """
+        if len(data) != 6:
+            raise ValueError(f"Timestamp requires exactly 6 bytes, got {len(data)}")
+        flag = data[0]
+        year = struct.unpack_from(">H", data, 1)[0]
+        unknown_byte = data[3]
+        month = data[4]
+        day = data[5]
+        return cls(
+            raw=bytes(data),
+            flag=flag,
+            year=year,
+            unknown_byte=unknown_byte,
+            month=month,
+            day=day,
+        )
+
+    @property
+    def clock_set(self) -> bool:
+        """False when year == 1995 (factory default / battery-lost state)."""
+        return self.year != 1995
+
+    def __str__(self) -> str:
+        if not self.clock_set:
+            return f"CLOCK_NOT_SET ({self.year}-{self.month:02d}-{self.day:02d})"
+        return f"{self.year}-{self.month:02d}-{self.day:02d}"
+
+
+# ── Device identity ───────────────────────────────────────────────────────────
+
+@dataclass
+class DeviceInfo:
+    """
+    Combined device identity information gathered during the startup sequence.
+
+    Populated from three response SUBs:
+    - SUB EA (SERIAL_NUMBER_RESPONSE):  serial, firmware_minor
+    - SUB FE (FULL_CONFIG_RESPONSE):    serial (repeat), firmware_version,
+                                         dsp_version, manufacturer, model
+    - SUB A4 (POLL_RESPONSE):           manufacturer (repeat), model (repeat)
+
+    All string fields are stripped of null padding before storage.
+    """
+
+    # ── From SUB EA (SERIAL_NUMBER_RESPONSE) ─────────────────────────────────
+    serial: str                     # e.g. "BE18189" ✅
+    firmware_minor: int             # 0x11 = 17 for S337.17 ✅
+    serial_trail_0: Optional[int] = None   # unit-specific byte — purpose unknown ❓
+
+    # ── From SUB FE (FULL_CONFIG_RESPONSE) ────────────────────────────────────
+    firmware_version: Optional[str] = None  # e.g. "S337.17" ✅
+    dsp_version: Optional[str] = None       # e.g. "10.72" ✅
+    manufacturer: Optional[str] = None      # e.g. "Instantel" ✅
+    model: Optional[str] = None             # e.g. "MiniMate Plus" ✅
+
+    def __str__(self) -> str:
+        fw = self.firmware_version or f"?.{self.firmware_minor}"
+        mdl = self.model or "MiniMate Plus"
+        return f"{mdl} S/N:{self.serial} FW:{fw}"
+
+
+# ── Channel threshold / scaling ───────────────────────────────────────────────
+
+@dataclass
+class ChannelConfig:
+    """
+    Per-channel threshold and scaling values from SUB E5 / SUB 71.
+
+    Floats are stored in the device in imperial units (in/s for geo channels,
+    psi for MicL).  Unit strings embedded in the payload confirm this.
+
+    Certainty: ✅ CONFIRMED for trigger_level, alarm_level, unit strings.
+    """
+    label: str                  # e.g. "Tran", "Vert", "Long", "MicL" ✅
+    trigger_level: float        # in/s (geo) or psi (MicL) ✅
+    alarm_level: float          # in/s (geo) or psi (MicL) ✅
+    max_range: float            # full-scale calibration constant (e.g. 6.206) 🔶
+    unit_label: str             # e.g. "in./s" or "psi" ✅
+
+
+# ── Peak values for one event ─────────────────────────────────────────────────
+
+@dataclass
+class PeakValues:
+    """
+    Per-channel peak particle velocity / pressure for a single event.
+
+    Extracted from the Full Waveform Record (SUB F3), stored as IEEE 754
+    big-endian floats in the device's native units (in/s / psi).
+    """
+    tran: Optional[float] = None    # Transverse PPV (in/s) ✅
+    vert: Optional[float] = None    # Vertical PPV (in/s) ✅
+    long: Optional[float] = None    # Longitudinal PPV (in/s) ✅
+    micl: Optional[float] = None    # Air overpressure (psi) 🔶 (units uncertain)
+
+
+# ── Project / operator metadata ───────────────────────────────────────────────
+
+@dataclass
+class ProjectInfo:
+    """
+    Operator-supplied project and location strings from the Full Waveform
+    Record (SUB F3) and compliance config block (SUB E5 / SUB 71).
+
+    All fields are optional — they may be blank if the operator did not fill
+    them in through Blastware.
+    """
+    setup_name: Optional[str] = None       # "Standard Recording Setup"
+    project: Optional[str] = None          # project description
+    client: Optional[str] = None           # client name ✅ confirmed offset
+    operator: Optional[str] = None         # operator / user name
+    sensor_location: Optional[str] = None  # sensor location string
+    notes: Optional[str] = None            # extended notes
+
+
+# ── Event ─────────────────────────────────────────────────────────────────────
+
+@dataclass
+class Event:
+    """
+    A single seismic event record downloaded from the device.
+
+    Populated progressively across several request/response pairs:
+    1. SUB 1E (EVENT_HEADER) → index, timestamp, sample_rate
+    2. SUB 0C (FULL_WAVEFORM_RECORD) → peak_values, project_info, record_type
+    3. SUB 5A (BULK_WAVEFORM_STREAM) → raw_samples  (downloaded on demand)
+
+    Fields not yet retrieved are None.
+    """
+    # ── Identity ──────────────────────────────────────────────────────────────
+    index: int                              # 0-based event number on device
+
+    # ── From EVENT_HEADER (SUB 1E) ────────────────────────────────────────────
+    timestamp: Optional[Timestamp] = None   # 6-byte timestamp ✅
+    sample_rate: Optional[int] = None       # samples/sec (e.g. 1024) 🔶
+
+    # ── From FULL_WAVEFORM_RECORD (SUB F3) ───────────────────────────────────
+    peak_values: Optional[PeakValues] = None
+    project_info: Optional[ProjectInfo] = None
+    record_type: Optional[str] = None       # e.g. "Histogram", "Waveform" 🔶
+
+    # ── From BULK_WAVEFORM_STREAM (SUB 5A) ───────────────────────────────────
+    # Raw ADC samples keyed by channel label.  Not fetched unless explicitly
+    # requested (large data transfer — up to several MB per event).
+    raw_samples: Optional[dict] = None      # {"Tran": [...], "Vert": [...], ...}
+
+    def __str__(self) -> str:
+        ts = str(self.timestamp) if self.timestamp else "no timestamp"
+        ppv = ""
+        if self.peak_values:
+            pv = self.peak_values
+            parts = []
+            if pv.tran is not None:
+                parts.append(f"T={pv.tran:.4f}")
+            if pv.vert is not None:
+                parts.append(f"V={pv.vert:.4f}")
+            if pv.long is not None:
+                parts.append(f"L={pv.long:.4f}")
+            if pv.micl is not None:
+                parts.append(f"M={pv.micl:.6f}")
+            ppv = " [" + ", ".join(parts) + " in/s]"
+        return f"Event#{self.index} {ts}{ppv}"

minimateplus/protocol.py

@@ -0,0 +1,317 @@
+"""
+protocol.py — High-level MiniMate Plus request/response protocol.
+
+Implements the request/response patterns documented in
+docs/instantel_protocol_reference.md on top of:
+  - minimateplus.framing  — DLE codec, frame builder, S3 streaming parser
+  - minimateplus.transport — byte I/O (SerialTransport / future TcpTransport)
+
+This module knows nothing about pyserial or TCP — it only calls
+transport.write() and transport.read_until_idle().
+
+Key patterns implemented:
+  - POLL startup handshake (two-step, special payload[5] format)
+  - Generic two-step paged read (probe → get length → fetch data)
+  - Response timeout + checksum validation
+  - Boot-string drain (device sends "Operating System" ASCII before framing)
+
+All public methods raise ProtocolError on timeout, bad checksum, or
+unexpected response SUB.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Optional
+
+from .framing import (
+    S3Frame,
+    S3FrameParser,
+    build_bw_frame,
+    POLL_PROBE,
+    POLL_DATA,
+)
+from .transport import BaseTransport
+
+log = logging.getLogger(__name__)
+
+
+# ── Constants ─────────────────────────────────────────────────────────────────
+
+# Response SUB = 0xFF - Request SUB  (confirmed pattern, no known exceptions
+# among read commands; one write-path exception documented for SUB 1C→6E).
+def _expected_rsp_sub(req_sub: int) -> int:
+    return (0xFF - req_sub) & 0xFF
+
+
+# SUB byte constants (request side) — see protocol reference §5.1
+SUB_POLL             = 0x5B
+SUB_SERIAL_NUMBER    = 0x15
+SUB_FULL_CONFIG      = 0x01
+SUB_EVENT_INDEX      = 0x08
+SUB_CHANNEL_CONFIG   = 0x06
+SUB_TRIGGER_CONFIG   = 0x1C
+SUB_EVENT_HEADER     = 0x1E
+SUB_WAVEFORM_HEADER  = 0x0A
+SUB_WAVEFORM_RECORD  = 0x0C
+SUB_BULK_WAVEFORM    = 0x5A
+SUB_COMPLIANCE       = 0x1A
+SUB_UNKNOWN_2E       = 0x2E
+
+# Hardcoded data lengths for the two-step read protocol.
+#
+# The S3 probe response page_key is always 0x0000 — it does NOT carry the
+# data length back to us.  Instead, each SUB has a fixed known payload size
+# confirmed from BW capture analysis (offset at payload[5] of the data-request
+# frame).
+#
+# Key: request SUB byte.  Value: offset/length byte sent in the data-request.
+# Entries marked 🔶 are inferred from captured frames and may need adjustment.
+DATA_LENGTHS: dict[int, int] = {
+    SUB_POLL:           0x30,   # POLL startup data block ✅
+    SUB_SERIAL_NUMBER:  0x0A,   # 10-byte serial number block ✅
+    SUB_FULL_CONFIG:    0x98,   # 152-byte full config block ✅
+    SUB_EVENT_INDEX:    0x58,   # 88-byte event index ✅
+    SUB_TRIGGER_CONFIG: 0x2C,   # 44-byte trigger config 🔶
+    SUB_UNKNOWN_2E:     0x1A,   # 26 bytes, purpose TBD 🔶
+    0x09:               0xCA,   # 202 bytes, purpose TBD 🔶
+    # SUB_COMPLIANCE (0x1A) uses a multi-step sequence with a 2090-byte total;
+    # NOT handled here — requires specialised read logic.
+}
+
+# Default timeout values (seconds).
+# MiniMate Plus is a slow device — keep these generous.
+DEFAULT_RECV_TIMEOUT = 10.0
+POLL_RECV_TIMEOUT    = 10.0
+
+
+# ── Exception ─────────────────────────────────────────────────────────────────
+
+class ProtocolError(Exception):
+    """Raised when the device violates the expected protocol."""
+
+
+class TimeoutError(ProtocolError):
+    """Raised when no response is received within the allowed time."""
+
+
+class ChecksumError(ProtocolError):
+    """Raised when a received frame has a bad checksum."""
+
+
+class UnexpectedResponse(ProtocolError):
+    """Raised when the response SUB doesn't match what we requested."""
+
+
+# ── MiniMateProtocol ──────────────────────────────────────────────────────────
+
+class MiniMateProtocol:
+    """
+    Protocol state machine for one open connection to a MiniMate Plus device.
+
+    Does not own the transport — transport lifetime is managed by MiniMateClient.
+
+    Typical usage (via MiniMateClient — not directly):
+        proto = MiniMateProtocol(transport)
+        proto.startup()              # POLL handshake, drain boot string
+        data = proto.read(SUB_FULL_CONFIG)
+        sn_data = proto.read(SUB_SERIAL_NUMBER)
+    """
+
+    def __init__(
+        self,
+        transport: BaseTransport,
+        recv_timeout: float = DEFAULT_RECV_TIMEOUT,
+    ) -> None:
+        self._transport = transport
+        self._recv_timeout = recv_timeout
+        self._parser = S3FrameParser()
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def startup(self) -> S3Frame:
+        """
+        Perform the POLL startup handshake and return the POLL data frame.
+
+        Steps (matching §6 Session Startup Sequence):
+          1. Drain any boot-string bytes ("Operating System" ASCII)
+          2. Send POLL_PROBE (SUB 5B, offset=0x00)
+          3. Receive probe ack (page_key is 0x0000; data length 0x30 is hardcoded)
+          4. Send POLL_DATA (SUB 5B, offset=0x30)
+          5. Receive data frame with "Instantel" + "MiniMate Plus" strings
+
+        Returns:
+            The data-phase POLL response S3Frame.
+
+        Raises:
+            ProtocolError: if either POLL step fails.
+        """
+        log.debug("startup: draining boot string")
+        self._drain_boot_string()
+
+        log.debug("startup: POLL probe")
+        self._send(POLL_PROBE)
+        probe_rsp = self._recv_one(
+            expected_sub=_expected_rsp_sub(SUB_POLL),
+            timeout=POLL_RECV_TIMEOUT,
+        )
+        log.debug(
+            "startup: POLL probe response page_key=0x%04X", probe_rsp.page_key
+        )
+
+        log.debug("startup: POLL data request")
+        self._send(POLL_DATA)
+        data_rsp = self._recv_one(
+            expected_sub=_expected_rsp_sub(SUB_POLL),
+            timeout=POLL_RECV_TIMEOUT,
+        )
+        log.debug("startup: POLL data received, %d bytes", len(data_rsp.data))
+        return data_rsp
+
+    def read(self, sub: int) -> bytes:
+        """
+        Execute a two-step paged read and return the data payload bytes.
+
+        Step 1: send probe frame (offset=0x00)      → device sends a short ack
+        Step 2: send data-request (offset=DATA_LEN) → device sends the data block
+
+        The S3 probe response does NOT carry the data length — page_key is always
+        0x0000 in observed frames.  DATA_LENGTHS holds the known fixed lengths
+        derived from BW capture analysis.
+
+        Args:
+            sub: Request SUB byte (e.g. SUB_FULL_CONFIG = 0x01).
+
+        Returns:
+            De-stuffed data payload bytes (payload[5:] of the response frame,
+            with the checksum already stripped by the parser).
+
+        Raises:
+            ProtocolError: on timeout, bad checksum, or wrong response SUB.
+            KeyError: if sub is not in DATA_LENGTHS (caller should add it).
+        """
+        rsp_sub = _expected_rsp_sub(sub)
+
+        # Step 1 — probe (offset = 0)
+        log.debug("read SUB=0x%02X: probe", sub)
+        self._send(build_bw_frame(sub, 0))
+        _probe = self._recv_one(expected_sub=rsp_sub)  # ack; page_key always 0
+
+        # Look up the hardcoded data length for this SUB
+        if sub not in DATA_LENGTHS:
+            raise ProtocolError(
+                f"No known data length for SUB=0x{sub:02X}. "
+                "Add it to DATA_LENGTHS in protocol.py."
+            )
+        length = DATA_LENGTHS[sub]
+        log.debug("read SUB=0x%02X: data request offset=0x%02X", sub, length)
+
+        if length == 0:
+            log.warning("read SUB=0x%02X: DATA_LENGTHS entry is zero", sub)
+            return b""
+
+        # Step 2 — data-request (offset = length)
+        self._send(build_bw_frame(sub, length))
+        data_rsp = self._recv_one(expected_sub=rsp_sub)
+
+        log.debug("read SUB=0x%02X: received %d data bytes", sub, len(data_rsp.data))
+        return data_rsp.data
+
+    def send_keepalive(self) -> None:
+        """
+        Send a single POLL_PROBE keepalive without waiting for a response.
+
+        Blastware sends these every ~80ms during idle.  Useful if you need to
+        hold the session open between real requests.
+        """
+        self._send(POLL_PROBE)
+
+    # ── Internal helpers ──────────────────────────────────────────────────────
+
+    def _send(self, frame: bytes) -> None:
+        """Write a pre-built frame to the transport."""
+        log.debug("TX %d bytes: %s", len(frame), frame.hex())
+        self._transport.write(frame)
+
+    def _recv_one(
+        self,
+        expected_sub: Optional[int] = None,
+        timeout: Optional[float] = None,
+    ) -> S3Frame:
+        """
+        Read bytes from the transport until one complete S3 frame is parsed.
+
+        Feeds bytes through the streaming S3FrameParser.  Keeps reading until
+        a frame arrives or the deadline expires.
+
+        Args:
+            expected_sub: If provided, raises UnexpectedResponse if the
+                          received frame's SUB doesn't match.
+            timeout:      Seconds to wait.  Defaults to self._recv_timeout.
+
+        Returns:
+            The first complete S3Frame received.
+
+        Raises:
+            TimeoutError: if no frame arrives within the timeout.
+            ChecksumError: if the frame has an invalid checksum.
+            UnexpectedResponse: if expected_sub is set and doesn't match.
+        """
+        deadline = time.monotonic() + (timeout or self._recv_timeout)
+        self._parser.reset()
+
+        while time.monotonic() < deadline:
+            chunk = self._transport.read(256)
+            if chunk:
+                log.debug("RX %d bytes: %s", len(chunk), chunk.hex())
+                frames = self._parser.feed(chunk)
+                if frames:
+                    frame = frames[0]
+                    self._validate_frame(frame, expected_sub)
+                    return frame
+            else:
+                time.sleep(0.005)
+
+        raise TimeoutError(
+            f"No S3 frame received within {timeout or self._recv_timeout:.1f}s"
+            + (f" (expected SUB 0x{expected_sub:02X})" if expected_sub is not None else "")
+        )
+
+    @staticmethod
+    def _validate_frame(frame: S3Frame, expected_sub: Optional[int]) -> None:
+        """Validate SUB; log but do not raise on bad checksum.
+
+        S3 response checksums frequently fail SUM8 validation due to inner-frame
+        delimiter bytes being captured as the checksum byte.  The original
+        s3_parser.py deliberately never validates S3 checksums for exactly this
+        reason.  We log a warning and continue.
+        """
+        if not frame.checksum_valid:
+            # S3 checksums frequently fail SUM8 due to inner-frame delimiter bytes
+            # landing in the checksum position.  Treat as informational only.
+            log.debug("S3 frame SUB=0x%02X: checksum mismatch (ignoring)", frame.sub)
+        if expected_sub is not None and frame.sub != expected_sub:
+            raise UnexpectedResponse(
+                f"Expected SUB=0x{expected_sub:02X}, got 0x{frame.sub:02X}"
+            )
+
+    def _drain_boot_string(self, drain_ms: int = 200) -> None:
+        """
+        Read and discard any boot-string bytes ("Operating System") the device
+        may send before entering binary protocol mode.
+
+        We simply read with a short timeout and throw the bytes away.  The
+        S3FrameParser's IDLE state already handles non-frame bytes gracefully,
+        but it's cleaner to drain them explicitly before the first real frame.
+        """
+        deadline = time.monotonic() + (drain_ms / 1000)
+        discarded = 0
+        while time.monotonic() < deadline:
+            chunk = self._transport.read(256)
+            if chunk:
+                discarded += len(chunk)
+            else:
+                time.sleep(0.005)
+        if discarded:
+            log.debug("drain_boot_string: discarded %d bytes", discarded)

minimateplus/transport.py

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

parsers/s3_analyzer.py

@@ -12,6 +12,7 @@ Usage:
 from __future__ import annotations
 
 import argparse
+import struct
 import sys
 import time
 from dataclasses import dataclass
@@ -139,6 +140,15 @@ class Session:
     index: int
     bw_frames: list[AnnotatedFrame]
     s3_frames: list[AnnotatedFrame]
+    # None = infer from SUB 0x74 presence; True/False = explicitly set by splitter
+    complete: Optional[bool] = None
+
+    def is_complete(self) -> bool:
+        """A session is complete if explicitly marked, or if it contains SUB 0x74."""
+        if self.complete is not None:
+            return self.complete
+        return any(af.header is not None and af.header.sub == SESSION_CLOSE_SUB
+                   for af in self.bw_frames)
 
     @property
     def all_frames(self) -> list[AnnotatedFrame]:
@@ -294,6 +304,129 @@ def split_into_sessions(
     return sessions
 
 
+# ──────────────────────────────────────────────────────────────────────────────
+# Mark-based session splitting (using structured .bin log)
+# ──────────────────────────────────────────────────────────────────────────────
+
+# Structured .bin record types (from s3_bridge.py)
+_REC_BW   = 0x01
+_REC_S3   = 0x02
+_REC_MARK = 0x03
+_REC_INFO = 0x04
+
+
+@dataclass
+class MarkSplit:
+    """A session boundary derived from a MARK record in the structured .bin log."""
+    label: str
+    bw_byte_offset: int   # byte position in the flat raw_bw stream at mark time
+    s3_byte_offset: int   # byte position in the flat raw_s3 stream at mark time
+
+
+def parse_structured_bin(bin_blob: bytes) -> list[MarkSplit]:
+    """
+    Read a structured s3_session_*.bin file and return one MarkSplit per MARK
+    record, containing the cumulative BW and S3 byte counts at that point.
+
+    Record format: [type:1][ts_us:8 LE][len:4 LE][payload:len]
+    """
+    marks: list[MarkSplit] = []
+    bw_bytes = 0
+    s3_bytes = 0
+    pos = 0
+
+    while pos + 13 <= len(bin_blob):
+        rec_type = bin_blob[pos]
+        # ts_us: 8 bytes LE (we don't need it, just skip)
+        length = struct.unpack_from("<I", bin_blob, pos + 9)[0]
+        payload_start = pos + 13
+        payload_end   = payload_start + length
+
+        if payload_end > len(bin_blob):
+            break  # truncated record
+
+        payload = bin_blob[payload_start:payload_end]
+
+        if rec_type == _REC_BW:
+            bw_bytes += length
+        elif rec_type == _REC_S3:
+            s3_bytes += length
+        elif rec_type == _REC_MARK:
+            label = payload.decode("utf-8", errors="replace")
+            # Skip auto-generated bridge lifecycle marks — only keep user marks
+            if label.startswith("SESSION START") or label.startswith("SESSION END"):
+                pass
+            else:
+                marks.append(MarkSplit(label=label,
+                                       bw_byte_offset=bw_bytes,
+                                       s3_byte_offset=s3_bytes))
+
+        pos = payload_end
+
+    return marks
+
+
+def split_sessions_at_marks(
+    bw_blob:  bytes,
+    s3_blob:  bytes,
+    marks:    list[MarkSplit],
+) -> list[Session]:
+    """
+    Split raw byte streams into sessions using mark byte offsets, then apply
+    the standard 0x74-based sub-splitting within each mark segment.
+
+    Each mark creates a new session boundary: session 0 = bytes before mark 0,
+    session 1 = bytes between mark 0 and mark 1, etc.
+    """
+    if not marks:
+        # No marks — fall back to standard session detection
+        bw_frames = annotate_frames(parse_bw(bw_blob, trailer_len=0,
+                                             validate_checksum=True), "BW")
+        s3_frames = annotate_frames(parse_s3(s3_blob, trailer_len=0), "S3")
+        return split_into_sessions(bw_frames, s3_frames)
+
+    # Build slice boundaries: [0 .. mark0.bw, mark0.bw .. mark1.bw, ...]
+    bw_cuts = [m.bw_byte_offset for m in marks] + [len(bw_blob)]
+    s3_cuts = [m.s3_byte_offset for m in marks] + [len(s3_blob)]
+
+    all_sessions: list[Session] = []
+    session_offset = 0
+    bw_prev = s3_prev = 0
+
+    n_segments = len(bw_cuts)
+    for seg_i, (bw_end, s3_end) in enumerate(zip(bw_cuts, s3_cuts)):
+        bw_chunk = bw_blob[bw_prev:bw_end]
+        s3_chunk = s3_blob[s3_prev:s3_end]
+
+        bw_frames = annotate_frames(parse_bw(bw_chunk, trailer_len=0,
+                                             validate_checksum=True), "BW")
+        s3_frames = annotate_frames(parse_s3(s3_chunk, trailer_len=0), "S3")
+
+        seg_sessions = split_into_sessions(bw_frames, s3_frames)
+
+        # A mark-bounded segment is complete by definition — the user placed the
+        # mark after the read finished.  Only the last segment (trailing, unbounded)
+        # may be genuinely in-progress.
+        is_last_segment = (seg_i == n_segments - 1)
+
+        # Re-index sessions so they are globally unique
+        for sess in seg_sessions:
+            sess.index = session_offset
+            for f in sess.all_frames:
+                f.session_idx = session_offset
+            # Explicitly mark completeness: mark-bounded segments are complete;
+            # the trailing segment falls back to 0x74 inference.
+            if not is_last_segment:
+                sess.complete = True
+            session_offset += 1
+            all_sessions.append(sess)
+
+        bw_prev = bw_end
+        s3_prev = s3_end
+
+    return all_sessions
+
+
 # ──────────────────────────────────────────────────────────────────────────────
 # Diff engine
 # ──────────────────────────────────────────────────────────────────────────────
@@ -341,6 +474,140 @@ def lookup_field_name(sub: int, page_key: int, payload_offset: int) -> Optional[
     return None
 
 
+def _extract_a4_inner_frames(payload: bytes) -> list[tuple[int, int, bytes]]:
+    """
+    Parse the inner sub-frame stream packed inside an A4 (POLL_RESPONSE) payload.
+
+    The payload is a sequence of inner frames, each starting with DLE STX (10 02)
+    and delimited by ACK (41) before the next DLE STX.  The inner frame body
+    (after the 10 02 preamble) has the same 5-byte header layout as outer frames:
+      [0] 00
+      [1] 10
+      [2] SUB
+      [3] OFFSET_HI  (page_key high byte)
+      [4] OFFSET_LO  (page_key low byte)
+      [5+] data
+
+    Returns a list of (sub, page_key, data_bytes) — one entry per inner frame,
+    keeping ALL occurrences (not deduped), so the caller can decide how to match.
+    """
+    DLE, STX, ACK = 0x10, 0x02, 0x41
+    results: list[tuple[int, int, bytes]] = []
+
+    # Collect start positions of each inner frame (offset of the DLE STX)
+    starts: list[int] = []
+    i = 0
+    # First frame may begin at offset 0 with DLE STX directly
+    if len(payload) >= 2 and payload[0] == DLE and payload[1] == STX:
+        starts.append(0)
+        i = 2
+    while i < len(payload) - 2:
+        if payload[i] == ACK and payload[i + 1] == DLE and payload[i + 2] == STX:
+            starts.append(i + 1)  # point at the DLE
+            i += 3
+        else:
+            i += 1
+
+    for k, s in enumerate(starts):
+        # Body starts after DLE STX (2 bytes)
+        body_start = s + 2
+        body_end = starts[k + 1] - 1 if k + 1 < len(starts) else len(payload)
+        body = payload[body_start:body_end]
+        if len(body) < 5:
+            continue
+        # body[0]=0x00, body[1]=0x10, body[2]=SUB, body[3]=OFFSET_HI, body[4]=OFFSET_LO
+        sub = body[2]
+        page_key = (body[3] << 8) | body[4]
+        data = body[5:]
+        results.append((sub, page_key, data))
+
+    return results
+
+
+def _diff_a4_payloads(payload_a: bytes, payload_b: bytes) -> list[ByteDiff]:
+    """
+    Diff two A4 container payloads at the inner sub-frame level.
+
+    Inner frames are matched by (sub, page_key).  For each pair of matching
+    inner frames whose data differs, the changed bytes are reported with
+    payload_offset encoded as:  (inner_frame_index << 16) | byte_offset_in_data.
+
+    Inner frames present in one payload but not the other are reported as a
+    single synthetic ByteDiff entry with before/after = -1 / -2 respectively,
+    and field_name describing the missing inner SUB.
+
+    The high-16 / low-16 split in payload_offset lets the GUI render these
+    differently if desired, but they degrade gracefully in the existing renderer.
+    """
+    frames_a = _extract_a4_inner_frames(payload_a)
+    frames_b = _extract_a4_inner_frames(payload_b)
+
+    # Build multimap: (sub, page_key) → list of data blobs, preserving order
+    def index(frames):
+        idx: dict[tuple[int, int], list[bytes]] = {}
+        for sub, pk, data in frames:
+            idx.setdefault((sub, pk), []).append(data)
+        return idx
+
+    idx_a = index(frames_a)
+    idx_b = index(frames_b)
+
+    all_keys = sorted(set(idx_a) | set(idx_b))
+    diffs: list[ByteDiff] = []
+
+    for sub, pk in all_keys:
+        list_a = idx_a.get((sub, pk), [])
+        list_b = idx_b.get((sub, pk), [])
+
+        # Pair up by position; extras are treated as added/removed
+        n = max(len(list_a), len(list_b))
+        for pos in range(n):
+            da = list_a[pos] if pos < len(list_a) else None
+            db = list_b[pos] if pos < len(list_b) else None
+
+            if da is None:
+                # Inner frame added in B
+                entry = SUB_TABLE.get(sub)
+                name = entry[0] if entry else f"UNKNOWN_{sub:02X}"
+                diffs.append(ByteDiff(
+                    payload_offset=(sub << 16) | (pk & 0xFFFF),
+                    before=-1,
+                    after=-2,
+                    field_name=f"[A4 inner] SUB {sub:02X} ({name}) pk={pk:04X} added",
+                ))
+                continue
+            if db is None:
+                entry = SUB_TABLE.get(sub)
+                name = entry[0] if entry else f"UNKNOWN_{sub:02X}"
+                diffs.append(ByteDiff(
+                    payload_offset=(sub << 16) | (pk & 0xFFFF),
+                    before=-2,
+                    after=-1,
+                    field_name=f"[A4 inner] SUB {sub:02X} ({name}) pk={pk:04X} removed",
+                ))
+                continue
+
+            # Both present — byte diff the data sections
+            da_m = _mask_noisy(sub, da)
+            db_m = _mask_noisy(sub, db)
+            if da_m == db_m:
+                continue
+            max_len = max(len(da_m), len(db_m))
+            for off in range(max_len):
+                ba = da_m[off] if off < len(da_m) else None
+                bb = db_m[off] if off < len(db_m) else None
+                if ba != bb:
+                    field = lookup_field_name(sub, pk, off + HEADER_LEN)
+                    diffs.append(ByteDiff(
+                        payload_offset=(sub << 16) | (off & 0xFFFF),
+                        before=ba if ba is not None else -1,
+                        after=bb if bb is not None else -1,
+                        field_name=field or f"[A4:{sub:02X} pk={pk:04X}] off={off}",
+                    ))
+
+    return diffs
+
+
 def diff_sessions(sess_a: Session, sess_b: Session) -> list[FrameDiff]:
     """
     Compare two sessions frame-by-frame, matched by (sub, page_key).
@@ -370,6 +637,16 @@ def diff_sessions(sess_a: Session, sess_b: Session) -> list[FrameDiff]:
         af_a = idx_a[key]
         af_b = idx_b[key]
 
+        # A4 is a container frame — diff at the inner sub-frame level to avoid
+        # phase-shift noise when the number of embedded records differs.
+        if sub == 0xA4:
+            diffs = _diff_a4_payloads(af_a.frame.payload, af_b.frame.payload)
+            if diffs:
+                entry = SUB_TABLE.get(sub)
+                sub_name = entry[0] if entry else f"UNKNOWN_{sub:02X}"
+                results.append(FrameDiff(sub=sub, page_key=page_key, sub_name=sub_name, diffs=diffs))
+            continue
+
         data_a = _mask_noisy(sub, _get_data_section(af_a))
         data_b = _mask_noisy(sub, _get_data_section(af_b))
 
@@ -425,11 +702,7 @@ def render_session_report(
     n_bw = len(session.bw_frames)
     n_s3 = len(session.s3_frames)
     total = n_bw + n_s3
-    is_complete = any(
+    status = "" if session.is_complete() else "  [IN PROGRESS]"
-        af.header is not None and af.header.sub == SESSION_CLOSE_SUB
-        for af in session.bw_frames
-    )
-    status = "" if is_complete else "  [IN PROGRESS]"
 
     lines.append(f"{'='*72}")
     lines.append(f"SESSION {session.index}{status}")
@@ -589,11 +862,7 @@ def render_claude_export(
     lines += ["## Capture Summary", ""]
     lines.append(f"Sessions found: {len(sessions)}")
     for sess in sessions:
-        is_complete = any(
+        status = "complete" if sess.is_complete() else "partial/in-progress"
-            af.header is not None and af.header.sub == SESSION_CLOSE_SUB
-            for af in sess.bw_frames
-        )
-        status = "complete" if is_complete else "partial/in-progress"
         n_bw, n_s3 = len(sess.bw_frames), len(sess.s3_frames)
         changed = len(diffs[sess.index] or []) if sess.index < len(diffs) else 0
         changed_str = f"  ({changed} SUBs changed vs prev)" if sess.index > 0 else "  (baseline)"
@@ -861,14 +1130,7 @@ def live_loop(
 
                     # Check for session close
                     all_sessions = split_into_sessions(bw_annotated, s3_annotated)
-                    # A complete session has the closing 0x74
+                    complete_sessions = [s for s in all_sessions if s.is_complete()]
-                    complete_sessions = [
-                        s for s in all_sessions
-                        if any(
-                            af.header is not None and af.header.sub == SESSION_CLOSE_SUB
-                            for af in s.bw_frames
-                        )
-                    ]
 
                     # Emit reports for newly completed sessions
                     for sess in complete_sessions[len(sessions):]:
@@ -899,13 +1161,7 @@ def live_loop(
             s3_annotated = annotate_frames(s3_frames_raw, "S3")
             bw_annotated = annotate_frames(bw_frames_raw, "BW")
             all_sessions = split_into_sessions(bw_annotated, s3_annotated)
-            incomplete = [
+            incomplete = [s for s in all_sessions if not s.is_complete()]
-                s for s in all_sessions
-                if not any(
-                    af.header is not None and af.header.sub == SESSION_CLOSE_SUB
-                    for af in s.bw_frames
-                )
-            ]
             for sess in incomplete:
                 report = render_session_report(sess, diffs=None, prev_session_index=None)
                 out_path = write_report(sess, report, outdir)

parsers/s3_parser.py

@@ -109,6 +109,28 @@ def _try_validate_sum8(body: bytes) -> Optional[Tuple[bytes, bytes, str]]:
     return None
 
 
+def _try_validate_sum8_large(body: bytes) -> Optional[Tuple[bytes, bytes, str]]:
+    """
+    Large BW->S3 write frame checksum (SUBs 68, 69, 71, 82, 1A with data).
+
+    Formula: (sum(b for b in payload[2:-1] if b != 0x10) + 0x10) & 0xFF
+    - Starts from byte [2], skipping CMD (0x10) and DLE (0x10) at [0][1]
+    - Skips all 0x10 bytes in the covered range
+    - Adds 0x10 as a constant offset
+    - body[-1] is the checksum byte
+
+    Confirmed across 20 frames from two independent captures (2026-03-12).
+    """
+    if len(body) < 3:
+        return None
+    payload = body[:-1]
+    chk = body[-1]
+    calc = (sum(b for b in payload[2:] if b != 0x10) + 0x10) & 0xFF
+    if calc == chk:
+        return payload, bytes([chk]), "SUM8_LARGE"
+    return None
+
+
 def _try_validate_crc16(body: bytes) -> Optional[Tuple[bytes, bytes, str]]:
     """
     body = payload + crc16(2 bytes)
@@ -137,11 +159,16 @@ def validate_bw_body_auto(body: bytes) -> Optional[Tuple[bytes, bytes, str]]:
     Try to interpret the tail of body as a checksum in several ways.
     Return (payload, checksum_bytes, checksum_type) if any match; else None.
     """
-    # Prefer SUM8 first (it fits small frames and is cheap)
+    # Prefer plain SUM8 first (small frames: POLL, read commands)
     hit = _try_validate_sum8(body)
     if hit:
         return hit
 
+    # Large BW->S3 write frames (SUBs 68, 69, 71, 82, 1A with data)
+    hit = _try_validate_sum8_large(body)
+    if hit:
+        return hit
+
     # Then CRC16 variants
     hit = _try_validate_crc16(body)
     if hit:
@@ -321,12 +348,7 @@ def parse_bw(blob: bytes, trailer_len: int, validate_checksum: bool) -> List[Fra
             i += 1
             continue
 
-        # AFTER_DLE
+        # AFTER_DLE: DLE XX => literal XX for any XX (full DLE stuffing)
-        if b == DLE:
-            body.append(DLE)  # 10 10 => literal 10
-        else:
-            # Robust recovery: treat as literal DLE + byte
-            body.append(DLE)
         body.append(b)
         state = IN_FRAME
         i += 1

sfm/server.py

@@ -0,0 +1,320 @@
+"""
+sfm/server.py — Seismograph Field Module REST API
+
+Wraps the minimateplus library in a small FastAPI service.
+Terra-view proxies /api/sfm/* to this service (same pattern as SLMM at :8100).
+
+Default port: 8200
+
+Endpoints
+---------
+GET  /health              Service heartbeat — no device I/O
+GET  /device/info         POLL + serial number + full config read
+GET  /device/events       Download all stored events (headers + peak values)
+POST /device/connect      Explicit connect/identify (same as /device/info)
+GET  /device/event/{idx}  Single event by index (header + waveform record)
+
+Transport query params (supply one set):
+  Serial (direct RS-232 cable):
+    port  — serial port name (e.g. COM5, /dev/ttyUSB0)
+    baud  — baud rate (default 38400)
+
+  TCP (modem / ACH Auto Call Home):
+    host      — IP address or hostname of the modem or ACH relay
+    tcp_port  — TCP port number (default 12345, Blastware default)
+
+Each call opens the connection, does its work, then closes it.
+(Stateless / reconnect-per-call, matching Blastware's observed behaviour.)
+
+Run with:
+    python -m uvicorn sfm.server:app --host 0.0.0.0 --port 8200 --reload
+or:
+    python sfm/server.py
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Optional
+
+# FastAPI / Pydantic
+try:
+    from fastapi import FastAPI, HTTPException, Query
+    from fastapi.responses import JSONResponse
+    import uvicorn
+except ImportError:
+    print(
+        "fastapi and uvicorn are required for the SFM server.\n"
+        "Install them with:  pip install fastapi uvicorn",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+from minimateplus import MiniMateClient
+from minimateplus.protocol import ProtocolError
+from minimateplus.models import DeviceInfo, Event, PeakValues, ProjectInfo, Timestamp
+from minimateplus.transport import TcpTransport, DEFAULT_TCP_PORT
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(levelname)-7s  %(name)s  %(message)s",
+    datefmt="%H:%M:%S",
+)
+log = logging.getLogger("sfm.server")
+
+# ── FastAPI app ────────────────────────────────────────────────────────────────
+
+app = FastAPI(
+    title="Seismograph Field Module (SFM)",
+    description=(
+        "REST API for Instantel MiniMate Plus seismographs.\n"
+        "Implements the minimateplus RS-232 protocol library.\n"
+        "Proxied by terra-view at /api/sfm/*."
+    ),
+    version="0.1.0",
+)
+
+
+# ── Serialisers ────────────────────────────────────────────────────────────────
+# Plain dict helpers — avoids a Pydantic dependency in the library layer.
+
+def _serialise_timestamp(ts: Optional[Timestamp]) -> Optional[dict]:
+    if ts is None:
+        return None
+    return {
+        "year": ts.year,
+        "month": ts.month,
+        "day": ts.day,
+        "clock_set": ts.clock_set,
+        "display": str(ts),
+    }
+
+
+def _serialise_peak_values(pv: Optional[PeakValues]) -> Optional[dict]:
+    if pv is None:
+        return None
+    return {
+        "tran_in_s": pv.tran,
+        "vert_in_s": pv.vert,
+        "long_in_s": pv.long,
+        "micl_psi":  pv.micl,
+    }
+
+
+def _serialise_project_info(pi: Optional[ProjectInfo]) -> Optional[dict]:
+    if pi is None:
+        return None
+    return {
+        "setup_name":      pi.setup_name,
+        "project":         pi.project,
+        "client":          pi.client,
+        "operator":        pi.operator,
+        "sensor_location": pi.sensor_location,
+        "notes":           pi.notes,
+    }
+
+
+def _serialise_device_info(info: DeviceInfo) -> dict:
+    return {
+        "serial":           info.serial,
+        "firmware_version": info.firmware_version,
+        "firmware_minor":   info.firmware_minor,
+        "dsp_version":      info.dsp_version,
+        "manufacturer":     info.manufacturer,
+        "model":            info.model,
+    }
+
+
+def _serialise_event(ev: Event) -> dict:
+    return {
+        "index":        ev.index,
+        "timestamp":    _serialise_timestamp(ev.timestamp),
+        "sample_rate":  ev.sample_rate,
+        "record_type":  ev.record_type,
+        "peak_values":  _serialise_peak_values(ev.peak_values),
+        "project_info": _serialise_project_info(ev.project_info),
+    }
+
+
+# ── Transport factory ─────────────────────────────────────────────────────────
+
+def _build_client(
+    port: Optional[str],
+    baud: int,
+    host: Optional[str],
+    tcp_port: int,
+) -> MiniMateClient:
+    """
+    Return a MiniMateClient configured for either serial or TCP transport.
+
+    TCP takes priority if *host* is supplied; otherwise *port* (serial) is used.
+    Raises HTTPException(422) if neither is provided.
+    """
+    if host:
+        # TCP / modem / ACH path
+        transport = TcpTransport(host, port=tcp_port)
+        log.debug("TCP transport: %s:%d", host, tcp_port)
+        return MiniMateClient(transport=transport)
+    elif port:
+        # Direct serial path
+        log.debug("Serial transport: %s baud=%d", port, baud)
+        return MiniMateClient(port, baud)
+    else:
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                "Specify either 'port' (serial, e.g. ?port=COM5) "
+                "or 'host' (TCP, e.g. ?host=192.168.1.50&tcp_port=12345)"
+            ),
+        )
+
+
+# ── Endpoints ──────────────────────────────────────────────────────────────────
+
+@app.get("/health")
+def health() -> dict:
+    """Service heartbeat.  No device I/O."""
+    return {"status": "ok", "service": "sfm", "version": "0.1.0"}
+
+
+@app.get("/device/info")
+def device_info(
+    port:     Optional[str] = Query(None,          description="Serial port (e.g. COM5, /dev/ttyUSB0)"),
+    baud:     int           = Query(38400,          description="Serial baud rate (default 38400)"),
+    host:     Optional[str] = Query(None,          description="TCP host — modem IP or ACH relay (e.g. 203.0.113.5)"),
+    tcp_port: int           = Query(DEFAULT_TCP_PORT, description=f"TCP port (default {DEFAULT_TCP_PORT})"),
+) -> dict:
+    """
+    Connect to the device, perform the POLL startup handshake, and return
+    identity information (serial number, firmware version, model).
+
+    Supply either *port* (serial) or *host* (TCP/modem).
+    Equivalent to POST /device/connect — provided as GET for convenience.
+    """
+    log.info("GET /device/info  port=%s host=%s tcp_port=%d", port, host, tcp_port)
+
+    try:
+        with _build_client(port, baud, host, tcp_port) as client:
+            info = client.connect()
+    except HTTPException:
+        raise
+    except ProtocolError as exc:
+        raise HTTPException(status_code=502, detail=f"Protocol error: {exc}") from exc
+    except OSError as exc:
+        raise HTTPException(status_code=502, detail=f"Connection error: {exc}") from exc
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=f"Device error: {exc}") from exc
+
+    return _serialise_device_info(info)
+
+
+@app.post("/device/connect")
+def device_connect(
+    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})"),
+) -> dict:
+    """
+    Connect to the device and return identity.  POST variant for terra-view
+    compatibility with the SLMM proxy pattern.
+    """
+    return device_info(port=port, baud=baud, host=host, tcp_port=tcp_port)
+
+
+@app.get("/device/events")
+def device_events(
+    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})"),
+) -> dict:
+    """
+    Connect to the device, read the event index, and download all stored
+    events (event headers + full waveform records with peak values).
+
+    Supply either *port* (serial) or *host* (TCP/modem).
+
+    This does NOT download raw ADC waveform samples — those are large and
+    fetched separately via GET /device/event/{idx}/waveform (future endpoint).
+    """
+    log.info("GET /device/events  port=%s host=%s", port, host)
+
+    try:
+        with _build_client(port, baud, host, tcp_port) as client:
+            info   = client.connect()
+            events = client.get_events()
+    except HTTPException:
+        raise
+    except ProtocolError as exc:
+        raise HTTPException(status_code=502, detail=f"Protocol error: {exc}") from exc
+    except OSError as exc:
+        raise HTTPException(status_code=502, detail=f"Connection error: {exc}") from exc
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=f"Device error: {exc}") from exc
+
+    return {
+        "device":      _serialise_device_info(info),
+        "event_count": len(events),
+        "events":      [_serialise_event(ev) for ev in events],
+    }
+
+
+@app.get("/device/event/{index}")
+def device_event(
+    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})"),
+) -> dict:
+    """
+    Download a single event by index (0-based).
+
+    Supply either *port* (serial) or *host* (TCP/modem).
+    Performs: POLL startup → event index → event header → waveform record.
+    """
+    log.info("GET /device/event/%d  port=%s host=%s", index, port, host)
+
+    try:
+        with _build_client(port, baud, host, tcp_port) as client:
+            client.connect()
+            events = client.get_events()
+    except HTTPException:
+        raise
+    except ProtocolError as exc:
+        raise HTTPException(status_code=502, detail=f"Protocol error: {exc}") from exc
+    except OSError as exc:
+        raise HTTPException(status_code=502, detail=f"Connection error: {exc}") from exc
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=f"Device error: {exc}") from exc
+
+    matching = [ev for ev in events if ev.index == index]
+    if not matching:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Event index {index} not found on device",
+        )
+
+    return _serialise_event(matching[0])
+
+
+# ── Entry point ────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import argparse
+
+    ap = argparse.ArgumentParser(description="SFM — Seismograph Field Module API server")
+    ap.add_argument("--host", default="0.0.0.0", help="Bind address (default: 0.0.0.0)")
+    ap.add_argument("--port", type=int, default=8200, help="Port (default: 8200)")
+    ap.add_argument("--reload", action="store_true", help="Enable auto-reload (dev mode)")
+    args = ap.parse_args()
+
+    log.info("Starting SFM server on %s:%d", args.host, args.port)
+    uvicorn.run(
+        "sfm.server:app",
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+    )