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

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.1
File Size Uploaded Provenance Actions
cidermill_apple_ble-0.6.1.tar.gz 107.1 kB Without provenance Details for cidermill_apple_ble-0.6.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cidermill-apple-ble 0.6.1
File Interpreter ABI Platform Actions
cidermill_apple_ble-0.6.1-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.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Total release size: 470.2 kB

Release files / cidermill_apple_ble-0.6.1.tar.gz

Download URL cidermill_apple_ble-0.6.1.tar.gz
Size 107.1 kB
Tags Source
SHA-256 checksum
How to use checksums
196e67d13946bb395b5e777aaeccb623113104b173528c2599135ef553f017b8
BLAKE2b-256 checksum
How to use checksums
9d7751ccf16aebc700b2489f0689715222ea9b1f12efc90ce712685da64022b2
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.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL cidermill_apple_ble-0.6.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 363.1 kB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
0253237c8900ba01debd92d737548152f91a12a37183016d9dba5e3ac8711036
BLAKE2b-256 checksum
How to use checksums
7cda71a5c95e8de31db8955705045ff01cc43e7d1c416aaf020bdd5283328547
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.1

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