快速入门

2026-03-12

开箱准备

本章以Quectel Pi H1开发套件为基础，讲解如何快速入门Quectel Pi H1智能主控板。

产品实物

产品俯视图和底视图

image-20251030173916369 image-20251030173942597

所需配件

  • 全套Quectel Pi H1开发套件（按“套件清单”核对无缺失）。

  • 支持5V/5A、9V/3A或PD快充协议的电源适配器。

  • 支持USB-C DP或HDMI的显示器（分辨率建议1080P及以上）。

  • USB键盘+鼠标（有线/无线均可，需接入智能主控板的USB口）。

  • 可联网的路由器（用于智能主控板联网调试）。

注意事项

  • 硬件使用规范（避免损坏）

    • 请使用套件自带的USB-A电源线（5A），禁止使用低于3A电流的电源（如手机充电器），否则可能导致智能主控板供电不足、频繁死机；若需外接大功率模块（如电机），需单独为模块供电，禁止通过智能主控板USB口或GPIO口取电（避免过载烧板）。

    • 插拔配件（如摄像头排线、网线）时必须先断开智能主控板的电源，带电插拔可能烧毁接口芯片；USB&DP接口仅支持DP显示+供电输出，不可给智能主控板供电。

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

  • 系统与软件注意事项

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

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

    • 禁止修改 /boot分区下的核心配置文件（如config.txt），误修改可能导致系统无法启动（建议修改前备份该文件）。

    • 安装软件时优先使用apt命令从官方源下载，避免安装未知来源的DEB包，防止系统中毒或崩溃。

硬件连接

⚠️ 警告:连接过程中请先断开所有电源，避免带电插拔接口导致硬件损坏！

Quectel Pi H1智能主控板出厂默认搭载Debian 13系统镜像，因此无需再次烧录镜像。仅需按照如下步骤操作即可：

显示连接

  • 方案1（高清）：将USB-C DP显示线一端接入Quectel Pi H1的USB&DP接口，另一端接入显示器的USB-C接口。

  • 方案2（兼容）：将HDMI线一端接入Quectel Pi H1的HDMI接口，另一端接入显示器的HDMI接口。

外设连接

将USB键盘、鼠标接入Quectel Pi H1的两个USB-A接口上；若用无线键鼠，将接收器插入USB口即可。

网络连接

用网线连接Quectel Pi H1网口和路由器的LAN口即可。

跳线帽连接

Quectel Pi H1左上角标有AUTO_POWER_ON丝印的排针，确保已经用跳线帽短接。

供电连接

最后将USB-A电源线的USB-A端接入电源适配器，USB-C端接入Quectel Pi H1的电源口（通常标注POWER IN）。

散热器安装

先将散热器的排线插入Quectel Pi H1的FAN插槽中，然后将散热器上的两端固定在Quectel Pi H1预留的插孔中。

（注：散热器不包含在开发套件中，推荐使用 树莓派5代官方原装散热器。）

系统启动

启动系统

⚠️ 若硬件连接时，没有将标有AUTO_POWER_ON丝印的排针使用跳线帽短接，则需要先长按Quectel Pi H1右侧的PWRKEY按钮，再接通电源，直到系统启动。

  • 打开显示器电源，确认显示器输入源已切换到对应的接口（如USB-C或HDMI）。
  • 接通Quectel Pi H1电源（插好电源线），此时Quectel Pi H1的电源灯（通常为红色）会常亮，系统灯（通常为绿色）会闪烁，表明系统正在启动。
  • 等待约1~2分钟，显示器将显示系统登录界面。

系统登陆

有关登陆用户名及密码设置，请参考系统登录。

系统更新

打开终端（快捷键Ctrl+Alt+T），输入以下命令更新系统（确保网络已通）：

sudo apt update && sudo apt upgrade -y

‼️若系统无法正常启动，请重刷系统镜像

基础配置

功能验证

启动完成后，快速验证核心配件是否正常工作：

  • 显示验证：确认显示器能清晰显示桌面，拖动窗口无卡顿、无花屏；
  • 网络验证：打开浏览器，输入任意网址（如www.baidu.com/www.google.com），或在终端输入ping 8.8.8.8（测试通外网），若有数据包返回则网络正常；
  • USB外设验证：用键盘输入字符、鼠标拖动窗口，确认键鼠响应正常。

区域设置

  • 系统语言：打开设置配置中文显示，设置好后重新登陆即可生效。
image-20251030165658517
  • 输入法编辑器及键盘布局：使用系统默认配置即可
image-20251030172026557

网络设置

根据Wi-Fi名称输入密码连接。

​

串口控制台

硬件连接

⚠️使用USB串口数据线和智能主控板进行串口登录时，请确保引脚连接正确，接错引脚可能会导致智能主控板硬件损坏。

​ image-20251031103814248

  • 连接方式

    • Quectel Pi H1智能主控板的GND引脚连接USB串口数据线的GND引脚
    • Quectel Pi H1智能主控板的DBG_TXD引脚连接USB串口数据线的RXD引脚
    • Quectel Pi H1智能主控板的DBG_RXD引脚连接USB串口数据线的TXD引脚

  • 使用跳线帽在USB转TTL串口小板上选择3.3 V电源

串口登录

前提：系统必须要先安装CH340驱动，要不然无法识别串口。

推荐使用PuTTY软件进行串口连接。

1.打开设备管理器查看串口。

image-20251101173133135

2.双击打开PuTTY，配置为USB串口并设置波特率为115200，然后点击Open。

3.在终端输入系统的用户名和密码进行登陆（终端输入密码不会显示出来，输入完密码按Enter登陆）。

image-20251101180334693

4.登陆成功后，即可通过串口查看日志及运行命令进行调试 。

用途

串口控制台主要用于通过串口连接查看系统日志、运行命令进行调试，以及在图形界面不可用时作为系统访问的备用方式。它是嵌入式Linux系统开发和维护的重要工具，特别适用于底层调试和故障排查。

HelloWorld

搭建开发环境

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

sudo apt update && sudo apt install vim gawk gcc g++ build-essential chrpath socat wget diffstat file unzip tar locales zstd debianutils iputils-ping cpio python3 python3-pip net-tools git make cmake

编译与运行helloworld

  1. 在 /Desktop目录下创建helloworld.c文件。

  2. 复制以下代码段，粘贴在helloworld.c文件内：

#include <stdio.h>
int main(void)
{
    printf("hello world\r\n");
    return 0;
}
  1. 执行以下命令，编译代码：
$ cd Desktop/
$ gcc helloworld.c -o helloworld
  1. 执行以下命令，运行helloworld程序：
$ ./helloworld
  1. 程序运行结果打印：
$ ./helloworld
$ hello world

交叉编译

交叉编译是在一种平台（如x86 PC）上，生成可以在另一种不同体系结构的平台（如ARM嵌入式设备）上运行的可执行程序。

准备工作

  • 一台32/64位主机计算机，用于编译代码。
  • 一块Quectel Pi H1智能主控板，用于运行可执行程序。

以64位计算机为例，在主机上执行如下步骤：

安装ARM64工具链

sudo apt update
sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

验证安装

$ aarch64-linux-gnu-gcc --version

img

创建代码文件

$ touch  hello.c
$ sudo vim hello.c

按下ESC + i，输入下面代码，然后再按下ESC + "shift + : " ,在命令台输入“wq + Enter”保存退出。

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

编译代码文件

$ aarch64-linux-gnu-gcc -o 生成编译文件名 原文件名
例：aarch64-linux-gnu-gcc -o hello_arm64 hello.c

检查文件架构

$ file 文件名

编译成功如下所示：

img

上传编译文件

将主机上的编译文件下载到本地，然后在Windows控制台通过SCP命令上传编译文件至Quectel Pi H1智能主控板。

#注：主机编译文件的存放路径不要使用中文
scp -O /本地/文件 username@远程IP:/目标路径/
例：scp -O D:\hello_arm64 pi@192.168.x.x:/home/pi
img

运行编译文件

在Quectel Pi H1智能主控板终端上为编译文件设置权限并执行。

sudo chmod 777 文件名

img

用途

HelloWorld程序主要用于验证开发环境搭建是否成功，通过编写、编译和运行一个简单的C语言程序来测试系统的基本功能，包括编译器、运行时环境等是否正常工作，是嵌入式开发入门的基础实践。

更多功能