# 模拟显示器

模拟显示器用于在控制台生成、查看和验证设备可视化输出：它绑定当前设备，可读取状态、把界面操作映射到设备规格里的命令或事件，并在真实屏幕或设备端界面实现前先验证内容、交互和控制链路。

## 使用前准备

使用模拟显示器前，需要先完成以下准备：

- 已创建设备智能体，并为目标设备定义好设备规格。显示内容中的控制按钮需要对应到设备规格里的命令或事件。
- 需要展示真实状态时，设备应通过 MQTT 或 SDK 在线，并能上报状态或遥测。
- 需要验证控制按钮时，设备端应能接收命令并返回结果。
- 准备接入真实屏幕时，先确认分辨率、输入方式、渲染框架和刷新频率。

## 控制台使用和真实屏幕接入

模拟显示器有两条使用路径：

| 路径 | 适用场景 | 需要完成 |
| --- | --- | --- |
| 控制台使用 | 开发调试、演示、验证设备屏幕或控制面板效果 | 选中设备后，在对话中要求设备智能体更新模拟显示器 |
| 真实屏幕接入 | 设备本身带屏幕、触摸屏或按键界面 | 参考模拟显示器确认的结构和交互，在设备端实现渲染和输入处理 |

两条路径使用同一份设备规格。控制台只负责模拟和验证；真实屏幕需要设备端实现。

## 控制台使用

进入设备智能体工作区并选中设备，可以在对话中要求设备智能体更新模拟显示器。例如：

```text
更新模拟显示器，显示快速体验里的 Smart Thermostat 控制面板。
只使用当前设备规格里的状态字段：power、current_temperature、humidity、heating_status、cooling_status、target_temperature、hvac_mode。
只使用当前设备规格里的命令：set_power、set_target_temperature、set_hvac_mode。
界面包含当前温度、目标温度、湿度、HVAC 模式、电源状态、加热状态和制冷状态。
添加一个当前温度与目标温度对比图，以及一个湿度仪表盘。
提供电源开关、目标温度滑块和 HVAC 模式选择器，并分别绑定到对应命令。
不要添加设备规格里没有的字段或控件。
```

控制台使用时可以：

- 要求设备智能体生成状态面板、控制面板、列表面板、图表仪表盘或设备屏幕。
- 放大模拟显示器窗口，或拖动窗口位置，方便和设备状态、对话记录一起查看。
- 检查显示内容是否读取了当前设备状态，例如温度、湿度、运行模式和在线状态。
- 检查图表是否使用了设备上报的遥测或事件数据，例如当前温度与目标温度对比、湿度仪表盘或状态统计。
- 对按钮、开关、滑块或输入控件逐项操作，确认是否触发设备规格中定义的命令或事件。
- 修改提示词后重新生成，用于比较布局、文案和交互方式。

![模拟显示器](../images/docs/usage/simulated-display/zh/01-simulated-display.png)

## 真实屏幕接入

模拟显示器不会自动把内容推送到真实硬件屏幕。真实设备有屏幕时，建议按这个顺序接入：

1. 先在控制台用模拟显示器验证显示内容、状态字段和控制动作。
2. 明确真实屏幕的分辨率、输入方式、渲染框架和刷新频率。
3. 在设备端实现屏幕渲染，把状态展示和按钮动作映射到设备规格中的字段、命令和事件。
4. 如需生成设备端屏幕、按键或触摸交互代码，可以在 [SDK 接入](../device-access/sdk-generation.md) 中使用智能体适配和增强 SDK。

## 验证结果

完成控制台使用或真实屏幕接入后，至少验证这些结果：

- 模拟显示器更新的是当前选中的设备，没有串到其他设备。
- 状态、遥测和告警内容与真实设备上报一致。
- 控制按钮或输入控件触发的是设备规格中定义的命令或事件。
- 设备端能收到命令、返回执行结果，并在控制台或日志中看到对应记录。
- 真实屏幕实现不依赖控制台的运行时渲染结果。

## 注意事项

模拟显示器只绑定当前选中的设备，适合验证静态图表和低频更新面板。真实屏幕渲染和控制动作仍需要设备端实现，并通过设备规格中的命令或事件落地；视频流、高频动画和复杂交互更适合放在真实前端或设备端界面。