蓝牙设备开发包

概述

蓝牙设备开发包 是基于 TuyaOS 系统裁剪的适用于涂鸦蓝牙 LE 协议产品的开发包，开发包将设备配网、上下行数据通信、产测授权、固件 OTA 升级等接口进行封装，并提供标准 API。

您无需关心各芯片平台相关功能的具体实现，只需要基于 TuyaOS 提供的标准 API 进行产品开发，即可接入 涂鸦开发者平台，完成设备智能化。

资源需求

蓝牙设备开发包 代码体积约占 20K 的 Flash 空间，正常运行需要约 10K RAM 空间。

开发包根据不同芯片平台的占用情况不同，内存占用情况也差异较大。实际芯片平台占用的 Flash 和 RAM 空间，在获取开发包之后查阅文档 TuyaOS_BLE_Platform_xxxx.md 的 开发软件 > 计算 Flash 和 RAM 占用 章节。

能力地图

设备管理

能力	说明
初始化	了解初始化流程对于理解蓝牙设备的软件框架会有很大帮助。 初始化是指设备上电进入 main 函数之后，调用一系列接口，完成设备硬件环境的初始化、TuyaOS 软件的初始化、应用功能的初始化等工作。应用初始化的时候，您要注意初始化的顺序，业务逻辑的初始化一般要放在蓝牙协议栈初始化之后，要尤其注意不同模块初始化的依赖条件。
重置	设备重置的目标是把设备恢复到配网之前的状态，方便客户再次进行配网。 根据触发源不同，分为本地重置和 App 重置。根据重置后设备所处的状态，又细分为普通重置（解除绑定）和恢复出厂重置（解绑并清除数据）。
授权	授权的目标是将普通的蓝牙设备转换为涂鸦的蓝牙设备。 授权的方式是将云端生成的设备标识信息写入到设备的非易失性存储器（一般为芯片的 Flash）之中，用于后续设备正常运行时的设备认证和配网激活流程。可以通过直接修改代码和上位机下发授权信息两种路径进行授权，前者主要在调试阶段使用，后者主要在量产阶段使用。
产测	产测可以发现蓝牙设备在生产过程中可能出现的硬件问题，提高良品率。 根据产测阶段的不同，分为 PCBA 产测和成品产测，PCBA 产测可以通过串口跟蓝牙设备通信，成品产测只能通过蓝牙无线连接的方式跟设备通信，从而检测设备的射频功能和外设功能是否正常。

蓝牙连接

能力	说明
连接能力	根据连接能力的不同，子设备分为三种类型： 支持涂鸦 智能生活 App 和涂鸦蓝牙网关。 仅支持涂鸦 智能生活 App，不能通过网关配网，不能通过网关连接，也不能通过 App 将子设备拖到网关下。 仅支持涂鸦蓝牙网关，只能通过网关配网，不需要通过 App 拖到网关下。
是否支持漫游	根据是否支持漫游功能，子设备分为两种类型： 漫游设备，漫游是指蓝牙子设备可以通过同一个家庭内的任一个涂鸦蓝牙网关基于 Tuya BLE Beacon 技术上传数据到云端。子设备和网关之间没有归属关系，只需要在同一个家庭下，无需任何配置即可实现。目前只支持上行数据（子设备 → 网关），不支持下行数据。 普通设备，普通设备不支持漫游能力，普通设备如果要支持网关连接，需要通过手机 App 面板添加到网关下，成为网关的子设备。
连接策略	对于支持涂鸦蓝牙网关连接的普通蓝牙子设备，根据连接策略分为两种类型： 长连接设备，长连接主要用于需要始终和蓝牙网关保持连接的子设备类型，如果断开了，网关会自动重新连接该设备。 短连接设备，又称作按需连接设备，短连接设备平时和蓝牙网关不保持连接，只有需要数据收发时才会建立连接，数据交互完成后断开连接。对于上行数据（子设备 → 网关），子设备会在广播包中置位请求连接标志，蓝牙网关扫描到该标志后发起连接。对于下行数据（网关 → 子设备），蓝牙网关接收云端/手机 App 的指令连接设备。

蓝牙配网

能力	说明
配网方式	主机通过蓝牙广播识别从机，并对已授权的从机发起配对请求，完成配对的主从机处于绑定状态。处于绑定状态的主从机之间存在一条符合蓝牙规范的安全通道，所有的业务类通信（包括 DP 数据）都在该安全通道中进行。 蓝牙的配网方式有两种： 常规配网，最常用的配网方式，子设备一直发送蓝牙广播包，可以通过涂鸦 智能生活 App 首页弹窗、配网品类页自动发现、配网品类页点击品类手动配网等方式发现子设备。 扫码配网，用户首先扫描包装、设备上的二维码/手动输入设备编号，然后涂鸦 智能生活 App 扫描对应的蓝牙设备并进行配网，子设备通过广播包中的标记位区分常规配网还是扫码配网。
移除方式	移除是设备重置的一种方式，根据移除的时机不同，分为两种方式： 在线移除：设备在线的时候移除。 离线移除：设备离线的时候移除，离线移除又称作异常解绑，机制为：涂鸦智能 APP 在未连接蓝牙设备的情况下，在面板上对该设备进行解除绑定/解绑并清除数据，操作成功并同步至云端，此时设备端还处于绑定状态。此后，设备进行蓝牙广播（绑定状态），如果任一涂鸦智能 APP 扫描到该设备，发现其广播是绑定状态，但是该设备在云端的状态为未绑定状态，则会主动对其进行蓝牙连接，连接成功后发送异常解绑指令（该过程 APP 界面无任何变化），此时蓝牙设备就能收到异常解绑事件，并进行异常解绑操作。
安全等级	根据安全等级的不同，子设备分为两种类型： 强绑定，当前绑定用户必须先从 App 上解绑设备后，其他用户才能对该设备进行配网操作，如果仅从设备端重置设备，设备仍无法被其他用户配网成功，强绑定主要用于安全等级高的产品类型，例如智能门锁。 弱绑定，设备无论是从手机端还是从设备端被重置，都可以被其他用户绑定，而不需要前一个用户同意，也不会给前一个用户发送通知，大多数蓝牙设备采用这种方式。

设备控制

能力	说明
DP 数据通信	DP 数据通信基于 DP 数据模型，根据数据流转方向的不同分为三种： DP 数据下发，手机 App/蓝牙网关发送给子设备。 DP 数据查询，手机 App/蓝牙网关先发送给子设备查询指令，子设备再根据查询指令批量上报查询的 DP 数据。 DP 数据上报，子设备发送给手机 App/蓝牙网关，可以选择是否带时间戳上报，也可以选择只上报给面板、只上报给云端或者同时上报给面板和云端。
联动模型	联动是基于 DP 模型的自动化功能，联动类型分为两种： 云端联动，由云端执行的联动，叫云端联动。 网关联动，由本地（目前只有网关）执行的联动叫网关联动/本地联动，无需连接外网。
场景一键执行	场景和自动化的区别：场景没有条件，只有动作，一般是动作的集合，触发场景就是触发这些动作。自动化就是条件+动作，当某个条件满足时，执行某个动作。

基础服务

能力	说明
时间服务	蓝牙设备可以通过涂鸦 智能生活 App /蓝牙网关向云端请求网络时间，可以指定请求的时间格式。
天气服务	蓝牙设备可以通过涂鸦 智能生活 App /蓝牙网关向云端请求天气数据，可以指定天气位置、天气类型和获取的天数，该服务目前可免费使用，不排除后续收费的可能性。
大数据传输	又称作离线 DP 数据批量传输，大部分产品应用中需要离线缓存 DP 数据，等到建立蓝牙连接时一次性发送缓存的数据，对于较大的离线数据，如果基于单一的 DP 发送指令同步数据，需要花费较长的时间，产品体验较差。 对于较大的离线缓存数据，可以通过离线 DP 数据批量传输通道同步到手机 App 端，当前该通道的传输速率最高可达 15kB/s，实际速率受到蓝牙芯片性能和手机性能的影响。
文件下发	对于智能门锁、智能手表/手环、蓝牙打印机等设备，通常需要在线生成并下载语音文件、表盘文件、打印文件等数据到蓝牙子设备。同时，这些文件在某些情况下需要可被操作，比如增加文件、删除文件、使用文件等。涂鸦蓝牙的文件下发通道即为该场景设计，目前通道速率可达 5~10KB/s，具体取决于所用蓝牙芯片和手机性能。
共享设备	共享设备是涂鸦蓝牙的一种设备类型，共享类设备可同时被多用户共同使用，支持多用户同时绑定，常用于体脂称，温湿度计等产品。
业务数据透传	涂鸦蓝牙 SDK 提供业务数据透传通道用于业务数据的自定义传输协议。

高级服务

能力	说明
iBeacon	iBeacon 是苹果公司发布的一种基于低功耗蓝牙广播的通信协议，其工作方式是：配备有 iBeacon 协议的低功耗蓝牙设备向周围广播发送自己特有的 ID，注册了 iBeacon 服务的 App 在手机收到广播后会被唤醒，并利用接收到的 ID 进行一些业务逻辑处理。苹果公司还提供了测距、地理围栏等可用特性，可实现诸如 SOS、报警、定位等 iBeacon 专项功能。 涂鸦蓝牙设备结合涂鸦 智能生活 App 已经完整支持了该功能，并提供了自己的业务逻辑功能，典型产品有： 防丢器，双击可触发 100 ms 每包的 iBeacon 广播，唤醒手机并响铃。 门锁，进入/离开 iBeacon 地理围栏区域，实现自动解锁/上锁。 防狼器，又称作防身报警器，专门给女性使用，例如遇到强盗等危害人身安全的时候，触发防狼器，设备可以大声报警，同时激活手机 App 上报 SOS 求救信息。 SOS 手电筒，手电筒开关按钮长按触发 iBeacon 广播唤醒附近 App 并立刻上报 SOS 报警信息，收到短信的亲属可以立刻按照位置呼叫救援。 温湿度设备，交替广播 iBeacon 和 Beacon 信号，当 iBeacon 唤醒附近手机 App 后，App 启动扫描接收 Beacon 信号并解析出温湿度数据。 食物探针，将探针插入食物中，当检测到可疑元素，探针触发 iBeacon 广播，唤醒附近 App 并上报可疑信号。
HID 靠近响应	HID（Human Interface Device）定义了蓝牙在人机接口设备中的协议、特征和使用规程，主要是利用蓝牙设备与手机系统蓝牙配对，靠近后设备能够自动回连此设备的特性，使连接的工作由 App 转到系统层，不用依赖 App 发起扫描连接，从而达到无感连接的体验（系统级，速度快，首次需要通过 App 操作配对）。典型应用场景有： 灯，依托 HID 自动回连特性，靠近开灯，远离关灯。 开关，依托 HID 自动回连特性，靠近开关自动打开，远离开关自动关闭。 门锁，基于地理围栏 + HID 自动回连特性，在地理围栏区域内检测到 HID 自动回连成功即自动开锁。 无感解锁车辆，基于 UWB + HID，HID 配对创建车辆的数字车钥匙，UWB 测距检查手机是否在车内，从而决定是否激活车钥匙。
Tuya BLE Beacon	Tuya BLE Beacon 是一种通过蓝牙广播上传涂鸦 DP 数据的技术，完全兼容 Tuya 蓝牙规范广播协议，不影响蓝牙子设备的重连、移除等能力，蓝牙 Beacon 也是漫游类蓝牙子设备上传数据的通信方式。
支持协议共存	涂鸦蓝牙协议是蓝牙应用层协议，完全符合蓝牙应用规范，当然也可以和其他蓝牙应用协议共存，单个蓝牙子设备可以同时运行涂鸦蓝牙协议和其他应用层协议，这样可以方便地开发支持多平台的蓝牙设备。同时，涂鸦蓝牙协议对蓝牙广播有严格的格式和内容要求，如果要支持多平台协议： 首选支持 multiple advertising sets 的蓝牙芯片。 其次建议使用涂鸦蓝牙广播协议。 交替广播（体验较差）。

三方生态

能力	说明
Alexa 语音助手	设备端采集固定格式编码的音频（当前支持 opus 和 msbc）通过涂鸦蓝牙传输协议实时发送 至手机端，手机端 APP 将音频数据传输至 AVS ，AVS 返回识别结果到手机，手机通过涂鸦蓝牙传输协议 发送至设备端展示。
非智能配件接入	对于没有无线通信能力的非智能配件类产品，可以借助涂鸦蓝牙智能化产品来接入云端，实现智 能化控制，例如 OTA 等，例如电池包和电动工具，一个电池包可以和不同种类的电动工具配合使用，该 能力区别于普通蓝牙通用对接方式，配件和主机可以有不同的产品 ID。

设备驱动

能力	说明
GPIO	GPIO 驱动，提供调试例程：可以通过上位机控制任意 GPIO 输出高低电平，也可以查询任意 GPIO 的当前电平。
UART	UART 驱动，提供调试例程：可以通过上位机设置任意 UART 的波特率，也可以控制任意 UART 发送自定义数据。
PWM	PWM 驱动，提供调试例程：可以通过上位机设置任意通道 PWM 的频率和占空比，也可以控制任意通道 PWM 恢复初始状态。
ADC	ADC 驱动，提供调试例程：可以通过上位机读取任意 ADC 通道的数值/电压值，也可以修改 ADC 的分辨率。
SPI	SPI 驱动，提供调试例程：可以通过上位机控制任意 SPI 模块的 SDI 和 SDO 引脚互相发送自定义数据，也可以修改任意 SPI 模块的通信速率。
IIC	IIC 驱动，提供调试例程：可以通过上位机控制任意 IIC 模块点亮 OLED 屏幕，并显示自定义数据。
RTC	RTC 驱动，提供调试例程：可以通过上位机设置/查询设备的 RTC 时间，也可以控制 RTC 模块的启动/停止。
Watchdog	Watchdog 驱动，提供调试例程：可以通过上位机启动/关闭看门狗，可以开启/关闭自动喂狗功能，也可以通过上位机测试手动喂狗的功能。

功耗管理

能力	说明
常规功耗设备	蓝牙广播间隔 20ms~200ms，持续广播，该设备平均功耗可维持在 60μA~1mA 左右。 蓝牙广播间隔越大，功耗越低，但是手机 App 和蓝牙网关发现和连接的时间也就越长，产品定义需要权衡利弊。
低功耗设备	蓝牙广播间隔 500ms~1200ms，持续广播，该设备平均功耗可维持在 15μA~50μA 左右。 蓝牙广播间隔越大，功耗越低，但是手机 App 和蓝牙网关发现和连接的时间也就越长，产品定义需要权衡利弊。
超低功耗设备	蓝牙广播间隔 20ms~200ms，由外部条件触发不大于 10s 的持续广播，该设备平均功耗可维持在 0.4μA~15μA 左右，一般用于单向上报类设备，例如遥控器、PIR。 蓝牙广播间隔越大，功耗越低，但是手机 App 和蓝牙网关发现和连接的时间也就越长，产品定义需要权衡利弊。

升级服务

能力	说明
蓝牙固件 OTA	通过涂鸦 智能生活 App /网关给蓝牙设备进行 OTA，支持断点续传、数据完整性校验、断电断网等异常处理能力。
MCU 固件 OTA	涂鸦 智能生活 App /网关将升级固件传输给蓝牙设备（蓝牙模组或整机设备），蓝牙设备通过 UART 或其他数字接口将升级固件传出给 MCU。
扩展固件 OTA	支持多达 10 个扩展固件升级，客户可根据需要自定义要传输的 OTA 固件能力。

设备安全

能力	说明
安全体系	涂鸦自有算法通过连接认证、请求授权、指令下发等多重交互保障设备安全，涉及到的安全措施有： 一机一密，每一个接入涂鸦的蓝牙芯片都会在出厂时烧录涂鸦分配的唯一授权信息，用于安全认证。 AES128 加密，采用 AES128 数据加密算法。 动态秘钥，每次蓝牙连接都会基于涂鸦自有算法生成新的会话秘钥。 防重放，4 字节的指令序列号，用于数据防重放攻击。 安全芯片，SDK 支持扩展添加硬件安全芯片。 涂鸦蓝牙私有加密协议是蓝牙应用层加密协议，区别于蓝牙链路层的配对（Pairing）和绑定（Bonding）机制。除了使用配对和绑定这种底层方式来保障蓝牙通信安全外，用户也可以在应用层实现相同的功能，涂鸦蓝牙私有加密协议就是基于应用层的，两者在功能和安全性上面没有任何区别，只不过应用层实现的话需要自己选择加密算法、秘钥生成方式以及秘钥交换方式等。

支持与帮助

在开发过程遇到问题，您可以登录 TuyaOS 开发者论坛 TuyaOS-子设备开发版块 进行沟通咨询。