教程:VENTUNO Q/Home Assistant 智能家居中枢

来自WindwizPi wiki
< 教程:VENTUNO Q
Windwiz​（留言 | 贡献）2026年9月28日 (一) 06:01的版本 （导入 VENTUNO Q 中文教程）
(差异) ←上一版本 | 最后版本 (差异) | 下一版本→ (差异)

简介

thumbnail.png


Home Assistant 是智能家居自动化领域出色的开源平台。通过将 Arduino® VENTUNO™ Q 用作单板电脑，你可以在本地托管稳健的 HomeLab 环境。本应用笔记将指导你通过 Docker 部署 Home Assistant，确保智能家居数据完全由你掌控并保持离线。

目标

本教程的主要目标是：

  • 展示 Docker 的简洁性： 使用单条容器命令部署本地 Home Assistant 实例。
  • 扩展你的 HomeLab： 将 Arduino VENTUNO Q 从开发板转变为专用的本地智能家居服务器。
  • 建立坚实基础： 配置持久化本地存储，确保你的物联网自动化、设备与配置在更新和重启后仍然安全稳定。

硬件与软件要求

硬件要求

\*也可使用其他电源，电压范围为 7–24 V，电流 ≥ 3 A。更多信息请参阅 用户手册 - 电源部分。

软件要求

安装与设置

为确保 Docker 容器更新或重启时不会丢失智能家居配置、设备与自动化，我们必须将本地文件夹映射到容器。此外，正确设置时区对基于时间的自动化至关重要。

  1. 创建配置文件夹： 打开 VENTUNO Q 终端并创建专用目录。
    mkdir -p ~/homeassistant_config
  2. 验证绝对路径： 查找要在 Docker 命令中使用的确切路径。
    cd ~/homeassistant_config && pwd（将输出类似 /home/arduino/homeassistant_config 的路径）。
  3. 运行 Docker 容器： 执行以下命令。请务必将卷路径替换为你的绝对路径，并将 TZ 变量调整为你的 本地时区（例如 America/Santo_Domingo）。 
    docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=America/Santo_Domingo \
  -v /home/arduino/homeassistant_config:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

你的 Home Assistant 容器现在已在后台运行！可在浏览器中访问 http://<VENTUNO_Q_IP>:8123 打开引导式 Web 界面。


step1.png


点击 Create my Smart Home 按钮并按所示步骤操作：


step2.png


在这里，你需要为智能家居创建主管理员账户：

  • Name & Username： 输入你的全名并选择唯一用户名。
  • Password： 设置强且安全的密码。由于此账户将控制整个 HomeLab，安全性至关重要！
  • 点击 Create account 按钮继续。

注意： 请妥善保管这些凭据，因为你需要用它们登录 Home Assistant 仪表板。


step3.png


恭喜，你的本地 Home Assistant 实例已启动并运行！完成初始设置后，你将被重定向到主 Overview 仪表板。

这是你智能家居的指挥中心。开箱即用，你会注意到几个关键区域：

  • Navigation Sidebar： 位于左侧，此菜单可访问 Settings、History、Energy monitoring 等。
  • Areas： 你可以通过将设备分配到特定房间（如客厅或厨房）来逻辑地组织智能家居。
  • Auto-Discovery： 注意右侧的 “Devices discovered” 卡片。Home Assistant 会自动扫描本地网络中的兼容智能设备，使开始构建 HomeLab 变得非常容易。

MQTT 传感器集成

要真正释放 HomeLab 的能力，我们需要一种方式将物理硬件与 Home Assistant 仪表板通信。我们将使用 MQTT（Message Queuing Telemetry Transport，消息队列遥测传输）——物联网的标准消息协议——来实现这一点。

虽然本示例中我们是将传感器直接连接到 VENTUNO Q，但 完全相同的 MQTT 架构也适用于任何无线传感器或 Arduino 节点（如 Arduino Nano 33 IoT 或 ESP32）通过 Wi-Fi 网络发送数据。

1. 硬件连接

我们将使用 Modulino Thermo 读取实时温度与湿度。 只需用 Qwiic 线缆将 Modulino Thermo 连接到 Arduino VENTUNO Q 上的 Qwiic（I2C）连接器。


connection.png


2. 设置 MQTT Broker（Mosquitto）

Home Assistant 需要一个 “Broker” 来接收和路由 MQTT 消息。由于我们使用 Docker，可以在 Home Assistant 旁边部署 Eclipse Mosquitto broker。

  1. 创建必要的配置目录： 在 VENTUNO Q 上运行： 
    mkdir -p ~/mosquitto/config ~/mosquitto/data ~/mosquitto/log
  2. 创建基本配置文件： 此演示配置允许无需密码连接，包括来自本地网络上其他设备的连接。仅在受信任网络上使用；在共享或生产环境中使用前请配置身份验证。 
    nano ~/mosquitto/config/mosquitto.conf
  3. 粘贴以下内容： 然后保存并退出（Ctrl+O、Enter、Ctrl+X）： 
    listener 1883
allow_anonymous true
  4. 运行 Mosquitto Docker 容器： 
    docker run -d \
  --name mosquitto \
  --restart unless-stopped \
  -p 1883:1883 \
  -v /home/arduino/mosquitto/config:/mosquitto/config \
  -v /home/arduino/mosquitto/data:/mosquitto/data \
  -v /home/arduino/mosquitto/log:/mosquitto/log \
  eclipse-mosquitto:latest

3. 部署 Arduino App Lab 项目

我们准备了一个 App Lab 项目，它从 Modulino Thermo 读取数据（通过 MCU），并发布到 MQTT Broker（通过 Python）。


app.png


  1. 下载 App： 在此下载 MQTT Thermo Bridge App。
  2. 导入 App： 打开 Arduino App Lab，通过导入下载的文件创建新 App。
  3. 在 Arduino App Lab 中点击 Run 开始广播数据。

4. 在 Home Assistant 中配置 MQTT

现在，我们需要让 Home Assistant 监听我们的新 broker。

  1. 进入 Home Assistant 界面。
  2. 导航到 Settings > Devices & services。
  3. 点击右下角的 + Add Integration 按钮。
  4. 搜索 MQTT 并选择它。
  5. 在 Home Assistant 的 MQTT 集成中，在 Broker 字段输入 127.0.0.1，在 Port 字段输入 1883，不要带 http://。Home Assistant 使用主机网络，因此这会连接到 VENTUNO Q 上的 broker，而不依赖其网络 IP 地址。将用户名和密码留空，然后点击 Submit。


mqtt-settings.png


5. 验证数据流

让我们确保数据正从 Python 脚本正确到达。

  1. 在 MQTT 集成页面，点击 Configure。
  2. 向下滚动到 Listen to a topic 部分。
  3. 在 “Topic to subscribe to” 字段中输入：ventuno_q/thermo/state
  4. 打开 Format JSON content 开关，然后点击 Start listening。
  5. 每 5 秒，你应能看到带有传感器数据的新传入载荷。


mqtt-test.png


6. 将数据映射到传感器

要在仪表板上显示这些数据，我们必须将原始 JSON 载荷映射为 Home Assistant 传感器实体。

  1. 打开 VENTUNO Q 终端： 编辑 Home Assistant 配置文件。根据用户权限，必要时使用 sudo： 
    sudo nano /home/arduino/homeassistant_config/configuration.yaml
  2. 追加 YAML 块： 在文件末尾添加以下内容： 
    mqtt:
  sensor:
    - name: "Ventuno Temperature"
      state_topic: "ventuno_q/thermo/state"
      unit_of_measurement: "°C"
      device_class: temperature
      value_template: "{{ value_json.temperature }}"

    - name: "Ventuno Humidity"
      state_topic: "ventuno_q/thermo/state"
      unit_of_measurement: "%"
      device_class: humidity
      value_template: "{{ value_json.humidity }}"
    应如下所示：

config-yaml.png

  1. 保存文件：（Ctrl+O、Enter、Ctrl+X）。
  2. 返回 Home Assistant： 导航到 Developer Tools > YAML。
  3. 检查配置： 点击 Check Configuration。如果有效，点击 Restart 以应用更改。

7. 构建仪表板

创建传感器后，我们现在可以可视化环境了！

  1. 转到 Settings > Dashboards 并点击 + Add Dashboard。
  2. 选择 New dashboard from scratch 并将其命名为 “VENTUNO”。
  3. 从左侧边栏打开新仪表板，并点击右上角的铅笔图标（Edit）。
  4. 点击 + Add Card。你可以使用 Gauge 卡片获得类似速度表的外观，或使用 History graph 卡片查看温度随时间的趋势。
  5. 搜索 sensor.ventuno_temperature 和 sensor.ventuno_humidity 实体，并将它们添加到卡片中。


dashboard.png


恭喜！你已成功使用 Docker、MQTT 和 Arduino App Lab，将物理硬件桥接到可扩展的本地物联网平台。

灵感

从这里开始，你可以添加集成并构建仪表板。为让你了解完整实现的 HomeLab 是什么样子，这里展示一个真实世界 Home Assistant 设置的一瞥。稍加时日，你就可以构建交互式平面图、车辆追踪器、本地服务器监控以及高度详细的天气仪表板：


inspiration.gif


结论

通过遵循本指南，你已成功将 Arduino VENTUNO Q 转变为强大的本地智能家居中枢。通过 Docker 部署 Home Assistant，为你提供了可扩展、安全且以隐私为先的构建基础。此外，你还学习了如何通过开发板的内部 RPC 架构与 MQTT broker，将 Modulino Thermo 集成到仪表板，从而弥合物理硬件与仪表板之间的差距。你的 HomeLab 现已准备好在不依赖云服务器的情况下控制你的环境。

下一步

本地中枢上线后，是时候扩展你的生态系统了。以下是一些可以最大化利用硬件的精彩项目：

  • 连接其他 Arduino 开发板： 在 Docker 环境中设置 MQTT broker（如 Eclipse Mosquitto），以通过 Wi-Fi 接收家中其他 Arduino 开发板的无线传感器数据。
  • 搭建气象站： 通过从外部传感器拉取实时环境数据，为本地气象站创建专用仪表板。
  • 探索 ESPHome： 集成 ESPHome，以最少编码构建自定义、本地控制的智能设备与传感器。
  • 用 Matter 和 Zigbee 扩展： 将 Matter/Zigbee USB 加密狗插入 VENTUNO Q，无缝集成标准智能家居设备，从而充分利用如 Arduino Nano Matter 等开发板。

原文：https://docs.arduino.cc/tutorials/ventuno-q/home-assistant/ 本页为 Arduino 官方教程的中文翻译，供内部查阅。命令与代码保持原文。

检索自“https://windwiz-pi.com/index.php?title=教程:VENTUNO_Q/Home_Assistant_智能家居中枢&oldid=2051”