Create a routine

A routine runs on the Hub without a model. Triggers set when the routine runs, steps set what the routine does, and every step's change goes through the Safety Kernel.

Start the hub

$ uv run openhal init
$ uv run openhal file confirm ~/.openhal/devices/plant-waterer.hal.yaml
$ uv run openhal start &
$ uv run openhal read plant-waterer.soil_moisture

Describe the routine

This routine checks the soil every hour and waters the plant for 20 seconds when the soil is dry.

id: morning-water
triggers:
  - every: 1 h
steps:
  - if: "plant-waterer.soil_moisture < 35 %"
    then:
      - action: { device: plant-waterer, action: water, args: { duration: 20 s } }

Store and dry run the routine

A new routine starts disabled. A dry run checks every command in every branch against the current state and sends nothing.

$ uv run openhal routine new morning-water --file morning-water.yaml
stored morning-water, disabled.
$ uv run openhal routine dry-run morning-water
dry run passes
  1. allowed  Allowed.

Enable the routine

A person enables the routine with the human token and the typed phrase enable, after the hub repeats the dry run.

$ uv run openhal routine enable morning-water
enabled  morning-water

A routine the kernel blocks

A step outside the limits fails the dry run, so the routine can't be enabled.

id: long-soak
triggers:
  - every: 1 h
steps:
  - action: { device: plant-waterer, action: water, args: { duration: 120 s } }

$ uv run openhal routine new long-soak --file long-soak.yaml
$ uv run openhal routine dry-run long-soak
blocked above_max  Blocked. The duration limit is 30 s (max). Requested 120 s.

The file also caps the pump at 3 runs per hour, routine runs included. hal/routines/dryRun returns the same results over the protocol. The routines section of the specification defines triggers, steps and approvals for high hazard devices.