Skip to main content

cidermill-apple-ble (Python)

Python bindings for cidermill-apple-ble, a Rust decoder for the Bluetooth LE advertisements AirPods and Beats broadcast: battery, charging, in-ear, lid and color.

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):

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).

Metadata

Release files for cidermill-apple-ble 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cidermill-apple-ble 0.6.0
File Size Uploaded Provenance Actions
cidermill_apple_ble-0.6.0.tar.gz 106.5 kB Without provenance Details for cidermill_apple_ble-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cidermill-apple-ble 0.6.0
File Interpreter ABI Platform Actions
cidermill_apple_ble-0.6.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.9 abi3 Linux glibc 2.17+ x86-64 Details for cidermill_apple_ble-0.6.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Total release size: 468.9 kB

Release files / cidermill_apple_ble-0.6.0.tar.gz

Download URL cidermill_apple_ble-0.6.0.tar.gz
Size 106.5 kB
Tags Source
SHA-256 checksum
How to use checksums
e74add369faa21145fe1cb347d4e96d6b6799c3ab50308604526b2c8fef87dce
BLAKE2b-256 checksum
How to use checksums
85793d5a317045444c6d108032cf678b9435495f438ac03165c29143112a5f9d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.18

Release files / cidermill_apple_ble-0.6.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL cidermill_apple_ble-0.6.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 362.4 kB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
27918e681d728ecba7e001b5d7e0c64be75e4d8f4a13d09c11f4c85813422c46
BLAKE2b-256 checksum
How to use checksums
ee76004745a62e021d7f0f3a63568e4be5a37f8c081a734f2d808157877f42a7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.18

Security for cidermill-apple-ble 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page