HA Synthetic Sensors

A Python package for creating formula-based synthetic sensors in Home Assistant integrations using YAML configuration and mathematical expressions.

What it does

Synthetic sensors are sensor extensions that provide capabilities beyond the base sensors or create new sensors with formula-based calculations. They provide a new state value by applying mathematical formulas to other entities, allowing you to:

• Extend sensor capabilities with calculated attributes
• Transform sensor values using mathematical formulations
• Combine multiple sensors into derived metrics
• Add computed states without modifying original sensors
• Add computed attributes that evaluate based on the main sensor state or other entities

Key Features

• Sensor Definition and Modification: Without code modification change the sensor or attribute state with YAML
• Bulk Load/Modify and Per-Sensor CRUD: Load complete sensor sets or make granular changes
• Rich Formula Based States: Formulas with natural syntax and powerful evaluation and collection patterns
• Variable reuse: Define variables globally or per sensor and use those variables in formulas or attributes
• Dot notation: Easy access to entity attributes in formulas
• Automatic Entity-ID Tracking: Updates the definitions based on external HA entity renaming
• Type safety: Complete TypedDict interfaces for better IDE support and validation
• Storage-first architecture: Runtime configuration changes without file modifications
• Built for Performance: AST caching and evaluation of formulas and bulk modification event storm avoidance
• Cross-Attribute References: Formulas can reference other attributes with proper evaluation order
• Dependency Validation: Automatic detection of circular dependencies and variable conflicts

Installation

Install the package using pip:

pip install ha-synthetic-sensors

For development setup:

git clone https://github.com/LegoTypes/ha-synthetic-sensors
git clone https://github.com/LegoTypes/ha-synthetic-sensors
cd ha-synthetic-sensors
poetry install --with dev
./setup-hooks.sh

Quick Start

Here's a simple example of how to create synthetic sensors:

version: "1.0"

sensors:
  energy_cost_current:
    name: "Current Energy Cost"
    formula: "current_power * electricity_rate / conversion_factor"
    variables:
      current_power: "sensor.span_panel_instantaneous_power"
      electricity_rate: "input_number.electricity_rate_cents_kwh"
      conversion_factor: 1000
    metadata:
      unit_of_measurement: "¢/h"
      state_class: "total"
      device_class: "monetary"
      icon: "mdi:currency-usd"

  energy_cost_analysis:
    name: "Energy Cost Analysis"
    formula: "current_power * electricity_rate / 1000"
    attributes:
      daily_projected:
        formula: "state * 24"
        metadata:
          unit_of_measurement: "¢"
          suggested_display_precision: 2
      monthly_projected:
        formula: "state * 24 * 30"
        metadata:
          unit_of_measurement: "¢"
          suggested_display_precision: 2
    variables:
      current_power: "sensor.span_panel_instantaneous_power"
      electricity_rate: "input_number.electricity_rate_cents_kwh"
    metadata:
      unit_of_measurement: "¢/h"
      device_class: "monetary"
      state_class: "total"

Major Components

• StorageManager - Manages sensor set storage and configuration
• SensorSet - Handle for individual sensor set operations
• FormulaConfig/SensorConfig - Configuration classes for sensors and formulas
• DataProviderResult - Type definition for data provider callbacks
• SyntheticSensorsIntegration - Main integration class for standalone use

Home Assistant services

# Reload configuration
service: synthetic_sensors.reload_config

# Get sensor information
service: synthetic_sensors.get_sensor_info
data:
  entity_id: "sensor.span_panel_main_energy_cost_analysis"

# Update sensor configuration
service: synthetic_sensors.update_sensor
data:
  entity_id: "sensor.span_panel_main_energy_cost_analysis"
  formula: "updated_formula"

# Test formula evaluation
service: synthetic_sensors.evaluate_formula
data:
  formula: "A + B * 2"
  context: { A: 10, B: 5 }

Syntax Documentation

For detailed syntax examples and advanced usage patterns, see the Cookbook.

Integration Documentation

For detailed implementation examples, API documentation, and integration patterns, see the Integration Guide.