Core Improvement
Setting up Wi-Fi on a HA OS installation today is not easy. It usually requires an Ethernet cable or manual editing of config files. That’s a hassle. A better approach would be to add BLE-based onboarding — something already used successfully in the Voice Preview Edition. It works great and would let users configure Wi-Fi directly from the Companion app. No cables. No manual edits. Just simple setup from your phone.
For devices without Bluetooth — like Home Assistant Green — we could use a Wi-Fi AP hotspot instead. This works similar to router first-time setup. The device creates a temporary Wi-Fi network. The user connects their phone, enters their home Wi-Fi credentials, and the device connects automatically. Then the hotspot shuts down. This is perfect for hardware without Bluetooth.
Current Limitations
Configuring Wi-Fi on a new HA OS install — whether on Raspberry Pi, x86, or other devices — requires either Ethernet or editing config files via an SD card. That’s not ideal. It’s frustrating when the device is mounted in a hard-to-reach place or when you don’t have a cable handy. There’s also no wireless-only setup option for generic hardware during first boot. Users are stuck with workarounds that make the process clunky and confusing.
Technical Benefits
BLE onboarding is already proven, reliable, and successfully used in the Home Assistant Voice Preview Edition. The Raspberry Pi 4 has built-in Bluetooth, so it’s already supported. The Companion app already includes BLE onboarding functionality. No extra hardware is needed — we just need to enable the existing infrastructure. That’s a win for simplicity and user experience.
For devices without Bluetooth, a Wi-Fi AP fallback makes perfect sense. We create a hotspot on first boot. The user connects their phone, enters their home Wi-Fi credentials, and the device connects automatically. Then the hotspot closes. This is perfect for devices like Home Assistant Green, which lack Bluetooth but still need wireless setup.
Onboarding Methods (Hardware-Specific)
Each device gets the optimal method based on its hardware:
Yellow → BLE onboarding
Green → Wi-Fi AP hotspot
Raspberry Pi → BLE (built-in radio)
x86 → Wi-Fi AP or config file
Alternative config-file method:
We can offer a simple utility on home-assistant.io. It prompts for Wi-Fi credentials and owner account information, then creates a file called ha-onboard.json. The user saves this file to a USB stick. When HA OS boots, it reads the file, applies the settings, and then deletes it for security. This is similar to how Raspberry Pi Imager lets users pre-fill settings.
Recovery Methods (if onboarding interrupted/hijacked)
If something goes wrong during setup, users should still be able to recover. Here are the options:
- Ethernet + GPIO button or PIN/QR code — physical access still requires verification
- USB stick config file — using the same utility
- GPIO button reset — to reset the onboarding window
- Monitor recovery QR/PIN — displayed on screen for verification
Security Window
There’s a 24-hour recovery window after successful Wi-Fi connection. During this time, all recovery methods are available: Ethernet, USB config, QR/PIN, and GPIO. After 24 hours, the recovery window closes to ensure maximum security. Even with physical Ethernet access, users must press the GPIO button or enter a PIN/QR code — preventing unauthorized modifications.
Additional Context
Other smart home devices already use BLE-based onboarding: Sonos, Philips Hue, and Matter devices all do it. It’s becoming the expected standard for modern IoT setup.
The Voice Preview Edition notably lacks an Ethernet port or SD card slot — BLE was the only viable option, and it works beautifully. There’s no reason this smooth setup should be exclusive to one device. All the pieces are already there: the app, the hardware, the infrastructure.
This would make HA OS far more accessible for new users and simplify installations in places where running cables is difficult or impossible. A simpler, wireless-first setup would improve the overall experience.