Single-board computer integration Raspberry Pi Integration into a smart home ecosystem often begins with choosing a local network connection method. Although a wired Ethernet connection is considered the most stable solution for automation servers, the physical location of the router doesn't always allow for cable runs to the device's installation location. In such cases, the only option is to use the wireless interface built into the board.
Setup process wireless connection Home Assistant OS, based on the Home Assistant operating system, has its own unique characteristics that differ from a standard Linux installation. Users must take into account the specifics of the containerized environment and file system access restrictions. Proper network configuration at the outset ensures the smooth operation of all integrations and automations in the future.
In this guide, we'll cover Wi-Fi activation methods in detail, from initial setup via configuration files to management via the graphical interface. You'll learn how to avoid common mistakes when entering security settings and how to prioritize wireless connections when a LAN port is active.
Preparing equipment and choosing a connection method
Before you begin software configuration, you need to make sure your hardware is compatible. Most modern models, such as Raspberry Pi 3, 4 And Zero W/2W, are equipped with a built-in wireless module. However, for older versions, for example Pi 1 or Pi 2, you will need an external USB adapter that supports access point mode and has drivers in the Linux kernel.
There are two main approaches to configuring a network: using a file network-config on the boot partition or editing the system file connection.json After OS installation. The first method is preferred for initial image deployment, as it does not require access to the operating system console.
It is important to understand that Home Assistant is critical to its operation. static IP addressDynamically assigning addresses by a router can cause integration devices in smartphones or voice assistants to stop responding after rebooting the equipment, as they will attempt to connect to the old address. Therefore, network configuration should be done with the address fixed.
Setting up Wi-Fi during initial OS installation
The most reliable way to get a Raspberry Pi to connect to the network immediately after first powering it on is to create a special configuration file on the FAT partition of the memory card. This method works before the operating system kernel loads and allows the device to obtain an IP address during the initialization phase.
To implement this method, you will need a computer running Windows, macOS, or Linux. After writing the Home Assistant image to the microSD card, in the root of the boot partition (usually called hassos-boot) you need to create a text file with the name network-config.yamlThis is where all the necessary network parameters are entered.
⚠️ Warning: YAML syntax is indentation-sensitive. Using tabs instead of spaces or breaking the indentation structure will result in the file being ignored by the system, and the device will be unable to connect.
The file contents must contain your wireless network information. Below is an example of the correct structure for connecting to a home router using WPA2 encryption:
version: 1wifi:
networks:
- ssid: "Your_network_name"
psk: "Wi-Fi_Password"
priority: 1
If your network is hidden (does not broadcast SSID), you need to add the parameter hidden: true in the appropriate block. It is also worth noting that the field priority Allows you to set network priority if the device is located within the coverage area of several routers with the same name (roaming).
Network configuration via the Home Assistant interface
If the system is already installed and accessible via a local IP address, but you need to change Wi-Fi settings or switch from a cable to a wireless network, the built-in interface is the most convenient option. However, it's worth remembering that the standard Home Assistant web interface doesn't have a direct "Connect to Wi-Fi" button in the main settings, as network management is delegated to the operating system.
To manage network interfaces in Home Assistant OS, an addon is used. File editor or Terminal & SSH, which allows you to edit system files, or the command ha network in the CLI. But the easiest way for the user is to create or edit a file connection.json in the boot partition, if there is physical access to the card, or using a terminal.
Let's look at the configuration option via the terminal, which is available after installing the add-on. Terminal & SSHYou will need to log in and use the utility. nmcli (NetworkManager command line interface), which manages the network in Home Assistant OS.
First, scan available networks to make sure your router is visible:
nmcli dev wifi listOnce the network is detected, use the command to connect. Please note that the password in the command will be visible in the history, so be careful when working on shared screens:
nmcli dev wifi connect "SSID_network" password "Your_password"☑️ Check before connection
After the command is successfully executed, the system will attempt to obtain an IP address. The connection status can be checked by restarting nmcli or through the router's web interface. If the connection is established, it will be saved and automatically activated upon boot.
Working with the wpa_supplicant.conf file
In some scenarios, especially when using older versions of images or custom builds, manual editing of the file may be required. wpa_supplicant.confThis file is the de facto standard for managing wireless connections in Raspberry Pi-based Linux environments.
The file is usually located in the section boot (available with Windows) or by path /etc/wpa_supplicant/wpa_supplicant.conf within the system. For Home Assistant OS, it's preferable to place it on the boot partition so that the configuration is applied before the OS fully loads.
The file structure should look like this:
country=RUctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
network={
ssid="Network_Name"
psk="Password"
key_mgmt=WPA-PSK
}
Parameter country=RU This is critical for the proper operation of the wireless module. It determines the permitted frequency channels and transmitting power according to the laws of your country. If you enter an incorrect country code, the Wi-Fi module may not start or may operate unstable.
⚠️ Caution: When editing a file on Windows, use a text editor that preserves UTF-8 encoding without the BOM (e.g., Notepad++). The standard Notepad may add hidden characters that will prevent the file from being read by a Linux system.
If you use multiple networks (for example, main and guest), you can add multiple blocks. networkThe system will try to connect to them in descending order of priority or according to the list.
Troubleshooting 5GHz Band and Static IP Issues
Modern routers often operate in two bands: 2.4 GHz and 5 GHz. Raspberry Pi Wi-Fi modules (especially those prior to version 4) may have limited support for 5 GHz or may operate unstable in this band due to antenna design issues. If you're experiencing connection issues, try temporarily separating the networks on your router by assigning unique names to each band.
To force connection to a specific band or channel in the configuration network-config.yaml or wpa_supplicant.conf You can specify the frequency. However, most often, the problem is solved by selecting a less congested channel in the router settings.
Below is a comparison table of range characteristics to help you understand which one to choose for your scenario:
| Characteristic | 2.4 GHz band | 5 GHz band |
|---|---|---|
| Range | Tall (breaks through walls better) | Low (fades strongly) |
| Transfer speed | Average (up to 150 Mbps) | High (up to 800+ Mbps) |
| Workload | High (a lot of interference from neighbors) | Low (many free channels) |
| Compatibility | Supports all devices | Only modern modules |
For Home Assistant, which transmits mainly text commands and sensor statuses, high speed is not as important as ping stability. Therefore, the range 2.4 GHz is often a preferable choice, especially if the server is located far from the router.
How to assign an IP address to a router?
The most reliable way to get a static IP is to reserve an address on your router rather than configure it internally on your Raspberry Pi. Find the "Static Lease" or "Address Reservation" section in your DHCP settings, select your Raspberry Pi's MAC address, and assign it a permanent IP address. This will prevent address conflicts.
Diagnostics and prioritization of interfaces
A common situation: a Raspberry Pi is connected via both a cable and Wi-Fi. In this case, the operating system must select one interface for primary traffic. By default, the wired connection (Ethernet) is prioritized, as it is considered more reliable.
If you need to force Wi-Fi to be used even when a cable is connected (for example, to test wireless network speed or if the LAN port is used for other purposes), you'll need to change the interface metrics. In Home Assistant OS, this can be done by creating a network configuration file with specified priorities.
To diagnose connection problems, use the command ip addr to view assigned addresses and ip route to check the routing table. If the default gateway (default via) indicates an incorrect interface, traffic will go to the wrong place.
⚠️ Note: Network settings and command interfaces may change with Home Assistant OS updates. Always consult the project's official documentation if standard commands stop working.
It is also useful to use the utility ping To check the connection to the gateway and external resources, run a continuous ping to the router's address to assess the stability of the wireless signal over time:
ping -c 10 192.168.1.1A high packet loss rate or sudden spikes in response time indicate a poor signal, interference, or channel congestion. In such cases, it is recommended to change the Wi-Fi channel on the router or move the Raspberry Pi closer to the signal source.
Why can't my Raspberry Pi see my Wi-Fi network?
There are several possible causes: the module doesn't support the 5 GHz frequency (if the network only supports it), the region (country code) is incorrect, the signal is too weak, or the network is hidden. Check the boot logs or try connecting the phone as an access point using your network's name.
Is it possible to use a USB Wi-Fi adapter instead of the built-in one?
Yes, Home Assistant OS supports many popular chipsets (Realtek, MediaTek). However, the driver must be built into the kernel. Before purchasing, check the compatibility of your specific model on the community forum.
How do I reset my network settings to factory defaults?
The easiest way is to delete the file network-config.yaml or connection.json From the memory card's boot partition. At the next boot, the system will attempt to obtain settings automatically via DHCP.
Does WPA3 encryption affect the connection?
Older Raspberry Pi models may not support the WPA3 standard. If you have a newer router that requires WPA3, try enabling mixed mode (WPA2/WPA3) or creating a separate guest network with WPA2 for smart home devices.