ha-yaml

<p align="center"> <img src="assets/banner.png" alt="Aurora Smart Home - Claude Skills" width="100%"> </p>

Aurora Smart Home

A Claude Code plugin for building smart home projects with verified reference data. Aurora routes your request to a specialist, validates every pin, entity, and address against schema-checked profiles, and refuses to ship code that does not pass.

      

⚠️ Use at your own risk. Aurora generates code and recommendations for

educational purposes. Smart home projects involve mains electricity, batteries,

and devices that control locks, water, heating, and gas. AI-generated configs

can be plausible but wrong. The maintainers, contributors, and Anthropic accept

no liability for property damage, personal injury, data loss, or any other harm.

See DISCLAIMER.md for full terms.

What's new: HA reference refresh (v1.9.2, May 2026)

The Home Assistant YAML skill's reference library has been brought up to date against the official HA documentation snapshot from 2026-05-30.

• •Dashboard actions — the actions.md reference now covers all seven Lovelace tap/hold/double-tap action types (more-info, toggle, perform-action, navigate, url, assist, none) including confirmation dialogs. Also added: response variables for capturing return data from calendar, weather, and other actions that produce structured output.
• •Device-specific conditions and triggers — conditions.md gained a Device-Specific Conditions section covering alarm, climate, timer, calendar (calendar.is_event_active), and more, plus a selection guide. triggers-advanced.md gained a Device Trigger Inventory spanning 18+ device domains and a dedicated Calendar Trigger section.
• •Modern syntax throughout — deprecated service:, platform:, and singular automation keys (trigger:, condition:, action:) replaced with action:, trigger: state, triggers:, conditions:, actions: across all four core reference files. The skill now also lists all 50 reference files in its Quick Reference table.

What's new: ESPHome 2026.5.0 (May 2026)

Aurora now targets ESPHome 2026.5.0. Twelve user-visible changes landed in this release at once - some of them (battery life, Bluetooth proxy stability, the audio stack) take effect the moment you reflash, no YAML changes required. Others unlock things that were not possible before: synchronized whole-house audio from ESP32s, Zigbee built into core for the C6 and H2, and a radio_frequency entity type that finally treats RF transceivers as first-class devices in Home Assistant.

• •Multi-room synchronized audio via the new Sendspin stack. One device runs

the hub, every other device runs a per-room player, and they stay in lock-step on the LAN. The decoder work in this release is tuned so a non-PSRAM ESP32 can actually keep up with 2-channel Opus, which previously required an S3 with PSRAM. Each room has its own delay_compensation to align with whatever amp/DAC chain you wire up.

• •Zigbee on ESP32-H2 and C6, no external component required. A Xiao C6 or

H2 module can now be flashed straight into a battery-powered Zigbee end device or router; both ZHA and zigbee2mqtt pick it up over standard clusters without custom converters. New on_join automation trigger and power_source field for advertising battery vs mains.

• •`radio_frequency` is now a first-class HA entity type. The entity itself

has no knowledge of which RF chip is wired underneath, so a CC1101, RFM69, SX127x, or custom external all work through the same YAML triggers. Pair with the new ir_rf_proxy platform if you want HA to know your frequency range.

• •Battery devices noticeably last longer. The runtime now actually runs

components at the cadence you ask for, and the watchdog feeding cost on ESP-IDF has finally been retuned (the original 3 ms throttle was set for a 2019 codepath that cost ~100 ns per feed; the IDF port pushed that to 10 µs per feed without anyone noticing). A reference Thread device measured 2.0 mA dropping to 1.1 mA. New esp32: watchdog_timeout: knob lets you trade responsiveness for sleep time, 5 to 60 seconds.

• •Bluetooth proxy reliability fix. The status=133 GATT failures that have

hit Yale and August lock owners for years are gone. The proxy now holds BT priority during active connections instead of releasing it after the handshake.

• •ESPHome Device Builder is in public beta. A separate web dashboard with a

visual component editor alongside Monaco YAML, a firmware job queue, labels, areas, device cloning, out-of-sync badges, cross-config YAML search, a YAML diff view, and a Ctrl-K command palette. Available via the "ESPHome (beta)" Home Assistant add-on; the classic dashboard is still default.

• •Native ESP-IDF toolchain alongside PlatformIO. esp32: toolchain: esp-idf

switches the build system to idf.py. ESP-IDF v6.0.1 readiness work landed in the same release.

• •40 kB more internal RAM on PSRAM boards via esp32_ble: use_psram: true,

which moves the Bluedroid stack into SPIRAM.

• •SPDIF speaker output through any GPIO using the new mode: spdif setting

on i2s_audio. Drive an optical TOSLINK module or a 75-ohm coax line directly from the ESP, no external DAC.

• •ESP32-P4 USB high-speed transfers via usb_host: max_packet_size: 512.

Previously P4 USB was stuck on 64-byte full-speed packets.

• •Locks gained OPENING and OPEN states for motorized smart locks where HA

needs to distinguish "bolt disengaged" from "door is hanging open". Existing LOCKED/UNLOCKED-only locks are unaffected.

• •`modbus_server` is its own component now. If you used modbus_controller

in server mode, move the keys to a top-level modbus_server: block: server_registers: becomes registers:, server_courtesy_response: becomes courtesy_response:. Worth about 60% flash savings on the way out.

Full details, breaking changes, and copy-paste recipes: `esphome/references/release-2026-5.md`.

What is Aurora

Aurora is a community plugin for Claude Code. You install it once. After that, every smart home request you make ("build a temperature sensor on ESP32", "automate my lights at sunset", "publish this integration to HACS") is handed to a specialist agent that consults machine-readable board and component profiles before generating code.

If the GPIO you asked for is reserved by USB, Aurora says so. If two I2C sensors collide on address 0x76, Aurora says so. If an automation references an entity the firmware never creates, Aurora says so. The reference data is the source of truth, not the model's training memory.

No runtime dependencies. The plugin is markdown and JSON. Claude reads it. Python and pytest are only used by maintainers to keep the reference data correct.

<details> <summary><strong>How the pieces fit together</strong> (plugin, command, skill, agent, validator)</summary>

</details>

Already comfortable with Claude Code skills? Skip to

How Aurora works,

Validation and safety,

or Included skills.

Quick start

You need Claude Code installed first. Get it at claude.com/claude-code.

Inside Claude Code:

/plugin marketplace add tonylofgren/aurora-smart-home
/plugin install aurora@aurora-smart-home

Restart Claude Code, then run:

/aurora:aurora

Aurora opens, asks what you want to build, and routes the request to the right specialist. That is it.

Try your first prompt

After /aurora:aurora opens, paste any of these:

What Aurora helps you do

• •Generate ESPHome firmware that compiles, on a board that actually exists,

with pins that are not reserved by USB or PSRAM.

• •Write Home Assistant automations and dashboards that reference entities

the firmware side actually creates.

• •Build Python custom integrations that pass HACS validation and do not

ship datetime.now() inside an async coroutine.

• •Review configs you already have. Paste existing YAML and Aurora flags

every issue with line-number anchored fixes.

• •Connect external APIs (Tibber, SMHI, OpenWeatherMap, Spotify, and others)

using verified patterns.

Who this is for

Aurora fits three kinds of work:

• •First sensor, first automation, first time touching ESP32. Aurora

picks parts that exist, pins that work, and a board that has not been end-of-lifed. You get one working build and the reasoning behind it. After that, you can do the next one without asking.

• •Existing install, dozens of automations, allergic to surprises.

Paste your YAML. Aurora checks it against your HA version and every entity in your setup, reports each issue with a line number and a paste-ready fix, and does not rewrite your file.

• •Building something to ship to other people. Volt knows the

difference between a board that survives a botched OTA and one that needs a recovery jig. Ada knows what HACS reviewers will catch before you submit.

How Aurora works

Activate Aurora — two ways

┌─────────────────────────────────────────────────────────────┐
│  Inline (one turn):                                         │
│    /aurora:aurora build a CO2 monitor on ESP32-S3           │
│                                                             │
│  Two-step (separate turns):                                 │
│    1) /aurora:aurora                                        │
│       → Aurora shows its banner and asks the opening        │
│         question.                                           │
│    2) build a CO2 monitor on ESP32-S3                       │
└─────────────────────────────────────────────────────────────┘

Both paths end up in the same routing flow. Re-running /aurora:aurora later in the same conversation skips the banner and just acknowledges that Aurora is already loaded — no version check, no re-greeting.

Routing

┌─────────────────────────────────────────────────────────────┐
│  Aurora (orchestrator)                                      │
│    Parses intent, picks the right specialist(s),            │
│    recommends a Claude model tier, opens a shared snapshot  │
│    if more than one specialist is involved.                 │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  Specialist (Volt for firmware in this case)                │
│    Loads the board profile (aurora/references/boards/).     │
│    Loads the component profile (aurora/references/          │
│       components/).                                         │
│    Calls validators: pin, conflict, i2c-address, voltage,   │
│       ota-safety, version, entity-id, secrets.              │
│    If a validator fails, refuses to generate. Shows a fix.  │
│    If validators pass, returns YAML + wiring + calibration. │
└─────────────────────────────────────────────────────────────┘

When the project spans firmware plus automations plus a dashboard, the agents share a project snapshot written to your workspace as aurora-project.json. Single-agent (QUICK mode) tasks skip the snapshot so there is no overhead for small jobs. Multi-agent (DEEP mode) tasks use it like this:

You: "Motion sensor on ESP32, automation in HA, with a dashboard tile"

Volt creates:    binary_sensor.living_room_motion
Sage uses:       binary_sensor.living_room_motion as trigger
Iris places:     binary_sensor.living_room_motion on the room view

If Sage references an entity Volt did not produce, or if Iris cannot find
the entity on the dashboard, Aurora raises a conflict instead of generating
broken YAML. Conflicts surface to you, not silently to the next agent.

What gets delivered

Aurora does not paste code into chat and call it done. Every project produces a folder on disk with the working files plus a README.md you can hand to someone else.

Hardware projects (Volt)

bedroom-co2/
├── README.md                ← project manual
├── bedroom-co2.yaml         ← ESPHome firmware
└── secrets.yaml.example     ← WiFi + API key template

The project README carries: what it does, BOM with estimated unit prices and a dated total, wiring with connection table and ASCII diagram, installation steps from flash to verified entities in Home Assistant, calibration procedures for the specific sensors used, troubleshooting for the three most likely failure points, and recovery instructions for when OTA goes wrong.

For custom PCB or production runs the folder grows with SCHEMATIC.md, PCB-NOTES.md, and (for production) MANUFACTURING.md, COST-ANALYSIS.md, CERTIFICATION.md, TEST-JIG.md. Aurora produces text specifications, not KiCad binaries.

Software projects (Sage, Ada, River, Iris)

For automations (Sage), custom integrations (Ada), Node-RED flows (River), and dashboards (Iris), the project folder includes the working YAML / Python / JSON plus a README.md with agent-specific installation steps, troubleshooting, and recovery.

Custom integrations (Ada) include the full custom_components/<id>/ structure with manifest.json, strings.json, translations, and a HACS-ready repo layout (hacs.json, LICENSE, .github/workflows/validate.yaml) when requested.

What you do not get

Aurora does not produce KiCad files, gerbers, or PNG wiring images. Schematics ship as text with ASCII block diagrams that a human or PCB designer can rebuild in their preferred tool.

The contract is enforced by Iron Law 8 in Volt's soul and Iron Law 3 in the four software-only specialists. Each agent verifies that every required file exists on disk before declaring delivery complete.

Validation and safety

Aurora ships 12 validators that specialist agents must run before returning code, plus three supporting specs (a shared output format, a retroactive review protocol, and a board-selector helper). All files live in `aurora/references/validators/`.

Validators (block code generation on failure):

Supporting specs:

Every validator emits the same four-tier output:

❌ Problem (short):
GPIO 19 cannot be used on ESP32-S3 DevKit C-1 while USB CDC is enabled.

📚 Explanation (medium):
The ESP32-S3 routes USB D+/D- to GPIO 19/20. With usb_cdc: enabled,
these pins are reserved and any assignment to them collides with USB.

🔧 Fix (concrete):
Move the sensor to GPIO 8 (SDA) and GPIO 9 (SCL), the board's default
I2C pins.

💡 Deeper (optional):
You can set usb_cdc: false to free GPIO 19/20, but you lose USB serial
console (only OTA-over-WiFi remains for log inspection).

When this block fires, the agent stops. No YAML is written until the problem is resolved or you explicitly tell the agent to override. The fix line is concrete enough that you usually paste two lines into your config and rerun.

When validators pass, you get a complete result: the YAML, a wiring diagram, the calibration procedure for the sensors involved, and a troubleshooting section. Not half-finished code that compiles but fails to boot.

Safety scope. Smart home work touches mains electricity, batteries, locks, water, and heating. Aurora validates configuration against verified reference data, but it does not replace your judgement, your electrician, or your fuse box. See DISCLAIMER.md for the full statement.

Included skills

Aurora is one plugin (aurora@aurora-smart-home). Inside it sits the /aurora:aurora orchestrator command plus six topic skills. The orchestrator routes requests across skills and across agents. The topic skills also activate automatically when you mention relevant keywords, so you can skip the orchestrator on quick tasks.

Meet the Aurora team

<details> <summary><strong>Show all 21 agents</strong></summary>

Aurora runs like a small smart home agency. 1 orchestrator + 20 named specialists across 7 departments. Each specialist has a defined domain, a soul (aurora/souls/), and a voice. Agents are not owned by a single skill, they are routed in by the orchestrator wherever their domain fits.

Hardware department

Home Assistant department

Field intelligence

• •🏪 Atlas | External API patterns, OAuth, community integrations. "Someone has already solved this. Let me show you how the community does it."

Quality desk

Research library

Operations

Design studio

• •🎨 Canvas | Graphic design, UI beyond dashboards. "The layout works but it has seven things asking for attention at once."

</details>

Examples

Complete, working projects live in `examples/`:

For how the skills connect across a multi-step project, see SKILL-INTEGRATION.md.

Updating

Claude Code does not auto-update plugins by default. Aurora ships new boards, sensors, and validators regularly.

# Inside Claude Code (refreshes every installed plugin)
/reload-plugins

# From your terminal (targets aurora only)
claude plugin update aurora@aurora-smart-home

Then restart Claude Code so the new files load.

Enable auto-update once and forget:

1. Run /plugin to open the plugin manager.
2. Open the Marketplaces tab.
3. Pick aurora-smart-home.
4. Choose Enable auto-update.

Note: the slash command /plugin update <name> does not accept arguments. Use /reload-plugins or the CLI form above.

Troubleshooting

Full guide: TROUBLESHOOTING.md.

Changelog

Version history lives in CHANGELOG.md.

What's new in v1.9.1: Path-resolution fix. /aurora:aurora no longer reports "the aurora directory doesn't exist in the project" when invoked from a working directory that isn't an Aurora-structured repo. The slash command at commands/aurora.md now explicitly tells Claude that aurora/SKILL.md lives in the plugin install directory, not the user's project. A new Path Conventions section at the top of aurora/SKILL.md clarifies the same rule for every reference Aurora makes to its own files. Latent regression since 2026-01-03 when the aurora plugin structure was first introduced; affected 15 releases (v1.0.0 through v1.9.0). If you ever saw such an error and gave up, this is fixed.

What's new in v1.9.0: Aurora now targets ESPHome 2026.5.0 with a complete release reference, working examples for every new feature (Sendspin multi-room audio, Zigbee on ESP32-C6/H2, radio_frequency entity, BLE coex fix for Yale/August locks, soft-brick OTA recovery), and the first vendored external component (panasonic_ac from DomiStyle, MIT-licensed, ships locally so builds work offline). The examples library expanded from 4 to 27 working projects covering battery sensors, leak detection, LED strips, smart plugs, soil moisture, voice assistant, solar inverter monitoring, EV charger control, pool chemistry, smart blinds, fingerprint unlocking, e-paper weather stations, LVGL touchscreen panels, and more. Skill orchestrator polish: cross-skill handoffs table in home-assistant, Process flowchart added to node-red, reactivation boundary documented.

What's new in v1.8.1: Custom PCB builds are now first-class. Tell Volt "bare chip", "custom board", or "module" and it routes to a new Mode C: picks the right Espressif module (ESP32-S3-WROOM-2, C3-MINI-1, or C6-MINI-1 for Thread/Matter), explains what a bare module demands (external LDO, no onboard USB-UART), and always walks you through the prototype-first workflow before you commit to a PCB layout. Board recommendation engine fixed: commercial devices (Shelly, Sonoff) no longer appear as fresh-build suggestions. LilyGO T-Display S3 default I2C pins now warn about the silent UART0 conflict.

What's new in v1.8.0: Hardware safety analysis — dangerous projects (battery, mains relay, outdoor, >5V) now trigger Vera's review before Volt starts and produce hardware/HAZARD-ANALYSIS.md. PCB files move from esphome/ to hardware/. Four HA integration patterns documented in aurora/references/ha-integration/. Self-validating delivery via aurora/scripts/check-delivery.py — every specialist must pass the script before declaring done.

The roadmap lives in ROADMAP.md.

Contributing

Issues and pull requests welcome. Start with CONTRIBUTING.md for the contribution workflow. Adding boards or components goes through aurora/references/ and must pass the pytest suite (pytest aurora/tests/).

License

MIT. See LICENSE.

Credits

Aurora's agent personas are inspired by the people building the Open Home.

Get started in 30 seconds

/plugin marketplace add tonylofgren/aurora-smart-home
/plugin install aurora@aurora-smart-home
/aurora:aurora

Then describe what you want to build.

Aurora helps you work with Home Assistant. Home Assistant's core development is funded by Nabu Casa. If your home runs on HA, please consider supporting them. Aurora is an independent community project, not affiliated with, endorsed by, or funded by Nabu Casa, the Open Home Foundation, or Anthropic. Agent personas are fictional.

Contact

Questions, build ideas, or want to share a project? Reach out on Instagram: @roligaprojekt.

Bug reports and feature requests: open a GitHub issue.

Created for use with Claude Code by Anthropic.