diff --git a/docs/micromate_protocol_reference.md b/docs/micromate_protocol_reference.md index 9f86180..8de4a36 100644 --- a/docs/micromate_protocol_reference.md +++ b/docs/micromate_protocol_reference.md @@ -723,18 +723,47 @@ Read-only, over USB, no Instantel software: Every event arrived at exactly its declared size, every channel came out equal length, and the timestamps are sequential across the recording session. -### ⚠ Gap: no content-based record-type discriminator +### Record type + filename: generate it, don't detect it -`read_idf_file()` decides waveform vs histogram from the **filename suffix** -(`.IDFH` / `.IDFW`) — and there is no filename when downloading over the wire. -The first 64 bytes of a histogram and a waveform are **byte-identical**, so the -header does not obviously carry the type either. +`read_idf_file()` decides waveform vs histogram from the **filename suffix** — +and there is no filename when downloading over the wire. -The protocol does supply one: **`SUB 0x0A` returns length `0x1E` for a -histogram and `0x00` for a waveform** (see the event-chain section). Any -direct-download implementation must carry the type from the chain walk rather -than inferring it from the payload, or find the type field inside the IDF -header. +⚠ Worth correcting a natural assumption: **Series III does not detect this from +content either.** `event_file_io.derive_record_type_from_filename()` reads the +last character of the extension (`M529LKIQ.G10H` → `H` → Histogram). Nothing +in the codebase infers record type from file content, for either family. + +And there is no obvious type field to find. The first 64 bytes of a histogram +and a waveform are byte-identical; they diverge at ~`0x0947` into wholly +different structures rather than differing by a flag. + +**The answer is the Series III pattern — generate the name.** Series III has +`blastware_filename()`, which builds a name from serial + timestamp + type. +Series IV needs the same thing, and its convention is far simpler: + +``` +_.IDF{W,H} e.g. UM12947_20260923163319.IDFW +``` + +versus Series III's `<4-char base-36 stem>`, where +the stem is base-36 of seconds-since-1985 ÷ 1296. + +All three inputs are already available on a direct download: + +| input | source | +|---|---| +| serial | `extract_binary_metadata()` — decoded from the IDF header | +| timestamp | `extract_binary_metadata()` — same | +| **type** | **the chain walk** — `SUB 0x0A` length `0x1E` = histogram, `0x00` = waveform | + +Verified against all five bench events: the generated names match the +convention of real files in the production store byte for byte. A directly +downloaded event can therefore be filed under exactly the name Thor would have +given it, and `/db/import/idf_file` needs no change at all. + +⚠ The type still comes from the *protocol*, not the payload — so a downloader +must carry it out of the chain walk. Losing it means losing the ability to +name the file correctly. ### ⚠ Unresolved: the `0x0C` peak float