feat: update event iteration logic to use null sentinel for end-of-events detection

minimateplus/protocol.py

@@ -518,24 +518,33 @@ class MiniMateProtocol:
 
         return frames_data
 
-    def advance_event(self) -> bytes:
+    def advance_event(self) -> tuple[bytes, bytes]:
         """
         Send the SUB 1F (EVENT_ADVANCE) two-step read with download-mode token
-        (0xFE) and return the next waveform key.
+        (0xFE) and return the next waveform key and the full 8-byte event data
+        block.
 
         In download mode (token=0xFE), the device skips partial histogram bins
         and returns the key of the next FULL record directly.  This is the
         Blastware-observed behaviour for iterating through all stored events.
 
         Returns:
-            key4 — 4-byte next waveform key from data[11:15].
-            Returns b'\\x00\\x00\\x00\\x00' when there are no more events.
+            (key4, event_data8) where:
+              key4        — 4-byte opaque waveform record address (data[11:15]).
+              event_data8 — full 8-byte block (data[11:19]).
+
+        End-of-events sentinel: event_data8[4:8] == b'\\x00\\x00\\x00\\x00'.
+        DO NOT use key4 == b'\\x00\\x00\\x00\\x00' as the sentinel — key4 is
+        all-zeros for event 0 (the very first stored event) and will cause the
+        loop to terminate prematurely.
+
+        Confirmed from 4-3-26 two-event capture:
+          - event 0 1E response:  key4=00000000  data8=0000000000011100  (valid)
+          - event 1 1F response:  key4=0000fe00  data8=0000fe0000011100  (valid)
+          - null 1F response:     key4=0000fe00  data8=0000fe0000000000  ← trailing zeros
 
         Raises:
             ProtocolError: on timeout, bad checksum, or wrong response SUB.
-
-        Confirmed from 3-31-26 capture: 1F uses token=0xFE at params[6];
-        loop termination is key4 == b'\\x00\\x00\\x00\\x00'.
         """
         rsp_sub = _expected_rsp_sub(SUB_EVENT_ADVANCE)
         length  = DATA_LENGTHS[SUB_EVENT_ADVANCE]   # 0x08
@@ -549,12 +558,14 @@ class MiniMateProtocol:
         self._send(build_bw_frame(SUB_EVENT_ADVANCE, length, params))
         data_rsp = self._recv_one(expected_sub=rsp_sub)
 
-        key4 = data_rsp.data[11:15]
+        event_data8 = data_rsp.data[11:19]
+        key4        = data_rsp.data[11:15]
+        is_done     = event_data8[4:8] == b"\x00\x00\x00\x00"
         log.debug(
-            "advance_event: next key=%s  done=%s",
-            key4.hex(), key4 == b"\x00\x00\x00\x00",
+            "advance_event: next key=%s  data8=%s  done=%s",
+            key4.hex(), event_data8.hex(), is_done,
         )
-        return key4
+        return key4, event_data8
 
     def read_compliance_config(self) -> bytes:
         """