ha integration dev

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: HA Integration Dev
description: >
  Home Assistant custom integration development in Python. Covers custom_components,
  DataUpdateCoordinator, config_flow, OAuth2, conversation agent, HACS publishing,
  device registry, entity platforms, services, repair issues, diagnostics,
  Bluetooth integrations, and multi-coordinator patterns.
source: https://github.com/tonylofgren/aurora-smart-home
---

# Home Assistant Integration Development

Reference skill for developing Home Assistant custom integrations in Python.

## Overview

**Core principle:** Home Assistant integrations run in the same Python process as Core with full filesystem access. Security, proper async patterns, and correct timestamp handling are non-negotiable.

**Context:** This skill requires understanding the integration type (polling vs push, cloud vs local) before generating code. The DataUpdateCoordinator pattern is mandatory for most integrations.

## The Iron Law

```
TIMESTAMPS: dt_util.now() / dt_util.utcnow() - NEVER datetime.now()
ATTRIBUTES: JSON-SERIALIZABLE ONLY - NO DATACLASSES, NO DATETIME OBJECTS
ASYNC: aiohttp FOR HTTP - NEVER requests
STORAGE: entry.runtime_data - NEVER hass.data[DOMAIN]
```

The first three rules cause 90% of integration bugs. The fourth rule (`runtime_data`) is the modern pattern since HA 2024.4 - it provides type safety and cleaner lifecycle management.

## The Process

```
User request
    │
    ▼
Clarify: API type, auth, entities
    │
    ▼
Ask: HACS preparation?
    │
    ▼
Select template
    │
    ▼
Read relevant references
    │
    ▼
Generate integration code
    │
    ▼
Run pre-completion checklist
    │
    ├──if HACS=yes──▶ Generate HACS files ──▶ Deliver integration
    │
    └──if HACS=no───▶ Deliver integration
```

## Common Pitfalls

Watch out for these Iron Law violations:

| Thought | Reality |
|---------|---------|
| "datetime.now() is fine" | WRONG. Use `dt_util.now()` for timezone-aware timestamps |
| "I'll store the dataclass in attributes" | WRONG. Convert to dict or extract primitive fields |
| "requests is simpler" | WRONG. Use aiohttp or async_get_clientsession |
| "I'll add unique_id later" | NO. Entities without unique_id can't be customized |
| "This API doesn't need rate limiting" | WRONG. Always implement backoff |
| "I'll skip the coordinator for simplicity" | NO. Coordinator centralizes error handling |
| "Logging the API key helps debugging" | NEVER log credentials |
| "I'll use hass.data[DOMAIN] for storage" | OUTDATED. Use `entry.runtime_data` (typed, HA 2024.4+) |
| "EntityDescription doesn't need frozen" | REQUIRED since HA 2025.1. Use `frozen=True, kw_only=True` |
| "Coordinator doesn't need config_entry" | REQUIRED. Pass `config_entry=entry` (deadline HA 2025.11) |
| "service: in YAML examples" | RENAMED. HA calls these "actions" since 2024.8 |

## First Step: Clarify Integration Type

Ask user:
1. **What does the integration connect to?** (cloud API, local device, calculated data)
2. **Update method?** (polling interval vs push/websocket)
3. **Authentication?** (none, API key, OAuth2)
4. **Entity types needed?** (sensor, switch, light, climate, etc.)
5. **Project folder location?**
   - Default: create `<integration_id>/` (or `<integration_id>-integration/` for HACS-ready) in the current working directory.
   - Alternative: user specifies a different path.

   **Delivery Contract:** every artifact is written to disk as a file in the project folder. Chat output is not delivery. The folder always contains `custom_components/<integration_id>/` with `__init__.py`, `manifest.json`, `const.py`, platform files, `strings.json`, `translations/en.json`, plus a `README.md` per Iron Law 3 in `aurora/souls/ada.md` (sections: What this does, Installation, Configuration, Troubleshooting, Recovery, per `aurora/references/deliverables/manual-format.md`). No chat-only output option.
6. **Prepare for HACS sharing?** (recommended for distribution)
   - **Yes** - Create hacs.json, README.md, LICENSE