feat: host-programmable LED matrix with phase-contrast annulus configurator (#623 + #624)

[Alpaca233]

What

Combines #623 (firmware) and #624 (host) into one PR so the feature lands atomically instead of as two PRs that each need the other to be useful. The three feature commits are cherry-picked unchanged from those branches (@hongquanli remains the author). One extra commit applies black to the two host files that failed the lint gate on #624; it is formatting only.

Make the LED matrix host-programmable per-pixel: patterns (rings, DPC, custom apertures) are computed on the host and painted into a framebuffer on the controller, so new patterns no longer require a firmware reflash. A new Phase Contrast tab computes an annular illumination pattern and drives it through the programmable source, with a separate ring per imaging configuration.

Firmware (firmware/controller/src/)

• ILLUMINATION_SOURCE_LED_ARRAY_PROGRAMMABLE (10) — displays a host-painted 128-LED framebuffer (led_matrix_user). It's kept separate from the live matrix so it survives the clear_matrix() that strobe-off does between acquisition frames; turning the source on copies the framebuffer into the live matrix and shows it.
• SET_ILLUMINATION_LED_MATRIX_PIXEL (45) — write one LED into the framebuffer (no show).
• CLEAR_ILLUMINATION_LED_MATRIX (46) — zero the framebuffer.
• Pixel /255*MAX_INTENSITY scaling and R/G channel order match the built-in full/half patterns, so a host-painted color renders identically to the same built-in color.

Host protocol (_def.py, microcontroller.py)

• Mirror the firmware commands: SET_ILLUMINATION_LED_MATRIX_PIXEL (45), CLEAR_ILLUMINATION_LED_MATRIX (46), ILLUMINATION_SOURCE_LED_ARRAY_PROGRAMMABLE (10).
• set_illumination_led_matrix_pixel / clear_illumination_led_matrix, and set_illumination_led_matrix_frame(frame) to push a full 128-LED frame (clear + non-black pixels), using the same R/G order and scaling as set_illumination_led_matrix.

GUI (widgets.py, gui_hcs.py, live_controller.py)

• New Phase Contrast tab (LedMatrixRingWidget) computes a 128-LED annulus frame and hands it to the live controller, which sends it per-pixel and selects the programmable source.
• Ring is specified by inner/outer diameter in pixels (LED pitches), with inner constrained ≤ outer. Ring type (full / 180° half), direction, and color are selectable; intensity comes from the channel's own live-view slider.
• Per-configuration settings: a selector lists the imaging configurations that use the programmable source; each keeps its own ring, persisted to cache/phase_contrast_annulus_settings.json. get_frame(intensity, channel_name) reads stored settings by name (plain data, not Qt widgets), so live view and wellplate multipoint acquisition both use the correct ring for whichever configuration is imaging — thread-safe from the acquisition worker.
• live_controller routes the programmable source through the widget frame and includes source 10 in _is_led_matrix; gui_hcs adds the tab and auto-follows the active live configuration.

Required machine config (not in this PR)

The annulus imaging channel and its port mapping live in machine_configs/ + user_profiles/, which are gitignored (per-machine). To enable the feature on a device, add:

machine_configs/illumination_channel_config.yaml — map a free controller port to source 10, and add the channel:

controller_port_mapping:
  USB6: 10          # any UNUSED port; must match ^(D[1-8]|USB[1-8])$ (USB9 is rejected)
channels:
  - name: Phase contrast annulus
    type: transillumination
    controller_port: USB6
    wavelength_nm: null
    intensity_calibration_file: null

user_profiles/<profile>/channel_configs/general.yaml — add the imaging channel (merges into every objective):

- name: Phase contrast annulus
  enabled: true
  display_color: '#FFFFFF'
  z_offset_um: 0.0
  camera_settings: {exposure_time_ms: 20.0, gain_mode: 10.0}
  illumination_settings:
    illumination_channel: Phase contrast annulus   # MUST equal the name above
    intensity: 20.0

Any imaging configuration whose illumination_channel resolves to source 10 appears in the tab's selector and gets its own ring.

Testing

• Firmware (from feat(firmware): host-programmable per-pixel LED matrix framebuffer #623): pio run -e teensy41 builds clean; flashed to a Teensy 4.1 and exercised from the host, painting a 128-LED annulus frame and displaying it in live view and acquisition.
• Host (from feat(gui): host-computed phase-contrast annulus with per-configuration rings #624): launched against the flashed Teensy. Verified the "Phase contrast annulus" configuration paints the ring in live view and applies the correct per-configuration ring during acquisition. Ring geometry checked numerically (default 6→8 px lights the expected 20-LED ring; half-ring lights exactly half).
• Combined branch: the diff is byte-identical to feat(firmware): host-programmable per-pixel LED matrix framebuffer #623 + feat(gui): host-computed phase-contrast annulus with per-configuration rings #624 apart from the black commit. Merges cleanly with current master (c05bef3a), including the firmware commands.cpp that feat(fw): TMC2240 stepper-driver support behind a per-axis driver seam (firmware 1.5) #644 also touched. black --check passes. CI-equivalent pytest run (--ignore=tests/control/test_HighContentScreeningGui.py): 1632 passed, 9 skipped, 1 xfailed. Merged firmware: pio run -e teensy41 succeeds and pio test -e native passes 138/138.

Supersedes

#623 and #624.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JRAcmjXX4CEN9wXSnp6HzK