Bluetooth Device Development Kit

Last Updated on : 2024-06-25 09:35:27download

Overview

Bluetooth Device Development Kit is built on top of TuyaOS for Bluetooth Low Energy (LE) device development. This kit includes a host of features and standard APIs to help you develop easily, including device pairing, upstream and downstream communication, production testing, authorization, and OTA updates.

You do not need to take care of feature implementation for different chip platforms. Just working on the standard APIs, you can connect your products to the Tuya Developer Platform and make them IoT-enabled.

Resource requirements

Bluetooth Device Development Kit requires 20 KB flash and 10 KB RAM.

The memory footprint of a development kit depends on the chip platform for use. Check the section Build Software > Calculate flash and RAM usage in the file TuyaOS_BLE_Platform_xxxx.md to get the flash and RAM usage for your chip platform.

Capability map

Device management

Capability	Description
Initialization	Understanding the initialization process can help you get through Bluetooth software development. Initialization is a process where after a device enters the `main` function after power on, it calls a range of APIs to initialize the hardware environment, TuyaOS software, and applications. During the application initialization, take care of the sequence of API calls. Business logic is generally after the Bluetooth stacks. The dependencies for initialization vary depending on the modules.
Reset	A reset can restore a device to the settings that the device had before it was paired. Device reset can be triggered by hardware operation or mobile app operation. In terms of device status after a reset, there are two types of reset: normal reset (device unbound) and factory reset (device unbound with data erased).
Authorization	Only authorized Bluetooth devices can connect to the Tuya Developer Platform. Authorization is the process of writing the device identification information for authentication and pairing to the non-volatile memory (typically the flash memory) on the device. You can perform authorization by editing the code or using a host. The former is for debugging purposes, and the latter is for mass production.
Production testing	Testing in the production process helps you identify any Bluetooth hardware issues for better yield. There are PCBA testing and end product testing. In PCBA testing, communication with Bluetooth devices is established through the serial port. In end product testing, communication is over Bluetooth to test the device’s radio and peripheral functionality.

Bluetooth connection

Capability	Description
Connectivity capability	There are three types of sub-devices by connectivity capabilities. Support connection to both the Smart Life app and the Tuya-enabled Bluetooth gateway. Support connection to the Smart Life app only. The sub-device cannot be paired or connected through the gateway, or added to the gateway using the mobile app. Support connection to the Tuya-enabled Bluetooth gateway only, without the need to add the sub-device to the gateway using the app.
Roaming	There are two types of sub-devices by roaming capability. Tuya Bluetooth LE beacon technology allows roaming-enabled Bluetooth sub-devices to upload data to the cloud through any of the Tuya-enabled Bluetooth gateways in the home. The sub-device and the gateway do not need to be associated with each other. As long as they belong to the same home, roaming can be achieved without any further configuration. Roaming only allows the sub-device to send data to the gateway and not vice-versa. A common device does not support roaming. To enable connection to the gateway, a device should be added to the gateway as a sub-device using the mobile app.
Connection strategy	There are two types of connection strategies for common Bluetooth sub-devices that support connection to the Tuya-enabled Bluetooth gateway. Persistent connection: The sub-device remains connected to the Bluetooth gateway. The gateway automatically reconnects to the sub-device if their connection is lost. Non-persistent connection: The sub-device is disconnected from the gateway unless they have data to exchange. After the data exchange, the connection will be closed. For sub-device-to-gateway communication, the sub-device sets a connection request flag in the advertising packet. When the gateway detects this flag, it initiates a connection to the sub-device. For gateway-to-sub-device communication, the Bluetooth gateway receives the command from the cloud or the mobile app for initiating a connection to the sub-device.

Pairing over Bluetooth

Capability	Description
Pairing modes	The central device can initiate a pairing request to an advertising peripheral device. After successful pairing, the peripheral device is bound to the central device. They communicate with each other (including the exchange of data point data) over a secure channel in compliance with Bluetooth specifications. There are two methods to pair a Bluetooth device. Common pairing: Bluetooth device sends advertising packets after entering the pairing mode. On the Smart Life app, the user can select the target device in the pop-up window on the home page or choose auto-discovery or manual adding on the Add Device page. Pair with QR code: The user scans the QR code on the package or device or manually enters the device serial number. Then, the user scans the Bluetooth device using the Smart Life app for pairing. The flag in the advertising packet identifies the pairing method.
Removing device	Removing a device is one of the methods to reset a device. There are two types of removing by connection status. Online removing: Remove a device when it is online. Offline removing: Remove a device when it is offline, also called abnormal unbinding. The user removes a device from the Smart Life app when the device is disconnected. On a successful operation, the device becomes unbound in the cloud, but remains in the bound state on the device side. In this case, when this device is advertising, if any Tuya-based mobile app connects to it, the app will send this device a command to unbind. Note that the process of device handling offline unbinding will not be reflected on the mobile app.
Security level	There are two types of sub-devices by security level. Strong binding: A paired device must be removed from the app by the current user before it can be paired by another user. For a device that is only reset locally, it cannot be paired by another user. Strong binding applies to products that require high-level security, such as smart locks. Weak binding: A device can be paired by another user regardless of how it has been reset. The pairing process does not involve the previous user. Most Bluetooth devices adopt weak binding.

Device control

Capability	Description
DP data communication	There are three types of DP communication based on the direction of data flow. DP data sending: The mobile app or Bluetooth gateway sends DP data to the sub-device. DP data query: The mobile app or Bluetooth gateway sends a query to the sub-device. The sub-device then reports the requested DP data in bulk. DP data reporting: The sub-device sends DP data to the mobile app or Bluetooth gateway. You can choose whether to carry the timestamp and the destination that can be the app panel only, the cloud only, or both the app panel and cloud.
Linkage model	Linkage is a type of automation based on the DP model. There are two types of linkage. Cloud linkage: The cloud runs the linkage, which requires internet access. Gateway linkage: The gateway runs the linkage, also known as local linkage. Internet access is not required.
Tap-to-Run	Difference between the scene and automation: A scene only consists of actions, without a condition. Triggering a scene is actually to execute the preset action. Automation contains both conditions and actions. When a condition is met, an action is executed.

Basic services

Capability	Description
Time service	A Bluetooth device can request the network time in a specified format through the Smart Life app or Bluetooth gateway.
Weather service	A Bluetooth device can request weather data in terms of location, weather variables, and forecast days through the Smart Life app or Bluetooth gateway. This feature is free for now, but may become paid in the future.
Bulk data transfer	Most products cache DP data when going offline and send all the cached data out when Bluetooth is connected. For large-size data, it takes a long time to send DP data one by one. Bulk data transfer is used to address this issue by sending the cached data in bulk to the mobile app. The transfer rate can reach 15 KB/s, depending on Bluetooth and mobile phone performance.
File download	Bluetooth devices such as smart locks, watches, bracelets, and printers need to download files from the cloud, such as voice files, watch faces, and files for printing. In some cases, the user performs add, delete, and read operations on these files. The file download speed is about 5 KB/s to 10 KB/s, depending on Bluetooth and mobile phone performance.
Device sharing	Bluetooth devices that support sharing can be shared with multiple users for binding and use, such as the body fat scale and thermo-hygrometer.
Raw data transmission	The pass-through channel allows you to transmit business data in a custom format.

Advanced services

Capability	Description
iBeacon	iBeacon is a Bluetooth Low Energy based protocol developed by Apple. An iBeacon-enabled device can broadcast its identifier to nearby devices. When the mobile phone receives the iBeacon signals, the mobile app with the iBeacon service registered will be invoked to perform specific actions. iBeacon supports proximity sensing and geofencing, which can be applied to SOS, alarming, and positioning. Tuya’s Bluetooth capabilities and business logic in tandem with the Smart Life app can implement the complete iBeacon features, which apply to the following use cases. Smart tracker: Double-tap triggers iBeacon advertising at an interval of 100 ms. When the distance between the phone and the tracker is within the specified range, the mobile app will be invoked and emit a sound. Door locks: When the user enters or exits the iBeacon geofence, the lock is automatically unlocked and locked. Personal safety alarm: When activated, it emits a loud noise to deter potential attackers and invokes the mobile app to report an SOS alarm. SOS flashlight: Pressing and holding the flashlight’s power button triggers iBeacon advertising. This can invoke the nearby mobile app to send an SOS alarm with the location information to the specified contacts. Thermo-hygrometer: It alternates the advertising between iBeacon and Beacon. When the mobile app is invoked via iBeacon signals, it starts receiving beacon signals and parsing the temperature and humidity data. Cooking thermometer: When food reaches or drops below a certain temperature, the probe broadcasts iBeacon signals to invoke the mobile app for alerting.
HID service	The human interface device (HID) profile defines how devices with Bluetooth enabled can use the HID Specification initially to discover Bluetooth HID devices and automatically connects to the saved device. With the HID service, the mobile phone instead of the mobile app initiates a connection request when a paired Bluetooth device is in range. This enables a fast and seamless connection to Bluetooth devices that have been paired with the mobile app. Typical use cases: Lights: With the HID auto-reconnect feature, lights automatically come on or off when the mobile phone is in or out of Bluetooth range. Switches: With the HID auto-reconnect feature, switches automatically turn on or off when the mobile phone is in or out of Bluetooth range. Door locks: With geofencing and HID auto-reconnect features, doors automatically unlock when the mobile phone is within the geofenced area and successfully connected to the lock. Automatically unlocking cars: Implemented with ultra-wideband (UWB) and HID. HID pairs the car with the digital car key on the phone. UWB detects the presence of the mobile phone in order to determine whether to activate the key.
Tuya Bluetooth Low Energy Beacon	Tuya Bluetooth Low Energy beacon enables DP data upload via Bluetooth broadcast. It is fully compatible with Tuya-defined Bluetooth advertising protocol without compromising Bluetooth sub-device capabilities such as reconnection and removal. Bluetooth sub-devices with the roaming feature also use Bluetooth beacon to upload data.
Protocol coexistence	As an application layer protocol, the Tuya-defined Bluetooth profile is compliant with Bluetooth profile specifications and compatible with other Bluetooth profiles. A Bluetooth sub-device can run both the Tuya-defined Bluetooth profile and other application profiles. Tuya-defined Bluetooth profile defines advertising format and content. To support protocols across multiple platforms, consider the following. Bluetooth chips with multiple advertising sets are preferred. Tuya-defined Bluetooth advertising protocol is recommended. Alternates Bluetooth advertising between different protocols.

Third-party ecosystem

Capability	Description
Alexa voice assistant	The device captures the audio encoded with a specific format (Opus and mSBC are supported currently) and then sends the audio to the mobile app in real time through Tuya-defined Bluetooth transfer protocol. The mobile app forwards the audio to Alexa Voice Service (AVS). AVS returns the speech recognition result that the mobile app forwards to the device for display.
Connection to non-smart accessories	Non-smart accessories are not capable of wireless communication. You can leverage Tuya-enabled Bluetooth smart devices to enable these accessories to connect to the cloud and use technologies such as OTA. For example, a battery pack can work with different types of power tools. This capability differs from common Bluetooth solutions in that the accessory and the main device can have a different product ID.

Capability

Description

Alexa voice assistant

The device captures the audio encoded with a specific format (Opus and mSBC are supported currently) and then sends the audio to the mobile app in real time through Tuya-defined Bluetooth transfer protocol. The mobile app forwards the audio to Alexa Voice Service (AVS). AVS returns the speech recognition result that the mobile app forwards to the device for display.

Connection to non-smart accessories

Non-smart accessories are not capable of wireless communication. You can leverage Tuya-enabled Bluetooth smart devices to enable these accessories to connect to the cloud and use technologies such as OTA. For example, a battery pack can work with different types of power tools. This capability differs from common Bluetooth solutions in that the accessory and the main device can have a different product ID.

Device driver

Capability	Description
GPIO	GPIO driver, with debugging routines. With a host, you can set a GPIO to output high or low and check the current state of a GPIO.
UART	UART driver, with debugging routines. With a host, you can set the baud rate for a UART and control a UART to send custom data.
PWM	PWM driver, with debugging routines. With a host, you can set the frequency and duty cycle of a PWM and restore a PWM to the initial state.
ADC	ADC driver, with debugging routines. With a host, you can read the value or voltage of an ADC channel and change the resolution of an ADC.
SPI	SPI driver, with debugging routines. With a host, you can control the SDI and SDO of an SPI module to receive and send custom data and change the transfer rate of an SPI module.
I2C	I2C driver, with debugging routines. With a host, you can control an I2C module to turn on an OLED screen and display custom data.
RTC	RTC driver, with debugging routines. With a host, you can set or get the RTC of a device and start or stop the RTC module.
Watchdog	Watchdog driver, with debugging routines. With a host, you can start or stop the watchdog, enable or disable automatic feeding, and test manual feeding.

Power management

Capability	Description
Standard power	Bluetooth advertising interval ranges from 20 ms to 200 ms. In continuous advertising mode, the average power consumption is about 60 μA to 1 mA. Longer advertising intervals consume less energy, but can result in longer discovery and connect times between the mobile app and the Bluetooth gateway. You need to trade off between discovery latency and power usage.
Low power	Bluetooth advertising interval ranges from 500 ms to 1,200 ms. In continuous advertising mode, the average power consumption is about 15 μA to 50 μA. Longer advertising intervals consume less energy, but can result in longer discovery and connect times between the mobile app and the Bluetooth gateway. You need to trade off between discovery latency and power usage.
Ultra-low power	Bluetooth advertising interval ranges from 20 ms to 200 ms. In continuous adverting triggered by externals at an interval of less than 10s, the average power consumption is about 0.4 μA to 15 μA. This mode is used for report-only devices, such as the remote control and PIR. Longer advertising intervals consume less energy, but can result in longer discovery and connect times between the mobile app and the Bluetooth gateway. You need to trade off between discovery latency and power usage.

OTA update

Capability	Description
Update Bluetooth firmware via OTA	Send an OTA update to a Bluetooth device through the Smart Life app or the gateway. Resumable transfer, data integrity check, and exception processing are supported.
Update MCU firmware via OTA	The Bluetooth device (Bluetooth module or end product) receives a firmware update from the Smart Life app or the gateway and then forwards the received file to the MCU through UART or other digital interfaces.
Update extended firmware via OTA	Up to 10 update channels are available for updating extended firmware, which can be set to your needs.

Device security

Capability	Description
Security system	Tuya’s proprietary algorithms secure devices regarding connection authentication, request authorization, and command sending, with the following measures. One-device-one-key authentication mechanism: Each Bluetooth chip connected to the Tuya Developer Platform is written with a unique license for identity authentication. Encryption using the AES-128 algorithm. Dynamic key: A session key is generated dynamically based on Tuya’s proprietary algorithm for each Bluetooth connection. Anti-replay: 4-byte operation code prevents replay attacks. Security chip: the SDK supports adding security chips. Tuya’s proprietary encryption protocol is used in the application layer. The pairing and bonding strategy secures data transmission in the underlying link layer. The application layer encryption and the link layer encryption have no difference in functionality and security. To implement application layer encryption, you need to determine the encryption algorithms and key generation and exchange methods.

Capability

Description

Security system

Tuya’s proprietary algorithms secure devices regarding connection authentication, request authorization, and command sending, with the following measures.

One-device-one-key authentication mechanism: Each Bluetooth chip connected to the Tuya Developer Platform is written with a unique license for identity authentication.
Encryption using the AES-128 algorithm.
Dynamic key: A session key is generated dynamically based on Tuya’s proprietary algorithm for each Bluetooth connection.
Anti-replay: 4-byte operation code prevents replay attacks.
Security chip: the SDK supports adding security chips.
Tuya’s proprietary encryption protocol is used in the application layer. The pairing and bonding strategy secures data transmission in the underlying link layer. The application layer encryption and the link layer encryption have no difference in functionality and security. To implement application layer encryption, you need to determine the encryption algorithms and key generation and exchange methods.

Support and help

If you have any problems with TuyaOS development, you can post your questions in the Tuya Developer Forum.

Prev DocType Development Kit

Next DocBluetooth Mesh