智能家居中控系统

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

---

智能家居中控系统是一个基于Quectel Pi H1智能主控板构建的家庭自动化中控方案。

本项目以Home Assistant作为核心平台，结合Docker容器化部署方式，在Quectel Pi H1本地完成设备接入、状态展示、场景联动和可视化控制。系统支持灯光、天气、电量、房间状态等家庭信息的集中展示，并可扩展Zigbee网关、传感器、摄像头及更多智能设备，适用于家庭中控面板、桌面控制终端以及轻量级边缘智能家居网关等场景。

该项目重点展示Quectel Pi H1在家庭自动化、本地服务部署、网页可视化界面承载以及多协议设备接入方面的能力，可作为智能家居控制中心、家庭信息看板和本地化智能场景联动系统的参考示例。

开发资源汇总

开发配件清单

说明：以下为推荐配件清单，实际开发可根据需求灵活调整。

配件名称	数量	规格参数
Quectel Pi H1智能主控板	1块	Quectel Pi H1智能主控板
电源适配器	1个	27W USB Type-C接口充电器，1.2米线长，PD快充，适用于树莓派5代
HDMI线	1根	HDMI 2.0标准，线长1m，HDMI-A（公头）转HDMI-D（公头）
网线	1根	千兆网线，线长1m
CPU散热风扇	1个	树莓派5代官方原装主动散热器（含导热贴）
网络摄像头(智能设备)	1个	Tenda腾达室内家用监控摄像头
Wi-Fi灯（智能设备）	1个	Smart Life涂鸦智能WI-FI灯泡
显示屏	1个	24英寸HDMI显示器

配件实物参考

快速上手

Quectel Pi H1智能主控板出厂预装 Debian 13 系统镜像，无需重新烧录系统，按照以下步骤即可开始开发。

硬件连接

完成以下所有硬件的连接操作，连接接口示意图如下：

1. 显示连接：HDMI线一端接主控板HDMI接口，另一端接显示器HDMI接口；

2. 网络连接：千兆网线一端接主控板千兆网口，另一端接路由器网口（替代方案：通过Wi-Fi接入同一局域网）；

3. 输入设备连接：USB键盘、鼠标接入主控板的两个USB-A接口，无线输入设备则将接收器插入USB口即可；

4. 供电连接：USB-A电源线的USB-A端接电源适配器，USB-C端接入主控板标注 POWER IN 的电源口。

项目实现

安装基础依赖

执行以下命令安装系统基础依赖包：

sudo apt update
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings

安装Docker

1.添加Docker官方GPG密钥：

sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

2.添加Docker软件源：

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

3.安装Docker套件：

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

4.设置Docker开机自启并验证安装：

sudo systemctl enable docker
sudo systemctl start docker
sudo docker version

用Docker Compose部署Home Assistant

Home Assistant官方Linux安装页给出的推荐容器参数包括：

• ghcr.io/home-assistant/home-assistant:stable

• network_mode: host

• privileged: true

• 配置目录挂载到 /config

• 可选挂载 /run/dbus，蓝牙相关需要用到

步骤1：创建部署目录及配置文件

sudo mkdir -p /opt/homeassistant
cd /opt/homeassistant
sudo nano compose.yaml

步骤2：写入Compose配置

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    restart: unless-stopped
    privileged: true
    network_mode: host
    environment:
      TZ: Asia/Shanghai
    volumes:
      - /opt/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro

步骤3：启动Home Assistant容器

sudo docker compose up -d

配置防火墙规则

默认情况下，8123端口未开放，仅支持本地访问Home Assistant控制台。如需局域网内其他设备访问，需手动开放端口：

1.编辑防火墙规则文件：

sudo vi /etc/iptables/rules.v4
sudo vi /etc/iptables/rules.v6

2.在文件中添加以下规则（将“端口号”替换为需开放的端口，如8123）：

-A INPUT -p tcp --dport 端口号 -j ACCEPT

3.重新加载防火墙规则：

sudo systemctl daemon-reload
sudo systemctl restart iptables-restore.service
sudo systemctl status iptables-restore.service

访问Home Assistant控制台

在局域网内打开浏览器，访问以下地址（替换 为主控板实际IP地址）：

http://<QuectelPi-IP>:8123

进入控制台后，完成用户创建及初始化配置即可使用，参考界面如下：

查看容器运行日志

sudo docker logs -f homeassistant

集成智能设备

支持将Wi-Fi灯、摄像头等智能设备接入Home Assistant统一管控，操作步骤如下：

1.进入Home Assistant控制台，点击「设置」；

2.选择「设备与服务」，点击「添加集成」；

3.搜索设备品牌名称，按指引添加对应集成即可。

拓展安装HACS（Home Assistant社区插件库）

HACS可扩展Home Assistant插件生态，安装步骤如下：

# 查看容器运行状态
sudo docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

# 进入 Home Assistant 容器
sudo docker exec -it homeassistant bash 

# 执行 HACS 官方安装脚本
wget -O - https://get.hacs.xyz | bash -   

# 退出容器并重启 Home Assistant
exit                                             
sudo docker restart homeassistant               

安装完成后，重启Home Assistant，在「设置」→「添加集成」中搜索“HACS”并完成添加：

使用HACS需登录GitHub账号完成授权，授权后即可下载社区插件：

创建场景和仪表盘

• 「场景」：可保存智能设备状态，实现一键启停多设备联动；

• 「仪表盘」：可集中概览所有设备及所属区域信息。

详细配置可参考 Home Assistant官方文档

注意事项

1. 本文档适配Quectel Pi H1智能主控板Debian 13系统环境，若系统版本不同，部分命令需按需调整；

2. 网络摄像头、Wi-Fi灯等配件为演示场景选配，实际部署可根据需求增减；

3. 若容器启动失败，优先排查以下问题：8123端口占用、/opt/homeassistant目录权限、网络模式配置；

4. HACS为社区开源插件库，使用前需遵守其开源协议及相关规范。

应用演示

smart-home-central-control-system

常见问题排查

Docker安装命令执行失败，提示包不存在

解决方案：

1. 重新执行 sudo apt update && sudo apt upgrade -y 更新系统源；

2. 检查Docker源添加命令是否输入正确，重新执行源添加步骤。

局域网其他设备无法访问Home Assistant控制台

解决方案：

1. 重新检查防火墙规则，确认添加8123端口放行规则并重启防火墙服务；

2. 检查所有设备的网络连接，确保接入同一路由器的Wi-Fi /有线网络；

3. 执行 ifconfig 查询主控板实际IP，替换错误IP重新访问

HACS安装完成后无法在集成中搜索到

1. 重新进入容器执行HACS安装脚本，确认脚本无报错执行完成；

2. 执行 sudo docker restart homeassistant 重启容器；

3. 检查主控板网络连通性，执行 ping github.com 测试，确保网络可访问GitHub

技术支持与贡献

如在使用过程中遇到问题，欢迎在 移远官方论坛 提交技术咨询，我们的技术支持团队将及时为您解答。