---
name: home-automation
description: 'Control and query home-automation devices on the LAN -- starting with Roku''s ECP remote-control API. Tools: hue-lights, hue-set, roku-apps, roku-launch, roku-play, roku-press, roku-status, roku-type. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: Requires fragletc and Docker. Network access required.
metadata:
  tags: internet
  tools: hue-lights.py, hue-set.py, roku-apps.py, roku-launch.py, roku-play.py, roku-press.py, roku-status.py, roku-type.py
---

# Home Automation

Control and query home-automation devices on the LAN -- starting with Roku's ECP remote-control API.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/hue-lights.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `hue-lights.py`

List the lights on a Philips Hue bridge via its local v1 API -- one "id\tname\ton\tbri%\treachable\thex" line per light. hex is the bulb's color as #rrggbb at full brightness (brightness stays in its own column), or "-" when the bulb has no color. hs mode is the inverse of hue-set's hex encoding, so a hex this prints can be sent back.

Use when the user asks what lights exist, their names/ids, or whether a light is on, reachable, at what brightness, and what color.

```sh
<skill-dir>/hue-lights.py -p ip="<ip>"
```

Parameters:
- `ip` (string, required) — LAN IP address of the Hue bridge, e.g. 192.168.0.245
- `HUE_USER` (secret, required) — read from the caller's environment, never passed with `-p`; Hue API username from link-button pairing (export HUE_USER on the agent host; delivered as a file, never a param, so it stays out of chat and the ledger)

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `hue-set.py`

Set a Philips Hue light (or all lights) via the bridge's local v1 API -- on/off/toggle, brightness percent, white temperature (kelvin or mired), color by hue degrees + saturation percent or by hex (e.g. hex=#ff8000). Light by numeric id or by name (exact then substring match, like home-automation/roku-launch.py); id=all drives group 0. Pairs with home-automation/hue-lights.py for discovery.

Use when the user asks to turn a light on or off, dim/brighten, or change its color or warmth -- e.g. "turn off the kitchen", "dim living room to 30", "warm the bedroom".

```sh
<skill-dir>/hue-set.py -p ip="<ip>" -p id="<id>" [-p on="<on>"] [-p bri="<bri>"] [-p temp="<temp>"] [-p ct="<ct>"] [-p hue="<hue>"] [-p sat="<sat>"] [-p hex="<hex>"] [-p transition="<transition>"] [-p name="<name>"] [-p delete="<delete>"]
```

Parameters:
- `ip` (string, required) — LAN IP address of the Hue bridge, e.g. 192.168.0.245
- `id` (string, required) — Numeric light id, light name (e.g. "kitchen"), or "all" for every light
- `on` (string, optional) — on, off, or toggle (toggle reads current state first; for "all", any-on means all-off)
- `bri` (string, optional) — Brightness 0-100 percent (0 turns the light off)
- `temp` (string, optional) — White point in kelvin, e.g. 2700 warm / 4000 neutral / 6500 daylight (mutually exclusive with ct)
- `ct` (string, optional) — White point in mired, 153-500 (Hue-native; mutually exclusive with temp)
- `hue` (string, optional) — Color hue in degrees 0-360 (needs a color-capable bulb)
- `sat` (string, optional) — Color saturation 0-100 percent (pairs with hue)
- `hex` (string, optional) — Hex color like #ff8000 or ff8000 (3 or 6 digits, # optional); shorthand for hue+sat, mutually exclusive with them
- `transition` (string, optional) — Fade time in seconds (Hue transitiontime is deciseconds; default bridge 0.4s)
- `name` (string, optional) — New name for the light on the bridge (e.g. name="Living room"; id=all refused)
- `delete` (string, optional) — Set true to DELETE this light from the bridge (numeric id only -- names and all refused; irreversible)
- `HUE_USER` (secret, required) — read from the caller's environment, never passed with `-p`; Hue API username from link-button pairing (export HUE_USER on the agent host; delivered as a file, never a param, so it stays out of chat and the ledger)

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `roku-apps.py`

List the apps installed on a Roku device via its ECP API -- one "id\tname\tversion" line per app, so a caller can find an app's numeric id for home-automation/roku-launch.py.

Use when the user asks what apps or channels are installed on a Roku, or needs an app's numeric id before launching it.

```sh
<skill-dir>/roku-apps.py -p ip="<ip>"
```

Parameters:
- `ip` (string, required) — LAN IP address of the Roku, e.g. 192.168.0.73

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `roku-launch.py`

Launch an app on a Roku device via its ECP API, optionally deep-linking straight into a piece of content when the app supports it (e.g. a Netflix title id) -- pairs with home-automation/roku-apps.py for the app_id.

Use when the user asks to open an app or channel on a Roku, or to jump straight to a specific show or movie inside one via a deep link.

```sh
<skill-dir>/roku-launch.py -p ip="<ip>" -p app_id="<app_id>" [-p content_id="<content_id>"] [-p media_type="<media_type>"]
```

Parameters:
- `ip` (string, required) — LAN IP address of the Roku, e.g. 192.168.0.73
- `app_id` (string, required) — App name (e.g. Netflix, YouTube) or numeric app id from home-automation/roku-apps.py
- `content_id` (string, optional) — App-specific content id to deep-link to (e.g. a Netflix title id from its netflix.com/title/<id> URL)
- `media_type` (string, optional) — Content type for the deep link, e.g. movie, series, episode

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `roku-play.py`

Search Roku's on-device universal search for a title and play the Nth result -- Home to a known state, opens Search, types the query via Lit_ keys, arrows Right into the results grid, opens the chosen result, and presses Select to clear provider-choice/profile screens. NOTE: Roku sunset the /search/browse ECP endpoint in OS 12.0, so this deliberately drives the on-screen keyboard instead; and keypress/Enter is a documented no-op on the OS 15 search screen (focus stays parked on "A", so Select-after-Enter types a stray "a") -- do NOT re-add either. Live-verified 2026-10-03 on Roku Ultra OS 15.3.4 (Home, Down x6 to Search, type, Right x6 to result 1, Select opens result, Select picks provider -> playback); result_index beyond 1 extrapolates one more Right per position and is untested. Timing is fixed-delay and can be thrown off by slow app intro animations -- if playback doesn't start, a manual follow-up home-automation/roku-press.py -p key=Select is the fix, same as a human would do.

Use when the user names a show or movie to play on a Roku without saying which app -- e.g. "play Seinfeld" -- and wants Roku's own cross-provider search used to find and start it, rather than a specific app's deep link.

```sh
<skill-dir>/roku-play.py -p ip="<ip>" -p query="<query>" [-p result_index=1] [-p confirm_selects=1]
```

Parameters:
- `ip` (string, required) — LAN IP address of the Roku, e.g. 192.168.0.73
- `query` (string, required) — Text to search for, e.g. "stargate atlantis"
- `result_index` (string, optional, default `1`) — Which result to open, counting from 1 (left to right in the results row). Only result_index=1 has been verified live; higher values extrapolate.
- `confirm_selects` (string, optional, default `1`) — How many times to press Select after opening the result, to clear a provider-choice and/or profile-picker screen. Some apps need a second Select that a slow intro animation can cause to land too early -- if it doesn't stick, send one more home-automation/roku-press.py -p key=Select by hand.

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `roku-press.py`

Send one or more remote-control key presses to a Roku device over its ECP API (no auth, LAN only) -- the same buttons as the physical remote: navigation, Select, Home, Back, playback, volume, channel. Pass a comma-separated list (e.g. "Down,Down,Down,Select") to send a whole sequence in one call instead of one fraglet run per key.

Use when the user asks to control a Roku -- press a remote button or a sequence of buttons, navigate menus, play/pause, change volume or channel, or go Home -- by its LAN IP address.

```sh
<skill-dir>/roku-press.py -p ip="<ip>" -p key="<key>"
```

Parameters:
- `ip` (string, required) — LAN IP address of the Roku, e.g. 192.168.0.73
- `key` (string, required) — One ECP key name, or a comma-separated sequence, e.g. "Down,Down,Down,Select". Keys: Home, Back, Select, Up, Down, Left, Right, Play, Rev, Fwd, InstantReplay, Info, Search, Enter, Backspace, VolumeUp, VolumeDown, VolumeMute, PowerOff, ChannelUp, ChannelDown

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `roku-status.py`

Ask a Roku what it is doing right now via ECP queries -- the foreground app (query/active-app) plus player state/position/duration when the app reports them (query/media-player). Read-only: touches nothing on screen, safe to run mid-playback.

Use when the user asks what is playing, which app is open, or how far into something the Roku is -- or before a relaunch/resume, to record the app (and position, when available) to go back to.

```sh
<skill-dir>/roku-status.py -p ip="<ip>"
```

Parameters:
- `ip` (string, required) — LAN IP address of the Roku, e.g. 192.168.0.73

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `roku-type.py`

Type free text into a Roku device's currently focused on-screen keyboard field (e.g. a search box) over its ECP API -- sends one keypress/Lit_<char> per character in a single call, instead of one fraglet run per letter. Pairs with home-automation/roku-press.py to navigate to the field first.

Use when the user asks to type a search query or other text into whatever on-screen text field is currently focused on a Roku.

```sh
<skill-dir>/roku-type.py -p ip="<ip>" -p text="<text>"
```

Parameters:
- `ip` (string, required) — LAN IP address of the Roku, e.g. 192.168.0.73
- `text` (string, required) — Text to type into the currently focused on-screen field, e.g. "stargate atlantis"

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.
