homectl

Local-first home automation control: one Rust CLI that unifies device control (Kasa/Tapo bulbs and plugs, LG WebOS TVs, cmdd-managed displays), a self-hosted web UI, a household inventory database, scene automation, and a video-driven "ambient lighting" engine.

homectl is designed for people who want their smart home to keep working when the internet is gone: device talks are direct on the LAN, state lives in a local SQLite database, and nothing is required to run in the cloud.

Features

• Direct LAN device control — Kasa legacy (TCP 9999, XOR) and the newer TP-Link TPAP scheme (HTTP, SPAKE2+ authenticated, AES-CCM) are both supported, with automatic detection and fallback per device.
• Household model — houses, spaces, items, placements, and devices in a versioned SQLite schema; seed it from a single household.json config.
• Scenes — declarative selector-based scene actions (by space, zone, kind, role, integration) dispatched to bulbs, plugs, TVs, and cmdd-managed displays.
• Dance (ambient lighting) — stream a video source through ffmpeg, extract HSV per frame, and drive bulbs in real time with per-scene smoothing, floors, and auto-stop behavior.
• Web UI — a built-in HTTP server with a floorplan view, device controls, scenes, and SSE live updates. No external services.
• Wi-Fi onboarding — provision Kasa devices over their setup AP from the command line (legacy and TPAP firmware).
• Scriptable — JSON/raw output modes, shell completions, and a typed SDK crate (home-sdk) for embedding.

Installation

# Installs homectl into ~/.cargo/bin
cargo install --path apps/homectl

# Or build locally:
cargo build --release
# Binary is at target/release/homectl

Build requirements: a stable Rust toolchain (see rust-version in Cargo.toml) and pkg-config. On Linux the SDL2 development headers (libsdl2-dev) are needed for the display subcommand, and the onboarding/tui/wheel features pull their own adapter crates. For a minimal build without those (no SDL2, no Linux Wi-Fi stack):

cargo install --path apps/homectl --no-default-features

ffmpeg is needed only for the sync/dance video pipeline.

Quickstart

# 1. Describe your home once in a household config (see examples/):
cp examples/household.example.json ~/.config/homectl/household.json

# 2. Seed the local database from that config:
homectl db seed

# 3. Control a device:
homectl device list
homectl device on example-plug-0
homectl bulb --hue 200 --sat 80 --val 60 192.0.2.11

# 4. Apply a scene:
homectl scene apply example-on

# 5. Serve the web UI:
homectl serve --port 8085
# Optional hardening: require a shared token and restrict CORS origins:
# homectl serve --auth-token "$(openssl rand -hex 16)" --cors-origin http://host-a:8085

Command overview

Command	Purpose
status, tui	Live status overview / interactive terminal dashboard
room, space, item, house	Household inventory CRUD with placement history
db	Database init, migrate, backup, doctor, seed
iot	Low-level inventory of endpoints, devices, profiles, capabilities
report, task, calibrate	Reports, task blueprints, read-only device probes
scene, dance	Scene application/planning and dance lifecycle
invoke	Capability invocation by selector (--space --zone --capability …)
device	Discover, inspect, control, verify, onboard individual devices
pair	Scan/provision Wi-Fi setup APs through a registered onboarding host
sync, bulb, wheel	Video-to-light sync engine, one-shot bulb control, color picker
plug, lgtv, display	Direct plug, WebOS TV, and test-signal control
floorplan	Floorplan import, validation, and rendering
serve	Built-in web UI + HTTP API
completions, test	Shell completions and internal self-tests

Run homectl --help (or homectl <command> --help) for the full, current list.

Configuration

Everything household-specific lives outside the repository, in ~/.config/homectl/:

• household.json — the single source of truth for your house: spaces, devices (addresses, capabilities, zones), execution endpoints, and scenes. See examples/household.example.json for the schema, and homectl db seed to apply it.
• floorplan.json — optional room polygons and device placements for the floorplan UI. See examples/floorplan.example.json.
• Dance scenes are supervised by cmdd: every scene with a dance block gets one cmdd service named exactly after the scene id (a dance-tv-office service runs homectl scene run dance-tv-office). Register matching services on your cmdd host to enable toggling from the CLI, TUI, and web UI; config/cmdd.example.toml shows the pattern.

XDG paths and precedence rules are documented in docs/xdg.md.

Architecture

Crate	Responsibility
home-core	Shared types: HSV, temperature ladders, group-brightness planning
home-db	SQLite schema, migrations, household records, floorplan geometry
home-device-kasa	Kasa legacy/TPAP transports, discovery, plug control, connection pool, Wi-Fi provisioning
home-device-cmdd	HTTP client for cmdd command servers
home-device-lgtv	LG WebOS WebSocket control and Wake-on-LAN
home-scene	ffmpeg capture and HSV analysis for the ambient-lighting engine
home-onboarding	Linux Wi-Fi association helpers (nl80211/rtnetlink)
home-display	SDL2 fullscreen test signal
home-sdk	Typed local/remote client used by the TUI and external tools
home-ui-tui	ratatui terminal dashboard
home-ui-wheel	ratatui color wheel
apps/homectl	The homectl binary: CLI, household engine, web server, dance controller

Documentation

• docs/bulbs.md — Kasa bulb protocol deep dive
• docs/plugs.md — Kasa plug protocol
• docs/lgtv.md — WebOS control protocol
• docs/invoke.md — selector-based invocation semantics
• docs/cli-output.md — output modes and scripting contract
• docs/device-calibration.md — read-only device probing
• TUTORIAL.md — guided tour of the database and inventory model

Development

cargo fmt --all            # formatting (CI enforces --check)
cargo clippy --workspace   # lints (CI runs with -D warnings)
cargo test --workspace     # 170+ unit tests; live-hardware tests are #[ignore]
./scripts/coverage.sh      # line-coverage ratchet (cargo-llvm-cov)

Tests are hermetic: they seed the synthetic fixtures in examples/ and never touch a machine's real ~/.config/homectl or local network.

License

AGPL-3.0-or-later — see LICENSE.