# MicroPython BLE Library **Repository Path**: walkline/micropython-ble-library ## Basic Information - **Project Name**: MicroPython BLE Library - **Description**: 根据之前研究学习到的 Micropython BLE 相关知识，将相关代码模块封装成为类库，方便以后使用 - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 23 - **Forks**: 7 - **Created**: 2020-03-19 - **Last Updated**: 2025-04-18 ## Categories & Tags **Categories**: hardware **Tags**: MicroPython, BLE ## README

MicroPython BLE Library

### 项目介绍 根据之前研究学习到的 Micropython BLE 相关知识，将相关代码模块封装成为类库，方便以后使用 ### BLE 相关名词解释 为了后文便于理解，也避免出现`关贸总协定`这样怪异的翻译，特此对几个名词做出我个人的理解，如有误导欢迎斧正 #### `Profile` 可以理解为 BLE 设备作为某个指定用途的`说明文档`，或者概述、简介等，比如作为`HID`设备（通常为键盘鼠标摇杆等外设）时，必须要实现以下三个服务： * `Battery Service` * `Device Information` * `Human Interface Device` 对这 3 个必要服务的说明就是`Profile`的作用 #### `Services` 项目中提供的 Services 以及后面的 Characteristics 和 Descriptors 都是由 [Bluetooth® Technology Website](https://www.bluetooth.com/) 定义的一些统一规范，所有人按照规范进行蓝牙硬件设备开发，在不需要额外开发软件的前提下我们的硬件设备即可以被诸如 PC、手机等`中心设备（Central）`识别并使用 `服务`的作用是告知中心设备我们的硬件将会提供什么样的服务，比如上述`HID`的 Profile 包含了 3 个服务，中心设备就会把它识别为一个键盘鼠标类的`外围设备（Peripheral）` #### `Characteristics` 名为`特征`，可以理解为服务的属性参数，就像一个 Profile 可以包含多个服务一样，服务也可以包含多个特征，用于具体描述某个服务的某项特征值 比如`Battery Service`服务包含了`Battery Level`特征，向它写入一个 0 到 100 的数值，就可以告知中心设备当前我们的设备电量情况 #### `Descriptors` 和服务一样，每个特征还可以包含多个`描述符`，描述符的作用是对特征的额外设置，比如一些中心设备会向我们的外围设备中的某个特征发送`通知（Notify）`，描述符可以设置是否接收通知，等 ### 如何使用？ 下面以`main.py`为例讲解如何使用类库生成一个 Profile > 假设你已经掌握了`MicroPython ubluetooth`模块的基本使用方法 #### 导入类库文件 ```python import ubluetooth as bt from ble.const import BLEConst from ble.tools import BLETools from ble.profile.manager import ProfileManager from ble.services import * from ble.characteristics import * from ble.descriptors import * ``` #### 生成 Profile ```python profile = ProfileManager() profile.add_services( BatteryService().add_characteristics( Characteristics(BLEConst.Characteristics.BATTERY_LEVEL, BLEConst.CharacteristicFlags.BATTERY_LEVEL_) ), HumanInterfaceDevice().add_characteristics( Characteristics(BLEConst.Characteristics.REPORT, BLEConst.CharacteristicFlags.REPORT_).add_descriptors( ClientCharacteristicConfiguration(), ) ), ) ``` 这里给 Profile 添加了 2 个服务，每个服务添加了 1 个特征和一个额外的描述符 * Battery Service（服务） * Battery Level（特征） * Human Interface Device（服务） * Report（特征） * Client Characteristic Configuration（描述符） 本来计划中应该使用更一目了然更直观的方式生成 Profile 的，例如这样 ```python # 定义 HID 设备必须的 3 个服务 profile.add_services( HumanInterfaceDevice().add_characteristics( ReportMap(), Report(), ProtocolMode(), HIDInformation(), HIDControlPoint(), BootMouseInputReport(), ), DeviceInformation().add_characteristics( PNPID(), ), BatteryService().add_characteristics( BatteryLevel(), ), ) ``` 但是鉴于官方定义的特征实在太多了，一一简化倒是会方便开发，但是相应的类库文件就会非常巨大（相对于 ESP32 的 4M 存储来说），无奈只能选择使用比较麻烦的方法了，但是服务和描述符相对较少，所以依然使用了简化方式 #### 注册服务 注册服务，获取特征和描述符句柄，用于和中心设备交互 > 定义句柄的顺序必须和定义 Profile 时候的顺序一致 ```python ble = bt.BLE() services = profile.get_services() ( ( handle_battery_level, ), ( handle_report, handle_report_desc, ), ) = ble.gatts_register_services(services) ``` #### 生成广播信息 为避免广播内容太多导致广播失败，建议将`设备名称`放置到`Scan Response`中 ```python uuids = profile.get_services_uuid() appearance = BLEConst.Appearance.GENERIC_HEART_RATE_SENSOR adv_payload = BLETools.advertising_generic_payload( services=uuids, appearance=appearance ) resp_payload = BLETools.advertising_resp_payload( name="BLELibTest" ) ``` #### 广播信息 广播 Profile 包含的 Services 信息，中心设备收到信息后经过分析可以展示给用户 ```python ble.gap_advertise(None) ble.gap_advertise(interval_us=100000, adv_data=adv_payload, resp_data=resp_payload) ``` #### 向中心设备传递消息通知 先在设备本地写入一个电量值，然后使用`Notify`方法告知中心设备 ```python import struct ble.gatts_write(handle_battery_level, struct.pack(" `handle_battery_level`是`注册服务`时获取的句柄 > > `conn_handle`是中心设备连接时的连接句柄 基本使用方法就是如此了，下面看一下中心设备展示给用户的内容吧 ### 查看一下效果吧 因为示例中使用的 Profile 为随机搭配的内容，所以并不能在电脑、手机上直接搜索到，我们需要借助第三方 APP 进行查看，比如 [nRF Connect](https://github.com/NordicSemiconductor/Android-nRF-Connect/releases) ![Screenshot01](images/screenshot_01.png) ![Screenshot02](images/screenshot_02.png) `REPL`中完整的输出内容如下 ```docs activating ble... I (57150) BTDM_INIT: BT controller compile version [5aed448] I (60951) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE I (61051) phy: phy_version: 4102, 2fa7a43, Jul 15 2019, 13:06:06, 0, 0 GAP procedure initiated: stop advertising. ble activated services registed GAP procedure initiated: advertise; disc_mode=2 adv_channel_map=7 own_addr_type=0 adv_filter_policy=0 adv_itvl_min=160 adv_itvl_max=160 advertising... >>> [52:5F:AF:24:C3:38] connected, handle: 0 [52:5F:AF:24:C3:38] disconnected, handle: 0 GAP procedure initiated: advertise; disc_mode=2 adv_channel_map=7 own_addr_type=0 adv_filter_policy=0 adv_itvl_min=160 adv_itvl_max=160 advertising... ``` ### 下载烧录自定义固件 最简便的使用本类库的方式就是下载并烧录我的自定义固件，免去上传冗长文件的过程 访问 [自定义固件下载项目](https://gitee.com/walkline/esp32_firmware) 下载最新的自定义固件，并参考 [附录1：如何刷写固件](https://gitee.com/walkline/esp32_firmware#%E9%99%84%E5%BD%951%E5%A6%82%E4%BD%95%E5%88%B7%E5%86%99%E5%9B%BA%E4%BB%B6) 烧录固件到开发板 ### 合作交流 * 联系邮箱： * QQ 交流群： * 走线物联：163271910 * 扇贝物联：31324057

走线物联扇贝物联