Program YAML Scripts

Program YAML is an authoring format for HOS scenes and automations. It is intended for Developer Tools, AI-assisted setup, and advanced users who want to write readable program steps without hand-editing the canonical script JSON.

YAML is not a separate runtime. HOS compiles YAML into the existing program script node array before saving and executing the program.

---

Where to Use It

In HOS:

1. Open Integration Manager.
2. Open Developer Tools.
3. Choose Program YAML Builder.
4. Write or paste YAML.
5. Use Validate to preview the compiled script nodes.
6. Use Save Disabled for a new review-only program, or Update Existing to replace a program script.

The same payload shape is also accepted by program write APIs through programYaml or scriptYaml.

---

Minimal Script

script:
  - action:
      deviceId: light_1
      action: turn_on
      params:
        brightness: 40
  - delay: 1s

This compiles into two script nodes:

• an action node for light_1
• a delay node for 1000 ms

---

Full Program Document

Use a full document when you want YAML to carry program metadata as well as steps.

name: Evening Lights
description: Dim living room lights for evening mode
enabled: false
trigger:
  type: manual
script:
  - action:
      deviceId: light_1
      action: turn_on
      params:
        brightness: 35
  - delay: 2s
  - action:
      deviceId: light_2
      action: turn_on
      params:
        brightness: 20

Supported top-level fields:

Field	Type	Notes
name	string	Program name
description	string	Optional description
enabled	boolean	Use false for review-only drafts
favorite	boolean	Optional home/favorite metadata
showOnHome	boolean	Optional home visibility metadata
trigger	object	Program trigger, defaults to manual when omitted in the Developer Tools save flow
timer	object	Optional timer configuration
sceneProfile	object	Optional scene metadata
script or steps	array	Required executable steps

---

Action Nodes

Action nodes send commands to logical devices.

script:
  - action:
      deviceId: media_room_tv
      action: turn_on
  - action:
      deviceId: receiver_1
      action: set_input
      params:
        input: HDMI1

Shortcut form:

steps:
  - deviceId: media_room_tv
    command: turn_on
  - deviceId: receiver_1
    command: set_volume
    params:
      volume: 35

Action fields:

Field	Notes
deviceId	Logical device ID
action or command	Command key to dispatch
entityId	Optional entity-scoped target
entityAction	Optional entity action
params	Object or JSON string. Objects are serialized before execution.

---

Delay Nodes

Delays pause the program before the next node.

script:
  - delay: 500ms
  - delay: 2s
  - delay: 1m
  - delay:
      seconds: 3

Supported units:

Unit	Meaning
ms	milliseconds
s, sec, second, seconds	seconds
m, min, minute, minutes	minutes

---

If / Else Nodes

Use if nodes to branch on event, state, or system context.

script:
  - if:
      field: system.isNight
      operator: eq
      value: true
    then:
      - deviceId: hallway_light
        command: turn_on
    else:
      - stop: true

Condition fields:

Field	Notes
field	Dot path such as state.power, data.input, or system.hour
operator	eq, neq, contains, gt, gte, lt, lte, or exists
value	Comparison value, omitted for exists

---

Stop Nodes

Stop nodes end the current program branch.

script:
  - stop: true

---

Triggers

Manual trigger:

trigger:
  type: manual

Driver event trigger:

trigger:
  type: driver_event
  event: ACTION_REQUESTED
  field: data.action
  operator: eq
  value: PLAY

State update trigger:

trigger:
  type: state_update
  deviceId: sensor_1
  field: motion
  operator: changed
  value: true

When writing YAML through Developer Tools, prefer saving new automations disabled first, then review and enable them after testing.

---

API Usage

Create or update a program with a full YAML document:

POST /os/programs/save
Content-Type: application/x-www-form-urlencoded

programYaml=<yaml document>

Validate YAML without saving:

POST /os/programs/yaml/validate
Content-Type: application/x-www-form-urlencoded

programYaml=<yaml document>

The mobile/OS API program save surfaces also accept:

{
  "name": "Evening Lights",
  "programYaml": "name: Evening Lights\nscript:\n  - deviceId: light_1\n    command: turn_on"
}

Use scriptYaml when only the executable steps should come from YAML and metadata is supplied separately.

---

Safety Notes

• YAML saves compile into the existing script node array before persistence.
• Existing Fleet cloud flows and legacy integration routes are not changed by YAML authoring.
• Save new YAML-authored programs disabled until the commands and targets are reviewed.
• Device IDs and command keys must match the logical devices and command catalog available in the running HOS instance.