Local iPhone Bluetooth presence and estimated rooms for Home Assistant. Install with HACS, enroll with Presence Pair, and keep presence data in your home.
The protocol lets an authenticated Home Assistant administrator associate a person with the Bluetooth identity created when that person’s iPhone bonds to a specific Windows or Linux receiver. It deliberately does not give the app a Home Assistant access token, MQTT credentials, or an IRK.
Home Assistant and the observer communicate through the local MQTT broker under
presence_bridge/v1/observers/<observer_id>. After scanning a code, the iPhone
temporarily advertises a Bluetooth LE GATT service. Current apps derive a fresh
service UUID from the one-time QR secret and session id, which prevents Windows
from reusing a stale GATT catalogue after a previous bond. Receivers also
accept the original static service UUID so older app builds remain pairable.
The Windows observer scans for either service and initiates the connection and
bond.
| Characteristic | UUID | Access |
|---|---|---|
| Service | Per-session UUID; legacy 61dd168c-4ec1-40de-a78c-ccdce5774bba |
Temporary iPhone advertisement |
| Session | ef70387a-ba9d-4e83-9171-fea99252b57a |
Plain read by observer |
| Claim | 700dbb64-64ed-4f51-adae-b106a00e908a |
HMAC-authenticated read by observer |
| Result | fb5312b1-c24c-42b5-8d21-5263874c258f |
HMAC-authenticated write by observer |
The authenticated HA panel creates a 32-byte random secret and a 2048-bit ephemeral RSA key. The app receives this short-lived URI through a QR code or a custom URL:
presencepair://pair?v=2&sid=<session>&oid=<observer>&exp=<unix>&secret=<base64url>
The invitation is valid for at most ten minutes to start. Scanning starts one five-minute app attempt, including proximity, retries and HA verification. The receiver starts its bounded attempt on the first exact QR-scoped advertisement. The completion phase inherits that deadline; it never renews it. Seeing a generic Presence Pair advertisement cannot consume or extend another invitation.
The Windows receiver keeps the same QR-scoped proximity beacon available after
the initial proximity write, through service discovery, Bluetooth bonding, and
the protected acknowledgement. The iPhone samples that beacon during the
active exchange. If the signal is continuously too weak or disappears beyond
the bounded gap, the app terminates the attempt with PP-PROX-02; it does not
reuse the interrupted exchange and asks the user to start a fresh QR attempt.
This is a proximity safety guard, not a calibrated distance measurement.
After a matching live address is verified and its identity persisted, HA sends
the receiver a non-retained MQTT complete command for the same active session.
Only then does the receiver advertise a completion receipt for at most 20 seconds,
within the remaining attempt budget. A failed protected GATT acknowledgement
must never produce a completion receipt, including reused bonds. The UUID is HMAC-SHA256(secret, UTF-8 of
presence-bridge-complete:v2\nsid\noid\nexp), truncated to 16 bytes with the same
UUID version/variant bits as the other services. The app scans only that UUID and
accepts it only within its active attempt. It contains no identity or key.
The encrypted GATT result means bond exchange accepted, not final HA completion.
The observer first reads the public session characteristic and requires an exact match with its active invitation. It then reads and verifies this claim before requesting a Windows bond:
HMAC-SHA256(secret, "presence-bridge:v2\n<sid>\n<oid>\n<exp>")
The claim proves that the nearby app owns the one-time invitation. The QR secret itself is never transmitted over Bluetooth. Verifying the claim before the bond also avoids a Windows/iOS interoperability failure where WinRT hides the temporary iPhone GATT service immediately after committing the bond.
After verification, the observer writes an encrypted acknowledgement carrying:
HMAC-SHA256(secret, "presence-bridge-result:v2\n<sid>\n<oid>\n<exp>\naccepted")
The acknowledgement is mandatory and means the secure exchange succeeded, not that HA has saved the association. The app must wait for the QR-authenticated HA completion receipt. A lost GATT channel may be retried within the original deadline, but cannot downgrade the protected acknowledgement to best effort.
Linux uses the same contract locally in-process or over MQTT. It reads only the
verified peer’s BlueZ bond file, requires an authenticated 128-bit LongTermKey,
then performs the protected result write. Because BlueZ can resolve RPAs in the
kernel, its encrypted result may also contain identity_address and
secure_exchange_complete: true. HA accepts fresh observations of that address
only from the enrolling observer. It never accepts another observer’s arbitrary
MAC as equivalent to resolving the IRK. Raw identity addresses stay out of UI
payloads and diagnostics.
The cross-language test vectors are:
sid = abcdefghijklmnopQRSTUVWX
oid = living_room_pc
exp = 1800000180
secret = bytes 00 through 1f
claim proof = -q6gU_keDbd_kcgOXTfnolM0m3ke96HzM_b-z1uuXPk
acceptance proof = u1KQY_RD_yBH9VIx0CrrOe2nZ0zrkbuoa3iOBhH6QE4
The SYSTEM observer selects the IRK created by the bond. For an existing bond, it matches the connected identity address or resolvable private address against the retained Windows IRKs. It encrypts the result with RSA-OAEP SHA-256 and publishes the ciphertext to HA. HA accepts the result only for the active session, decrypts it in memory, and checks that the IRK resolves a currently observed private address before storing it.
IRKs and raw addresses are omitted from entities, WebSocket UI payloads, logs, and diagnostics.
Following verified receiver-side removal, invitations can include the optional
reset=forget_receiver query hint. This is phone-side preparation guidance only,
not deletion authority. It does not alter the canonical claim, secret or derived
GATT UUIDs. HA persists it by person/receiver across retries and restarts and
clears it only with a verified identity commit. Supporting apps wait for explicit
phone-side preparation before starting the radio transport; older apps retain
the same protocol and see the guidance in the HA panel.
An unreadable service does not authenticate a peer. Windows may offer a repair only after a session-scoped advertisement uniquely resolves to a stored IRK. An opaque, one-shot offer is bound to the failed session, observer, identity fingerprint and a ten-minute deadline. Only HA’s administrator WebSocket command can confirm it; radio discovery alone never triggers an unpair. HA rejects identities assigned to another person or receiver. Windows rejects stale offers and cancels only that same failed attempt before using its existing interactive removal helper. SYSTEM verifies bond and key absence. HA then clears only that identity and creates a new invitation for the same person and receiver. The raw key never enters the repair command, UI, diagnostics or recovery journal. Offers are deliberately not persisted: after a restart a fresh attempt is needed.