# 智能家居中控系统

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

---

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

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

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

```{image} images/image_DOHEbB1rkozvw9xIuxCcfBihnPW.webp
:width: 1024px
:height: 768px
```

# 开发资源汇总

## 开发配件清单

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

| <div style="text-align: center"><br><strong>配件名称</strong><br></div> | <div style="text-align: center"><br><strong>数量</strong><br></div> | <div style="text-align: center"><br><strong>规格参数</strong><br></div> |
| --- | --- | --- |
| Quectel Pi H1智能主控板 | <div style="text-align: center"><br>1块<br></div> | <div style="text-align: center"><br><a href="<https://detail.tmall.com/item.htm?abbucket=14&id=941006342186&pisk=geTmoNbMznSXH2abmfbjDRx_BzmRHZ_1TdUOBNBZ4TW7MIEAMNxMiLUx1CW9SNvWUG8AkIplIddeDKQAXV8l662aurrV4z5f1GJOBIFXVpdUkEnfWPbf5NkKp23KMI_17fvj5xybUs1ZWs5N3Z_yoGESl23pGQVAgXdrJFK0m5CubPJN0TRP6Tzau1JNz85fUr5auNWrZ16P7rrV7_WPT64V7oWNzQ519rzNbiPz4T1N7sW2QQll6TWN7NJwaby779YwPUkagdQZM9qy5sjcLIW2MILz9irXMTYwSU5DZtO4fPzwrsjDzD4cC9IvbBsBkC0gPZdH4a5M5XrGIMxwka8qU2S5bUJPaKhTf_xM_e_fDWaBKZvGYESu_fAAStblaelTATLlHd8c4XUhXa8dYZ--VxIOo6vwlKVg7pRJ9EsWSv2PCnCCz1YsTlXGbgJb4kzqiP1r6Ur_fi55Z9Kg1erUzpx1LbcuAmsVNsHKZbq_fi55Z9hoZkw10_1xp&rn=a0b0cde1aa6e376a9b5f96c50ceb198f&spm=a1z10.5-b-s.w4011-23773508522.57.6b936560dX8ASU&skuId=5840912585943>">Quectel Pi H1智能主控板</a><br></div> |
| 电源适配器 | <div style="text-align: center"><br>1个<br></div> | <div style="text-align: center"><br><a href="<https://www.waveshare.net/shop/PSU-27W-USB-C-CN-B.htm>">27W USB Type-C接口充电器，1.2米线长，PD快充，适用于树莓派5代</a><br></div> |
| HDMI线 | <div style="text-align: center"><br>1根<br></div> | <div style="text-align: center"><br>HDMI 2.0标准，线长1m，HDMI-A（公头）转HDMI-D（公头）<br></div> |
| 网线 | <div style="text-align: center"><br>1根<br></div> | <div style="text-align: center"><br>千兆网线，线长1m<br></div> |
| CPU散热风扇 | <div style="text-align: center"><br>1个<br></div> | <div style="text-align: center"><br><a href="<https://www.waveshare.net/shop/Raspberry-Pi-5-Official-Active-Cooler.htm>">树莓派5代官方原装主动散热器（含导热贴）</a><br></div> |
| 网络摄像头(智能设备) | <div style="text-align: center"><br>1个<br></div> | <div style="text-align: center"><br><a href="<http://item.jd.com/100201292520.html?pcdk=ujfLGcdBEhSkpL477iIjlWwxDYsCx5G1-WFyWgshYVeNlwRrXP9UJXgxsNbMxi3R.rQ4a.tlbT>">Tenda腾达室内家用监控摄像头</a><br></div> |
| Wi-Fi灯（智能设备） | <div style="text-align: center"><br>1个<br></div> | <div style="text-align: center"><br><a href="<https://item.taobao.com/item.htm?id=938147740452&pisk=gSZq2LNsUiI2sW13LJmNzPQh-snxcc5QilGsIR2ihjc0lRDib7V1HjwGM5rZZ7JfMrGsb5Pa_jG0lRTg_SNTl5yOHAcgs5l_lasQH-ntj6sNAMwvFELUeSkmS8XiCvYcFqxFydfmj61CAU9oksighDd6YuYopbDDmcDGUbDtLcDDojXrZAkpSIVijTWrCvOinhxDrLDEZKxDjqDkZvDnshDmSTyowAiis50cU8c-IcciaYe0I3kIotkWwciVgEgIt-cyjHJK3qfUEFtHxGkxkX0owhb74xuqt-qHRJrIEuZrR491N02LPSDrYiRK3z2EmArOKFlZ7onraWSHXYU0gu0aVOI3hmkZ-c0yIh2znbgumDjHaYUuhPqYgd-iHoZI7X3PIh3sqkg3-SJOp8mmI53Lf6KxiR2LvyiF0BH4rJoP4hOtEQ5gXrRM7qD-UX6PUI7bl6rhtRT6WF3ovYlChxT9WqqsUX6yqFLtkoHrOtYC.>">Smart Life涂鸦智能WI-FI灯泡</a><br></div> |
| 显示屏 | <div style="text-align: center"><br>1个<br></div> | <div style="text-align: center"><br>24英寸HDMI显示器<br></div> |

## 配件实物参考

```{image} images/image_JQtYbpJipomCY6xm4aPcatVpnzd.webp
:width: 1303px
:height: 745px
```

# 快速上手

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

## 硬件连接

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

```{image} images/image_W4Chb0enpo59Coxblx4cJJlNnqc.webp
:width: 833px
:height: 521px
```

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

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

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

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

## 项目实现

### 安装基础依赖

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

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

### 安装Docker

1.添加Docker官方GPG密钥：

```plaintext
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软件源：

```plaintext
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套件：

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

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

```plaintext
sudo systemctl enable docker
sudo systemctl start docker
sudo docker version
```

```{image} images/image_Mq9lb1ANToJSiVx1vSucLic4nMh.webp
:width: 506px
:height: 506px
```

### 用Docker Compose部署Home Assistant

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

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

- *network_mode: host*

- *privileged: true*

- 配置目录挂载到 */config*

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

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

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

**步骤2：写入Compose配置**

```plaintext
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容器**

```plaintext
sudo docker compose up -d
```

```{image} images/image_AhOSbrpBgoJh6xxPs1NcJ5qQn4j.webp
:width: 817px
:height: 98px
```

### 配置防火墙规则

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

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

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

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

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

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

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

### 访问Home Assistant控制台

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

```plaintext
http://<QuectelPi-IP>:8123
```

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

```{image} images/image_EKFUbS6AXoFXS8x5YezcWV8unwe.webp
:width: 1200px
:height: 787px
```

```{image} images/image_EQ7pbOnixo8wXTxgzfBcued2njd.webp
:width: 1187px
:height: 754px
```

```{image} images/image_GlPmbvW75oL2dxxcHYsc2pHYn2f.webp
:width: 1356px
:height: 800px
```

```{image} images/image_Q1PKb8ojkocf8PxwmTecBrI9n8d.webp
:width: 1293px
:height: 786px
```

```{image} images/image_ECsfbq4c6oQ8YNxHnCzcITd8nCe.webp
:width: 1294px
:height: 718px
```

```{image} images/image_SRm9b3H7jojyZGxjNVUciZTMnDe.webp
:width: 1374px
:height: 796px
```

### 查看容器运行日志

```plaintext
sudo docker logs -f homeassistant
```

### 集成智能设备

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

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

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

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

```{image} images/image_TVMWbe1nYolTpjxlEQWclCHhnvd.webp
:width: 1356px
:height: 792px
```

```{image} images/image_IwO0bbW2kozoC2xgJIdcIukVnle.webp
:width: 1366px
:height: 792px
```

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

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

```plaintext
# 查看容器运行状态
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               
```

```{image} images/image_EZWMbmrhQom2EzxM6WscJt9Pnxb.webp
:width: 817px
:height: 504px
```

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

```{image} images/image_BqhOb1U16oOr2bxyBIgcPxxjnRh.webp
:width: 1366px
:height: 792px
```

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

```{image} images/image_GR7KbcKnOoAB5dxlfALcg1r3nNU.webp
:width: 589px
:height: 344px
```

```{image} images/image_JroubKWZ6oCVzix4D0tceNB9n2g.webp
:width: 1374px
:height: 796px
```

### 创建场景和仪表盘

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

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

详细配置可参考 [Home Assistant官方文档](<https://www.home-assistant.io/getting-started/onboarding_dashboard/>)

```{image} images/image_I53lbohyQohL3bxX77RcSe1enge.webp
:width: 1356px
:height: 792px
```

### 注意事项

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

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

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

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

# 应用演示

<div class="video-preview">
  <video width="100%" controls preload="none">
    <source src="videos/video_R7reb20I3oRd7GxkQNoc9nfBnxg.mp4" type="video/mp4">
    Your browser does not support the video tag.
  </video>
  <div class="video-caption">
    <strong>smart-home-central-control-system</strong>
  </div>
</div>


# 常见问题排查

## 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

# 技术支持与贡献

如在使用过程中遇到问题，欢迎在 [移远官方论坛](<https://forumschinese.quectel.com/c/quectel-pi/58>) 提交技术咨询，我们的技术支持团队将及时为您解答。