TCube laser: send the setpoint after enabling, zero it before disabling (0.2.4 safety patch)

[kalidke]

Safety patch, 0.2.3 -> 0.2.4. v0.2.3 and every earlier tag are affected.

The hazard

The Thorlabs TLD001 ignores LD_SetLaserSetPoint while its output is disabled and, on the next LD_EnableOutput, runs on whatever setpoint it had stored. v0.2.3's setpower sent the setpoint whenever it was called and light_on only enabled the output, so the ordinary setpower(l, x); light_on(l) ran at the stale stored value. Observed on the 642 nm rig's TLD001 (64849775) on 2026-09-28 and recorded in #66; on 2026-09-29 a script in that order drove the diode for about 13 s at the controller's ~160 mA limit.

The fix (TCubeLaserControl)

• light_on re-checks drive_current against the ceiling (nothing is sent if it fails), enables, then sends the setpoint. If that setpoint fails it disables the output again and throws.
• light_off and shutdown zero the setpoint while the output is still on, then disable, so the next enable starts dark. A failed zero is logged; a failed disable still throws.
• setpower still sends on every call (harmless while off, and it covers an output enabled elsewhere); it now says when the current will be applied at light_on.
• Limitation, documented: between the enable and the setpoint that follows it (one USB round trip) the controller runs on its stored setpoint: 0 after this driver's light_off/shutdown, but anything up to its limit if other software left it there.

Behaviour changes, each in the CHANGELOG: light_on before any setpower now enables at setpoint 0 with a warning (it used to run at the stored value, which is the hazard); a failed zeroing in light_off logs instead of throwing.

Decision 0035: this release changes no public signature and no config type. The TCubeLaser struct, its fields and both constructors are unchanged, and so are the signatures of setpower, light_on, light_off and shutdown. The one new function, zero_setpoint, is internal and unexported.

Release process (same PR, per T16)

• Lab decision 0033: TagOnMerge skips a -DEV version quietly, and CI's version check accepts X.Y.Z-DEV. The rules and their selftest are in .github/scripts/versions.py, shared by both workflows. The selftest (16 cases) passes; the read path was checked on Python 3.12.
• Decision 0009 amendment: TagOnMerge tags only when the merged commit's tree is byte-identical to that of a commit with a passing lab/tests (the commit itself or the merged PR's head); otherwise it fails and says why. The coverage block was dry-run against real squash merges here (TCube laser: refuse out-of-range currents, keep the caller's ceiling, report the drive current #62, Trim CI to the minimum useful signal; make the local suite the gate #61, PI stage: refuse to finish initialize unreferenced #64): each squash commit's tree equalled its PR head's tree.
• One separate commit (391a3e4), per admiral's ruling on the record_tests.jl refusal: a minimal test/test_groups.toml (the whole suite as Core), dev/output/ gitignored (decision 0028), plus the two further things record_tests.jl turned out to need. First, test/lab_summary.jl writes the LAB_TEST_SUMMARY it reads; it wraps the existing top-level testset in two lines and changes no test. Second, DAQmx's [sources] is committed in the rev = "main" form Pkg.test() rewrites it to, so a run leaves the tree clean.

Tests

• New test/tcube_output_order.jl (8 cases) against a fake controller that models the ignore-while-off behaviour (test/tcube_fake_sdk.jl, extended). On v0.2.3's driver, cases a to g fail (g only on its log assertion); h is a regression guard that also passes on v0.2.3. On this head: 28/28.
• Two existing assertions updated (the shutdown call order now starts with the zeroing setpoint); no other test changed.
• Full local suite on the tested tree: xvfb-run -a julia --project -e 'using Pkg; Pkg.test()': 987 pass, 8 broken, 0 fail, 0 error, 122 s wall. The head differs from that tree only in the [sources] line and CHANGELOG text. The lab/tests record on this head follows.
• Hardware verification: not done in this repository. No hardware result is claimed.

Not to be merged without Keith's word.

🤖 Generated with Claude Code