Pylon Home Control (PHC)

Pylon Home Control (PHC) is a small, YAML-configured home automation framework. It polls and controls a tree of pluggable devices (weather stations, sun position, virtual/test devices, and anything you add), and runs tasks — condition- or time-driven automations — against their state, all on a fixed-heartbeat scheduler.

Documentation

• User guide — docs/: concepts, configuration reference (!include, module/ parameter scoping, logging, time/duration syntax), endpoint and device profiles, conditions, scripted actions & sticky values, and one page per extension/integration: random light control, mail alerts, log database, recovery, web UI, debug portal, and the Razberry/zWay Z-Wave integration. See also installing PHC on a Raspberry Pi.
• Developer guide — docs/developer/: writing a device module, plus internals for zway, the web UI, and the debug portal.

Concepts

• Device — a node in a tree that exposes zero or more endpoints (readable/writable state) and may have child devices, backed by a plugin module declared in a system YAML file.
• Module — a device plugin: a devices/<name>/device.py (the Device subclass) plus a devices/<name>/module.yaml describing its parameters and endpoints declaratively. Modules are discovered automatically at startup.
• Task — an automation triggered either by a schedule (time/repeat) or by a device endpoint changing (condition), performing one or more actions (set, toggle, log, create_task, kill_task, script, ...).
• Scheduler — drives each device's fetch on its own interval and evaluates tasks once per heartbeat tick, running device I/O concurrently.

See docs/concepts.md for the full picture (including endpoint types/units/formatting), examples/ for complete system configurations, and the module.yaml file in each devices/ subfolder for what parameters/endpoints a given device module supports. extensions/ is the home for non-device PHC extensions, following the same package-plus-descriptor pattern as device modules.

Requirements

• Python >= 3.11
• Dependencies: PyYAML, aiohttp, astral, Jinja2 (see pyproject.toml)

Install

pip install -e .

For running the test suite, install the dev extra instead:

pip install -e ".[dev]"

Usage

Run PHC against one of the example systems:

phc --config examples/virtual_system.yaml

(pip install -e . installs the phc console command; python phc.py --config ... works the same way when run from the repo root without installing.)

Useful flags:

• --log-level LEVEL — default logging level (DEBUG, INFO, WARNING, ERROR); applies to every stream (stdout/stderr) destination in log:, never a file destination — see Logging.
• --log-level-module NAME=LEVEL — override the level of one logger (e.g. scheduler=DEBUG) on every stream destination; repeatable.

Stop with Ctrl+C (SIGINT) or SIGTERM for a graceful shutdown.

Tests

pytest

Contributing

See CONTRIBUTING.md for the development workflow, and CHANGELOG.md for release history.

License

MIT — see LICENSE.