pioreactor-automations

name	pioreactor-automations
description	Create, update, debug, or review Pioreactor dosing, temperature, and LED automations, including automation families, config sections, UI descriptors, runtime execution strategies, published settings, lifecycle cleanup, and dosing shutdown safety.

Pioreactor Automations

Goal

Help Codex implement Pioreactor automations that match the existing dosing, temperature, and LED job architecture, choose the correct trigger model, and preserve runtime safety.

Families

• Automations are split into 3 families: dosing, temperature, led under core/pioreactor/automations/.
• Each family is powered by a background job base class:
  • core/pioreactor/background_jobs/dosing_automation.py
  • core/pioreactor/background_jobs/temperature_automation.py
  • core/pioreactor/background_jobs/led_automation.py
• Shared automation execution helpers live in core/pioreactor/automations/base.py.

Config.ini sections

Use section name [<type>_automation.<automation_name>]. Example:

[dosing_automation.turbidostat]
[dosing_automation.pid_morbidostat]
[temperature_automation.thermostat]

UI yaml

Automation chooser descriptors

Path: .pioreactor/ui/automations/<type>/*.yaml Served by: /api/automations/descriptors/<automation_type> in core/pioreactor/web/api.py Schema: AutomationDescriptor in core/pioreactor/structs.py Fields: - display_name - automation_name - description - fields[] where each field has key/default/label/type/unit/disabled/options

• automation_name in Python class must match YAML automation_name.
• UI fields[].key should correspond to constructor args and/or published settings.
• Runtime mutability is governed by published_settings[...]["settable"], not by YAML alone.
• Do not add skip_first_run as a global UI field. If an automation needs it, expose it as an explicit field for that automation.

Execution strategies

Pick the strategy that matches the automation's real trigger. Do not force event-like automations into a duration loop.

Periodic automations

Use self.run_every(duration, skip_first_run=...) in __init__ when the automation should run at a fixed cadence.

• execute() contains one automation decision/action.
• run_every() starts a RepeatedTimer after the job reaches its post-init phase.
• set_duration() reschedules the next periodic run based on _latest_run_at.
• Example shape: chemostat-style dosing, where each cycle exchanges a fixed volume.

Event-triggered automations

Use passive MQTT listeners plus self.trigger_run_once_from_event() when the automation should react to fresh data.

• Let the base listener update cached values first, then trigger.
• Ignore retained MQTT messages for control decisions.
• Gate startup with a simple readiness flag if callbacks can arrive before constructor-specific fields are initialized.
• trigger_run_once_from_event() is non-overlapping. If an event arrives while execute() is running, it records one pending follow-up run.
• Example shape: turbidostat dosing reacts to selected biomass signal updates.

Boundary-scheduled automations

Use a one-shot timer when the next useful run is a calculable boundary, not a fixed polling interval.

• Keep execute() as the current-state application.
• After applying state, schedule the next boundary.
• On setting changes, apply current state and reschedule.
• On sleeping/disconnected, cancel the active boundary timer.
• If assigning _automation_strategy_start_callback, the callback must be Callable[[], None]. Wrap methods that return AutomationEvent | None in a no-return callback.
• Example shape: light/dark LED cycle schedules the next light/dark phase transition.

Shared execution rules

• Prefer run_once() over calling execute() directly. It handles READY gating, non-overlap, event logging, latest_event, and common exception handling.
• execute() should return an AutomationEvent or None.
• Use wait_for_ready=False only when the caller already knows the job is ready or is running from a controlled state transition.
• Avoid defensive compatibility shims for old automation APIs unless there is a current caller in this repo.
• Keep automation callbacks and timers explicitly cancellable in on_sleeping() / on_disconnected().

Subclassing existing automations

• Try to run super().__init__(...) immediately in the new __init__.
• Initialize any fields used by MQTT callbacks before they can be observed, or use a small readiness flag.
• Constructor args should accept float | str / int | str for UI and CLI inputs, then coerce once in __init__ or setters.
• Published setting setters should apply live state changes when possible. Example: changing LED intensity while lights are active should update LEDs immediately.

Dosing shutdown safety

• DosingAutomationJob.on_disconnected() must stop active pump jobs before waiting for automation timers to finish.
• _continue_pumping_event is cooperative: it prevents the next subdose, but does not interrupt a currently running pump action by itself.
• Shutdown order should be: set the cooperative stop event, publish stop messages to active pump jobs, then call shared timer cleanup.