Capture Sec+2.0 obstruction traffic on a device: OBST_1 vs PAIR_3_RESP timing, OBST_2 semantics

[heythisisnate]

Blocks #29 (fix for #27). Both are parked until someone can capture Security+ 2.0 obstruction traffic from a live opener.

Background

The obstruction path has been reworked twice, each time trading away a signal:

• Before Improve obstruction detection time. #21 — obstruction came only from the OBST bit in STATUS frames, applied unconditionally. Correct, but users reported it as too slow.
• Improve obstruction detection time. #21 — added PAIR_3_RESP decode with both edges explicit: byte1 == 0x0e → obstructed, byte1 == 0x09 → cleared. The unconditional status path stayed as a backstop.
• Use OBST events for immediate obstruction sensing. #22 — went after OBST_1, which lands earlier than PAIR_3_RESP. To stop the two mechanisms fighting it deleted the 0x09 clear branch, demoted 0x0e to only arming obst_clear_from_status, and gated the status backstop behind obstruction == MAX || obst_clear_from_status.

After #22 the state machine has no explicit "cleared" signal, so it infers one by toggling on each OBST_1 behind a 1-second debounce — and #27 is the direct result: a swallowed OBST_1 desyncs it, with no backstop left to repair it.

Separately, GDO_CMD_OBST_2 (0x085) is defined in gdo_priv.h and stringified in gdo_utils.c, but decode_packet() has never handled it. Nobody has looked at what it carries.

What we need from a device

The proposed fix (see #29) is to let each message do the one thing it's good at: OBST_1 sets obstructed, 0x0e confirms, 0x09 clears, STATUS reconciles. Two facts decide whether that design needs a debounce guard and a magic number, or whether it collapses into something simpler.

Q1 — how much latency does OBST_1 actually buy over PAIR_3_RESP 0x0e?

This is the load-bearing question. If 0x0e follows OBST_1 within tens of milliseconds, drop OBST_1 handling entirely, take both edges from PAIR_3_RESP, and no guard is needed — that's #21's design plus the restored backstop. If OBST_1 is meaningfully earlier (presumably what motivated #22), it stays as a set-only fast path and we need a guard against a clear-burst tail landing after 0x09.

Q2 — does OBST_1 fire on the clear edge, or only on the trip?

#22's comment claims "many obstruction events will be sent when a long obstruction is cleared", implying it fires on both. If it does, ordering matters: an OBST_1 arriving after 0x09 would spuriously re-assert obstructed. (An OBST_1 arriving before 0x09 is harmless — we're already obstructed, so setting obstructed is a no-op.) The guard window in Q1 only needs to cover the burst tail.

Q3 — what does OBST_2 carry?

If OBST_1/OBST_2 distinguish trip from clear, the whole edge-inference problem disappears. Its data bytes may encode state directly.

Capture plan

Log cmd, nibble, byte1, byte2 and a millisecond timestamp for every frame, then exercise:

• Brief interruption (fast hand wave through the beam, well under 1s). Record the full frame sequence with timings.
• Sustained interruption (box in the beam, 30s+), through trip, hold, and clear.
• Repeated trips in quick succession, to see how bursts overlap.

From those captures, answer:

• Q1: measured delta between OBST_1 and the following PAIR_3_RESP 0x0e.
• Q2: does OBST_1 appear on the clear edge? Before or after 0x09? How long is the burst tail?
• Q3: does OBST_2 ever appear, and does it correlate with trip vs. clear? What's in its data bytes?
• Is 0x09 reliably emitted for short obstructions, or only long ones? (Use OBST events for immediate obstruction sensing. #22's "long duration" framing suggests 0x0e may be long-only — if so, what marks a short trip?)
• Does the STATUS OBST bit ((byte1 >> 6) & 1) latch, or does it track the beam in real time? Does it lag the OBST_* messages, and by how much?
• Cross-check the STATUS bit against whichever OBST_* / PAIR_3_RESP preceded it, to confirm it's safe to restore as an unconditional backstop.

Also worth confirming on the device

• Whether a GET_STATUS issued during an obstruction burst survives the TX path, or gets dropped by the 3-second staleness check at gdo.c:1671 after repeated 150ms collision reschedules. This is the mechanism that sinks the round-trip approach in Fix Sec+2.0 obstruction reporting so it updates the moment the beam breaks #29.

[heythisisnate]

Live capture results — Security+ 2.0 obstruction traffic

Captured on a live GDO blaQ (ESP32-S3) wired to a Security+ 2.0 opener, obst_from_status = true. gdolib was instrumented with a millisecond-stamped log line for every OBST_1 / OBST_2 / PAIR_3_RESP / STATUS frame (t= is ms since boot; ESPHome's log header is only second-resolution, hence the in-message stamp). Three scenarios from the capture plan were run: brief wave (<1 s), sustained block (~30 s), and repeated rapid trips.

Decoded bit semantics

• STATUS obstruction bit is (byte1 >> 6) & 1, active-low: byte1=0x60 → bit 1 = clear, byte1=0x20 → bit 0 = obstructed.
• PAIR_3_RESP: byte1=0x0e = obstructed marker, byte1=0x09 = clear marker.
• Every frame is double/triple-transmitted ~74 ms apart with the same rolling code — these are retransmissions of one logical frame, not multiple events. This is what the debounce mainly exists to collapse.

Scenario 1 — brief wave (<1 s)

t=209915  OBST_1   data=…084   trip  → Clear→Obstructed   [sensor ON]
t=209989  OBST_1   data=…084   (74 ms dup, same rolling, skipped)
t=210064  OBST_2   data=…085   (unhandled)
t=210965  OBST_1   data=…084   clear → Obstructed→Clear   [sensor OFF]
t=211038  OBST_1   data=…084   (dup, skipped)
t=211113  OBST_2   data=…085
t=211187  STATUS   byte1=0x60 bit=1 (clear)   ← first STATUS after the whole event

• No PAIR_3_RESP and no STATUS bit change at all — the obstruction fell entirely between the opener's STATUS broadcasts. A pure STATUS backstop would have missed this event.
• The two edges were 1050 ms apart — just over the 1 s debounce. A faster wave would have had the clear-edge OBST_1 swallowed → stuck obstructed. That's the Obstruction notification lags until another event is triggered #27 fragility.

Scenario 2 — sustained block (~30 s) — the load-bearing data

Trip:

t=380433  OBST_1        trip  → Obstructed   [sensor ON, immediate]
t=380849  STATUS  byte1=0x60 bit=1 (CLEAR)   ← 416 ms after trip, STATUS still says clear
t=382876  STATUS  byte1=0x60 bit=1 (clear)   ← still clear at +2.4 s
t=382951  STATUS  byte1=0x60 bit=1 (clear)
t=384165  PAIR_3_RESP  byte1=0x0e            ← "long duration" marker, +3.7 s after trip
t=384823  STATUS  byte1=0x20 bit=0 (OBSTRUCTED)  ← STATUS bit finally flips, +4.4 s after trip

Clear (object removed):

   ...held, STATUS steady byte1=0x20 bit=0...
t=431866  PAIR_3_RESP  byte1=0x09            ← explicit CLEAR marker
t=432337  OBST_1        clear-edge (+471 ms after 0x09)
t=432446  OBST_1        (dup)
t=432520  STATUS  byte1=0x60 bit=1 (clear)   [sensor OFF]

Q1 — OBST_1 vs PAIR_3_RESP 0x0e latency: 0x0e arrives ~3.7 s after the OBST_1 trip (380433 → 384165), and the STATUS bit flips ~4.4 s after the trip. Not tens of ms — seconds. OBST_1 must remain the fast path; 0x0e/STATUS are slow confirmations.

The STATUS obstruction bit is NOT real-time — it lags the beam by ~4.4 s and reflects the opener's own confirmed/debounced obstruction state. For 2.5 s after the beam broke, STATUS kept reporting clear. This is the single most important finding: a naive unconditional STATUS backstop is actively wrong — right after a real OBST_1 trip, the next (stale) STATUS bit=1 would reset the state to clear and it would flap until the bit caught up ~4 s later.

Scenario 3 — repeated rapid trips (5 waves in ~2–3 s)

Rolling codes contiguous (no dropped frames). The opener produced exactly two OBST_1 events — one on the first break, one on the final clear, 4.2 s apart:

t=275107  OBST_1   first break → Obstructed
t=275256  STATUS   byte1=0x60 bit=1 (clear)   ← STATUS bit NEVER flips during intermittent obstruction
t=277619  STATUS   byte1=0x60 bit=1 (clear)
t=279336  OBST_1   final clear → Clear
   (no PAIR_3_RESP at all)

The opener coalesces intermittent interruptions. A flickering beam is reported only as OBST_1-on-first-break + OBST_1-on-final-clear; the confirmed-obstruction machinery (STATUS bit + 0x0e) needs ~4 s of continuous blockage to latch, so it never engaged. For brief and intermittent obstructions, OBST_1 is the only signal that fires. This also means hand-waving cannot reproduce the sub-1 s toggle desync — the opener paces OBST_1 edges ≥ ~1 s apart, so the debounce only ever collapses the 74 ms retransmit.

Consolidated three-signal model

Signal	Latency after physical edge	Fires on	Payload	Role
OBST_1 (0x084)	immediate	both edges (+ occasional repeat during a hold)	all-zero — edge-ambiguous	only fast signal; only signal for brief/intermittent
OBST_2 (0x085)	immediate, ~75 ms after OBST_1	both edges	all-zero	carries no state — safe to keep ignoring
PAIR_3_RESP	~3.7 s	continuous obstruction only	0x0e=obstructed, 0x09=clear	explicit directional confirm; 0x09 currently dead code
STATUS bit6	~4.4 s	continuous only	active-low, authoritative-but-lagging	backstop, not real-time

Answers to the open questions:

• Q1: OBST_1 leads 0x0e by ~3.7 s. Keep OBST_1 as the fast path.
• Q2: OBST_1 does fire on the clear edge (identical payload). On a sustained clear it arrives ~471 ms after 0x09 — so ordering matters: an unguarded "OBST_1 sets obstructed" would re-assert obstructed right after 0x09 cleared it.
• Q3: OBST_2 carries no trip/clear information (all-zero on both edges). No handler needed.
• Short obstruction 0x09/0x0e? No — 0x0e/0x09 and the STATUS bit only track continuous obstruction (~4 s to latch). Brief/intermittent are OBST_1-only.
• Does the STATUS bit latch or track real time? Lagging latch (~4.4 s), tracks the opener's confirmed state, not the beam.
• Is a GET_STATUS round-trip viable? No. The requested STATUS carries the same ~4 s-lagging bit, so it would report clear right after a trip and never fire for brief/intermittent obstructions. This sinks the Fix Sec+2.0 obstruction reporting so it updates the moment the beam breaks #29 round-trip approach.

Implication for the fix (see #29)

• OBST_1 stays as the immediate fast path (toggle), because it's the only signal for brief/intermittent obstructions.
• Restore the 0x09 clear branch — the opener gives an explicit clear marker; it's currently dropped.
• Restore a STATUS backstop, but safety-biased: believe "obstructed" immediately; only accept "clear" once a sustained obstruction is confirmed (or after boot), never letting a stale clear cancel a fresh trip.
• Suppress OBST_1 for a short window after an authoritative (0x0e/0x09/STATUS) change so the ~471 ms trailing clear-edge OBST_1 can't re-assert obstructed.
• Drop the GET_STATUS round-trip entirely.

Debounce/guard constants are now grounded in measurements rather than guessed: 74 ms retransmit spacing, ~471 ms trailing OBST_1 after 0x09, ~1050 ms minimum real-edge spacing, ~4.4 s STATUS lag.