zzx123/xiaozhi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
xiaozhi/xiaozhi-esp32-server/docs/homeassistant-integration.md
“wangquan” 57fdf656b9 add_xiaozhi
2025-07-18 13:12:09 +08:00

9.8 KiB
Executable File
Raw Blame History

小智ESP32-开源服务端与HomeAssistant集成指南

[TOC]

简介

本文档将指导您如何将ESP32设备与HomeAssistant进行集成。

前提条件

  • 已安装并配置好HomeAssistant
  • 本次我选择的模型是：免费的ChatGLM，它支持functioncall函数调用

开始前的操作（必要）

1. 获取HA的网络网络地址信息

请访问你Home Assistant的网络地址，例如，我的HA的地址是192.168.4.7，端口则是默认的8123，则在浏览器打开

http://192.168.4.7:8123

手动查询 HA 的 IP 地址方法**（仅限小智esp32-server和HA部署在同一个网络设备[例如同一个wifi]下）**：

  1. 进入 Home Assistant（前端）。

  2. 点击左下角 设置（Settings） → 系统（System） → 网络（Network）。

  3. 滑到最底部Home Assistant 网址(Home Assistant website)区域，在本地网络(local network)中，点击眼睛按钮，可以看到当前使用的 IP 地址（如 192.168.1.10）和网络接口。点击复制连接(copy link)可以直接复制。

    image-20250504051716417

或，您已经设置了直接可以访问的Home Assistant的OAuth地址，您也可以在浏览器内直接访问

http://homeassistant.local:8123

2. 登录Home Assistant拿到开发密钥

登录HomeAssistant，点击左下角头像 -> 个人，切换安全导航栏，划到底部长期访问令牌生成api_key，并复制保存，后续的方法都需要使用这个api key且仅出现一次（小tips: 您可以保存生成的二维码图像，后续可以扫描二维码再此提取api key）。

方法1：小智社区共建的HA调用功能

功能描述

  • 如您后续需要增加新的设备，该方法需要手动重启xiaozhi-esp32-server服务端以此更新设备信息**（重要**）。

  • 需要您确保已经在HomeAssistant中集成Xiaomi Home，并将米家的设备导入进HomeAssistant。

  • 需要您确保xiaozhi-esp32-server智控台能正常使用。

  • 我的xiaozhi-esp32-server智控台和HomeAssistant部署在同一台机器的另一个端口，版本是0.3.10

    http://192.168.4.7:8002

配置步骤

1. 登录HomeAssistant整理需要控制的设备清单

登录HomeAssistant，点击左下角的设置，然后进入设备与服务，再点击顶部的实体。

然后在实体中搜索你相关控制的开关，结果出来后，在列表中，点击其中一个结果，这是会出现一个开关的界面。

在开关的界面，我们尝试点击开关，看看是开发会随着我们的点击开/关。如果能操作，说明是正常联网的。

接着在开关面板找到设置按钮，点击后，可以查看这个开关的实体标识符。

我们打开一个记事本，按照这样格式整理一条数据：

位置+英文逗号+设备名称+英文逗号+实体标识符+英文分号

例如，我在公司，我有一个玩具灯，他的标识符是switch.cuco_cn_460494544_cp1_on_p_2_1，那么就这个写这一条数据

公司,玩具灯,switch.cuco_cn_460494544_cp1_on_p_2_1;

当然最后我可能要操作两个灯，我的最终的结果是：

公司,玩具灯,switch.cuco_cn_460494544_cp1_on_p_2_1;
公司,台灯,switch.iot_cn_831898993_socn1_on_p_2_1;

这段字符，我们称为“设备清单字符”需要保存好，等一下有用。

2. 登录智控台

image-20250504051716417

使用管理员账号，登录智控台。在智能体管理，找到你的智能体，再点击配置角色。

将意图识别设置成函数调用或LLM意图识别。这时你会看到右侧有一个编辑功能。点击编辑功能按钮，会弹出功能管理的框。

在功能管理的框里，你需要勾选HomeAssistant设备状态查询和HomeAssistant设备状态修改。

勾选后，在已选功能点击HomeAssistant设备状态查询，然后在参数配置里配置你的HomeAssistant地址、密钥、设备清单字符。

编辑好后，点击保存配置，这时功能管理的框会隐藏，这时你再点击保存智能体配置。

保存成功后，即可唤醒设备操作。

3. 唤醒设别进行控制

尝试和esp32说，“打开XXX灯”

方法2：小智将Home Assistant的语音助手作为LLM工具

功能描述

  • 该方法有一个比较严重的缺点——该方法无法使用小智开源生态的function_call插件功能的能力，因为使用Home Assistant作为小智的LLM工具会将意图识别能力转让给Home Assistant。但是这个方法是能体验到原生的Home Assistant操作功能，且小智的聊天能力不变。如实在介意可以使用同样是Home Assistant支持的[方法3](##方法3：使用Home Assistant的MCP服务（推荐）)，能够最大程度体验到Home Assistant的功能。

配置步骤：

1. 配置Home Assistant的大模型语音助手。

需要您提前配置好Home Assistant的语音助手或大模型工具。

2. 获取Home Assistant的语言助手的Agent ID.

  1. 进入Home Assistant页面内。左侧点击开发者助手。
  2. 在打开的开发者助手内，点击动作选项卡（如图示操作1），在页面内的选项栏动作中，找到或输入conversation.process（对话-处理）并选择对话（conversation）: 处理（如图示操作2）。

image-20250504043539343

  1. 在页面内勾选代理(agent)选项，在变成常亮的对话代理(conversation agent)内选择您步骤一配置好的语音助手名称，如图示，我这边配置好的是ZhipuAi并选择。

image-20250504043854760

  1. 选中后，点击表单左下方的进入YAML模式。

image-20250504043951126

  1. 复制其中的agent-id的值，例如图示中我的是01JP2DYMBDF7F4ZA2DMCF2AGX2(仅供参考)。

image-20250504044046466

  1. 切换到小智开源服务端xiaozhi-esp32-server的config.yaml文件内，在LLM配置中，找到Home Assistant，设置您的Home Assistant的网络地址，Api key和刚刚查询到的agent_id。
  2. 修改config.yaml文件内的selected_module属性的LLM为HomeAssistant，Intent为nointent。
  3. 重启小智开源服务端xiaozhi-esp32-server即可正常使用。

方法3：使用Home Assistant的MCP服务（推荐）

功能描述

  • 需要您提前在Home Assistant内集成并安装好HA集成——Model Context Protocol Server。

  • 这个方法与方法2都是HA官方提供的解决方法，与方法2不同的是，您可以正常使用小智开源服务端xiaozhi-esp32-server的开源共建的插件，同时允许您随意使用任何一个支持function_call功能的LLM大模型。

配置步骤

1. 安装Home Assistant的MCP服务集成。

集成官方网址——Model Context Protocol Server。。

或跟随以下手动操作。

2. 配置小智开源服务端MCP配置信息

进入data目录，找到.mcp_server_settings.json文件。

如果你的data目录下没有.mcp_server_settings.json文件，

  • 请把在xiaozhi-server文件夹根目录的mcp_server_settings.json文件复制到data目录下，并重命名为.mcp_server_settings.json
  • 或下载这个文件，下载到data目录下，并重命名为.mcp_server_settings.json

修改"mcpServers"里的这部分的内容：

"Home Assistant": {
      "command": "mcp-proxy",
      "args": [
        "http://YOUR_HA_HOST/mcp_server/sse"
      ],
      "env": {
        "API_ACCESS_TOKEN": "YOUR_API_ACCESS_TOKEN"
      }
},

注意：

  1. 替换配置：
    • 替换args内的YOUR_HA_HOST为您的HA服务地址，如果你的服务地址已经包含了https/http字样（例如http://192.168.1.101:8123)，则只需要填入192.168.1.101:8123即可。
    • 将env内API_ACCESS_TOKEN的YOUR_API_ACCESS_TOKEN替换成您之前获取到的开发密钥api key。
  2. 如果你添加配置是在"mcpServers"的括号内后续没有新的mcpServers的配置时，需要把最后的逗号,移除，否则可能会解析失败。

最后效果参考以下（参考如下）：

 "mcpServers": {
    "Home Assistant": {
      "command": "mcp-proxy",
      "args": [
        "http://192.168.1.101:8123/mcp_server/sse"
      ],
      "env": {
        "API_ACCESS_TOKEN": "abcd.efghi.jkl"
      }
    }
  }

3. 配置小智开源服务端的系统配置

  1. 选择任意一款支持function_call的LLM大模型作为小智的LLM聊天助手（但不要选择Home Assistant作为LLM工具），本次我选择的模型是：免费的ChatGLM，它支持functioncall函数调用，但部分时候调用不太稳定，如果像追求稳定建议把LLM设置成：DoubaoLLM，使用的具体model_name是：doubao-1-5-pro-32k-250115。

  2. 切换到小智开源服务端xiaozhi-esp32-server的config.yaml文件内，设置您的LLM大模型配置，并且将selected_module配置的Intent调整为function_call。

  3. 重启小智开源服务端xiaozhi-esp32-server即可正常使用。