Androidアプリの実機開発・動作確認・障害調査を、毎回同じ初期条件から開始できるか確認するための開発ツールです。特定のIssueや検証フェーズには依存せず、Bluetooth/NMEA受信やオフライン地図を扱う作業全般で継続利用します。本書は再利用可能な開発・復旧手順の正本です。
リポジトリルートの次のファイルを使用します。
tools/android/check_android_baseline.sh
adbを実行できる。Windows上のWSL環境ではWindows版ADBを使う（復旧・設定手順はWindows再起動後のWSL・Android実機試験 復旧手順を参照）dev.drogger.tabletのデバッグ版がインストールされているdrogger/）をカレントディレクトリにしている最初に端末が認識されていることを確認します。
adb devices
端末が1台だけdevice状態で表示される必要があります。unauthorizedの場合は、タブレットに表示されるUSBデバッグ許可ダイアログを承認してください。
リポジトリルートで実行します。
tools/android/check_android_baseline.sh
各項目がPASSまたはFAILで表示されます。すべて成功すると終了コード0、1項目でも失敗すると終了コード1になります。
出力例:
PASS adb device 80b254207d94
PASS Bluetooth permission BLUETOOTH_CONNECT granted=true
PASS Bluetooth ON
PASS app process PID 24774
PASS NMEA instance instance=a1b2c3 only
PASS NMEA heartbeat 0s old
PASS PMTiles 1141387 bytes
PASS forced Doze mForceIdle=false
PASS Doze state ACTIVE / light ACTIVE
Result: PASS (9 passed, 0 failed)
MANUAL Confirm DG-PRO1RWS power and map/aerial/field-polygon rendering.
--markdownを付けると、Gitea Issueへ貼り付けやすいチェックリスト形式になります。
tools/android/check_android_baseline.sh --markdown
結果をクリップボードへ直接コピーしたい場合は、利用環境に応じてxclipなどへ渡します。
tools/android/check_android_baseline.sh --markdown | xclip -selection clipboard
| 項目 | 合格条件 |
|---|---|
| adb device | 認証済みの実機が1台だけ接続されている |
| Bluetooth permission | BLUETOOTH_CONNECTがgranted=true |
| Bluetooth | AndroidのBluetooth設定がON |
| app process | dev.drogger.tabletのPIDが1つだけ存在する |
| NMEA instance | 現在のPIDのheartbeatに現れるinstanceIdが1種類だけ |
| NMEA heartbeat | 最新受信が既定で10秒以内 |
| PMTiles | 内部ストレージのPMTilesが1,141,387 bytes |
| forced Doze | mForceIdle=false |
| Doze state | 通常・Light Dozeの両方がACTIVE |
次の項目はADBだけでは正しく判定できないため、スクリプト成功後に実機で確認します。
自動確認と手動確認がすべて成功した状態を、そのシナリオのベースラインとします。
既定では最新heartbeatが10秒以内なら合格です。端末や検証条件に合わせて変更できます。
tools/android/check_android_baseline.sh --max-heartbeat-age 30
環境変数でも指定できます。
MAX_HEARTBEAT_AGE_SECONDS=30 tools/android/check_android_baseline.sh
Windows再起動後にADBが見えない、deviceなのにshellが戻らない、WSL版/Windows版ADBが競合する場合は、個別対処を繰り返す前にWindows再起動後のWSL・Android実機試験 復旧手順を先頭から実施します。
adb devices
unauthorizedならタブレット側の確認ダイアログを許可するアプリの権限を許可します。
adb shell pm grant dev.drogger.tablet android.permission.BLUETOOTH_CONNECT
タブレットの設定画面からBluetoothをONにします。
アプリが停止している場合は起動します。PIDが複数表示される場合は一度強制停止してから起動し直します。
adb shell am force-stop dev.drogger.tablet
強制停止後は、実機でアプリを起動してDG-PRO1RWSへ再接続してください。
ファイルが無い、またはサイズが異なる場合は、アプリデータ内のコピーが不完全な可能性があります。対象シナリオの途中でなければ、アプリデータを初期化して正常コピーをやり直します。
adb shell pm clear dev.drogger.tablet
この操作はBluetooth権限なども消去します。アプリを起動して権限を再許可し、地図表示を確認してください。PMTiles破損シナリオの観察中は、結果を記録する前に初期化しないでください。
強制Dozeを解除します。
adb shell dumpsys deviceidle unforce
adb shell dumpsys deviceidle
解除後、スクリプトを再実行してください。
check_android_baseline.shは単発の確認用です。数時間規模の連続利用試験のように、試験時間中ずっと張り付いて確認できない場合は、次の2つのスクリプトを使います。
tools/android/capture_long_run.sh
tools/android/summarize_long_run.sh
tmuxやscreenなどフォアグラウンドで動かし続けられる端末で実行します。
tools/android/capture_long_run.sh --out-dir session_logs/android-long-run/$(date +%Y%m%dT%H%M%S)
--out-dir配下に、adb logcat -v threadtimeの連続キャプチャ（logcat.log）と、5分間隔（既定）でのPID・メモリ（dumpsys meminfoのTOTAL PSS）・電池残量・Doze状態のスナップショット（snapshots.tsv）を書き続けます。試験終了時にCtrl-Cで停止してください。間隔は--snapshot-interval SECONDS、上限時間は--duration SECONDS（省略時は無期限）で変更できます。
tools/android/summarize_long_run.sh session_logs/android-long-run/<試験ディレクトリ>/logcat.log session_logs/android-long-run/<試験ディレクトリ>/snapshots.tsv
クラッシュ/ANR件数、BluetoothGpsViewModelの状態遷移回数、NMEA heartbeatの最初/最後（受信センテンス数・checksum不正件数の推移が分かる）、検出されたinstance id（複数あれば二重接続やプロセス再生成の疑い）、メモリ/電池/Dozeスナップショットの最初/最後を表示します。
BluetoothGpsViewModelは5秒間隔でheartbeatを出力します。接続・受信全般のinstance、connectionState、sentenceCount、checksumFailCount、lastReceivedAgeMsに加え、有効位置を診断するfixValid、fixQuality、numSatellites、rmcStatus、invalidFixCount、lastInvalidReason、lastValidFixAgeMsを含みます。これにより「Bluetooth/NMEAは受信中だが、衛星受信条件により有効Fixが無い」状態をlogcatだけで区別できます。check_android_baseline.shの「NMEA instance」「NMEA heartbeat」項目もこのログを参照します。
スクリプト自体の正常系テストは、実機を使わずモックADBで実行できます。
tools/android/tests/test_check_android_baseline.sh
tools/android/tests/test_capture_long_run.sh
tools/android/tests/test_summarize_long_run.sh
構文だけを確認する場合:
bash -n tools/android/check_android_baseline.sh
bash -n tools/android/capture_long_run.sh
bash -n tools/android/summarize_long_run.sh
通常は変更不要です。
| 環境変数 | 既定値 | 用途 |
|---|---|---|
ADB |
adb |
使用するADBコマンドのパス |
PACKAGE_NAME |
dev.drogger.tablet |
対象アプリのパッケージ名 |
EXPECTED_PMTILES_BYTES |
1141387 |
正常なPMTilesの期待サイズ |
MAX_HEARTBEAT_AGE_SECONDS |
10 |
heartbeatの最大経過秒数 |