Bluetooth Door Lock

Overview

This topic describes how to develop Bluetooth door locks based on the TuyaOS Bluetooth Device Development Kit. By following this guide, you can quickly get started and complete door lock product development.

Related documentation

Base documentation

• What is TuyaOS?
• Environment Setup
• Tuya Wind IDE

Technical documentation

• Bluetooth Software
• Bluetooth Capability Map
• Bluetooth Basics Demo

Chip datasheet

• BK3633 Datasheet
• FR801x Datasheet
• GR551x Datasheet

Data point (DP) protocol reference

• Bluetooth Lock DP Reference
• Accessory DP Reference

Lock (accessory) SDK documentation

• Hardware design: .\hardware\
• Usage instructions:
  • Markdown format: .\software\TuyaOS\apps\tuyaos_ble_lock_xxxxxx_demo\README.md
  • HTML format: .\software\TuyaOS\apps\tuyaos_ble_lock_xxxxxx_demo\doc\index.html

Technical support

• TuyaOS Developer Forum

Select solutions

Bluetooth development framework + proprietary door lock development framework

• Use case: You already have a mature and stable proprietary lock framework and only require Bluetooth connectivity to the Tuya platform.
• Recommendation: Thoroughly review Bluetooth Software and call the relevant APIs. Alternatively, download the lock development kit and refer to its API implementation methods.
• Note: The current version (v3.12.1 and earlier) of the Bluetooth Development Framework does not include components for dynamic and offline lock passwords. If required, please contact Tuya FAE. Future versions will migrate these components from the Lock Development Kit to the standard Bluetooth Development Framework.

Bluetooth development framework + lock development kit

• Use case: You are integrating with Tuya’s framework for the first time or are familiar with Tuya’s legacy lock SDK. You have no need to care about Bluetooth API calls—only adapt peripheral driver integration and customize application logic such as audio/visual feedback.

• Recommendation: Read the kit’s built-in documentation in either README.md or index.html format.

Bluetooth development framework + lock accessory development kit

• Use case: Develop Tuya Bluetooth lock accessories, such as Bluetooth keys and keypads.

• Recommendation: Read the kit’s built-in documentation in either README.md or index.html format.

Tuya Bluetooth module + proprietary door lock development framework

• Use case: You already have a mature and stable proprietary lock framework and chip platform, and want to integrate with Tuya via the Bluetooth module’s UART commands.

• Recommendation: Refer to Bluetooth Serial Communication Protocol.

Get development kit

Get Bluetooth Device Development Kit

Open Visual Studio Code, navigate to the Resource Center of the Tuya Wind IDE plugin, filter the latest Bluetooth Device Development Kit for the desired platform, and click Create to download it to your local device.

Get lock (accessory) development kit

After the Bluetooth Device Development Kit is created, you can download it from the Product Dev Kit tab of the Dev Framework page.

Build and configure

Select the desired development kit in the apps directory, right-click it, and then select Build Project. After the first compilation, the firmware and Keil5 project files are generated in the .log folder. You can then choose Visual Studio Code or Keil5 for development, depending on your preference.

Debug and verify

Authorize

In the app_config.h file, by default, the macro TUYA_SDK_DEBUG_MODE is either undefined or set to 0. In this state, the device must be authorized via the serial port using a host software. When TUYA_SDK_DEBUG_MODE is defined as 1, the device uses the license from the tuya_ble_protocol_callback.h file for authorization. You need to replace the following content based on the actual product and authorization information created on the Tuya Developer Platform:

#define TY_DEVICE_NAME        "LOCK"                           //!< Broadcast device name 
#define TY_DEVICE_PID         "xxxxxxxx"                        //!< Device PID 
#define TY_DEVICE_MAC         "XXXXXXXXXXXX"                    //!< MAC 
#define TY_DEVICE_DID         "XXXXXXXXXXXXXXXX"                //!< UUID 
#define TY_DEVICE_AUTH_KEY    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"  //!< AUTH_KEY

After authorization is completed, the device can be discovered by the Tuya app for pairing. After successful pairing, the app can communicate with the device over Bluetooth, enabling command transmission and status control.

Develop based on the Bluetooth development kit

Tuya provides Bluetooth-related interfaces for you to build a door lock application framework as needed.

Interface category	Description
Protocol callback function	The tuya_ble_protocol_callback function in the tuya_ble_protocol_callback.c file handles callbacks for the Tuya Bluetooth protocol stack events. Examples include: Bluetooth connection/disconnection, receiving commands from the app, time sync, unbinding/resetting, and OTA updates.
Bluetooth request interfaces	tuya_ble_api.h provides interfaces for proactively initiated Bluetooth requests from the device, including: Status reporting Log reporting Cloud time request Device reset and unbinding
Peripheral interfaces	The drivers/tkl_xx.h file defines peripheral interfaces, including operation interfaces for peripherals such as ADC, GPIO, Flash, I2C, and PWM.
System interfaces	The system/tkl_xx.h file provides OS-related interfaces, including functional interfaces for dynamic memory allocation/release, device restart, random number generation, and delay operations.

Develop based on the door lock development kit

Using the door lock development kit provided by Tuya, you do not need to build an application framework from scratch. Tuya has already constructed a complete door lock application framework based on the Bluetooth development kit. The example path is apps/tuyaos_ble_lock_xxxx_demo.

Component category	Path	Description
Application components	app.components	Provides almost all general-purpose functional modules for door lock applications. Implements the parsing, processing, and status reporting logic for door lock DP commands defined on the Tuya Developer Platform.
Peripheral driver components	app.drivers	Contains the peripheral driver interfaces for the door lock, including: Motor control (forward, reverse, brake, stop) Indicator light on/off status control Button input reading and debounce handling NFC card reading, writing, and verification Fingerprint enrollment, recognition, and deletion operations

• custom_app custom logic:

  File name	Description
  custom_app_button_sensor.c	Button actions: Defines various button actions. For example, long press for factory reset, one-key lock/unlock, and electronic double locking.
  custom_app_dps_parse.c	Device status & settings reporting: When a Bluetooth connection is established, the device reports all door lock status and setting information, such as battery percentage, lock state, and volume level. The content to be reported can be selected based on the product’s DPs defined on the Developer Platform.
  custom_app_smartlock_interactive.c	Human-machine interaction prompts: Handles the prompt effects for different device states, such as starting pairing, pairing success, lock/unlock success, and low battery. The state entry points are defined in tbl_lock_interactive.h. You can redefine the required prompt logic here.
  custom_app_lighting_mgr.c	Indicator light management: Implements custom indicator light control, such as flowing lights and special blinking effects. It can be used to call interaction prompt logic.
  custom_app_menu_xxxx.c	Menu configuration: Defines various configuration parameters for the door lock’s local menu.
  custom_app_product_test.c	Production test logic: Implements custom production test logic for the door lock.
  custom_app_sleep_mgr.c	Sleep/Wake-up: Implements the sleep and wake-up logic for the door lock.
  custom_app_smartlock_deadbolt.c	Motor & photo-signal logic: Customizes motor control during deadbolt lock/unlock actions, as well as the processing logic for photo-signals.

FAQs

Low power

• Bluetooth development framework: By default, the system does not automatically enter sleep mode. After tal_cpu_allow_sleep() is invoked, the Bluetooth MCU enters sleep mode and can be woken up by any external interrupt, software timer interrupt, or Bluetooth event. If tal_cpu_force_wakeup() is invoked after waking up, the chip will no longer automatically enter sleep mode. To ensure proper sleep or wakeup behavior, peripherals such as UART and I2C must be disabled or enabled accordingly to avoid malfunctions.

  For testing, refer to the Bluetooth Basics Demo and use the Logic host software to send sleep testing commands. Compare and verify sleep mode power consumption against the corresponding chip datasheet for accuracy.

• Lock development kit: After you enable low power management (configSUPPORT_SLEEP_MODE), the lock development kit automatically handles sleep mode entry and exit. Enable relevant logs during the debugging phase for sleep mode monitoring.