# 首次启动 ***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按钮手动开机 | ```{image} images/image_OCBtbHlCEof9Y0xnncFc488LnTf.webp :width: 600px :height: 373px ``` ```{image} images/image_Wm9mbdR9aoaZujxAoQocEHF4nCY.webp :width: 1101px :height: 756px :align: center ``` ```{note} 若未短接AUTO_POWER_ON，上电后需要长按PWRKEY按钮才能启动系统。 ``` # 选择使用场景 Quectel Pi H1智能主控板出厂默认搭载Debian 13系统镜像，通常无需重新烧录镜像。请根据设备条件选择相应的启动方式： | **场景** | **适用条件** | **跳转** | | --- | --- | --- | | **有外接显示器** | 有HDMI / USB-C DP / MIPI显示器、键盘鼠标 | [外接显示器启动Quectel Pi H1](#外接显示器启动quectel-pi-h1) | | **无外接显示器** | 未配备显示器，但有一根USB-C数据线和一台电脑 | [无显示器启动Quectel Pi H1](#无显示器启动quectel-pi-h1) | ## 外接显示器启动Quectel Pi H1 ### 硬件连接 ```{image} images/image_FOBVbgsgzocYBAxD7obcxoV2nde.webp :width: 833px :height: 521px :align: center ``` 1. **显示连接**：需根据显示器的接口选择以下连接方案之一，上图以方案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](<../../使用指南/显示/MIPI/MIPI.md>)。 2. **网络连接**：将千兆网线的一端接入Quectel Pi H1千兆网口，另一端接入路由器网口（替代方案：通过Wi-Fi接入，参考 [配置Wi-Fi](<../../操作系统/Debian/qpi-config/qpi-config.md#配置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分钟，显示器将显示系统登录界面。 ```{note} 若硬件连接时，没有将标有 **AUTO_POWER_ON** 丝印的排针使用跳线帽短接，则需要先长按Quectel Pi H1右侧的 **PWRKEY按钮，再接通电源，直到系统启动。若系统无法正常启动，请重新烧录系统镜像**： 1. [点此下载Debian 13镜像]()； 2. [点此下载和安装USB驱动]()； 3. 使用符合要求的电源适配器给Quectel Pi H1供电； 4. 将智能主控板的USB & DP接口连接到电脑； 5. [点此查看安装系统教程](<../../操作系统/Debian/安装系统/安装系统.md#>)。 ``` ### 系统登录 有关用户名和密码的设置方法，请参考 [系统登录](<../../操作系统/Debian/系统登录/系统登录.md>)。 ```{note} 1. ***root*** 账户默认无密码，需自行设置。 2. 若创建用户时误入 **Enterprise Login** 界面无法退出，可再次点击 **Enterprise Login** 切回用户创建界面。 ``` ```{image} images/image_WYDtbMvFJoswGDxaz7ic823znre.webp :width: 1280px :height: 960px ``` ### 网络配置 选择要连接的Wi-Fi网络，输入密码后进行连接。 ```{image} images/image_D3jSbc0JGoIRHPxouXqcPoSBnMb.webp :width: 962px :height: 630px ``` ### 进入终端命令行 ```{image} images/image_FQKPbipw0o0jY7x7JjvcXPSvnrc.webp :width: 1675px :height: 954px :align: center ``` ## 无显示器启动Quectel Pi H1 如果Quectel Pi H1未连接显示器、键盘和鼠标，可以通过另一台电脑远程控制该设备。 要远程控制Quectel Pi H1，需先将其接入网络，再通过另一台设备上的客户端进行访问。SSH用于远程访问命令行终端，VNC用于远程访问图形化桌面。若设备尚未联网，可先通过 **ADB** 完成初始网络配置。 有关更多远程访问方式，请参考 [设备连接](<../../使用指南/设备连接/设备连接.md>)。 | **方式** | **说明** | **前置条件** | **教程链接** | | --- | --- | --- | --- | | VNC | 远程访问图形化桌面 | 设备已联网 | [VNC远程桌面](<../../使用指南/设备连接/VNC远程桌面/VNC远程桌面.md>) | | SSH | 远程访问命令行终端 | 设备已联网 | [SSH远程终端](<../../使用指南/设备连接/SSH远程终端/SSH远程终端.md>) | ```{note} 首次启动时，建议先通过ADB完成Wi-Fi配置，然后即可使用VNC或SSH进行日常操作。 ``` ### ADB连接Quectel Pi H1 此方法可在没有外接显示器的情况下远程登录并控制Quectel Pi H1。 下载ADB工具：[platform-tools]()。 ### ADB安装 将下载的 *platform-tools* 解压到电脑上的指定文件夹。 ### 确认ADB设备已识别 ```{image} images/image_Q0Qhbj9e5o9k6LxB3w2ckX6Dncf.webp :width: 775px :height: 461px :align: center ``` 用USB Type-C线连接Quectel Pi H1与电脑，在ADB工具目录中打开终端并执行以下命令： ```bash adb devices ``` 输出示例： ```plaintext List of devices attached 790c2fb9 device ``` ```{note} 如果设备状态显示为 *unauthorized*，或未显示任何设备，请检查USB线是否为数据线（非纯充电线），或尝试更换USB接口。 ``` ### ADB连接设备 ```bash adb shell ``` 连接成功后，将以root用户身份进行操作。 ### 创建普通用户 系统默认仅提供root用户，建议创建普通用户用于日常操作。 **创建用户** 以下以创建pi用户为例，您也可以指定其他用户名。 ```bash adduser pi #此处pi为创建的用户名称 ``` 系统会提示您设置密码，请按提示输入两次密码。 ```{image} images/image_F6Nvb3z5XoIRo5xvzUWcsLncnTd.webp :width: 437px :height: 208px :align: center ``` 用户创建完成后，系统会自动将 */home/用户名* 创建为该用户的家目录。后续可在此目录下存放个人文件和项目代码等内容。 **赋予*sudo*****权限** ```bash usermod -aG sudo pi ``` **切换用户** ```bash #验证用户 id pi #切换用户 su - pi #测试权限 whoami sudo whoami #应输出root，验证sudo权限 ``` ### 连接Wi-Fi Quectel Pi H1内置qpi-config工具，可用于管理Wi-Fi连接。 **扫描周围Wi-Fi网络** ```bash qpi-config wifi scan ``` ```{image} images/image_IvCcb7YTjomzblxlRAkc1kV8nrc.webp :width: 785px :height: 202px :align: center ``` **连接Wi-Fi** ```bash #连接Wi-Fi qpi-config wifi connect "你的Wi-Fi名称" "你的Wi-Fi密码" #查看已保存的Wi-Fi连接 qpi-config wifi show #删除已保存的Wi-Fi连接 qpi-config wifi remove ``` ```{image} images/image_RwA3bAW26oyypJxtrfLcFge8nsg.webp :width: 650px :height: 105px :align: center ``` **验证网络连通性** ```bash ping www.baidu.com ``` ### SSH连接智能主控板 **查看设备IP地址** 在智能主控板终端中执行 *ifconfig* 命令，获取设备的IP地址。 示例中查询到的设备IP为 *10.55.101.49*。 ```{image} images/image_QrypbY1Ulora5NxshHMcTl6wnGb.webp :width: 601px :height: 461px :align: center ``` **使用QPiTerminal工具SSH连接智能主控板** 打开 **QPiTerminal** 并新建 **SSH** 会话，输入智能主控板的 **IP** 地址、用户名和密码，然后点击 **连接**。 ```{image} images/image_EpTob048VoWJz8xpu3ocv3z5n6g.webp :width: 1499px :height: 808px :align: center ``` ```{image} images/image_X2AfbRT7QomUEcxMsszc4XiGnJg.webp :width: 1506px :height: 813px :align: center ``` # 系统健康检查 系统启动后，在终端通过 ***qpi-config*** 命令快速检查系统状态。 ## 查询系统各模块温度 ```bash sudo qpi-config dump temperature ``` ```{image} images/image_O297bHZ7LozseOxJWuncNrV2ndh.webp :width: 901px :height: 513px :align: center ``` ## 查询系统CPU、内存和存储状态 ```bash sudo qpi-config dump systemusage ``` ```{image} images/image_X3Nob1b6YonZFNx30PRcQs7An9c.webp :width: 898px :height: 334px :align: center ``` ## 网络状态检查 通过网线或Wi-Fi将设备接入网络后，使用 **ping** 命令确认设备能正常访问外部网络。 ```bash ping www.baidu.com ``` **正常连通输出示例：** ```plaintext 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 ``` ```{note} **标识说明：** *64 bytes from ...*：收到ICMP应答（reply），表示网络连通正常 *icmp_seq*：序列号，递增说明持续收到响应 *ttl*：生存时间，正常值一般在30~128之间 *time*：往返延迟，数值越小说明网络质量越好 *0% packet loss*：丢包率为0%，表示本次测试未发生丢包 ``` ```{image} images/image_JwFabhw1QorqzCxE2L7cqLT2noh.webp :width: 478px :height: 248px :align: center ``` # 第一个Hello World程序 ## 搭建开发环境 登录到Quectel Pi H1的Debian系统后，打开终端窗口，输入以下命令并回车，安装必要的开发环境： ```bash sudo apt update && sudo apt install gcc make ``` ## 编译与运行helloworld（C语言版） 1. 打开系统终端，输入以下命令创建 *hello.c* 文件。 ```bash touch hello.c ``` 2. 输入以下命令，使用 ***nano*** 编辑器打开 *hello.c* 文件。 ```bash sudo nano hello.c ``` 3. 将下列代码复制到 *hello.c* 文件中，依次按 **Ctrl+O** 和 **Enter** 键保存，然后按 **Ctrl+X** 退出 ***nano*** 编辑器。 ```c #include int main(void) { printf("hello world\r\n"); return 0; } ``` 1. 执行以下命令，编译代码： ```bash gcc hello.c -o hello ``` 5. 执行以下命令，运行hello程序： ```bash ./hello ``` 6. 程序运行结果如下： ```plaintext ./hello hello world ``` ## 编译与运行helloworld（Python版） 除了C语言，还可以使用Python快速实现Hello World程序。系统已预装Python环境，无需额外安装解释器。 1. 打开系统终端，在终端输入以下命令创建 *hello.py* 文件。 ```bash touch hello.py ``` 2. 在系统中打开 **Files** 管理器，然后在 *Home* 目录下双击打开 *hello.py* 文件。 3. 复制以下代码，并将其粘贴到 *hello.py* 文件中： ```python def main(): print("Hello, World!") if __name__ == "__main__": main() ``` 4. Python是解释型语言，无需编译，直接执行即可： ```bash python3 hello.py ``` 5. 程序运行结果如下： ```plaintext python3 hello.py Hello, World! ``` ## 用途 Hello World程序可用于验证开发环境是否搭建成功。通过编写和运行简单的C语言或Python程序，可以检查编译器、运行时环境等是否正常工作，也可将其作为嵌入式开发的入门练习。 # 安全关机与重启 Quectel Pi H1支持通过桌面图形界面、命令行和物理按键三种方式安全关机或重启。 ## 通过桌面图形界面关机 如果您使用外接显示器并处于桌面环境中： 1. 点击桌面右上角的系统菜单。 2. 选择 **关机（Power Off）** 或 **重启（Restart）**。 ```{image} images/image_PEAMbp5B1o6oUqxgzGSctUmAnAH.webp :width: 1920px :height: 1080px :align: center ``` ## 通过命令行关机 在终端（本地终端、SSH或ADB shell）中执行以下命令： **关机** ```bash sudo poweroff ``` **重启** ```bash sudo reboot ``` ## 通过物理按键关机 长按Quectel Pi H1右侧的 **PWRKEY** 按钮（约3~5秒），系统将执行安全关机流程。 ```{note} 请等待系统指示灯LED1（绿色）熄灭后再断开电源线。该指示灯熄灭表示系统已停止运行，此时可以安全断电。 ``` # 后续学习建议 完成入门操作后，可继续了解以下内容： - [支持配件](<../../支持配件/支持配件.md>) - [使用指南](<../../使用指南/使用指南.md>) - [操作系统](<../../操作系统/操作系统.md>) - [应用开发](<../../应用开发/应用开发.md>) - [边缘计算](<../../边缘计算/边缘计算.md>) - [开发工具](<../../开发工具/开发工具.md>) - [支持清单](<../../支持清单/支持清单.md>) - [FAQ](<../../FAQ/FAQ.md>)