智能家居中控系统

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

---

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

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

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

智能主控板作为后台网关服务器运行，MIPI屏为外接设备，支持通过局域网客户端浏览器访问看板。

开发资源汇总

开发配件清单

备注

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

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

配件实物参考

快速上手

Quectel Pi H1 出厂预装 Debian 13 操作系统，通常无需重新烧录系统镜像。按照以下步骤即可开始开发：

硬件连接

按以下步骤完成硬件连接，各接口的位置见下图：

1. 显示连接：将Micro-HDMI连接线的Micro HDMI端接入智能主控板的Micro HDMI接口，另一端接入显示器的HDMI接口；

2. 网络连接：将千兆网线一端接入智能主控板的千兆网口，另一端接入路由器的网口（或通过Wi-Fi接入同一局域网）；

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

4. 供电连接：将电源适配器接入电源，电源适配器的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

步骤2：写入Compose配置：

sudo nano compose.yaml

将下列配置复制到compose.yaml中：

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

该镜像拉取自GitHub容器镜像源（ghcr.io）。若因网络原因出现拉取超时，建议为智能主控板配置Docker镜像加速代理或通过代理节点拉取。

步骤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. 在文件中添加以下规则（将 <PORT> 替换为需开放的端口，如8123）：

-A INPUT -p tcp --dport <PORT> -j ACCEPT

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

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

访问Home Assistant控制台

在局域网内打开浏览器，访问 http://:8123（将 替换为智能主控板实际IP地址）。

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

查看容器运行日志

sudo docker logs -f homeassistant

集成智能设备

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

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

2. 选择 设备与服务；

3. 点击 添加集成；

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

扩展安装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. 本文档适配智能主控板Debian 13系统环境，若系统版本不同，部分命令需按需调整；

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

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

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

应用演示

smart-home-central-control-system

常见问题排查

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

解决方案：

1. 先检查Docker官方源与架构配置是否正确，再执行 sudo apt update 刷新索引。

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

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

解决方案：

1. 执行 ip a 查询智能主控板的实际IP地址，替换错误的IP地址后重新访问；

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

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

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

解决方案：

1. 刷新浏览器界面重试；

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

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

4. 执行 ping github.com 检查智能主控板的网络连通性，确保可以访问GitHub。

技术支持与贡献

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