huanghai
/
DuoDuoProject
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '2e80dac1bd'
${ noResults }
DuoDuoProject/xiaozhi-esp32-server-0.7.1/docs/homeassistant-integration.md

9.8 KiB
Raw Blame History Escape

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

小智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即可正常使用。