-
-
Notifications
You must be signed in to change notification settings - Fork 20
Bluetooth
Ava turns an Android device into a full Bluetooth gateway for Home Assistant — presence detection, BLE proxy, and room-level triangulation, all without an ESP32.
Compatible with Android 5-16.
0.6.0 added IRK support for private address resolution and ESPHome 2026.8.1 compatibility. 0.6.1 hardened scanning for screen-off operation and completed tracked-device IRK management. 0.6.2 fixed presence stopping after screen-off on some Samsung/ROM combinations. 0.6.3 added Bluetooth proxy self-recovery with stale scanning detection and system radio check. 0.7.3 added presence AI with flap suppression, peer-deaf coordination, and dark-wake deaf-window grace for multi-Ava homes.
Most Bluetooth-to-Home-Assistant solutions require dedicated ESP32 nodes or USB dongles. Ava uses the Android device's built-in Bluetooth chip, which is already there, already powered, and already connected to WiFi.
- Native ESPHome Bluetooth proxy — HA sees Ava as a native proxy, no custom integration needed
- BTHome advertisement forwarding — BLE advertisements from BTHome devices (thermometers, plant sensors, scales, etc.) are forwarded to HA in real time with deduplication
- Multi-device claim coordination — when multiple Ava devices are on the same network, they coordinate to avoid double-claiming the same BLE device
- Chip-aware scanning — Ava detects the Bluetooth chip at runtime and applies vendor-specific workarounds for known issues
- Watchdog with self-healing — if BLE advertisements stop arriving, Ava detects the stall and automatically restarts scanning
- Wake word arbitration — when multiple Ava devices hear the same wake word, they arbitrate so only one device responds
- Low-end device support — even Echo Show devices and cheap tablets with broken BLE chips can run in compatibility mode with root
Note: The Bluetooth proxy feature is not open source and is only available in release builds.
Detect if phones, wearables, and other Bluetooth devices are nearby. Ava scans for tracked devices at regular intervals and reports presence/absence to Home Assistant.
- Track up to 5 devices by MAC address
- RSSI threshold filtering (ignore weak signals)
- Configurable away delay (prevent flicker when device briefly goes out of range)
- Bonded device support (automatically picks up system-paired devices)
- Real-time presence state in HA
Ava acts as a BLE proxy, forwarding all Bluetooth Low Energy advertisements to Home Assistant as if HA had a direct Bluetooth connection.
- Forwards all BLE advertisements to HA (not just tracked devices)
- Native HA Bluetooth integration — auto-discovered, zero config
- BTHome device detection with automatic slot allocation
- Active and passive scan modes
- Adjustable scan power (High / Balanced / Low)
- Advertisement deduplication (prevents duplicate data flooding HA)
- Scan session rotation (prevents Android BLE stack from going stale)
Ava can advertise itself as a BLE device, broadcasting its presence to nearby Bluetooth scanners. This is useful for:
- Bermuda room presence triangulation
- Detecting which room Ava is in
- Multi-device proximity sensing
Ava runs a continuous scan loop:
- Scans for BLE devices at a fixed interval (6 seconds on normal devices, 30 seconds on low-end chips)
- For each tracked device found, records the strongest RSSI seen during the scan cycle
- If RSSI exceeds the threshold, marks the device as "present" and resets the away timer
- If a tracked device is not seen for the configured away delay, marks it as "away"
- Presence state is published to Home Assistant as a binary sensor
Presence logic:
| Status | Condition |
|---|---|
| Present | Device detected with RSSI above threshold |
| Away | Device not detected for the configured away delay |
When the RSSI threshold or away delay is changed in settings, Ava immediately re-evaluates all tracked devices — no need to wait for the next scan cycle.
The proxy scan runs independently from presence detection:
- Ava continuously scans for BLE devices and forwards all advertisements to HA
- A watchdog monitors the advertisement stream — if no data arrives within a stale threshold, scanning is automatically restarted
- Scan sessions are periodically rotated to keep the BLE stack healthy
- Duplicate advertisements are filtered to prevent data flooding
- BTHome devices are automatically detected and allocated to connection slots
When multiple Ava devices are on the same LAN, they coordinate BLE device claims:
- Each Ava device has a unique ID
- When a device claims a BLE peripheral, it notifies other Ava devices on the network
- Other Ava devices respect existing claims and do not attempt to connect to the same peripheral
- Up to 5 BLE peripherals can be claimed per Ava device
- This prevents duplicate data and connection conflicts when deploying multiple Ava devices in the same area
When multiple Ava devices are within earshot, they arbitrate wake word events:
- Each Ava device generates a unique random ID at startup
- When a wake word is detected, the device broadcasts an arbitration signal
- All Ava devices that heard the same wake word compare IDs
- The device with the lowest ID wins and responds; others stay silent
- Arbitration completes within 80ms — no perceptible delay
- If arbitration fails (network error, no response), the device responds as fallback
This means placing 2-3 Ava devices in different rooms will not cause all of them to respond to a single wake word — only the closest one (or the one that wins the arbitration) responds.
The Bluetooth proxy now monitors for stale scanning and automatically attempts a controlled soft restart.
On rooted or Shizuku-enabled devices, Ava can perform deeper recovery when the Android Bluetooth stack becomes unresponsive. Recovery avoids interrupting active GATT connections, temporarily pauses conflicting BLE advertising when necessary, and is cancelled immediately when the Bluetooth master switch is disabled.
Ava also checks whether the system Bluetooth radio is disabled. Root, Shizuku, and device-owner installations can restore it silently; standard installations receive the normal Android confirmation prompt.
Go to Settings -> Bluetooth
| Setting | Description | Default |
|---|---|---|
| Device Detection | Turn on Bluetooth presence detection | Off |
| RSSI Threshold | Signal strength threshold (left = near, right = far) | -80 dBm |
| Away Delay | Seconds before marking as away (min: scan interval + 1) | 120s |
| Add Bluetooth Device | Add devices to track by MAC address | — |
| IRK Resolution | Resolve private addresses from paired-device bonding (root/Shizuku) | Auto |
Bluetooth Presence supports IRKs (Identity Resolving Keys) for paired devices that rotate their private Bluetooth address. With root or Shizuku access, Ava reads the IRK from system bonding data and uses it to keep identifying the same device after its MAC address changes.
- Exact MAC matching still takes priority. IRK resolution is only a fallback for resolvable private addresses (RPA); it does not interfere with ESPHome Bluetooth proxy forwarding.
- Ava attempts to read the IRK automatically and only stores it after validating it against a nearby advertisement.
- In 0.6.1+, the tracked-device management sheet lets you retry automatic bond-store lookup or paste, replace, and clear a 32-character hexadecimal or Base64 IRK manually. Ava validates and normalizes the key before using it.
- An IRK can identify a device that is still advertising under a rotated address. It cannot force a phone or watch to advertise after its operating system stops broadcasting in Doze.
Each tracked Bluetooth device can have a custom alert sound that plays when the device's presence state changes. This is useful for notifications like "phone arrived home" or "watch left range".
Setup: Tap the hollow bell icon next to a tracked device to open the alert sound picker.
Trigger options:
| Trigger | Description |
|---|---|
| Nearby | Play sound when the device comes into range (was away → present) |
| Not nearby | Play sound when the device goes out of range (was present → away) |
Sound sources:
- System ringtones: All system notification sounds are listed in the picker
-
External audio: Select any audio file from device storage via the system file picker (
+ Select External Audio) - Custom sounds: Up to 24 custom audio URIs are persisted across sessions; previously used custom sounds appear in the picker list
- None: No alert sound (default)
Behavior:
- When the trigger condition is met, the selected sound is played through the TTS audio player
- A toast notification is shown with the device name and state (e.g., "iPhone is nearby" / "iPhone is not nearby")
- Alert sound and trigger are stored per-device in the tracked device data
- Custom URIs require persistable URI permission (granted automatically on file selection)
i18n: All alert-related UI text and toast messages are localized in 6 languages (English, Chinese, German, Russian, Portuguese, Vietnamese).
| Setting | Description | Default |
|---|---|---|
| BLE Gateway / Mesh | Turn on Bluetooth proxy | Off |
| Scan Mode | Active or Passive scanning | Active |
| Scan Power | High Performance, Balanced, or Low Power | High |
| Mode | Description |
|---|---|
| Active Scan | Actively request scan responses — more data, higher power consumption |
| Passive Scan | Listen only — lower power, may miss some advertisement types |
| Power | Description | Use When |
|---|---|---|
| High Performance | Maximum scan frequency, lowest latency | Device is plugged in, need real-time data |
| Balanced | Moderate scan frequency | Typical use, battery-powered |
| Low Power | Reduced scan frequency | Battery conservation is priority |
Ava detects the device's BLE capabilities at runtime and classifies it into a tier. This is not based on the Bluetooth version number reported by apps — it is based on what the Android BLE stack actually supports at the API level.
| Tier | Description | Typical Devices |
|---|---|---|
| Full | All BLE features available, maximum connections | Modern phones (Pixel, Samsung flagship), Android 8+ |
| Balanced | Most features work, some limitations | Mid-range devices, older flagships |
| Compatibility | Limited mode, reduced scan rate, may need root | Echo Show, cheap tablets, low-end chips |
| Capability | What It Means |
|---|---|
| Offloaded Filtering | Hardware can filter scan results — saves CPU, enables targeted scanning |
| Multiple Advertisement | Can broadcast multiple BLE ad slots simultaneously |
| Extended Advertising | BLE 5.0 extended advertising — larger payload, longer range |
| LE Coded PHY | Long-range coded PHY — up to 4x range in open space |
| LE 2M PHY | 2M PHY — high-speed data transfer |
Tier assignment:
- Full: Offloaded filtering + Multiple advertisement + at least one advanced PHY
- Balanced: At least 2 basic capabilities, or any advanced BLE 5 signal
- Compatibility: Everything else
Some devices report BLE 5.0 in specs but do not expose all features through Android APIs. Ava tests at runtime, not by reading spec sheets.
When multiple Ava devices in the same home are all scanning for Bluetooth presence, they can disagree about which room a person is in. A phone's BLE signal bounces off walls and bodies — the same person can appear in two rooms at once, or flap back and forth every few seconds.
Presence AI is Ava's multi-device presence arbitration system. It runs entirely on-device over the local network — no cloud, no central server.
| Problem | How Presence AI Handles It |
|---|---|
| Flapping — person appears in room A, then B, then A every few seconds | Strike-based flap suppression: each room accumulates strikes before claiming a move. Strikes decay over time, so a brief signal dip doesn't trigger a room change |
| Stale coverage — a room's scan data is too old to trust | Coverage expires after a staleness threshold; stale rooms don't participate in arbitration |
| Peer deafness — another Ava in the group stopped responding | Hold-away grace period prevents a single unresponsive peer from blocking arbitration for the whole group |
| Dark-wake deafness — a peer wakes briefly but its BLE stack hasn't initialized | Deaf-window grace gives the peer time to come online before treating it as absent |
| Ambient stale — background noise level is too old to compare against | Ambient data has its own staleness threshold, separate from scan coverage |
Ava devices share presence state over the local network. Each device reports what it sees; the group arbitrates who is where. No single device is the "boss" — arbitration is distributed and symmetric.
- A device that sees a stronger, fresher signal wins the claim
- A device whose data is stale or whose BLE stack is recovering is given grace, not penalized
- When a device leaves the group (screen off, app killed), its claims expire naturally
- Does not send audio or personal data to other devices — only presence state
- Does not require a central server or Home Assistant involvement
- Does not override Home Assistant's own presence entities — it feeds into them
Path: Ava Settings → Bluetooth → Presence AI
Devices with limited BLE chips (Echo Show, cheap tablets, some MediaTek/Spreadtrum/Allwinner devices) run in compatibility mode:
- Scan interval is increased to 30 seconds (vs 6 seconds on normal devices) to maintain WiFi stability
- Bermuda may show skull or exclamation icons — this is expected, not a bug
- Bluetooth media playback is not supported
- Root access is typically required for stable operation
- Built-in Bluetooth presence detection may have reduced accuracy
- Ava can auto-grant location permission via root on pre-Android 12 devices with low-end BLE chips (Android requires location permission for BLE scanning)
Ava detects the Bluetooth chip at runtime and applies appropriate behavior:
| Vendor | Known Issues | Ava's Response |
|---|---|---|
| MediaTek | Scan stalls after several minutes | Watchdog detects stall, restarts scan |
| Spreadtrum | Scan filters unreliable, RSSI inaccurate | Falls back to unfiltered scanning |
| Allwinner | Passive scan broken, batch scan broken | Forces active scan, disables batching |
| Qualcomm | Generally stable | Standard scan mode |
| Samsung (Exynos) | Generally stable | Standard scan mode |
On non-low-end devices, Ava runs a watchdog that monitors the BLE advertisement stream:
- If no advertisements arrive within a stale threshold, the scan is considered stalled
- Ava forces a clean restart of the Bluetooth stack
- After Bluetooth recovers (typically 5 seconds), scanning resumes automatically
- Scan sessions are also periodically rotated to keep the BLE stack healthy
This means Ava's Bluetooth proxy is self-maintaining — it does not require manual intervention or app restarts to recover from BLE stack issues.
Bluetooth presence and proxy operation now adapt when Android locks the screen. Ava uses targeted filters, a bounded wake lock and duty-cycled compatibility scanning instead of assuming every manufacturer will keep a normal application scan alive.
- Directed scan filters are built from tracked MAC addresses, manufacturer IDs and service UUIDs so Android does not suspend an unfiltered BLE scan while the device is locked.
- When a vendor stack stalls, Ava first pauses and restarts scanning without disrupting Wi-Fi.
- Shizuku can request a deeper Bluetooth recovery.
- Rooted devices can use the bundled native HCI/MGMT scanner when Android's public scanner is no longer sufficient.
- The low-level path detects common chipset and manufacturer quirks, coordinates presence, proxy and advertising ownership, and avoids repeatedly killing the Bluetooth process. This is especially important on older or lower-memory hardware where Bluetooth and Wi-Fi share resources.
Fixed Presence Detection stopping after the screen turns off on some Samsung devices and customized Android ROMs. Ava builds directed scan filters from tracked MAC addresses, manufacturer IDs, and service UUIDs so Android does not suspend an unfiltered BLE scan while the device is locked. If scanning stalls, Ava restarts the scan path according to device capabilities and coordinates Bluetooth resources between Presence Detection, the Home Assistant Bluetooth Gateway, and the BLE proxy.
Note: Presence Detection and the Home Assistant Bluetooth Gateway remain separate systems. Disabling the corresponding feature or the Bluetooth master switch cleans up its scan, advertising, and proxy resources independently.
When Ava's Bluetooth proxy is disabled, Home Assistant can leave behind a stale bluetooth config entry that still shows in the integrations list. 0.7.3 adds automatic cleanup: when the proxy is turned off, Ava removes its remote Bluetooth scanner config entry from Home Assistant so the integrations page stays clean.
This runs automatically — no manual action needed. The cleanup uses HA's REST API to delete the orphaned entry.
| Permission | Android Version | Description |
|---|---|---|
| BLUETOOTH_SCAN | 12+ | BLE scanning |
| BLUETOOTH_CONNECT | 12+ | Connect to BLE devices |
| BLUETOOTH | 5-11 | Basic Bluetooth access |
| ACCESS_FINE_LOCATION | All | Required by Android for BLE scanning |
On pre-Android 12 devices with low-end BLE chips, Ava can auto-grant location permission via root if it is missing. Android requires location permission for BLE scanning even when the app does not use location data.
binary_sensor.your_device_name_bluetooth_presence
Bluetooth proxy natively integrates with Home Assistant's Bluetooth integration:
- Enable BLE Gateway in Ava Settings -> Bluetooth
- Add the Bluetooth integration in HA (Settings -> Devices & Services -> Add Integration -> Bluetooth)
- Ava will be automatically discovered as a Bluetooth proxy
- BLE devices in range of Ava will appear in HA as if connected to a local Bluetooth dongle
Ava works with the Bermuda integration for Bluetooth triangulation and room presence. Ava broadcasts BLE advertisements that Bermuda can use to estimate which room the device is in.
Setup:
- Install Bermuda from HACS
- Ava's BLE advertisements will be picked up by Bermuda
- Configure Bermuda to use Ava devices as beacons
- Room presence sensors will appear in HA
Supported BLE Device Types (via proxy):
- Bluetooth thermometers/hygrometers (Xiaomi, Govee, etc.)
- Bluetooth scales (Mi Scale, etc.)
- Bluetooth plant sensors (Xiaomi Mi Flora, etc.)
- Bluetooth smart locks
- BTHome devices (buttons, sensors, etc.)
- Any BLE device supported by HA's Bluetooth integration
Arrival — turn on lights and climate:
automation:
- alias: "Arrival Home"
trigger:
- platform: state
entity_id: binary_sensor.ava_bluetooth_presence
to: "on"
action:
- service: light.turn_on
target:
entity_id: light.living_room
- service: climate.set_temperature
target:
entity_id: climate.living_room
data:
temperature: 22Departure — away mode:
automation:
- alias: "Departure - Away Mode"
trigger:
- platform: state
entity_id: binary_sensor.ava_bluetooth_presence
to: "off"
for:
minutes: 5
action:
- service: light.turn_off
target:
entity_id: group.all_lights
- service: climate.set_temperature
target:
entity_id: climate.living_room
data:
temperature: 16
- service: media_player.turn_off
target:
entity_id: media_player.living_roomMulti-device presence — track family members:
Track multiple phones by adding each as a separate tracked device. Each gets its own presence state:
automation:
- alias: "Everyone Left"
trigger:
- platform: template
value_template: >
{{ is_state('binary_sensor.ava_bluetooth_presence', 'off') }}
for:
minutes: 10
condition:
- condition: state
entity_id: binary_sensor.ava_bedroom_bluetooth_presence
state: "off"
for:
minutes: 10
action:
- service: alarm_control_panel.alarm_arm_away
target:
entity_id: alarm_control_panel.homeTurn on devices when entering a room:
automation:
- alias: "Entered Kitchen"
trigger:
- platform: state
entity_id: sensor.phone_room_presence
to: "kitchen"
for:
seconds: 5
action:
- service: light.turn_on
target:
entity_id: light.kitchenFollow-me audio — play music in the room you are in:
automation:
- alias: "Follow Me Music"
trigger:
- platform: state
entity_id: sensor.phone_room_presence
action:
- service: media_player.join
target:
entity_id: >
{% set room = states('sensor.phone_room_presence') %}
{% if room == 'living_room' %} media_player.living_room
{% elif room == 'kitchen' %} media_player.kitchen
{% elif room == 'bedroom' %} media_player.bedroom
{% endif %}Auto-discovered sensors:
When BLE devices are in range of Ava's proxy, they appear in HA automatically. No automation needed — just use the sensor data:
automation:
- alias: "Plant Needs Water"
trigger:
- platform: numeric_state
entity_id: sensor.plant_sensor_moisture
below: 20
action:
- service: notify.mobile_app
data:
message: "The plant needs water (moisture: {{ states('sensor.plant_sensor_moisture') }}%)"Temperature log:
automation:
- alias: "Log Room Temperature"
trigger:
- platform: time_pattern
minutes: "/30"
action:
- service: input_number.set_value
target:
entity_id: input_number.living_room_temp_log
data:
value: "{{ states('sensor.ble_thermometer_temperature') }}"Place Ava devices in different rooms:
Each Ava device acts as an independent BLE proxy. HA will see all BLE devices from all proxies. With Bermuda, you can determine which room a BLE device is closest to:
automation:
- alias: "Door Sensor in Kitchen"
trigger:
- platform: state
entity_id: binary_sensor.ble_door_sensor
to: "on"
condition:
- condition: state
entity_id: sensor.ble_door_sensor_room
state: "kitchen"
action:
- service: notify.mobile_app
data:
message: "Kitchen door opened"No automation needed — this works automatically when multiple Ava devices are on the same network. Only the winning device responds to a wake word. This prevents the "all devices respond" problem common with multiple smart speakers.
- Google Pixel 4a+
- Samsung Galaxy S10+ / Note 10+
- Xiaomi Mi 9+
- Any device with Qualcomm Snapdragon 700+ series
- Samsung Galaxy A series
- Xiaomi Redmi Note series
- Most mid-range Android 8+ devices
- Amazon Echo Show (all generations)
- Cheap Android tablets (Lenovo, Amazon Fire, etc.)
- Devices with MediaTek/Spreadtrum/Allwinner chips
- May require root for stable BLE proxy operation
- Devices without Bluetooth LE (very old Android 5 devices)
- Devices with broken Bluetooth stacks that crash on BLE scan
- Ensure the target device's Bluetooth is on
- Check if the MAC address is correct
- Adjust RSSI threshold — move slider left for near (stricter), right for far (looser)
- Increase away delay to prevent flicker
- Ensure location permission is granted (Android requires it for BLE scanning)
- Try changing scan power to High Performance
- Some devices reduce Bluetooth visibility in sleep mode — check the target device's battery settings
- Change scan power to Low Power or Balanced
- Increase away delay
- Only enable detection when needed (e.g., disable at night)
- If running proxy + presence simultaneously, consider using Balanced power
- Check Bluetooth permissions (Settings -> Permissions)
- Check location permission (required by Android for BLE)
- Ensure the target device is discoverable (not hidden)
- Check if the device is in compatibility mode — low-end chips may need root
- Try resetting Bluetooth:
adb shell am broadcast -a com.example.ava.ACTION_GRANT_BLUETOOTH
This is expected in compatibility mode. The device has limited BLE capabilities. The skull icon means Bermuda is receiving data but the signal quality is reduced. For full functionality, use a device with complete BLE proxy support (Full tier).
- Check if BLE Gateway is enabled in Settings -> Bluetooth
- Check Bluetooth and location permissions
- Check capability tier in Settings -> Bluetooth — if Compatibility, root may be needed
- Restart the Ava service
- If scanning stalls, the watchdog should self-heal within 30 seconds — if not, restart the app
Wake word arbitration is enabled by default. Check:
- All Ava devices are on the same WiFi network
- Multi-Device Arbitration is enabled in Settings -> Voice
- UDP port 19847 is not blocked by the router/firewall
Ava has a built-in watchdog that detects stalled scans and restarts them. If the problem persists:
- Check if the device is in compatibility mode — low-end chips may need periodic Bluetooth adapter resets
- On rooted devices, Ava can kill and restart the Bluetooth process automatically
- If the issue persists, try restarting the Ava service or the device
On Full and Balanced tier devices, yes. On Compatibility tier devices, Bluetooth media playback is not supported — the BLE chip cannot handle simultaneous audio streaming and scanning.
Back to Home
- Quick-Start
- System-Requirements
- Voice-Control
- Chorus-Wake
- ESPHome-Encryption
- HA-Direct-Connection
- Browser
- Screensaver
- Floating-Windows
- Home-Launcher
- Home-Screen-Widgets
- Notification-Scenes
- Quick-Entity
- Sensors
- Backup
- Sendspin
- Bluetooth
- Voice-Messages-Calls
- Music-Playback
- Camera
- Screen-Control
- Intent-Launcher
- ADB-Commands
- Mod-Store
- Ava-Fleet