首次启动¶
Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.
安全须知（必读）¶
💡 硬件使用规范
请使用套件自带的USB-A电源线（5 A），禁止使用额定输出电流低于3 A的电源（如手机充电器），否则可能造成Quectel Pi H1智能主控板供电不足或反复异常停机；若需外接大功率模块（如电机），需单独为模块供电，禁止通过智能主控板的USB口或GPIO口取电，以免过载并损坏Quectel Pi H1。
插拔配件（如摄像头排线、网线）时 必须先断开智能主控板的电源，带电插拔可能损坏接口芯片；USB & DP接口仅支持DP显示和供电输出，不可用于为智能主控板供电。
工作温度：-20~+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与台式机 |
○ |
√ |
上电前准备¶
Quectel Pi H1智能主控板左上角标有 AUTO_POWER_ON 丝印的排针，需使用跳线帽短接，方可启用上电自动启动功能。
跳线帽状态说明：
状态 |
外观 |
行为 |
|---|---|---|
已短接（推荐） |
跳线帽同时套在两根排针上，将两针导通 |
接通电源后系统自动启动，无需额外操作 |
未短接 |
跳线帽未安装，或仅套在单根针上（悬空保存） |
接通电源后，系统不会自动启动，需长按PWRKEY按钮手动开机 |
备注
若未短接AUTO_POWER_ON，上电后需要长按PWRKEY按钮才能启动系统。
选择使用场景¶
Quectel Pi H1智能主控板出厂默认搭载Debian 13系统镜像，通常无需重新烧录镜像。请根据设备条件选择相应的启动方式：
场景 |
适用条件 |
跳转 |
|---|---|---|
有外接显示器 |
有HDMI / USB-C DP / MIPI显示器、键盘鼠标 |
|
无外接显示器 |
未配备显示器，但有一根USB-C数据线和一台电脑 |
外接显示器启动Quectel Pi H1¶
硬件连接¶
显示连接：需根据显示器的接口选择以下连接方案之一，上图以方案2（HDMI连接）为例；
方案1（USB-C DP连接）：将USB-C DP显示线一端接入Quectel Pi H1的USB & DP接口，另一端接入显示器的USB-C接口。
方案2（HDMI连接）：将HDMI线一端接入Quectel Pi H1的HDMI接口，另一端接入显示器的HDMI接口，如上图所示。
方案3（MIPI屏）：请确认排线金手指与接口触点位于同一侧。将排线插到底后，再压下卡扣固定，以免因方向错误导致无显示。具体操作请参考 MIPI。网络连接：将千兆网线的一端接入Quectel Pi H1千兆网口，另一端接入路由器网口（替代方案：通过Wi-Fi接入，参考 配置Wi-Fi）；
输入设备连接：将USB键盘和鼠标接入Quectel Pi H1的USB-A接口，无线输入设备则将接收器插入USB口即可；
供电连接：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按钮，再接通电源，直到系统启动。若系统无法正常启动，请重新烧录系统镜像：
使用符合要求的电源适配器给Quectel Pi H1供电；
将智能主控板的USB & DP接口连接到电脑；
系统登录¶
有关用户名和密码的设置方法，请参考 系统登录。
备注
root 账户默认无密码，需自行设置。
若创建用户时误入 Enterprise Login 界面无法退出，可再次点击 Enterprise Login 切回用户创建界面。
网络配置¶
选择要连接的Wi-Fi网络，输入密码后进行连接。
进入终端命令行¶
无显示器启动Quectel Pi H1¶
如果Quectel Pi H1未连接显示器、键盘和鼠标，可以通过另一台电脑远程控制该设备。
要远程控制Quectel Pi H1，需先将其接入网络，再通过另一台设备上的客户端进行访问。SSH用于远程访问命令行终端，VNC用于远程访问图形化桌面。若设备尚未联网，可先通过 ADB 完成初始网络配置。
有关更多远程访问方式，请参考 设备连接。
方式 |
说明 |
前置条件 |
教程链接 |
|---|---|---|---|
VNC |
远程访问图形化桌面 |
设备已联网 |
|
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，或未显示任何设备，请检查USB线是否为数据线（非纯充电线），或尝试更换USB接口。
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 www.baidu.com
SSH连接智能主控板¶
查看设备IP地址
在智能主控板终端中执行 ifconfig 命令，获取设备的IP地址。
示例中查询到的设备IP为 10.55.101.49。
使用QPiTerminal工具SSH连接智能主控板
打开 QPiTerminal 并新建 SSH 会话，输入智能主控板的 IP 地址、用户名和密码，然后点击 连接。
系统健康检查¶
系统启动后，在终端通过 qpi-config 命令快速检查系统状态。
查询系统各模块温度¶
sudo qpi-config dump temperature
查询系统CPU、内存和存储状态¶
sudo qpi-config dump systemusage
网络状态检查¶
通过网线或Wi-Fi将设备接入网络后，使用 ping 命令确认设备能正常访问外部网络。
ping www.baidu.com
正常连通输出示例：
PING www.a.shifen.com (183.2.172.177) 56(84) bytes of data.
64 bytes from 183.2.172.177: icmp_seq=1 ttl=51 time=18.5 ms
64 bytes from 183.2.172.177: icmp_seq=2 ttl=51 time=18.2 ms
64 bytes from 183.2.172.177: icmp_seq=3 ttl=51 time=18.3 ms
64 bytes from 183.2.172.177: icmp_seq=4 ttl=51 time=18.8 ms
64 bytes from 183.2.172.177: icmp_seq=5 ttl=51 time=18.2 ms
64 bytes from 183.2.172.177: icmp_seq=6 ttl=51 time=18.5 ms
64 bytes from 183.2.172.177: icmp_seq=7 ttl=51 time=18.9 ms
--- www.a.shifen.com ping statistics ---
7 packets transmitted, 7 received, 0% packet loss, time 6011ms
rtt min/avg/max/mdev = 18.199/18.482/18.901/0.249 ms
备注
标识说明：
64 bytes from …：收到ICMP应答（reply），表示网络连通正常
icmp_seq：序列号，递增说明持续收到响应
ttl：生存时间，正常值一般在30~128之间
time：往返延迟，数值越小说明网络质量越好
0% packet loss：丢包率为0%，表示本次测试未发生丢包
第一个Hello World程序¶
搭建开发环境¶
登录到Quectel Pi H1的Debian系统后，打开终端窗口，输入以下命令并回车，安装必要的开发环境：
sudo apt update && sudo apt install gcc make
编译与运行helloworld（C语言版）¶
打开系统终端，输入以下命令创建 hello.c 文件。
touch hello.c
输入以下命令，使用 nano 编辑器打开 hello.c 文件。
sudo nano hello.c
将下列代码复制到 hello.c 文件中，依次按 Ctrl+O 和 Enter 键保存，然后按 Ctrl+X 退出 nano 编辑器。
#include <stdio.h>
int main(void)
{
printf("hello world\r\n");
return 0;
}
执行以下命令，编译代码：
gcc hello.c -o hello
执行以下命令，运行hello程序：
./hello
程序运行结果如下：
./hello
hello world
编译与运行helloworld（Python版）¶
除了C语言，还可以使用Python快速实现Hello World程序。系统已预装Python环境，无需额外安装解释器。
打开系统终端，在终端输入以下命令创建 hello.py 文件。
touch hello.py
在系统中打开 Files 管理器，然后在 Home 目录下双击打开 hello.py 文件。
复制以下代码，并将其粘贴到 hello.py 文件中：
def main():
print("Hello, World!")
if __name__ == "__main__":
main()
Python是解释型语言，无需编译，直接执行即可：
python3 hello.py
程序运行结果如下：
python3 hello.py
Hello, World!
用途¶
Hello World程序可用于验证开发环境是否搭建成功。通过编写和运行简单的C语言或Python程序，可以检查编译器、运行时环境等是否正常工作，也可将其作为嵌入式开发的入门练习。
安全关机与重启¶
Quectel Pi H1支持通过桌面图形界面、命令行和物理按键三种方式安全关机或重启。
通过桌面图形界面关机¶
如果您使用外接显示器并处于桌面环境中：
点击桌面右上角的系统菜单。
选择 关机（Power Off） 或 重启（Restart）。
通过命令行关机¶
在终端（本地终端、SSH或ADB shell）中执行以下命令：
关机
sudo poweroff
重启
sudo reboot
通过物理按键关机¶
长按Quectel Pi H1右侧的 PWRKEY 按钮（约3~5秒），系统将执行安全关机流程。
备注
请等待系统指示灯LED1（绿色）熄灭后再断开电源线。该指示灯熄灭表示系统已停止运行，此时可以安全断电。
后续学习建议¶
完成入门操作后，可继续了解以下内容：