SDK Development

This topic describes the Bluetooth lock SDK in terms of its architecture, APIs, and demo routine. This SDK allows you to develop door lock applications that use Bluetooth Low Energy (LE) to connect to the Smart Life app and the cloud.

With a development board and a host, you can try the full features of a standard Bluetooth LE lock without writing a single line of code.

Software architecture

The architecture of the Bluetooth lock SDK

Main components

The main components include implementations for Bluetooth pairing, communication, and lock applications. Tuya-enabled Bluetooth LE products are built based on the Bluetooth pairing protocol that implements the generic pairing process and basic data communication. The source code of this fundamental protocol is located in the tuya_ble_sdk folder. If the demo routine for your chip platform is ready to use, protocol porting is not needed. If your platform is not supported, port the protocol to the target platform. For more information, see Bluetooth LE Guide.

On top of the generic pairing protocol, a suite of data point (DP) protocols for locks is defined to describe how the lock applications interact with the mobile app. To simplify the development, typical DP protocols are abstracted by the API. You can find the source code in lock_dp_parser and lock_dp_report. See the Data Point Reference for the protocol details.

Supporting components

The supporting components are divided into two parts:

• Third-party components are used for common features such as storage and debugging.

  They include easyLogger and mbedtls. If the demo routine for your chip platform is ready to use, component porting is not needed. If your platform is not supported, adapt the easyLogger component to the target platform. As for the encryption component mbedtls, it can be ported directly without adaptation.

• Tuya’s proprietary components are used for dedicated features such as authorization and production testing.

  They are a set of common routines that you can refer to for developing most Bluetooth LE products. This topic only describes lock applications.

  The features include authorization and production testing, OTA update, local storage management, and end product testing. In the authorization and production testing process, you flash the MAC address, AuthKey, and device ID to the device and verify the validity. OTA update uses Tuya’s proprietary Bluetooth OTA technology. If no demo routine is available for your chip platform, port the OTA component yourself. Local storage management provides a simple example of the local storage logic for lock applications. End product testing refers to verifying the full functionality of the final product.

app_port

The application layer (including Tuya’s proprietary components) is isolated from other layers for better compatibility. The isolation layer is called app_port. In the application layer, only the encapsulated underlying APIs (prefixed with app_port) in the isolation layer and the application APIs exist.

app

• app_lock: implements the applications dedicated to the lock products.

  • lock_common: uncategorized.
  • lock_hard: user hardware interface and serial port emulator (for debugging).
  • lock_dp_parser: parses DP data, with data flowing from the mobile phone to the device.
  • lock_dp_report: reports DP data, with data flowing from the device to the mobile phone.
  • lock_timer: the timer in the application layer.
  • lock_dynamic_pwd: dynamic password.
  • lock_offline_pwd: offline password.
  • lock_test: end product testing.

• app_common: implements the common applications for Bluetooth products.

  • app_common: uncategorized.
  • app_flash: local storage management.
  • app_ota: OTA update.
  • app_active_report: reports data proactively.
  • app_antilost: anti-lost feature.
  • app_test: authorization and production testing.

• app_port: encapsulated underlying APIs, providing unified naming and management for all the APIs used in the application layer. This makes the application layer an independent module for easy portability.

tuya_ble_sdk

Bluetooth LE pairing SDK is used to implement the pairing process and basic data communication between the Bluetooth LE device and the mobile app. For more information, see Bluetooth LE Guide.

Chip vendor SDK

• Beken (BK3431Q)

  Encapsulated APIs based on the chip vendor SDK:

  • bk_common: uncategorized.
  • bk_scan_adv: scanning and advertising.
  • bk_ble: Bluetooth LE parameters.
  • bk_svc: service and Characteristics.
  • bk_uart: serial port.
  • bk_timer: timer.
  • bk_flash: flash memory.
  • bk_gpio: GPIO.
  • bk_test: for testing.

Third-party components

• cpt_math: math algorithms such as checksum, CRC-16, CRC-32, and byte reversal.
• cpt_hash, cpt_mbedtls, and cpt_fpe: encryption algorithms, such as AES-128-ECB, AES-128-CBC, MD5 hash, and format preserving encryption (FPE).
• cpt_easylogger: SDK log output. The following two APIs are used:
  • log_d();
  • elog_hexdump(name, width, buf, size);

If the demo routine for your chip platform is ready to use, component porting is not needed. If your platform is not supported, port the component to the target platform and implement at least the two APIs mentioned above.

Check the source code on GitHub.

Routine description

Local storage management

tuya_ble_sdk uses 16 KB of flash memory to store authorization and tuya_ble_sdk system information. The memory is allocated separately, with the start address TUYA_NV_START_ADDR.

40 KB of flash memory is allocated to the application layer to store cached data and other application data with the SimpleFlash based ID-value storage structure. You can adjust the available flash memory to your needs. The starting address is SF_AREA0_BASE. The following APIs are used for operating the flash memory.

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);

The flash memory mentioned above refers only to the storage space without including the code area.

Local storage refers to storage for hardware, events, and settings. The storage logic is implemented in the app_flash.c file.

• Hardware storage

  A ready-to-use hardware storage routine in the application layer can help you get started. In real-world development, implement the storage logic to your business needs. The demo routine can store up to 256 pieces of hardware, with one unlocking method per piece.

• Event storage

  A ready-to-use event storage routine in the application layer can help you get started. In real-world development, implement the storage logic to your business needs. The demo routine can store up to EVTID_MAX events. The upper limit can be specified as needed. If it exceeds the allocated flash memory, adjust the memory allocation accordingly. Up to 64 events can be stored by default.

  

• Setting storage

  A ready-to-use setting storage routine in the application layer can help you get started. In real-world development, implement the logic to your business needs. The routine stores the lock settings. For more information, see lock_settings_t.

  To modify the default lock settings, find lock_settings_default and modify the respective parameters.

DP data parsing

The DP data parsing routine is located in the lock_dp_parser and lock_dp_report folders, which follows the Data Point Reference. You can directly use the routine to get started. In real-world development, implement the logic to your business needs.

• lock_dp_parser.c is used to parse the DP data received by the Bluetooth module. The hardware-specific data will be passed to lock_hard.c that serves as an interface between DP data and local logic.

• lock_dp_report.c is used to report DP data to the Bluetooth module. You can also call the API in this file to report the data on the local storage.

OTA update

Tuya provides the OTA update deployment service backed by the Tuya Developer Platform and data communication protocol. You need to implement the flash storage logic for OTA updates. The demo routine has this logic implemented. The OTA implementation is located in app_ota. If the demo routine for your chip platform is ready to use, porting is not needed. If your platform is not supported, port the OTA feature to the target platform by referring to the demo routine.

• BK3431Q platform

  OTA feature: seamless updates, with no support for resumable transfer

• nRF52832 platform

  OTA feature: seamless updates and resumable transfer

Production testing

Production testing is divided into two parts:

• Authorization and production testing: Check the device information and flash the MAC address, UUID, and AuthKey to the device.

• End product testing: includes the required radio RSSI test and other optional functional tests.

  The end product testing verifies the functionality of peripherals to reduce product defects and ensure the yield rate. Tuya provides the complete Bluetooth test case, dongle, and host software.

Demo

This section uses BK3431Q as an example to describe the routines in the SDK.

Basic Information

• Chip: BK3431Q
• SDK: ble_3435_sdk_ext_39_0F0E
• IDE: μVision V5.28.0.0
• Authorization: UART 1
• Log output: UART 2

Demo structure

Request license

Contact the project manager to request the license.

If you are working on a real project, use the requested license for debugging. Do a full chip erase and download the firmware to the chip to take the license effect.

The code below indicates where you can modify the product ID (PID), AuthKey, and device ID.

OTA update

1. Modify the firmware version in the app_common.h file, as shown below.

   

2. Compile your project. The output file is located in \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. For more information about deploying an OTA update, see Update Firmware.

4. Open the Smart Life app and connect to the Bluetooth device. Tap the pencil icon in the top right corner > Device Update to install the update.