其他问题¶

设备发烫严重怎么办？¶

先确认温度是否过高¶

执行以下命令获取各系统模块的温度（芯片结温）：

qpi-config dump temperature

若芯片结温温度超过85 °C，建议采取降温措施。

定位发热源¶

排查CPU：

# 查看CPU占用率
top -b -n 1 | head -n -20

# 查看各核心频率（确认是否持续保持在最高频率）
cat /sys/devices/system/cpu/cpu[0-9]*/cpufreq/scaling_cur_freq

# 查看是否启用了performance调度器
cat /sys/devices/system/cpu/cpu[0-9]*/cpufreq/scaling_governor

排查GPU：

cat /sys/class/kgsl/kgsl-3d0/gpu_busy_percentage 
cat /sys/class/kgsl/kgsl-3d0/max_gpuclk

# 或者新版基线使用以下命令
cat /sys/kernel/debug/dri/0/perf
cat /sys/class/devfreq/3d00000.gpu/cur_freq
cat /sys/class/devfreq/3d00000.gpu/governor
cat /sys/class/devfreq/3d00000.gpu/available_frequencies
cat /sys/class/devfreq/3d00000.gpu/trans_stat

排查NPU：

查看是否运行涉及大量NPU计算的进程。若需查看NPU负载，请联系移远通信技术支持获取固件，可参考其他问题。

排查存储：

# 查看%util
iostat -x 1 3   

# 若报错无iostat命令，可使用以下命令安装
sudo apt update
sudo apt install sysstat -y

软件层面降温措施¶

检查是否存在异常进程：

ps aux --sort=-%cpu | head -n -10

# 或者
top -b -n 1 | head -n 20

降低CPU频率（此处以 cpu0 为例）：

# 查看可用频率
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies

# 设定最大频率（例如1.65 GHz）
echo 1651200 | sudo tee /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq

切换CPU调度器为schedutil：

echo schedutil > sudo tee /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

降低GPU最高运行频率：

# 查看可用频率
cat /sys/class/kgsl/kgsl-3d0/devfreq/available_frequencies

# 设定最大频率（例如550 MHz）
echo 550000000 > sudo tee /sys/class/kgsl/kgsl-3d0/devfreq/max_freq

上述通过 /sys 节点的调频属于临时生效策略，设备重启后配置将丢失。如需量产固化，请在系统开机自启脚本中加载上述命令，或在 /etc/thermal-engine.conf 中调整降频温控触发点。

物理散热措施¶

确保Quectel Pi H1所处的工作环境通风良好：温度范围（建议-20 °C ~ +50 °C）以及风道流速（建议≥ 0.7 m/ s）；
增加被动散热，如导热材料 + 散热片；
部署外部主动散热模块，当设备温度超过设定阈值时，风扇将自动提高转速以强化散热。CPU散热风扇详见支持配件。

库使用异常怎么办？¶

确认异常现象并定性¶

链接错误：编译时出现 cannot find -lxxx，或运行时出现 cannot open shared object file；
运行时崩溃：抛出 undefined symbol: xxx 或触发 Segmentation fault；
功能异常：库加载成功，但调用特定API时无响应或返回异常错误码。

检查库文件是否存在及其搜索路径¶

# 1. 查找库文件
find /usr/lib /usr/lib64 /usr/local/lib /lib -name "libxxx.so*"

# 2. 检查动态链接器是否能够识别该库
ldconfig -p | grep libxxx

# 3. 检查LD_LIBRARY_PATH是否包含该路径
echo $LD_LIBRARY_PATH

若库文件存在于非标准路径，需设置 LD_LIBRARY_PATH 环境变量，或在 /etc/ld.so.conf.d/ 目录中添加对应路径配置文件，并执行 ldconfig 命令以更新缓存。

检查依赖关系解决“未定义符号”¶

# 查看该库依赖哪些其他库（比ldd更安全，不会执行代码）
readelf -d /path/to/libxxx.so | grep NEEDED

# 检查符号是否存在于该库中
nm -D /path/to/libxxx.so | grep "  T " | grep symbol_name

# 或
readelf -s /path/to/libxxx.so | grep symbol_name

若符号未定义，通常表明库版本不匹配或存在缺失的依赖库；若符号存在但应用程序仍报错，则可能是链接顺序问题或ABI不一致所致。

检查库版本与ABI兼容性¶

# 查看库的实际版本字符串
strings /path/to/libxxx.so | grep -i version

# 查看库的SONAME（链接器使用的名字）
readelf -d /path/to/libxxx.so | grep SONAME

若应用程序在构建时链接到 libxxx.so.1，而系统仅提供 libxxx.so.2，即使新版库包含所需符号，ABI不兼容仍可能导致应用程序在运行时崩溃。确认两个库版本的ABI兼容后，可创建符号链接（ln -s libxxx.so.2 libxxx.so.1）作为临时解决方案。长期来看，应安装与应用程序兼容的库版本，或基于系统现有的库重新编译应用程序。

跟踪运行时动态库加载过程诊断加载失败¶

# 1. 查看动态链接器加载的库，确认是否加载了错误版本
LD_DEBUG=libs ./your_app 2>&1 | grep libxxx

# 2. 使用strace追踪库文件打开过程
strace -e openat,open ./your_app 2>&1 | grep libxxx

# 3. 若应用程序启动后立即崩溃，使用gdb定位崩溃位置
gdb ./your_app
# 在gdb交互界面中启动运行
(gdb) run
# 崩溃时查看调用栈
(gdb) bt   

如何集成/移植第三方驱动？¶

获取官方SDK，下载方式请参考镜像构建。
在 sources/quectel-src/kernel/qcom-6.6/drivers/ 目录相应模块下添加第三方驱动源码。
参考其他同类驱动完善源码同级目录下的配置文件 Kconfig、Makefile，以及 /sources/quectel-src/kernel/qcom-6.6/arch/arm64/configs/qcom_defconfig。
在 sources/quectel-src/kernel/qcom-6.6/arch/arm64/boot/dts/qcom/qcs6490-idp-pi.dts 文件中添加对应外设的设备树节点。
编译系统镜像并将其烧录至设备，然后进行驱动功能测试。

运行速度慢怎么办？¶

设备运行性能低下，通常并非由单一因素导致，而是 CPU 调度、内存压力、存储 I/O、温度降频、软件配置等多种因素交织作用的结果。

快速定位瓶颈¶

# 1. 查看系统整体负载（1/ 5/ 15分钟）
uptime
# 如果load average长期>CPU核心数（8核>8.0），说明CPU资源不足

# 2. 查看CPU使用率分布（用户态/ 系统态/ 软中断/ 空闲）
mpstat -P ALL 1 3

# 3. 查看内存与交换分区（是否用到swap）
free -h
# 如果available<10 %且swap used>0，说明内存不足

# 4. 查看存储I/O瓶颈（%util接近100 %说明磁盘是瓶颈）
cat /proc/diskstats | grep -E 'mmcblk0|sda'

# 5. 查看温度与降频（判断是否发生过热降频，此处以cpu0为例）
qpi-config dump temperature
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq

关键指标判定标准：

温度>95 °C：触发温控降频；
free -h 中available极少：内存不足。

采取针对性优化措施¶

CPU瓶颈（%us或%sy长期>85 % ~ 90 %）¶

查找占用CPU资源最高的进程；
降低相机等外设的负载；
提升关键线程的实时优先级（如调整调度策略）。

内存瓶颈（available极低，且swap used>0）¶

查看内存占用排名前10的进程（Top 10）；
检查page cache与可回收内存，如果page cache很大但可回收，说明内存压力是暂时的，可手动回收；
检查是否存在DMA-BUF或ION内存泄漏。

存储I/O瓶颈（iostat中%util接近100 %）¶

查找写入I/O最多的进程；
减少不必要的日志写入；
检查异常：小文件频繁写、日志暴涨、swap颠簸、驱动DMA异常。

温控降频（温度过高导致降频）¶

确认当前是否已触发降频机制；
采取物理或软件层面的主动散热措施。

如何设置开机启动？¶

systemd 是现代Linux发行版（包括配置了 systemd 的Yocto镜像）的主流服务管理机制。它提供了强大的依赖管理、自动重启、环境变量配置等功能。

创建服务单元文件¶

在 /etc/systemd/system/ 目录下创建.service文件，例如 my-camera.service：

[Unit]
Description=My Camera Service
# 在网络启动后启动（按需调整）
After=network.target

[Service]
# 或forking、oneshot等
Type=simple
ExecStart=/usr/bin/my_script.sh
# 自动重启
Restart=on-failure
# 指定运行用户（通常为root）
User=root
WorkingDirectory=/opt/my_app

[Install]
# 在系统进入多用户模式时启动
WantedBy=multi-user.target

启用并启动服务¶

# 重新加载systemd配置
sudo systemctl daemon-reload

# 启用开机自启（创建符号链接）
sudo systemctl enable my-camera.service

# 立即启动（可选）
sudo systemctl start my-camera.service

# 查看服务状态
sudo systemctl status my-camera.service

如何动态加载/ 卸载第三方驱动？¶

获取驱动模块文件：获取第三方驱动源码，并在与设备内核版本匹配的环境中进行交叉编译，生成.ko驱动模块文件；
传输驱动文件：将编译好的.ko文件通过scp、adb或U盘等方式传输至设备。
加载与卸载驱动：
执行 insmod 加载驱动：

sudo insmod your_driver.ko

执行 rmmod 卸载驱动：

sudo rmmod your_driver

执行 lsmod 查看当前系统已加载的所有模块：

lsmod

未找到解决方案怎么办？¶

访问常见问题页面： https://www.quectel.com.cn/faqs
前往技术论坛提问： https://forumschinese.quectel.com/