# BLE Lock
## User Guide of BLE Lock SDK (Public Edition)
## 1 Overview
The Tuya common Bluetooth door lock is a common version of Tuya Bluetooth door locks. The Tuya common Bluetooth door lock SDK allows you to connect your lock business app to the TuyaSmart app and Tuya Smart platform through Bluetooth Low Energy (BLE).
Tuya provides this document to help you resolve all issues during embedded software development. If you encounter a problem, read this document first.
To get quickly started, see section 5 that describes serial interface commands for hardware simulation and a quick experience of Tuya lock products. You may also use the example for subsequent debugging.
## 2 Software Architecture
Tuya BLE products use the common, basic Bluetooth network pairing protocol, which implements the common Bluetooth product network pairing process and basic data communications. For details about the protocol, see *Tuya Common BLE SDK Protocol*. The source code is stored in the **tuya\_ble\_sdk** folder. If you use the demo platform, ignore this protocol because Tuya has migrated the protocol. If you use a new platform, migrate this protocol. For details, see *Tuya Common BLE SDK Development Guide*.
In addition to the common network pairing protocol, Tuya defines a set of data point (DP) protocols for lock products. These protocols describe the communications logic between lock business and a mobile app. To facilitate development, Tuya has encapsulated these DP protocols. For details about the source code, see the app-layer files **lock\_dp\_parser** and **lock\_dp\_report**. For details about the protocol content, see *Tuya BLE Lock DP Specifications*.
The preceding Tuya Bluetooth product network pairing, communications, and lock service implementation are the main framework. In addition to the main framework, there are some important support components: third-party components and Tuya components. Third-party components implement common features such as storage and debugging, whereas Tuya components implement private features such as authorization and product test.
Third-party components include easyFlash, easyLogger, and mbedtls. If you use the demo platform, ignore these components because Tuya has migrated them. If you use a new platform, simply migrate the easyFlash and easyLogger components and do not alter the mbedtls component. The mbedtls component mainly contains encryption APIs.
Tuya components are common source code packages and apply to most Tuya's low-power single-node BLE products. This document describes their application in door lock apps and provides reference for applications in other apps. Tuya components include the components of authorization product test, Over-the-Air (OTA) upgrades, local storage management, and complete device tests. The authorization product test component is used for burning and verification of parameters such as the MAC address, authkey, and device ID that the common network pairing protocol requires. For details, see *Tuya Common BLE Authorization Product Test Protocol*. The OTA upgrade component implements the Tuya-defined Bluetooth OTA protocol. If you use a non-demo platform, migrate this component. For details, see *Tuya Common BLE SDK Protocol*. The local storage management component implements the local storage logic of lock apps and also applies to other apps. The complete device test component tests overall product functions. For details, see *Tuya Common BLE Complete Device Test Protocol*.
In addition to the main framework and support components, an isolation layer called "app\_port" is deployed between the app layer and other layers to improve compatibility of the app layer (involving Tuya components). At the app layer, you can only view bottom-layer APIs (their names start with "app\_port") that have been encapsulated at the isolation layer and app layer APIs.
### 2.1 App
**2.1.1 app\_lock**
* This folder is used for lock business functions at the app layer and applies only to lock products.
* lock\_common: not classified.
* lock\_dp\_parser: DP parsing. Data flows from a mobile phone to a device. For details, see *Tuya BLE Lock DP Specifications*.
* lock\_dp\_report: DP reporting. Data flows from a device to a mobile phone. For details, see *Tuya BLE Lock DP Specifications*.
* lock\_hard: customer hardware APIs and serial interface commands for hardware simulation (used for a quick start or debugging).
* lock\_test: complete device test. For details, see *Tuya Common BLE Complete Device Test Protocol*.
**2.1.2 app\_common**
* This folder implements common functions at the app layer and applies to various Bluetooth products.
* app\_common: not classified.
* app\_flash: local storage management.
* app\_ota: OTA upgrade functions. For details, see *Tuya Common BLE SDK Protocol*.
* app\_test: product test authorization. For details, see *Tuya Common BLE Authorization Product Test Protocol*.
* app\_port: For details, see section 2.2 "app\_port."
### 2.2 app\_port
* **app\_port** is used for bottom-layer API encapsulation and provides unified names and management of all APIs that the app layer may use, ensuring an independent app layer and facilitating migration.
### 2.3 tuya\_ble\_sdk
* **tuya\_ble\_sdk** is a common network pairing SDK for Tuya BLE products. It implements network pairing and basic communications between BLE devices and a mobile app.
* Implementation protocol: For details, see *Tuya Common BLE SDK Protocol*.
* Development guide: For details, see *Tuya Common BLE SDK Development Guide*.
### 2.4 Chip Vendor's SDK
* The demo project uses Nordic's SDK nRF5\_SDK\_15.3.0\_59ac345.
#### 2.4.1 NRFS (Applies Only to the Demo Project)
* NRFS encapsulates APIs of the Nordic SDK.
* nrfs\_common: not classified
* nrfs\_scan\_adv: scanning and advertising
* nrfs\_ble: BLE parameters
* nrfs\_svc: service and feature values
* nrfs\_uart: serial interfaces
* nrfs\_timer: timer
* nrfs\_flash: flash
* nrfs\_gpio: GPIO
* nrfs\_test: used for R\&D and test
### 2.5 Components
* This section describes third-party components.
**2.5.1 cpt\_math**
* Implements common mathematical algorithms, such as checksum, CRC-16, CRC-32, and byte reversal.
* Is a pure C language library. You do not need to migrate or alter this component, regardless of the platform you use.
**2.5.2 cpt\_mbedtls**
* Implements common encryption algorithms, such as AES-128 in ECB mode, AES-128 in CBC mode, and MD5.
* Is used for encrypting data in **tuya\_ble\_sdk**.
* Is a pure C language library. You do not need to migrate or alter this component, regardless of the platform you use.
**2.5.3 cpt\_easyflash**
* Implements the flash-based key value storage mechanism, mainly by using the following four APIs. For details about the APIs, see the code comment.
* easyflash\_init();
* ef\_set\_env\_blob(key, buf, size) ;
* ef\_get\_env\_blob(key, buf, size) ;
* ef\_del\_env(key) ;
* If you use the demo platform, this component has been migrated and you can use it directly. If you use a new platform, migrate this component and enable at least functions of the preceding four APIs.
* For details about the source code and guide, visit .
**2.5.4 cpt\_easylogger**
* Implements the SDK log printing mechanism, mainly by using the following two APIs. For details about the APIs, see the code comment. log\_d(); elog\_hexdump(name, width, buf, size);
* If you use the demo platform, this component has been migrated and you can use it directly. If you use a new platform, migrate this component and enable at least functions of the preceding two APIs.
* For details about the source code and guide, visit .
## 3 Important Parsing
### 3.1 Local Storage Management
**tuya\_ble\_sdk** requires 16 KB flash memory to store system information related to authorization and **tuya\_ble\_sdk**. The flash memory must be separately allocated and cannot be used for other purposes. The memory start address is TUYA\_NV\_START\_ADDR.
By default, the app layer requires 16 KB flash memory to store offline records and other app data (key-value storage structure based on easyFlash). You can use the remaining space and need to adjust the occupied flash memory size based on actual usage. The memory start address is EF\_START\_ADDR, and the occupied memory size is ENV\_AREA\_SIZE. Related APIs are as follows: - uint32\_t app\_port\_kv\_set(const char \*key, const void \*buf, size\_t size); - uint32\_t app\_port\_kv\_get(const char \*key, void \*buf, size\_t size); - uint32\_t app\_port\_kv\_del(const char \*key);
The above mentioned flash memory contains only the user data storage area and does not contain the code storage area.
Local storage includes hardware, event, and settings storage. The storage logic is implemented in the **app\_flash.c** file.
**3.1.1 Hardware Storage**
The app layer has implemented the management logic for hardware storage and can store up to 256 hardware devices. A hardware device support one type of door opening methods, and the app layer can store four door opening method types. You can adjust the maximum number of stored door opening methods of each type based on actual requirements. By default, each type supports 10 door opening methods, as shown in the following figure.
**3.1.2 Event Storage**
The app layer has implemented the management logic for event storage and can store "EVTID\_MAX" events. You can adjust the maximum number of events that can be stored based on actual requirements. If the size of stored event data exceeds the allocated flash memory size, the flash memory needs to be re-allocated. By default, up to 64 events can be stored, as shown in the following figure.
**3.1.3 Settings Storage**
The app layer has implemented the management logic for settings storage to store setting items related to the door lock. For details, see the "lock\_settings\_t" structure.
To modify a default door lock setting, modify the related parameter in "lock\_settings\_default" of the API.
### 3.2 Bluetooth Data Channel
### 3.3 DP Parsing
The **lock\_dp\_parser** and **lock\_dp\_report** files are used for DP parsing based on *Tuya BLE Lock DP Specifications*. These files describe this protocol specification document in C language.
The **lock\_dp\_parser.c** file is used for parsing lock DP data received through Bluetooth. If the parsed data is related to hardware, the data will be sent to the **lock\_hard.c** file, which contains the API for DP data and local logic and deserves your most attention.
The **lock\_dp\_report.c** file is used for reporting DP data through Bluetooth. To report required data in the local logic, invoke the encapsulated API in this file.
### 3.4 OTA Upgrade
The OTA upgrade component is stored in the **app\_ota** file. The demo implementation process applies to the demo platform. It is only for your reference if you use a new platform. To perform an OTA upgrade of the new platform, use the communications protocol that Tuya provides. To put it simply, Tuya provides the Tuya Smart platform to store OTA upgrade files and data communications protocols. You need to implement the local flash storage logic for the OTA upgrade component. The logic has been implemented in the demo project.
### 3.5 Product Test
Product tests of a Tuya Bluetooth lock product include the following:
1. Authorization test: inspects product information and burns the MAC address, device ID (or UUID), and authkey.
2. Complete device test: includes the mandatory RF received signal strength indicator (RSSI) test and optional tests of other functions.
The purpose of an authorization product test is authorization. It involves inspection of product information and burning of important parameters used in the common network pairing protocol, including the MAC address, device ID (or UUID), and authkey. It is the base for product security. The complete device test tests product peripherals to ensure a low defect rate during production. Tuya has provided a complete Bluetooth-based product test protocol, product test Dongle firmware, and product test microcontroller unit (MCU) for complete device tests. For details about the product test, see related protocol documents.
## 4 Demo
### 4.1 Basic Demo Information
* Chip: nRF52832
* SDK: nRF5\_SDK\_15.3.0\_59ac345
* IDE: μVision V5.28.0.0
* Project: ble\_app\_uart
* Serial interface: rx-8 and tx-6 (for authorization test)
* Debugging information: RTT\_viewer
### 4.2 Demo Project Architecture
### 4.3 Firmware Burning
Double-click **load\_softdevice\_bootloader\_app.bat** in \*\*\nRF5\_SDK\_15.3.0\_59ac345\examples\ble\_peripheral\ble\_app\_uart\pca10040\s132\arm5\_no\_packs\hex\*\*.
The preceding method burns the softdevice, bootloader, and app. To burn only the app, use keil download.
### 4.4 License Application
Contact your Tuya business manager and apply for a license based on *Bluetooth Door Lock SDK License Application Process*.\
For official projects, please use the license applied by the project manager for debugging (re-download the firmware after the chip is completely erased to take effect)!\
Product id, authkey, and device id are modified as shown in the following figure:
### 4.5 OTA Upgrade Process
1. Modify the firmware version. For details about the firmware version rules, see *Tuya Common BLE SDK Protocol*. The following figure shows the **app\_common.h** file.Note: On some platforms, some platform-related key parameters also need to be modified before an OTA upgrade.
2. Recompile the project. Locate the **tuya\_ble\_lock\_common\_nRF52832\_xx.xx.bin** file in **\nRF5\_SDK\_15.3.0\_59ac345\examples\ble\_peripheral\ble\_app\_uart\pca10040\s132\arm5\_no\_packs\ota**.
3. Log in to the Tuya Smart platform. On the **Product** page, click the product to be operated. On the displayed product page, click **Extensions** and click **Settings** next to **Firmware Updates Center**. Click **New Firmware Update**, enter the firmware information, and click **OK**. If you do not have the permission to create firmware, contact your Tuya business manager.\
To check the product's firmware version and virtual ID, do as follows: Open the TuyaSmart app and pair it with the Bluetooth device. Tap the edit icon in the upper right corner of the device page. On the displayed page, tap **Check for Firmware Upgrades**. A pop-up box shows the current firmware version. Tap **Confirm**. Tap **Device Information**, copy the virtual ID, and send it to your PC.
4. Tap **Check for Firmware Upgrades** in the app again to update the firmware. If the update fails, retry or verify the firmware.
## 5 Hardware Simulation Using Serial Interface Commands
To debug and verify solution feasibility conveniently and quickly, use simple serial interface commands to simulate various hardware door opening methods and other commands.
### 5.1 Serial Interface Command Format
* Recording failure causes
* For details, see the recording failure causes part in section 3.1.1 of *Tuya BLE Lock DP Specifications*.
* dp\_id1
* For details, see the dp\_id part in section 3.2 of *Tuya BLE Lock DP Specifications*.
* Hardware ID
* The default value is 0x01. The value varies depending on the dp\_id value.
* For details, see the data content and value ranges part in section 3.2 of *Tuya BLE Lock DP Specifications*.
* Alarm reasons
* For details, see the alarm reasons part in section 3.2 of *Tuya BLE Lock DP Specifications*.
* dp\_id2
* For details, see the dp\_id part in section 3.3 of *Tuya BLE Lock DP Specifications*.
* Status display content
* For details, see the data content and value ranges part in section 3.3 of *Tuya BLE Lock DP Specifications*.
### 5.2 Example
1. Prepare a Nordic PCA10040 (recommended) or a development board with the nRF52832 chip and the same serial interfaces as the PCA10040 (RX = 8 and TX = 6). Connect the development board to a PC through J-Link and open the RTT Viewer debugging window.
2. Access **\nRF5\_SDK\_15.3.0\_59ac345\examples\ble\_peripheral\ble\_app\_uart\pca10040\s132\arm5\_no\_packs\hex**, and double-click **load\_softdevice\_bootloader\_app.bat** to download the firmware. If the script execution fails, install **JLink\_Windows\_V652e.exe** and try again. After the command is executed, the debugging window will display a log.
3. Double-click **sscom5.13.1.exe** in **\tuya\_ble\_lock\_sdk\tools\uart\_simulate\_hard\SSCOM**.
4. Click the **Multi-string** button. Some serial interface commands mentioned in section 5.1 are automatically entered in the right text box of the software.
5. Set the serial interface baud rate to 9600 bit/s and use serial interface commands to simulate the hardware, as shown in the following figure.
1. Open the TuyaSmart app. Tap the plus sign (+) in the upper right corner and tap **Auto Scan**. Tap **Start Scanning**, select the Tuya common door lock, and tap **Next**. Tap **Add** (optional). Wait until the binding is completed.
2. Open the Tuya common door lock page and tap **Door Opening with Mobile Phone** to view logs about door opening with the mobile phone. Choose **Door Opening Records** > **Fingerprint** on the serial interface debugging assistant. "fingerprint unlock" is displayed in the TuyaSmart app. Use other functions as needed.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.ifreeq.com/developer/smart-product-solution/lock/ble-lock.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.