控制 Home Assistant - 智能家居HA

INFO

小智是一款实时语音交互助手，Home Assistant（HA）是一个开源的智能家居平台，支持接入米家、海尔、美的、格力、海信等上千品牌设备。小智Pro 通过 HA 的 REST API 连接你自建的 HA 实例，让你用语音指挥小智控制全屋智能设备，也能在控制台手动调试每个实体。

WARNING

连接 HA 功能限 SVIP 会员使用。

1. 基本原理

小智Pro 服务端作为 HA 的客户端，通过 HA 的 REST API 与你自建的 HA 实例通信：

小智设备 ──(语音)──> 小智Pro服务端 ──(REST API)──> Home Assistant
                                                        │
小智设备 <──(播报)── 小智Pro服务端 <──(设备状态/服务)──────┘

1.1 连接与探测

1. 用户在小智Pro控制台填写 HA 的 base_url 和长期访问令牌
2. 点击连接，服务端创建向 HA 发起探测
3. 探测会拉取 HA 的全部 states（实体状态）和 services（服务定义）
4. 服务端将实体分为两类：
   • 可控设备（controls）：带有可调用服务（如 turn_on/turn_off）的实体，按 domain 分类（light/switch/climate/camera 等）
   • 传感器（sensors）：只读实体，如温度、湿度、电量、门窗状态等
5. 实体按"设备"自动分组，并展示设备型号、厂商信息

1.2 服务调用

控制设备本质是调用 HA 的服务：

操作	domain	service	示例 entity_id
开灯/关灯	light	turn_on/turn_off	light.living_room
开关切换	switch	toggle	switch.socket
设空调温度	climate	set_temperature	climate.bedroom
摄像头截图	camera	snapshot	camera.front_door

服务调用支持传入额外参数（JSON），如设置亮度、色温、目标温度等。

1.3 关键设计

特性	说明
一用户一配置	每个账号只能保存一份 HA 配置
实时探测	连接/刷新时实时拉取设备状态，不缓存过期数据
服务自描述	每个可控制实体自带可用服务及参数定义，前端动态渲染表单
乐观更新	HA 不返回响应时按服务名（turn_on/off/toggle）推断设备状态
错误日志	一键拉取 HA 服务端错误日志，便于排查集成与服务调用异常
配置变更断连	修改配置后自动断开旧连接，下次连接使用新配置

2. 操作指南

2.0 前置准备

在配置小智Pro 之前，请先完成 HA 的搭建并创建长期访问令牌：

1. HA 公网可访问（如 http://x.x.x.x:8123 或 https://ha.yourdomain.com）
2. 已在 HA 中接入你要控制的设备（米家/海尔/美的/格力/海信等）
3. 已创建长期访问令牌：
   • 登录 HA → 左下角点击头像 → 安全 → 拉到底部"长期访问令牌" → 创建令牌 → 复制保存

TIP

令牌只会在创建时显示一次，请妥善保存。

2.1 配置 HA 连接

进入小智Pro 控制台，点击左侧菜单 设备端MCP → 智能家居HA：

1. 首次进入页面，点击 配置并连接 按钮
2. 在弹出的对话框中填写：
   • HA 地址：HA 的访问地址，如 http://x.x.x.x:8123 或 https://ha.yourdomain.com
   • 长期访问令牌：在 HA 中创建的长期访问令牌
3. 点击 保存

⚠️ 小智Pro 服务端需能访问到该地址。若 HA 部署在内网，请确保 HA 已通过内网穿透/反代暴露到公网。

2.2 连接 HA 并探测设备

保存配置后会自动尝试连接。也可点击页面顶部的 连接 HA 按钮手动连接：

• 连接成功：提示"HA 连接成功"，页面进入设备列表视图
• 已连接但探测失败：提示"HA 已连接但探测失败，请检查配置"，通常是令牌权限或网络问题
• 连接失败：检查地址是否可达、令牌是否有效

连接成功后，页面顶部会显示：

• 状态标签（绿色=在线 / 红色=离线 / 灰色=未连接）
• HA 地址
• 令牌（脱敏显示，仅显示首尾各 4 位）
• 可控制设备数 / 传感器数
• 探测时间与错误信息（如有）

2.3 查看与控制设备（可控制设备 Tab）

切换到 可控制设备 Tab：

左侧 - 设备列表

• 按"设备"自动分组（折叠面板），每组显示设备名、设备数量、厂商与型号
• 展开分组可看到该设备下的所有可控制实体
• 每个实体显示：domain 标签、友好名称、entity_id、当前状态（on/off 等）
• 点击任一实体，右侧加载该实体的服务调用面板

右侧 - 服务调用面板

1. 选择服务：下拉框展示该实体支持的所有服务（如 turn_on、turn_off、toggle、set_temperature）
2. 参数说明：选中服务后，自动展示该服务所需的字段定义（必填项、示例值、取值范围与单位）
3. 额外参数 (JSON)：填入服务所需的额外参数，格式为 JSON，例如：
   • 设置亮度：{"brightness": 128}
   • 设置色温：{"color_temp": 300}
   • 设置空调温度：{"temperature": 26}
   • 无额外参数时填 {}
4. 点击 调用服务，下方展示调用结果

调用结果说明

返回类型	含义	提示级别
非空数组	HA 返回受影响实体的真实状态，调用成功	成功
空数组 []	服务已调用但无状态变化，设备可能离线/未响应	警告
无返回（null）	新版 HA 默认不返回响应，按服务名乐观推断状态	成功

调用成功后，左侧设备列表中该实体的状态会同步更新。

2.4 查看传感器数据（传感器 Tab）

切换到 传感器 Tab：

• 同样按"设备"自动分组
• 每个传感器卡片显示：友好名称、entity_id、当前数值（大字号）、单位、设备类型
• 数值自动格式化（最多保留一位小数）
• 时间戳类状态会自动格式化为可读时间

传感器为只读实体，不支持服务调用，仅用于查看温湿度、电量、门窗状态等数据。

2.5 刷新设备

当你在 HA 中新增/删除设备，或设备状态长时间未更新时，点击 刷新 按钮：

• 服务端重新向 HA 拉取全部 states 和 services
• 刷新完成后页面自动同步最新设备列表与状态

2.6 查看错误日志

遇到服务调用失败、设备无响应、集成异常等问题时，点击 错误日志 按钮：

• 抽屉中展示 HA 服务端的错误日志（纯文本）
• 可点击 刷新 按钮拉取最新日志
• 日志按 HA 原始格式输出，便于定位集成加载失败、实体不可用等问题

2.7 修改与删除配置

修改配置

点击 修改配置 按钮，可更新 HA 地址或令牌：

• 保存后服务端会自动断开旧连接
• 下次点击 连接 HA 时使用新配置重新连接

删除配置

点击红色 删除 按钮（需二次确认）：

• 清除当前账号的 HA 配置
• 自动断开 HA 连接
• 删除后页面回到初始"配置并连接"状态

2.8 断开连接

点击 断开（需二次确认）：

• 仅断开当前 HA 连接，不会删除配置
• 断开后可随时点击 连接 HA 重新连接，无需重新填写地址和令牌

2.9 通过设备语音操控

WARNING

设备固件版本需为 v2.2.6.2 以上：https://github.com/hougeai/xiaozhiPro/releases

配置好 HA 连接后，你可以直接对小智发出语音指令，控制接入 HA 的全屋智能设备：

- '把客厅的灯打开'
- '关掉卧室的空调'
- '把客厅空调温度调到 26 度'
- '打开客厅的窗帘'

小智会将指令转发给 HA 执行对应服务，并将执行结果通过语音播报反馈给你。

提示：语音操控覆盖所有已接入 HA 的可控制设备。设备名称以 HA 中的友好名称为准，建议在 HA 中为设备设置易于识别的名称。

3. 常见问题

连接 HA 失败？

• 检查 HA 地址格式是否正确（必须以 http:// 或 https:// 开头）
• 确认 HA 服务正在运行且可访问
• 确认长期访问令牌有效（未过期、未删除）
• 确认公网能访问到该地址（内网穿透配置正确）
• 点击 错误日志 查看详细错误

提示"已连接但探测失败"？

• 通常是令牌权限不足或网络不稳定导致探测中断
• 检查令牌是否为管理员账号创建
• 点击 刷新设备 重试
• 查看 错误日志 排查具体实体加载失败原因

服务调用返回空响应？

• 设备可能离线或未响应（如 Wi-Fi 断开、设备休眠）
• 服务已下发但设备状态未变化
• 建议点击 刷新设备 确认设备真实状态

设备列表是空的？

• 确认 HA 中已接入设备（设置 → 设备与服务）
• 点击 刷新设备 重新探测
• 部分实体可能被识别为传感器而非可控制设备，请切换到 传感器 Tab 查看

修改了 HA 里的设备，控制台没更新？

• 控制台不会自动同步 HA 的变更，需手动点击 刷新设备
• 新增设备需在 HA 中完成集成配置后才会出现

语音控制没反应？

• 确认控制台显示"在线"状态
• 确认设备固件版本为 v2.2.6.2 以上
• 查看 错误日志 确认 HA 端无异常