Maps 地图使用说明
Maps 显示 OpenStreetMap 地图，支持拖动、缩放、地址搜索和当前位置定位。 它优先使用 nRF9151 GNSS 坐标，无法获得有效定位时使用公网 IP 的近似位置。
使用前准备
- 安装 Maps，确保系统提供 curl、CA 证书及应用运行库。
- 下载新地图、地址搜索和 IP 定位需要联网。
- 精确 GNSS 定位需要兼容 Nordic SLM 固件的 nRF9151、可访问的串口和接收条件良好的 GNSS 天线。
- 室内或天线遮挡时可能长时间无法获得 GNSS 坐标；仅收到卫星信息不代表已经定位。
- 地图缓存目录需要可写，串口访问需要相应系统权限。
浏览与搜索
- 从启动器打开 Maps，等待地图加载，查看状态中当前使用的定位来源。
- 拖动地图查看其他区域，使用 + / − 缩放。
- 点击 Search address，输入中文或英文地址，然后提交搜索。
- 搜索成功后，地图会定位到第一个结果；无结果或网络错误会保留原来的地图中心。
- 点击定位图标，返回有效 GNSS 坐标或本次会话最近成功的 IP 位置。
实体键盘可输入地址，方向键移动光标，Backspace 删除，Enter 搜索，Esc 退出编辑。 手动拖动、缩放或搜索后，自动跟随位置会暂停；再次点击定位按钮恢复。 应用提供地图浏览和地点查找，没有路线规划或逐向语音导航界面。
理解定位结果
- GNSS 有效时优先使用 GNSS；定位失效或串口不可用时回退到 IP。
- IP 定位只能估计地区，VPN、代理和共享网络出口会造成明显偏差。
- GNSS 本身可离线工作，但显示新区域的地图仍需要缓存或网络。
- 定位按钮回到 GNSS 时使用缩放级别 16，IP 位置使用级别 11。
- 没有可用坐标时，应用保持当前地图或初始世界视图。
Maps 和 Cellular 不能同时直接占用同一 GNSS 串口。 如果 Cellular 或其他串口工具正在使用模组，Maps 会回退到 IP 并在后台重试。
地图缓存与离线使用
已查看区域的地图瓦片会缓存到磁盘；离线只能查看已经下载过的区域和缩放级别。 应用不会提前下载整座城市，也不提供离线地址搜索。
点击垃圾桶图标打开 Clear map data?，选择 Clear 删除已下载地图，或 Cancel 取消。 清除后离线可用区域也会消失；联网时可重新下载。
| 启动环境 | 默认缓存位置 |
|---|---|
| root 用户 | /root/maps/openstreetmap |
设置了 XDG_CACHE_HOME 的普通用户 | $XDG_CACHE_HOME/lilygo-ui-maps/maps/openstreetmap |
| 其他普通用户 | $HOME/.cache/lilygo-ui-maps/maps/openstreetmap |
管理员可设置 LILYGO_MAPS_CACHE_DIR 指定专用缓存目录；最后一级必须叫 openstreetmap 才能在界面中清除。 设置 LILYGO_MAPS_DISABLE_NETWORK=1 可禁用网络请求，GNSS 与已有缓存仍可使用。 默认 GNSS 串口是 /dev/ttyACM0，可用 LILYGO_MAPS_GNSS_PORT 指定；LILYGO_MAPS_DISABLE_GNSS=1 仅使用 IP。 这些变量需在启动前传给应用，不是界面中的设置选项。
数据与常见问题
GNSS 坐标在本地处理。IP 查询会联系定位服务，地址关键词会发送给 Nominatim，地图请求会向瓦片服务表明浏览区域。 最终 IP 回退服务使用 HTTP；其他正常地图和搜索请求使用 HTTPS。
| 现象 | 处理方法 |
|---|---|
| 地图空白或有缺块 | 检查网络、curl、证书；离线时确认该区域和缩放级别已缓存。 |
| 位置离实际地点很远 | 查看是否为 IP 定位，检查 VPN，并等待室外 GNSS 定位。 |
| 一直没有 GNSS | 检查天线、固件、串口权限，关闭占用串口的 Cellular 或终端工具。 |
| 地址搜索失败 | 核对网络与地址关键词，检查是否设置了禁用网络变量。 |
| 无法清除缓存 | 检查目录权限及缓存目录最后一级是否为 openstreetmap。 |