Windows Native, Zero Pairing, BT Home Gateway
AirFoxBT is a zero-driver, zero-privilege Windows background service and desktop tray gateway. Part of the FoxDen Software suite (alongside inFaux and WireFox), it turns any Windows 10, Windows 11, or Windows Server machine into an ESPHome Bluetooth Proxy (port 6053) for Home Assistant.
AirFoxBT passively sniffs 2.4 GHz airwaves using your PC's Bluetooth adapter or high-gain desktop antenna, decodes beacon telemetry in real time, and streams raw frames directly to Home Assistant over TCP without pairing, bonding, or custom drivers.
Run it completely headless from the CLI or minimized in your system tray, or if you prefer, pop open the rich dark-mode desktop GUI to inspect live sensor cards, RSSI signal meters, and raw BLE ingestion frames in real time.
flowchart TD
Airwaves["2.4 GHz BLE Airwaves<br/>(Sensors, Beacons, Buttons)"] -->|BLE Advertisements| BleWatcher["WinRT BleWatcherEngine<br/>(BleWatcherEngine.cs)"]
BleWatcher -->|Raw BLE Packets| EsphomeProxy["ESPHome Native API Server<br/>(TCP Port 6053)"]
EsphomeProxy -->|TCP / Protocol Buffers| HomeAssistant["Home Assistant<br/>(Zero-Config mDNS Discovery)"]
BleWatcher -->|Parsed Payloads| Decoders["Decoders<br/>(BTHome v2 / ATC / PVVX)"]
Decoders -->|Telemetry Data| ViewModels["SensorCardViewModel"]
ViewModels -->|WPF Data Binding| MainWindow["MainWindow Dashboard & Tray"]
BleWatcher -->|Aggregated Metrics| RestServer["LocalApiService<br/>(REST & SSE Port 8766)"]
Runs entirely in user mode through native Windows Runtime APIs (BluetoothLEAdvertisementWatcher). No Zadig, WinUSB, libusb, or kernel filter drivers required. Your existing Bluetooth mice, keyboards, and headsets keep working normally without interruption.
Implements the official ESPHome Native API Bluetooth Proxy specification. Home Assistant connects directly over TCP port 6053, populating sensors automatically in BTHome, Shelly BLE, and Xiaomi BLE integrations.
Broadcasts _esphomelib._tcp.local from an ephemeral outbound port, avoiding WSAEADDRINUSE port 5353 collisions with Windows Dnscache so Home Assistant discovers the proxy instantly on your network.
Deep-sleeping sensors like the Shelly BLU Door / Window only broadcast when triggered. AirFoxBT caches their verified state and synthesizes periodic keepalives into the proxy stream so Home Assistant never marks your contact sensors unavailable. Includes per-device toggle switches on every card.
Decodes standard BTHome v2 (0xFCD2) payloads (temperatures, humidities, door/window contacts, tilt, illuminance, battery) as well as custom ATC and PVVX firmware (0x181A) on Xiaomi Mijia and Tuya thermometers. Thermometer readings retain priority over transient button wake bursts.
Switch between four deduplication profiles on the fly:
Eco: 15-second deduplication window for crowded airwaves.Balanced: 5-second deduplication window (default profile).Realtime: 1-second deduplication window for fast updates.Raw: Unfiltered firehose streaming every packet directly to Home Assistant.
Provides JSON endpoints at http://localhost:8766/api/sensors, live packet counts at /api/stats, and a Server-Sent Events stream at /api/stream.
Install AirFoxBT directly into %LOCALAPPDATA%\Programs\AirFoxBT without administrator privileges:
irm https://raw.githubusercontent.com/TalviFox/AirFoxBT/main/install.ps1 | iexThe installer automatically stages the executable, configures Windows startup shortcuts, creates Desktop and Start Menu entries, and offers automatic Windows Firewall configuration.
Verify release binary authenticity against official GitHub release SHA-256 hashes before executing:
irm https://raw.githubusercontent.com/TalviFox/AirFoxBT/main/verify.ps1 | iexDownload AirFoxBT.exe from the latest release and run it directly:
.\AirFoxBT.exeCommand line arguments:
--minimized: Starts AirFoxBT minimized directly in the Windows system notification area.--firewall: Checks and prompts to configure inbound Windows Firewall rules for TCP ports 6053 and 8766.
To remove AirFoxBT, its registry startup keys, and shortcuts cleanly:
irm https://raw.githubusercontent.com/TalviFox/AirFoxBT/main/uninstall.ps1 | iexOnce AirFoxBT is running on your Windows PC:
- Open Home Assistant and navigate to Settings -> Devices & Services.
- AirFoxBT will appear automatically under Discovered as an ESPHome device (e.g.
AirFoxBT (HOSTNAME)). - Click Configure, submit without encryption key (unless configured), and confirm the pairing.
- Your BLE sensors within range will immediately appear in Home Assistant under their respective Bluetooth integrations (BTHome, Shelly BLU, Xiaomi BLE).
If Home Assistant resides on an isolated VLAN where mDNS multicast does not cross the boundary, simply click Add Integration -> ESPHome, and enter your Windows PC's IPv4 address with port 6053.
- Windows 10 (Build 19041+) or Windows 11
- .NET 10.0 SDK
AirFoxBT builds with the standard .NET CLI. The release binary is self-contained with no runtime dependencies for end users:
# Standard debug build
dotnet build
# Release compilation
dotnet build -c ReleaseTo compile a single-file, self-contained binary packaged with FoxDen release artifacts, run the automated release pipeline:
powershell -ExecutionPolicy Bypass -File .\release.ps1 -Version 1.0.1The resulting artifacts, checksum tables, and release notes will be generated directly into the publish/ directory.
If AirFoxBT made your Windows BLE setup easier or saved you from buying extra hardware dongles, feel free to support development on Ko-fi.
AirFoxBT is licensed under the PolyForm Noncommercial License 1.0.0. You are free to inspect, modify, fork, and run this software for personal and non-commercial home automation setups.
AirFoxBT is an independent open-source project by FoxDen Software and is not affiliated with, sponsored by, or endorsed by ESPHome, Nabu Casa, or Home Assistant.