XIAO ESP32C3 通过 ESPHome 服务访问 Home Assistant

本文将指导您在自己的 Home Assistant 环境中安装 ESPHome 服务。通过使用 XIAO ESP32C3 的 WiFi 功能，您将能够以非常流畅的方式将 XIAO 连接到 Home Assistant，作为家庭终端的一部分。

此外，我们将结合最受欢迎的 24GHz mmWave 人体静态存在模块 Lite 构建一个具有人体存在检测功能的 Home Assistant。

入门指南

tip

截至 2023 年 7 月 31 日，之前会导致雷达完全失效的问题现已修复，因此请更新本教程中的库文件和配置器，以确保正常工作。

如果您想完整地学习本教程，您需要准备以下物品。

XIAO ESP32C3	24GHz mmWave 人体静态 存在模块 Lite
立即获取 🖱️	立即获取 🖱️

本项目的最终目标是在 Home Assistant 中部署 24GHz mmWave 人体静态存在模块 Lite。

我们为 24GHz mmWave 人体静态存在模块 Lite 编写了完整的配置文件和库，以便您在本项目中快速将传感器部署到 Home Assistant。

本教程的内容将大致经过以下步骤。

1. 选择您的 Home Assistant 环境
2. 在 Home Assistant 中安装和配置 ESPHome
3. 配置 XIAO ESP32C3 和 ESPHome 连接
4. 配置 Home Assistant 面板

当然，如果您对 XIAO ESP32C3 如何在 Home Assistant 中使用 Grove 感兴趣，您可以直接阅读这一章节。

• 使用 XIAO ESP32C3 将 Grove 连接到 Home Assistant

选择您的 Home Assistant 环境

在本教程中，我们不会详细介绍如何安装 Home Assistant 环境，我们假设您已经有一个正常工作的 Home Assistant 设备。

如果您希望学习如何安装 Home Assistant，那么您可以参考官方教程。我们强烈建议您使用 x86 设备安装 Home Assistant，因为这是安装带有 Supervised 的 Home Assistant 最用户友好的方式。

根据上表，安装 Home Assistant OS 和 Home Assistant Supervised 是最合适的，这将为您省去很多麻烦。如果您在 OpenWRT 上使用 Docker 运行 Home Assistant（例如使用 LinkStar H68K），请不要担心，我们也会为您提供如何操作的详细参考。

我们还为一些 Seeed Studio 产品编写了如何安装 Home Assistant 的教程，请参考它们。

• 在 ODYSSEY-X86 上开始使用 Home Assistant
• 在 reTerminal 上开始使用 Home Assistant
• 在 LinkStar H68K/reRouter CM4 上开始使用 Home Assistant

在 Home Assistant 中安装 ESPHome

步骤 1. 安装 ESPHome

• 场景 1：在 Home Assistant OS 下安装 ESPHome（带有 Add-on Store）

如果您安装了 Home Assistant OS，它有一个 Add-on Store，这使得安装 ESPHome 变得更加容易。

在 Add-on Store 中，您可以搜索并安装 ESPHome。

• 场景 2：在 OpenWRT Docker/Docker 下的 Home Assistant 中安装 ESPHome（没有 Add-on Store）

由于我们安装的是 Home Assistant Container，我们无法简单地通过 Add-on Store 下载 ESPHome 服务，因此需要一个折中的方法。

我们需要下载 ESPHome 镜像。

esphome/esphome:latest

在创建容器的页面中，我们需要进行一些简单的设置。

• Container Name：您的容器名称
• Docker Image：选择刚刚下载的 esphome 镜像
• Network：选择 host 模式
• Environment Variables(-e)：您的环境变量

填写完上述内容后，保存并应用。您将看到容器已经创建。您还需要启动它。

为了实现与在 Home Assistant 中下载 ESPHome 相同的效果，我们需要修改 Home Assistant 下的配置文件。

进入 Home Assistant 容器。

我们进入 Home Assistant 中的终端。

在终端中输入以下命令。

vi configuration.yaml

在 configuration.yaml 文件末尾添加以下内容。

# Example configuration.yaml entry
panel_iframe:
  esphome:
    title: "ESPHome"
    url: "http://192.168.100.1:6052"
    icon: mdi:chip

通过输入以下命令退出 docker 容器

在 Home Assistant 容器 shell 中输入 exit。完成后，我们重启 Home Assistant 容器。

创建一个新的浏览器页面，输入地址 http://homeassistant:8123/ 并输入您的 Home Assistant 账户，您将看到 ESPHome 出现在左侧工具栏中。

配置 XIAO ESP32C3 和 ESPHome 连接

步骤 2. 硬件准备

我们教程的目标是能够在 Home Assistant 仪表板中看到 24GHz 毫米波人体静态存在模块 Lite 的数据信息。

通过主板将设备连接到计算机。接线图如下表所示。

XIAO ESP32C3		24GHz 毫米波人体静态 存在模块 Lite
5V	-->	5V
GND	-->	GND
D2	-->	RX
D3	-->	TX

步骤 3. 保持 XIAO ESP32C3 和 Home Assistant 在同一局域网中

我确信您的 Home Assistant 已经完成了接入网络的工作，例如通过网线连接到您的设备。然后您需要做的就是简单地打开一个本地网络（例如 WiFi），以便 XIAO ESP32C3 也可以连接到这个网络。

下面我将以 LinkStar H68K 为例。我的目标是让 XIAO 连接到 LinkStar H68K 的热点。

在 OpenWRT 的 Network 选项卡中，选择 Wireless --> ADD。

在 Device Configuration 中的 Transmit Power，选择 auto。

对于 Interface Configuration 设置，请按照以下说明填写。

• General Setup
  • Mode: 取决于 LinkStar 如何接入互联网。如果您使用有线连接，则选择 Client，如果您连接到 WiFi，则选择 Access Point。
  • ESSID: 输入您的 WiFi 名称，请尽量不要有空格或特殊字符。
  • Network: 勾选 lan。

• Wireless Security
  • Encryption: WPA2-PSK
  • Key: 输入您希望设置的 WiFi 密码。

填写完上述信息后，点击右下角的 Save and Apply，等待片刻让 LinkStar 开启热点。

当没有设备连接到此热点时，它将显示为无信号。

综合考虑，让我们回到 Home Assistant 页面。

点击 NEW DEVICE。然后点击 Continue。

在新弹出的窗口中，请输入您希望设置的应用程序名称，以及您在 LinkStar 中设置的热点名称和密码（或您自己的 WiFi）。确保 XIAO ESP32C3 和 Home Assistant 在同一局域网中。

然后点击 Next。

在设备类型中，请选择 ESP32-C3。

然后点击 Next。

点击 Encryption key 并将其保存在安全位置，我们将在后续步骤中使用此密钥。

然后点击 SKIP。

步骤 4. 更改 XIAO ESP32C3 配置 yaml 文件

然后，我们点击刚刚创建的设备选项卡，左下角有 EDIT 按钮。

请注意，我们需要对这个 yaml 文件进行更改。我们将要修改的内容分为两个主要部分，对应下图中的一和二。

• 在内容的 ① 中，除了您已配置的设备名称外，请不要更改，其余内容请参考以下代码。

css
# 第1部分：
substitutions:
  name: "xiao-esp32c3"
  friendly_name: "XIAO ESP32C3"

esphome:
  name: "${name}"
  friendly_name: "${friendly_name}"
  name_add_mac_suffix: true
  project:
    name: "seeedstudio.mmwave_kit"
    version: "2.0"
  platformio_options:
    board_build.flash_mode: dio
    board_build.mcu: esp32c3

external_components:
  - source: github://limengdu/mmwave-kit-external-components@main
    refresh: 0s

esp32:
  board: esp32-c3-devkitm-1
  variant: esp32c3
  framework:
    type: esp-idf

# 启用日志记录
logger:
  hardware_uart: USB_SERIAL_JTAG
  level: DEBUG

• 在内容的 ② 中，在 captive_portal: 后复制以下代码。

点击此处预览完整代码

# 设置蓝牙 LE（仅限 ESP32）以允许用户
# 向设备提供 wifi 凭据。
esp32_improv:
  authorizer: none

# 设置通过串口客户端进行 Wi-Fi 配置的 improv。
# 如果您的设备有 USB 端口，用户可以在首次获得设备时添加凭据，这很方便。
# improv_serial: # 注释掉，直到 improv 在 idf 上与 usb-jtag 兼容

uart:
  id: uart_bus
  baud_rate: 115200
  rx_pin: 4
  tx_pin: 5
  parity: NONE
  stop_bits: 1

seeed_mr24hpc1:
  id: my_seeed_mr24hpc1

text_sensor:
  - platform: seeed_mr24hpc1
    heart_beat:
      name: "心跳"
    product_model:
      name: "产品型号"
    product_id:
      name: "产品 ID"
    hardware_model:
      name: "硬件型号"
    hardware_version:
      name: "硬件版本"
    keep_away:
      name: "接近度主动报告"
    motion_status:
      name: "运动信息"
    custom_mode_end:
      name: "自定义模式状态"

binary_sensor:
  - platform: seeed_mr24hpc1
    has_target:
      name: "存在信息"

sensor:
  - platform: seeed_mr24hpc1
    custom_presence_of_detection:
      name: "静态距离"
    movement_signs:
      name: "身体运动参数"
    custom_motion_distance:
      name: "运动距离"
    custom_spatial_static_value:
      name: "存在能量"
    custom_spatial_motion_value:
      name: "运动能量"
    custom_motion_speed:
      name: "运动速度"
    custom_mode_num:
      name: "当前自定义模式"

switch:
  - platform: seeed_mr24hpc1
    underlying_open_function:
      name: 底层开放功能信息输出开关

button:
  - platform: seeed_mr24hpc1
    restart:
      name: "模块重启"
    custom_set_end:
      name: "自定义模式设置结束"

select:
  - platform: seeed_mr24hpc1
    scene_mode:
      name: "场景"
    unman_time:
      name: "进入无人状态时间（标准功能）"
    existence_boundary:
      name: "存在边界"
    motion_boundary:
      name: "运动边界"

number:
  - platform: seeed_mr24hpc1
    sensitivity:
      name: "灵敏度"
    custom_mode:
      name: "自定义模式"
    existence_threshold:
      name: "存在能量阈值"
    motion_threshold:
      name: "运动能量阈值"
    motion_trigger:
      name: "运动触发时间"
    motion_to_rest:
      name: "运动到静止时间"
    custom_unman_time:
      name: "进入无人状态时间（底层开放功能）"

然后，请点击右上角的保存按钮。

步骤 5. 将固件上传到 XIAO ESP32C3

• 方法 1：直接编译并上传

如果您使用的是 x86 设备并且可以在设备端口上看到 XIAO，那么您可以编译程序并将其上传到 XIAO。

将 XIAO 连接到您的设备。

点击设备栏右下角的三个点，选择安装。

点击插入运行 ESPHome 仪表板的计算机。

选择已连接的端口。

现在它将下载所有必要的开发板包并将 ESPHome 固件刷入 XIAO ESP32C3。如果刷写成功，您将看到以下输出。

如果将 XIAO 连接到设备后无法找到端口，那么您可以尝试使用第二种方法。

• 方法 2：使用主机上传编译的固件

像 LinkStar H68K 这样的软路由不支持识别外部 MCU 设备，我们需要先下载编译的固件，然后通过另一台 PC 上传固件。

点击右上角的安装按钮。然后选择最后一项手动下载。

选择现代格式。

然后需要很长时间来下载和编译，请耐心等待。一切准备就绪后，固件将自动下载到您的计算机。

要将固件上传到 XIAO ESP32C3，这里有几个选项，我们展示 2 种方法：

• 选项 1：使用 ESPhome Web 工具 上传。

确保您已安装正确的驱动程序。以下是 ESP 设备中常用芯片的驱动程序。

1. CP2102 驱动程序：Windows 和 Mac

2. CH342、CH343、CH9102 驱动程序：Windows，Mac

3. CH340、CH341 驱动程序：Windows，Mac

使用 Chrome 或 Edge 网络浏览器打开 ESPhome Web 工具。

点击连接。

在弹出窗口中选择 XIAO ESP32 串行端口。

点击安装，然后选择从上述步骤下载的 .bin 文件。

• 选项 2：使用 esphome-flasher 工具。

如果在安装驱动程序和更换浏览器后仍无法使用方法一上传固件，那么您可以尝试使用方法二。具体的安装方法和说明请参考官方教程。

tip

如果您希望观察 XIAO ESP32C3 的日志消息，您也可以通过此软件的查看日志按钮来查看。

上传完成后，您可以断开 XIAO ESP32C3 与 PC 的连接（除非您需要查看日志），只需单独为 XIAO 供电即可。

如果一切顺利，XIAO ESP32C3 将搜索并连接到您为其设置的 WiFi。

就像我一样，我使用 LinkStar H68K 的网络。您可以在网络选项中找到它，并查看 LinkStar H68K 分配给它的 IP 地址。

通常，此时在 Home Assistant 中，设备的状态也会从离线变为在线。

配置 Home Assistant 面板

步骤 6. 连接到 XIAO ESP32C3

如果您的局域网上没有很多 Home Assistant 设备，Home Assistant 可以自动搜索并将您的 ESP 设备添加到设备选项卡。您可以在设置中的设备和服务选项卡内看到此设备。

如果它没有自动搜索，您也可以根据其 IP 地址连接到 XIAO ESP32C3。

点击添加集成并搜索 esphome。

然后输入 XIAO ESP32C3 的 IP 地址和端口号 6053。然后点击提交。

如果输入的 IP 地址和端口号正确，那么您将看到要求您输入加密密钥，这是我们在步骤 4 中要求保存的。

然后点击提交。

此时，添加设备的步骤已成功完成。

步骤 7. 24GHz 毫米波模块 Lite 功能概述

为了帮助您快速了解套件的全部功能和这些功能的使用，您需要仔细阅读本节。如果您想要更详细的信息，我们建议您花时间阅读产品用户手册。

有关仪表板配置和参数的详细信息，我们在 ESPHome 文档中编写了详细的说明，因此请移步阅读完整的说明和详细信息。

ESPHome 文档 📕

步骤 8. 配置 Home Assistant 面板

如果您发现默认卡片非常无聊且不利于数据展示，Home Assistant 提供了各种现成的仪表板供您选择。

您可以根据自己的喜好制作自己的仪表板。

例如，控制信息输出的选项变成了一个漂亮的开关。

将人体运动速度转换为可视化仪表板显示。

这是我想出的。看起来它具备了智能家居控制中心的雏形。

到目前为止，我们已经成功完成了我们的教程内容。

使用 XIAO ESP32C3 将 Grove 连接到 Home Assistant

当然，XIAO ESP32C3 在 Home Assistant 中不仅仅支持 24GHz 毫米波人体静态存在模块 Lite，您可以在此文档中找到更多教程供您自己使用。

• 使用 XIAO ESP32C3 将 Grove 连接到 Home Assistant

发挥您的创造力！

故障排除

常见问题 1：使用 ESPhome Web 工具上传固件时出现以下错误，如何修复？

答：如果在上传时出现此提示，请断开 XIAO ESP32C3 与 PC 的连接。然后，按住 BOOT 按钮，在按住 BOOT 按钮的同时将开发板连接到 PC，然后释放它以进入引导加载程序模式。此时重新连接并再次上传固件即可。

常见问题 2：按照 esphome flasher 教程在 Linux 下无法安装 esphome flasher？

答：执行以下命令时，您需要选择您的系统版本，否则会出现错误。例如，我的计算机是 Ubuntu 22.04，那么应该执行的命令如下。

sudo apt install python3

pip3 install -U \
    -f https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-22.04/ \
    wxPython

pip3 install esphomeflasher

FAQ3: 我填写了正确的WiFi和密码，为什么看不到XIAO ESP32C3的IP地址？

答：当您遇到这个问题时，请检查XIAO ESP32C3的天线是否连接到位。如果天线已经连接，请确保XIAO与LinkStar的距离不超过3米（除非您已经更换了更强大的天线）。 如果您仍然看不到XIAO，您可以使用esphome flasher软件检查XIAO的日志信息，并通过日志检查XIAO连接。 您可以重新插拔xiao，让它尝试重新搜索WiFi并连接。

FAQ4：我使用Jlink刷写固件，但出现错误"Programming of range @address 0x08000000 failed (block verification error) Program failed Failed to program and verify target"？

当您使用Jlink刷写固件并出现此错误时，您可能处于以下任一情况中。

1. 您的传感器完全无法正常工作，您无法从中接收任何消息。
2. 您正在尝试使用无效或错误的固件。

caution

如果您的雷达原本工作正常，请再次检查您使用的固件是否正确！使用的固件因雷达而异，因传感器型号而异！并且通过UART升级固件与通过Jlink升级固件不同！请停止执行以下步骤。

我已确认我的产品在异常情况下出现此错误消息

如果您的雷达完全无法工作，那么出现此错误消息可能是正常的。

因为雷达的异常运行已经触发了雷达的读/写保护机制，一般不再允许用户对产品进行刷写程序，所以我们需要解锁雷达的读/写保护机制。

由于解除读写保护的风险很高，我们不会在此处单独向公众披露解除读写保护的方法，我们将把该方法放在此处的zip文件中供需要的人使用。一旦异常雷达解除保护，就可以再次更新固件以恢复正常运行。

技术支持与产品讨论

感谢您选择我们的产品！我们在这里为您提供不同的支持，以确保您使用我们产品的体验尽可能顺畅。我们提供多种沟通渠道，以满足不同的偏好和需求。