From 0ad1505cc576466a9ff52263da71afae01a23d2f Mon Sep 17 00:00:00 2001
From: serversdwn <brianharrison02@gmail.com>
Date: Fri, 27 Feb 2026 02:24:47 -0500
Subject: [PATCH] feat: update s3_bridge to v0.4.0 with annotation markers and
 dual log output

---
 bridges/s3-bridge/s3_bridge.py       | 86 ++++++++++++++++++++++++++--
 docs/instantel_protocol_reference.md | 35 ++++++++++-
 2 files changed, 114 insertions(+), 7 deletions(-)

diff --git a/bridges/s3-bridge/s3_bridge.py b/bridges/s3-bridge/s3_bridge.py
index cdc038f..835333c 100644
--- a/bridges/s3-bridge/s3_bridge.py
+++ b/bridges/s3-bridge/s3_bridge.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """
 s3_bridge.py — S3 <-> Blastware serial bridge with frame-aware session logging
-Version: v0.3.0
+Version: v0.4.0
 
 Key features:
 - Low CPU: avoids per-byte console printing
@@ -9,12 +9,21 @@ Key features:
 - Frame-aware logging: buffers per direction until ETX (0x03), then logs full frame on one line
 - Also logs plain ASCII bursts (e.g., "Operating System") cleanly
 - Dual log output: hex text log (.log) AND raw binary log (.bin) written simultaneously
-- Session log files created on start, closed on Ctrl+C
+- Interactive annotation: type 'm' + Enter to stamp a [MARK] into both logs mid-capture
+- Binary sentinel markers: out-of-band FF FF FF FF <len> <label> in .bin for programmatic correlation
+- Auto-marks on session start and end
 
 Usage examples:
   python s3_bridge.py
   python s3_bridge.py --bw COM5 --s3 COM4 --baud 38400
   python s3_bridge.py --quiet
+
+Annotation:
+  While running, type 'm' and press Enter. You will be prompted for a label.
+  The mark is written to the .log as:
+      [HH:MM:SS.mmm] >>> MARK: your label here
+  And to the .bin as an out-of-band sentinel (never valid frame data):
+      FF FF FF FF <1-byte length> <label bytes>
 """
 
 from __future__ import annotations
@@ -31,7 +40,12 @@ from typing import Optional
 import serial
 
 
-VERSION = "v0.3.0"
+VERSION = "v0.4.0"
+
+# Sentinel prefix for binary markers. Four 0xFF bytes can never appear in
+# valid Instantel DLE-framed data (0xFF is not a legal protocol byte in any
+# framing position), so this sequence is unambiguously out-of-band.
+BIN_MARK_SENTINEL = b"\xFF\xFF\xFF\xFF"
 
 
 def now_ts() -> str:
@@ -74,6 +88,20 @@ class SessionLogger:
         with self._lock:
             self._bin_fh.write(data)
 
+    def log_mark(self, label: str) -> None:
+        """
+        Write an annotation mark to both logs simultaneously.
+
+        .log  — visually distinct line: [TS] >>> MARK: label
+        .bin  — out-of-band sentinel: FF FF FF FF <len> <label utf-8, max 255 bytes>
+        """
+        ts = now_ts()
+        label_bytes = label.encode("utf-8", errors="replace")[:255]
+        sentinel = BIN_MARK_SENTINEL + bytes([len(label_bytes)]) + label_bytes
+        with self._lock:
+            self._fh.write(f"[{ts}] >>> MARK: {label}\n")
+            self._bin_fh.write(sentinel)
+
     def close(self) -> None:
         with self._lock:
             try:
@@ -202,6 +230,43 @@ def forward_loop(
             time.sleep(0.002)
 
 
+def annotation_loop(logger: SessionLogger, stop: threading.Event) -> None:
+    """
+    Runs on the main thread (or a dedicated thread) reading stdin.
+    Type 'm' + Enter to trigger an annotation prompt.
+    Any other non-empty input is ignored with a hint.
+    Bare Enter (empty line) is silently ignored to prevent accidental marks.
+    """
+    print("[MARK] Type 'm' + Enter to annotate the capture. Ctrl+C to stop.")
+    while not stop.is_set():
+        try:
+            line = input()
+        except EOFError:
+            # stdin closed (e.g. piped input exhausted)
+            break
+        except KeyboardInterrupt:
+            break
+
+        line = line.strip()
+        if not line:
+            continue  # bare Enter — ignore silently
+
+        if line.lower() == "m":
+            try:
+                sys.stdout.write("  Label: ")
+                sys.stdout.flush()
+                label = input().strip()
+            except (EOFError, KeyboardInterrupt):
+                break
+            if label:
+                logger.log_mark(label)
+                print(f"  [MARK written] {label}")
+            else:
+                print("  (empty label — mark cancelled)")
+        else:
+            print("  (type 'm' + Enter to annotate)")
+
+
 def main() -> int:
     ap = argparse.ArgumentParser()
     ap.add_argument("--bw", default="COM5", help="Blastware-side COM port (default: COM5)")
@@ -229,8 +294,10 @@ def main() -> int:
     logger = SessionLogger(log_path, bin_path)
     print(f"[LOG] Writing hex log to  {log_path}")
     print(f"[LOG] Writing binary log to {bin_path}")
+
     logger.log_line(f"[{now_ts()}] [INFO] s3_bridge {VERSION} start")
     logger.log_line(f"[{now_ts()}] [INFO] BW={args.bw} S3={args.s3} baud={args.baud}")
+    logger.log_mark(f"SESSION START — BW={args.bw} S3={args.s3} baud={args.baud}")
 
     stop = threading.Event()
 
@@ -251,12 +318,19 @@ def main() -> int:
         args=("S3->BW", s3, bw, logger, stop, args.quiet, args.status_every),
         daemon=True,
     )
+    # Annotation loop runs in its own daemon thread so it doesn't block shutdown
+    t_ann = threading.Thread(
+        target=annotation_loop,
+        name="Annotator",
+        args=(logger, stop),
+        daemon=True,
+    )
 
     t1.start()
     t2.start()
+    t_ann.start()
 
     try:
-        # Wait until Ctrl+C
         while not stop.is_set():
             time.sleep(0.05)
     finally:
@@ -266,6 +340,7 @@ def main() -> int:
         stop.set()
         t1.join(timeout=1.0)
         t2.join(timeout=1.0)
+        # t_ann is daemon — don't join, it may be blocked on input()
 
         try:
             bw.close()
@@ -276,6 +351,7 @@ def main() -> int:
         except Exception:
             pass
 
+        logger.log_mark("SESSION END")
         logger.log_line(f"[{now_ts()}] [INFO] ports closed, session end")
         print("[LOG] Closing session log")
         logger.close()
@@ -284,4 +360,4 @@ def main() -> int:
 
 
 if __name__ == "__main__":
-    raise SystemExit(main())
\ No newline at end of file
+    raise SystemExit(main())
diff --git a/docs/instantel_protocol_reference.md b/docs/instantel_protocol_reference.md
index 4edcdc8..8cc684a 100644
--- a/docs/instantel_protocol_reference.md
+++ b/docs/instantel_protocol_reference.md
@@ -30,6 +30,7 @@
 | 2026-02-26 | §15 → Appendix A | **RENAMED:** Binary log format section moved to Appendix A with explicit note that it describes tooling behavior, not protocol. |
 | 2026-02-26 | Header | **ADDED:** Certainty legend clarification — ratings apply to protocol semantics only, not tooling behavior. |
 | 2026-02-26 | §7.6 Channel Config Float Layout | **NEW SECTION:** Trigger level confirmed as IEEE 754 BE float in in/s. Alarm level identified as adjacent float = 1.0 in/s. Unit string `"in./s"` embedded inline. `0x082A` removed as trigger level candidate. |
+| 2026-02-25 | Appendix A | **UPDATED:** v0.4.0 — annotation markers added. `.bin` sentinel format documented. Parser caveat added for SUB `5A` raw ADC payloads. |
 
 ---
 
@@ -631,7 +632,7 @@ Build in this order — each step is independently testable:
 | Channels | Tran, Vert, Long, MicL (4 channels) |
 | Sample Rate | ~1024 sps (🔶 INFERRED) |
 | Bridge Config | COM5 (Blastware) ↔ COM4 (Device), 38400 baud |
-| Capture Tool | s3_bridge v0.4.0 |
+| Capture Tool | s3_bridge v0.4.0 (annotation markers, dual .log/.bin output) |
 
 ---
 
@@ -639,10 +640,13 @@ Build in this order — each step is independently testable:
 
 ## Appendix A — s3_bridge Capture Format
 > ✅ **CONFIRMED — 2026-02-26**
+> ⚠️ **Updated for v0.4.0 — annotation markers added.**
 
 > ⚠️ **This behavior is not part of the Instantel protocol. It is an artifact of the bridge logger implementation.**
 
-The `.bin` files produced by `s3_bridge` are **not raw wire bytes**. The logger makes one modification:
+### A.1 Binary modifications
+
+The `.bin` files produced by `s3_bridge` are **not raw wire bytes**. The logger makes one modification to frame data:
 
 | Wire sequence | In .bin file | Notes |
 |---|---|---|
@@ -656,6 +660,33 @@ The `.bin` files produced by `s3_bridge` are **not raw wire bytes**. The logger
 
 > ⚠️ This means checksums cannot be verified on frames where the stuffed payload ends in `0x10` — that trailing `0x10` would normally be the DLE prefix of ETX, but the logger strips it, making the frame boundary ambiguous in that edge case. In practice this has not been observed in captured data.
 
+### A.2 Annotation markers (v0.4.0+)
+
+When the operator types `m` + Enter during a capture, both files receive a marker at that timestamp.
+
+**`.log` format:**
+```
+[HH:MM:SS.mmm] >>> MARK: label text here
+```
+The `>>>` prefix never appears in frame log lines (which use `[direction]`) and is trivially skippable by a parser.
+
+**`.bin` format — out-of-band sentinel:**
+```
+FF FF FF FF <len: 1 byte> <label: len bytes, UTF-8>
+```
+
+The four `0xFF` sentinel bytes are chosen because `0xFF` is not a valid byte in any Instantel framing position:
+- Not a valid ACK (`0x41`), DLE (`0x10`), STX (`0x02`), or ETX (`0x03`)
+- The `0xFF - SUB` response pattern produces values like `0xA4`, `0xEA`, `0xFE` — never a bare `0xFF` in the framing layer
+
+**⚠️ Parser caveat — SUB `5A` raw ADC payloads:**
+The sentinel assumption is robust for the framing layer, but the raw ADC sample data in SUB `5A` bulk waveform streams is less constrained. High-amplitude samples could theoretically produce `FF FF FF FF` within the data portion of a frame. **Do not scan the entire `.bin` file as a flat byte stream for sentinels.** Instead:
+1. Parse frame boundaries first (walk `0x41` ACK → `0x10 0x02` STX → ... → bare `0x03` ETX)
+2. Only scan for `FF FF FF FF` in the **gaps between frames** — sentinels are always written between complete frames, never mid-frame
+3. Any `FF FF FF FF` appearing inside a frame boundary is ADC data, not a marker
+
+Session start and end are automatically marked in both files.
+
 ---
 
 ## 14. Open Questions / Still Needs Cracking