Bluetooth Low Energy Lock SDK (Public Edition)

This topic describes the architecture, interface, and routine of the public version SDK of Bluetooth door locks. No matter what you need, as long as you develop a lock application, and want to connect to the Tuya Smart app and Tuya Cloud Platform through low power Bluetooth, you can develop the application based on the Tuya public version SDK of Bluetooth locks.

Beginners can go to the following section — Simulate hardware with serial port commands. According to the example procedure, simulate hardware with serial port commands, and try Tuya locks quickly. This example is also a good debugging tool during future development.

Software architecture

The following figure shows the architecture of the public version SDK of Bluetooth locks.

Main framework

The main framework includes Tuya Bluetooth network configuration, communication, and lock business implementation. Tuya low power Bluetooth products are based on Bluetooth general network configuration protocol. This protocol mainly implements Bluetooth general network configuration procedures and basic data communication protocols. It is the basic protocol of Tuya low power Bluetooth products. Source codes are in the tuya_ble_sdk folder. If your platform has corresponding Demo routines, you do not need to pay attention to this protocol. Tuya has done all the migrations. If you use a new platform, this protocol must be migrated. For more information, see Tuya Bluetooth Low Energy (LE) SDK User Guide.

Based on the general network configuration protocol, Tuya defines a whole set of data point (DP) protocols of locks, which describe the communication logic between lock application business and mobile phone app. For your reference, Tuya has encapsulated frequently-used DP protocols. Source codes are in the lock_dp_parser and lock_dp_report files of the app layer. For more information, see Tuya_ble_lock_dp_protocol.

Support components

Besides the main framework, there are some important support components. There are two parts:

• The first part is third-party components, which provide general functions such as storage and debugging.

  Third-party components mainly include easyLogger and mbedtls. If your platform has corresponding Demo routines, you do not need to pay attention to these components since Tuya has done all the migrations. If you use a new platform, only easyLogger component must be migrated, and you do not need to modify mbedtls component, which is mainly the encryption interfaces.

• The second part is Tuya components, which provide specific functions such as authorization and production test.

  Tuya components are some general source package routines. When you develop most of Tuya low-power Bluetooth products, you can refer to these routines to implement product logic. Take lock applications for example.

  Tuya components mainly include authorized production test, OTA, local storage management, and whole device production test. Authorized production test is used to burn and verify the parameters required by general network configuration protocol, such as MAC, authkey, and device ID. OTA implements Tuya Bluetooth OTA protocol. If you do not use the Demo platform, the protocol must be migrated. Local storage management implements the local storage logic of lock applications. The whole device production test implements the whole functional test of the product in a wireless way.

app_port

To improve the compatibility of the app layer, including Tuya components, the app layer is isolated from other layers. The isolation layer is called app_port. In the app layer, you can only see the underlying API (which is started with app_port) encapsulated by the isolation layer and the API of the app layer.

app

• app_lock: this folder mainly implements lock business functions of the application layer. It only applies to locks.

  • lock_common: unclassified.
  • lock_dp_parser: DP parsing. The data is transferred from the mobile phone to the device.
  • lock_dp_report: DP reporting. The data is transferred from the device to the mobile phone.
  • lock_hard: your hardware interface and simulated hardware through serial ports. It is used by beginners or debugging.
  • lock_test: whole device production test.

• app_common: this folder mainly implements general functions of the application layer. It applies to all Bluetooth products.

  • app_common: unclassified.
  • app_flash: local storage management.
  • app_ota: OTA function.
  • app_test: authorized production test.
  • app_port: see the app_port section.

• app_port: underlying interface encapsulation. It provides uniform names and management for all interfaces that might be used by the app layer. In this way, the application layer becomes an independent module and can be migrated conveniently.

tuya_ble_sdk

Tuya low power Bluetooth general network configuration SDK. It implements the network configuration procedure and basic communication protocol between a low power Bluetooth device and a mobile phone app. For more information, see Tuya Bluetooth LE SDK User Guide.

Chip original SDK

• nrfs (nRF52832)

  Encapsulate interfaces of Nordic original SDK:

  • nrfs_common: unclassified.
  • nrfs_scan_adv: scan and broadcast.
  • nrfs_ble: Bluetooth parameter.
  • nrfs_svc: service and characteristic value.
  • nrfs_uart: serial port.
  • nrfs_timer: timer.
  • nrfs_flash: flash.
  • nrfs_gpio: general-purpose input/output.
  • nrfs_test: for R&D test.

• bk (bk3431q)

  Encapsulate interfaces of BK original SDK:

  • bk_common: unclassified.
  • bk_scan_adv: scan and broadcast.
  • bk_ble: Bluetooth parameter.
  • bk_svc: service and characteristic value.
  • bk_uart: serial port.
  • bk_timer: timer.
  • bk_flash: flash.
  • bk_gpio: general-purpose input/output.
  • bk_test: for R&D test.

Component

It refers to a third-party component here.

• cpt_math: it implements some general mathematical algorithms, including checksum, CRC16, CRC32, and byte reversion.
• cpt_hash, cpt_mbedtls and cpt_fpe: it implements some general encryption algorithms, including aes128_ecb, aes128_cbc, MD5 calculation, and FPE algorithm.
• cpt_easylogger: it implements a log printing mechanism of the whole SDK. The following two APIs are used.
  • log_d().
  • elog_hexdump(name, width, buf, size).

If you use the Demo platform, the component has been migrated, and you can use it directly. If you use a new platform, the component must be migrated to implement functions of at least the above two APIs.

Source code and tutorial: EasyLogger.

Key point

Local storage management routine

tuya_ble_sdk uses 16 KB Flash space to store the authorization and tuya_ble_sdk system information. The space is allocated separately. You do not need to configure it, and you cannot occupy it. The start address is TUYA_NV_START_ADDR.

The app layer uses 16 KB Flash space to store the offline record data and other application data (key-value storage structure based on EasyFlash). You can use the free space and adjust the used Flash space properly. The start address is EF_START_ADDR, and the used space size is ENV_AREA_SIZE. The relevant API is 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 space only refers to the storage area, excluding the code area.

Local storage mainly refers to hardware storage, event storage, and setting storage. Storage logic is mainly implemented in the app_flash.c file.

• Hardware storage routine

  The app layer has implemented management logic routines of hardware storage, and you can use it directly when you start to develop. Actual products implement corresponding logic according to business requirements. The routine can store a maximum of 256 hardware, and one unlocking method is one hardware. At present, it can store five unlocking methods whose maximum storage quantity can be adjusted according to the specific situations. By default, the storage quantity of each unlocking method is 30, as shown in the following app_flash.h file.

  

• Event storage routine

  The app layer has implemented management logic routines of event storage, and you can use it directly when you start to develop. Actual products implement corresponding logic according to business requirements. The routine can store EVTID_MAX events. You can adjust the maximum storage quantity of events according to the specific situations. In case of exceeding the allocated Flash space, the space must be allocated again. By default, a maximum of 64 events can be stored, as shown in the following figure.

  

• Setting storage routine

  The app layer has implemented management logic routines of setting storage, and you can use it directly when you start to develop. Actual products implement corresponding logic according to business requirements. The routine can store lock-related settings. For more information, see the struct lock_settings_t. To modify default settings of locks, find the lock_settings_default API, and modify the parameters.

DP parsing routine

DP parsing routines are mainly located in the lock_dp_parser file and lock_dp_report file. The routines are implemented according to Tuya_ble_lock_dp_protocol and can be regarded as the C language description of the protocol. You can use it directly when you start to develop. Actual products implement corresponding logic according to business requirements.

• The lock_dp_parser.c file is used to parse lock DP data received by the Bluetooth device. If the parsed data is related to the hardware, the data is sent to the lock_hard.c file, which is the interface between DP data and local logic.

• The lock_dp_report.c file is used to report DP data to the Bluetooth device. If data in the local logic needs to be reported, you can call the API encapsulated in the file to report the data.

OTA

Tuya provides an OTA file storage platform — IoT Console, and data communication protocol. You must implement the local Flash storage logic of OTA. The demo project has been implemented. OTA is mainly located in the app_ota file, and Demo routines apply to specific platforms. You can use Demo routines directly. If you use a new platform, you can refer to the routine, and implement the OTA process on the new platform according to Tuya communication protocols.

• bk3431q platform

  OTA type: upgrade by a partition, restricted by the platform, and resumable transfer unavailable.

  Flash partition table

• nRF52832 platform

  OTA type: upgrade by a partition, and resumable transfer available.

  Flash partition table

Production test

Production test of Tuya Bluetooth locks mainly consists of two parts:

• Authorization production test: mainly including detection of product information, burning of MAC address, device ID (UUID), and authkey.

  Its main function is authorization, mainly including detection of product information, burning of MAC address, device ID (UUID), authkey, and important parameters in the general network configuration protocol. It is the foundation of product safety.

• Whole device production test: mainly including radiofrequency RSSI test (required) and other functional tests (optional).

  Its main function is to test the numerous peripherals of the products and guarantee the yield rate of the products during production. The advantage is that Tuya provides a complete production test protocol based on Bluetooth wireless communication, production test dongle firmware, and production test host.

For more information, see the protocols.

Demo

This section takes the nRF52832 platform for example and introduces relevant routines in the SDK.

Basic information

• Chip: nRF52832
• SDK: nRF5_SDK_15.3.0_59ac345
• IDE: μVision V5.28.0.0
• Project: ble_app_uart
• Serial port: rx-8 and tx-6 (authorization test)
• Debugging information: RTT_viewer

Demo architecture

Firmware burning

Double click to run \nRF5_SDK_15.3.0_59ac345\examples\ble_peripheral\ble_app_uart\pca10040\s132\arm5_no_packs\hex\load_softdevice_bootloader_app.bat.

The above-mentioned method is used to burn softdevice + bootloader + app. To burn the app only, you can use the Keil download button for embedded research and development.

Apply for a license

Contact the project manager.

A formal project must be debugged with the license that has been obtained from the project manager. After chip information is completely erased, the firmware must be downloaded again, and the license will be valid. The product ID, authkey, and device ID can be modified as shown in the following figure.

OTA procedure

1. Modify the firmware version, as shown in the following figure (app_common.h file).

   

   Note: Before the OTA upgrade of some platforms, you must modify key parameters of some other platforms.

2. Compile the project again, and find the tuya_ble_lock_common_nRF52832_xx.xx.bi file in the \nRF5_SDK_15.3.0_59ac345\examples\ble_peripheral\ble_app_uart\pca10040\s132\arm5_no_packs\ota path.

3. Log in to Tuya IoT Console, find the desired product, enter product page, extend the functions, upgrade the firmware, create new firmware, fill in information about new firmware, and confirm. If you have no permission, contact Tuya product manager.

4. OpenTuya Smart app, connect Bluetooth device, click the icon at the top right corner, check firmware upgrade, view current firmware version, device information, copy virtual ID and send it to the computer, and then fill in the test device in Step 3.

5. Click Check Firmware Upgrade in Step 4, upgrade, start to upgrade, and wait until the upgrade is completed. In case of failure, try again or check the firmware.

Simulate hardware with serial port commands

To facilitate your debugging and fast verification of solution feasibility, you can use simple serial port commands to simulate multiple hardware unlocking methods and other commands.

Serial port command format

Serial port command format

Example (nRf52832)

1. Prepare one Nordic official demo board PCA10040 (recommended), or another demo board that carries nRF52832 chip (the serial port must be the same as that of PCA10040 demo board, RX=8, TX=6). Connect the demo board to the computer through J-link, and then open RTT-viewer debugging window.
2. Open the
   \nRF5_SDK_15.3.0_59ac345\examples\ble_peripheral\ble_app_uart\pca10040\s132\arm5_no_packs\hex path, double click load_softdevice_bootloader_app.bat to download the firmware. If the script fails to run, open the readme file, download and install JLink_Windows_V652e.exe and nrfconnectsetup260.exe, and try again. Wait until the command is executed, and a log will appear in the debugging window.
3. Open the sscom5.13.1.exe serial port software in the \tuya_ble_lock_sdk\tools\uart_simulate_hard\SSCOM path.
4. Click Multistring button, and you will find some of the above-mentioned serial port commands have been entered in the text box on the right side of the software.
5. Adjust the serial port Baud to 9600 to start the simulation.
6. Open Tuya Smart app, click + at the top right corner, click Auto Scan, start scanning, find Tuya public version Bluetooth lock, click next, add the device (optional), and wait until the binding is completed.
7. Enter the page of Tuya public version Bluetooth lock, touch and hold to unlock, and Bluetooth unlock log will be seen. Click Unlock Record – Fingerprint on the serial port debugging assistant, and you will see “Fingerprint unlock” on the Tuya Smart app. You can search for other functions.

Example (bk3431q)

1. Prepare one BK official demo board, and read Tuya bk3431q Development Guide.

2. After the firmware is burned successfully in any way, P16 and P17 pin headers on the demo board must be welded, and connected to RX and TX pins of USB – serial port tool. Launch the serial port debugging assistant (921600), and reset the demo board. The log will be seen.

3. Open the sscom5.13.1.exe serial port software in the \tuya_ble_lock_sdk\tools\uart_simulate_hard\SSCOM path. The software can also be used in Step 2.

4. Click Multistring button, and you will find some of the above-mentioned serial port commands have been entered in the text box on the right side of the software.

5. Adjust the serial port Baud to 921600 to start the simulation.

6. Open Tuya Smart app, click + at the top right corner, click Auto Scan, start scanning, find Tuya public version Bluetooth lock, click next, add the device (optional), and wait until the binding is completed.

7. Enter the page of Tuya public version Bluetooth lock, touch and hold to unlock, and Bluetooth unlock log will be seen. Click Unlock Record – Fingerprint on the serial port debugging assistant, and you will see “Fingerprint unlock” on the Tuya Smart app. You can search for other functions.