From 27b0b25f159d50a4ab000e8ac84c4689c85c06ef Mon Sep 17 00:00:00 2001 From: serversdown Date: Sat, 26 Sep 2026 00:09:55 -0400 Subject: [PATCH] docs(claude): refresh "Where things stand" -- Series-4 live protocol and tooling The orientation block was dated 2026-08-28 and predated every finding from the Series-4 live-protocol work, which is exactly the content a fresh session needs and cannot discover on its own. Adds, at the top where it will actually be read: * The Series-4 live wire protocol is mapped end to end, with the three framing differences that break a Series III parser (no leading DLE, 0xC5/0x03 flags, uint16 length at payload[8:10]) and the note that the inbound call-home session is the only protocol unknown left. * That NO command has ever been originated against a unit by this project -- every write was performed by THOR while we recorded. Worth stating plainly so the next session does not casually break it. * That micromate/ is still codec-only with no live client, and that minimateplus.transport is protocol-agnostic and reusable when one is built. * The bench tooling, including why mm_frame_parse.py has to exist at all: S3FrameParser scans for DLE+STX and therefore cannot see Micromate responses. * The FTDI/CDC-ACM-only USB host constraint and the Sabrent/Benfei cable trap, since a PL2303 cable leaves a unit with no working modem port and the cables are indistinguishable by eye. Corrects a stale operational claim: the v0.30.0 Series-4 backfill HAS now been run on prod, so the ~3.3%-low geophone values are fixed and the job does not need repeating. Also generalises the "update the protocol reference" instruction from the single Series III document to a table of all three, and adds bridges/ plus the two newer docs to the project layout. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Ru8Lg9HkkYvX9VWWo65SmL --- CLAUDE.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 52 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a8faa16..cc80b6f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,10 +10,38 @@ pair — lives in `../terra-view/docs/tmi-stack.md`, which is also loaded as --- -## Where things stand (updated 2026-08-28) +## Where things stand (updated 2026-09-26) Read this first when picking the project back up. +- **The Series-4 LIVE wire protocol is reverse-engineered end to end + (2026-09-25).** `docs/micromate_protocol_reference.md` is the Series-4 + Rosetta Stone, sibling to `instantel_protocol_reference.md`. **A Micromate + answers Series III command frames** — three framing differences: responses + have **no leading `DLE`** (a bare `STX`), `payload[1]` is `0xC5` (Blastware + firmware) or `0x03` (Thor firmware) rather than `0x10`, and the data length + is a **uint16 BE at `payload[8:10]`** (as a byte it under-reads `SUB 0x1A` + by 47x). Read path, event chain, setups, scheduler, monitoring control and + per-event delete are all mapped; **the inbound call-home session is the only + protocol unknown left.** + ⚠ **No command has ever been originated against a unit by this project.** + Every write was performed by THOR while we recorded. That line is worth + keeping. + ⚠ `micromate/` still has **no live client** — it is codec-only. The + `minimateplus/` stack (transport/framing/protocol/client) has no Series-4 + counterpart yet. `minimateplus.transport` is protocol-agnostic and reusable. +- **Bench tooling for device diagnosis (2026-09-25).** `bridges/mm_probe.py` + distinguishes the four faults THOR reports identically as "disconnected" + (refused / connect timeout / **connected but no reply** / replied) and names + what to try next. `bridges/mm_link.py` is a stand-in for a cellular modem + with a decoded log and fault injection. `scratch/mm_frame_parse.py` exists + because **`S3FrameParser` cannot see Micromate responses at all** — it scans + for `DLE+STX`, which never appears in Series-4 traffic. +- **A Micromate's USB-A host port drives FTDI and CDC-ACM only** — no Prolific, + in either firmware line. TMI buys both Sabrent (FTDI) and Benfei (PL2303) + cables and they are indistinguishable by eye. A PL2303 cable leaves a unit + with **no working modem port at all**; identify by `lsusb` VID, `0403` vs + `067b`. This accounted for a unit that could not be deployed. - **Series-3 decode is verified per-sample at scale (v0.27.0).** The full DL2 archive decodes **14,338 / 14,338** paired files exactly against their preserved Blastware ASCII exports — 1,249 waveform + 13,089 histogram, 45 @@ -92,6 +120,9 @@ Read this first when picking the project back up. **v0.27.0 does NOT owe prod a backfill** — verified: the partial-final-block fix changes 0 of the 10,215 histograms in the prod store (the 4 recovered files are archive-only and were never ingested). + ✅ **The v0.30.0 Series-4 backfill HAS been run on prod (2026-09-25).** Every + stored Series-4 geophone value was ~3.3% low until then; that is corrected and + the job does not need repeating. - **The "offset" hardware fault has its own journal** -- `docs/offset_investigation.md`. **5 of 45 units (11%)**, and the fault is **persistent** — it stays until the geophone is serviced. Detect it with @@ -103,7 +134,18 @@ Read this first when picking the project back up. `SUB 0x0E` (unimplemented), which may carry those very numbers. -When new information about the protocol is discovered, please update the instantel_protocol_reference.md with the findings in addition to this document +When new information about a protocol is discovered, record it in the matching +reference **in addition to** this document: + +| series | document | +|---|---| +| Series III (MiniMate Plus / BlastMate) | `docs/instantel_protocol_reference.md` | +| **Series IV (Micromate / THOR)** | **`docs/micromate_protocol_reference.md`** | +| Thor IDF file format | `docs/idf_protocol_reference.md` | + +Both protocol references carry retractions in place rather than deleting what +turned out to be wrong — that convention has already saved re-deriving the same +mistakes twice, so keep it. --- @@ -276,8 +318,15 @@ minimateplus/ ← Python client library (primary focus) sfm/server.py ← FastAPI REST server exposing device data over HTTP seismo_lab.py ← Tkinter GUI (Bridge + Analyzer + Console tabs) +bridges/ + mm_probe.py ← name the fault behind a dead unit (4 verdicts, read-only) + mm_link.py ← bench stand-in for a cellular modem, with fault injection + ach_mitm.py ← TCP relay for recording a Series-3 ACH session + docs/ - instantel_protocol_reference.md ← reverse-engineered protocol spec ("the Rosetta Stone") + instantel_protocol_reference.md ← Series III protocol spec ("the Rosetta Stone") + micromate_protocol_reference.md ← Series IV protocol spec + THOR's measured behaviour + idf_protocol_reference.md ← Thor IDF file format CHANGELOG.md ← version history ```