Metadata-Version: 2.4
Name: cidermill-apple-ble
Version: 0.6.1
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Communications
License-File: LICENSE
Summary: A decoder for Apple BLE proximity-pairing advertisements (AirPods, Beats, etc.) and AirPods battery and head-tracking messages over AAP. Rust core, Python bindings.
Keywords: airpods,bluetooth-le,ble,apple,parser
License-Expression: GPL-3.0-or-later
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# cidermill-apple-ble (Python)

Python bindings for
[cidermill-apple-ble](https://gitlab.com/timrs2998/cidermill-apple-ble), a Rust
decoder for the Bluetooth LE advertisements AirPods and Beats broadcast: battery, charging,
in-ear, lid and color.

```python
import cidermill_apple_ble

# Manufacturer data for company ID 0x004C, with the ID stripped (bleak: advertisement_data.manufacturer_data[0x004C]).
advert = cidermill_apple_ble.parse(0x004C, data)
if advert:
    print(advert["model_name"], advert["lowest_battery"], advert["any_in_ear"])
```

`parse` returns `None` for anything else; it never raises on bad input. Type stubs describe the
dict (`cidermill_apple_ble.Advertisement`). Also: `parse_manufacturer_data`, `model_name`,
`color_name`, `is_mono`, `known_models`, `known_colors`.

## AirPods battery and motion sensors (AAP)

`aap_host_connect`, `aap_set_report_interval`, `aap_parse_frame`, `aap_parse_motion`,
`aap_plist_string` and the `AAP_*` constants build and read the connected-mode messages that stream
AirPods (3rd generation) head tracking; the parsers return `None` rather than raising. Opening the
channel is yours. `aap_parse_battery` reads the battery notification, which carries every
component's level to 1 % (the BLE advertisement carries tens); it needs only `AAP_HANDSHAKE` then
`AAP_REQUEST_NOTIFICATIONS` sent first (`AAP_SET_FEATURES` is optional and model-specific), and
returns `entries` with `component` (`left`, `right`, `case` or `other`), `level`, `level_percent`
(`None` for a disconnected part's placeholder), `status`, and `other_component` and `other_status`
(the raw byte of a value with no name). Its layout comes from published notes and is not checked
against hardware here. On Linux, with a raw Bluetooth socket (the buds must be bonded):

```python
import socket, struct
import cidermill_apple_ble as ab

s = socket.socket(socket.AF_BLUETOOTH, socket.SOCK_SEQPACKET, socket.BTPROTO_L2CAP)
s.setsockopt(274, 4, struct.pack("BB", 2, 0))  # SOL_BLUETOOTH, BT_SECURITY: BT_SECURITY_MEDIUM
opts = bytearray(s.getsockopt(6, 1, 12))  # SOL_L2CAP, L2CAP_OPTIONS
opts[2:4] = struct.pack("<H", ab.AAP_RECEIVE_MTU)  # imtu, before connect
s.setsockopt(6, 1, bytes(opts))
s.connect((address, ab.AAP_PSM))  # 0x1001

for message in (ab.AAP_HANDSHAKE, ab.AAP_SET_FEATURES, ab.AAP_REQUEST_NOTIFICATIONS, ab.aap_host_connect(1)):
    s.send(message)
while True:
    frame = ab.aap_parse_frame(s.recv(4096))
    for sub in frame["sub_packets"] if frame else []:
        if sub["kind"] == "connect" and ab.aap_plist_string(sub["body"], "AccessoryService") == ab.AAP_MOTION_SERVICE:
            s.send(ab.aap_set_report_interval(2, sub["device_id"], 10_000))  # 100 Hz
        elif sub["kind"] == "input_report" and sub["report"]:
            sample = ab.aap_parse_motion(sub["report"])
            if sample:
                print(sample["attitude_quaternion"])
```

Noise control and ear detection: `aap_parse_listening_mode`, `aap_parse_ear_detection`,
`aap_set_listening_mode`, `aap_allow_off_mode`, `aap_set_stem_modes` and
`aap_listening_modes_for_model` read and build the messages. `AapSession` is the whole
conversation without a socket or a clock: call `start(now_ms)`, send what `take_transmits()`
returns, pass each received frame to `receive(frame, now_ms)` (or `tick(now_ms)` when
`next_deadline()` passes) and read the event dicts it returns (`type` is `ready`, `battery`,
`listening_mode`, `ear_detection`, `mode_change`, `motion`, `refused` or `ended`). Commands
(`set_listening_mode`, `set_stem_modes`, `start_head_tracking`) raise `AapCommandError` with the
reason. `battery` and `ear` hold the merged battery levels and the last ear placement, and
`close()` ends the session. None of this has been verified on hardware.

License: GPL-3.0-or-later, the same as the core (see LICENSE).

