定位

Quectel Pi 开发板支持 GNSS 定位功能。本文说明板端内置定位测试工具的用途区别、硬件连接注意事项，以及推荐的 GNSS 定位测试命令。

💡 测定位优先使用 garden_app。qlril-api-test 主要用于 QLRIL / 蜂窝通信 API 测试，虽然也包含简单 GNSS 菜单，但不建议作为定位验收的首选工具。

测试环境确认

当前开发板通过 ADB 连接后确认如下：


项目


结果


说明

garden_app

/usr/bin/garden_app

板端已内置 Qualcomm GNSS Garden 测试程序。

qlril-api-test

/usr/bin/qlril-api-test

板端已内置 Quectel QLRIL API 测试工具。

ModemManager 定位能力

gps-raw、gps-nmea、agps-msa、agps-msb

通过 mmcli -m 0 --location-status 可查询。

硬件连接

测试 GNSS 前，请确认开发板已正确连接 GNSS 天线，并尽量将天线放置在室外、窗边或无遮挡位置。室内、屏蔽环境、天线未连接或天线方向不正确，都可能导致长时间无法搜星或无法定位。

硬件连接示意图：

../../_images/image_EJEpb3qfOo4LrSxq1VwcghZDnsd.webp

GNSS 天线：

../../_images/image_Kcv0bCF6eo6R3DxvwImceqa2nGe.webp

工具区别


工具


主要用途


是否推荐用于定位验收

garden_app

Qualcomm GPS/GNSS Garden 测试程序，用于测试 LOC API HAL、GNSS 定位、NMEA、卫星信息、TTFF 等。

推荐。

qlril-api-test

Quectel QLRIL API 测试工具，主要测试 SIM、运营商、信号、语音、短信、数据拨号和 RIL 相关能力；也包含简单 GNSS 菜单。

不作为首选，仅用于 QLRIL/GNSS 接口辅助验证。

qlril-api-test 中 GNSS 相关菜单包括 QLRIL_GNSS_CLIENT_OPEN、QLRIL_GNSS_NEMA_TYPE、QLRIL_GNSS_START_FIX、QLRIL_GNSS_STOP_FIX、QLRIL_GNSS_CLIENT_CLOSE 和 QLRIL_GNSS_NEMA_GetLocation。这些接口更适合验证 Quectel RIL API 对 GNSS 的封装，而不是完整定位体验测试。

推荐测试方法：garden_app

1. 确认工具存在

adb shell 'command -v garden_app; command -v qlril-api-test'

正常情况下应输出：

/usr/bin/garden_app
/usr/bin/qlril-api-test

2. 查看 garden_app 帮助

adb shell 'garden_app -h'

重点关注以下参数：


参数


含义


建议

-t

定位 session 的最长等待时间，单位为秒。

首次测试建议设置为 120 秒。

-n

打印 NMEA 字符串、时间戳和长度。

建议打开，便于确认 GNSS 输出。

-y

打印可见卫星的详细信息。

建议打开，便于判断是否搜星。

-o

设置 TTFF 阈值，超过阈值会判定失败。

可设置为 120，用于定位验收。

-A

配合 -B 使用，表示看到的最少卫星数量。

快速搜星测试可设为 4。

-B

配合 -A 使用，表示每颗卫星的最小 SNR / CN0 门限。

快速搜星测试可设为 28。

3. 测试是否能正常输出定位结果

如果目标是确认“是否能定位出经纬度”，建议使用以下命令：

adb shell 'garden_app -n -y -t 120 -o 120'

观察输出中是否出现 location callback、经纬度、TTFF 等信息。如果有定位结果，并且 TTFF 在预期范围内，说明 GNSS 定位链路基本正常。

4. 快速确认是否能搜到卫星

如果只是想快速确认天线、射频和 GNSS 搜星能力，可以使用 -A 和 -B：

adb shell 'garden_app -n -y -t 120 -A 4 -B 28'

该命令的含义是：在测试过程中，如果看到至少 4 颗卫星，并且这些卫星的 SNR / CN0 不低于 28，则可以提前结束测试。

💡 -A 4 -B 28 只能说明已经看到满足门限的卫星，用于节省测试时间；它不等同于已经输出经纬度定位点。如果验收标准要求真实定位结果，应以 location callback、经纬度和 TTFF 为准。

5. 查看 ModemManager 定位能力（可选）

adb shell 'mmcli -L'
adb shell 'mmcli -m 0 --location-status'

如果输出中包含 gps-raw、gps-nmea、agps-msa、agps-msb，说明 ModemManager 能看到 modem 暴露的定位能力。但 BSP/GNSS 功能验收仍建议以 garden_app 为主。

qlril-api-test 的用途

qlril-api-test 启动后会进入交互菜单，主要用于测试 QLRIL API。其功能范围包括：

  • 通用接口：初始化、退出、版本查询、AT 命令发送等。

  • SIM 和网络：IMSI、IMEI、ICCID、运营商、信号强度、注册状态等。

  • 语音和短信：拨号、接听、挂断、短信发送等。

  • 数据业务：数据注册状态、建立/断开数据连接、RNDIS 等。

  • GNSS 辅助接口：打开 GNSS client、设置 NMEA 类型、开始/停止 fix、获取 location 等。

如果需要进入该工具查看菜单，可执行：

adb shell 'qlril-api-test'

GNSS 相关菜单编号一般为 90 到 95，但由于它是交互式 QLRIL API 测试工具，操作步骤较分散，不适合作为普通定位验收的首选路径。

建议验收流程

  1. 确认 GNSS 天线已连接，天线位置无遮挡，开发板供电稳定。

  2. 执行 adb shell 'command -v garden_app'，确认板端内置 garden_app。

  3. 执行 adb shell 'garden_app -n -y -t 120 -o 120'，观察是否输出定位点、NMEA 和 TTFF。

  4. 如果长时间没有定位点，执行 adb shell 'garden_app -n -y -t 120 -A 4 -B 28'，先判断是否能看到满足门限的卫星。

  5. 若看不到卫星，优先检查天线、测试环境和 GNSS 相关日志；若能看到卫星但不能定位，再继续分析辅助数据、时间同步、SUPL/XTRA 配置和定位服务日志。

常见问题排查


现象


可能原因


建议排查

找不到 garden_app

rootfs 未集成 garden-app 包。

确认 garden-app 包是否安装，检查镜像 packagegroup 是否包含 garden-app。

能运行但长时间无卫星

天线未接、天线位置差、室内遮挡严重或 GNSS 射频链路异常。

检查天线连接，移动到室外或窗边，查看 -y 输出的 SV 信息。

能看到卫星但无定位点

卫星质量不足、时间/辅助数据不足、配置问题或定位服务异常。

延长测试时间，观察 TTFF 和 NMEA，检查 /etc/gps.conf、时间同步和定位日志。

-A 4 -B 28 通过但没有经纬度

该参数组合只按卫星数量和信噪比提前停止，不要求真实 fix。

使用 garden_app -n -y -t 120 -o 120 重新确认真实定位结果。

想验证蜂窝/RIL 功能

测试目标不是 GNSS 定位，而是 modem/RIL API。

使用 qlril-api-test，按菜单选择 SIM、信号、数据拨号或 AT 命令相关项目。

结论

当前开发板已内置 garden_app 和 qlril-api-test。如果测试目标是 GNSS 定位功能，应优先使用 garden_app；如果测试目标是 SIM、信号、拨号、短信或数据业务等 RIL 功能，再使用 qlril-api-test。