Presence Bridge

Logo

Local iPhone Bluetooth presence and estimated rooms for Home Assistant. Install with HACS, enroll with Presence Pair, and keep presence data in your home.

View the Project on GitHub ravhello/presence-bridge

Troubleshooting

No observer in Home Assistant

The receiver cannot find the app

There is no prompt to accept on the Windows receiver. After scanning, leave Presence Pair open. Only iOS may show an Allow or Pair prompt, and that prompt must be accepted on the iPhone.

The app reports the stage that failed:

After the first proximity check, the Dell keeps the session-specific beacon advertising while the iPhone discovers the GATT service, completes the Bluetooth bond, and writes the protected acknowledgement. The app continues to sample that beacon. Three consecutive readings at or below -82 dBm, or ten seconds without a reading, fail the attempt with PP-PROX-02. Missing samples produce a warning after three seconds. Once the protected exchange finishes, missing beacons during HA persistence are no longer a range failure. The threshold is a conservative radio guard, not a measurement in metres.

Opening the HA panel or local QR helper in more than one tab does not create a second invitation. Every tab receives the same active code during its ten-minute start window; only New code explicitly replaces it. Once the receiver verifies the exact session, the QR is consumed. The attempt has one five-minute deadline; neither retries nor the final verification restart it. A reused Windows bond may not trigger an iOS Pair prompt. HA sends a session-specific Bluetooth completion receipt after saving and verifying the identity, including on the existing-bond path.

iOS asks to pair but HA reports no identity

The receiver stopped pairing after accepting Pair

Check the last step in HA, not just the iPhone’s saved Bluetooth devices:

A disconnected channel does not itself mean Windows’ service metadata is stale. Recovery may reuse the freshly discovered service metadata, but session and claim values are read from the phone again, and the protected write is mandatory. Unreadable cached handles force an uncached lookup; a blocked filtered lookup also gets a complete uncached service lookup before recovery fails. These routes do not request another pairing ceremony or extend the five-minute deadline. See Bleak’s Windows read semantics.

After a terminal error, choose New code and reopen Presence Pair. Keep the saved bond unless HA specifically requests removal. Do not restart HA or the receiver during the attempt: restarting HA discards its temporary session keys and requires a new invitation. No phone or receiver reset is needed for a normal retry. A receiver-side fix does not require reinstalling the iPhone app.

A saved phone never reaches QR verification

iphone_saved_bond_unreachable means Windows remembers a bond but the current service could not be read after bounded retries. It is not by itself proof of a key mismatch. The receiver preserves the bond and offers Repair saved pairing only if the failed attempt’s address resolves to exactly one stored identity.

  1. Open the error in Home Assistant as an administrator.
  2. Choose Repair saved pairing and confirm the targeted reset.
  3. If the receiver is still in iPhone Settings > Bluetooth, forget it there too. iOS does not allow this app to delete a system bond automatically.
  4. Use the new code that HA creates after verified receiver cleanup.

After verified removal, HA persists the phone-side preparation requirement for that person and receiver until verified re-enrollment. QR renewal, cancellation and HA restarts do not clear it. Presence Pair 219 and later opens a preparation screen before starting Bluetooth: confirm Removed or not listed: continue only after checking the selected receiver in iPhone Settings. If it is absent, continue without deleting any other device. HA also displays these instructions next to the QR so older apps do not hide the required manual step.

Ordinary retries do not carry this requirement and can reuse working bonds. Temporary sessions and invitations are cleaned up independently; a timeout or weak signal must not trigger indiscriminate system-bond deletion.

The repair uses the signed-in Windows Bluetooth broker, then SYSTEM verifies both the OS bond and private keys are absent. A successful Windows API return alone is not enough. Only the selected phone is removed; other phones, the HA person and Wi-Fi assignments remain unchanged. A failure does not silently clear the HA identity or start another QR. The repair offer expires after ten minutes and cannot be used for another attempt or receiver. If no offer appears, the target could not be identified safely; collect diagnostics instead of deleting arbitrary Bluetooth devices. Working pairings never need this reset.

Controller error 0x3E denotes a connection-establishment or synchronization timeout, not an authentication failure.

Each failed discovery must release its native MaintainConnection request before cancelling the connection coroutine: Bleak’s cancellation cleanup discards the native session reference. Calling cleanup only afterwards is too late to explicitly revoke the request. Timeout and user cancellation must both drain the old operation before opening the next route. The admin-authorized bond repair is separate from transport cleanup and never resets the radio.

References: Windows connection lifetime, Bluetooth controller error codes.

Removal fails or the server still remembers the phone

The room is wrong

The phone becomes away briefly

Increase the Away timeout in the integration options. iOS system advertisements are intermittent, especially while the phone is stationary.