Communication protocols

Why protocols matter

In Chapter 14, you learned how to add an integration to Home Assistant. Integrations belong to the software layer; this chapter goes one layer deeper to explain how a signal actually travels from your phone to a light bulb.

Why should you care about this low-level detail? Three costly reasons:

• Buying the wrong device wastes your money. A low-cost “smart switch” may advertise voice-assistant support yet work only through its vendor’s cloud account. Home Assistant may not be able to access it at all.
• An internet outage can disable your entire home. Local protocols can still turn on the lights when your router loses its internet connection. Cloud-controlled devices stop working when your internet provider or the vendor’s service goes down.
• You may not discover capacity limits until the 20th device. A typical example is filling a home with Wi-Fi plugs, only for the router to begin dropping connections after the first dozen or so. Consumer routers have practical limits on the number of concurrent clients. Avoid this trap before buying your first device.

By the end of this chapter, you will be able to assess whether a product can work with Home Assistant, choose a primary protocol for your home with confidence, and identify the correct layer to investigate when a device goes offline.

What does a protocol govern? Three distinct layers

Most confusion comes from treating three different concepts as though they were the same. Separate them now, and the rest becomes much clearer. Imagine speaking to someone in another room:

Layer 1: radio or wire—the medium that carries the message

This is the difference between shouting, using a two-way radio, and using a telephone line. Wi-Fi, Zigbee, Thread, and Bluetooth all use radio in the 2.4 GHz band. Z-Wave uses a different, lower-frequency band. KNX and Modbus RTU do not use radio at all; they run over physical wiring.

Layer 2: data format—the language being spoken

Two people can use identical radios and still fail to communicate if one speaks Taiwanese Hokkien and the other French. Zigbee devices understand one another, but Zigbee does not automatically understand Z-Wave. Matter has attracted attention because it aims to provide a common language that many ecosystems understand.

Layer 3: how Home Assistant receives it—who translates

Your Home Assistant host may have Ethernet and Wi-Fi, but it does not automatically have Zigbee or Z-Wave radios. You therefore need either a USB radio adapter, known as a coordinator, or a vendor gateway or hub that translates the protocol into network traffic and passes it to Home Assistant.

Two terms you must distinguish

At-a-glance comparison of nine protocols

This is the chapter’s essential reference table. Treat the range column as an approximate guide, not a specification. Building materials, furniture, and interference have a major effect: the same device may achieve three times the range through timber partitions that it does through reinforced concrete.

The next table explains how each option connects to Home Assistant:

Hands-on: inventory the protocols in your home

Before buying anything new, establish what you already have. These five steps take about ten minutes.

1. Review your integrations

   In the sidebar, select Settings, then open Devices & services. This page lists every configured integration. Note the relevant names. If you see MQTT, Zigbee Home Automation, or Bluetooth, for example, those technologies are already in use in your home.

2. Look for dedicated Zigbee or Z-Wave pages

   If you have connected a Zigbee coordinator and configured ZHA, a Zigbee entry appears under Settings. A configured Z-Wave network similarly adds a Z-Wave entry. These are the quickest indicators that the corresponding network exists. Menu locations may change slightly between releases; follow the labels in your installed version.

3. Count your Wi-Fi devices

   Sign in to your router’s administration page and find its connected-device list. Exclude phones, computers, and televisions; the remaining clients are likely to include your Wi-Fi smart devices. If you already have more than a dozen and intend to keep expanding, consider Zigbee or Thread for future devices.

4. Classify each device as local or cloud-dependent

   Return to Settings > Devices & services and inspect each integration. If setup required credentials for the vendor’s app or redirected you to the vendor’s website for authorization, it is probably cloud-dependent. If it required only a local IP address or was discovered directly on your LAN, it is probably local.

5. Conduct an internet-outage drill

   Disconnect the router’s WAN cable—not Wi-Fi—while leaving your internal network running. Then use Home Assistant to control each device. Devices that respond are genuinely local; those that time out depend on the cloud. Reconnect the cable when you finish.

6. Record the results

   Use the labels described in Chapter 4 to add a “Cloud” label to cloud-dependent devices. You will then know at a glance what will fail during an outage and what to replace first.

Zigbee in depth: coordinators, routers, and channel interference

Zigbee is widely available, relatively inexpensive, and highly efficient for battery-powered devices. It also has several pitfalls that can make the protocol seem unreliable when the real problem is network design.

Three roles: coordinator, router, and end device

Choosing a coordinator

Home Assistant currently recommends several coordinator families: models based on Silicon Labs EmberZNet chips, including Home Assistant Connect ZBT-2, Connect ZBT-1, Home Assistant Yellow, SONOFF ZBDongle-E, and SMLIGHT SLZB-07; USB adapters based on the Texas Instruments CC2652 and CC1352 families; and the dresden elektronik ConBee III.

The documentation no longer recommends several older models, including ConBee II, RaspBee II, SONOFF ZBBridge, Nortek HUSBZB-1, the Elelabs, Digi XBee, and ZiGate ranges, and TI CC2530, CC2531, and CC2538 devices. Many remain available through online marketplaces and second-hand sellers, often at one-third the price of a recommended model. Before ordering an unusually cheap adapter, check whether it appears on the “not recommended” list.

Home Assistant Connect ZBT-2 uses a Silicon Labs MG24 radio and an ESP32-S3 for USB connectivity. Its data rate is 460800, compared with 115200 for the preceding ZBT-1; it has an external antenna; and its suggested retail price is US$49 or €45. The box includes a 1.5-metre USB-C cable.

Channel interference: do not rush to change the Zigbee channel

Zigbee and Wi-Fi both occupy the 2.4 GHz band, so interference is common. Home Assistant’s ZHA documentation differs from much online advice: best practice is not to change the Zigbee channel. When a network is created, ZHA’s Smart option scans all channels once and gives preference to channels 15, 20, and 25.

If interference persists, the documented sequence is to move the coordinator away from Wi-Fi access points and other Wi-Fi sources first. If that does not help, change your router’s Wi-Fi channel, not the Zigbee channel. The practical reason is that changing the Zigbee channel usually requires every device to be paired again—easily an afternoon’s work.

USB 3.0: the hidden source of interference

Use a USB extension cable to move the adapter away from the host itself, because the computer, hard drives, and SSDs are all potential interference sources. The documentation recommends a well-shielded extension cable; thicker cables generally provide better shielding.

Placement recommendations

• Place the coordinator in a central location, not at the back of a media console or inside a metal cabinet.
• Keep it away from appliances and dense wiring. Refrigerators, microwave ovens, and power supplies are poor locations.
• In a large or elongated home, add a permanently powered Zigbee device near the midpoint as a relay before expanding farther.
• ZHA users can select Show map under Settings > Zigbee to inspect the network topology. RSSI and LQI values can help identify especially weak links.

ZHA or Zigbee2MQTT?

The same coordinator and set of Zigbee devices can connect to Home Assistant in two ways. This is one of the most common decisions for newcomers.

Zigbee2MQTT currently recommends zStack (Texas Instruments) and EmberZNet (Silicon Labs) adapters. This overlaps substantially with the ZHA recommendations, so a good coordinator can support either route. In Home Assistant, Zigbee2MQTT is installed as an App, formerly called an add-on. It also requires an MQTT broker; Mosquitto is the official recommendation.

What if you replace the coordinator?

ZHA includes a migration function under Settings > Zigbee. The official documentation describes migration among devices based on Silicon Labs, Texas Instruments, and ConBee or RaspBee hardware. This may allow you to replace an old adapter without pairing every sensor again. Follow the migration wizard shown in your installed version.

Z-Wave: more expensive, but dependable

Z-Wave is much less visible than Zigbee in Taiwan and is substantially more expensive, but it is a mainstream choice in Europe and North America. Because it does not share Wi-Fi’s 2.4 GHz band, it is inherently subject to far less interference.

Confirm the frequency region before buying

How Z-Wave runs in Home Assistant

Home Assistant’s Z-Wave integration uses Z-Wave JS. Once configured, access its management page through Settings > Z-Wave or Settings > Devices & services > Z-Wave. It uses the Z-Wave JS “App,” formerly known as an “Add-on.” Home Assistant 2026.2 officially renamed Add-ons to Apps, and the menu path is now Settings > Apps. Localized wording may continue to change; “App” and its translation refer to the same place. See Appendix A for a fuller explanation.

Hardware and device inclusion

For a new installation, the official documentation recommends an 800-series adapter with firmware 7.23.2 or later, and specifically names Home Assistant Connect ZWA-2. Older devices such as Aeotec Z-Stick Gen5+, Zooz ZST10, and Nortek HUSBZB-1 remain on the compatible list, but “compatible” does not mean “recommended for a new purchase.”

There are two ways to add a device to the network, a process called inclusion:

• SmartStart: Scan the QR code on the device. Once powered, the device should join automatically within 10 minutes, according to the official documentation.
• Traditional inclusion: Put both the controller and the device into inclusion mode. Consult the device manual for its exact procedure; every manufacturer differs.

Z-Wave supports S2 encryption. The official documentation notes that S2 provides additional benefits without adding network-traffic overhead. Security keys are generated automatically when a new network is created. Z-Wave Long Range is also available as a long-distance network topology for compatible devices.

Matter and Thread: one is the language, the other the route

These terms are often confused. In short, Thread defines how data is transported at the network layer, while Matter defines what devices say at the application layer. Consequently, both Matter over Thread and Matter over Wi-Fi devices exist; both are Matter devices.

What is a Thread border router?

Thread devices form a low-power mesh network using IPv6. A border router connects that Thread network to your home’s Wi-Fi or wired network.

The official Thread integration documentation currently lists the following border routers:

If you already own a HomePod mini or Nest Hub, you already have a border router and do not need to buy another. To view your Thread network status, open Settings > Devices & services > Thread > Configure.

Add a Matter device to Home Assistant

One prerequisite causes particular confusion: you must pair Matter devices through the mobile Companion app; a browser cannot perform the pairing. Home Assistant’s Matter controller uses the Companion app for commissioning. Chapter 7 covers Companion app installation.

1. Install the Matter integration

   Under Settings > Devices & services, add the Matter integration. If you use Home Assistant OS, the system asks whether to install the official Matter Server; select Submit and allow it to install. Matter Server runs independently and connects your Matter network, known as a fabric, to Home Assistant.

2. Confirm that IPv6 is enabled

   The official documentation lists IPv6 as a requirement. Under Settings > System > Network, set IPv6 to Automatic or Static. If IPv6 is disabled, later pairing can fail without an obvious explanation.

3. Open the Companion app on your phone

   In the Home Assistant app, open Settings > Matter and select Add device. Android users must also set the app’s location permission to “Allow all the time,” or discovery will fail.

4. Specify whether the device is new or already commissioned

   For a new device that has not joined another platform, select “No, it’s new.” Scan the device’s QR code with your phone, or select “More options” and enter the pairing code manually. Finally, select Add to Home Assistant.

5. If the device is already on another platform

   If the device is already part of Apple Home or Google Home, select “Yes, it’s already in use,” identify its current controller, and follow the on-screen instructions. In practice, you generate a sharing QR code or pairing code in the other platform’s app, then use that code in Home Assistant. One of Matter’s major advantages is that several platforms can control the same device simultaneously.

MQTT and local HTTP: two versatile routes for DIY projects

The protocols above describe forms of radio communication. MQTT and HTTP are different: they are application-layer protocols that run over your home network, whether the underlying connection is Wi-Fi or Ethernet. When a device lacks a dedicated integration, these two routes can be invaluable.

MQTT as a community noticeboard

Imagine a noticeboard in an apartment lobby, divided into spaces called topics. Every five minutes, a temperature sensor posts the value 26.5 in the living-room/temperature space. Home Assistant subscribes to that space and receives every new value. The broker is the server that provides the noticeboard and distributes its messages.

The publisher does not need to know who is reading, and subscribers do not need to know who published the message. You can therefore add any number of devices and subscribers without directly connecting each one to every other participant.

Install a broker

The official MQTT documentation recommends the Mosquitto Broker App, formerly called the Mosquitto add-on, as the simplest option. It can also be installed automatically while you configure the MQTT integration.

To add the integration, open Settings > Devices & services, select Add integration in the lower-right corner, and choose MQTT.

Discovery: the compelling part

This is why Zigbee2MQTT and Tasmota feel so seamless: pair a new sensor in their interface, and its entity appears automatically in Home Assistant a few seconds later.

After initial setup, the documentation distinguishes between two kinds of change:

• Change the broker connection, such as its IP address or credentials: open Settings > Devices & services, select the MQTT integration, open the three-dot menu, and select Reconfigure.
• Change discovery and related options: on the same MQTT integration page, select Configure MQTT Options.

Button labels vary by release and language. If the wording differs, look for the three-dot menu and the options button on the integration page.

Local HTTP: a last resort, but a useful one

Some devices provide no supported protocol but do expose a web interface or an HTTP endpoint. The rest_command integration can call that API. It must currently be configured in configuration.yaml:

rest_command:
  open_gate:
    url: "http://192.168.1.50/api/open"
    method: post
    verify_ssl: false

Documented parameters include url, which is required and supports templates; method, which defaults to get and accepts get, patch, post, put, or delete; headers; payload; verify_ssl, which defaults to true; and timeout, which defaults to 10 seconds. The example disables verify_ssl because small devices on a private LAN often lack a valid certificate. Do not disable verification when calling an internet service. Once configured, call it from an automation or script as follows:

actions:
  - action: rest_command.open_gate

Bluetooth LE: inexpensive and efficient, but short-range

Bluetooth Low Energy (BLE) devices are often the least expensive, and a coin cell can power one for a long time. The limitation is equally direct: Bluetooth signals penetrate walls poorly, and Bluetooth does not form a mesh, so a device in one room may not reach the next.

Two operating modes

The Home Assistant Bluetooth integration provides three scanning modes: Auto, which listens passively most of the time and performs brief active scans; Active, which scans continuously for the fastest updates at the cost of more power; and Passive, which only listens and has the least effect on battery life. According to the official documentation, Auto mode uses about 95% less scanning power than continuous active scanning. Unless you have a specific reason to change it, leave the mode on Auto.

Add it under Settings > Devices & services > Add integration > Bluetooth.

Bluetooth Proxy: put a receiver in every room

Because Bluetooth has limited range, do not rely exclusively on the host’s own Bluetooth radio. Place an inexpensive device in each room to receive Bluetooth signals, then forward them to Home Assistant over Wi-Fi or Ethernet. This is a Bluetooth proxy.

The official Bluetooth documentation explains that the integration can receive advertisements from remote scanners. It specifically lists ESPHome on ESP32 devices, Shelly Gen2 and later devices, and SMLIGHT SLZB-U.

Build an ESPHome Bluetooth Proxy

Buy an inexpensive ESP32 development board, install ESPHome, and use these core configuration lines:

esp32_ble_tracker:

bluetooth_proxy:
  active: true

The ESPHome documentation highlights the following points:

• Use an ESP32-family board. The documentation recommends the esp-idf framework for the ESP32 platform because the alternative arduino framework uses substantially more memory and performs less well for this purpose.
• active enables the proxy to make active connections. Documentation for different versions is inconsistent about its default, so explicitly setting active: true, as above, makes the intended behavior unambiguous.
• connection_slots controls the number of simultaneous active connections and defaults to 3. The documentation recommends no more than 5 to avoid memory problems; with the esp-idf framework, the maximum is 9. Each slot uses about 1 KB of memory, and the value cannot exceed the limit configured under esp32_ble_tracker as max_connections.
• Ethernet-connected boards such as Olimex ESP32-PoE-ISO are generally more reliable because Bluetooth does not have to compete with Wi-Fi for the 2.4 GHz radio.

KNX and Modbus: protocols for buildings and industry

These are professional-grade protocols. You will rarely encounter them in consumer marketplaces, but a newly built smart home or a commercial office may use one throughout the building. Both are wired, exceptionally reliable, and capable of operating for decades—but they also demand specialist knowledge to configure.

KNX: the bus inside the walls

KNX is a European standard for building automation. Switches, covers, and HVAC controllers all connect to a dedicated bus cable. Its defining feature is that it can operate without a central controller. Assign a living-room wall switch and light to the same group address, and the switch still operates the light even if Home Assistant is offline.

A Group Address is fundamental to KNX. It resembles the three-part number 1/2/3. Think of it as a slot on a noticeboard: a switch posts “on” to 1/2/3, and every light subscribed to that address turns on. The official KNX integration documentation accepts group addresses as strings or integers; 1/2/3 is the three-level format.

Configure the KNX integration through the UI under Settings > Devices & services > Add integration. The official documentation lists three connection methods:

Secure Tunneling and KNX IP Secure Routing provide encrypted alternatives. The documentation also describes a KNX panel that creates entities, configures devices, and manages exposures directly in the frontend without handwritten YAML.

Modbus: the common language of industrial equipment

Modbus is a veteran industrial protocol dating from 1979. It remains ubiquitous in electricity meters, variable-frequency drives, PLCs, industrial HVAC controllers, and solar inverters. Its model is extremely simple: a device contains numbered locations called registers. You read a register and receive a number; the manufacturer’s register map tells you what that number means.

Modbus has two common connection methods:

• Modbus RTU: Runs over physical RS-485 wiring. It generally requires a USB-to-RS-485 adapter connected to the host. Cables can run long distances and resist interference well.
• Modbus TCP: Runs over the network, and the device has its own IP address. It is considerably easier to configure.

The official Modbus integration currently must be configured in YAML, and Home Assistant must be restarted after a change. It supports four connection types: tcp, udp, rtuovertcp, and serial. A minimal configuration looks like this:

modbus:
  - name: modbus_hub
    type: tcp
    host: 192.168.1.60
    port: 502
    sensors:
      - name: Office master meter
        address: 100
        input_type: holding
        device_address: 1

For an RS-485 serial connection, use these key fields instead:

modbus:
  - name: modbus_hub
    type: serial
    port: /dev/ttyUSB0
    baudrate: 9600
    bytesize: 8
    method: rtu
    parity: E
    stopbits: 1

The documentation specifies these key parameters and defaults:

The official documentation currently lists seven entity platforms: sensor, switch, binary sensor, climate, cover, fan, and light.

Five checks and a decision process before you buy

This is the most practical part of the chapter. Bookmark it and work through it before every purchase.

Five checks

1. Which protocol does it actually use?

   Read the product title and specifications. If you cannot find Zigbee, Z-Wave, Matter, Thread, or Bluetooth, and the listing mentions only “smart,” “Wi-Fi connectivity,” or “mobile remote control,” treat it as a cloud-dependent Wi-Fi device. When one model comes in several protocol versions, the suffix in the model number is often decisive.

2. Can it operate without the cloud?

   Look for “local control” or “local API.” Conversely, treat “requires the XX app” or “account registration required” as warning signs of cloud dependence. Matter-certified devices provide greater assurance here because Matter is designed for local operation.

3. Does Home Assistant have a compatible integration?

   Before ordering, search for the brand at home-assistant.io/integrations/. An official integration is ideal. If only a HACS custom integration is available, check whether the project is still maintained; approach one that has not been updated for six months with caution.

4. Will you need another gateway?

   Some vendors tie their Zigbee products to a proprietary gateway. If you already own a general-purpose Zigbee coordinator, you can usually pair the device directly without that gateway. Some brands, however, use proprietary commands that limit a general-purpose coordinator to basic on/off control. Before buying, search for the brand name with “ZHA” or “Zigbee2MQTT” and read community reports.

5. Will replacements still be available?

   A model that is readily available in your region and widely discussed by the community is a better choice than one with impressive specifications sold by a single overseas retailer. You will appreciate that decision when you need a second unit three years from now.

Purchase decision guide

Work through these situations in order to identify a sensible starting point:

Troubleshooting common problems

1. One device frequently shows “Offline” or “Unavailable”

   First determine whether every device has dropped offline or only one. If all devices are unavailable, inspect the coordinator or gateway: check for a loose USB connection, a USB 3 port, or another application claiming the adapter. If only one device fails, signal quality is the likely cause. It may be too far from its nearest router device or obstructed by a structural wall, metal door, mirror, or aquarium. Add a permanently powered device between them to provide a relay. For a battery device, check the battery first—many people spend three hours investigating the network only to discover a flat battery.

2. A Zigbee device is unstable only five metres from the coordinator

   Inspect the USB connection. The official documentation explicitly says not to use a USB 3.x port, because USB 3 noise directly interferes with 2.4 GHz. Then confirm that an extension cable moves the adapter away from the host and that no Wi-Fi access point sits beside the coordinator. ZHA users can open Show map under Settings > Zigbee and inspect LQI and RSSI; an especially low value identifies the weak link.

3. The mesh does not reach the farthest room

   Remember that only permanently powered router devices relay mesh traffic; battery devices do not. Installing ten battery sensors in the farthest room does nothing to extend the network. Instead, add a mains-powered Zigbee plug or bulb at an intermediate point such as a corridor or landing. The distant devices may need to be paired again, or may take some time to adopt the new route automatically.

4. A Matter device repeatedly fails to pair

   Check every requirement in the official documentation: IPv6 is enabled under Settings > System > Network and set to Automatic or Static; mDNS and multicast traffic can move freely across the network and are not blocked by a VLAN or AP isolation; you are using the mobile Companion app rather than a browser; Android location permission is set to “Allow all the time”; and, for Matter over Wi-Fi, the phone is on the same 2.4 GHz network as the device. Missing any one of these five requirements can prevent pairing.

5. A newly purchased device is locked to the vendor’s gateway

   The symptoms are a Zigbee device that will not pair with a general-purpose coordinator, or one that pairs but exposes only basic switching while every advanced function disappears. The vendor is using proprietary commands. Two remedies are possible: check whether Zigbee2MQTT has a matching device definition, because its community often reverse-engineers such devices; or buy the vendor gateway and determine whether it provides a local API. The only long-term solution is to read community reports before your next purchase.

6. Half the devices stop working when the internet goes down

   This is the classic sign of cloud dependence. Use the internet-outage drill above to identify the affected devices, then label them. In the short term, move important automations involving safety or lighting to local triggers and devices. In the long term, replace cloud-dependent products gradually. Door locks and alarms in particular must never rely exclusively on the cloud.

7. The Modbus integration does not start after configuration

   The most common cause is defining the connection without defining an entity. The official documentation requires at least one entity under each Modbus hub, or the integration will not load. You must also restart Home Assistant after changing Modbus configuration; reloading alone is insufficient. A serial-device path such as /dev/ttyUSB0 may also change when USB devices are reconnected in a different order.

Frequently asked questions