简体中文
简体中文
English
联系我们
注册
登录

蓝牙通用串口协议

更新时间:2022-11-11 09:14:30下载pdf

本文主要为涂鸦蓝牙透传方案中串口协议描述。适用于如下架构的通讯方案:

蓝牙通用串口协议

串口通讯约定

  • 波特率(bps):9600 / 115200

  • 数据位:8

  • 奇偶校验:无

  • 停止位:1

  • 数据流控:无

    蓝牙模组每次上电或重启时,会启动波特率轮询。优先以上一次的串口配置开始发送心跳包,每个心跳周期切换一次波特率。若收到回复,则判断为通讯波特率,停止轮询并写配置到 Flash。该功能部分固件旧版本上不支持。

名称解释

名词 说明
DP 即设备功能(Data Point),代表一条或一对指令码。更多详情,请参考 产品功能
PID 即产品 ID(Product ID),描述一类产品功能(DP)的集合。在 涂鸦 IoT 开发平台 创建的每一个产品都会产生一个唯一的产品编号,关联了产品具体的设备功能、App 控制面板、出货信息等所有跟这个产品相关的信息。
蓝牙绑定 指蓝牙设备通过 涂鸦蓝牙通讯协议 与 App 账号建立起的一种绑定关系,以及表示设备在云端的绑定状态。
蓝牙解绑 指设备解除与 App 账号的绑定关系,进入未绑定未连接状态。
蓝牙重置 指在 App 上操作解绑并清除数据,与 蓝牙解绑 的区别在于用户数据是否清除。
蓝牙连接 仅表示蓝牙设备链路层的状态为连接状态。
蓝牙广播 仅表示蓝牙设备链路层的状态为广播状态。
蓝牙配网状态 该名词中的 配网 不同于 Wi-Fi 设备配路由器的过程,指的是未绑定未连接的蓝牙设备处于广播状态的一种状态,此时 App 可通过广播发现设备。
蓝牙绑定已连接 通常也叫设备 上线,蓝牙绑定已连接是指蓝牙设备通过 涂鸦蓝牙通讯协议 与 App 建立的安全通讯状态。
蓝牙绑定未连接 通常也叫设备 离线,表示设备与 App 账号建立了绑定关系,但链路层未连接,不处于安全通讯状态。
蓝牙网关在线 判断网关的在线状态,依赖于网关的离线和在线逻辑:
  • 网关监听到设备在广播,或已经处于 绑定已连接,表示网关在线
  • 设备处于 绑定未连接,且超过一定时长未广播,表示网关离线
具体以网关逻辑为准。

帧数据包结构

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 协议升级扩展用
3 1 命令字 CMD 具体帧类型
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len 数据
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

所有大于 1 个字节的数据均采用大端模式传输。

DP 格式说明

字段 字节数 说明
dp_id 1 DP 的指令码
dp_type 1 DP 的数据类型
dp_data_len 2 DP 的数据长度
dp_data_value dp_data_len DP 的数据

dp_type 的取值范围及含义(云端定义):

dp_type 取值 字节数 说明
raw 0x00 1~255 原始类型,HEX 数组
bool 0x01 1 布尔值
value 0x02 4 值类型(Integer)
string 0x03 0~255 字符串(可能为空)
enum 0x04 1 枚举型
bitmap 0x05 1/2/4 长度大于 1 字节时,大端表示

通用固件品类划分

各通用对接品类支持模组如下所示:

通用对接品类 芯片 云模组
基础类 chip-bk3432、chip-tlsr825x、chip-phy6222 BPU、BTU、BT3L、BT7L、YLB1
门锁类 chip-nrf52832、chip-bk3431q、chip-tlsr825x TYBN1、BT3L
共享类 chip-bk3432、chip-bk3431q、chip-tlsr825x BT3L、YLB1
传感类 chip-tlsr825x、chip-phy6222 BT3L、BT7L、BTU、BPU

通用固件协议接口支持情况

不同品类的通用固件支持的协议情况不同,同一品类不同版本对协议接口的支持情况也不同。协议接口支持情况,请咨询您的涂鸦技术支持工程师或客户经理。

通用对接协议

心跳包(CMD-0x00)

  • 模组上电后,以 3s 的间隔定期发送心跳包。收到 MCU 的心跳包回应后,模组会认为 MCU 正常工作。在 MCU 首次(上电或重启)回复心跳包后,模组会向 MCU 查询产品信息。

  • MCU 侧也可依据此心跳定期检测模组是否正常工作。若模组无心跳下发,则 MCU 可通过模组提供的硬件复位引脚复位模组。

  • 模组在获取 MCU 信息之后,在低功耗模式下无心跳,正常功耗模式下以 10s 的间隔定期发送心跳。

    Telink 模组在低功耗下无心跳,非低功耗下在获得 MCU 信息(PID)后也不再发送心跳包,因此也无法检测 MCU 是否发生重启。

模组发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x00
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

MCU 返回

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x00
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:仅 MCU 上电后第一次收到模组心跳包后的返回值,模组端也可依据这一点判断工作过程中 MCU 是否重启。
  • 0x01:除 MCU 重启后第一次返回 0x00 外,其余均返回此值。

获取 MCU 信息(CMD-0x01)

  • Product key:固定为 8 字节,由涂鸦 IoT 开发平台生成,用于云端记录产品相关信息。
  • 产品信息主要是 PID 信息。
  • 通用串口协议 2.0.0 以上版本支持根据可选 TLD 信息配置模组固件功能,具体支持情况需咨询您的技术支持工程师确定。

模组发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x01
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

MCU 返回

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x01
4
5
2 数据长度 0x00
0x0d
6~18+n 13+n Data 见下表
19+n 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 格式

1~8 9~13 14~14+n
PID 保留字段 可选信息 TLD [TLD] [TLD]…

示例:55 AA 00 01 00 0D 66 74 62 38 78 32 78  30 31 2E 30 2E 30 C0 (pid=ftb8x2x0,mcu ver=1.0.0)

  • PID:为 8 位字符串,如 ftb8x2x0

  • 保留字段:此字段原填充的是 MCU 软件版本号,但模组目前不对该字段做解析,字段保留,起占位作用。MCU 版本号通过 CMD E8\E9 上报。

  • TLD:用于配置通用固件的一些功能、能力。TLD 是一种自定义数据格式:

    • T 表示要配置的功能 ID,即 Type。
    • L 表示该配置后面跟的数据长度。
    • D 为具体的配置数据。

    TLD 可以有 1 个或多个,当不使用默认配置的时候需要填,使用默认配置可以不填。

    T 和 L 的值是固定的,模组端会根据 T 和 L 的值解析 D 的数据,不同 TLD 之间没有顺序要求。

    以下是具体的 TLD 数据格式,序号仅表示 TLD 的字节序号

    • 当 T=0x07,L=0x01 时,D 表示“状态上报——beacon 能力”配置。(可选 TLD,未选且没配置过则默认不支持 beacon)

      1 2 3
      T(0x07) L(0x01) beacon_enable

      beacon_enable:状态上报(CMD-0x07)接口,beacon 能力标志。开启后可使设备在绑定未连接时支持状态广播的方式将状态上报到网关或 App ,主要用于网关配合工作。详情见 CMD-0x07

      • 0x00:关闭

      • 0x01:开启

      • 其他:保留

        示例:55 AA 00 01 00 10 6D 6E 75 78 64 38 30 75  31 2E 30 2E 30  07 01 01   0F

    • 当 T=0x03,L=0x01 时,D 表示“设备在线逻辑标志”配置。(可选 TLD,未选且没配置过则默认 0x00)

      1 2 3
      T(0x03) L(0x01) online_flag

      online_flag:设备在线逻辑标志,目前只与蓝牙网关端在线逻辑有关,与手机没有关系。

      • 0x00:采用标准功耗设备在线策略
      • 0x01:采用低功耗设备在线策略
      • 其他:保留

      示例:55 AA 00 01 00 13 6D 6E 75 78 64 38 30 75   31 2E 30 2E 30   07 01 01   03 01 01  17

    • 当 T=0xBA,L=0x01 时,D 表示“SMP 使能”配置。(可选 TLD,未选且没配置过则默认 0x00)

      1 2 3
      T(0xBA) L(0x01) SMP_ENABLE

      SMP_ENABLE:蓝牙 SMP 相关功能模块使能状态。

      • 0x00:不使用 SMP 配对相关功能
      • 0x01:使用 SMP 配对相关功能
      • 其他:保留

      示例:55 AA 00 01 00 10 34 6B 78 36 68 6C 61 78   31 2E 30 2E 30   BA 01 01  B3

    • 当 T=0x01,L=0x01 时,D 表示“安全连接类型”配置。(可选 TLD,未选且没配置过则默认 0x00)

      1 2 3
      T(0x01) L(0x01) Secure_connect_type

      Secure_connect_type:蓝牙安全连接类型。

      • 0x00:使用默认配置,默认不限制,即二维码和搜索方式都能添加设备。
      • 0x01:限制仅通过扫描二维码方式添加设备。
      • 其他:保留

      示例:55 AA 00 01 00 10 34 6B 78 36 68 6C 61 78   31 2E 30 2E 30   01 01 01  FA

      可选信息为非必填项,MCU 信息及配置信息会存 Flash。未填情况模组会根据之前的配置进行处理,若没配置过则使用默认,否则使用之前的配置。

请求模组工作模式(CMD-0x02)

  • 模组工作模式主要针对如何指示模组的工作状态以及如何重置模组而言,主要分两种情况:

    • MCU 与模组配合处理,即模组通过串口通知 MCU 模组当前的工作状态,然后 MCU 提供显示支持。MCU 检测出模组的重置需求,通过串口通知模组重置模组。
    • 模组自处理:不支持。
  • 目前仅支持 MCU 与模组配合处理模式。

模组发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x02
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 02 00 00 01

MCU 回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x02
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

示例55 AA 00 02 00 00 01

发送模组工作状态(CMD-0x03)

  • 模组工作状态:
    • 0x00:未绑定
    • 0x01:绑定未连接
    • 0x02:绑定已连接
  • 当模组收到 MCU 请求模组工作模式回复 CMD 0x02 后,则会向 MCU 下发模组工作状态。
  • 当模组检测到模组状态发生变化,则主动下发模组状态至 MCU。

模组发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x03
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
State 工作状态说明 共享类通用固件注意
0x00 未绑定 共享类产品对“绑定”这个概念进行了模糊处理,未绑定和绑定未连接在共享类都认为是可配网状态
0x01 绑定未连接 同上
0x02 绑定已连接 绑定已连接在共享类认为是已配网已连接状态

重置模组(CMD-0x04)

  • 断开模组蓝牙连接,解除蓝牙绑定关系,清除模组离线缓存信息,清除虚拟 ID,重启。
  • 由于之前 Telink 平台的模组有大量使用该接口作为解绑接口来使用的情况,为了不影响这部分场景的功能,Telnik 平台重置后不会清除虚拟 ID。

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x04
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 04 00 00 03

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x04
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

示例55 AA 00 04 00 00 03

新重置模组(CMD-0x05)

  • 断开模组蓝牙连接,解除蓝牙绑定关系,清除模组离线缓存信息,清除虚拟 ID,重启。
  • 该接口和 CMD-0x04 接口的作用完全一致,主要用于解决 Telink 平台不清除虚拟 ID 的问题和平衡前后版本的兼容性。
  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x05
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 05 00 00 04

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x05
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

示例55 AA 00 05 00 00 04

命令下发(CMD-0x06)

  • datapoint 参考概述中 DP 格式说明部分
  • 命令下发可含多个 datapoint 命令数据单元。
  • 命令下发为异步处理协议,对应于 MCU 的 datapoint 状态上报

模组发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x06
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len datapoint 见下表
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

datapoint 格式:

1 2 3~4 5~ …… n n+1 n+1~n+2 n+3~
dp1_id dp1_type dp1_len dp1_data …… dpN_id dpN_type dpN_len dpN_data

示例55 aa 00 06 00 05 03 01 00 01 01 10

MCU 返回

状态上报(CMD-0x07)

  • datapoint 参考 DP 格式说明部分
  • 状态上报可含多个 datapoint 命令数据单元。
  • 状态上报为异步处理协议,触发机制有三类:
    • MCU 收到命令下发处理帧时,正确执行相应 datapoint 命令,再通过状态上报帧将变化后的 datapoint 状态发送至模组。
    • MCU 主动检测到 datapoint 有变化,将变化后的 datapoint 状态发送至模组。
    • MCU 收到 状态查询 帧时,将所有的 datapoint 状态发送至模组。
  • 若开启 beacon 功能,模组绑定未连接状态支持状态广播,每个 datapoint 中的 dp_len 最大支持 4 字节。开启 beaocn 能力的方法见 获取 MCU 信息 CMD-0x01

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x07
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len datapoint 见下表
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

datapoint 格式

1 2 3~4 5~ …… n n+1 n+1~n+2 n+3~
dp1_id dp1_type dp1_len dp1_data …… dpN_id dpN_type dpN_len dpN_data

示例55 aa 00 07 00 05 03 01 00 01 01 11

模组返回

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x07
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:成功
  • 其他:失败

状态查询(CMD-0x08)

  • 状态查询为异步处理协议,主要用于模组查询 MCU 所有的 obj 类型的 datapoint 状态,当 MCU 收到此帧时,通过 CMD 0x07 状态上报帧 上报 datapoint 状态。
  • 状态查询发送时机主要有两种:
    • 模组绑定已连接状态下,检查到 MCU 发生重启(通过 心跳 回复判断),查询发送。

      Telink 通用固件不支持检测 MCU 重启。

    • 模组蓝牙离线再上线(由绑定未连接状态变化成绑定已连接状态)的情况,查询发送。

模组发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x08
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

示例55 aa 00 08 00 00 07

MCU 返回

模组解绑(CMD-0x09)

  • 仅解除和手机的绑定关系,并且断开蓝牙连接,不会清除数据和虚拟 ID。

    共享类通用固件“绑定”概念被模糊处理了,故不支持模组解绑接口。

  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x09
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

模组返回

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x09
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:成功
  • 其他:失败

查询模组连接状态(CMD-0x0A)

  • 用于 MUC 主动查询模组的连接状态。模组收到查询后将通过CMD 0x03 发送模组工作状态。
  • 模组工作状态:
    • 0x00:未绑定
    • 0x01:绑定未连接
    • 0x02:绑定已连接

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x0A
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

记录型数据上报(CMD-0xE0)

  • 该接口主要用于重要数据的上报,如果上报时模组处于离线状态,模组会将数据存储在模组 Flash 中,待模组上线再上报至 App。如果模组在线时,会在最后一条数据上报成功(连续上报的最后一条)后,释放缓存数据至 App。

  • 模组可存储最多存储 N 条 DP 数据,记录将循环覆盖存储:

    • NRF52832/BK3431q 存储条数为 63 条稳定存储条数和 16 条缓冲条数,每条数据最长 200 字节。
    • Telink 最多可存储 63 条,每条数据最长 160 字节。
    • BK3432 存储条数为 23 条稳定存储条数和 8 条缓冲条数,每条数据最长 32 字节。
  • 蓝牙模组内部时钟精度有限,24 小时误差小于 1 分钟,但每次重连会重新校准时钟。如果您对精度要求高,建议使用 MCU 自带时间上报。

    无论设备是在线还是离线状态,记录型数据强烈建议使用该接口上报。

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE0
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len Data 见下表
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 格式

1 2~x x x+1 x+2~x+3 x+4~ …… n n+1 n+1~n+2 n+3~
TYPE Time_Str dp1_id dp1_type dp1_len dp1_data …… dpN_id dpN_type dpN_len dpN_data
  • Time_Str:13 位 UNIX 时间字符串

    TYPE_bit3_bit0 时间填充方式说明
    0x01 格式 1:蓝牙模组自带时间上报
    0x03 格式 3:MCU 自带时间上报
    TYPE_bit5_bit4 上报方式说明
    0x00 同时上报云端和面板
    0x01 上报云端,不上报面板
    0x02 上报面板,不上报云端

    TYPE_bit7_bit6:保留

    TYPE 字段使用枚举:

    • 0x01:模组自带时间同时上报云端和面板
    • 0x03:MCU 上报时间同时上报云端和面板
    • 0x11:模组自带时间只上报云端
    • 0x13:MCU 上报时间只上报云端
    • 0x21:模组自带时间只上报面板
    • 0x23:MCU 上报时间只上报面板
  • unix_time_string:仅 TYPE_bit3-bit0 等于 0x03 时需要填,其他格式不用填。

示例

  • 格式 1:蓝牙模组自带时间上报:

    55 AA 00 E0 00 17 01 66 02 00 04 00 00 00 01 67 03 00 05 72 77 72 77 77 68 04 00 01 00 89
    
  • 格式 3:MCU 自带时间上报:

    55 AA 00 E0 00 28 03 31 35 38 39 31 36 38 33 32 37 30 30 30 66 02 00 04 00 00 00 01 67 03 00 09 72 77 72 77 77 61 66 61 66 68 04 00 01 00 D0
    

模组返回

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE0
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明

  • 0x00:存储成功
  • 其他:存储失败

获取实时时间(CMD-0xE1)

  • 年月日格式时间请求建议使用格式 0x02。
  • 设备上线后会主动同步一次云端时间给 MCU。

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE1
4
5
2 数据长度 0x00
0x01
6 1 Time_Type 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Time_type 说明

Time_Type_bit3-bit0 时间类型
0x00 格式 0:获取 7 字节时间类型+2 字节时区信息
0x01 格式 1:获取 13 字节 ms 级 unix 时间+2 字节时区信息
0x02 格式 2:获取 7 字节时间类型+2 字节时区信息
Time_Type_bit5_bit4 时间源
0x00 通过 App 请求云端时间
0x01 请求模组内部软件时钟时间

Time_Type_bit7_bit6:保留

Time_Type 字段使用枚举:

  • 0x00:请求 App 格式 0 时间

  • 0x01:请求 App 格式 1 时间

  • 0x02:请求 App 格式 2 时间

  • 0x10:请求模组内部格式 0 时间

  • 0x11:请求模组内部格式 1 时间

  • 0x12:请求模组内部格式 2 时间

    格式 0 获取自定义时间存在不同平台兼容性问题,后面版本会废除,年月日时间格式建议使用 0x02 格式。

    • Telink 通用固件已经不再支持格式 0,请求格式 0 时间则会返回格式 2 时间。
    • 时区为实际时区的 100 倍,例如北京东 8 区为 800,西 7.5 区为 -750。

模组返回

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE1
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len Time_Data 见下表
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余
  • Time_Data 格式 0:

    结果码 时间格式 星期 时区
    1 2 3 4 5 6 7 8 9 10~11
    Result Time_Type 2018+year mon day hour min sec week time_zone
  • Time_Data 格式 1:

    结果码 时间格式 ms 级 unix 时间 时区
    1 2 3~15 16~17
    Result Time_Type unix_time_string time_zone
  • Time_Data 格式 2:

    结果码 时间格式 星期 时区
    1 2 3 4 5 6 7 8 9 10~11
    Result Time_Type 2000+year mon day hour min sec week time_zone

    Result 为 0x00 表示成功,其他表示失败。

示例

  • Time_Data 格式 0:
    • MCU:55 AA 00 E1 00 01 00 E1
    • 模组:55 AA 00 E1 00 0B 00 00 01 0C 1E 0F 34 1F 01 03 20 9C,表示 2019 年 12 月 30 日 15 点 52 分 31 秒 星期一 东八区
  • Time_Data 格式 1:
    • MCU:55 AA 00 E1 00 01 01 E2
    • 模组:55 AA 00 E1 00 11 00 01 31 35 37 37 36 39 32 33 39 35 30 30 30 03 20 BB,表示时间戳 1577692395000 东八区
  • Time_Data 格式 2:
    • MCU:55 AA 00 E1 00 01 02 E3
    • 模组:55 AA 00 E1 00 0B 00 02 13 0C 1E 10 09 29 01 03 20 90,表示 2019 年 12 月 30 日 16 点 09 分 35 秒 星期一 东八区

恢复出厂设置通知(CMD-0xA1)

  • 当 App 向模组发送恢复出厂设置命令时,模组会向 MCU 发出恢复出厂设置通知,MCU 可以根据该指令做恢复出厂设置功能。
  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

模组发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA1
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

MCU 返回

MCU 查询模组版本号(CMD-0xA0)

  • MCU 如果需要获得模组的版本信息,可通过该接口查询。如果 MCU 不需要模组的版本信息,可以不实现该协议。
  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA0
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA0
4
5
2 数据长度 0x00
0x06
6~11 6 DATA 见下表
12 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

DATA 格式

1~3 4~6
Soft_Ver Hard_ver
  • Soft_Ver:模组当前固件版本号,例如 0x01 00 02 代表版本为 V1.0.2。
  • Hard_ver:模组当前硬件版本号,PCBA 版本号。

MCU OTA 相关接口

查询 MCU 版本号(CMD-0xE8)

模组发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE8
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

MCU 返回

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE8
4
5
2 数据长度 0x00
0x06
6~11 6 DATA 见下表
12 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

DATA 格式

1~3 4~6
Soft_Ver Hard_ver
  • Soft_Ver:MCU 当前固件版本号,例如 0x01 00 02 代表版本为 V1.0.2。

  • Hard_ver:MCU 当前硬件版本号,PCBA 版本号。

MCU 主动发送当前版本号(CMD-0xE9)

  • 为了确保模组及时获取到 MCU 版本信息,MCU 在每次启动时(一般在串口初始化后)需要主动发送一次当前版本号到模组,如果没有收到模组的响应,需要再次发送。
  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

MCU 返回

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE9
4
5
2 数据长度 0x00
0x06
6~11 6 DATA 见下表
12 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

DATA 格式

1~3 4~6
Soft_Ver Hard_ver
  • Soft_Ver:MCU 当前固件版本号,例如 0x01 00 02 代表版本为 V1.0.2。
  • Hard_ver:MCU 当前硬件版本号,PCBA 版本号。

模组返回

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE9
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:成功
  • 其他:失败

MCU OTA 流程

蓝牙通用串口协议

MCU OTA 升级请求(CMD-0xEA)

  • 升级开始的时候由模组向 MCU 发送请求,获取 MCU 串口能传输的最大单包长度。
  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

模组发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xEA
4
5
2 数据长度 0x00
0x02
6~7 2 最大单包数据长度 Len1 见说明
8 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Len1:最大单包数据长度,设备允许的单包数据最大长度,单位字节。

示例55 AA 00 EA 00 02 00 C8 B3

MCU 回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xEA
4
5
2 数据长度 0x00
0x06
6~11 6 Data 见下表
12 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 格式

1 2~4 5~6
Flag MCU 当前固件版本号(Version 可接受最大数据长度(Len2
  • Flag:0x00:允许升级,0x01:拒绝升级。
  • Version:当前固件版本号,例如 0x01 00 02 代表版本为 V1.0.2。
  • Len1:模组限定最大单包数据长度。
  • Len2:MCU 可接受最大包长度,如果 len1<len2,升级以 len1 为准,反之以 len2 为准。

示例55 AA 00 EA 00 06 00 01 00 00 00 C8 B8

MCU OTA 升级文件信息(CMD-0xEB)

模组发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xEB
4
5
2 数据长度 0x00
0x23
6~40 35 Data 见下表
41 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 格式

8 字节 3 字节 16 字节 4 字节 4 字节
产品 PID 文件版本 文件 MD5 文件长度 CRC32
  • PID:MCU 的 PID。
  • 文件版本:例如,0x010002 代表版本为 V1.0.2。
  • 文件 MD5:升级固件的 MD5 值。
  • 文件长度:升级固件的总长度,单位字节。
  • CRC32:升级固件的 CRC32。

MCU 回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xEB
4
5
2 数据长度 0x00
0x19
6~30 25 Data 见下表
31 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 格式

1 字节 4 字节 4 字节 16 字节
STATE 已储存文件长度 已储存文件 CRC32 已储存文件 MD5(目前不使用)

STATE:

  • 0x00:正常升级。
  • 0x01:产品 PID 不一致。
  • 0x02:文件版本低于或者等于当前版本。
  • 0x03:文件大小超过范围。
  • 其他:保留。
  • 为了支持断点续传,这里会返回设备端已经储存的文件信息。
    1. App 收到信息后,根据设备返回的已储存文件长度,计算新文件对应长度的 CRC32,然后和设备返回的 CRC32 对比。
    2. 如果两者都吻合,那么在下面的文件起始传输请求中将起始传输偏移量改为该长度值。否则文件起始传输偏移量改为 0,表示从头开始传输。
  • 每次断点续传都会完全按照 MCU OTA 流程的顺序,从 OTA 升级请求开始。所以 MCU 如果有维护升级状态的话,需要在收到模组工作状态为非绑定已连接的其他状态时重置升级状态,以确保可以开始下一个升级流程。

MCU OTA 升级文件偏移请求(CMD-0xEC)

有关协议接口支持情况,请参考 通用固件协议接口支持情况

模组发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xEC
4
5
2 数据长度 0x00
0x04
6~9 4 OFFSET 见下表
10 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

offset:文件起始传输偏移量,四字节。

MCU 回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xEC
4
5
2 数据长度 0x00
0x04
6~9 4 OFFSET 见下表
10 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

offset:MCU 要求的起始传输文件偏移量

实际文件传输的偏移地址应该以 MCU 端要求的为准,且 MCU 端要求的地址会小于等于 App 端给出的偏移。

MCU OTA 升级数据(CMD-0xED)

有关协议接口支持情况,请参考 通用固件协议接口支持情况

模组发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xED
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len Data 见下表
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 格式

2 字节 2 字节 2 字节 n 字节
包号 当前包数据长度 n 当前包数据 CRC16 当前包数据

包号从 0 开始,当前包数据长度不能大于 OTA 升级请求指令制定的最大包长度。

MCU 回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xED
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:成功
  • 0x01:包号异常
  • 0x02:长度不一致
  • 0x03:CRC 校验失败
  • 0x04:其他

MCU OTA 升级结束(CMD-0xEE)

有关协议接口支持情况,请参考 通用固件协议接口支持情况

模组发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xEE
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

MCU 回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xEE
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:成功
  • 0x01:数据总长度错误
  • 0x02:长度不一致
  • 0x03:其他

产测相关接口

RF 射频测试(CMD-0x0E)

  • 为了检测出厂后蓝牙模组的射频是否正常工作,需要测试模组的 RSSI 信号强度。

  • 测试工具:

    • 蓝牙信标:涂鸦提供
    • 作用:发射名称为 ty_mdev 的广播信号
  • 测试步骤:

    1. 将信标放在距离模组较近(0.5 米左右)的地方。
    2. 通过串口发送该 RF 射频测试指令。
    3. 模组会搜索蓝牙信标并返回信号强度值,一般信号强度大于 -70db 认为模组射频工作正常。

    一些特殊芯片/模组,例如 BK3431Q,BK3432,不支持扫描信标的方式,测试 RSSI 需要使用以下工具:

    • 测试工具:蓝牙 dongle(涂鸦提供),作用:连接被测设备并返回 RSSI。
    • 测试步骤:
      1. 将 dongle 放在距离模组较近(0.5 米左右)的地方。
      2. 通过串口向模组发送该 RF 射频测试指令。
      3. dongle 会连接模组并返回信号强度值,一般信号强度大于- 70db 认为模组射频工作正常。
        模组需要保持非低功耗模式,且模组处于非绑定状态。
        :::

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x0E
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0x0E
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len Data 见下表
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 格式

Data 说明
{“ret”:true,“rssi”:“-55”} 信号强度为 -55db
{“ret”:false} 没有搜索到该信号

低功耗功能附加协议

低功耗工作说明

  • 模组工作模式分为低功耗模式和正常模式:

    • 正常模式:蓝牙广播间隔约为 100ms,暂不开放设置,串口可上行可下行。

    • 低功耗模式:蓝牙广播间隔为 MCU 设置的参数(如果是 0 则关闭广播,默认 1s)。该模式下模组串口下行正常工作,上行禁用(不接收 MCU 串口数据)。

      BK3432 在进入低功耗模式后,将主动断开蓝牙连接并关闭蓝牙广播。

  • 模组的低功耗工作状态由模组低功耗控制引脚的电平决定,MCU 可以通过低功耗控制引脚输出不同电平控制模组的功耗状态。Lowpower_moudle_enable 表示是否需要通过 CMD-0xE5 使能低功耗功能模块,具体参考下表:

    芯片(category) Lowpower_moudle_enable Moudle_wakeup_pin Wakeup_level Idle_level
    chip-tlsr825x(all) needed TL_B5 high low
    chip-phy6222(all) needed P26 high low
    chip-bk3432(all) needed P03(configurable) high low
    chip-bk3431q(lock) unneeded P03 high low
    chip-nrf52832(lock) unneeded IO11 low high

    建议在唤醒模组后,延时 100ms 再使用串口。特殊的,Telink 在深度休眠后需要 1 秒的唤醒启动时间。

  • 当模组需要发送数据给外部 MCU 时,模组会在切换 MCU 唤醒脚的电平切换至 wakeup_level 后一定时间后,才发送数据给 MCU。发送完成后恢复为 Idle_level,具体参考下表:

    芯片(category) Lowpower_moudle_enable Wakeup_mcu_pin Wakeup_level Idle_level
    chip-tlsr825x(all) needed TL_D2 high low
    chip-phy6222(all) needed P31 high low
    chip-bk3432(all) needed / / /
    chip-bk3431q(lock) unneeded P10 high low
    chip-nrf52832(lock) unneeded IO14 low high

    唤醒时间见 CMD-0xB0 说明部分。

  • 模组将在每次连接事件后自动获取 App 时间以校准蓝牙模组内部时间,该模组内部时钟精度取决于晶振的质量,如果您需要精度高的时间,请务必测量模组内部时钟的精度。测试程序请联系您的涂鸦技术支持工程师或客户经理。模组内部时钟掉电将重置。

  • 可选择关闭低功耗下系统计时以降低功耗。

  • 当供电电压低于正常工作电压时,芯片内部 Flash 操作将有出错的风险,造成固件或者用户数据被异常修改。以下方法可以保护该使用场景:

    • MCU:当 MCU 检测到电池电压过低时,切断模组工作电源或关闭广播并控制芯片进入睡眠模式。

    • 模组:当模组检测到工作电压低于正常工作电压时,模组会进入睡眠模式。

      唤醒脚各平台默认上下拉情况可能存在差异,MCU 端与模组唤醒脚对接的引脚不要使用悬空状态。

使能低功耗功能(CMD-0xE5)

  • 低功耗工作说明部分 Lowpower_moudle_enable 字段为 needed 的固件,需要先通过该指令使能低功耗功能。然后才能通过 Moudle_wakeup_pin 控制模块的工作模式。该设置将永久储存。
  • 使能低功耗功能并不是让模组立即进入低功耗模式。模组具体使用哪种功耗模式运行,取决于当前模组功耗控制管脚的高低电平。
  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE5
4
5
2 数据长度 0x00
0x01
6 1 Data 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 取值说明:

  • 0x00:关闭低功耗功能
  • 0x01:打开低功耗功能

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE5
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:成功
  • 其他:失败

系统计时器配置(CMD-0xE4)

  • 为降低芯片低休眠时的功耗,可以通过该指令关闭蓝牙模组内部计时功能。如果 MCU 不需要时间功能,也可以关闭该功能。该设置永久存储。

  • BK3431Q 和 TYBN1 中,由于单纯计时功耗比较低,主要耗电的是存 Flash 操作,这里只是关闭了 Flash 存储操作。打开后,时钟可周期性(1min)存 Flash,可解决重启后模组时钟时间重置的问题。默认为关闭状态。

    对于 Telink 模组,当计时功能和广播功能都关闭后,拉低模组低功耗引脚后会进入深度睡眠,功耗降低至 3uA,唤醒后,模组将重启,重新运行。

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE4
4
5
2 数据长度 0x00
0x01
6 1 Data 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 取值说明:

  • 0x00:关闭系统计时器
  • 0x01:打开系统计时器

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE4
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:成功
  • 其他:失败

模组唤醒引脚配置(CMD-0xE3)

  • 适用模组:目前仅适用于 BK3432 通用固件。

  • 主要用于芯片对接您的自定义模组低功耗唤醒引脚。如果您需要使用非默认引脚外的引脚进行唤醒模组,建议在 MCU 初始化 UART 后立即通过该指令对模组低功耗唤醒引脚进行配置。

  • 设置永久存储。

  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

    由于模组进入低功耗后串口不可上行,所以 MCU 需要在模组上电 1s 内(模组上电 1s 内不会进入低功耗)进行设置或者在开低功耗使能之前设置(模组默认是关低功耗使能的)。

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE3
4
5
2 数据长度 0x00
0x06
6~11 6 数据内容 CFG 见下表
12 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

数据内容 CFG 格式

4 字节 1 字节 1 字节
PIN_NUM 保留 保留

PIN_NUM 大端传输,保留字段不解析,填 0xff/0x00 即可。如果对 PIN_NUM 不清楚可联系您的涂鸦技术支持工程师或客户经理确认配置指令。

示例

  • 设置 BK3432 P03 为模组低功耗唤醒引脚,P03 对应 PIN_NUM 为 0x03

    55 AA 00 E3 00 06 00 00 00 03 00 00 EB

  • 设置 BK3432 P11 为模组低功耗唤醒引脚,P11 对应 PIN_NUM 为 0x11

    55 AA 00 E3 00 06 00 00 00 11 00 00 F9

    BK3432 目前有 P02、P03、P04、P05、P10、P11、P12、P13、P34、P14、P35、P32、P31 可配置。BK 的 Pxx 对应 PIN_NUM 为 0xxx。

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE3
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:成功
  • 其他:失败

MCU 低功耗唤醒配置(CMD-0xB0)

  • MCU 可以通过该接口配置自身从低功耗唤醒所需要的时间 t。

    模组向 MCU 发送串口数据将会先拉高或拉低 t 时间左右的 MCU 唤醒引脚。

  • MCU 修改后,需测试唤醒时间是否能正常唤醒 MCU,如果不能需则调大。

  • 调用时机:建议 MCU 在收到 CMD-0x0255 aa 00 02 00 00 01)后,调用该接口设置 MCU 低功耗唤醒配置。(该设置非永久存储,模组上电/重启后恢复默认值)

  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xB0
4
5
2 数据长度 0x00
0x01
6 1 interval 见说明
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

interval 表示间隔单位,为 10ms。取值范围为 1~20,即最小支持 10ms,最大支持 200ms。

示例

  • 55 aa 00 E2 00 01 00 E2:设置低功耗模式下关闭广播
  • 55 aa 00 E2 00 01 06 E8:设置低功耗下广播间隔为 600ms

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xB0
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:成功
  • 其他:失败

功能拓展协议

本章节协议为一些功能拓展协议,主要包括动态数据上报、大数据存储上报、文件下发和天气等功能接口。您可根据产品的特性选用以下接口以丰富产品的功能。

带标志位 DP 上报(CMD-0xA4)

  • 适用固件:BK3432 共享协议通用固件、TYBT3L 共享协议通用固件。
  • 可根据不同标志选择是否上报面板或云端。一般用于动态数据、实时数据。
  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA4
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len Data 见下表
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 格式

2 字节 1 字节 1 字节 (可选)13 字节 m 字节
序号 SN Flag Time_flag Time_date datapoint
  • 序号 SN(2):两字节,高字节在前。

  • Flag(1):

    • 0x00:同时上报云端和面板
    • 0x01:上报云端,不上报面板
    • 0x02:上报面板,不上报云端
    • 0x03:都不上报
  • Time_flag(1) :

    • 0x00:模组自带时间上报
    • 0x01:MCU 自带时间上报
  • Time_date:仅 Time_flag 等于 0x01 时需要填写,该字段为 13 位 unix 时间字符串。

  • DP 数据封装(m):datapoint 参考 DP 格式 说明部分。

    55 aa 00 A4 00 16 00 01 01 00 66 02 00 04 00 00 00 01 28

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA4
4
5
2 数据长度 0x00
0x04
6~9 4 Data 见下表
10 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 格式

2 字节 1 字节 1 字节
序号 SN Flag State
  • 序号 SN(2):取自上报 SN
  • Flag(1):取自上报 Flag
  • State(1):0x00 成功,其他失败

大数据存储(CMD-0xB5)

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xB5
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6 1 SubCmd 见说明
7~7+Len-1 Len Data 见说明
7+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

SubCmd(子命令)

  • 0x00:数据存储
  • 0x01:存储配置

不同 SubCmd,Data 字段的格式不一样,模组端依据 SubCmd 及下面 Data 的格式进行解析。

  • SubCmd 为 0x00 时 Data 字段填充的数据格式如下:

    1~3 4 5~x x x+1 x+2~x+3 x+4~ …… n n+1 n+1~n+2 n+3~
    Res TYPE Time_Str dp1_id dp1_type dp1_len dp1_data …… dpN_id dpN_type dpN_len dpN_data

    Res:保留字段(3 字节),请设置为 0x00。

    TYPE 时间填充方式说明
    0x01 格式 1:蓝牙模组自带时间上报
    0x03 格式 3:MCU 自带时间上报

    Time_Str:

    • 13 位 UNIX 时间字符串。
    • 仅 TYP 等于 0x03 时需要填,其他格式不用填。
  • SubCmd 为 0x01 时 Data 字段填充的数据格式如下:

    CFG(1 字节) 说明
    0x00 小数据存储,常用于 2 个内(含)value 型 DP 的存储,dplen1+3+[dplen2+3]+[dplen_n+3] <=17。
    0x01 中等长度数据存储,常用于 6 个内(含)value 型 DP 的存储,dplen1+3+[dplen2+3]+[dplen_n+3]<=49。
    0x02 默认配置,dplen1+3+[dplen2+3]+[dplen_n+3] <=113。

    当 CFG 发生改变时,模组会清空大数据存储区。

模组返回

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xB5
4
5
2 数据长度 0x00
0x01
6 1 SubCmd 见下表
7~7+Len-1 Len Data 见说明
7+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

SubCmd(子命令)

  • 0x00:数据存储
  • 0x01:存储配置

不同 SubCmd,Data 字段的格式不一样,模组端依据 SubCmd 及下面 Data 的格式进行解析。

  • SubCmd 为 0x00 时 Data 字段填充的数据格式如下:

    STATE(1字节):

    • 0x00:存储成功
    • 0x01:长度错误
    • 0x02:TYPE 错误
    • 0x03:DP 格式非法
    • 0x04:存储错误
    • 其他:失败
  • SubCmd 为 0x01 时 Data 字段填充的数据格式如下:

    1 2 3~4
    STATE MAX_SIZE TOTAL_NUM
    • STATE:
      • 0x00:设置成功
      • 其他:设置失败
    • MAX_SIZE:单条可存储组合 DP 的最大长度。
    • TOTAL_NUM:可存储的总条数。

示例

  • 配置为小数据存储(MCU > 蓝牙):55 aa 00 b5 00 02 01 00 B7
  • 配置为中等数据存储(MCU > 蓝牙):55 aa 00 b5 00 02 01 01 B8
  • 配置为通用数据存储(MCU > 蓝牙):55 aa 00 b5 00 02 01 02 B9
  • 存储一条数据(MCU > 蓝牙):55 AA 00 B5 00 12 00 01 01 02 00 04 00 00 01 04 02 02 00 04 00 00 00 DB

获取天气数据(CMD-0xB6)

  • 通过该接口可向手机请求获取指定位置及指定的天气数据。
  • 天气参数详情见附录。

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xB6
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len Data 见说明
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 说明:

位置 天气参数 预报天数
1字节 4字节 1字节
  • 位置:

    • 0x01:配网位置
    • 0x02:当前位置(手机)
  • 天气参数

    (1 << 0), /**< temperature. */
    (1 << 1), /**< high temperature. */
    (1 << 2), /**< low temperature. */
    (1 << 3), /**< humidity. */
    (1 << 4), /**< weather condition. */
    (1 << 5), /**< pressure. */
    (1 << 6), /**< sendible temperature. */
    (1 << 7), /**< uvi. */
    (1 << 8), /**< sunrise. */
    (1 << 9), /**< sunset. */
    (1 << 10), /**< unix time, Use with sunrise and sunset. */
    (1 << 11), /**< local time, Use with sunrise and sunset. */
    (1 << 12), /**< wind speed. */
    (1 << 13), /**< wind direction. */
    (1 << 14), /**< wind speed scale/level. */
    (1 << 15), /**< aqi. */
    (1 << 16), /**< tips. */
    (1 << 17), /**< Detailed AQI status and national ranking. */
    (1 << 18), /**< pm10. */
    (1 << 19), /**< pm2.5. */
    (1 << 20), /**< o3. */
    (1 << 21), /**< no2. */
    (1 << 22), /**< co. */
    (1 << 23), /**< so2. */
    (1 << 24), /**< weather condition mapping id. */
    
  • 预报天数:需要预报天数(n表示,需要预报的天数,1<= n <=7,1表示当天),详情见附录。

模组返回:

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xB6
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len Data 见说明
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 说明:Status(1字节)+ weather_values(0 字节或 Len-1 字节)。

  • Status:

    0x00-成功

    0x01-参数错误

    0x02-请求失败

    0x03-请求超时

    0x04-重复请求

    0x05-状态错误

  • Weather_values:天气值,仅当 Status=0x00 时有该字段,格式见下表。

{某天 天气参数(小端) 数据类型 数据长度x 数据} …… 依以上格式循环
1字节 4字节 1字节 1字节 x字节 …… 依以上格式循环

​ 数据类型:0x00-整形,0x01-字符串

例:

MCU->Moulde:

55 AA 00 B6 00 06 01 00 00 00 0F 01 CC

Moulde->MCU:

55 AA 00 B6 00 2D 00 01 01 00 00 00 00 04 00 00 00 21 01 02 00 00 00 00 04 00 00 00 24 01 04 00 00 00 00 04 00 00 00 1C 01 08 00 00 00 00 04 00 00 00 44 AA

蓝牙特有协议

主动断开蓝牙连接(CMD-0xE7)

断开蓝牙连接并进入广播状态。

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE7
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE7
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:成功
  • 其他:失败

蓝牙广播使能(CMD-0xA3)

  • 模组非低功耗固定 100ms 间隔的广播,低功耗默认 1000ms 间隔(MCU 可设置 0~2000,0 代表广播)的广播。App 扫描到广播即可配网。如果您希望配网的时机完全由 MCU 控制,可调用该接口来实现。

  • 广播使能状态模组会记录在 Flash 中,如果您希望配网时间由 MCU 控制,需要在串口初始化后调用该接口调整为 MCU 希望的默认使能状态。MCU 应该在需要配网的时候打开使能,不需要配网的时候关闭使能。

  • 模组默认是使能广播状态,通过该接口关闭模组广播使能,模组不管是低功耗还是非低功耗都不会有广播。

  • 如果关闭广播使能之前模组处于广播状态,关闭后模组会立即停止广播。

  • 打开广播使能后模组会立即启动广播

  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

    与修改低功耗下广播间隔来控制广播的区别主要在于,该接口可控制非低功耗下的广播,而修改低功耗下广播间隔只能作用于低功耗状态。所以控制配网时机需要使用使能广播接口。

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA3
4
5
2 数据长度 0x00
0x01
6 1 Data 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 取值说明:

  • 0x00:关闭广播使能
  • 0x01:打开广播使能

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA3
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:成功
  • 其他:失败

请求上线(CMD-0xA5)

  • 该接口主要用于网关按需连接。
    1. MCU 调用该接口后,蓝牙模组会启动 30s 高频广播。
    2. 蓝牙主机扫描带标志的模组广播后,会主动连接模组。
    3. 模组上线后,MCU 即可正常上报 DP。
  • 通常用法:记录型数据都调用 0xE0 上报。如果 MCU 检测到模组为绑定未连接状态,则调用该接口请求上线,模组上线后会自动释放通过 0xE0 上报的数据。
  • 实时数据不符合主动上报一般使用场景,但 MCU 端如果想实时数据也上报,有两种方法:
    1. 调用该接口后,等待模组工作状态变为绑定已连接(模组上线会下发工作状态)
    2. 通过 0xE0 的 0x02 格式上报实时数据,模组上线后会将数据释放给 App(不建议使用)
  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA5
4
5
2 数据长度 0x00
0x00
6 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA5
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:成功
  • 其他:失败

修改低功耗模式下的广播间隔(CMD-0xE2)

  • BK3432 共享类通用固件暂不支持该接口。

  • 为降低休眠时的功耗,可以通过该指令修改广播间隔,广播参数将永久保存。当设置为 0 时,将关闭广播。该设置将永久储存。

    低功耗下广播间隔默认 1s,广播间隔越大连接所需要的时间越长,甚至某些性能差手机可能很难连接上,不建议您修改更大的广播间隔值。

  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE2
4
5
2 数据长度 0x00
0x01
6 1 Adv_interval 见下表
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Adv_interval:可设置数值范围为 0 到 20,单位为 100ms,即实际广播间隔范围为 100ms 到 2 秒。当设置数值为 0 时将关闭广播。

示例

  • 55 aa 00 E2 00 01 00 E2:设置低功耗模式下关闭广播
  • 55 aa 00 E2 00 01 06 E8:设置低功耗下广播间隔为 600ms

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE2
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:成功
  • 其他:失败

蓝牙连接间隔设置(CMD-0xB1)

  • 适用模组:BT2S、BT5S、BT3L、BT7L(即 Telink825x 通用固件 8.10+版本支持)。
  • 若调用该接口时,模组处于绑定已连接状态,将会向主节点(master)发送更新连接参数请求。否则仅记录连接参数,之后连接时使用。特殊的,如果当前模组处于 OTA 状态,将不会向主节点(master)请求更新,但会将 MCU 设置的参数保存下来。
  • 如果模组有离线缓存数据未释放,重连时模组会在离线缓存数据完全释放完后才更新为 MCU 设置的连接参数。
  • 设置永久存储。
  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xB1
4
5
2 数据长度 0x00
0x0B
6~16 11 CFG 见说明
17 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

CFG 格式:

1 字节 1 字节 1 字节 2 字节 2 字节 2 字节 2 字节
cfg_type cfg_ack mode min_interval max_interval latency timeout
  • cfg_type:配置方式

    • 0x00:按模式配置,根据 mode 字段选择连接参数,min_intervalmin_intervallatencytimeout 字段不生效,一般建议使用这种方式。
    • 0x01:自定义配置方式,支持自定义连接参数,即根据 min_interval~timeout 字段参数配置连接间隔,该方式供蓝牙开发者使用。
  • cfg_ack:配置响应

    • 0x00:不需要配置成功响应
    • 0x01:需要配置成功响应。连接参数主要由主节点(master)指定,有的情况会更新不成功,配置需要响应,则会在成功更新连接参数后,将使用的连接参数下发给 MCU。
  • mode

    • 0x00:快速模式,蓝牙交互响应快,但功耗较高。适用于功耗要求一般,要求快速响应的产品。
    • 0x01:均衡模式,功耗和蓝牙交互响应速度适中,适用于对功耗要求一般的产品。
    • 0x02:低速模式,响应慢,但功耗低,适用于对功耗要求高,但交互频率低的产品,例如传感类产品。
  • min_interval:最小连接间隔,单位:1.25ms。范围参考 GAP 连接参数限制。

  • max_interval:最大连接间隔,单位:1.25ms。范围参考 GAP 连接参数限制。

  • latency:连接事件数量中的从属延迟。范围参考 GAP 连接参数限制。

  • timeout:连接超时时间,单位 10 ms。范围参考 GAP 连接参数限制。

    大于两字节字段按大端传输。若无必要,cfg_typecfg_ack 建议使用 0x00。

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xB1
4
5
2 数据长度 0x00
0x09
6~14 1 State 返回的状态值
15 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 说明

1 字节 2 字节 2 字节 2 字节 2 字节
result min_interval max_interval latency timeout

result 说明

  • 0x00:收到连接参数更新请求,模组将向主节点(master)发起连接参数更新请求。min_intervalmax_intervallatencytimeout 字段表示目标连接参数。

  • 0x01:更新连接参数成功,min_intervalmax_intervallatencytimeout 字段表示实际更新到的连接参数。

  • 0x02:更新连接参数失败,min_intervalmax_intervallatencytimeout 字段表示目标的连接参数。

  • 0x03:非法状态,一般表示当前模组状态非绑定已连接状态。

  • 0x06:无效参数。

  • 其他:失败

    cfg_ack 配置为 0x01 的时候,模组才会在实际更新连接参数成功后,同步当前连接参数给 MCU。即 result-0x01 和 result-0x02 只有 cfg_ack 设置为 0x01 才会收到,否则模组不回同步结果给 MCU。

示例

  • 设置为低速模式:

    • MCU 发送55 AA 00 B1 00 0B 00 00 02 00 00 00 00 00 00 00 00 BD
    • 模组回复55 AA 00 B1 00 09 00 01 90 01 A0 00 00 01 90 7C
  • 设置为均衡模式:

    • MCU 发送55 AA 00 B1 00 0B 00 00 01 00 00 00 00 00 00 00 00 BC
    • 模组回复55 AA 00 B1 00 09 00 00 90 00 A0 00 00 01 90 7A
  • 设置为快速模式:

    • MCU 发送55 AA 00 B1 00 0B 00 00 00 00 00 00 00 00 00 00 00 BB
    • 模组回复55 AA 00 B1 00 09 00 00 32 00 3C 00 00 01 90 B8
  • 设置为自定义参数:

    • MCU 发送55 AA 00 B1 00 0B 01 00 00 01 90 01 A0 00 00 01 90 7F
    • 模组回复55 AA 00 B1 00 09 00 01 90 01 A0 00 00 01 90 7C

蓝牙 HID 相关(CMD-0xBA)

  • 用于需要 HID 自动回连的特定使用场景的产品,一般类型产品无需配置。
  • 使用 HID 相关功能必选在 CMD-0x01 获取 MCU 信息中上传 TLD 字段,以使能 SMP 功能模块。否则,模组将拒绝该指令。
  • RSSI 受环境干扰会有一定波动,在使用 RSSI 做阈值判断时需多取几个,以提高准确性。

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xBA
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6 1 SubCmd 见说明
7~7+Len-1 Len Data 见说明
7+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

SubCmd(子命令)

  • 0x00:SMP 使能配置

    暂不支持动态配置 SMP,请在 CMD-0x01(获取 MCU 信息)中上报 SMP 使能状态。默认不使能 SMP 模块,使能状态发生改变时蓝牙模组将会自重启一次,并清空配对信息,以完成相关初始化。该配置支持断电记忆。

  • 0x01:请求 HID 配对

  • 0x02:请求 HID 配对连接下的 RSSI

  • 0x03:查询 HID 配对状态

    不同 SubCmd,Data 字段的格式不一样,模组端依据 SubCmd 及下面 Data 的格式进行解析。

Data(数据格式)

  • SubCmd 为 0x01 和 0x03 时,Data 字段为空。

    • 示例 1:请求 HID 配对

      MCU > 模组 :55 aa 00 BA 00 01 01 BB

    • 示例 2:查询 HID 配对状态

      MCU > 模组 :55 aa 00 BA 00 01 03 BD

  • SubCmd 为 0x02 时 Data 字段填充的数据格式如下:

    1 2 3
    op num interval
    • op:操作。0x00:停止获取。0x01:开始获取。

    • num:需要获取 RSSI 的数量。

    • interval:下发 RSSI 的间隔,单位 100ms,限制可设置范围为 1~20。

      • 示例:请求开始获取 HID 配对连接下的 RSSI,数量 10 包,间隔 200ms。
      • MCU > 模组:55 AA 00 BA 00 04 02 01 0A 02 CC

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xBA
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6 1 SubCmd 见下表
7~7+Len-1 Len Data 见说明
7+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

SubCmd(子命令)

  • 0x00:SMP 使能配置

  • 0x01:请求 HID 配对

  • 0x02:请求 HID 配对连接下的 RSSI

  • 0x03:查询 HID 配对状态/HID 配对状态通知

    不同 SubCmd,Data 字段的格式不一样,MCU 请依据 SubCmd 及下面 Data 的格式进行解析。

  • SubCmd 为 0x00 时 Data 字段填充的数据为 1 个字节的状态码 Status,其含义如下:

    Status:

    • 0x00:SMP 使能成功
    • 0x01:SMP 使能失败
  • SubCmd 为 0x01 时 Data 字段填充的数据为 1 个字节的状态码 Status,其含义如下:

    Status:

    • 0x00:已发送 HID 配对请求
    • 0x01:HID 配对失败
    • 0x02:HID 配对成功
    • 0x03:状态错误
    • 0x04:拒绝
  • SubCmd 为 0x02 时 Data 字段填充的数据格式如下:

    1 2
    Status rssi_raw
    • rssi_raw:status 非 0 的情况下,rssi_raw 的值为 0xff。
    • rssi_real:= rssi_raw- 110,假设 rssi_raw 返回值为 50,则 rssi = -60 db。

    Status:

    • 0x00:成功
    • 0x02:参数错误
    • 0x03:非 HID 连接配对状态
    • 0x04:拒绝
  • SubCmd 为 0x03 时 Data 字段填充的数据为 1 个字节的状态码 Status,其含义如下:

    Status:

    • 0x00:未连接
    • 0x01:已连接
    • 0x02:HID 配对已连接
    • 0x04:拒绝
    • 0x05:HID 配对已连接且校验通过

蓝牙广播名字设置(CMD-0xBB)

仅允许处于未绑定状态时设置,其他状态模组将拒绝。

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xBB
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len Data 见说明
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 格式

1 2~2+ADV_LOCAL_NAME_LEN-1
ADV_LOCAL_NAME_LEN ADV_LOCAL_NAME
  • ADV_LOCAL_NAME_LEN:广播名的字符串长度。(基于 V2.1.2 以下基线的固件最大支持 5 个字节,V2.1.2(含)以上的最大支持 14 个字节)
  • ADV_LOCAL_NAME:广播名字,ASCII 码。

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xBB
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:成功
  • 0x01:超出长度
  • 0x02:拒绝

门锁类附加协议

该章节协议为门锁类通用固件附加的协议,其他品类通用固件不支持该协议。

动态密码(CMD-0xE6)

  • 模组计算动态密码基于时间,必须确保云端和设备时间同步,计算的动态密码才一致,否则将导致密码错误。(设备与 App 建立连接会自动同步时间)
  • 管理员密码入参暂不支持,当前管理员密码长度填 0 即可
  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE6
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len Data 见下表
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 格式

8 字节 1 字节 N 字节 N 字节 ……
password 管理员密码长度 第 1 组管理员密码 第 2 组管理员密码 ……

password:用户输入的密码数据 Data[0]~Data[7]数据内容范围为 ‘0’~’9’ 数据传输使用 ASCII 码

管理员密码入参暂不支持,当前管理员密码长度填 0 即可

示例:MCU 发送不带管理员密码的数据包

55 aa 00 E6 00 09 30 31 32 33 34 35 36 37 00 8a

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xE6
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:密码核对通过
  • 0x01:密码核对失败

示例

  • 55 AA 00 E6 00 01 01 E7:密码核对失败
  • 55 AA 00 E6 00 01 00 E6:密码核对通过

新动态密码校验(CMD-0xA7)

  • 协议中的时间数据用于运算当前的动态密码,这里的动态密码运算时间都为当前的格林时间,设备需要给模组格林时间数据。
  • 功能上和 CMD-0xE6 完全相同,参数部分有改动,支持 MCU 传递时间。
  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA7
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len Data 见下表
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 格式

1 字节 1 字节 1 字节 1 字节 1 字节 1 字节 1 字节 1 字节 N 字节
TimeSource 2000+Year Mon Day Hour Min Sec Code_len Code
  • TimeSource:填 0x00 即可。

    • 0x00:时间来源于 MCU 上传的 year/mon/day/hort/min/sec 字段。

    • 0x01:使用模组内部时间,year/mon/day/hort/min/sec 不解析。

      MCU 上传时间说明:MCU 传的时间应是格林时间的年月日格式,即 0 时区的年月日时间。如北京时间 2020 年 6 月 20 日 12 时 00 分 00 秒,格林时间填 0x14 0x06 0x14 0x04 0x00 0x00。

  • Code_len:密码长度。

  • Code:密码。区别于旧动态密码 CMD-0xE6 中密码传 ASCII 码 1~9 的十进制格式,新动态密码直接传数字,1 即 0x01,9 即 0x09。可参考以下示例。

示例

55 AA 00 A7 00 10 00 14 0A 09 0D 33 2C 08 01 08 05 08 06 04 04 05 7A

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA7
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len State 返回的状态值
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:密码核对通过
  • 0x01:密码核对失败

示例

  • 55 AA 00 A7 00 01 01 A8:密码核对失败
  • 55 AA 00 A7 00 01 00 A7:密码核对通过

离线密码(CMD-0xA2)

  • 设备长时间不联网也可使用的动态密码。
  • 模组内部时钟精度不高,24 小时低于 1min,模组在每次上线时会同步一次云端时间,模组内部时钟不支持掉电工作,即掉电会重置。

    如果 MCU 有外接时钟,强烈建议时钟源选择 0x00,即 MCU 上传格林时间。使用模组内部时钟可找研发要测试程序测量时钟误差。

  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA2
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len Data 见下表
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 格式

1 字节 1 字节 1 字节 1 字节 1 字节 1 字节 1 字节 1 字节 N 字节
TimeSource 2000+Year Mon Day Hour Min Sec Code_len Code
  • TimeSource:填 0x00 即可。

    • 0x00 时间来源于 MCU 上传的 year/mon/day/hour/min/sec 字段。

    • 0x01 使用模组内部时间,year/mon/day/hour/min/sec 不解析。

      MCU 上传时间说明:MCU 传的时间应是格林时间的年月日格式,即 0 时区的年月日时间。如北京时间 2020 年 6 月 20 日 12 时 00 分 00 秒,格林时间填 0x14 0x06 0x14 0x04 0x00 0x00。

  • Code_len:密码长度。

  • Code:密码。区别于动态密码中密码传 ASCII 码 1~9 的十进制格式,离线密码直接传数字,1 即 0x01,9 即 0x09。可参考以下示例。

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA2
4
5
2 数据长度 Len Len 高 8 位
Len 低 8 位
6~6+Len-1 Len Data 见下表
6+Len 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

Data 格式

1 字节 1 字节 1 字节 N 字节
Result Type Decode_len Decode
  • Result

    • 0x00:正确
    • 其他:错误(后续数据无意义)
  • Type

    • 0x00:验证成功
    • 0x01 清空单条成功
    • 0x02:清空所有成功
  • Code_len:加密后的数据长度

  • code:加密后的清空码和开锁密码

    Typecode 用于 MCU DP 上报使用,参照门锁 DP 协议离线密码功能解析,dpid 为 65、66、67。

例如:使用模组内部时间+密码(2279084005)

  • MCU:55 AA 00 A2 00 12 01 00 00 00 00 00 00 0A 02 02 07 09 00 08 04 00 00 05 E3
  • 模组:55 AA 00 A2 00 13 00 00 10 F3 50 3C 8F FF 03 F5 E9 0D 54 99 2A 62 A1 DE 42 F9

门锁业务功能配置(CMD-0xA6)

  • 适用模组:
    • TYBN1 门锁通用固件 6.2 以上版本支持
    • BK3431Q 门锁通用固件 3.3 以上版本支持
  • 一些门锁功能需要模组封装处理 DP 部分字段,为了不影响不使用这些功能,将对这部分功能设置开关,且默认关闭。该设置永久存储。
  • 目前需要通过该接口配置的功能有:
    • 门锁端配件功能
    • 配件端开关锁功能
    • 门锁密码进制配置
  • 有关协议接口支持情况,请参考 通用固件协议接口支持情况

MCU 发送

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA6
4
5
2 数据长度 0x00
0x04
6~9 4 DATA 见下表
10 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

CFG 格式:

配置项 0 配置项 1 配置项 2 配置项 3
1 2 3 4
FLAG PWD_NUM PWD_BEGIN_NUM 保留(0x00)
  • FLAG

    • bit0:门锁端配件功能使能(0 关/1 开,默认关闭)

    • bit1:配件端开关锁功能使能(0 关/1 开,默认关闭)

      bit0 和 bit1 互斥,即打开一个另外一个则自动变成关闭。

    • bit2:保留

    • bit3:保留

    • bit4:保留

    • bit5:保留

    • bit6:保留

    • bit7:保留

  • PWD_NUM:表示组成门锁密码的数字个数,默认 10 个(数字 0~数字 9)。部分密码盘上只有 4~9 个连续数字的情况可以通过该字段进行配置。另外可通过 PWD_BEGIN_NUM 配置密码从数字 0 开始还是从数字 1 开始。

    PWD_NUM 字段只有填 0x04~0x09 才会生效,其余数字均使用默认设置(10 个数字)。

  • PWD_BEGIN_NUM:表示密码盘上最小的数字,从数字 0 开始还是从数字 1 开始。如果密码盘从数字 0 开始,则填 0x00。如果从数字 1 开始,则填 0x01。

    PWD_BEGIN_NUM 字段只有填 0x00 或 0x01 才会生效,其余数字均使用默认设置(从数字 0 开始)。

示例

  • 55 AA 00 A6 00 04 01 00 00 00 AA:打开门锁配件功能
  • 55 AA 00 A6 00 04 00 00 00 00 A9:关闭门锁配件功能

模组回复

序号 字节数 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA6
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:设置成功
  • 其他:设置失败
点击展开“对接指南”

Q:这个协议接口有什么作用?什么时候需配置?

A:用于配置模组端业务功能逻辑的开关(主要是设计到 DP 的业务)。目前有三个业务逻辑的封装:

  • 门锁端配件功能。
  • 配件端开关锁功能。(这两个功能都是服务于门锁蓝牙配件的,一个是用于门锁的,一个是用于配件的。)
  • 多位密码配置。

如果门锁用不到配件的可以不配置,默认是全关闭的。如果有配件需求的,可以在 MCU 串口初始化后,发送一次进行配置即可,该配置永久存储。

Q:非十进制密码盘怎么办?多位密码功能如何配置?

  • PWD_NUM:表示组成门锁密码的数字个数,默认 10 个(数字 0~数字 9)。部分密码盘上只有 4~9 个连续数字的情况可以通过该字段进行配置。另外可通过 PWD_BEGIN_NUM 配置密码从数字 0 开始还是从数字 1 开始。

    PWD_NUM 字段只有填 0x04~0x09 才会生效,其余数字均使用默认设置(10 个数字)。

  • PWD_BEGIN_NUM:表示密码盘上最小的数字,从数字 0 开始还是从数字 1 开始。如果密码盘从数字 0 开始,则填 0x00。如果从数字 1 开始,则填 0x01。

    PWD_BEGIN_NUM 字段只有填 0x00 或 0x01 才会生效,其余数字均使用默认设置(从数字 0 开始)。

配置示例

  • 示例 1:密码盘上只有数字 1、2、3、4、5、6,则 PWD_NUM 设置为 6,PWD_BEGIN_NUM 设置为 1。

  • 示例 2:密码盘上只有数字 0、1、2、3、4、5、6,7、8,则 PWD_NUM 设置为 9,PWD_BEGIN_NUM 设置为 0。

Q:门锁端配件功能如何对接?

A:MCU 对接-门锁配件功能对接介绍
门锁配件功能涉及 4 个 门锁新增的 DP,以及一个通用串口协议接口 CMD 0xA6(门锁业务功能配置)。

门锁和配件之间的配对、重连这些其实已经被门锁封装门锁通用固件中了,这部分无需关心。

为了提高安全等级,确保配件出现后门锁端的相对安全,在业务层进行了身份的二次确认,过程如下:

  • 云端为主机(App/配件)分配“主机 ID+主机随机数”,用于唯一识别主机。
    云端为从机(门锁)分配“从机 ID+从机随机数”,用于唯一识别从机。

  • 云端首先将 App 的“主机 ID+主机随机数”和门锁的“从机 ID”发送给门锁,此时认为 App 和门锁完成了业务配对。
    然后将配件的“主机 ID+主机随机数”发送给门锁,将配件的“主机 ID+主机随机数”和门锁的“从机 ID”发送给配件,此时认为配件和门锁完成了业务配对。

  • 此时,门锁端存储着:
    App 的“主机 ID+主机随机数”
    配件的“主机 ID+主机随机数”(一个/多个)
    门锁的“从机 ID”

  • 配件端存储着:
    配件的“主机 ID+主机随机数”
    门锁的“从机 ID”

此时,配件能够对门锁做的操作只有“开锁”,且配件在做这一操作之前需要告诉门锁自己的身份(配件的“主机 ID+主机随机数”)和门锁的身份(门锁的“从机 ID”),以此保证通信的安全。

以上逻辑门锁通用固件对其进行了封装。但由于这个逻辑需要对 DP 内容进行抓取、解析,因此属于业务逻辑,且通用固件原则上是不处理 DP 内容,只进行透传。所以,门锁通用固件为了保持通用性,对该逻辑默认进行了关闭处理。如果您需要对接和使用该功能,通过 CMD 0xA6 接口对该功能进行配置打开,模组才会对其处理(模组只是抓取内容和解析主机 ID、从机 ID、随机数,并不会改变数据内容)。

否则,模组将直接将数据进行透传处理,有 MCU 完成相关逻辑。

配件身份验证逻辑封装

通过 CMD 0xA6(55 AA 00 A6 00 04 01 00 00 00 AA)打开门锁配件功能后,模组将会完全处理 dpid=70 配置主机随机数不会透传给 MCU。

而对于 dpid=71 开关锁和 dpid=73 远程开锁配置模组会抓取 DP 内容中的主机 ID、从机 ID、随机数字段进行身份验证:

  • 如果身份验证成功,模组会将 DP 数据完全透传给 MCU,MCU 需要对开关锁远程开锁配置除(主机 ID、从机 ID、随机数)部分的门锁业务逻辑进行处理。
  • 如果身份验证失败,模组将不会透传给 MCU,而是直接回复失败信息。

MCU 端 DP 处理

开启模组门锁配件业务能力后,模组只是根据(主机 ID、从机 ID、随机数)来对配件进行身份验证,进而决定是否透传给 MCU 处理。MCU 收到后虽然不需要对(主机 ID、从机 ID、随机数)这几个字段做逻辑判断和处理,但需要根据协议对字段调整下位置,例如 dpid=71:

功能 数据
方向
dp_id
(1 字节)
dp_type
(1 字节)
dp_da
ta_len
(1
字节)
dp_data_value


下发 71 raw len 主机 ID
(2 字节)
从机 ID
(2 字节)
随机数
(8 字节)
操作
(1 字节)
开关锁
时间戳
(4 字节)
开关锁
方式
(1 字节)
开关锁
信息
(len-12 字节)
0~10000 0~10000 主机随机数 0x00:关锁
0x01:开锁
说明 说明 说明
上报 71 raw len 从机 ID
(2 字节)
主机 ID
(2 字节)
随机数
(8 字节)
操作
(1 字节)
开关锁
时间戳
(4 字节)
开关锁
方式
(1 字节)
返回状态
(1 字节)
0~10000 0~10000 主机随机数 0x00:关锁
0x01:开锁
说明 说明 取值范围

MCU 需要注意主机 ID 和从机 ID 的位置需要对调了

  • 模组->MCU:55 AA 00 06 00 17 47 00 00 13 00 02 00 01 39 38 36 35 33 36 33 39 01 01 E4 6D 11 5F 00 ED
  • MCU->模组:55 AA 00 07 00 17 47 00 00 13 00 01 00 02 39 38 36 35 33 36 33 39 01 01 E4 6D 11 5F 00 EE

其他dpid=73也是一样处理。

MCU 在收到dpid=71 开关锁 DP 后,需要记录下主机 ID、从机 ID、随机数,然后在开/关锁成功后通过开关锁记录上报下开关锁记录,其中主机 ID、从机 ID、随机数来源之前 dpid-71 记录的。

功能 数据
方向
dp_id
(1 字节)
dp_type
(1 字节)
dp_da
ta_len
(1
字节)
dp_data_value




上报 72 raw len 从机 ID
(2 字节)
主机 ID
(2 字节)
随机数
(8 字节)
操作
(1 字节)
开关锁
时间戳
(4 字节)
开关锁
方式
(1 字节)
开关锁
信息
(len-12 字节)
0~10000 0~10000 主机随机数 0x00:关锁
0x01:开锁
说明 说明 说明

Q:配件端开关锁功能如何对接?

A:蓝牙配件-MCU 对接方案,需要首先使用 门锁业务功能配置(CMD-0xA6) 接口将配件端开关锁功能使能,使能的目的为打开配件的相关业务功能:

模组在收到 MCU 发送的 开关锁 命令后,模组会根据开关锁 DP 中的从机 ID,在 Flash 中查询是否有相关信息,有则说明门锁已经添加过该配件,配件可以控制门锁开关锁。然后模组会对门锁发起重连并转发开关锁 DP,门锁收到开关锁 DP 后进行开关锁操作。

功能 数据
方向
dp_id
(1 字节)
dp_type
(1 字节)
dp_da
ta_len
(1
字节)
dp_data_value


下发 71 raw len 主机 ID
(2 字节)
从机 ID
(2 字节)
随机数
(8 字节)
操作
(1 字节)
开关锁
时间戳
(4 字节)
开关锁
方式
(1 字节)
开关锁
信息
(len-12 字节)
0~10000 0~10000 主机随机数 0x00:关锁
0x01:开锁
说明 说明 说明
上报 71 raw len 从机 ID
(2 字节)
主机 ID
(2 字节)
随机数
(8 字节)
操作
(1 字节)
开关锁
时间戳
(4 字节)
开关锁
方式
(1 字节)
返回状态
(1 字节)
0~10000 0~10000 主机随机数 0x00:关锁
0x01:开锁
说明 说明 取值范围

主机 ID 和随机数,配件 MCU 上报 DP 的时候可以不用填,只需要填从机 ID,配件蓝牙模组中如果有存储从机 ID 对应的信息,配件会自动填充主机 ID 和随机数。

配件 MCU 端需要存储:

  • 从机 ID(门锁的 ID)

    门锁 ID 在添加开门方式的时候会下发,具体见 DP 协议规范。

  • 其余 DP,模组不会处理,直接透传。

    连上之后配件会转发送 MCU 报上来的开关锁 DP 给门锁,启动 30s 定时器,若门锁超 30s 未回复开锁结果,则断开蓝牙连接。若收到开锁结果,也断开蓝牙连接。

iBeacon 配置接口(CMD-0xA8)

  • 适用固件:门锁类通用固件。
  • 从设备角度看,支持防丢功能或靠近解锁功能,就是在一段时间内进行特定的广播,广播内容符合 iBeacon 数据结构。手机搜索到 iBeacon 后进行一些操作。
  • 防丢功能和靠近解锁功能的业务依赖相关功能的 DP 以及 App。
  • 防丢 iBeacon 的配置模组不记忆,重启不会继续之前的动作。靠近解锁 iBeacon 的配置模组会记忆到 Flash,重启后会继续之前的动作。
  • 解绑或重置设备后,会重置 iBeacon 配置。

MCU 发送

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA8
4
5
2 数据长度 0x00
0x06
6~11 6 CFG 见下表
12 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

CFG 格式:

1 字节 1 字节 2 字节 2 字节
1 2 3~4 4~5
operation config_type ibeacon_interval timeout
  • operation

    • 0x00:关闭防丢 iBeacon
    • 0x01:打开防丢 iBeacon
    • 0x02:关闭靠近解锁 iBeacon
    • 0x03:打开靠近解锁 iBeacon
  • config_type

    • 0x00:使用默认配置,ibeacon_interval 和 timeout 字段填 0x00 即可,模组不做解析。
    • 0x01:使用自定义配置,见 ibeacon_interval 和 timeout 字段。
  • ibeacon_interval:低功耗下的 iBeacon 广播间隔,单位 100ms,实际广播间隔为 ibeacon_interval*100ms,可设置范围 100ms~2s。非低功耗固定 100ms。

    开启 iBeacon 后的广播间隔补充说明:

    • 非低功耗状态下,广播间隔为 100ms。
    • 低功耗状态下,若使用默认配置,广播间隔为 500ms。该广播间隔与 CMD-0xE2 设置的广播间隔互相独立。打开 iBeacon 的时候,低功耗状态以 ibeacon_interval 设置的间隔进行广播。
    • 防丢功能打开,以 ibeacon_interval 间隔广播 iBeacon 内容。
    • 靠近解锁功能打开,以 ibeacon_interval 间隔交替广播 iBeacon 广播和涂鸦标准广播内容。每个广播切换间隔(1S)会进行涂鸦标准广播和 iBeacon 广播的广播内容切换,广播切换间隔不可配置,所以 ibeacon_interval 应小于 1s。
  • timeout:iBeacon 超时关闭时间,单位 5s,即 5*timeout 秒后超时。可设置范围 5s~2min。仅作用于防丢功能。靠近解锁功能没有超时时间,需要通过配置关闭。

示例

  • 防丢 iBeacon:55 AA 00 A8 00 06 01 00 00 00 00 00 AE
  • 靠近解锁 iBeacon:55 AA 00 A8 00 06 03 00 00 00 00 00 B0

模组回复

序号 长度(byte) 字段 说明
0
1
2 帧头 0x55
0xAA
2 1 版本号 0x00
3 1 命令字 CMD 0xA8
4
5
2 数据长度 0x00
0x01
6 1 State 返回的状态值
7 1 CRC8 从帧头开始按字节求和得出的结果对 256 求余

State 返回值说明:

  • 0x00:设置成功
  • 其他:设置失败

协议记录

协议版本 主要变更 修订日期 说明
3.0.3 新增查询天气数据支持 CMD-0xB6 20220801 协议新增
3.0.2 CMD-0x01指令新增安全连接类型配置选项 20220501 协议改动
3.0.1 修订部分描述和排版调整 20220215 排版调整
3.0.0 协议框架调整和协议新增 20211123 详情见 蓝牙特有协议 部分
2.0.2 修订部分描述 20211016 修订部分描述
2.0.1 修订部分错误描述与增加名称解释 20210908 修订部分错误描述与增加名称解释
2.0.0 修改 CMD-0x01,CMD-0x07,CMD-0xE0,新增 CMD-0xB5 20210706 支持大数据存储及 Beaocn DP 功能
1.0.1 修订低功耗部分描述 20210327 ----
1.0.0 初版协议 20200225 首次公开发布

附录:

天气服务参数表

天气数据参数 (KEY) 天气数据参数 (值) 含义 值类型 国内 国外 是否支持实时 是否支持预报
w.temp (1 << 0) 温度 整数 支持 支持
w.thigh (1 << 1) 最高温度 整形
w.tlow (1 << 2) 最低温度 整形
w.humidity (1 << 3) 湿度 整数 支持 支持 支持7天内数据
w.condition (1 << 4) 天气状况描述文本,晴、雨、雪等,非固定以多语言配置为准,
在不同数据中心、不同语种情况下(支持本地化翻译),值的文本内容会有所不同。建议用 conditionNum,返回天气状况编码
字符串 支持 支持 支持 7 天内数据
w.pressure (1 << 5) 气压 整数 不支持 (大陆地址不支持) 支持 支持 7 天内数据
w.realFeel (1 << 6) 温度实感 整数 不支持 支持
w.uvi (1 << 7) 紫外线指数 整数 不支持 支持 支持 7 天内数据
w.sunRise (1 << 8) 日出时间 字符串(格式:2017-04-24 05:24:00) 支持 支持 支持 7 天内数据
w.sunSet (1 << 9) 日落时间 字符串(格式:2017-04-24 18:32:00) 支持 支持 支持 7 天内数据
t.unix (1 << 10) 格林时间 [搭配日出/日落使用]
t.local (1 << 11) 本地时间 [搭配日出/日落使用]
w.windSpeed (1 << 12) 风速 字符串(格式:0.9) 支持 支持 支持 7 天内数据
w.windDir (1 << 13) 风向 字符串 支持 不支持
w.windLevel (1 << 14) 风等级 整数 支持 不支持
w.aqi (1 << 15) 空气质量指数 整数 支持 不支持
w.tips (1 << 16) 天气贴士 字符串
w.rank/ w.quality (1 << 17) 详细 AQI 实况及全国排名 字符串(格式:447/609) 支持 (仅大陆地址支持) 不支持
w.pm10 (1 << 18) PM10 指数 整数 支持 不支持
w.pm25 (1 << 19) PM2.5 指数 整数 支持 不支持
w.o3 (1 << 20) O3 指数 整数 支持 不支持
w.no2 (1 << 21) NO2 指数 整数 支持 不支持
w.co (1 << 22) CO 指数 整数 支持 不支持
w.so2 (1 << 23) 二氧化硫指数 整数 支持 不支持
w.conditionNum (1 << 24) 天气状态,晴、雨、雪等,以数字编码方式表示 字符串 支持 支持 支持 7 天内数据

天气 UTF-8 编码对照表

编号 conditionNum 天气(中文) condition 中文UTF-8编码(16进制) 天气(英文) condition
120 E699B4 no precipitation
101 大雨 E5A4A7 E99BA8 heavy rain
102 雷暴 E99BB7 E69AB4 thunderstorms|possible thunderstorms
103 沙尘暴 E6B299 E5B098 E69AB4 dangerously windy
104 小雪 E5B08F E99BAA light snow|possible light snow
105 E99BAA snow
106 冻雾 E586BB E99BBE frozen fog
107 暴雨 E69AB4 E99BA8 heavy precipitation
108 局部阵雨 E5B180 E983A8 E998B5 E99BA8 partially rainy
109 浮尘 E6B5AE E5B098 float dust
110 雷电 E99BB7 E794B5 thunder flash
111 小阵雨 E5B08F E998B5 E99BA8 light precipitation|possible light precipitation
112 E99BA8 precipitation
113 雨夹雪 E99BA8 E5A4B9 E99BAA possible light sleet|light sleet
114 尘卷风 E5B098 E58DB7 E9A38E dust devil
115 冰粒 E586B0 E7B292 ice particle
116 强沙尘暴 E5BCBA E6B299 E5B098 E69AB4 strong sand storm
117 扬沙 E689AC E6B299 blowing sand
118 小到中雨 E5B08F E588B0 E4B8AD E99BA8 small to medium rain
119 大部晴朗 E5A4A7 E983A8 E699B4 E69C97 mixed precipitation
121 E99BBE foggy
122 阵雨 E998B5 E99BA8 shower
123 强阵雨 E5BCBA E998B5 E99BA8 strong shower
124 大雪 E5A4A7 E99BAA heavy snow
125 特大暴雨 E789B9 E5A4A7 E69AB4 E99BA8 very heavy snow
126 暴雪 E69AB4 E99BAA blizzard
127 冰雹 E586B0 E99BB9 sleet
128 小到中雪 E5B08F E588B0 E4B8AD E99BAA small to medium snow
129 少云 E5B091 E4BA91 partly cloudy
130 小阵雪 E5B08F E998B5 E99BAA possible flurries
131 中雪 E4B8AD E99BAA snow
132 E998B4 overcast
133 冰针 E586B0 E99288 heavy sleet
134 大暴雨 E5A4A7 E69AB4 E99BA8 rainy big
136 雷阵雨伴有冰雹 E99BB7 E998B5 E99BA8 E4BCB4 E69C89 E586B0 E99BB9 shower with hail
137 冻雨 E586BB E99BA8 ice rain
138 阵雪 E998B5 E99BAA flurries
139 小雨 E5B08F E99BA8 possible drizzle|drizzle|possible light rain|light rain
140 E99CBE haze fog
141 中雨 E4B8AD E99BA8 rain
142 多云 E5A49A E4BA91 mostly cloudy
143 雷阵雨 E99BB7 E998B5 E99BA8 shower with thunder
144 中到大雨 E4B8AD E588B0 E5A4A7 E99BA8 medium to big rain
145 大到暴雨 E5A4A7 E588B0 E69AB4 E99BA8 big to heavy rain