ZHA Step by Step: Installation and First Configuration

If Lesson 3 pointed you toward ZHA, this lesson walks through the actual installation, from your coordinator plugged in to a fully working ZHA integration, step by step, with the typical first-timer snags flagged before they trip you up.

Before installation: a checklist

Confirm four things before opening the integrations page. Your coordinator, whichever model Lesson 2 helped you choose, is physically plugged into your mini PC, either directly or through the USB extension cable that lesson recommended. Home Assistant itself is fully updated. You have a recent backup, per Module 8's habits, taken in the last day or two. And you have this course's Zigbee notebook section ready, since installation is exactly when you'll start filling it in.

Installing ZHA step by step

Open Settings, then Devices & Services, then Add Integration, and search for ZHA. Home Assistant will scan for available serial devices and offer to auto-detect your coordinator's port. If it's found automatically, select it and continue. If nothing appears, you'll enter the port path manually, covered in the next section. Confirm the radio type Home Assistant suggests, matching your specific coordinator model, then let ZHA finish its initial network setup, which takes under a minute for a brand new coordinator.

The USB port: ttyUSB, ttyACM, and by-id

If auto-detection doesn't find your coordinator, you'll need its exact port path. Most USB coordinators show up as something like /dev/ttyUSB0 or /dev/ttyACM0, but these numbered names can shift if you ever plug in another USB device, causing ZHA to silently lose its connection after a reboot. The safer, permanent option is the by-id path, found under /dev/serial/by-id/, which stays fixed to your specific coordinator regardless of what else is plugged in. Use the by-id path during setup whenever it's available, and note it in your Zigbee notebook.

Common first-installation problems

Port not found usually means the coordinator isn't seated properly, or Home Assistant needs a restart to recognize a newly plugged-in device. Wrong radio type selected causes ZHA to connect but behave erratically, worth double-checking against your coordinator's documentation. And a permissions error on some installation methods means Home Assistant's process can't access the serial port, typically resolved by the installation method itself rather than anything you configure manually.

First configuration: what we don't touch

ZHA's advanced settings, network channel, PAN ID, and transmit power, all have sensible defaults that work correctly for the overwhelming majority of homes. Resist the urge to tune these on day one. This course revisits channel selection specifically in Lesson 8, once you actually have a mesh network worth optimizing, not before you've paired a single device.

No mass pairing

Once ZHA is running, it's tempting to immediately put every device you own into pairing mode at once. Don't. Lesson 6 pairs your three starter devices one at a time deliberately, so any pairing problem is obviously tied to the one device you just attempted, rather than lost in a pile of five devices added simultaneously.

What to record in your Zigbee notebook

Write down your coordinator's exact model, its by-id port path, the radio type ZHA selected, and today's date. This handful of details takes thirty seconds to record and saves real time if you ever need to reinstall ZHA or troubleshoot a connection issue months from now.

Removing and re-adding ZHA, only on an empty network

If something goes wrong during this initial setup, before any devices are paired, removing the ZHA integration and adding it fresh is a safe, clean reset. Once real devices are paired, though, removing ZHA means re-pairing every single one, so this clean-reset approach is really only for right now, during this lesson, not something to reach for casually later.

Radio type: a short guide

ZHA supports several radio chip families, and the setup wizard usually detects yours correctly from the coordinator's USB identifier. If you're ever asked to choose manually, check your coordinator's product page or documentation for its specific chip family rather than guessing, an incorrect radio type is one of the more common causes of a coordinator that connects but never actually finds any devices.

What you do after installing ZHA (checklist)

Confirm the ZHA integration shows as connected on the integrations page. Record the notebook details above. Take a fresh backup now that ZHA is installed, before pairing anything. Restart Home Assistant once, and confirm ZHA reconnects automatically without you touching anything. Only then move to Lesson 6 for actual device pairing.

Exercise after this lesson

Complete the checklist above in order, confirm connected status, notebook entry, fresh backup, restart test, before moving on. Don't skip the restart test specifically, it catches port-path problems while the stakes are still low, with zero devices paired yet.

FAQ: questions from a first ZHA install

Can I install ZHA on a Raspberry Pi instead of the mini PC this course recommends? Yes, ZHA works the same way regardless of underlying hardware, though Module 5's mini PC recommendation still applies for overall system stability. Does ZHA need internet access to work? No, ZHA and your Zigbee mesh both run entirely locally, though Home Assistant itself may want internet for other integrations. Will installing ZHA slow down my system? Negligibly, ZHA's resource footprint is small even with dozens of paired devices later on.

Smart home notebook: what to record today

Beyond the coordinator details already mentioned, note that ZHA is your chosen path, with today's date, so future-you has a clear record of when this decision was made and confirmed working.

The calm path versus forum shortcuts

Forum posts sometimes recommend manually editing ZHA's configuration files directly, skipping the setup wizard entirely. Don't, the wizard exists precisely to avoid the class of subtle mistakes manual configuration invites, and this lesson's step-by-step approach gets you to the same working result without that added risk.

A real story: the port that kept changing

A reader in this course's community installed ZHA using the numbered ttyUSB0 path shown by default, everything worked fine for weeks, until they plugged in a USB drive for an unrelated backup task and rebooted their mini PC. ZHA immediately lost its connection, the coordinator had silently shifted to ttyUSB1 once the extra USB device claimed the lower number. Reconfiguring ZHA to point at the by-id path instead, exactly as this lesson recommends, fixed the issue permanently, no more silent breakage every time another USB device gets plugged in or removed. Their advice to future readers was blunt: spend the extra thirty seconds finding the by-id path during initial setup, it's genuinely cheaper than debugging a mysteriously disconnected coordinator weeks later.

Finding the by-id path in practice

If your installation method gives you terminal access, listing the contents of /dev/serial/by-id/ shows every currently connected serial device by its stable, manufacturer-specific identifier rather than a number that can shift. If your installation method doesn't expose a terminal directly, the ZHA setup wizard itself often lists available ports using these same stable identifiers when it presents your coordinator as an option, so you may never need direct terminal access at all to benefit from this more reliable path.

Why the setup wizard beats manual configuration

Home Assistant's ZHA setup wizard validates each choice as you make it, catching an unreachable port or a mismatched radio type before it becomes a saved, broken configuration you have to untangle later. Manual configuration files skip that validation entirely, a small typo in a device path or radio type setting simply fails silently until you notice devices aren't responding, often much later and with much less context about what actually went wrong. For a first installation especially, the wizard's guardrails are worth using rather than working around.

Confirming ZHA survived your restart

After the restart this lesson's checklist calls for, revisit Settings, then Devices & Services, and confirm ZHA still shows as connected rather than showing an error badge or a reconfiguration prompt. This exact check, repeated after every Home Assistant restart for the rest of this module, is the single habit that catches port-path problems early, well before they compound into a mesh full of devices that mysteriously stopped reporting.

Backing up right after installation

Module 8 established automatic, off-server backups as a standing habit, and this is a natural moment to take a manual one too, right after ZHA is confirmed working but before any device is paired. A backup at this exact point gives you a clean, known-good restore target if anything goes sideways during Lesson 6's pairing process, genuinely cheap insurance for a two-minute task.

If ZHA won't detect any port at all

Occasionally the setup wizard shows no available ports whatsoever, even with a coordinator physically connected. Try a different USB port on your mini PC first, some ports are hubs with less reliable power delivery. Try the USB extension cable from Lesson 2 if you weren't already using one, direct connections sometimes suffer interference from the mini PC's own internals. And confirm the coordinator's status LED is actually lit, a surprisingly common cause is simply a cable that isn't fully seated.

Documentation habits that pay off later

The notebook habit this lesson asks for feels almost too small to matter on installation day, but months into this course, with dozens of devices paired across several modules, that one page recording your coordinator's exact model and port path becomes genuinely valuable the one time you need to troubleshoot or migrate hardware. Treat it as part of the installation itself, not an optional extra step you can skip if you're in a hurry.

Comparing this installation to Module 6's early integrations

If you've already added a handful of cloud-based integrations back in Module 6, ZHA's installation flow will feel familiar, the same Settings, then Devices & Services, then Add Integration path you've used before. The genuine difference here is that ZHA talks to a physical piece of hardware over a serial connection rather than a cloud API, which is exactly why port paths and radio types matter in a way that a purely cloud-based integration never asked of you. Recognizing that this is fundamentally a hardware integration, not just another cloud service, helps explain clearly why this lesson spends so much more time carefully on physical connection details than a typical Module 6 setup ever did.

A note on patience during this lesson

This installation genuinely takes only a few minutes when everything goes smoothly, but if you hit one of the common problems this lesson covers, resist the urge to rush toward a fix pulled from a random forum thread that may not match your exact hardware or installation method. Working through this lesson's own troubleshooting sections first, in order, resolves the overwhelming majority of first-installation issues without needing to venture outside this course's guidance at all, and it keeps your growing Zigbee notebook consistent with everything else this course has already taught you.

What "done" actually looks like here

Before moving on, this lesson is genuinely complete only once every checklist item has been confirmed, not just attempted. That means an actually connected ZHA integration, a notebook entry with the four details this lesson asked for, a fresh backup taken after installation, and a restart that left ZHA reconnected without any manual intervention on your part. Skipping the restart test specifically is the single most common shortcut readers take, and it's exactly the one this lesson recommends against, since it's cheap to run now and expensive to skip if a port-path problem is quietly waiting to surface later.

Key takeaways

With ZHA installed and confirmed stable, Lesson 6 pairs your first three real devices, a smart plug, a temperature sensor, and a motion sensor, one at a time.