# 定位

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

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

# 测试环境确认

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

| <div style="text-align: center"><br><strong>项目</strong><br></div> | <div style="text-align: center"><br><strong>结果</strong><br></div> | <div style="text-align: center"><br><strong>说明</strong><br></div> |
| --- | --- | --- |
| `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 天线，并尽量将天线放置在室外、窗边或无遮挡位置。室内、屏蔽环境、天线未连接或天线方向不正确，都可能导致长时间无法搜星或无法定位。

**硬件连接示意图：**

```{image} images/image_EJEpb3qfOo4LrSxq1VwcghZDnsd.webp
:width: 1397px
:height: 911px
:align: center
```

**GNSS 天线：**

```{image} images/image_Kcv0bCF6eo6R3DxvwImceqa2nGe.webp
:width: 800px
:height: 800px
:align: center
```

# 工具区别

| <div style="text-align: center"><br><strong>工具</strong><br></div> | <div style="text-align: center"><br><strong>主要用途</strong><br></div> | <div style="text-align: center"><br><strong>是否推荐用于定位验收</strong><br></div> |
| --- | --- | --- |
| `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. 确认工具存在

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

正常情况下应输出：

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

## 2. 查看 garden_app 帮助

```bash
adb shell 'garden_app -h'
```

重点关注以下参数：

| <div style="text-align: center"><br><strong>参数</strong><br></div> | <div style="text-align: center"><br><strong>含义</strong><br></div> | <div style="text-align: center"><br><strong>建议</strong><br></div> |
| --- | --- | --- |
| `-t` | 定位 session 的最长等待时间，单位为秒。 | 首次测试建议设置为 `120` 秒。 |
| `-n` | 打印 NMEA 字符串、时间戳和长度。 | 建议打开，便于确认 GNSS 输出。 |
| `-y` | 打印可见卫星的详细信息。 | 建议打开，便于判断是否搜星。 |
| `-o` | 设置 TTFF 阈值，超过阈值会判定失败。 | 可设置为 `120`，用于定位验收。 |
| `-A` | 配合 `-B` 使用，表示看到的最少卫星数量。 | 快速搜星测试可设为 `4`。 |
| `-B` | 配合 `-A` 使用，表示每颗卫星的最小 SNR / CN0 门限。 | 快速搜星测试可设为 `28`。 |

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

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

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

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

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

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

```bash
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 定位能力（可选）

```bash
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 等。

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

```bash
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 配置和定位服务日志。

# 常见问题排查

| <div style="text-align: center"><br><strong>现象</strong><br></div> | <div style="text-align: center"><br><strong>可能原因</strong><br></div> | <div style="text-align: center"><br><strong>建议排查</strong><br></div> |
| --- | --- | --- |
| 找不到 `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`。