apple-ble 0.1.0__tar.gz

apple_ble-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Environments
+.venv/
+venv/
+.env
+
+# uv
+uv.lock
+
+# OS
+.DS_Store

apple_ble-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: apple-ble
+Version: 0.1.0
+Summary: Pure-Python parser for Apple Continuity BLE proximity-pairing adverts (AirPods battery + Apple device presence)
+Project-URL: Homepage, https://github.com/hudsonbrendon/apple-ble
+Author-email: Hudson Brendon <contato.hudsonbrendon@gmail.com>
+License: MIT
+Keywords: airpods,apple,ble,bluetooth,continuity,home-assistant
+Requires-Python: >=3.12
+Provides-Extra: cli
+Requires-Dist: bleak>=0.22; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# apple-ble
+
+Pure-Python parser for Apple Continuity BLE *proximity-pairing* advertisements.
+Reads AirPods battery (case / left / right) and charging state from the
+unencrypted manufacturer-76 advert. No connection required, no HA dependency.
+
+## Install
+```bash
+pip install apple-ble            # core (parsing only)
+pip install "apple-ble[cli]"     # + bleak scanner CLI
+```
+
+## Use as a library
+```python
+from apple_ble import parse_proximity_pairing, APPLE_MANUFACTURER_ID
+
+# `payload` is manufacturer_data[76] from any BLE stack (bleak, HA, etc.)
+data = parse_proximity_pairing(payload)
+if data:
+    print(data.model, data.left_battery, data.right_battery, data.case_battery)
+```
+
+## Scan from the terminal
+```bash
+apple-ble   # opens a 15s BLE scan, prints AirPods it sees
+```
+
+## Limitations
+- Only AirPods expose battery over BLE. Apple Watch / iPhone do **not**.
+- Apple rotates the BLE MAC (~15 min); there is no stable per-device id in the advert.
+- Battery is reported in coarse 10% steps.
+
+Reverse-engineering credit: furiousMAC/continuity, kavishdevar/librepods,
+delphiki/AirStatus, d4rken-org/capod.

apple_ble-0.1.0/README.md

@@ -0,0 +1,34 @@
+# apple-ble
+
+Pure-Python parser for Apple Continuity BLE *proximity-pairing* advertisements.
+Reads AirPods battery (case / left / right) and charging state from the
+unencrypted manufacturer-76 advert. No connection required, no HA dependency.
+
+## Install
+```bash
+pip install apple-ble            # core (parsing only)
+pip install "apple-ble[cli]"     # + bleak scanner CLI
+```
+
+## Use as a library
+```python
+from apple_ble import parse_proximity_pairing, APPLE_MANUFACTURER_ID
+
+# `payload` is manufacturer_data[76] from any BLE stack (bleak, HA, etc.)
+data = parse_proximity_pairing(payload)
+if data:
+    print(data.model, data.left_battery, data.right_battery, data.case_battery)
+```
+
+## Scan from the terminal
+```bash
+apple-ble   # opens a 15s BLE scan, prints AirPods it sees
+```
+
+## Limitations
+- Only AirPods expose battery over BLE. Apple Watch / iPhone do **not**.
+- Apple rotates the BLE MAC (~15 min); there is no stable per-device id in the advert.
+- Battery is reported in coarse 10% steps.
+
+Reverse-engineering credit: furiousMAC/continuity, kavishdevar/librepods,
+delphiki/AirStatus, d4rken-org/capod.

apple_ble-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "apple-ble"
+version = "0.1.0"
+description = "Pure-Python parser for Apple Continuity BLE proximity-pairing adverts (AirPods battery + Apple device presence)"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Hudson Brendon", email = "contato.hudsonbrendon@gmail.com" }]
+keywords = ["airpods", "ble", "bluetooth", "apple", "continuity", "home-assistant"]
+dependencies = []
+
+[project.optional-dependencies]
+cli = ["bleak>=0.22"]
+dev = ["pytest>=8", "pytest-cov>=5"]
+
+[project.scripts]
+apple-ble = "apple_ble.scanner:main"
+
+[project.urls]
+Homepage = "https://github.com/hudsonbrendon/apple-ble"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/apple_ble"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

apple_ble-0.1.0/src/apple_ble/__init__.py

@@ -0,0 +1,16 @@
+"""Pure-Python parser for Apple Continuity BLE proximity-pairing adverts."""
+
+from .const import APPLE_MANUFACTURER_ID, MODEL_BY_CHAR
+from .models import AirPodsData, AppleAdvert
+from .parser import decode_battery_nibble, parse_proximity_pairing
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "APPLE_MANUFACTURER_ID",
+    "MODEL_BY_CHAR",
+    "AirPodsData",
+    "AppleAdvert",
+    "decode_battery_nibble",
+    "parse_proximity_pairing",
+]

apple_ble-0.1.0/src/apple_ble/const.py

@@ -0,0 +1,33 @@
+"""Constants for the Apple Continuity proximity-pairing protocol."""
+
+# Apple's Bluetooth company identifier (0x004C).
+APPLE_MANUFACTURER_ID: int = 76
+
+# Continuity message type for AirPods battery/proximity pairing.
+MSG_TYPE_PROXIMITY_PAIRING: int = 0x07
+
+# A proximity-pairing payload (after the company id) is 27 bytes = 54 hex chars.
+PROXIMITY_PAIRING_HEX_LEN: int = 54
+
+# Nibble indices into the 54-char hex string of manufacturer_data[76].
+# These mirror the well-tested AirStatus layout.
+IDX_MODEL: int = 7
+IDX_FLIP: int = 10
+IDX_LEFT_NOFLIP: int = 13
+IDX_RIGHT_NOFLIP: int = 12
+IDX_CHARGE: int = 14
+IDX_CASE: int = 15
+
+# Battery nibble value 0x0F means "not present / unknown".
+NIBBLE_UNKNOWN: int = 0x0F
+
+# Model is identified by the single hex char at IDX_MODEL — the low nibble of
+# the device-model byte (e.g. 0x0E -> "e" = AirPods Pro, 0x14 -> "4" = Pro 2).
+MODEL_BY_CHAR: dict[str, str] = {
+    "2": "AirPods (1st gen)",
+    "f": "AirPods (2nd gen)",
+    "3": "AirPods (3rd gen)",
+    "e": "AirPods Pro",
+    "4": "AirPods Pro 2",
+    "a": "AirPods Max",
+}

apple_ble-0.1.0/src/apple_ble/models.py

@@ -0,0 +1,31 @@
+"""Immutable data models returned by the parser."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class AirPodsData:
+    """Parsed AirPods proximity-pairing state.
+
+    Battery values are integer percentages in 10% steps, or None when the
+    pod/case is not present or the value is unknown (nibble 0x0F).
+    """
+
+    model: str
+    left_battery: int | None
+    right_battery: int | None
+    case_battery: int | None
+    left_charging: bool
+    right_charging: bool
+    case_charging: bool
+
+
+@dataclass(frozen=True, slots=True)
+class AppleAdvert:
+    """A minimal record of any Apple manufacturer-76 advertisement seen."""
+
+    address: str
+    rssi: int
+    is_proximity_pairing: bool

apple_ble-0.1.0/src/apple_ble/parser.py

@@ -0,0 +1,64 @@
+"""Parse Apple Continuity proximity-pairing advertisements into AirPodsData."""
+
+from __future__ import annotations
+
+from . import const
+from .models import AirPodsData
+
+
+def decode_battery_nibble(nibble: int) -> int | None:
+    """Convert a 0x0-0xF battery nibble to a percentage in 10% steps.
+
+    Apple reports battery in deciles: 0..10 -> 0..100%. Values 11-15 mean
+    "not present / unknown" and yield None.
+    """
+    if nibble > 10:
+        return None
+    return nibble * 10
+
+
+def _is_flipped(hexstr: str) -> bool:
+    """AirPods report L/R swapped depending on orientation bit."""
+    return (int(hexstr[const.IDX_FLIP], 16) & 0x02) == 0
+
+
+def parse_proximity_pairing(data: bytes) -> AirPodsData | None:
+    """Parse manufacturer_data[76] bytes into AirPodsData, or None if not AirPods.
+
+    `data` must be the bytes that follow Apple's company id (i.e. starting with
+    the message type byte). Returns None for any advert that is not a complete
+    proximity-pairing message.
+    """
+    if not data or data[0] != const.MSG_TYPE_PROXIMITY_PAIRING:
+        return None
+
+    hexstr = data.hex()
+    if len(hexstr) < const.PROXIMITY_PAIRING_HEX_LEN:
+        return None
+
+    model = const.MODEL_BY_CHAR.get(hexstr[const.IDX_MODEL], "AirPods")
+
+    flipped = _is_flipped(hexstr)
+    left_idx = const.IDX_RIGHT_NOFLIP if flipped else const.IDX_LEFT_NOFLIP
+    right_idx = const.IDX_LEFT_NOFLIP if flipped else const.IDX_RIGHT_NOFLIP
+
+    left_battery = decode_battery_nibble(int(hexstr[left_idx], 16))
+    right_battery = decode_battery_nibble(int(hexstr[right_idx], 16))
+    case_battery = decode_battery_nibble(int(hexstr[const.IDX_CASE], 16))
+
+    charge = int(hexstr[const.IDX_CHARGE], 16)
+    left_bit = 0b0010 if flipped else 0b0001
+    right_bit = 0b0001 if flipped else 0b0010
+    left_charging = bool(charge & left_bit)
+    right_charging = bool(charge & right_bit)
+    case_charging = bool(charge & 0b0100)
+
+    return AirPodsData(
+        model=model,
+        left_battery=left_battery,
+        right_battery=right_battery,
+        case_battery=case_battery,
+        left_charging=left_charging,
+        right_charging=right_charging,
+        case_charging=case_charging,
+    )

apple_ble-0.1.0/src/apple_ble/scanner.py

@@ -0,0 +1,57 @@
+"""Optional standalone BLE scanner CLI (requires the `cli` extra: bleak)."""
+
+from __future__ import annotations
+
+import asyncio
+
+from . import const
+from .models import AirPodsData
+from .parser import parse_proximity_pairing
+
+
+def _fmt(v: int | None) -> str:
+    """Format a battery percentage for display; absent pods show '--'."""
+    return "--" if v is None else f"{v}%"
+
+
+def advert_to_airpods(advertisement_data) -> AirPodsData | None:
+    """Extract AirPodsData from a bleak AdvertisementData-like object."""
+    mfr = getattr(advertisement_data, "manufacturer_data", {}) or {}
+    payload = mfr.get(const.APPLE_MANUFACTURER_ID)
+    if payload is None:
+        return None
+    return parse_proximity_pairing(bytes(payload))
+
+
+async def _scan(seconds: float) -> None:
+    from bleak import BleakScanner  # imported lazily so core lib has no dep
+
+    seen: dict[str, AirPodsData] = {}
+
+    def _cb(device, advertisement_data) -> None:
+        data = advert_to_airpods(advertisement_data)
+        if data is not None:
+            seen[device.address] = data
+            print(
+                f"[{advertisement_data.rssi} dBm] {data.model}: "
+                f"L={_fmt(data.left_battery)} R={_fmt(data.right_battery)} "
+                f"case={_fmt(data.case_battery)} "
+                f"(charging L/R/case={data.left_charging}/"
+                f"{data.right_charging}/{data.case_charging})"
+            )
+
+    scanner = BleakScanner(detection_callback=_cb)
+    await scanner.start()
+    await asyncio.sleep(seconds)
+    await scanner.stop()
+    if not seen:
+        print("No AirPods adverts seen. Open the lid near the scanner and retry.")
+
+
+def main() -> None:
+    """Console entry point: `apple-ble`."""
+    asyncio.run(_scan(15.0))
+
+
+if __name__ == "__main__":
+    main()

apple_ble-0.1.0/tests/test_const.py

@@ -0,0 +1,25 @@
+from apple_ble import const
+
+
+def test_apple_manufacturer_id_is_76():
+    assert const.APPLE_MANUFACTURER_ID == 76
+
+
+def test_proximity_pairing_type_is_0x07():
+    assert const.MSG_TYPE_PROXIMITY_PAIRING == 0x07
+
+
+def test_model_map_covers_known_airpods():
+    assert const.MODEL_BY_CHAR["e"] == "AirPods Pro"
+    assert const.MODEL_BY_CHAR["4"] == "AirPods Pro 2"
+    assert const.MODEL_BY_CHAR["a"] == "AirPods Max"
+    assert const.MODEL_BY_CHAR["2"] == "AirPods (1st gen)"
+
+
+def test_nibble_indices():
+    assert const.IDX_MODEL == 7
+    assert const.IDX_FLIP == 10
+    assert const.IDX_LEFT_NOFLIP == 13
+    assert const.IDX_RIGHT_NOFLIP == 12
+    assert const.IDX_CHARGE == 14
+    assert const.IDX_CASE == 15

apple_ble-0.1.0/tests/test_models.py

@@ -0,0 +1,35 @@
+from apple_ble.models import AirPodsData
+
+
+def test_airpods_data_holds_fields():
+    data = AirPodsData(
+        model="AirPods Pro",
+        left_battery=90,
+        right_battery=100,
+        case_battery=None,
+        left_charging=False,
+        right_charging=True,
+        case_charging=False,
+    )
+    assert data.model == "AirPods Pro"
+    assert data.left_battery == 90
+    assert data.case_battery is None
+    assert data.right_charging is True
+
+
+def test_airpods_data_is_frozen():
+    data = AirPodsData(
+        model="AirPods Pro",
+        left_battery=None,
+        right_battery=None,
+        case_battery=None,
+        left_charging=False,
+        right_charging=False,
+        case_charging=False,
+    )
+    try:
+        data.model = "x"  # type: ignore[misc]
+    except Exception as exc:  # frozen dataclass raises FrozenInstanceError
+        assert "cannot assign" in str(exc).lower() or "frozen" in str(exc).lower()
+    else:
+        raise AssertionError("AirPodsData should be immutable")

apple_ble-0.1.0/tests/test_parser.py

@@ -0,0 +1,173 @@
+from apple_ble.parser import decode_battery_nibble
+from apple_ble.parser import parse_proximity_pairing
+
+
+def test_full_battery():
+    assert decode_battery_nibble(10) == 100
+
+
+def test_mid_battery():
+    assert decode_battery_nibble(9) == 90
+    assert decode_battery_nibble(5) == 50
+
+
+def test_empty_battery():
+    assert decode_battery_nibble(0) == 0
+
+
+def test_unknown_nibble_is_none():
+    assert decode_battery_nibble(15) is None
+    assert decode_battery_nibble(11) is None
+
+
+# A 27-byte (54 hex char) proximity-pairing advert.
+# Layout (nibble indices): model@7='e' (AirPods Pro), flip@10='7',
+# right@12='a'(=10 ->100%), left@13='9'(->90%), charge@14='3'
+# (bit0 set, bit1 set, bit2 clear), case@15='6'(->60%).
+
+
+def _sample_bytes() -> bytes:
+    # Nibble layout: type@0-1='07', model@7='e'(AirPods Pro), flip@10='7'(not flipped),
+    # right@12='a'(->100%), left@13='9'(->90%), charge@14='3'(L+R charging, case not),
+    # case@15='6'(->60%).
+    hexstr = "0719070e2070a93601000045121212"
+    hexstr = hexstr + "0" * (54 - len(hexstr))  # right-pad nibbles to 54 chars
+    return bytes.fromhex(hexstr)
+
+
+def test_parses_model_and_batteries():
+    data = parse_proximity_pairing(_sample_bytes())
+    assert data is not None
+    assert data.model == "AirPods Pro"
+    # flip nibble @10 = '7'; int('7',16)&0x02 == 2 (nonzero) -> NOT flipped
+    # not flipped: left=idx13, right=idx12
+    assert data.right_battery == 100   # idx12 = 'a' = 10 -> 100
+    assert data.left_battery == 90     # idx13 = '9' -> 90
+
+
+def test_parses_charging_flags():
+    data = parse_proximity_pairing(_sample_bytes())
+    assert data is not None
+    # charge nibble @14 = '3' = 0b0011, not flipped:
+    assert data.left_charging is True    # bit0
+    assert data.right_charging is True   # bit1
+    assert data.case_charging is False   # bit2
+
+
+def test_case_battery():
+    data = parse_proximity_pairing(_sample_bytes())
+    assert data is not None
+    assert data.case_battery == 60   # idx15 = '6' -> 60
+
+
+def test_rejects_non_proximity_pairing():
+    # Type byte 0x10 (not 0x07) -> not a proximity pairing message.
+    assert parse_proximity_pairing(bytes.fromhex("10" + "0" * 52)) is None
+
+
+def test_rejects_wrong_length():
+    assert parse_proximity_pairing(bytes.fromhex("0719")) is None
+
+
+def test_rejects_empty():
+    assert parse_proximity_pairing(b"") is None
+
+
+def test_public_api_exports():
+    import apple_ble
+
+    assert hasattr(apple_ble, "parse_proximity_pairing")
+    assert hasattr(apple_ble, "AirPodsData")
+    assert apple_ble.APPLE_MANUFACTURER_ID == 76
+
+
+def _make_hexstr(charge_nibble: str, left_nibble: str = "9", right_nibble: str = "a",
+                  flip_nibble: str = "7") -> bytes:
+    """Build a NOT-flipped (flip_nibble='7') advert with custom charge/battery nibbles.
+
+    Hex layout (indices):
+      0-1: type '07'
+      2-5: '1907'  (payload length + subtype)
+      6-7: '0e'    model byte (idx6='0', idx7='e' -> AirPods Pro)
+      8-9: '20'
+      10:  flip_nibble  (default '7' = 0b0111, bit1 set -> NOT flipped)
+      11:  '0'
+      12:  right_nibble (IDX_RIGHT_NOFLIP)
+      13:  left_nibble  (IDX_LEFT_NOFLIP)
+      14:  charge_nibble
+      15:  '6'  case battery -> 60%
+      16+: zeros padded to 54 chars
+    """
+    s = "071907" + "0e" + "20" + flip_nibble + "0" + right_nibble + left_nibble + charge_nibble + "6"
+    s = s + "0" * (54 - len(s))
+    return bytes.fromhex(s)
+
+
+# --- Charging-bit attribution tests (NOT flipped, flip nibble = '7') ---
+
+def test_charging_only_left():
+    # charge nibble '1' = 0b0001; not flipped: left_bit=0b0001, right_bit=0b0010
+    # -> left_charging True, right_charging False, case_charging False
+    data = parse_proximity_pairing(_make_hexstr(charge_nibble="1", left_nibble="5", right_nibble="8"))
+    assert data is not None
+    assert data.left_charging is True
+    assert data.right_charging is False
+    assert data.case_charging is False
+    # Confirm batteries are correctly read (distinct nibbles, not-flipped)
+    assert data.left_battery == 50   # idx13='5'
+    assert data.right_battery == 80  # idx12='8'
+
+
+def test_charging_only_right():
+    # charge nibble '2' = 0b0010; not flipped: left_bit=0b0001, right_bit=0b0010
+    # -> left_charging False, right_charging True
+    data = parse_proximity_pairing(_make_hexstr(charge_nibble="2", left_nibble="3", right_nibble="7"))
+    assert data is not None
+    assert data.left_charging is False
+    assert data.right_charging is True
+
+
+def test_charging_only_case():
+    # charge nibble '4' = 0b0100; case_bit=0b0100
+    # -> case_charging True, left/right False
+    data = parse_proximity_pairing(_make_hexstr(charge_nibble="4", left_nibble="2", right_nibble="6"))
+    assert data is not None
+    assert data.left_charging is False
+    assert data.right_charging is False
+    assert data.case_charging is True
+
+
+# --- Flipped-orientation test ---
+
+def test_flipped_swaps_indices_and_charging_bits():
+    # flip_nibble '4' = 0b0100; bit1 clear (0x02 & 0x04 == 0) -> FLIPPED
+    # In flipped mode: left reads IDX_RIGHT_NOFLIP (idx12), right reads IDX_LEFT_NOFLIP (idx13)
+    # idx12='2' -> 20%, idx13='8' -> 80%
+    # charge nibble '1' = 0b0001; flipped: left_bit=0b0010, right_bit=0b0001
+    # -> bit0 set hits right_bit -> right_charging True, left_charging False
+    data = parse_proximity_pairing(_make_hexstr(
+        charge_nibble="1", left_nibble="8", right_nibble="2", flip_nibble="4"
+    ))
+    assert data is not None
+    # Index swap: left reads idx12='2'->20, right reads idx13='8'->80
+    assert data.left_battery == 20
+    assert data.right_battery == 80
+    # Bit swap: charge bit 0b0001 -> right_charging (not left) when flipped
+    assert data.left_charging is False
+    assert data.right_charging is True
+
+
+def test_real_hardware_airpods_pro_2():
+    # Captured live from real AirPods Pro 2 (device-model bytes 0x14 0x20) over
+    # the Mac's built-in Bluetooth. Pods were out of the case and flipped.
+    # This is a real-world regression fixture, not a synthetic one.
+    raw = bytes.fromhex("07190114200b538f10000848273aff815e50000000261e7bfab684")
+    data = parse_proximity_pairing(raw)
+    assert data is not None
+    assert data.model == "AirPods Pro 2"  # nibble@7='4'
+    assert data.left_battery == 50        # flip@10='0' -> flipped; left=idx12='5'
+    assert data.right_battery == 30       # right=idx13='3'
+    assert data.case_battery is None      # case@15='f' -> not present
+    assert data.left_charging is False
+    assert data.right_charging is False
+    assert data.case_charging is False

apple_ble-0.1.0/tests/test_scanner.py

@@ -0,0 +1,20 @@
+from apple_ble.scanner import advert_to_airpods
+
+
+class _FakeAdvData:
+    def __init__(self, manufacturer_data):
+        self.manufacturer_data = manufacturer_data
+
+
+def test_advert_to_airpods_parses_apple_data():
+    hexstr = "0719070e2070a93601000045121212"
+    hexstr = hexstr + "0" * (54 - len(hexstr))
+    adv = _FakeAdvData({76: bytes.fromhex(hexstr)})
+    data = advert_to_airpods(adv)
+    assert data is not None
+    assert data.model == "AirPods Pro"
+
+
+def test_advert_to_airpods_ignores_non_apple():
+    adv = _FakeAdvData({6: b"\x01\x02"})  # Microsoft, not Apple
+    assert advert_to_airpods(adv) is None