SDK 接入

SDK 接入用于把真实硬件接入设备智能体。设备端连接 MQTT 后，可以按设备规格上报状态和事件、响应命令，并作为真实设备出现在设备列表中。

选择接入方式

在设备智能体工作区中点击 接入设备，控制台会提供三种入口：

方式	适合场景
SDK 工程	需要一个可运行的设备端工程，再补充硬件逻辑
智能体适配和增强 SDK	基于 SDK 工程生成设备端业务逻辑，下载后继续微调或直接运行
已有设备	已经有固件、网关或后端服务，只需要按 MQTT 主题和消息体约定适配

SDK 工程

SDK 工程是一套可运行的设备端代码，已经包含 MQTT 连接、设备身份、命令响应、状态上报和事件上报。生成包中的公共文件包括：

文件	用途
.env.example	MQTT 和设备身份等连接配置
device-spec.json	当前设备的命令、属性和事件定义
README.md	安装、配置、运行和开发步骤

不同语言的主要修改位置和运行方式如下：

语言	主要修改文件	运行方式与适用环境
C	src/main.c	使用 CMake 编译，适合网关和嵌入式 Linux
Python	src/main.py	使用 uv 运行，适合网关、脚本和现有 Python 服务
Node.js	src/device.ts	使用 npm 运行，适合 TypeScript、JavaScript 和 Node.js 服务

device-spec.json 是设备端实现依据。命令名、参数名、属性字段和事件字段都应与它保持一致。

生成包也提供可选的语音和视觉接入代码，用于连接设备上的麦克风、扬声器和摄像头；具体使用方式见 语音交互 和 摄像头与视觉识别。

下载 SDK 工程

创建 SDK 工程时需要确认：

• 开发语言：当前控制台支持 C、Node.js 和 Python。
• 设备名称：可选，当前不会写入生成的 SDK 工程。
• 设备 ID：真实设备的唯一标识，在同一 Device Agent 部署中不能重复。

下载后先按 README 启动，确认设备能上线；再把默认逻辑替换为真实传感器、执行器或业务服务调用。

常见运行步骤是：

1. 解压代码包。
2. 根据 .env.example 配置连接信息。
3. 安装依赖或编译工程。
4. 启动设备端程序。

设备启动并完成首次状态上报后，会自动出现在当前设备智能体的设备列表中。

不同语言的 SDK 使用方式见：

• C SDK
• Python SDK
• Node.js SDK

使用智能体适配和增强 SDK

智能体适配和增强 SDK 适合设备端业务逻辑还没有写好的场景。它会先生成 SDK 工程，再基于补充描述生成状态上报、命令处理、事件触发和设备端流程。

你可以补充这些信息：

• 设备端逻辑，例如如何读取温湿度、如何控制继电器、如何触发告警事件。
• 业务要求，例如上报频率、阈值事件、命令执行后的状态更新方式。
• 可选的硬件信息，例如芯片、系统、驱动文档链接、接口文档或硬件协议文件。

提交后，设备智能体会在对话中返回可下载的代码包。生成结果不符合预期时，可以继续要求调整，例如补充驱动调用、修改事件触发条件，或简化状态上报逻辑。

接入已有设备

如果设备固件、网关或后端服务已经存在，可以选择 已有设备。这个入口不会生成 SDK 代码，而是给出 MQTT 服务地址、设备身份、主题和消息体示例，方便已有系统直接适配。

已有设备接入的核心是按 MQTT 约定订阅命令、响应命令、上报状态和事件。完整说明见 MQTT 接入。

运行并验证

设备端程序启动后，回到设备智能体工作区确认：

1. 设备列表中出现新的真实设备。
2. 设备状态为在线。
3. 当前数据能看到设备上报的属性字段。
4. 通过对话下发控制命令后，设备端能收到命令并返回结果。
5. 如果设备会上报事件，可以在最近上报事件中看到事件记录。

如果设备没有出现，先检查设备端是否已连接 MQTT、productId 和 deviceId 是否正确、是否已经上报状态或遥测。配置项见 配置。