首次启动

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

---

安全须知（必读）

💡 硬件使用规范

• 请使用套件自带的USB-A转USB Type-C电源线（支持最高5 A电流），禁止使用额定输出电流低于 3 A的电源（如手机充电器），否则可能造成Quectel Pi H1智能主控板供电不足或反复异常停机；若需外接大功率模块（如电机），需单独为模块供电，禁止通过智能主控板的USB接口或GPIO引脚取电，以免过载并损坏Quectel Pi H1。

• 插拔配件（如摄像头排线、网线）时建议先断开智能主控板的电源，带电插拔可能损坏接口芯片；USB&DP接口仅支持DP显示和供电输出，不可用于为Quectel Pi H1供电。

• 工作温度：-20 °C ~ +70 °C，禁止在阳光直射等高温环境、潮湿环境（湿度＞80 %）或多尘环境中使用；操作前先触摸金属物体释放静电，避免用手直接接触单板上的芯片引脚。

系统与软件注意事项

• 仅支持官方提供的系统镜像，禁止刷入其他智能主控板（如树莓派）的镜像，否则会出现驱动不兼容、无法启动等问题。

• 若需自定义系统，需使用 Yocto Linux SDK 进行开发，确保内核版本、驱动模块与Quectel Pi H1匹配。

• 请勿修改 /boot 分区下的核心配置文件（如 config.txt），否则可能导致系统无法启动。如确需修改，请先备份相应文件。

• 安装软件时优先使用 apt 命令从官方源下载，避免安装未知来源的.deb包，降低系统感染恶意软件或发生故障的风险。

准备工作

根据使用场景，可选择外接显示器或ADB连接两种配置方案。√表示必需，○表示可选。

配件	规格要求	外接显示器	ADB连接
Quectel Pi H1智能主控板	—	√	√
电源适配器	5 V/ 5 A或9 V/ 3 A PD	√	√
网线	连接路由器或使用Wi-Fi	○	○
显示器	台式机显示屏/ MIPI屏	√	○
USB-C DP/ HDMI线	连接显示器	√	○
键盘/ 鼠标	USB有线/ 无线	√	√
台式机/ 笔记本电脑	用于运行终端软件	○	√
USB Type-C转USB Type-A数据线	连接Quectel Pi H1与台式机	○	√

备注

9 V需要使用PD协议的适配器和对应线缆。

上电前准备

Quectel Pi H1左上角标有 AUTO_POWER_ON 丝印的排针，需使用跳线帽短接，方可启用上电自动启动功能。

跳线帽状态说明：

跳线状态	插法说明	系统上电响应 / 启动行为
已短接（推荐）	跳线帽同时套在两根排针上，将两针导通	接通电源后系统自动启动，无需额外操作
未短接	跳线帽未安装，或仅套在单根针上（悬空保存）	接通电源后，系统不会自动启动，需长按 PWRKEY 按钮3-5秒手动开机

选择使用场景

Quectel Pi H1出厂默认搭载Debian 13系统镜像，通常无需重新烧录镜像。请根据设备条件选择相应的启动方式：

场景	所需硬件	参考章节
有外接显示器	HDMI/ USB-C DP显示器或MIPI DSI屏幕、键盘和鼠标	外接显示器启动Quectel Pi H1
无外接显示器	USB-C数据线和电脑	无外接显示器启动Quectel Pi H1

有外接显示器启动Quectel Pi H1

硬件连接

1. 显示连接：需根据显示器的接口选择以下连接方案之一，上图以 方案2（HDMI连接）为例；
   方案1（USB-C DP连接）：将USB-C DP显示线一端接入Quectel Pi H1的USB&DP接口，另一端接入显示器的USB-C接口。
   方案2（HDMI连接）：将HDMI线一端接入Quectel Pi H1的Micro HDMI接口，另一端接入显示器的HDMI接口，如上图所示。
   方案3（MIPI屏）：请确认排线金手指与接口触点位于同一侧。将排线插到底后，再压下卡扣固定，以免因方向错误导致主板或屏幕硬件物理击穿烧毁。具体操作请参考 MIPI。

2. 网络连接：将千兆网线的一端接入Quectel Pi H1千兆网口，另一端接入路由器网口（或通过Wi-Fi接入，参考 配置Wi-Fi）；

3. 输入设备连接：将USB键盘和鼠标接入Quectel Pi H1的USB-A接口，无线输入设备则将接收器插入USB接口即可；

4. 供电连接：USB-A电源线的USB-A端接符合要求的电源适配器，USB-C端接入Quectel Pi H1标注 POWER IN 供电接口。

系统启动

• 打开显示器电源，确认显示器输入源已切换到对应的接口（如USB-C或HDMI）。

• 接通Quectel Pi H1电源。电源灯（红色）常亮且系统灯（绿色）闪烁时，表示系统正在启动。

• 等待约1~2分钟，显示器将显示系统登录界面。

备注

若硬件连接时，没有将标有 AUTO_POWER_ON 丝印的排针使用跳线帽短接，则需要先接通电源，长按Quectel Pi H1右侧的 PWRKEY 按钮，直到系统启动。若系统无法正常启动，请重新烧录系统镜像：

1. 点此下载Debian 13镜像；

2. 点此下载和安装USB驱动；

3. 将智能主控板的USB & DP接口连接到电脑；

4. 点此查看安装系统教程。

系统登录

有关用户名和密码的设置方法，请参考 系统登录。

备注

1. 使用普通用户通过 sudo 提权，或在终端执行 sudo passwd root 为root账户设置密码。

2. 若创建本地用户时误入 Enterprise Login 界面无法退出，可再次点击 Enterprise Login 切回本地用户创建界面。

网络配置

点击右上角的状态栏然后进入设置，选择要连接的Wi-Fi网络，输入密码后进行连接。

进入终端命令行

无外接显示器启动Quectel Pi H1

如果Quectel Pi H1未外接显示器、键盘和鼠标，可以通过一台主机远程控制该设备。

要远程控制Quectel Pi H1，需先将其接入网络，再通过主机上的客户端进行访问。若设备尚未联网，可先通过 ADB 完成初始网络配置。

有关更多远程访问方式，请参考 设备连接。

方式	说明	前置条件	参考文档
VNC	远程访问图形化桌面	设备已联网	VNC远程桌面
SSH	远程访问命令行终端	设备已联网	SSH远程终端

备注

首次启动时，建议先通过ADB完成Wi-Fi配置，然后即可使用VNC或SSH进行日常操作。

ADB连接Quectel Pi H1

此方法可在没有外接显示器的情况下远程登录并控制Quectel Pi H1。

下载ADB工具：platform-tools。

配置 ADB 工具

将下载的 platform-tools 解压到电脑上的指定文件夹。

确认ADB设备已识别

用USB Type-C线连接Quectel Pi H1与电脑，在ADB工具目录中打开终端并执行以下命令：

adb devices

输出示例：

List of devices attached
790c2fb9        device

备注

如果设备状态显示为 unauthorized，在终端执行 adb kill-server && adb start-server 重启服务。

ADB连接设备

adb shell

连接成功后，将以root用户身份进行操作。

创建普通用户

系统默认仅提供root用户，建议创建普通用户用于日常操作。

创建用户

以下以创建pi用户为例，您也可以指定其他用户名。

adduser pi
#此处pi为创建的用户名称

系统会提示您设置密码，请按提示输入两次密码。

用户创建完成后，系统会自动将 /home/<用户名> 创建为该用户的家目录。后续可在此目录下存放个人文件和项目代码等内容。

配置*sudo*权限

usermod -aG sudo pi

切换用户

#验证用户
id pi

#切换用户
su - pi

#测试权限
whoami
sudo whoami
#应输出root，验证sudo权限

连接Wi-Fi

Quectel Pi H1内置qpi-config工具，可用于管理Wi-Fi连接。

扫描周围Wi-Fi网络

qpi-config wifi scan

连接目标Wi-Fi

#连接目标Wi-Fi
qpi-config wifi connect <"你的Wi-Fi名称"> <"你的Wi-Fi密码">

#查看已保存的Wi-Fi连接
qpi-config wifi show

#删除已保存的Wi-Fi连接
qpi-config wifi remove <connection_uuid>

验证网络连通性

ping -c 4 www.baidu.com  # 可随时按键盘上的Ctrl + C终止

SSH连接智能主控板

查看设备IP地址

在上一节已经建立的ADB终端中执行 ip a 命令，获取设备的IP地址。

示例中查询到的设备IP为 10.55.84.133。

使用QPiTerminal工具SSH连接智能主控板

打开 QPiTerminal 并新建 SSH 会话，输入智能主控板的IP地址、用户名和密码，然后点击”连接“。

系统健康检查

系统启动后，在终端通过 qpi-config 命令快速检查系统状态。

查询系统各模块温度

# 需要管理员权限
sudo qpi-config dump temperature

查询系统CPU、内存和存储状态

# 需要管理员权限
sudo qpi-config dump systemusage

网络状态检查

通过网线或Wi-Fi将设备接入网络后，使用 ping 命令确认设备能正常访问外部网络。

# 可随时按键盘上的Ctrl + C终止
ping -c 4 www.baidu.com 

正常连通输出示例：

备注

标识说明：
64 bytes from ...：收到ICMP应答（reply），表示网络连通正常
icmp_seq：序列号，递增说明持续收到响应
ttl：生存时间，通常为固定值
time：往返延迟，数值越小说明网络质量越好
0% packet loss：丢包率为0%，表示本次测试未发生丢包

第一个Hello World程序

用途

Hello World程序可用于验证开发环境是否搭建成功。通过编写和运行简单的C语言或Python程序，可以检查编译器、运行时环境等是否正常工作，也可将其作为嵌入式开发的入门练习。

搭建开发环境

登录到Quectel Pi H1的Debian系统后，打开终端窗口，输入以下命令并回车，安装必要的开发环境：

sudo apt update && sudo apt install gcc make 

编译与运行helloworld（C语言版）

1. 打开系统终端，输入以下命令创建 hello.c 文件。

touch hello.c

2. 输入以下命令，使用 nano 编辑器打开 hello.c 文件。

nano hello.c

3. 将下列代码复制到 hello.c 文件中，依次按 Ctrl+O 和 Enter 键保存，然后按 Ctrl+X 退出 nano 编辑器。

#include <stdio.h>
int main(void)
{
    printf("Hello, World!\n");
    return 0;
}

4. 执行以下命令，编译代码：

gcc hello.c -o hello

5. 执行以下命令，运行hello程序：

./hello

6. 程序运行结果如下：

Hello, World!

编写与运行helloworld（Python版）

除了C语言，还可以使用Python快速实现Hello World程序。系统已预装Python环境，无需额外安装解释器。

1. 打开系统终端，在终端输入以下命令创建 hello.py 文件。

touch hello.py

2. 输入以下命令，使用 nano 编辑器打开 hello.py 文件。

nano hello.py

3. 复制以下代码，并将其粘贴到 hello.py 文件中：

def main():
    print("Hello, World!")

if __name__ == "__main__":
    main()

4. Python是解释型语言，无需编译，直接执行即可：

python3 hello.py

5. 程序运行结果如下：

Hello, World!

安全关机或重启

Quectel Pi H1支持通过桌面图形界面、命令行和物理按键三种方式安全关机或重启。

通过桌面图形界面关机或重启

如果您使用外接显示器并处于桌面环境中：

1. 点击桌面右上角的快速设置面板，在弹出的面板右上角，点击电源图标展开系统电源操作菜单。

2. 选择 关机（Power Off...） 或 重启（Restart...）。

通过命令行关机或重启

在终端（本地终端、SSH或ADB shell）中执行以下命令：

关机

sudo poweroff

重启

sudo reboot

通过物理按键关机

短按Quectel Pi H1右侧的 PWRKEY 按钮（约1~2秒），系统将执行安全关机流程。

备注

请等待系统指示灯（绿色）熄灭后再断开电源线。该指示灯熄灭表示系统已停止运行，此时可以安全断电。

后续学习建议

完成入门操作后，可继续了解以下内容：

• 支持配件

• 使用指南

• 操作系统

• 应用开发

• 边缘计算

• 开发工具

• 支持清单

• FAQ