# SDK 接入

SDK 接入用于把真实硬件接入设备智能体。设备端连接 MQTT 后，可以按设备规格上报状态和事件、响应命令，并作为真实设备出现在设备列表中。文档和代码包中出现的 `namespace` 表示当前运行空间，默认值为 `default`。

## 选择接入方式

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

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

前两种入口都会生成设备端代码包；已有设备入口不会生成代码，而是给出接入参数和消息示例。

![选择 SDK 接入方式](../images/docs/device-access/sdk-generation/zh/01-connect-device.png)

## SDK 工程

SDK 工程是一套可运行的设备端代码。它已经接好 MQTT、设备身份、命令响应、状态上报和事件上报，真实硬件逻辑在设备业务入口中补充。

不同语言的文件名会略有差异，但整体结构相同：

```text
SDK 工程
├── .env.example        连接配置：MQTT、namespace、productId、deviceId
├── device-spec.json    当前设备规格：命令、遥测、事件
├── README.md           安装、配置、运行和开发说明
├── src/
│   ├── main.*          启动入口：加载配置并连接 MQTT
│   └── device.*        业务逻辑入口：处理命令、更新状态、上报事件
├── 语音代码             通过 /ws/voice 接入设备端语音对话
├── 视觉代码             上传图像并发起拍照识别
└── SDK 运行层           订阅命令、发送响应、上报在线状态、遥测和事件
```

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

## 语音和视觉代码

SDK 工程除了 MQTT 接入，也包含可选的语音和视觉代码。它们用于把真实设备上的麦克风、扬声器、摄像头或图像来源接入设备智能体。

- **语音**：设备端通过 `/ws/voice` 建立 WebSocket 连接，发送 16 kHz 单声道 Int16LE PCM 音频，并接收识别文本、智能体回复和 TTS 音频。
- **视觉**：用于拍照识别类命令。设备端获取一张图片，上传到 `/api/vision/frames`，再把返回的 `visionRefs` 带到 `/api/chat` 获取识别结果。

`.env.example` 中的 `VOICE_CHAT_HOST` 是语音和视觉接口的统一主机入口。语音、视觉不会替代 MQTT 设备控制；MQTT 仍然负责命令、状态、遥测和事件。

| 语言 | 语音代码 | 视觉代码 |
| --- | --- | --- |
| C | `voice_client.h`、`voice_client.c`、`examples/voice_chat.c` | `vision_client.h`、`vision_client.c` |
| Python | `src/voice_client.py` | `src/main.py` 中的拍照识别命令处理 |
| Node.js | `VoiceClient` | `VisionClient` 和 `captureLocalVisionImage()` |

## 下载 SDK 工程

创建 SDK 工程时需要确认：

- **开发语言**：当前控制台支持 C、Node.js 和 Python。
- **设备名称**：用于在控制台中识别设备，可以后续调整。
- **设备 ID**：真实设备的唯一标识，同一个设备智能体下不要重复。

下载后先按 README 启动，确认设备能上线；再把默认逻辑替换为真实传感器、执行器或业务服务调用。代码包会保留 `device-spec.json`、`README.md` 和 `.env.example`。Node.js 工程还包含 `AGENTS.md`、`CLAUDE.md` 和设备实现说明，可用于 Claude Code、Cursor 或 Codex 继续开发。

常见运行步骤是：

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

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

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

- [C SDK](./sdk-generation/c.md)
- [Python SDK](./sdk-generation/python.md)
- [Node.js SDK](./sdk-generation/nodejs.md)

## 使用智能体适配和增强 SDK

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

你可以补充这些信息：

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

![填写设备端逻辑](../images/docs/device-access/sdk-generation/zh/03-agent-enhanced-input.png)

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

![生成增强后的 SDK 代码包](../images/docs/device-access/sdk-generation/zh/04-agent-enhanced-result.png)

## 接入已有设备

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

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

## 运行并验证

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

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

![真实设备接入后的设备状态](../images/docs/device-access/sdk-generation/zh/02-device-status.png)

如果设备没有出现，先检查设备端是否已连接 MQTT、`productId` 和 `deviceId` 是否正确、是否已经上报状态或遥测。更多配置项见 [配置](../operate-reference/configuration.md)。

## 下一步

- 阅读 [MQTT 接入](./mqtt.md)，了解已有设备如何直接适配主题和消息体。
- 阅读 [语音交互](../usage/voice.md)，了解设备端语音链路的接入方式。
- 阅读 [摄像头与视觉识别](../usage/multimedia.md)，把摄像头和图像输入接入设备端。
- 阅读 [模拟显示器](../usage/simulated-display.md)，了解设备可视化输出的验证方式。