An Autonomous Agent consists of a directory with a file machine.yaml and an optional set of support scripts and more.
In the concepts section we described a theoretical HVAC management agent, lets look how that might look as a machine.
Lets try to solve the HVAC problem from our concepts page, to recap we want to have a file lets say hvac.json that describes in it thresholds for air quality that you read from sensors in the room. Could be humidity, temperature, co2 levels, whatever you decide. Based on these configured thresholds and the input from your sensors you want to turn the HVAC on and off.
Reasoning about this we determine we have 3 possible states:
Lets think about the transitions, this is what triggers the HVAC to go off and on and so forth:
Lets think about the watchers, this is monitors you need to run to inform the system when to fire transitions:
Machines are stored in directories, the example below would be stored like this:
hvac ├── machine.yaml ├── hvac.json ├── monitor.sh ├── off.sh └── on.sh
When you use scripts in exec watchers or reference files in file watchers the paths are relative to your machine.yaml. At present the only requirement is that a machine.yaml exist in the directory the rest are optional.
The manifest here describe the machine we designed above, the splay_start item is optional, everything else is required.
A JSON schema describes these files and you can configure some editors to validate the YAML file based on that. The command
choria machine validate can validate a machine.yaml against this schema.
The scripts called are not shown here, they simply have to exit 0 on success or 1 on failure, everything else is ignored.
name: HVAC # Must be SemVer format version: "1.0.0" # The state the machine starts in initial_state: unknown # Will wait a random period up to this many seconds before starting, defaults to 0 splay_start: 30 # Creates all the valid transitions this machine can receive, we do # not specifically need to list all the states as they are inferred # from the "from" and "destination" lines transitions: - name: variables_unknown from: [unknown, idle, running] destination: unknown - name: variables_changed from: [unknown, idle, running] destination: idle - name: air_good from: [idle, running] destination: idle - name: air_bad from: [idle, running] destination: running watchers: # checks the hvac.json exist and if its changed, on change # success_transition is fired, if the file is missing # fail_transition is fired. - name: variables type: file state_match: [unknown, idle, running] fail_transition: variables_unknown success_transition: variables_changed interval: "5s" properties: path: hvac.json # turns the HVAC off, no special handling for failures - it would # stay in the state it was and keep retrying - on success it moves # the machine to idle - name: off type: exec state_match: [unknown, idle] success_transition: idle interval: "5m" properties: command: off.sh # turns the HVAC on, this is only valid in the running state and # it runs regularly to keep the HVAC on in case someone fiddles # with the switch - name: on type: exec state_match: [running] interval: "5m" properties: command: on.sh # monitors the air, exits with 0 if the air is good and 1 if its bad - name: monitor type: exec state_match: [idle, running] success_transition: air_good fail_transition: air_bad interval: "1m" properties: command: monitor.sh
You can validate the machine.yaml by running choria machine validate hvac where hvac is the directory with your machine.
The graph below can be generated using the choria machine graph hvac/ command based on the previous layout.
You can use this to verify the structure of your machine and what transitions are supported etc, it’s in the Graphviz dot format and can be viewed using many online or offline viewers.
You can run the machine locally on your desktop during testing using the choria machine run hvac command, where hvac is a directory that matches the above layout.
Machines are hosted within your Choria Server and are read from disk. There isn’t much to configure:
plugin.choria.machine.store = /etc/choria/machines
On start every machine found in directories there will be started and hosted forever, they will log and publish events to the middleware. Machines with splay_start set as in the example above will sleep randomly up to this many seconds before starting, if you are running for example a cron style job on a large estate this can assist with spreading the load.
Updates to this directory will be detected, machines stopped and reloaded from disk on demand without restarting the Choria Server.