【指南】使用 MQTT 将 ESP32-C5 连接到 Home Assistant
本帖最后由 zoey不种土豆 于 2025-8-18 18:10 编辑FireBeetle 2 ESP32-C5是一款紧凑而强大的开发板，由ESP32-C5芯片提供支持，专为需要高效可靠无线连接的物联网应用而设计。ESP32-C5采用运行频率高达240 MHz的RISC-V 32位单核处理器，集成了先进的连接选项，包括双频Wi-Fi 6（2.4 GHz和5 GHz）、蓝牙5（LE）和IEEE 802.15.4（Zigbee 3.0、Thread 1.3）。它拥有384 KB SRAM、320 KB ROM和29个可编程GPIO，提供强大的性能和灵活性，是智能家居和⼯业物联⽹项⽬的理想选择。
本文中，我们将引导你完成在 Home Assistant 环境中设置 MQTT（消息队列遥测传输）的基本步骤。MQTT 是⼀种常用的物联网设备和家庭自化协议。通过这些步骤，你将了解在 Home Assistant 中配置 MQTT 的基本步骤，从而实现 ESP32-C5 与系统之间的高效通信，以实现⽆缝设备控制和自动化。
什么是 Home Assistant？
Home Assistant 是⼀个免费开源的平台，充当家庭自动化的核心枢纽。它能够无缝控制和自动化来自不同品牌的智能家居设备，提供统⼀的界面，无需依赖云服务或互联网连接。这种本地控制的焦点确保了更高的隐私性和可靠性。通过 Home Assistant 云，⽤户可以安全地远程访问其系统，集成语音助手，并保持全面加密。Home Assistant 设计用于互操作性，既作为智能家居枢纽，又作为集成平台，使其成为从单⼀端点管理各种物联网设备的多功能解决方案。
入门指南
硬件：
要跟随本指南操作，你需要以下设备：
[*]Home Assistant Green：一款专门用于管理智能家居的Home Assistant硬件设备。
[*]FireBeetle 2 ESP32-C5：这是一款低功耗物联网开发板，具备高性能、多协议无线连接和智能电源管理功能，使其非常适合可靠、灵活且持久的智能家居和物联网应用。
[*]DHT11：精确的温湿度传感器，具备即插即用接口。
如果想用树莓派来DIY你的家庭助理，你将需要以下物品：
[*]树莓派5或树莓派4搭配电源（请确保选择至少有2GB RAM的型号）。
[*]带读卡器的MicroSD SD卡：请确保使用至少提供32GB存储空间的卡。
[*]以太网线：安装时需要。安装完成后，Home Assistant可以使用Wi-Fi，但以太网络连接更可靠，强烈推荐使用。
软件：
[*]树莓派镜像写入工具：一种快速简便的方法，可将树莓派操作系统和其他操作系统安装到 microSD 卡上，以便与你的树莓派一起使用。
[*]Arduino IDE：它是一个多功能、对初学者友好的开源电子原型开发平台。只需稍加学习，你就能迅速开始开发自己的项目。
步骤一.安装Home Assistant
在通过MQTT将ESP32-C5连接到Home Assistant之前，你需要一个正在运行的Home Assistant实例。在这里，我们将介绍两种流行的入门方法：一种是使用树莓派的DIY方法，以获得亲身体验；另一种是使用Home Assistant Green的即插即用选项，以实现简单性。有关其他安装方法，例如使用虚拟机或其他硬件，请参考官方指南：https://www.home-assistant.io/installation/。
树莓派DIY
树莓派是一款紧凑、价格实惠的单板计算机，也是托管Home Assistant最受欢迎的选择之一。如果你对亲自动手的DIY项目感兴趣，希望借此提升技能并自定义设置，那么这种方法是理想之选。
按照以下步骤，使用树莓派镜像工具在树莓派上安装Home Assistant操作系统（HAOS）：
[*]从树莓派官方网站下载并安装树莓派镜像写入工具。
[*]将 microSD 卡插入计算机。
[*]在Imager中，选择“Home Assistant”作为OS，选择你的树莓派型号，然后将镜像写入SD卡。
[*]将SD卡插入树莓派，接通电源，然后按照屏幕提示进行设置。
如需详细检查，包括硬件要求和故障排除，请查看官方教程：https://www.home-assistant.io/installation/raspberrypi。
与Home Assistant Green即插即用
如果你希望轻松上手，Home Assistant Green是一款经济实惠、即用型设备，专为Home Assistant量身打造。它预装了软件，因此你只需插上电源，几分钟内即可启动运行，无需组装或安装操作系统。
设置方法如下：
[*]打开 Home Assistant Green 的包装盒，将其连接到电源和网络（通过以太网线）。
[*]在同一网络中的浏览器中访问 homeassistant.local:8123 的网页界面。
[*]完成初始配置向导，创建你的账户并设置智能家居。
有关逐步说明，包括开箱和网络提示，请参阅支持文章：https://support.nabucasa.com/hc/en-us/articles/24737667232413-Getting-started-with-Home-Assistant-Green。
一旦 Home Assistant 通过任一方法启动并运行，你就可以继续为 ESP32-C5 集成配置 MQTT。
步骤二. Home Assistant MQTT集成
步骤1. 导航到你的 Home Assistant 用户界面。
提示：要访问高级功能，如MQTT配置，请启用Advanced Mode（高级模式）：
点击你的个人资料并启用Advanced Mode。
步骤2. 在侧边栏中，点击Settings打开设置菜单，然后选择Add-ons（附加组件）以访问附加组件商店。
步骤3. 使用搜索栏或浏览可用的附加组件，以找到Mosquitto broker（Mosquitto代理）。
步骤4. 点击按钮打开Mosquitto broker主页，然后点击INSTALL（安装）添加它。
步骤5. 安装完成后，点击START启动。
步骤6. 等待服务启动，然后查看Log（日志）选项卡中是否有错误。请注意，日志不会自动刷新，你需要手动刷新。成功启动的日志应如下所示：
为MQTT添加专用用户
步骤1. 专门为 MQTT 访问创建一个单独的账户。
步骤2. 点击 Settings（设置）按钮，然后选择 People（人员）。
步骤3. 点击ADD PERSON（添加人员）。
步骤4. 输入一个Name（名称），并确保勾选Allow person（允许人员）登录。
注意
[*]名称不能为 homeassistant 或 add-ons，因为这些是保留用户名。
[*]如果你看不到创建新用户的选项，请确保Advanced Mode（高级模式）已在你的Home Assistant个人资料中启用。
步骤5. 在Add User（添加用户）弹出窗口中，输入密码，确认密码，然后点击CREATE（创建）。
添加MQTT集成
步骤1. 导航到Settings -> Devices & Services（设置 -> 设备和服务）。
步骤2.在Integrations（集成）页面上，你应该能看到MQTT集成。
步骤3. 点击CONFIGURE -> SUBMIT -> FINISH（配置 -> 提交 -> 完成）。之后，你将在Configured（配置）下看到MQTT。
注意：请将ESP32C5和Home Assistant保持在同一局域网内
步骤三. 将 MQTT 示例烧录到 ESP32-C5Arduino准备
步骤1.根据你的操作系统下载并安装最新版本的Arduino IDE
https://h7dvigefi0.feishu.cn/space/api/box/stream/download/asynccode/?code=NzEyMDI5YjBmZDdhMDg1MTgyMjA1NDA0NWZhOTIzMDhfMklNVXBmM1VHa0JRVVFaWVJVWEIyMnFMbzlveGl4RkFfVG9rZW46SW41QWI4TXc4bzdiQ3B4b092SGM2ajNDbjhiXzE3NTU0OTgxNzc6MTc1NTUwMTc3N19WNA步骤2.启动Arduino应用程序
步骤3.将ESP32板包添加到你的Arduino IDE中
导航到File > Preferences（文件 > 首选项），并在“Additional Boards Manager URLs”（"附加开发板管理器 URL"）中填入以下 URL：https://espressif.github.io/ardu ... sp32_dev_index.json
导航到Tools > Board > Boards Manager...（工具 > 开发板 > 开发板管理器...），在搜索框中输入关键字esp32，选择v3.3.0-alpha1分支的最新版本esp32，然后安装它。
步骤4.选择你的开发板和端口
主板：
导航到Tools > Board > esp32，然后选择ESP32-C5 Dev Module。
在上传代码之前，请配置你的开发板设置：
[*]启动时USB CDC：
[*]Enabled 启用：通过USB接口打印串口数据
[*]Disabled 禁用：通过TX/RX引脚打印串口数据
[*]Partition Scheme 分区方案：选择适合你开发板闪存大小的存储分区
[*]Port 端口：导航到Tools > Port(工具 > 端口)，并为你的开发板选择正确的串口。确保COM编号正确；它不需要与芯片型号匹配。
步骤5. 导航到 Sketch > Include Library > Manage Libraries...，在搜索框中输入关键字 "PubSubClient"，选择 PubSubClient 的最新版本并安装。
步骤6.按照图示连接ESP32-C5：将DHT11连接到扩展板，再通过USB线将ESP32-C5连接到计算机。
步骤7. 将Esp32C5_to_WiFi_and_MQTT代码上传到你的ESP32-C5。
你可以在这里找到代码：https://github.com/Skicheng/ESP3 ... me%20assistant-MQTT
在这里，你可以看到它连接到Wi-Fi，然后连接到MQTT代理。一旦显示MQTT已连接，它就开始发送数据。
现在，让我们回到 Home Assistant。在Settings > Add-ons,(设置 > 插件)中，打开代理并查看日志。你可以看到客户端正在连接并尝试向 MQTT 发送数据。
设置你的家庭助理仪表盘
现在我们可以在Home Assistant仪表板上显示传感器数据了。
添加文件编辑器
步骤1. 转到Add-on Store(附加组件商店)并找到File editor(文件编辑器)。
步骤2. 点击按钮打开File editor(文件编辑器)主页，然后点击INSTALL 安装。
步骤3. 安装完成后，点击START启动。
步骤4. 点击New File (新建文件)并将其命名为mqtt.yaml
步骤5. 在mqtt.yaml文件中，添加以下行：
sensor: name: MQTT Demo unique_id: "MQTT_Demo" state_topic: esp32c5/data
步骤6. 点击右上角的红色图标保存。
步骤7. 然后点击configuration.yaml
步骤8. 在configuration.yaml文件中，添加以下行，然后点击右上角的红色图标保存：
mqtt: !include mqtt.yaml
步骤9。转到Developer Tools(开发者工具)并点击CHECK CONFIGURATION(检查配置)。
步骤10. 然后点击ALL YAML CONFIGURATION(所有YAML配置)，你应该会看到一个绿色的对勾图标。
传感器数据现已成功显示在Home Assistant仪表板上。
安装HACS
HACS（Home Assistant社区商店）是一个由社区驱动的附加组件商店，为Home Assistant提供广泛的第三方集成和自定义组件。在本指南中，我们将向你展示如何将HACS集成到Home Assistant中，以及如何安装和使用它提供的各种组件，以使你的智能家居系统更加完善和个性化。
步骤 1. 导航到Settings > Add-ons> Add-on store(设置 > 插件 > 插件商店)以找到Terminal & SSH and install it(终端和 SSH 并安装它)。
如果你看到以下屏幕，则表示安装成功。
步骤2.在终端中输入以下命令，下载HACS安装包：
运行HACS下载脚本。
wget -O - https://get.hacs.xyz | bash -
3. 重启Home Assistant
设置 HACS 集成
步骤1. 在 Home Assistant 中，转到 Settings > Devices & Services(设置 > 设备与服务)。 在右下角，点击 + Add Integration(添加集成)。 搜索 HACS 并选择它。
步骤2. 确认声明并选择Submit(提交)。
对集成进行身份验证：
[*]HACS使用设备OAuth流程来进行与GitHub的身份验证。
[*]复制设备代码并选择链接https://github.com/login/device。
[*]登录GitHub。
[*]如果你尚未在浏览器中登录 GitHub，则需要立即注册或登录才能继续设置。
[*]如果你已经登录，则可以跳过此部分。
[*]输入你在上一步中复制的设备代码，然后选择Continue继续。
步骤3. 选择授权HACS。一旦看到确认屏幕，就可以关闭标签页并返回Home Assistant。
恭喜！你已在 Home Assistant 中安装了 HACS 集成。
返回 My Home(我的主页)，你可以轻松使用 HACS 来发现、安装和更新第三方集成与自定义组件，让你的 Home Assistant 仪表盘更具视觉吸引力。
页:
[1]