HAConfig-as-PyCode

HAConfig-as-PyCode is an event-driven, programmatic Home Assistant configuration project that utilizes Python for improved reusability, encapsulation, and modular expandability. The project employs a hybrid approach, combining declarative data structures for entity description with imperative logic for event-driven processing, offering an alternative to Home Assistant's default YAML-based declaration.

Implementation

The core functionality of HAConfig-as-PyCode is built around an event-driven architecture, integrating Python scripts with PyScript and Home Assistant's built-in automation capabilities. The architecture leverages an MQTT broker for event-driven communication to ensure scalability and efficiency.

Main Home Automation

• auto_entities.py: Defines entity behavior based on deviating states and their correlated condition-based actions, utilizing the AUTO_ENTITIES data structure for entity-state mapping.
• auto_motion.py: Manages motion sensor-based automations, mapping sensors to actions through the AUTO_MOTION_ENTITIES data structure.
• auto_notify.py: Handles notifications to external devices, e.g., mobile, employing the notify_immo function to parse and deliver housing offers from various Berlin housing associations.
• config_control.py: Defines controller behavior and maps it to scenes and actions using the CONFIG_CONTROL data structure.

Home Automation Capabilities

For integration purposes:

• ha_helper.py: Provides helper functions for interaction with Home Assistant resources, focusing on system logging.
• ha_system.py: Handles system-related setup, configuration management tasks, and system monitoring.
• ha_utils.py: Contains utility functions, e.g., mobile notifications and triggers for mobile event-based shortcuts.

For functionality purposes:

• script_air_cleaner.py: Implements automatic air purification control based on pollen concentration, with scheduling according to various thresholds.
• script_off.py: Provides functionality to turn off all types of integrated entities, either individually or by domain.

For service-based purposes:

• services.py: Implements a service factory that generates periodically executed services based on provided cron expressions, e.g., filebackup.sh for automated backup of Home Assistant configuration and data.
• sync_git.py: Enables automatic synchronization of the configuration to this Git repository.

Modules

The /pyscript/modules directory contains reusable Python modules that encapsulate various functionalities used throughout the project, independent of Home Assistant capabilities.

• constants.py

  • config.py: Centralizes configuration settings used across the project, promoting code organization and maintainability.
  • devices.py: Manages device-specific configurations and mappings.
  • entities.py: Describes the default desired state for entities and conditions for default behavior, such as timeouts.
  • events.py: Defines event constants used throughout the project.
  • expressions.py: Contains expressions for various automation scenarios.
  • mappings.py: Provides naming and mappings to entities and device capabilities.
  • settings.py: Contains settings or configuration values specific to application and service logic.

• utils.py: Contains central functions for generating expressions and implements project-wide logging functions

Native Python

Native Python is used within this project to handle privileged and I/O tasks that could potentially interfere with PyScript's main loop handling of asynchronous tasks.

• filesystem.py: Provides file system operations for tasks that require privileges beyond the PyScript sandbox.
• logfile.py: Manages structured logging operations, differentiating between a file logger for application or service logs and a debug logger for debugging purposes, implemented using a singleton pattern for project-wide accessibility.

Customization

• User Interface: The project includes various custom templates for the Home Assistant Lovelace UI. These are implemented through the templates/ directory and external data integration.

  • templates/badges.yaml: Defines badge cards for displaying system status, backup information, air quality, and providing quick access to common actions like turning everything off.
  • templates/bar.yaml: Implements customizable button bars for room-specific lighting and device control.
  • templates/calendar.yaml: Includes a customized calendar view for displaying upcoming events from various calendars.
  • templates/card-art.yaml: Provides a comprehensive overview card with weather information, badges, and a calendar view.
  • templates/card.yaml: Defines room-specific overview cards with dynamic images, thermostat controls, and button bars.
  • templates/clima.yaml: Implements a custom thermostat card with temperature graphs and trend indicators.
  • templates/weather.yaml: Includes a weather forecast card and a custom weather display.

• Backup and Synchronization: Automated backup and synchronization of the Home Assistant configuration and data.

• External Data: The project integrates external data from various sources through sensors defined in the config/.sensors/ directory:

  • Housing Offers: Scrapes and delivers housing offers and real estate listings from various companies in Berlin. The data is delivered via notifications to trigger mobile services.

• Customized Shell: The project includes a customized shell environment with an optimized configuration for the Zsh shell, located in files/.zshrc.