iotc BLE 配网/交互流程说明

适用于 iotc BLE-only 方案。本文从协议与框架角度描述设备端通用流程：
从启动广播，到手机完成加密会话并读写设备属性。具体文件与函数名随平台实现不同，
本文不绑定某一工程。

---

目录

1. 总览
2. 启动与广播
3. 连接与链路层
4. 服务表与路由
5. 会话建立（SPEKE）
6. 业务属性读写
7. 响应/上报与送达确认
8. deviceInfo 的触发方式
9. 日志速查
10. 交互时序

---

一、总览

设备开机
  └─ 设备初始化 → BLE 使能 → 注册业务回调 → 启动主循环
      └─ BLE 服务启动 → 开始广播
          └─ 手机连接 → 停止广播 → MTU 交换
              └─ 会话建立：createSession → SPEKE（协商会话密钥） → authSetup
                  └─ 手机通过 customSecData 加密通道读写设备属性
                      └─ 设备响应/上报 → indication → 手机回执确认

1.1 角色

角色	说明
手机	BLE Central / SPEKE Client，主动连接并发起所有业务
设备	BLE Peripheral / SPEKE Server，被动应答

1.2 GATT 数据通道

设备侧只使用一个 GATT 数据服务承载配网与业务数据：

项	UUID	属性	用途
Service	15F1E600A27743FCA484DD39EF8A9100	-	数据通道
WRITE 特征	15F1E602A27743FCA484DD39EF8A9100	WRITE	手机 → 设备请求
READ 特征	15F1E601A27743FCA484DD39EF8A9100	READ + INDICATE	设备 → 手机响应/上报

设备所有下行由 WRITE 特征接收，所有上行通过 READ 特征的 indication 发送。

1.3 加密类型

链路层帧头携带 encryptType，不同服务允许的加密类型不同：

值	枚举	含义
0	ENC_TYPE_UNENCRYPTED	明文
1	ENC_TYPE_SPEKE	SPEKE 协商期
2	ENC_TYPE_STS	STS
3	ENC_TYPE_SESSKEY	会话密钥（业务阶段）

---

二、启动与广播

2.1 初始化顺序

设备侧典型启动顺序：

1. 设备信息初始化：载入产品 ID、SN、型号、厂商、软硬件版本等信息，
   并注册业务服务列表。
2. BLE 使能：注册 BLE 配置与 BLE 核心初始化单元。
   • 若尚未注册“OS BLE 使能回调”，使能流程会提示回调为空并返回可忽略的错误码，
     正式集成时应在使能前完成注册。
3. 注册业务回调：属性读写、pincode、接入密钥、随机数源、事件监听、
   广播超时等。
4. 启动主循环：注册公共/核心初始化单元，创建 iotc 主循环任务后返回。

2.2 服务启动与广播

• 设备服务启动事件触发后，BLE 服务被拉起并配置广播参数。
• 广播类型通常为自定义广播，由注册的广播数据回调填充内容。
• 广播启动成功后，手机即可扫描到设备。

2.3 广播内容

广播数据分两部分：

位置	内容
Advertising Data	Flags（AD type 0x01）；启用靠近发现能力时，追加私有扩展字段
Scan Response	Complete Local Name（AD type 0x09）

设备名一般由产品信息拼装（厂商、设备类型、协议版本、产品 ID、SN 等），
并附带一个字节的配网能力位；未绑定/已绑定时名称前缀可能不同。
具体格式由 SDK 的广播数据模块决定，集成方通常无需改动。

---

三、连接与链路层

3.1 连接

连接建立后设备停止广播，并与手机进行 MTU 交换。MTU 大小由协议栈与手机共同决定，
业务层按协商结果分包。

手机连接后可能先发送一个很短的探测帧（长度不足以构成合法链路层包），
设备会打印参数非法并丢弃，属于正常现象。

3.2 分包与组包

链路层使用固定长度包头（PKG_HEAD_LEN = 7），字段包括：

• 分片标识（token）
• 分片总数 / 分片序号
• 加密类型
• 其他控制字段

处理流程：

收到 WRITE 特征数据
  ├─ 解析 7 字节包头
  ├─ 按 token 插入分片缓存
  ├─ 记录本帧加密类型
  ├─ 判断是否收齐所有分片
  ├─ 组包并按 encryptType 解密
  └─ 交给命令解析/服务分派

单个分片不完整或长度不足时直接丢弃，不返回业务响应。

3.3 命令帧格式

Svc 帧位于 7 字节链路层包头之后，格式如下：

字段	长度	说明
type	1B	高 4 位 dataFormat（1=JSON，0=TLV 暂不支持）；低 4 位 opType（0=PUT、1=GET、2=RPT）
svcLen	1B	service 字符串长度
service	svcLen	服务名
payloadLen	2B	小端序
payload	payloadLen	JSON 数据

线上完整帧 = 7B 包头 + Svc 帧。响应的帧头由请求帧复制或重新构造，
回填包头后发送。

3.4 下行处理链路

WRITE 特征回调
  → 异步/同步调度到 iotc 执行器（带超时）
      → 链路层分包、组包、解密
      → 解析 Svc 帧头
      → 查服务表
      → 校验加密类型
      → 按 opType 分派 putFunc / getFunc
      → 编码响应
      → 通过 indication 回给手机

注意：执行器等待时间需要覆盖最慢的业务处理（例如 SPEKE 的大数运算），
否则会出现等待超时日志，但通常不影响手机重试后的最终结果。

---

四、服务表与路由

服务表定义设备支持的服务、允许的加密类型及处理函数：

svcIdx	service	允许的加密类型	处理方向
80	netCfgVer	明文	只读：查询配网版本
81	deviceInfo	SPEKE / 会话密钥	只读：查询设备信息
83	authSetup	SPEKE	只读：鉴权参数
85	clearDevRegInfo	SPEKE / 会话密钥	写入：清除注册信息
67	speke	明文	写入：SPEKE 协商报文
68	netCfg	SPEKE	写入：配网信息
84	createSession	明文	只读：创建会话
79	customSecData	SPEKE / 会话密钥	写入：业务属性通道

说明：

• 部分服务受编译开关控制（配网、会话、SPEKE 等），裁剪后可能不在服务表中。
• 收到帧时会校验 encryptType 是否在该服务允许的集合内，不匹配直接拒绝。
• 分派日志一般形如：recv bt cmd optype:x, svc:name, len:x。

---

五、会话建立（SPEKE）

5.1 为什么需要

deviceInfo、customSecData、netCfg 等服务要求 SPEKE 或会话密钥 加密帧，
因此手机必须先完成密钥协商。

5.2 pincode

设备通过注册的回调提供 pincode，长度必须与框架定义一致（IOTC_PINCODE_LEN），
并与 App 侧逐字节相同。pincode 作为 HKDF material 参与密钥派生，
不一致会导致共享密钥不同、HMAC 校验失败。

5.3 流程

手机 → 设备：CLIENT_REQ（携带临时公钥）
设备：读取 pincode → 计算 → 回复 SERVER_RSP（可能拆成多包 indicate）
手机 → 设备：CLIENT_CFM（HMAC 确认）
设备：校验通过，派生会话密钥 → 回复 SERVER_CFM

要点：

• 协商期报文均使用 ENC_TYPE_SPEKE 或明文发送。
• 协商成功后设备保存会话密钥；后续发送自动使用 ENC_TYPE_SESSKEY。
• 设备端大数运算耗时较长（百毫秒到秒级），期间可能出现执行器等待超时，
  手机通常会重传，需保证重传不会破坏协商上下文。

5.4 超时与重传

常见现象：

• 等待执行器超时：请求处理超过等待阈值。
• 手机重传同一确认报文：若协商上下文已释放，会返回“协商上下文未初始化”类错误。

一般不影响最终协商结果，但应关注是否反复出现；错误码解释见对应错误码文档。

---

六、业务属性读写

会话建立后，手机通过 customSecData 服务读写业务属性。

6.1 GET / PUT 判定

服务端根据请求中是否包含 data 字段区分：

请求
  ├─ 无 "data" 字段 → GET
  │    ├─ sid 表示“全部服务” → 触发全量上报
  │    └─ 指定 sid          → 查询对应业务属性 → 构造响应 → 加密上报
  └─ 有 "data" 字段 → PUT
       ├─ 下发到业务层执行写操作
       └─ 写入成功后，异步查询最新状态并上报

6.2 业务层职责

业务层需要提供：

• 属性写回调：接收 {svcId, data, len}，执行实际控制（如开关、参数设置）。
• 属性读回调：返回当前状态 JSON。
• 全量上报回调：汇总所有可读属性。
• 数据释放回调：释放框架分配/业务返回的 JSON 字符串。

服务 ID、数据结构由产品定义决定，框架只负责路由与加解密。

6.3 典型日志

recv bt cmd optype:0, svc:customSecData, len:xx
send bt cmd optype:2, svc:customSecData, len:xx
indicate conf ... status:0

---

七、响应/上报与送达确认

设备所有响应/上报都通过 indicate（READ 特征）发出。日志分两级：

日志	含义
send indicate msg ret=0	本地已把发送请求交给协议栈，不代表对端已收到
indicate conf ... status=0	对端已回执确认，表示真正送达

排查“手机没收到数据”时，应以第二级日志为准。

---

八、deviceInfo 的触发方式

设备信息不会被主动推送，只能由手机触发，通常有两条路径：

8.1 标准 deviceInfo 服务（GET）

手机对 deviceInfo 服务发 opType=GET（需加密），设备返回：

{
  "prodId": "...",
  "sn": "...",
  "vendor": {
    "deviceInfo": {
      "sn": "...", "model": "...", "devType": "...", "manu": "...",
      "prodId": "...", "bleMac": "...", "fwv": "...", "hwv": "...",
      "swv": "...", "protType": "...", "subProdId": "...",
      "uniqueId": "...", "customData": "..."
    }
  }
}

8.2 customSecData 通道查询

手机也可在 customSecData 请求中指定设备信息对应的 sid，
设备走业务层读取接口，返回 {sid:"deviceInfo", data:{...}}。

两条路径的数据源应保持一致，否则会出现 App 与云端信息不一致。

---

九、日志速查

阶段	典型日志
BLE 使能	iotc oh ble enable
广播类型	set adv type to 5（5 = 自定义广播）
广播启动	start adv success
连接	connect success
停止广播	stop adv success
MTU	set mtu success
下行分包	recv bt data pkg(i/n), encType:x
服务分派	recv bt cmd optype:x, svc:name, len:x
SPEKE 结果	speke errcode:%d（0 表示成功）
本地发送	send indicate msg ret=0
送达确认	indicate conf ... status=0
链路层丢弃	ll process bt data param invalid, len:x

---

十、交互时序

Phone                                 Device
  |--- GATT Connect ------------------>|  connect success / stop adv
  |--- MTU Exchange ------------------>|  set mtu success
  |--- 短探测帧 ----------------------->|  参数非法，忽略
  |--- speke CLIENT_REQ --------------->|  读取 pincode → SERVER_RSP（多包）
  |<-- indicate xN --------------------|  indicate conf status:0
  |--- speke CLIENT_CFM --------------->|  校验通过，派生会话密钥 → SERVER_CFM
  |<-- indicate xN --------------------|  indicate conf status:0
  |=== 会话密钥建立，后续帧使用会话密钥 ===
  |--- customSecData GET sid=xxx ------>|  业务层读属性 → 加密上报
  |<-- indicate -----------------------|  indicate conf status:0
  |--- customSecData PUT {data:...} --->|  业务层写属性 → 异步查询并上报
  |<-- indicate -----------------------|  indicate conf status:0

---

十一、集成检查项

1. pincode / 接入密钥：长度、内容必须与 App、云端一致。
2. 广播内容：产品信息、绑定状态、配网能力位正确。
3. 服务表：业务所需的 service 均已注册，加密类型配置正确。
4. MTU 与分包：大报文（deviceInfo、SPEKE）在多包场景下可正确重组。
5. 执行器超时：最慢业务路径（SPEKE）不会因超时导致会话失败。
6. indicate 确认：以 indicate conf status:0 作为送达依据。
7. 重传幂等：重复请求不会产生重复副作用。
8. 断连恢复：连接断开后能重新广播并被再次连接。