被动BLE广告的解析器

此PyPI包解析BLE广告以供多个传感器读取数据，可用于设备跟踪（通过（固定）MAC地址或通过UUID）。该解析器最初作为Home Assistant的BLE监控自定义组件的一部分开发，但现在可用于其他实现。该包不处理BLE广告的数据收集，您可以使用aioblescan或bleson等包来执行此部分。示例可以在示例文件夹中找到。

安装

pip install bleparser

支持的传感器

支持的传感器品牌

• Acconeer
• Air Mentor
• Amazfit
• ATC（小米/青平传感器的自定义固件）
• BlueMaestro
• Brifit
• BTHome
• b-parasite
• Govee
• HHCC
• Inkbird
• iNode
• Jaalee
• Jinou
• Kegtron
• KKM
• Mikrotik
• Moat
• Oral-B
• Qingping
• Relsib
• Ruuvitag
• Sensirion
• SensorPush
• SmartDry
• Switchbot
• Teltonika
• Thermoplus
• Thermopro
• Tilt
• Xiaogui（秤）
• 小米（MiBeacon）
• 小米（MiScale）

所有支持的传感器的完整列表可以在BLE监控文档中找到

用法

在使用默认输入参数的情况下，您可以使用bleparser按照以下方式使用原始BLE数据（下面有更多示例）。

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

您还可以设置可选参数，以下示例显示了所有可能的输入参数及其默认值。

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)

还可以直接使用广告数据。

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 和 man_spec_data_list 必须在列表中，因为 BKE 广告可以包含多个服务数据/制造商特定数据包。

report_unknown

报告未知传感器。可以设置为 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 或 Xiaomi 来向记录器报告特定品牌的未知传感器。您可以将其设置为 Other 来向记录器报告所有未知广告。默认：False

discovery

布尔值。当设置为 False 时，仅解析 sensor_whitelist 中的传感器。默认：True

filter_duplicates

布尔值。大多数传感器发送多个具有完全相同数据的广告，以提高接收质量。当设置为 True 时，它将根据传感器发送的 packet_id 过滤重复广告。如果具有相同的 packet_id，则只解析一个广告。请注意，并非所有传感器都具有 packet_id。默认：False

sensor_whitelist

列表，包含正在解析的设备的 MAC 地址或 UUID，如果 discovery 设置为 False。如果 discovery 设置为 True，则解析所有支持的传感器。默认：[]

tracker_whitelist

包含要跟踪的设备（MAC 地址或 UUID）的列表。默认：[]

aeskeys

包含 mac 加密密钥对的字典，用于需要解密有效载荷的传感器。默认：{}

结果

解析结果有两个字典，一个包含传感器数据（例如温度读数），另一个包含跟踪数据。

解析传感器数据

以下最小示例展示了如何从（支持的）BLE 广告中提取传感器测量值

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)

sensor_msg 的输出是

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

如果可以解析广告，它将始终显示 rssi、mac、type、packet、firmware 和 data 字段。根据传感器类型，还可能存在包含测量值的附加字段，如 temperature 和 humidity。

解析跟踪数据

以下是最小示例，展示了如何跟踪 BLE 设备。为了防止跟踪所有经过的设备，您必须指定一个白名单，其中包含您想要跟踪的设备。这需要一个包含 MAC 地址的列表，MAC 地址为小写，不带 :。

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)

结果是

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

输出始终显示 mac、rssi 以及是否 is connected。