Gotchas
Every one of these started as a problem that cost real time and taught a rule worth keeping. They’re written generalized on purpose — the specific gear doesn’t matter, the principle does. The bar for every lesson here is the same: would this help a stranger with a different house?
Each lesson follows the same shape — TL;DR, the situation, what bit me, the general rule and why it holds, how to apply it, and how to verify you got it right — so you can scan for the rule and dig in only where you need to.
| Lesson | TL;DR | Link |
|---|---|---|
| Automate against reality, not labels | The names on inputs and zones describe someone’s intent, not your wiring — automate on what’s physically connected. | Read |
| Idempotent commands | Every command should be safe to send twice; check state first and prefer discrete commands over toggles. | Read |
| Prove the riskiest integration first | The one integration nobody has a clean path for sets your whole timeline — isolate and prove it before planning the rest. | Read |
| Migrate in parallel, never big-bang | Keep the old system live, move one zone at a time, always have a same-day rollback — the family is your acceptance test. | Read |
| Power-off test the old controller | The legacy hub is usually an orchestrator, not a signal router — prove it by pulling power and watching what goes dark, before you plan removal. | Read |
| One control authority per device | Two controllers or two grouping planes fighting over one device silently break volume and availability — give each device exactly one owner. | Read |
| Device status codes can lie | A device’s protocol owns the meaning of its status codes — a 401 may mean “malformed command,” not “wrong password.” Verify against its own spec. |
Read |
| Power commands have a blast radius | One “power on” can wake zones you never named — scope power to the zone, and verify each zone independently before believing it’s off. | Read |
| Ping is not identity | Something answering at an address isn’t proof it’s your device — identify by the service it speaks, and know that randomized MACs break reservations. | Read |
| Stale state is not proof of silence | A source reporting “off” doesn’t mean the room is quiet — ask the amplifier what it’s playing, not the source. | Read |
| An input is a signal contract | An input specifies a level and an equalization curve, not just a connector shape — the wrong level isn’t a volume problem you can trim away. | Read |
| Exhaust the hardware before blaming software | Intermittent flapping for weeks is often failing hardware — eliminate the physical layer before building workarounds that outlive the bug. | Read |
| Deploys invalidate open clients | A reload silently no-ops already-open dashboards — check whether the action ever fired before you debug the action. | Read |
More are coming as the migration behind this guide gets written up — and as others contribute theirs. Got a hard-won lesson? Add yours.