Pioreactor Automations

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.