TCube laser: closed-loop (power) mode and the DiodeLaser interface, verified on the 642 nm rig

[AliKNS]

Summary

This adds a closed-loop ("power") mode for the TCube laser, the DiodeLaser interface it needs, and the hardware facts learned bringing it up on the 642 nm rig. Original work by @AliKNS; review changes are on top.

It targets main as a non-breaking 0.2.5 change (decisions 0033 and 0035). The version stays main's -DEV. Every 0.2.4 line keeps working and means what it meant, including TCubeLaser("serial"; max_current = ..., properties = ...) and setpower(laser, mA). Closed loop is opt-in by keyword. test/tcube_output_order.jl, 0.2.4's own TCube cases, passes unchanged on an open-loop laser built without mode and driven by setpower.

• Types. DiodeLaser <: LightSource, the ConstantCurrent and ConstantPhotocurrent mode types, and TCubeLaser{M} with a PhotodiodeLoop. The mode keyword defaults to ConstantCurrent(), which is 0.2.4's behaviour.
• Closed loop is chosen with mode = ConstantPhotocurrent(). It requires wa_calibration, tia_range, tec_stabilised, properties and max_current. The last is the clamp initialize programs, and it is the only real protection in that mode.
• New calls: setcurrent!, setoutputpower!, setlevel!, measured_current, measured_photocurrent, indicated_output_power and loop_status.
• Deprecated, and still working:
  • setpower on a ConstantCurrent laser forwards to setcurrent!. On a ConstantPhotocurrent laser it throws, naming setoutputpower!, so an mA call can never become an mW one.
  • properties.power.
  • The 2-argument export_state.
• export_state adds the new keys and keeps 0.2.4's six.
• TCubeLaser's default properties stay 0.2.4's ("mW", 0, 100). In open loop they are labels only.
• Mode-dispatched panels: mA in open loop and mW at the laser output in closed loop, with the configured range shown. An out-of-range entry is refused with a red border. Opening a panel sends no command and makes no read. The output toggle follows properties.is_on.
• SimDiodeLaser takes the same keywords as TCubeLaser, minus the serial. The contract test and the API map walk the type hierarchy to its leaves.
• Closed-loop ramp and lock check are per-laser keywords:
  • ramp_step_mW defaults to Inf, a single write; ramp_step_s sets the step interval.
  • lock_check_s = 0.2 and lock_ratio = 1.5: a photocurrent above 1.5x the request after 0.2 s zeroes and disables the output, then throws.
• CALIBRATION.md keeps how to calibrate and a new "Controller facts (TLD001)" section. The rig diary and ceiling sections are cut here, for the rig's own repository to keep.

Safety changes from review (all on the fake SDK, none yet on hardware)

• Every disable is preceded by a zero, including a failed light_on, and a failed send, confirm or lock check in setoutputpower!. If a disable fails, properties.is_on stays true and the log says the output may still be on.
• initialize zeroes and disables the output before the mode command, in both modes.
• Closed-loop light_on and setoutputpower! re-read the status word and the current limit before emitting. They refuse if the loop bit is gone, or if the limit is above max_current or more than 0.5 mA above the programmed clamp.
• The clamp is recorded only after the whole closed-loop initialize succeeds.

What an open-loop 0.2.4 caller now sees (CHANGELOG, Changed)

None of these is yet run on hardware; each needs the 642 nm rig check.

1. initialize starts background polling (LD_StartPolling). shutdown and a failed initialize stop it.
2. initialize zeroes the setpoint and disables the output before the mode command, so properties.is_on is false afterwards.
3. initialize may lower the max-current potentiometer when the controller's limit is above max_current. By construction it never raises it.
4. Two cases now warn that the ceiling is enforced in software only, and initialize carries on, as in 0.2.4:
   • a max_current below the potentiometer's floor (about 17.25 mA);
   • a lowering that fails.
5. light_on and setcurrent! wait up to 1 s for the controller's setpoint read-back and throw if it does not confirm. light_on then zeroes and disables the output.
6. setcurrent! with the output off sends nothing, and light_on applies it after the enable. When the driver recorded the output off, a fresh status read decides.
7. gui(laser) on an open-loop TCubeLaser opens the diode-laser current panel (mA).

Hardware verification (642 nm rig, TLD001 64849775, power meter before the fibre; on @AliKNS's 10f1aba)

• Open loop at 70–130 mA: the current follows the setpoint exactly, giving 1.69–57.7 mW.
• Closed loop at 1, 2, 3, 5, 10, 20, 40 and 70 mW gave 0.56, 1.55, 2.54, 4.52, 9.30, 19.04, 38.74 and 68.59 mW (224.2 W/A holds).
• The diode is an Ushio HL6366DG, rated 80 mW. The meter position sees 0.93 of the head power. The rig's ceiling is 70 mW / 150 mA.
• Found and fixed on the rig, none of it visible to the fake SDK:
  • The TLD001 ignores setpoints sent with the output off. They are now sent right after enabling and zeroed before disabling.
  • The setpoint read-back only refreshes under polling.
  • The photocurrent is signed, with 0x8000 meaning over range.
  • The max-current pot needs adjust mode, and the header's position scale is wrong. The clamp is the controller's reported limit.
• Unexplained and intermittent: a setpoint jumped from 0 locked the loop at about 21 mW three times, then jumps worked at 10, 40 and 70 mW. A single write is the default. The ramp is the opt-in fallback, and the lock check catches the lock.

Rig checks owed on this head, beyond the open-loop list above:

• the lock check's 1.5x / 0.2 s threshold;
• the two extra request/read round trips on every closed-loop light_on and setoutputpower!;
• the re-check's half-step slack;
• the GUI toggle correction after a failed light_off.

Test plan

• Local suite at fe5bb10 (kitt, Julia 1.13): 1722 pass, 3 broken, 0 fail. test/tcube_output_order.jl passes 39/39, unedited.
• lab/tests on fe5bb10: Core pass, 1725 tests; Core on Julia 1.11.9 pass.
• MicroscopeAdapt's suite against this head (it passed against 10f1aba).
• 642 nm rig run of the checks above.
• Downstream rig GUI check after merging.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[kalidke]

Ali, three things from Keith's review of MicroscopeControl.

1. Laser safety issue in 0.2.3. Setting power while the output is off is ignored, so the next "on" runs at whatever was stored (the 642 once sat 13 s at 160 mA this way). A 0.2.4 fix is coming today. Until you have it, set power only after turning the output on, and check the reading.
2. We're pushing fixes to this TCube laser: closed-loop (power) mode and the DiodeLaser interface, verified on the 642 nm rig #66 branch, on top of your commits and never overwriting them. Please pull before pushing from the rig.
3. After 0.2.4, development moves to main, which becomes 0.2.5-DEV. The 0.3rc1 branch goes away, and release branches are used only for safety backports.