2026年11月18日 星期三

Turning an Old Android Phone into a GPS Tracker with Termux: On-Device Logging, a Leaflet Map, and Five Pitfalls | 舊 Android 手機用 Termux 變 GPS 追蹤器:手機端記錄、Leaflet 地圖頁與五個實測踩坑

一支沒插 SIM 卡的舊 Android 手機,裝上 Termux 之後可以當成 GPS 追蹤器:手機自己記錄位置,家裡的 Linux 主機把資料收回來,用瀏覽器就能看到目前位置、走過的軌跡、每一趟行程的里程和時速。整套東西不用寫 Android App、不用 Google Maps 金鑰、不用雲端服務,主機端只用 Python 標準函式庫。這篇記錄兩天內從第一版做到可用的過程,重點放在實際踩到的五個坑,每一個都是實測出來的。

先講清楚範圍:這是放在自己手機、看自己位置的工具,網頁只開在 Tailscale 私有網路裡。文中的截圖用的是裁掉住家和公司附近路段之後的示範資料。


圖說:完成後的畫面:軌跡依時速上色,下方是目前位置和這趟行程的摘要

一、架構:手機記錄、主機同步、瀏覽器顯示

圖說:三個部分各做一件事,中間只靠 SSH 和 HTTP

  • 手機:Termux 加 Termux:API,一支 shell script 常駐,用 termux-location 取位置,寫進手機本機的 CSV。
  • 主機:一支 Python 程式,每 20 秒用 SSH 把 CSV 裡比資料庫新的行拉回來存進 SQLite,同時提供網頁和 JSON API。
  • 瀏覽器:Leaflet 加 OpenStreetMap 圖磚,每 10 秒更新一次。
  • 連線:手機和主機都在 Tailscale 裡,手機不管連家裡 Wi-Fi、公司 Wi-Fi 還是另一支手機的熱點,主機都用同一個位址連得到。

手機要能遠端 SSH 進 Termux、開機自動起 sshd 和 Tailscale,這部分的設定是另一個專題,這裡不重複。座標轉地址用 OpenStreetMap 的 Nominatim,免費、不用金鑰,規定是每秒最多查一次,所以主機端有快取。

二、第一版為什麼不行:主機每分鐘去問手機

最直覺的做法是主機每分鐘 SSH 到手機跑一次 termux-location,把結果存起來。在家裡測沒問題,第二天帶出門就露出兩個毛病:

  • 斷網就漏:手機走熱點時連線不穩,有一段 6 分鐘、一段 14 分鐘主機連不上手機,那幾分鐘的位置就永遠沒有了。地圖上變成一條橫跨街區、切過河面的直線。
  • 太稀:一次 SSH 加一次定位就要十幾秒,實際是 1.5 到 2 分鐘才一筆,開車時每個轉彎都被切掉。

所以改成手機自己記:位置先寫在手機本機,主機只負責同步。網路斷掉時照記,連上後一次補回來。

# 手機端:取一筆、寫一行(欄位:時間,緯度,經度,誤差,海拔,速度,來源)
j=$(timeout 15 termux-location -p gps -r once </dev/null)
echo "$(date +%s),$lat,$lon,$acc,$alt,$speed,gps" >> ~/gpslog/track.csv

# 主機端:只拉比資料庫新的行(since 是資料庫裡最後一筆的時間)
ssh -p 8022 phone "awk -F, -v t=$since '\$1>t' ~/gpslog/track.csv"

主機的同步指令順便檢查記錄程式還在不在,不在就把它叫起來,所以手機重開機後不用另外設自動啟動。

三、踩到的五個坑

坑 1:termux-* 指令會吃掉 stdin

用 ssh phone 'bash -s' <<EOF 一次送一整批指令過去測試時,跑到一半後面的指令全部不見,有些還假性逾時。原因是 termux-* 這些指令會讀標準輸入,把還沒執行的腳本內容當成輸入吃掉了。解法是每個指令後面加 </dev/null,或先把腳本 scp 過去再執行。

坑 2:室內等不到 GPS,Termux:API 被系統砍掉,通知狂跳

圖說:手機放在辦公室約一小時,累積了 50 則錯誤通知

手機帶進辦公室後,位置變成 20 分鐘才進來一筆,通知列還一直跳「Termux:API Error: Error in ResultReturner」。從手機的 logcat 看,Termux:API 這個 App 每 80 秒左右就被重啟一次:

09:12:42  TermuxAPIApplication: AppInit                 ← 行程啟動
09:14:05  com.termux.api: reacting to signal 3          ← 系統判定沒回應,要它吐堆疊
09:14:05  com.termux.api: Wrote stack traces to tombstoned
09:14:05  TermuxAPIApplication: AppInit                 ← 被砍掉後重啟
09:14:05  ResultReturner: java.io.IOException: Connection refused   (連續好幾筆)

termux-location -r once 是「等到下一筆定位才回」。室內收不到衛星就一直等,卡到系統判定這個 App 沒回應而砍掉它;這時排隊中的其他請求,客戶端早就逾時走了,App 重啟後一筆一筆回傳都找不到人,每筆失敗就跳一則通知。

對策是室內根本不要試 GPS。判斷方法很土但有效:手機連著家裡或公司的 Wi-Fi 就當作在室內,只讀系統已經算好的網路定位(-p network -r last,這個是立即回應的);連的是熱點或沒有 Wi-Fi 才進 GPS 模式。

INDOOR_SSIDS="家裡的SSID|公司的SSID"
if ssid | grep -qxE "$INDOOR_SSIDS"; then
  termux-location -p network -r last </dev/null   # 立即回應,不會卡
  sleep 60; continue
fi

坑 3:移動中的網路定位會把你丟回幾百公尺外

過橋的時候 GPS 有一次沒在時限內回應,程式退而求其次用了網路定位,結果拿到的是對岸 600 公尺外的舊位置(誤差標示 100 公尺)。軌跡就多了一條從南岸跳回北岸再跳回來的線。

網路定位靠的是周圍 Wi-Fi 基地台的位置資料庫,人在移動、又是連著一支也在移動的熱點時,它給的常常是過時的位置。處理分兩層:

  • 手機端:兩分鐘內有過 GPS 定位,就繼續等 GPS,不拿網路定位頂替。
  • 主機端:顯示和匯出前過濾,前後三分鐘內有 GPS 點的網路定位不採用;要時速 180 公里以上才到得了的點也丟掉。資料庫保留原始資料,只在輸出時濾。

坑 4:兩次 GPS 請求之間多做一件事,晶片就涼了

這個最難找。同一支程式,早上去程是 4 秒一筆、誤差 2 到 3 公尺;傍晚回程卻變成 8 到 30 秒一筆、誤差 10 公尺,軌跡變成鋸齒狀。

早上去程傍晚回程
取樣間隔約 4 秒8~30 秒
誤差2~3 公尺9~11 公尺
差別每輪:GPS → 休息 2 秒每輪:查 Wi-Fi 名稱 → GPS → 休息 2 秒

差別就是坑 2 加的那個「每輪先查 Wi-Fi 名稱」。查一次約 2 秒,加上原本休息的 2 秒,兩次 GPS 請求之間隔太久,GPS 晶片就關掉了;下一筆等於重新開機定位,要十幾秒,而且剛定到位的第一筆精度本來就差。請求夠密的時候晶片一直開著,每筆幾秒就回,精度也好。

改法是 GPS 剛定到位(10 秒內)就不查 Wi-Fi,直接要下一筆;只有 GPS 斷了一陣子才回頭查是不是進室內了。改完當場在戶外量 100 秒:

間隔(誤差):4(2m) 5(1m) 4(1m) 5(1m) 6(2m) 4(2m) 5(2m) 4(2m) 4(2m) 4(2m) 5(2m) 5(2m) 5(2m) 5(2m) 4(2m) 4(2m)

結論是:GPS 請求之間不要插任何耗時的動作,間隔維持在 4 秒左右。

坑 5:想讓 GPS 保持開著,反而更慢

在找到坑 4 的真正原因之前,我先猜是「GPS 晶片沒保溫」,於是在背景多開一個 termux-location -p gps -r updates 想讓晶片不要關。結果更糟。實測發現兩件事:這一版 Termux:API 的 updates 跑 32 秒只回一筆;而且定位請求是排隊一個一個處理的,背景那個佔著的時候,正常的請求全部被擋住。這個修改上線約兩小時就拿掉了。先量再改,比先猜再改省事。

四、網頁功能

圖說:手機上的即時畫面

  • 目前位置:藍點加誤差圈,下方顯示地址、時間、座標、誤差、定位來源、電量、目前時速。
  • 回現在位置:地圖跟著手機移動;手動拖地圖就停止跟隨,方便看別的地方。
  • 旋轉與車頭朝上:Leaflet 本身不能轉,用 leaflet-rotate 外掛。車頭朝上是拿最近兩分鐘內相距 20 公尺以上的兩個 GPS 點算行進方向,停著不動時沿用上一次的方向,不會亂轉。
  • 依日期查看、下載:選某一天看整天路線;可下載 GPX(匯入其他地圖軟體)或 CSV(Excel 直接開)。
  • 停止記錄:按一下,主機通知手機關掉記錄程式。停止的時段另外記在資料庫,那段時間的位置一律不匯入,地圖上直接斷開。

圖說:車頭朝上:地圖轉成行進方向朝上,左上的紅色箭頭指向北方

行程清單、時速上色、平滑

圖說:行程清單:自動切成一趟一趟,點一趟就只看那一趟

  • 切行程:資料中斷超過 5 分鐘,或在 60 公尺範圍內停留滿 5 分鐘,就算一趟結束。不到 200 公尺的不算,免得室內定位飄動被當成出門。
  • 時速:手機單次定位回來的速度欄位幾乎都是 0,所以用前後兩點的距離除以時間來算。軌跡線依時速分四級上色。
  • 交通方式:用移動中時速的中位數猜,只分走路、慢速、行車。開車和騎機車從速度分不出來,就不硬分。
  • 平滑:連續的 GPS 點做 1-2-1 加權平均,濾掉一兩公尺的左右跳動。地圖和 GPX 用平滑後的位置,CSV 給原始座標。

圖說:點進單一行程:藍色是 25~60 公里,橘色 7~25,綠色是 7 以下(等紅燈、轉彎)

五、資料量和耗電

  • 資料量:一筆約 70 位元組。每天外出兩小時(GPS 4 秒一筆)加上其餘時間在室內,一天約 0.2 MB,一年不到 100 MB。
  • 室內不重複存:位置沒變(30 公尺內)就不寫,只每 10 分鐘存一筆表示還活著。
  • 耗電:晚上連續記錄約 35 分鐘(多數時間 GPS 開著),電量從 98% 掉到 97%。樣本只有這一次,長時間的數字還要再觀察。

六、還沒做和已知限制

  • 車頭朝上、目前時速這兩項做好時手機都不在移動,只用指定方向的方式驗證過畫面,實際邊走邊轉的效果還沒看過。
  • 戶外長時間收不到衛星(例如地下停車場)時,仍可能偶爾跳一兩則 Termux:API 錯誤通知。
  • 手機靜置室內時系統會放慢背景程式,設定 60 秒一輪實際拉長到 3、4 分鐘。位置沒變所以影響不大,還沒處理。
  • 資料庫沒有備份,只有主機上一份。
  • 看一整週的軌跡時點數會很多,還沒做抽稀。
  • 室內的判斷靠 Wi-Fi 名稱清單,常待的新地點要手動加進去。

回頭看,這個專題真正花時間的不是地圖頁,而是搞清楚 termux-location 在各種情況下的行為:什麼時候立即回、什麼時候會卡住、卡住會拖累誰、請求之間隔多久晶片會關。這些文件上都沒寫,只能一個一個量出來。

沒有留言:

張貼留言