SDK 开发参考

本文介绍了蓝牙门锁产品公版 SDK 相关的架构，接口和例程。无论您的需求是什么，只要您开发的是锁类业务应用，想要通过低功耗蓝牙的通信方式接入智能生活 App 和云端，您都可以参考涂鸦蓝牙门锁公版 SDK 做开发。

涂鸦蓝牙门锁公版 SDK 借助上位机模拟，实现了蓝牙门锁公版的全功能演示。跳过开发步骤，您只需要一块开发板、一个上位机，就可以体验蓝牙门锁公版的所有功能。

新手入门请首先跳转至 上位机模拟硬件，根据示例流程操作，通过上位机模拟硬件，快速体验涂鸦锁类产品，该示例在后续开发过程中也是很好的调试工具。

软件架构

以下为蓝牙门锁产品公版 SDK 的架构图。

主框架

主框架包含了涂鸦蓝牙配网、通信和锁类业务的实现。涂鸦低功耗蓝牙产品基于蓝牙通用配网协议，该协议主要实现了蓝牙通用配网流程和基本的数据通信协议，是涂鸦低功耗蓝牙产品的基础协议，源码位于 tuya_ble_sdk 文件夹内。如果您的平台有对应的 Demo 例程，则无需关心该协议，涂鸦已经做好了所有的移植工作。如果您使用新平台，则需要移植该协议，详见链接。

在通用配网协议的基础上，涂鸦定义了一整套锁类产品的 DP （功能点）协议，详细描述了锁类应用业务和手机 App 之间的通信逻辑。为了方便您开发参考，涂鸦已经对常用的 DP 协议进行了简单封装，源码详见 app 层的lock_dp_parser 和 lock_dp_report 文件，协议详情请参考 Tuya_ble_锁类_dp。

支撑组件

在主框架之外，还有一些重要的 支撑组件。分为两部分：

• 第三方组件，负责存储、调试等相关的通用功能。

  第三方组件主要包括 easyLogger 和 mbedtls。如果您的平台有对应的 Demo 例程，则无需关心这些组件，涂鸦已经做好了所有的移植工作。如果您使用新平台，则只需要对 easyLogger 组件做简单的移植即可，mbedtls 组件（主要为加密接口）无需改动。

• 涂鸦的组件，负责授权、产测等相关的专用功能。

  涂鸦的组件是一些通用的源码包例程，在开发涂鸦的大部分低功耗蓝牙单点产品时都可以参考这些例程实现产品逻辑，此处仅以锁类应用为例介绍。

  主要包括授权产测、OTA、本地存储管理和整机产测：授权产测用于烧录和校验通用配网协议所需的 mac、authkey 和 device id 等参数。OTA 实现涂鸦自己的蓝牙 OTA 协议（如果您使用的不是 Demo 中的平台，则需要进行移植）。本地存储管理提供了锁类应用在本地的存储逻辑一种简单方案的演示。整机产测基于无线的方式实现对产品的整体功能测试。

app_port

为了提高 app 层（包括涂鸦组件）的兼容性，将 app 层和其它层之间做了简单的隔离，隔离层叫做 app_port。也就是说，在 app 层只能够见到隔离层封装好的底层 API（app_port 开头）和 app 层自己的 API。

app

• app_lock：该文件夹主要实现应用层的锁类业务功能，仅适用于锁类产品。

  • lock_common：未分类的
  • lock_hard：客户硬件接口和串口模拟硬件（入门或调试用）
  • lock_dp_parser：DP 解析，数据方向：手机→设备
  • lock_dp_report：DP 上报，数据方向：设备→手机
  • lock_timer：App 层定时器
  • lock_dynamic_pwd：动态密码
  • lock_offline_pwd：离线密码
  • lock_test：整机产测

• app_common：该文件夹主要实现应用层的通用功能，适用于各类蓝牙产品。

  • app_common：未分类的
  • app_flash：本地存储管理
  • app_ota：OTA 功能
  • app_active_report：主动上报
  • app_antilost：防丢功能
  • app_test：授权产测

• app_port：底层接口封装，为 app 层可能用到的所有接口提供统一的命名和管理，使应用层成为一个独立的模组，方便移植。

tuya_ble_sdk

涂鸦低功耗蓝牙通用配网 SDK，实现低功耗蓝牙设备和手机 App 之间的配网流程和基础通信协议。详见链接。

芯片原厂 SDK

• bk（bk3431q）

  对 bk 原厂 SDK 的接口封装：

  • bk_common：未分类
  • bk_scan_adv：扫描和广播
  • bk_ble：ble 参数
  • bk_svc：服务和特征值
  • bk_uart：串口
  • bk_timer：定时器
  • bk_flash：flash
  • bk_gpio：gpio
  • bk_test：研发测试用

component

此处指第三方组件。

• cpt_math：实现一些常见的数学算法，例如校验和、crc16、crc32、字节反转等。
• cpt_hash、cpt_mbedtls、cpt_fpe：实现一些常见的加密算法，例如 aes128_ecb、aes128_cbc、md5 计算、fpe 算法等。
• cpt_easylogger：实现整个 SDK 的 log 打印机制，主要用到如下 2 个 API（详情见注释）：
  • log_d();
  • elog_hexdump(name, width, buf, size);

如果使用 Demo 平台，则已经实现了该组件的移植，您可以直接使用。如果使用新平台，则需要移植该组件，至少需实现如上 2 个 API 的功能。

源码和教程地址：https://github.com/armink/EasyLogger

重点解析

本地存储管理例程

tuya_ble_sdk 占用 16k bytes Flash 空间用于存储授权和 tuya_ble_sdk 相关的系统信息，需单独分配，您无需关心，也不可占用，起始地址为 TUYA_NV_START_ADDR。

app 层默认分配了 40k bytes Flash 空间用于存储离线记录数据和其他应用数据（id-value 存储结构，基于 simpleFlash），您可使用剩余空间，只要注意根据使用情况适当调整占用 Flash 空间的大小即可，起始地址为 SF_AREA0_BASE，相关 API 如下：

u32 sf_nv_init(u32 area_id);
u32 sf_nv_write(u32 area_id, u16 id, void *buf, u8 size);
u32 sf_nv_read(u32 area_id, u16 id, void *buf, u8 size);
u32 sf_nv_delete(u32 area_id, u16 id);

以上提到的 Flash 空间仅指存储区域，不包含代码区域。

本地存储主要指硬件存储、事件存储和设置存储，存储逻辑主要在 app_flash.c 文件中实现。

• 硬件存储例程

  app 层已经实现了硬件存储的管理逻辑例程，您在入门开发的时候可直接使用，实际产品中根据业务需要实现自己的存储逻辑，例程支持最大 256 个硬件存储，一个开门方式为一个硬件。

• 事件存储例程

  app 层已经实现了事件存储的管理逻辑例程，您在入门开发的时候可直接使用，实际产品中根据业务需要实现自己的存储逻辑，例程支持 EVTID_MAX 个事件存储，您可根据实际情况调整事件的最大存储数量（若超出已分配 Flash 空间，需重新分配），默认存储最多 64 个事件，如下图所示：

  

• 设置存储例程

  app 层已经实现了设置存储的管理逻辑例程，您在入门开发的时候可直接使用，实际产品中根据业务需要实现相应的逻辑，例程用来存储跟门锁相关的设置项目，详见结构体 lock_settings_t。

  想要修改门锁的默认设置，请找到 API lock_settings_default，修改相应参数即可。

DP 解析例程

DP 解析例程主要位于 lock_dp_parser 和 lock_dp_report 两个文件中，例程完全按照 Tuya_ble_锁类_DP 规范 协议实现，可以认为是该协议文档的 c 语言描述，您在入门开发的时候可直接使用，实际产品中根据业务需要实现相应的逻辑。

• lock_dp_parser.c 文件用于解析蓝牙接收到的锁类 DP 数据，如果解析到的数据跟硬件相关，数据会被传到 lock_hard.c 文件中，该文件是 DP 数据和本地逻辑的接口。

• lock_dp_report.c 文件用于上报 DP 数据给蓝牙，本地逻辑中如果有需要上报的数据，都可以通过调用该文件内封装好的 API 进行数据的上报。

OTA

涂鸦提供 OTA 文件存储平台（iot 平台）和数据通信协议，您需要实现 OTA 在本地的 Flash 存储逻辑（Demo 工程中已帮您实现好）。OTA 主要位于 app_ota 文件中，Demo 例程中是针对相应平台的实现，如果您直接使用 Demo 例程，可直接使用。如果您使用新平台，可以参考该例程，按照涂鸦提供的通信协议实现新平台上的 OTA 过程。

• bk3431q 平台

  OTA 类型：分区升级，受平台限制，不支持断点续传

  Flash 分区表

• nRF52832 平台

  OTA 类型：分区升级，支持断点续传

  Flash 分区表

产测

涂鸦蓝牙锁类产品的产测主要分为两个部分：

• 授权产测：主要包括检测产品信息，烧录 Mac 地址，device id（即 uuid）和 authkey 等。

  授权产测的主要功能是授权，主要包括检测产品信息，烧录 Mac 地址，device id（即 uuid）和 authkey 等通用配网协议中用到的重要参数，是产品安全性的基础

• 整机产测：主要包括射频 RSSI 测试（必选）和其他功能测试（可选）。

  整机产测的主要功能是测试产品的众多外设，保证产品在产线生产过程中的良品率，涂鸦整机产测的优势在于提供了基于蓝牙无线通信方式的完整产测协议、产测 dongle 固件和产测上位机。

关于产测的详细描述请参考相应协议文档。

Demo

本小节以 BK3431Q 平台为例，详细介绍 SDK 中的相关例程。

基本信息

• 芯片：BK3431Q
• SDK：ble_3435_sdk_ext_39_0F0E
• ide：μVision V5.28.0.0
• 授权通道：串口 1
• 调试信息：串口 2

Demo 架构

固件烧录

烧录指南

申请 License

请联系项目经理。

正式项目请使用项目经理申请的 License 进行调试（完全擦除芯片后重新下载固件生效）。
product id、authkey 和 device id 修改的位置如下图所示：

OTA 流程

1. 修改固件版本，如下图所示（app_common.h文件）。

   

2. 重新编译工程，找到路径 \Tuya_ble_lock_sdk_bk3431q_with_fitting\ble_3435_sdk_ext_39_0F0E\projects\ble_app_gatt\output\app\bk3435_ble_app_oad.bin 文件。

3. 登录 涂鸦开发者平台 → 找到需要操作的产品 → 进入产品页面 → 拓展功能 → 固件升级 → 创建新固件 → 填写新固件信息，并确定（若无权限联系涂鸦产品经理）即可。

4. 打开智能生活 App，连接蓝牙设备 → 单击右上角的标志 → 检查固件升级，查看当前固件版本 → 设备信息 → 复制 虚拟 ID 并发送到电脑，填入步骤 3 中的测试设备中。

5. 再次单击步骤 4 中的 检查固件升级 → 更新 → 开始更新 → 等待更新完成即可，若失败请重试或检查固件。

上位机模拟硬件

为方便您调试和快速验证方案的可行性，使用上位机模拟多种硬件开门方式的添加和其他功能。
详情请参考 Tuya_ble_lock_simulator GitHub 仓库。