bleparser 3.7.1__tar.gz → 4.0.1__tar.gz

{bleparser-3.7.1 → bleparser-4.0.1}/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2022 Ernst Klamer
+Copyright (c) 2025 Custom components for Home Assistant
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{bleparser-3.7.1/package/bleparser.egg-info → bleparser-4.0.1}/PKG-INFO

@@ -1,17 +1,24 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: bleparser
-Version: 3.7.1
+Version: 4.0.1
 Summary: Parser for passive BLE advertisements
 Home-page: https://github.com/Ernst79/bleparser
 Author: Ernst79
 Author-email: e.klamer@gmail.com
 Project-URL: Bug Tracker, https://github.com/Ernst79/bleparser/issues
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: pycryptodomex
+Dynamic: license-file
 
 # BLE parser for passive BLE advertisements
 
@@ -23,6 +30,11 @@ This pypi package is parsing BLE advertisements to readable data for several sen
 pip install bleparser
 ```
 
+The passive parsers and parser fixtures are synchronized with
+[`custom-components/ble_monitor` at `51bf13b994a1`](https://github.com/custom-components/ble_monitor/commit/51bf13b994a1f9c8b72c345401f48d81dd96f984).
+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
@@ -31,31 +43,47 @@ Supported sensor brands
 - 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)
@@ -72,6 +100,19 @@ 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:
+
+```python
+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.
 
 ```python
@@ -101,11 +142,17 @@ sensor_data, tracker_data = self.parse_advertisement(
 )
 ```
 
-`service_data_list` and `man_spec_data_list` have to be in a list, as a BKE advertisement can contain multiple service data/manufacturer specific data packets. 
+`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`, `Brifit`, `BTHome`, `Govee`, `HHCC`, `Inkbird`, `iNode`, `Jaalee`, `Jinou`, `Kegtron`, `KKM`, `Mikrotik`, `Moat`, `Mi Scale`, `Oral-B`, `Qingping`, `Relsib`, `Ruuvitag`, `SensorPush`, `Sensirion`, `SmartDry`, `Switchbot`, `Teltonika`, `Thermoplus`, `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`
+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**
 
@@ -119,6 +166,15 @@ Boolean. Most sensors send multipe advertisements with the exact same data, to i
 
 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. 
+```python
+    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: `[]`
@@ -127,6 +183,11 @@ List with devices (MAC addresses or UUIDs) to track. Default: `[]`
 
 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. 
+```python
+    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.
@@ -154,6 +215,11 @@ The output of `sensor_msg` is:
 
 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 `:`. 

bleparser-3.7.1/PKG-INFO → bleparser-4.0.1/README.md

@@ -1,18 +1,3 @@
-Metadata-Version: 2.1
-Name: bleparser
-Version: 3.7.1
-Summary: Parser for passive BLE advertisements
-Home-page: https://github.com/Ernst79/bleparser
-Author: Ernst79
-Author-email: e.klamer@gmail.com
-Project-URL: Bug Tracker, https://github.com/Ernst79/bleparser/issues
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-
 # 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](https://github.com/custom-components/ble_monitor), 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](https://github.com/frawau/aioblescan) or [bleson](https://bleson.readthedocs.io/en/latest/index.html) to do that part. An example is given in the [examples folder](https://github.com/Ernst79/bleparser/tree/master/examples).
@@ -23,6 +8,11 @@ This pypi package is parsing BLE advertisements to readable data for several sen
 pip install bleparser
 ```
 
+The passive parsers and parser fixtures are synchronized with
+[`custom-components/ble_monitor` at `51bf13b994a1`](https://github.com/custom-components/ble_monitor/commit/51bf13b994a1f9c8b72c345401f48d81dd96f984).
+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
@@ -31,31 +21,47 @@ Supported sensor brands
 - 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)
@@ -72,6 +78,19 @@ 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:
+
+```python
+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.
 
 ```python
@@ -101,11 +120,17 @@ sensor_data, tracker_data = self.parse_advertisement(
 )
 ```
 
-`service_data_list` and `man_spec_data_list` have to be in a list, as a BKE advertisement can contain multiple service data/manufacturer specific data packets. 
+`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`, `Brifit`, `BTHome`, `Govee`, `HHCC`, `Inkbird`, `iNode`, `Jaalee`, `Jinou`, `Kegtron`, `KKM`, `Mikrotik`, `Moat`, `Mi Scale`, `Oral-B`, `Qingping`, `Relsib`, `Ruuvitag`, `SensorPush`, `Sensirion`, `SmartDry`, `Switchbot`, `Teltonika`, `Thermoplus`, `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`
+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**
 
@@ -119,6 +144,15 @@ Boolean. Most sensors send multipe advertisements with the exact same data, to i
 
 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. 
+```python
+    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: `[]`
@@ -127,6 +161,11 @@ List with devices (MAC addresses or UUIDs) to track. Default: `[]`
 
 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. 
+```python
+    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.
@@ -154,6 +193,11 @@ The output of `sensor_msg` is:
 
 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 `:`.