diff --git a/docs/micromate_protocol_reference.md b/docs/micromate_protocol_reference.md index ee0eb0f..c9f653a 100644 --- a/docs/micromate_protocol_reference.md +++ b/docs/micromate_protocol_reference.md @@ -15,20 +15,77 @@ with no events stored**. ## The headline -**The Micromate answers Series III command frames.** +**A Micromate running the *Blastware* firmware answers Series III command +frames.** An unmodified Series III `POLL` (`SUB 0x5B`), built by `minimateplus.framing.build_bw_frame` with no changes at all, produced a -complete two-step probe/data cycle from a Micromate. Ten Series III read -commands were then tried and **all ten answered**, every one obeying the -Series III response-SUB rule. +complete two-step probe/data cycle. Ten Series III read commands were then +tried and **all ten answered**, every one obeying the Series III response-SUB +rule. -This is not a new protocol. It is close enough to Series III that large parts -of `minimateplus/protocol.py` may apply more or less directly, and the work -ahead is mapping *divergence* rather than mapping from scratch. +⚠ **That qualifier is load-bearing, and it was discovered after the fact.** +Instantel ships the Micromate in two firmware lines: + +| firmware | Instantel's own description | +|---|---| +| `11.0CB` | "Utilize with **Blastware**" | +| `11.0BD` | "Utilize with **THOR, Vision, Vision II**" | + +The bench unit reports **`11.0CB`** — the Blastware build. So the clean +Series III behaviour above is very likely *because the unit is in Blastware +mode*, not because the Micromate natively speaks Series III. **Nothing here +should be assumed to hold on a `11.0BD` unit until tested.** + +This reframes the project. The question is no longer only "what is the +Series IV protocol" but **"which firmware line do we target, and does one of +them let the existing Series III stack drive the whole fleet?"** --- +## Firmware — the variable nobody knew was a variable + +This explains a production problem TMI has lived with: two ACH servers, two +machines, and units that will not cross over. It is not a misconfiguration. +**Instantel ships different firmware for different host software**, and the +wire protocol differs with it. + +Versions observed so far: + +| where | version | notes | +|---|---|---| +| bench unit UM12947, today | **`11.0CB`** | Blastware line — answers Series III | +| corpus, 932 event files | `11.0AK` | produced Thor-collected `.IDFW`/`.IDFH` | +| corpus, 83 event files | `10.90GC` | older; UM12947's own files from Sept 2025 | + +Note UM12947 produced `10.90GC` files in production last year and reports +`11.0CB` on the bench now — so **it has been reflashed at some point**, and +firmware is not stable per-unit over time. Any fleet-wide claim needs a +per-unit firmware audit first. + +The version is readable over the wire from `SUB 0x01` as two separate ASCII +runs — `"0CB"` then `"11"` — with no single concatenated string. + +### The strategic fork + +- **Option A — standardise the fleet on the Blastware line.** Every unit, + MiniMate and Micromate alike, then speaks Series III, and the existing + `minimateplus/` stack drives all of it. One protocol, one call-home + receiver. Dramatically cheaper *if* it holds up. +- **Option B — reverse-engineer the Thor line (`11.0BD`) and support both.** + +Option A is the shortcut, but it is unproven and carries real unknowns, all +of which are cheap to answer on the bench and expensive to discover later: + +1. **What file format does a `11.0CB` unit produce?** If it emits Blastware + binaries rather than `.IDFW`/`.IDFH`, the (now exact) Series III decoder + applies and the IDF codec becomes a legacy path. Not a loss — we have + both — but it changes what the ingest pipeline sees. +2. **Does Thor still work with a `11.0CB` unit?** If not, flashing a + production unit breaks data collection until the replacement path exists. +3. **Are any Micromate-specific capabilities lost** on the Blastware line? +4. **Is the flash reversible in the field**, and what does it cost in downtime? + ## How this was obtained No Thor, no modem, no Windows machine. The Micromate exposes its protocol on @@ -221,9 +278,13 @@ Also unknown: ## Session provenance -Unit **UM12947**, on the bench via USB, **zero events stored** (memory free == -total). Read commands only. Every response in this document was checksum- -validated. +Unit **UM12947**, firmware **`11.0CB`** (Blastware line), on the bench via +USB, **zero events stored** (memory free == total). Read commands only. +Every response in this document was checksum-validated. + +⚠ Firmware is the single biggest caveat on this document. Every finding here +is from one unit on the Blastware build. A `11.0BD` unit has not been +touched. An empty unit is a real limitation: `0x08`, `0x1E`, `0x0A` and `0x06` all have event-dependent payloads that could not be exercised. Recording a couple of