appdaemon-lighting 0.2.0
Composable lighting building blocks for AppDaemon + Home Assistant
Requires Python: >=3.12
Keywords: appdaemon, automation, home-assistant, lighting

# appdaemon-lighting

Composable lighting building blocks for [AppDaemon](https://appdaemon.readthedocs.io/) + Home Assistant.

## What Is This?

If you've written AppDaemon lighting automations, you've probably solved the
same problems more than once: rate-limiting service calls so you don't flood
Zigbee meshes, tolerating small brightness differences so lights don't flicker,
detecting when a bulb has drifted from its target after a manual override or a
power blip, and restoring state after a temporary scene. This library extracts
those solutions into a small set of typed, composable Python building blocks.

The core idea is a **`LightTarget`** — a frozen dataclass that says "this
entity should be on at this brightness and colour temperature". Your app
computes a list of targets from whatever signals it cares about (motion,
occupancy, time of day, switches). The library then handles the messy part:
signature-based deduplication, per-light and global rate limiting, deadband
tolerance to avoid writing trivially similar states, and drift detection that
repairs lights the user (or a reboot) has nudged away from the target. An
optional overlay manager snapshots and restores light state for temporary
modes, and a reconciler watches for entities that go unavailable and
re-applies the correct state when they come back online.

Everything talks through Python Protocols — there is **no dependency on
AppDaemon at runtime**. You write a thin adapter (a few one-line methods
wrapping `self.call_service` and `self.get_state`), and the rest is plain
Python that you can unit-test without a running HA instance. The
configuration models use Pydantic, which means your YAML gets validated at
app startup rather than silently misbehaving at 2am.

**This is not a framework.** It doesn't manage your app lifecycle, impose a
file layout, or decide how your layers combine. You wire together exactly the
pieces you need. If all you want is the actuator, import that. If you want
the full zone/layer/period registry with overlay and reconciliation, that
works too. It came out of a real home with ~40 lights across five rooms, so
the defaults are practical — but it's a library for people who want to
understand and control their own automation logic, not a black box.

## Install

```bash
pip install appdaemon-lighting
```

## Components

```mermaid
graph BT
    %% ── Inputs (signals from HA) ─────────────────────────────────
    subgraph Inputs["HA Signals (your app reads these)"]
        sensors["sensor.*  binary_sensor.*\nmotion · lux · occupancy · switches"]
        period["Period\n'breakfast' | 'evening' | …"]
    end

    %% ── Configuration layer (registry.py) ────────────────────────
    subgraph Registry["registry · Pydantic config models"]
        zones["ZoneConfig\nentities: light.a, light.b"]
        profiles["PeriodProfile\nct_mired · transition_s"]
        layers["LayerConfig × N\nname · enabled_entity\n┗ LayerZoneConfig per zone\n   bri_pct · ct_mired\n   bri_pct_by_period"]
    end

    %% ── Target computation (your app logic) ──────────────────────
    targets["LightTarget[]\nentity_id · on · brightness\nct_mired · transition · zone · layer"]

    %% ── Signature gating (signatures.py) ─────────────────────────
    sig["stable_signature()\ndeterministic JSON hash\nskip apply if unchanged"]

    %% ── Actuator (actuator.py) ───────────────────────────────────
    subgraph Act["Actuator"]
        config["ActuatorConfig\nrate limits · deadband tols"]
        actuator["Actuator.apply(targets)\n→ global rate gate\n→ per-light rate gate\n→ deadband match\n→ drift detection"]
        result["ApplyResult\napplied · suppressed_match\nsuppressed_rate · sig_unchanged"]
    end

    %% ── Overlay (overlay.py) — parallel path ────────────────────
    subgraph Ovr["OverlayManager (optional)"]
        snapshot["LightSnapshot\ncaptures current HA state"]
        overlay["enter(mode, entities)\nsnapshot → override → exit() restores"]
    end

    %% ── Reconciler (reconcile.py) — background repair ───────────
    subgraph Rec["Reconciler (optional)"]
        watcher["register_watchers()\nlisten_state on controlled entities"]
        recon["unavailable → available\nschedule settle → on_reconcile()"]
    end

    %% ── Output ───────────────────────────────────────────────────
    ha["HAService Protocol\nturn_on · turn_off · get_state\n(adapter around hass.Hass)"]
    lights["💡 Physical lights in HA"]

    %% ── Edges ────────────────────────────────────────────────────
    sensors --> targets
    period --> profiles
    profiles --> targets
    zones --> targets
    layers --> targets

    targets --> sig --> actuator
    config --> actuator
    actuator --> result
    actuator --> ha

    overlay --> ha
    snapshot -.->|"exit: restore"| ha

    watcher --> recon
    recon -.->|"triggers re-apply"| targets

    ha --> lights

    %% ── Styles ───────────────────────────────────────────────────
    style Inputs fill:#e8f4f8,stroke:#5ba3c9,color:#333
    style Registry fill:#fef9e7,stroke:#d4a017,color:#333
    style Act fill:#fdebd0,stroke:#ca6f1e,color:#333
    style Ovr fill:#ebdef0,stroke:#8e44ad,color:#333
    style Rec fill:#e8f8f5,stroke:#1abc9c,color:#333
    style targets fill:#fff,stroke:#2c3e50,color:#333,stroke-width:2px
    style sig fill:#f0f0f0,stroke:#666,color:#333
    style ha fill:#d5f5e3,stroke:#27ae60,color:#333
    style lights fill:#fffacd,stroke:#daa520,color:#333
```

### Module reference

| Module | What it does |
|--------|-------------|
| **types** (`LightTarget`) | Frozen dataclass describing the desired state of a single light — entity, on/off, brightness, CT, transition, plus zone/layer metadata. |
| **registry** (`ZoneConfig`, `LayerConfig`, `PeriodProfile`) | Pydantic models that declare which lights belong to which zones, what each layer does to each zone, and what the default CT/transition is per time-of-day period. |
| **signatures** (`stable_signature`) | Produces a deterministic JSON hash from a list of `LightTarget`s so you can skip redundant apply cycles when nothing changed. |
| **actuator** (`Actuator`) | Takes a list of `LightTarget`s and writes them to HA, gated by global and per-light rate limits, brightness/CT deadband tolerance, and drift detection that repairs manual overrides. |
| **overlay** (`OverlayManager`) | Snapshots the current state of lights on entry, lets a temporary mode take over, then restores the original state on exit. |
| **reconcile** (`Reconciler`) | Watches controlled entities for unavailable→available transitions and automatically re-applies the correct lighting state after the bulb settles. |
| **utils** | Pure helper functions — `clamp`, `lerp`, `smoothstep`, `linmap`, `safe_float`, `as_bool`, brightness↔percent conversions. |

## Quick Example

```python
import appdaemon.plugins.hass.hassapi as hass
from appdaemon_lighting import Actuator, ActuatorConfig, LightTarget

class MyLights(hass.Hass):
    def initialize(self):
        self.actuator = Actuator(
            config=ActuatorConfig(rate_limit_s=0.5),
            call_service=self.call_service,
            get_state=self.get_state,
            now_fn=self.datetime,
            log_fn=self.log,
        )

    def apply_scene(self):
        targets = [
            LightTarget(
                entity_id="light.ceiling",
                brightness=200,
                color_temp=350,
                transition=2,
            ),
        ]
        self.actuator.apply(targets)
```

## Design Principles

- **Composable** — each component works standalone
- **No magic** — you wire things together explicitly
- **Typed** — full type hints, Protocols for extension
- **Testable** — all logic works without AppDaemon runtime
- **Zero AppDaemon dependency** — Protocols only

## License

MIT