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"])

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

Metadata

Release files for cidermill-apple-ble 0.5.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.5.0
File Size Uploaded Provenance Actions
cidermill_apple_ble-0.5.0.tar.gz 71.1 kB Without provenance Details for cidermill_apple_ble-0.5.0.tar.gz

Built distribution (wheel)

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

Total release size: 375.5 kB

Release files / cidermill_apple_ble-0.5.0.tar.gz

Download URL cidermill_apple_ble-0.5.0.tar.gz
Size 71.1 kB
Tags Source
SHA-256 checksum
How to use checksums
1add97d312aeaea28405c1b20cc35203f17d8ab2f63e9e470a7d7717ce6eb48b
BLAKE2b-256 checksum
How to use checksums
122b1241037b72ecf9a3128dd9857195d4027412555688cf85513fd2cbac764f
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.5.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL cidermill_apple_ble-0.5.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 304.3 kB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
cde6d1c3736254ed909ef44e1bee0583ca962baf5d3a612064ea81786c6ae017
BLAKE2b-256 checksum
How to use checksums
08eba7a330bc11de58868db3b7e53fcd0d12fd288e999285a92f90bd0eed6afe
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.5.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