协议与云平台开发文档

本文档介绍 fw-AC63_BT_SDK 中与通信协议及云平台对接相关的开发文档资源，重点覆盖腾讯连连（腾讯云 IoT）开发文档中的数据模板 JSON 转 C 代码生成机制、LLSync 协议要点，以及 BLE SDK / 网关接入流程。

Purpose and Scope

本页面梳理 SDK 内"协议与云平台开发"这条文档线的全部可验证素材：

SDK 对第三方云平台协议的整体支持（third_party_profile：SigMesh、涂鸦、腾讯连连、HiLink）
doc/腾讯连连开发文档/ 目录中的工具链与实例：script/json 代码生成脚本、template实例 模板、腾讯连连开发说明.pdf
数据模板 JSON → C 代码的生成原理（"动态生成 + 固定写入"）、头文件/BLE/网关三种生成流程
开发者从物联网平台下载模板到固件编译接入的完整工作流

本页面不覆盖（留给同级目录的其他页面）：

蓝牙协议栈（BR/EDR、BLE）自身的实现细节——见 README 中的协议支持说明及各 include_lib 头文件
芯片 Datasheet、参考原理图等硬件文档——属于 doc/datasheet/ 文档资源
各具体应用示例（spp_and_le、third_party_profile 下的具体工程代码）——属于对应应用页面

Overview

fw-AC63_BT_SDK 是杰理科技为 AC63 系列蓝牙 SoC 提供的通用固件开发包，基于 Zephyr RTOS，内置通过蓝牙 SIG 认证的完整蓝牙协议栈（见 README.md）。

在应用层，SDK 通过 apps/**/third_party_profile 目录统一挂载第三方云平台协议，包括 SigMesh（蓝牙 Mesh）、涂鸦（Tuya）、腾讯连连（Tencent）与 HiLink（见 README.md）。其中腾讯连连对应腾讯云物联网开发平台（IoT Explorer）的 BLE 直连方案，其官方协议为 LLSync（低功耗蓝牙安全连接协议）。

云平台对接的最大痛点在于：物联网平台侧的数据模板（属性/事件/动作定义）与终端固件侧的结构体、宏定义、操作函数必须逐字段保持一致。腾讯连连开发文档中的 script/json 工具链正是为解决这一问题而设计：它以平台导出的 JSON 数据模板为唯一输入，自动生成 C 代码，从机制上保证两端数据定义一致，显著减少手工对齐工作量（见 readme.md）。

Architecture

flowchart TD
    subgraph sg_Cloud["腾讯云 IoT 平台"]
        Cloud["物联网平台<br/>数据模板 JSON"]
    end

    subgraph sg_Toolchain["doc/腾讯连连开发文档/script/json 工具链"]
        Config["config/dt.conf<br/>INI 配置"]
        Scripts["src/ 脚本"]
        Fixed["src/dt_fixed_content/<br/>固定代码片段"]
        BLE["interpret_dt_ble.py"]
        GW["interpret_dt_gateway.py"]
    end

    subgraph sg_Generated["生成产物"]
        Hdr["头文件<br/>宏/枚举/结构体/函数声明"]
        BleC["BLE C 文件<br/>ble_qiot_template.c"]
        GwC["网关 C 文件"]
    end

    subgraph sg_Firmware["固件侧"]
        BleSDK["BLE SDK<br/>data_template 目录编译"]
        GWSdk["网关 SDK 编译"]
        Ops["用户实现的操作函数"]
    end

    Cloud -->|"下载模板"| BLE
    Cloud -->|"下载模板"| GW
    Config --> Scripts
    Fixed --> Scripts
    Scripts --> BLE
    Scripts --> GW
    BLE --> Hdr
    BLE --> BleC
    GW --> Hdr
    GW --> GwC
    BleC --> Ops
    Ops --> BleSDK
    GwC --> GWSdk
    BleSDK -->|"LLSync 协议<br/>BLE 连接"| Cloud
    GWSdk -->|"LLSync 协议<br/>网关接入"| Cloud

架构说明：

输入唯一化：无论 BLE SDK 还是网关，代码生成的唯一输入都是物联网平台导出的 JSON 数据模板文件，避免多份手工定义漂移。
动态生成 + 固定写入：脚本（interpret_dt_ble.py / interpret_dt_gateway.py）负责解析 JSON 动态生成数据定义；而属性/事件/动作的操作函数骨架是固定不变的，从 dt_fixed_content 静态文件读取后写入，从而简化脚本逻辑（见 readme.md）。
配置驱动：config/dt.conf 以 INI 格式为脚本提供配置项，与代码逻辑解耦。
用户职责最小化：BLE 路径下，用户只需按数据特性实现 ble_qiot_template.c 中的操作函数，即可编译接入。

腾讯连连开发文档资源清单

doc/腾讯连连开发文档/ 目录是协议与云平台开发文档的核心，包含四类资源：

资源	路径	作用
开发说明	`腾讯连连开发说明.pdf`	腾讯连连平台接入的整体说明
代码生成脚本	`script/json/src/interpret_dt_ble.py`、`interpret_dt_gateway.py`	将 JSON 数据模板转换为 C 代码
固定代码片段	`script/json/src/dt_fixed_content/`	属性/事件/动作/函数原型的固定实现
模板实例	`template实例/ble_qiot_template.c`、`ble_qiot_template.h`、`template.json`	BLE 数据模板的参考实现与示例 JSON

脚本工具目录结构如下（摘自 readme.md）：

interpret_json_dt
├─config                                # 配置文件目录
│  └─dt.conf                            # INI配置文件
├─src                                   # 脚本文件目录
│  ├─dt_fixed_content                   # 固定代码文件目录
│  │   ├─dt_ble_action                  # ble action部分固定代码
│  │   ├─dt_ble_event                   # ble event部分固定代码
│  │   ├─dt_ble_property                # ble property部分固定代码
│  │   ├─dt_ble_prototype               # ble 函数原型
│  │   ├─dt_gateway_action              # gateway action部分固定代码
│  │   ├─dt_gateway_event               # gateway event部分固定代码
│  │   ├─dt_gateway_property            # gateway property部分固定代码
│  │   └─dt_gateway_prototype           # gateway 函数原型
│  ├─interpret_dt_ble.py                # 转换json脚本生成ble sdk代码
│  ├─interpret_dt_gateway.py            # 转换json脚本生成网关代码
│  └─example.json                       # 示例文件

Source: readme.md

代码生成机制详解

设计意图："动态生成 + 固定写入"

生成器采用双源拼接策略（见 readme.md）：

动态生成：脚本解析平台导出的 JSON 文件，把数据模板中的每个 id、类型、取值范围转换为对应的 C 定义——这部分因产品而异，必须由脚本逐字段翻译。
固定写入：每个数据 id 对应的操作函数（读写属性、上报事件、响应动作）骨架是固定不变的，从 dt_fixed_content 静态文件读取写入。

这样拆分的原因是：数据模板的"形状"千变万化，但云平台交互的"行为"模式有限（属性/事件/动作三类），把不变的部分固化成模板文件，脚本只负责组装，既降低了脚本复杂度，也保证了生成代码风格一致。

头文件生成流程（四步）

头文件生成遵循严格顺序（见 readme.md）：

按 LLSync 协议定义写入公共定义——包括数据类型定义、消息类型定义等；
解析 JSON，将字符串 id 转换为枚举类型 id（字符串比较变枚举匹配，降低运行时开销）；
按类型转换每个 id 对应的取值范围：
- 枚举类型 → 转换为枚举值定义；
- 整数/浮点类型 → 将最大值、最小值、起始值、步进转换为宏定义；
- 字符串类型 → 将最大长度、最小长度转换为宏定义；
写入不同数据类型的结构体定义；
写入函数声明——函数声明从 dt_gateway_prototype 等原型文件读取。

该顺序保证了头文件内引用先于定义、宏先于使用，生成物可直接参与编译。

BLE C 文件生成流程

BLE 路径生成两大部分（见 readme.md）：

解析 JSON，根据每个 id 生成其操作函数——注意：操作函数只是生成骨架，需要用户按需求实现；
解析 JSON，生成数据模板的结构数组（数据定义表）；
读取静态文件（dt_ble_action/event/property），写入固定操作函数。

生成产物为 ble_qiot_template.c 及其头文件，用户将生成文件拷贝到 data_template 目录编译，并补全操作函数实现即可。

网关 C 文件生成流程

网关路径更轻量（见 readme.md）：

解析 JSON，生成数据模板的结构数组；
读取静态文件（dt_gateway_*），写入固定操作函数。

网关不要求用户手工实现操作函数（子设备数据由网关统一代理），因此比 BLE 路径少一步用户介入。

模板实例（template实例）

doc/腾讯连连开发文档/template实例/ 提供可直接对照学习的参考实现：

ble_qiot_template.c / ble_qiot_template.h——BLE 数据模板的 C 实现，展示脚本生成代码的最终形态与操作函数实现规范；
template.json——示例数据模板 JSON，即脚本的输入样例，可用于在无平台账号的情况下本地试跑生成脚本。

三份文件共同构成"JSON 输入 → 脚本 → C 输出"闭环的完整示例，是理解工具链行为的最佳起点。

Core Flow：从平台模板到固件接入

BLE SDK 的端到端接入流程如下（依据 readme.md 的使用方法整理）：

sequenceDiagram
    participant Dev as 开发者
    participant Cloud as 腾讯云物联网平台
    participant Script as interpret_dt_ble.py
    participant Gen as 生成产物
    participant Fw as 固件工程

    Dev->>Cloud: 登录平台，定义产品数据模板
    Cloud-->>Dev: 下载数据模板 JSON 文件
    Dev->>Script: python3 interpret_dt_ble.py &lt;your_json_file&gt;
    Script->>Gen: 生成头文件 + ble_qiot_template.c/h
    Dev->>Gen: 按数据特性实现操作函数
    Dev->>Fw: 拷贝生成文件到 data_template 目录
    Fw->>Fw: 编译烧录
    Fw->>Cloud: LLSync 协议 BLE 连接、属性上报/事件上报/动作下发

流程要点：

平台侧定义：产品属性、事件、动作先在腾讯云物联网平台定义并导出 JSON——这是唯一事实来源（single source of truth）。
脚本转换：python3 运行解释脚本，JSON 中的每个 id 被翻译为枚举、宏、结构体与函数声明。
用户实现：BLE 场景下，生成的 ble_qiot_template.c 中操作函数体需用户按数据特性填充（如属性读写对应的硬件寄存器/传感器操作）。
编译接入：生成文件放入 data_template 目录随固件编译，设备通过 LLSync 协议与平台完成数据交互。

网关接入流程与 BLE 类似，但使用 interpret_dt_gateway.py，且无需用户实现操作函数，生成文件直接拷贝进 SDK 编译即可。

Usage Examples

示例一：BLE SDK 数据模板转换

BLE 接入的标准命令序列（摘自 readme.md）：

# 1. 从物联网平台下载数据模版 json 文件（平台侧操作）
# 2. 执行解释脚本生成对应的数据模版文件
python3 interpret_dt_ble.py <your_json_file>
# 3. 按照数据特性实现 ble_qiot_template.c 中的操作函数
# 4. 将生成文件拷贝到 data_template 目录编译即可

Source: readme.md

示例二：网关数据模板转换

网关接入的命令序列（摘自 readme.md）：

# 1. 从物联网平台下载数据模版 json 文件（平台侧操作）
# 2. 执行解释脚本生成对应的数据模版文件
python3 interpret_dt_gateway.py <your_json_file>
# 3. 将生成文件拷贝 SDK 编译即可

Source: readme.md

示例解读：

两个脚本的用法高度一致，差异仅在产物与后续步骤：BLE 需要用户实现操作函数，网关直接编译；
脚本要求 python3 解释器（见 readme.md），兼容性以 Python 3 为准；
<your_json_file> 应替换为从平台下载的实际模板文件路径。

Configuration Options

脚本工具的配置集中在 config/dt.conf（INI 格式，见 readme.md）。源码中可见的配置项如下：

配置项	类型	默认值	说明
`dt.conf` 文件内容	INI 配置	随仓库提供	脚本运行的配置参数（输出路径、生成选项等）

说明：dt.conf 的具体键值未在本仓库的 Markdown 文档中展开，实际键名请直接查看 config/dt.conf 文件。配置文件与脚本逻辑解耦的设计意图是：产品接入时只需调整配置，无需改动生成脚本本身。

Failure Modes、边界情况与一致性保证

依据源码文档可确认的边界与失败模式如下：

场景	风险	缓解机制
JSON 模板与固件定义不一致	属性/事件/动作的 `id`、类型、取值范围漂移，设备与平台通信异常	代码由同一 JSON 生成，从源头消除手工对齐；脚本按 LLSync 协议写入公共定义（见 readme.md）
BLE 操作函数未实现	生成的操作函数只是骨架，编译可通过但运行期功能缺失	流程中显式要求"按数据特性实现操作函数"（见 readme.md）
类型转换遗漏	枚举/整数/浮点/字符串的边界值（max/min/起始/步进/长度）未定义，固件校验逻辑失效	生成流程逐类型规定了转换规则（见 readme.md）
Python 运行环境不符	脚本无法执行	明确要求使用 `python3` 解释器（见 readme.md）
模板文件缺失/格式错误	生成中断或产出错误代码	以平台导出的 JSON 为唯一输入，示例文件 `example.json` 可用于校验脚本行为（见 readme.md）

一致性设计意图：该工具链把"终端设备与网关设备上数据定义的一致性"作为首要目标（见 readme.md）。相比手工维护两份 C 头文件，自动生成避免了跨人、跨版本、跨产品线的不一致。

性能与运维注意事项

生成阶段：代码生成是构建期/开发期行为（python3 脚本），不占用设备运行资源；生成物（宏、枚举、结构体数组）均为编译期常量，无运行期解析开销。
运行期成本：字符串 id 被转换为枚举 id（见 readme.md），固件侧匹配为整数比较而非字符串比较，对低功耗 BLE 设备的 RAM/CPU 开销友好。
固件体积：结构数组与固定操作函数会引入一定代码体积，建议在资源紧张的型号（如 AC63 系列小 Flash 版本）上裁剪未用到的数据类型定义。
版本管理：建议将生成的 C 文件与对应 JSON 模板一并纳入版本控制，保证固件版本与平台数据模板版本可追溯。

Extension Points

新增数据模板：在平台侧新增属性/事件/动作后，重新下载 JSON 并重跑脚本即可，脚本与固定代码无需改动。
扩展固定代码：若需要新的操作函数模式（例如新增一种上报策略），可修改 src/dt_fixed_content/ 下的固定代码片段（dt_ble_action、dt_ble_event、dt_ble_property、dt_ble_prototype 等），但需注意会同时影响所有产品的生成结果。
网关与 BLE 双路径：同一套 JSON 模板可分别喂给 interpret_dt_ble.py 与 interpret_dt_gateway.py，满足"BLE 直连设备"与"网关子设备"两种拓扑（见 readme.md）。
其他云平台：SDK 在 third_party_profile 下同时支持 SigMesh、涂鸦、HiLink（见 README.md），各平台的接入文档与工具链相互独立，可按需选择。