[taylorlm88]

Summary

Wires the LED backlight controller into the arena rig the way BIAS is wired, so a protocol’s backlight plugin (declared in the YAML as matlab: class: "LEDControllerPlugin") runs from the Studio through the backlight node instead of being skipped. The node itself, rig_nodes.backlight_node, comes from reiserlab/rig-nodes#11.

• Gateway (rig/nodes/bridge_node.py): /backlight/cmd|reply|status constants. A backlight entry in CONNECTOR_TOPICS (relay, replies routed to the asking tab, run-log connector events, hello_ack advertises it). The three topics are added to the bag and to the run's opening connector_status.
• Launcher (rig/nodes/rig.py):
  • --backlight, --backlight-sim and --backlight-args, following BIAS.
  • The node has no default port, so --backlight-sim fills in --port socket://127.0.0.1:5020, and --backlight with no port exits 2 before anything starts.
  • TCP 5020 is added to the startup port check.
  • Against a rig-nodes without the node, it prints one line and starts the rest of the rig, as the host monitor does.
• Converter (rig/nodes/mcap_convert.py): /backlight/reply|status → {"type":"connector","src":"backlight",…} events.
• Studio (arena_studio.html):
  • connectorPluginNames() maps LEDControllerPlugin, or a plugin named backlight, to the backlight connector.
  • The "▶ Run this condition" driveable set includes it.
• rig/pixi.toml: backlight-node, backlight-cmd and backlight-sim tasks.
• Tests:
  • test_gateway_registration.py: five backlight checks.
  • studio_emulator.py --backlight-cmds: six commands as the Studio writes them.
  • test_ros2_poc.py: simulator and node on the graph. Checks commands and via=ws replies one to one with the plugin name, status lines, /backlight/* in the bag, and that the simulator received exactly the Studio's lines in order.
• rig/README.md: a Backlight paragraph, commands and the tasks row.

Depends on: a rig-nodes release containing reiserlab/rig-nodes#11, then a commit here bumping rig/pixi.toml's rig_nodes pin to it. Until then the backlight checks skip with an info line (the installed 0.4.0 has no backlight node). Opened as a draft for that reason.

Open questions

• W3. Every Studio-authored color command sends RED 5 0, never RED 5.
  • plugin-registry.js gives panel_num a default of 0 ("Panel # (0=all)"), and the Studio writes non-empty defaults into new cards. So every setRedLEDPower card is {power: 5, panel_num: 0}. pattern's default '' is empty, so it isn't written.
  • Kept as is for now; MATLAB running the same protocols sends the same bytes.
  • What does panel 0 mean to the backlight controller's firmware? If it isn't "all", the default should go.
• L2. The Studio doesn't consult critical for connector commands. A failed connector command is proceed-and-skip, for BIAS and ScanImage today and the backlight with this PR. MATLAB aborts the run when a critical plugin fails, so a backlight that stops working mid-run would no longer stop the experiment. Is proceed-and-skip the intended policy for every connector?
• W5. The registry's critical field has no effect in the Studio (a consequence of L2).
• W8. Should --backlight start without the node when the installed rig-nodes lacks it? It currently prints one line and starts the rest of the rig, following the host-monitor pattern. The alternative is to refuse to start for a device the operator asked for by name.
• W7 (noticed, not changed): ScanImage is missing from the Studio's "Run this condition" driveable set, so that button counts ScanImage commands as skipped, although the runner drives them.

Tier

next candidate (changes the Studio)

Release notes

Studio

• Backlight plugin commands now run from the Studio. A protocol's backlight commands (setIRLEDPower, setRedLEDPower, turnOnLED, …) go through the rig's backlight node instead of being skipped. Start the rig with pixi run rig -- --backlight --backlight-args "--port COM6", or try it without hardware using --backlight --backlight-sim.

Test plan

• pixi run test
• pixi run -e dev test-gateway: 10/10, macOS. The dev environment was pointed at the rig-nodes branch; that change is not committed.
• pixi run -e dev test (rig): 67/67, macOS. Includes the five backlight checks: Studio-path commands, via=ws replies with the plugin name, status lines, /backlight/* in the bag, and exact lines at the simulator in order. An earlier run had five timing/BIAS-video failures that didn't recur. The harness's tolerances are tuned for rig PCs.
• Studio JS tests that read arena_studio.html pass. Separately checked: connectorPluginNames() maps LEDControllerPlugin and backlight to the backlight connector, and BIAS is unchanged.
• main merged in after rig: the ROS distribution is one switch — jazzy/lyrical features in rig/pixi.toml (rigs' environments unchanged) #294; rig/pixi.toml's [workspace.build-variants] now comes from main, so nothing extra is needed here.
• The browser Studio on a rig running a protocol with backlight commands, through pixi run rig -- --backlight --backlight-sim. Not done.
• The real backlight controller. See the hardware list in Backlight: LED backlight controller node (port of MATLAB LEDController / LEDControllerPlugin) rig-nodes#11.