深入解析ATC_MiThermometer项目的Python接口与数据模型

深入解析ATC_MiThermometer项目的Python接口与数据模型

ATC_MiThermometer Custom firmware for the Xiaomi Thermometers and Telink Flasher 项目地址: https://gitcode.com/gh_mirrors/atc/ATC_MiThermometer

本文将详细介绍如何使用Python接口与ATC_MiThermometer项目进行交互，包括数据解码、编码、加密解密以及设备配置等核心功能。

项目概述

ATC_MiThermometer项目提供了一套自定义固件，用于蓝牙低功耗(BLE)温湿度计设备。该项目包含一个Python接口模块，能够处理设备发出的BLE广播数据，并提供了丰富的工具集来解析、显示和编辑这些数据。

核心组件与技术栈

该Python接口基于以下几个关键技术组件构建：

1. bleak：一个跨平台的BLE库，用于扫描和连接蓝牙设备
2. construct：一个对称的Python库，用于声明式定义数据结构
3. construct-gallery：扩展construct功能的工具集，提供GUI界面

安装指南

基础安装

使用pip安装核心功能包：

pip install atc-mi-interface

如需GUI功能，需安装额外依赖：

pip install atc-mi-interface[gui]

Raspberry Pi特殊配置

在树莓派上需要额外安装GTK开发库：

sudo apt-get install -y libgtk-3-dev

数据解析与编码

基础解析示例

from atc_mi_interface import general_format

# 解析自定义格式数据帧
frame_data = bytes.fromhex("12 16 1a 18 cc bb aa 38 c1 a4 77 07 88 13 ca 0a 50 01 07")
parsed_data = general_format.parse(frame_data)

# 提取关键数据
print("温度:", parsed_data.search_all("^temperature"))
print("湿度:", parsed_data.search_all("^humidity"))
print("电池电量:", parsed_data.search_all("^battery_level"))

数据编码示例

from atc_mi_interface import custom_format

# 构建数据帧
built_frame = custom_format.build({
    "size": 18,
    "uid": 22,
    "UUID": b"\x18\x1a",
    "MAC": "A4:C1:38:AA:BB:CC",
    "temperature": 19.11,
    "humidity": 50.0,
    "battery_level": 80
})

print(built_frame.hex(" "))

加密与解密功能

解密示例

from atc_mi_interface import general_format

# 需要提供MAC地址和绑定密钥
mac = bytes.fromhex("A4:C1:38:AA:BB:CC".replace(":", ""))
key = bytes.fromhex("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA")

# 解析加密帧
encrypted_frame = bytes.fromhex("0e 16 1a 18 bd 9d c5 4e fa b5 00 0e 8b b8 07")
decrypted_data = general_format.parse(encrypted_frame, mac_address=mac, bindkey=key)

print(decrypted_data)

加密示例

from atc_mi_interface import custom_enc_format

# 构建加密帧
encrypted_frame = custom_enc_format.build(
    {
        "size": 14,
        "uid": 22,
        "UUID": b"\x18\x1a",
        "codec": {
            "temperature": 19.11,
            "humidity": 50.0
        }
    },
    mac_address=mac,
    bindkey=key
)

print(encrypted_frame.hex(" "))

设备配置管理

读取配置示例

from atc_mi_interface import cfg

# 解析配置数据
config_bytes = bytes.fromhex("43 85 10 00 00 28 04 A9 31 31 04 B4")
config_data = cfg.parse(config_bytes)

# 访问配置项
print("固件版本:", f"{config_data.firmware_version.major}.{config_data.firmware_version.minor}")
print("温度单位:", config_data.flg.temp_F_or_C)

修改配置示例

# 修改温度单位为华氏度
config_data.flg.temp_F_or_C = "temp_F"

# 生成新的配置字节
new_config = cfg.build(config_data)
print(new_config.hex(" "))

实用工具

该项目提供了三个主要命令行工具：

1. atc_mi_advertising：BLE广播数据浏览器(GUI)
2. atc_mi_config：设备配置工具
3. atc_mi_format_test：格式测试工具

可通过以下方式调用：

python -m atc_mi_interface -a  # 启动广播数据浏览器
python -m atc_mi_interface -c  # 启动配置工具

最佳实践与注意事项

1. Python版本选择：推荐使用Python 3.10，3.11及以上版本可能存在兼容性问题
2. 性能考虑：在资源受限设备(如树莓派)上，GUI功能会占用较多资源
3. 数据安全：妥善保管绑定密钥，避免泄露
4. 错误处理：在实际应用中应添加适当的错误处理逻辑

通过本文介绍，开发者可以充分利用ATC_MiThermometer项目的Python接口实现设备数据的解析、加密、配置等高级功能，为物联网应用开发提供强大支持。

ATC_MiThermometer Custom firmware for the Xiaomi Thermometers and Telink Flasher 项目地址: https://gitcode.com/gh_mirrors/atc/ATC_MiThermometer