Stream-path power bytes scope-verified; contract rules hardware-proven

Power-bytes-only program played by the pulse engine with the scope on
LASER_PWM: full duty staircase observed, run-start 100 percent duty
reset confirmed on the pin, consecutive-power-byte drop confirmed
(second byte of a back-to-back pair discarded), and duty persists
after end-of-data - the laser-off guarantee rests entirely on FIRE.
Zero motion (motor_lock=15 + no step bytes; position counters pinned)
and the laser chain silent throughout. Adds pwm_stream_test.py to the
bench kit and records the FIRE/OK_2_FIRE/LASER_ON/HV_EN naming from
the OpenGlow LASER SAFING sheet.

docs/BRINGUP.md

@@ -170,10 +170,26 @@ hardware I/O — host testing).
      cursor-measured **6.4 % vs 6.3 % commanded** (PWMSAR=8) — clean
      pulse, no runts, carrier stable across the full range. Matches the
      register-level audit numbers (divider 13 × 127 counts, 39.98 kHz).
-   - **≤1-tick laser drop at underrun/end-of-data: OPEN** — needs a
-     stream-path scope session (power bytes + bit-4 FIRE toggling with
-     the latch locked: FIRE is observable while LASER_ON stays gated
-     off by the hardware AND).
+   - **Stream-path power bytes: PASSED 2026-08-02** (scope on
+     LASER_PWM, `scripts/bench/pwm_stream_test.py`: power-bytes-only
+     program preloaded and played by the pulse engine; steppers
+     energized but motor_lock=15 + zero step bits — position counters
+     pinned at 0). Operator observed the full staircase AND both
+     contract rules on the pin: **run-start duty reset to 100%**
+     (first pulses would fire at full power unless the stream's first
+     power byte precedes its first FIRE bit) and **consecutive power
+     bytes dropped** (saw 25 % where a 75 % byte rode directly behind;
+     75 % applied only after a spacer). Also measured: **duty persists
+     after end-of-data** (PWMSAR retains the last value; the end-of-data
+     backstop forces FIRE/step lines low, not the power setpoint) — the
+     laser-off guarantee rests entirely on FIRE.
+   - **≤1-tick FIRE drop at underrun/end-of-data: OPEN** — needs a
+     scope on the FIRE net (bit-4 toggling with the latch locked: FIRE
+     is observable while LASER_ON stays gated off by the hardware AND).
+     Signal naming (per the OpenGlow LASER SAFING sheet): FIRE = the
+     CPU's per-tick request (kernel attr `laser_enable`); OK_2_FIRE =
+     chain verdict; LASER_ON = FIRE∧OK_2_FIRE to the tube (active low);
+     HV_EN = HV supply enable, driven by the safing hardware only.
    - **Interlock readback semantics cross-check: OPEN** (see
      factory-laser-safety-readbacks notes).
 3. **Homing**: X/Y home switch GPIOs exist in the cnc pin map (unused so

scripts/bench/pwm_stream_test.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""LASER_PWM stream-path test - runs ON the board.
+
+Streams POWER BYTES ONLY (bit 7 set) through /dev/glowforge and lets the
+kernel pulse engine play them, so the scope on LASER_PWM verifies the
+real power path the laser milestone will use, including two contract
+rules (run-start duty reset; consecutive power bytes dropped).
+
+Safety posture:
+- The stream contains ZERO step bytes and ZERO FIRE (bit 4) bits.
+- motor_lock=15 masks step output on all axes regardless.
+- laser_latch re-asserted locked; lid closed; HV watchdog untouched.
+- Position counters compared before/after - must be identical.
+- streaming stays 0: end-of-data is a normal completion.
+"""
+import fcntl, mmap, os, struct, time
+
+TICK_HZ = 10000
+PWM2_BASE = 0x02084000
+
+
+def wr(attr, val):
+    with open('/sys/glowforge/' + attr, 'w') as f:
+        f.write(str(val))
+
+
+def rd(attr):
+    with open('/sys/glowforge/' + attr) as f:
+        return f.read().strip()
+
+
+def rd_pos():
+    with open('/sys/glowforge/cnc/position', 'rb') as f:
+        raw = f.read(32)
+    x, y, z, done, total = struct.unpack('<5i', raw[:20])
+    return x, y, z, done, total
+
+
+def pwmsar():
+    with open('/dev/mem', 'rb') as f:
+        m = mmap.mmap(f.fileno(), 4096, mmap.MAP_SHARED, mmap.PROT_READ,
+                      offset=PWM2_BASE)
+        sar = struct.unpack('<I', m[0x0C:0x10])[0]
+        m.close()
+    return sar
+
+
+def power(v):
+    return bytes([0x80 | (v & 0x7F)])
+
+
+PAD = b'\x00'
+
+stream = (
+    PAD * TICK_HZ +                 # 1 s: shows the run-start 100% reset
+    power(64) + PAD * (2 * TICK_HZ) +               # 50%
+    power(32) + power(96) + PAD * (2 * TICK_HZ) +   # 25%; the 96 must be DROPPED
+    power(96) + PAD * (2 * TICK_HZ) +               # 75% (applies after pads)
+    power(8)  + PAD * (2 * TICK_HZ) +               # ~6%
+    power(127) + PAD * (2 * TICK_HZ)                # 100%
+)
+
+print('stream: %d bytes = %.1f s at %d Hz' % (len(stream), len(stream) / TICK_HZ, TICK_HZ))
+print('pre:  state=%s pos=%s laser_enable=%s PWMSAR=%d'
+      % (rd('cnc/state'), rd_pos(), rd('cnc/laser_enable'), pwmsar()))
+
+wr('cnc/laser_latch', 1)
+wr('cnc/motor_lock', 15)
+wr('cnc/step_freq', TICK_HZ)
+
+fd = os.open('/dev/glowforge', os.O_WRONLY)
+try:
+    fcntl.flock(fd, fcntl.LOCK_EX)
+    os.lseek(fd, 1, os.SEEK_SET)       # clear pulse data + byte counters
+    wr('cnc/enable', 1)
+    time.sleep(0.5)
+    os.write(fd, stream)               # preload the whole program
+    pos_before = rd_pos()
+    print('run: state=%s, starting playback...' % rd('cnc/state'))
+    wr('cnc/run', 1)
+    t0 = time.time()
+    state = ''
+    while time.time() - t0 < 30:
+        state = rd('cnc/state')
+        if state != 'running':
+            break
+        time.sleep(0.2)
+    dt = time.time() - t0
+    print('done: state=%s after %.1f s' % (state, dt))
+    pos_after = rd_pos()
+    print('post: pos before=%s after=%s  MOVED=%s'
+          % (pos_before, pos_after, pos_before[:3] != pos_after[:3]))
+    print('post: laser_enable=%s laser_on=%s laser_on_sampled=%s faults=%s underruns=%s'
+          % (rd('cnc/laser_enable'), rd('cnc/laser_on'),
+             rd('cnc/laser_on_sampled'), rd('cnc/faults'), rd('cnc/underruns')))
+    print('post: PWMSAR=%d  (duty after end-of-data)' % pwmsar())
+finally:
+    fcntl.flock(fd, fcntl.LOCK_UN)
+    os.close(fd)
+
+wr('cnc/disable', 1)
+print('safe state restored: state=%s' % rd('cnc/state'))