From 2f084ed1051c097c3314e77854528231e43acd32 Mon Sep 17 00:00:00 2001 From: Brian Harrison Date: Sun, 26 Apr 2026 01:28:47 -0400 Subject: [PATCH] fix(protocol): update chunk counter formula to use max(key4[2:4], 0x0400) for accurate data streaming --- CLAUDE.md | 33 ++++++++++++----------- docs/instantel_protocol_reference.md | 22 ++++++++++----- minimateplus/protocol.py | 40 +++++++++++++++++----------- 3 files changed, 56 insertions(+), 39 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 6101185..16089fe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -118,28 +118,29 @@ S3→BW (response): Both differences confirmed by reproducing Blastware's exact wire bytes from the 1-2-26 BW TX capture. All 10 frames verified. -### SUB 5A — chunk counter formula (FINAL CORRECTION 2026-04-24) +### SUB 5A — chunk counter formula (FINAL CORRECTION 2026-04-26) -**Chunk counter = `key4[2:4] + (chunk_num - 1) * 0x0400` for ALL chunks.** +**Chunk counter = `max(key4[2:4], 0x0400) + (chunk_num - 1) * 0x0400` for ALL chunks.** where `key4[2:4] = (key4[2] << 8) | key4[3]` is the event's circular-buffer base offset. -The 4-2-26 BW TX capture showed `counter=0x1004` for chunk 1 of event key `01110000`, which -led to `_CHUNK1_COUNTER = 0x1004` being hardcoded as a special case. This was a Blastware -artifact, not a protocol requirement. Empirical test 2026-04-06: with `counter=0x1004` for -chunk 1 the device times out (120 s); with `counter=0x0400` (= `1 * 0x0400`) it responds -immediately and streams all frames correctly. +The `max(..., 0x0400)` guard is critical for events at the start of the circular buffer +(key4[2:4] == 0x0000, e.g. key `01110000`). Without it, chunk 1 gets counter=0x0000, which +is the same address as the probe frame — the device re-returns the STRT record data instead +of waveform payload. With the guard, chunk 1 gets counter=0x0400, which is confirmed correct +from the empirical live-device test 2026-04-06 (`counter=0x0400 → responds immediately and +streams all frames correctly`). -The 4-3-26 capture confirms the pattern for a second event (key `0111245a`): -chunk 1 = `0x245A`, chunk 2 = `0x285A`, chunk 3 = `0x2C5A` (each +0x0400). Blastware's -true formula is `key4[2:4] + (chunk_num - 1) * 0x0400`. +The 4-3-26 capture confirms the pattern for a second event (key `0111245a`, key4[2:4]=0x245a): +chunk 1 = `0x245A`, chunk 2 = `0x285A`, chunk 3 = `0x2C5A` (each +0x0400). +`max(0x245a, 0x0400) = 0x245a` → formula works correctly for non-zero base offset too. -**2026-04-24 CORRECTION — `n * 0x0400` is WRONG for non-first events.** For event key -`01110000`, `key4[2:4] == 0x0000` so the old `chunk_num * 0x0400` formula was accidentally -correct. For keys with `key4[2:4] != 0` (e.g. key `01111884`, offset `0x1884`), the old -formula sends counters pointing into the wrong buffer region — the device returns data from -a completely different stored event and `b"Project:"` never appears in the stream. -Use `key4[2:4] + (chunk_num - 1) * 0x0400` exclusively. +**History:** +- Original: `_CHUNK1_COUNTER = 0x1004` hardcoded (Blastware capture artifact — WRONG). +- 2026-04-06: Corrected to `chunk_num * 0x0400` (worked for key 01110000 only). +- 2026-04-24: Corrected to `key4[2:4] + (chunk_num-1) * 0x0400` (fixed non-zero offsets, + but accidentally broke key 01110000 — counter=0x0000 sends probe address again). +- 2026-04-26: Final formula: `max(key4[2:4], 0x0400) + (chunk_num-1) * 0x0400`. ### SUB 5A — params are 11 bytes for chunk frames, 10 for termination diff --git a/docs/instantel_protocol_reference.md b/docs/instantel_protocol_reference.md index 327ed13..95950ec 100644 --- a/docs/instantel_protocol_reference.md +++ b/docs/instantel_protocol_reference.md @@ -1231,23 +1231,31 @@ Two critical differences from `build_bw_frame`: | Frame | offset_word | counter | params | Purpose | |---|---|---|---|---| | Probe | `0x1004` | `0x0000` | 10 bytes (`bulk_waveform_params(0)`) | Initiate transfer | -| Chunk 1 | `0x1004` | `key4[2:4]` | 11 bytes | First data chunk | -| Chunk 2 | `0x1004` | `key4[2:4] + 0x0400` | 11 bytes | Second chunk | -| Chunk N | `0x1004` | `key4[2:4] + (N-1) * 0x0400` | 11 bytes | Nth chunk | +| Chunk 1 | `0x1004` | `max(key4[2:4], 0x0400)` | 11 bytes | First data chunk | +| Chunk 2 | `0x1004` | `max(key4[2:4], 0x0400) + 0x0400` | 11 bytes | Second chunk | +| Chunk N | `0x1004` | `max(key4[2:4], 0x0400) + (N-1) * 0x0400` | 11 bytes | Nth chunk | | … | … | … | … | … | -| Termination | `0x005A` | `key4[2:4] + N * 0x0400` | 10 bytes | End transfer | +| Termination | `0x005A` | `max(key4[2:4], 0x0400) + N * 0x0400` | 10 bytes | End transfer | > ⚠️ **2026-04-06 CORRECTED — chunk counter is `key4[2:4] + (N-1) * 0x0400`.** > The 4-2-26 BW TX capture showed counter=0x1004 for chunk 1 of key `01110000`, leading to > an interim "monotonic n * 0x0400" formula. This was accidentally correct because > `key4[2:4] == 0x0000` for that event. > -> **2026-04-24 FINAL CORRECTION:** The counter is an absolute circular-buffer address. +> **2026-04-24 CORRECTION:** The counter is an absolute circular-buffer address. > BW's true formula is `key4[2:4] + (chunk_num - 1) * 0x0400` where `key4[2:4]` is the > event's storage base offset (`(key4[2]<<8) | key4[3]`). For keys where > `key4[2:4] != 0x0000` (e.g. key `01111884`), using `n * 0x0400` sends requests into the -> wrong buffer region — the device returns data from a completely different event and -> `b"Project:"` never appears in the stream. Confirmed correct 2026-04-24. +> wrong buffer region — the device returns data from a completely different event. +> +> **2026-04-26 FINAL CORRECTION:** The formula `key4[2:4] + (N-1) * 0x0400` is wrong when +> `key4[2:4] == 0x0000` (e.g. event key `01110000`, the very first event after a device erase). +> Counter=0x0000 for chunk 1 is the same address as the probe frame — the device re-returns +> the STRT record data instead of waveform payload (frame 1 has len=1097, same as probe, and +> contains `b"STRT\xff\xfe"`, contributing zero waveform bytes). +> Final formula: `max(key4[2:4], 0x0400) + (chunk_num - 1) * 0x0400`. +> For key `01110000`: chunk 1 = 0x0400 (confirmed working, empirical test 2026-04-06). +> For key `0111245a`: chunk 1 = 0x245a (unchanged, confirmed from 4-3-26 capture). The `stop_after_metadata=True` flag causes the loop to stop as soon as `b"Project:"` is found in the accumulated A5 frame data, typically after 4–9 chunks. A termination frame diff --git a/minimateplus/protocol.py b/minimateplus/protocol.py index f599170..0a69f93 100644 --- a/minimateplus/protocol.py +++ b/minimateplus/protocol.py @@ -585,13 +585,12 @@ class MiniMateProtocol: frames_data: list[S3Frame] = [] counter = 0 - # BW counter formula (confirmed from 4-3-26 capture for key 0111245a): - # counter for chunk n = key4[2:4] + (n - 1) * 0x0400 - # key4[2:4] is the event's circular-buffer base offset — without it, chunk - # requests address the wrong region of the device buffer and the device - # streams data from the wrong event (no "Project:" in any response). - # PREVIOUSLY WRONG NOTE: "device does not validate counter; chunk_num*0x0400 - # is correct" — that was only true for key 01110000 where key4[2:4]==0x0000. + # BW counter formula (confirmed from 4-3-26 capture for key 0111245a, + # and empirical live-device test 2026-04-06 for key 01110000): + # counter for chunk n = max(key4[2:4], 0x0400) + (n - 1) * 0x0400 + # key4[2:4] is the event's circular-buffer base offset. The max() guard + # ensures chunk 1 never uses counter=0x0000 (which equals the probe address + # and causes the device to re-return STRT record data for the first chunk). _key4_offset = (key4[2] << 8) | key4[3] # ── Step 1: probe ──────────────────────────────────────────────────── @@ -612,15 +611,24 @@ class MiniMateProtocol: log.debug("5A A5[0] page_key=0x%04X %d bytes", rsp.page_key, len(rsp.data)) # ── Step 2: chunk loop ─────────────────────────────────────────────── - # Correct counter formula: key4[2:4] + (chunk_num - 1) * 0x0400 - # This matches Blastware exactly (confirmed from 4-3-26 capture). - # For events where key4[2:4]==0 (e.g. 01110000), this gives the same - # result as the old chunk_num*0x0400 formula shifted by one step, which - # the device also accepted — but for events with a non-zero base offset - # (e.g. key 01111884 with key4[2:4]=0x1884) the old formula sends - # completely wrong counters and the device streams the wrong buffer region. + # Counter formula: _chunk_base + (chunk_num - 1) * 0x0400 + # where _chunk_base = max(key4[2:4], 0x0400). + # + # For events with key4[2:4] != 0 (e.g. key 0111245a, offset 0x245a): + # _chunk_base = 0x245a → chunk 1=0x245a, chunk 2=0x285a, ... + # Confirmed from 4-3-26 capture. + # + # For events with key4[2:4] == 0 (e.g. key 01110000): + # _chunk_base = max(0, 0x0400) = 0x0400 + # → chunk 1=0x0400, chunk 2=0x0800, ... (= old chunk_num*0x0400) + # CRITICAL: counter=0x0000 (same as the probe) causes the device to + # re-return the STRT record data for chunk 1, making frame 1 look like + # a second probe response (confirmed from server log: frame 1 len=1097, + # contains STRT\xff\xfe, contributes zero body bytes after DLE-strip). + # counter=0x0400 for chunk 1 confirmed working (empirical test 2026-04-06). + _chunk_base = max(_key4_offset, _BULK_COUNTER_STEP) for chunk_num in range(1, max_chunks + 1): - counter = _key4_offset + (chunk_num - 1) * _BULK_COUNTER_STEP + counter = _chunk_base + (chunk_num - 1) * _BULK_COUNTER_STEP params = bulk_waveform_params(key4, counter) log.debug("5A chunk %d counter=0x%04X", chunk_num, counter) self._send(build_5a_frame(_BULK_CHUNK_OFFSET, params)) @@ -675,7 +683,7 @@ class MiniMateProtocol: chunk_num, extra_chunks_after_metadata) for _extra_n in range(extra_chunks_after_metadata): chunk_num += 1 - counter = _key4_offset + (chunk_num - 1) * _BULK_COUNTER_STEP + counter = _chunk_base + (chunk_num - 1) * _BULK_COUNTER_STEP params = bulk_waveform_params(key4, counter) self._send(build_5a_frame(_BULK_CHUNK_OFFSET, params)) try: