BLE Wi-Fi onboarding for HA OS (like Voice Preview Edition)

[jakubhegr18-design]

Describe your core improvement

BLE Wi-Fi onboarding for HA OS — currently, setting up Wi-Fi on a fresh HA OS installation requires an Ethernet cable or manually editing config files. Adding optional BLE-based onboarding (like the Voice Preview Edition already uses) would allow users to configure Wi-Fi directly from the Companion app without any cables or manual steps.

Current limitations

Configuring Wi-Fi on a new HA OS install (Raspberry Pi, x86, etc) requires ethernet or editing config files via the SD card. It's quite annoying when it's mounted somewhere or you don't have a cable handy. There should be an option to configure it wirelessly on generic hardware for the first boot.

Technical benefits

BLE onboarding is already done through the Companion app in Home Assistant Voice Preview Edition - we already have proven it is possible. RPi 4 has built-into Bluetooth already, and the Companion app has BLE onboarding already built-in. Turning on that same pairing mode in HA OS for standard installs would take no additional hardware support and could piggy-back on top of what's already there. It would make HA OS far more accessible for new users and simpler to install in situations where running cables would be difficult.

Additional context

The Voice Preview Edition notably lacks an Ethernet port or SD card slot. This left BLE onboarding as the only option - which works fantastic. There is no need for this magic to be exclusive to this one device when the pieces are already there. Other smart home devices use similar BLE-based onboarding (Sonos, Philips Hue, Matter devices) and it's becoming expected in modern IoT device setup. Implementing this into HA OS would not only hit users expectations but reduce friction for new adopters.

[jakubhegr18-design]

Some other recovery/onboarding options:
Ideally there would be multiple methods supported so that the onboarding system can work however the user wants it to:
Onboarding Methods:
🔵 BLE through Companion app — completely wireless and headless
📄 Config file through USB stick/SD card — there could be a very simple utility on home-assistant.io that prompts the user to enter their Wi-Fi credentials and owner account info, then creates a file (ex. ha-onboard.json) that the user can save to a USB stick. HA OS would look for it on boot, apply the configs, and then delete for security purposes. Sort of like how you can pre-fill Wi-Fi/SSH through Raspberry Pi Imager.
🖥 Monitor — shows QR code or PIN to pair with
🔌 Ethernet — always available for recovery
Possible recovery methods if onboarding was interrupted/hijacked:
Plug in Ethernet and change info
Create config file on USB drive
Hold GPIO button to reset onboarding window
Monitor would show recovery QR/PIN
Options like this would provide every flavor of user a method that best fits their needs — from non-techie to advanced — without needing to buy any extra hardware.

[jakubhegr18-design]

There is another thing to consider as well: not all HA hardware includes Bluetooth. Home Assistant Green, for example, doesn't include a BLE radio.
Devices like that can utilize a Wi-Fi AP onboarding method instead. On first boot it powers up a temporary hotspot, your phone connects to it, you enter your home Wi- Fi credentials, and then it automatically connects.
You might know this process from most routers and their first-time setup.
Essentially this allows each platform to have the optimal onboarding method for the hardware:
🟡 Yellow —> BLE onboarding
🟢 Green —> Wi- Fi AP onboarding
🍓 Raspberry Pi —> BLE (has built-in radio)
🖥️ x86 —> Wi-Fi AP or config file
No one is left behind!