蓝牙门锁产品开发指南

概述

本文详细介绍如何基于 TuyaOS 蓝牙设备开发包进行蓝牙门锁的开发。通过本指南，开发者可以快速上手并完成门锁产品开发。

相关文档资料

基础文档

• TuyaOS 概述
• 开发环境搭建
• Tuya Wind IDE 使用教程

技术文档

• 蓝牙开发框架介绍
• 蓝牙能力地图
• 蓝牙产测授权
• Bluetooth LE Demo 演示

芯片手册

• BK3633 芯片手册
• FR801x 芯片手册
• GR551x 芯片手册

DP 协议参考

• 蓝牙门锁 DP 参考
• 蓝牙门锁配件 DP 参考

门锁（配件）开发包 SDK 自带文档

• 硬件设计：.\hardware\
• 开发包使用说明：
  • Markdown 格式：.\software\TuyaOS\apps\tuyaos_ble_lock_xxxxxx_demo\README.md
  • HTML 格式：.\software\TuyaOS\apps\tuyaos_ble_lock_xxxxxx_demo\doc\index.html

技术支持

• TuyaOS 开发者论坛

方案选择指南

蓝牙开发框架 + 自有门锁开发框架

• 适用场景：开发者已有成熟稳定的自研门锁开发框架，仅需蓝牙接入涂鸦平台。
• 建议：详读 蓝牙开发框架介绍 文档，调用相关 API。也可以下载门锁开发包，参考门锁开发包对 API 的调用方法。
• 注：当前版本（v3.12.1 及以下版本）蓝牙开发框架暂不包含门锁动态/离线密码相关组件，如有需要请联系涂鸦 FAE。后续版本迭代会将相关组件从门锁开发包中移入基础蓝牙开发框架。

蓝牙开发框架 + 门锁开发包

• 适用场景：开发者首次对接涂鸦开发框架或熟悉涂鸦老门锁 SDK，无需关注蓝牙 API 调用，仅调整门锁外设驱动接入和自定义声光交互等应用逻辑。

• 建议：仔细阅读开发包自带的 README.md 格式或 index.html 格式文档。

蓝牙开发框架 + 门锁配件开发包

• 适用场景：开发者需要开发如蓝牙钥匙、密码盘、KEYPAD 等涂鸦蓝牙门锁配件产品。

• 建议：仔细阅读开发包自带的 README.md 格式或 index.html 格式文档。

涂鸦蓝牙模组+自有门锁开发框架

• 使用场景：开发者已有成熟稳定的自研门锁开发框架和芯片平台，通过蓝牙模组串口指令接入涂鸦平台。

• 建议：参照 蓝牙通用串口协议。

开发资料获取步骤

获取蓝牙设备开发包

进入 VS Code 的 Tuya Wind IDE 插件资源中心，筛选目标平台 最新版本 的蓝牙设备开发包，单击 创建 将其下载到本地。

获取门锁（配件）开发包

蓝牙设备开发包创建完成后，可以在 开发框架 页面的 产品开发包 标签页进行下载。

编译和配置

在 apps 目录下选择目标开发包，右键选择 Build Project 进行编译。第一次编译后，在 .log 文件夹内生成固件和 Keil5 工程文件，后续可根据个人偏好选择 VS Code 或 Keil5 进行开发。

调试和验证

授权

app_config.h 文件中默认情况下宏定义 TUYA_SDK_DEBUG_MODE 未定义或被设置为 0。此时设备需要通过上位机串口完成授权；当 TUYA_SDK_DEBUG_MODE 被定义为 1 时，设备使用 tuya_ble_protocol_callback.h 文件中的授权码进行授权。开发者需根据实际在涂鸦开发者平台上创建的产品和授权信息，替换以下内容：

#define TY_DEVICE_NAME        "LOCK"                           //!< 广播设备名
#define TY_DEVICE_PID         "xxxxxxxx"                        //!< 设备 PID
#define TY_DEVICE_MAC         "XXXXXXXXXXXX"                    //!< 授权码 MAC
#define TY_DEVICE_DID         "XXXXXXXXXXXXXXXX"                //!< 授权码 UUID
#define TY_DEVICE_AUTH_KEY    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"  //!< 授权码 AUTH_KEY

授权完成后，设备即可被 涂鸦 App 检测到并进行配网。配网成功后，App 可通过蓝牙与设备通信，实现指令收发和状态控制。

开发 - 基于蓝牙开发包

涂鸦提供了蓝牙相关接口，由开发者依据需求构建门锁应用框架：

接口类别	说明
协议回调函数	tuya_ble_protocol_callback.c 文件中的 tuya_ble_protocol_callback 函数，负责处理涂鸦蓝牙协议栈事件的回调。例如：蓝牙连接断开、接收 App 指令、时间同步、解绑重置以及 OTA 更新等事
蓝牙请求接口	tuya_ble_api.h 提供了设备主动发起的蓝牙请求接口，包括： 状态上报 日志上报 云端时间请求 设备重置与解绑
外设接口	drivers/tkl_xx.h 文件定义了外设接口，包含 ADC、GPIO、Flash、I2C、PWM 等外设的操作接口
系统接口	system/tkl_xx.h 文件提供了操作系统相关接口，包含动态内存申请/释放、设备重启、随机数生成、延时操作等功能接口

开发 - 基于门锁开发包

基于涂鸦提供的门锁开发包，开发者无需从零搭建应用框架。涂鸦已经基于蓝牙开发包构建好一整套门锁应用框架，示例路径为 apps/tuyaos_ble_lock_xxxx_demo。

组件类别	路径	说明
应用功能组件	app.components	提供门锁应用的几乎所有通用功能模块 实现涂鸦开发者平台定义的门锁 DP 指令的解析、处理及状态上报逻辑
外设驱动组件	app.drivers	包含门锁的外设驱动接口，具体包括： 电机控制（正转、反转、刹车、停止） 指示灯指定亮灭状态 按键输入读取及消抖处理 NFC 卡片的读写、验证 指纹录入、识别、删除等操作

• custom_app 自定义逻辑：

  文件名称	说明
  custom_app_button_sensor.c	按键操作：定义各类按键动作（如长按恢复出厂设置、一键开关锁、电子反锁开关等）
  custom_app_dps_parse.c	设备状态及设置信息上报：蓝牙连接时，设备会统一上报所有门锁状态和设置信息（如电量百分比、锁状态、音量等级等），可根据开发者平台产品定义的 DP 选择需要上报的内容
  custom_app_smartlock_interactive.c	人机交互提示：设备在不同状态下（例如：开始配网、配网成功、开关锁成功、电量低等）的提示效果由此文件处理，对应的状态入口在 tbl_lock_interactive.h 中定义。开发者可自行重定义所需的提示逻辑
  custom_app_lighting_mgr.c	指示灯管理：实现自定义指示灯控制（如流水灯、特殊闪烁效果等），可用于调用交互提示逻辑
  custom_app_menu_xxxx.c	菜单配置：定义门锁本地菜单的各类配置参数
  custom_app_product_test.c	产测逻辑：实现门锁的自定义生产测试逻辑
  custom_app_sleep_mgr.c	休眠唤醒：实现门锁的休眠与唤醒逻辑
  custom_app_smartlock_deadbolt.c	电机与光电信号逻辑：定制 Deadbolt 门锁开关动作中的电机控制，以及光电信号的处理逻辑

常见问题

关于低功耗

• 蓝牙开发框架：默认不会自动进入休眠，调用 tal_cpu_allow_sleep() 后蓝牙 MCU 进入休眠，任意外部中断、软件定时器中断、蓝牙事件都会唤醒 MCU。唤醒后如果调用 tal_cpu_force_wakeup()，芯片不会再自动进入休眠。实际进/出休眠还需要关闭/打开 UART、I2C 等外设，避免出现异常。也可以参照 Bluetooth LE Demo 演示 使用 Logic 上位机发送休眠测试等指令测试。芯片休眠功耗参照对应芯片手册对比验证。

• 门锁开发包：使能 enable low power manage（configSUPPORT_SLEEP_MODE） 后门锁开发包会自动管理进出休眠。调试阶段可以打开相关 Log。