Skip to main content

BLE parser for passive BLE advertisements

This pypi package is parsing BLE advertisements to readable data for several sensors and can be used for device tracking (by (fixed) MAC address or by UUID). The parser was originally developed as part of the BLE monitor custom component for Home Assistant, but can now be used for other implementations. The package does NOT take care of the data collecting of the BLE advertisements, you can use other packages like aioblescan or bleson to do that part. An example is given in the examples folder.

Installation

pip install bleparser

The passive parsers and parser fixtures are synchronized with custom-components/ble_monitor at 51bf13b994a1. Home Assistant integration code and active Bluetooth key-retrieval tools are not included. The package remains standalone and supports Python 3.11 through 3.15.

Supported sensors

Supported sensor brands

  • Acconeer
  • Air Mentor
  • Amazfit
  • ATC (custom firmware for Xiaomi/Qingping sensors)
  • Beckett
  • BlueMaestro
  • Blustream
  • Brifit
  • BTHome
  • b-parasite
  • Chef iQ
  • Eddystone-TLM
  • Govee
  • Grundfos
  • HHCC
  • HolyIOT
  • Hormann
  • Inkbird
  • iNode
  • Jaalee
  • Jinou
  • Kegtron
  • KKM
  • Laica
  • Michelin
  • Mikrotik
  • Minew
  • Moat
  • Mocreo
  • Oral-B
  • Oras
  • Qingping
  • Relsib
  • Ruuvitag
  • Sensirion
  • SensorPush
  • Senssun
  • SmartDry
  • Sonoff
  • Switchbot
  • Teltonika
  • Thermobeacon (including Brifit and Thermoplus)
  • Thermoplus
  • Thermopro
  • Thermosafer
  • Tilt
  • Xiaogui (Scale)
  • Xiaomi (MiBeacon)
  • Xiaomi (MiScale)

A full list of all supported sensors can be found on the BLE monitor documentation

Usage

When using default input parameters, you can use bleparser with raw BLE data as follows (more working examples below).

ble_parser = BleParser()
sensor_msg, tracker_msg = ble_parser.parse_raw_data(data)

For an HCI event containing multiple legacy or extended advertisement reports, use parse_raw_data_reports to receive all recognized reports:

for sensor_msg, tracker_msg in ble_parser.parse_raw_data_reports(data):
    print(sensor_msg, tracker_msg)

parse_raw_data continues to return one (sensor_msg, tracker_msg) pair (the first recognized report), or (None, None) when nothing is recognized. Truncated reports are ignored, and malformed reports are logged at debug level without discarding other complete reports in the event.

You can set optional parameters, the example below shows all possible input parameters with default values.

ble_parser = BleParser(
    report_unknown=False,
    discovery=True,
    filter_duplicates=False,
    sensor_whitelist=[],
    tracker_whitelist=[],
    aeskeys={}
    )
sensor_msg, tracker_msg = ble_parser.parse_raw_data(data)

It is also possible to use advertisement data directly.

ble_parser = BleParser()
sensor_data, tracker_data = self.parse_advertisement(
    mac,
    rssi,
    service_class_uuid16,
    service_class_uuid128,
    local_name,
    service_data_list,
    man_spec_data_list
)

service_data_list and man_spec_data_list have to be in a list, as a BLE advertisement can contain multiple service data/manufacturer specific data packets.

report_unknown

Report unknown sensors. Can be set to Acconeer, Air Mentor, Amazfit, ATC, b-parasite, BlueMaestro, BTHome, Govee, HHCC, Inkbird, iNode, Jaalee, Jinou, Kegtron, KKM, Mikrotik, Moat, Mi Scale, Oral-B, Qingping, Relsib, Ruuvitag, SensorPush, Sensirion, SmartDry, Switchbot, Teltonika, Thermopro, Tilt, Xiaogui or Xiaomi to report unknown sensors of a specific brand to the logger. You can set it to Other to report all unknown advertisements to the logger. Default: False

Additional report_unknown names are Beckett, Blustream, Chef iQ, Eddystone, Grundfos, HolyIOT, Hormann, Minew, Sonoff, Thermobeacon, and Thermosafer. Brifit and Thermoplus advertisements now use the upstream Thermobeacon firmware name; use report_unknown="Thermobeacon" for these devices.

discovery

Boolean. When set to False, only sensors in sensor_whitelist will be parsed. Default: True

filter_duplicates

Boolean. Most sensors send multipe advertisements with the exact same data, to increase reception quality. When set to True, it will filter duplicate advertisements based on a packet_id that is send by the sensor. Only one advertisement will be parsed if it has the same packet_id. Note that not all sensors have packet_ids. Default: False

sensor_whitelist

List with MAC addresses or UUIDs of devices that are being parsed, if discovery is set to False. If discovery is set to True, all supported sensors will be parsed. Default: []

The MAC addresses should be in bytes.

    sensor_whitelist=[bytes.fromhex("A4:C1:38:56:53:84".replace(":", ""))],

For iBeacon, AltBeacon, and Tilt sensor data, whitelist the beacon UUID as bytes rather than only its MAC address. A whitelisted UUID also allows devices whose MAC address changes.

tracker_whitelist

List with devices (MAC addresses or UUIDs) to track. Default: []

aeskeys

Dictionary with mac + encryption key pairs, for sensors that require an encryption key to decrypt the payload. Default: {}

The mac and encryption key pairs should be in bytes.

    aeskeys={bytes.fromhex("A4:C1:38:56:53:84".replace(":", "")): bytes.fromhex("a115210eed7a88e50ad52662e732a9fb") for mac, aeskey in AESKEYS.items()},

Result

The parser result are two two dictionaries, one with sensor data (e.g. temperature readings) and one with tracking data.

Parsing sensor data

The following minimal example shows how to extract the sensor measurements out of a (supported) BLE advertisement:

from bleparser import BleParser

data_string = "043e2502010000219335342d5819020106151695fe5020aa01da219335342d580d1004fe004802c4"
data = bytes(bytearray.fromhex(data_string))

ble_parser = BleParser()
sensor_msg, tracker_msg = ble_parser.parse_raw_data(data)
print(sensor_msg)

The output of sensor_msg is:

{'rssi': -60, 'mac': '582D34359321', 'type': 'LYWSDCGQ', 'packet': 218, 'firmware': 'Xiaomi (MiBeacon V2)', 'data': True, 'temperature': 25.4, 'humidity': 58.4}

If the advertisements can be parsed, it will always show the rssi, mac, type, packet, firmware and data fields. Additional fields with the measurements, like temperature and humidity will be available depending on the sensor type.

Sensor and tracker results now also include local_name (an empty string when the advertisement has no valid UTF-8 local name). Measurement names and values follow the pinned upstream parser, including newer BTHome measurements and device-specific corrections.

Parsing tracker data

A minimal example for tracking BLE devices is shown below. To prevent tracking of all devices that pass by, you will have to specify a whitelist with devices that you want to track. This needs to be a list with MAC addresses in lower case, without :.

from bleparser import BleParser

data_string = "043e2502010000219335342d5819020106151695fe5020aa01da219335342d580d1004fe004802c4"
data = bytes(bytearray.fromhex(data_string))

tracker_whitelist = []
track_mac = "58:2D:34:35:93:21"
track_mac = bytes.fromhex(track_mac.replace(":", ""))
tracker_whitelist.append(track_mac.lower())

ble_parser = BleParser(tracker_whitelist=tracker_whitelist)
sensor_msg, tracker_msg = ble_parser.parse_raw_data(data)
print(tracker_msg)

The result is:

{'is connected': True, 'mac': '582D34359321', 'rssi': -60}

The output is always showing the mac, rssi and if it is connected.

Metadata

Release files for bleparser 4.0.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 bleparser 4.0.1
File Size Uploaded Provenance Actions
bleparser-4.0.1.tar.gz 68.9 kB Without provenance Details for bleparser-4.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bleparser 4.0.1
File Interpreter ABI Platform Actions
bleparser-4.0.1-py3-none-any.whl Python 3 none any Details for bleparser-4.0.1-py3-none-any.whl

Total release size: 160.7 kB

Release files / bleparser-4.0.1.tar.gz

Download URL bleparser-4.0.1.tar.gz
Size 68.9 kB
Tags Source
SHA-256 checksum
How to use checksums
b1a8d860847de5890a40335ef6220a0615140a7205880485b0cc99c1be3229a4
BLAKE2b-256 checksum
How to use checksums
066ceed3e385f08a529025867739fc032b8940acef83088fd5b7d64116783c6f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Release files / bleparser-4.0.1-py3-none-any.whl

Download URL bleparser-4.0.1-py3-none-any.whl
Size 91.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dc23e56bd08cfc067e33f6a7ed75d15ddb6ccfe64e07acb47339edd4ab7053b8
BLAKE2b-256 checksum
How to use checksums
ecc2a7da7cb01657ee2960e81ee829c9838c4fe0b1ab001acf534628df4533a5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Security for bleparser 4.0.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