apple-ble

Read AirPods battery (case / left / right + charging) and detect nearby Apple devices from Python, straight off the unencrypted Apple Continuity proximity-pairing BLE advertisement — no pairing, no connection.

This library powers the Apple BLE Home Assistant integration, but works standalone in any Python project (or straight from the command line). The parser is pure and dependency-free; bleak is only needed for the optional scanner CLI.

What works: AirPods broadcast their battery in an unencrypted Continuity advert when the lid is opened. What doesn't: Apple Watch / iPhone do not put battery in their adverts — BLE can only tell you an Apple device is nearby. Apple rotates the BLE MAC (~15 min), so there is no stable per-device id.

Features

• 🔋 AirPods battery — case, left, and right levels plus per-pod and case charging flags, decoded from the manufacturer-0x004C proximity-pairing advert.
• 👂 In-ear / in-case / lid — which bud is in an ear, how many are in the case, and whether the case lid is open (layout verified on real AirPods Pro 2).
• 🔐 Exact battery with the AirPods keys — decrypt_status() decrypts the AES half of the advert (1 % battery, charging, connected host) and resolve_rpa() recognises your AirPods behind the rotating address.
• 🎧 Model detection — AirPods 1/2/3, Pro, Pro 2, Max.
• 📡 Presence-friendly — exposes the Apple manufacturer id so callers can count nearby Apple devices.
• 🧪 Pure parser — parse_proximity_pairing(bytes) -> AirPodsData | None, no I/O, trivially unit-testable.
• 🖥️ CLI — apple-ble scans and prints any AirPods it sees (needs the cli extra).

Requirements

• Python 3.12 or newer.
• A Bluetooth LE adapter (built-in or USB) — only for live scanning; the parser itself needs nothing.

Installation

pip install apple-ble            # core (parsing only)
pip install "apple-ble[cli]"     # + bleak scanner CLI

CLI usage

apple-ble    # 15s BLE scan; open your AirPods lid nearby and watch the battery

Library usage

from apple_ble import parse_proximity_pairing, APPLE_MANUFACTURER_ID

# `payload` is manufacturer_data[76] from any BLE stack (bleak, Home Assistant, ...)
data = parse_proximity_pairing(payload)
if data:
    print(data.model, data.left_battery, data.right_battery, data.case_battery)
    print(data.left_charging, data.right_charging, data.case_charging)

With the per-AirPods keys (on a Mac: keychain item MobileBluetooth, account = AirPods address, fields MagicAccIRK / MagicAccEncKey):

from apple_ble import decrypt_status, parse_key, resolve_rpa

irk, enc = parse_key(irk_text), parse_key(enc_text)   # accepts "FE-47-…" or hex
if resolve_rpa(address, irk):                          # these are *your* AirPods
    st = decrypt_status(payload, enc, flipped=data.flipped)
    print(st.left_battery, st.right_battery, st.case_battery, st.host_suffix)

parse_proximity_pairing returns None for anything that isn't a complete AirPods proximity-pairing advert, so it is safe to feed it every Apple advert you see and keep the non-None results.

API

Credits

Continuity reverse-engineering: furiousMAC/continuity, kavishdevar/librepods, delphiki/AirStatus, d4rken-org/capod. Author @hudsonbrendon.

License

MIT — see LICENSE.