Byonoy L96: device queries, integration modes, cancel, LED bar

[vcjdeboer]

Summary

Extends pylabrobot/byonoy to drive the full HID surface the Luminescence 96 firmware advertises — beyond the existing read_luminescence(integration_time), this PR adds device queries, integration-mode presets, per-well selection, software-cancellable reads, named-data-fields identity reads, LED bar control, and per-backend firmware-error decoding. Every byte is decoded from the headers in Byonoy's published C library; the vendor wheel is not a runtime dependency.

Validated on hardware against an L96 (sn BYOMAL00029, fw Luminescence V1 2025-03-24).

What's new

Public surface on ByonoyBase (Driver):

• get_status() / get_environment() / get_versions() / get_api_version() / get_supported_reports() / get_device_info() — device queries via REP_*_IN reports (0x0080, 0x0050, 0x0010, 0x0300, 0x0310) and REP_DEVICE_DATA_READ_IN (0x0200) with the documented routing_info=\x80\x40 request tag.
• read_data_field(field_index) — generic typed read of any DD_* field.
• cancel(report_id=0x0340) — fires REP_ABORT_REPORT_OUT (0x0060) and raises a software flag the read loop polls; bails within ~2 s instead of the previous 120 s hard timeout.
• set_led_colours(colours) / set_led_effect(effect, ...) — drives the 20-pixel front bar via REP_LED_BAR_COLOURS_OUT / REP_LED_BAR_EFFECTS_OUT.
• describe_error_code(code) — overridable per-backend decoder.

LuminescenceParams now mirrors the C-library shape:

• mode: Lum96IntegrationMode (RAPID 100 ms / SENSITIVE 2 s / ULTRA_SENSITIVE 20 s / CUSTOM)
• integration_time: Optional[float] (forces CUSTOM if set; preserves the legacy call shape)
• selected_wells: Optional[List[bool]] — output filter (firmware always scans all 96, zero-fills unselected wells; doesn't reduce read time).

Per-backend error tables: Abs96StatusError / Abs1StatusError enums mirroring hid-reports/.../abs96status.cpp and abs1status.cpp. ByonoyAbsorbance96Backend opts in via _ERROR_NAMES = ABS96_ERROR_NAMES; Lum96 has no documented table and inherits the honest hex sentinel fallback (errorCode=0xNN) — the same answer Byonoy's own software gives.

Docs:

• docs/user_guide/byonoy/luminescence_96/lab_guide.md — 13-section walkthrough for someone running an actual luminescence assay (single read, kinetic series, custom integration, well selection, cancel, LED feedback, troubleshooting table).
• pylabrobot/byonoy/ARCHITECTURE_NOTES.md — captures the v1b1-capability review so a future Driver / CapabilityBackend split has the context.

Test plan

• from pylabrobot.byonoy import byonoy_l96; await reader.setup() against a physical L96 — connects via HID, no errors.
• All six device queries return sane values (uptime, temperature, humidity, accelerometer at ~1 g down, firmware string).
• get_supported_reports() returns 23 IDs matching the firmware's published feature set.
• RAPID / SENSITIVE / ULTRA_SENSITIVE modes all complete with appropriate wall-clock times.
• selected_wells mask: column-1-only read returns column 0 with real data and columns 1-11 as exactly 0.00. Read time is unchanged from a full-plate read at the same mode (firmware behaviour, documented).
• cancel() aborts an ULTRA_SENSITIVE read within ~1 s (was 120 s). Device returns to is_measuring=False immediately after.
• set_led_colours and set_led_effect produce the expected visual changes on the front bar.
• get_device_info() returns the same identity fields the C library's byonoy_get_device_information returns.

Out of scope

The pre-existing collapse of Driver and CapabilityBackend into one class (ByonoyBase) is documented in ARCHITECTURE_NOTES.md but not addressed here — that refactor is independent and benefits from being a single focused PR. The notes propose ByonoyDriver + ByonoyDiagnostics / ByonoyLEDBar helpers (P-16 STARCover pattern), with concrete shape suggestions and v1b1 precedent paths.

🤖 Generated with Claude Code

[rickwierenga]

this is a great improvement!

[rickwierenga]

could you make this into a notebook so people can run it directly?

[vcjdeboer]

Done, converted to lab_guide.ipynb

[rickwierenga]

could LED be its own capability / backend?

[vcjdeboer]

(A) Literal LEDBar capability with set_colours/set_effect as the
frontend. Helper-with-a-capability-label. Other devices with chassis
indicators (Flex, Synergy, Cytation) can't realistically fake a 20-pixel
RGB bar.

(B) StatusIndicator paired with InstrumentStatus — transferable,
both new to PLR:

# pylabrobot/capabilities/instrument_status/  (new)                                                                                                                                                       
class InstrumentState(enum.Enum):                         
    OFF; IDLE; BUSY; WAITING; SUCCESS; ERROR                                                                                                                                                              
                                                                                                                                                                                                          
class InstrumentStatusBackend(ABC):                                                                                                                                                                       
    @abstractmethod                                                                                                                                                                                       
    async def read_status(self) -> InstrumentStatusReading: ...                                                                                                                                           
 
# pylabrobot/capabilities/status_indicator/  (new)                                                                                                                                                        
class StatusIndicatorBackend(ABC):                        
    @abstractmethod                                                                                                                                                                                       
    async def set_state(self, state: InstrumentState,
                        progress: Optional[float] = None) -> None: ...                                                                                                                                    
                                                          
# pylabrobot/byonoy/  (new concrete backends)
class ByonoyInstrumentStatusBackend(InstrumentStatusBackend):                                                                                                                                             
    async def read_status(self):                                                                                                                                                                          
        s = await self._driver.get_status()        # firmware 0x0300                                                                                                                                      
        return InstrumentStatusReading(state=..., ...)                                                                                                                                                    
                                                                                                                                                                                                          
class ByonoyStatusIndicatorBackend(StatusIndicatorBackend):
    async def set_state(self, state, progress=None):                                                                                                                                                      
        # maps state → driver.set_led_colours / set_led_effect
        ...                                                                                                                                 

Byonoy implements both: InstrumentStatus wraps firmware report 0x0300;
StatusIndicator maps states to LED colours/effects. Low-level
pixel/effect stays on the driver as escape hatch.

Leaning (B). what do you think?

[rickwierenga]

I don't think focal_height is something that byonoy supports?

[vcjdeboer]

yes fixed it