A practitioner's field guide to migrating a whole-home Control4 AV system to Home Assistant — without downtime and without a rip-out weekend.
Written for anyone weighing the move or already mid-migration: the decisions, the framework, and the gotchas that only show up once you're holding the soldering iron.
Most people start a migration doc on day one, get three zones in, and never come back to finish it. This one is different: it was written after a completed, multi-phase migration of a roughly 10-zone whole-home audio/video system — then distilled into reusable decisions and principles. The goal is not to document one house. It's to hand the next person the map I wish I'd had.
There are two ways into this guide, depending on where you are:
- Deciding whether to leave Control4? Start with the decision layer →
docs/decision/. It walks the honest tradeoffs before you spend a dollar or pull a single zone. - Already migrating? Go straight to the framework, the build guide, and the lessons →
docs/framework/,docs/building/, anddocs/gotchas/. The framework gives you the sequence; the build guide shows how to do it well in Home Assistant; the gotchas keep you from re-learning things the hard way.
docs/decision/— Should you leave Control4 at all? Tradeoffs, what you're signing up for, and a readiness self-check.docs/framework/— The repeatable 5-stage migration model plus the cross-cutting principles that hold across every house.docs/building/— Building it well in Home Assistant: integrations, Music Assistant, scripting, automations, and platform pitfalls — with small illustrative snippets.docs/gotchas/— A growing catalog of hard-won, generalized lessons: the failures, the rules they taught me, and how to apply them.docs/journey/— The actual arc of one migration, compressed — proof the framework came from doing, not theorizing.
New here? The one-screen router lives at docs/00-start-here.md. Pointing an AI assistant at this repo? See AI-GUIDE.md.
Framework-first, journey-as-evidence. The principles lead; the story exists to show they were earned. Most of this guide is principle-level — no exact device-to-input maps, no "do this and you're done." The Home Assistant build guide goes more concrete, with small illustrative snippets that show the shape (generic placeholders, not copy-paste configs for your house). Your house is wired differently from mine, your gear is different, and your family's tolerance for a dark living room is different. The point is to teach you how to think about the migration so you can make the right call for your setup.
This guide is meant to grow. Your migration bit you in a way mine never did — that lesson belongs here.
- Share a gotcha or suggest a recommendation by opening an issue.
- Ask an open-ended "how did you handle X?" in Discussions.
See CONTRIBUTING.md for the contribution conventions and the anonymization bar every entry must clear.
By amellomd · CC-BY-4.0