BLE デバイスの電源が入っていて近くにあるにもかかわらず、Android アプリのデバイスリストが空になっています。接続コードを変更する前に、スキャンの開始に失敗したのか、周辺機器がアドバタイズを停止したのか、またはアプリケーションが有効な結果を破棄したのかを特定してください。このガイドでは、権限、アドバタイズデータ、スキャンコールバック、条件を揃えた比較を使用した実践的なトラブルシューティング手順を説明します。
まず検出がどこで失敗しているかを特定する
デバイスリストが空であるだけでは、BLE 検出のどの部分が失敗したかは分かりません。
周辺機器がアドバタイズしていない可能性があります。Android にスキャン権限がない可能性もあります。スキャンの開始に失敗した可能性もあります。または、アプリが有効なアドバタイズを受信したものの、画面を更新する前に削除した可能性もあります。
問題を次の3つの質問に分けてください：
- アプリは例外や失敗コールバックなしでスキャンを開始しましたか？
- アプリはスキャン結果を1件でも受信しましたか？
- アプリケーションのフィルタリング前に、対象デバイスがそれらの結果に含まれていましたか？
各境界で証拠を記録してください。読み込み中のスピナーが示すのは、画面が読み込み状態に入ったことだけです。
まず条件を揃えたテストを行います。アプリを表示したまま画面をオンにし、周辺機器を近くに置いて、時間を制限したスキャンを1回実行してください。権限、ファームウェア、フィルターを同時に変更しないでください。
周辺機器がアドバタイズしていることを確認する
電源が入っているデバイスが必ずしも検出可能とは限りません。
ファームウェアのアドバタイズ動作を確認してください。一部の製品は、セットアップ中、ボタンを押した後、または起動後の限られた時間だけアドバタイズします。別のセントラルに接続している間はアドバタイズを停止する製品もあります。
必要に応じて他のクライアントを切断し、文書化された検出モードにデバイスを移行してください。ステータス LED が点灯しているからといって、アドバタイズが有効であるとは限りません。
同じスマートフォン上の BLE 検査アプリを使用して、アドバタイズが表示されるか確認してください。同じデバイス状態で、時間を空けずにテストを比較してください。
比較結果を解釈する
- どちらのアプリでも対象が見つからない： アドバタイズ状態、デバイスの電源、無線環境、スマートフォンの設定を調査してください。
- 検査アプリでは対象が見つかるが、自分のアプリでは見つからない： 権限、スキャン設定、フィルターを比較してください。
- コールバックは対象を受信しているが、リストは空のまま： 解析、アプリケーションのフィルタリング、UI 状態の更新を調査してください。
これらの観察結果は調査範囲を絞り込みますが、それだけで原因を確定するものではありません。
正常に動作することが分かっている BLE 周辺機器を比較対象として用意してください。アプリがその機器を検出できても対象を検出できない場合は、対象のアドバタイズデータや動作の違いに注目してください。
Android バージョン、ターゲット SDK、権限を確認する
スマートフォンの Android バージョンとアプリのターゲット SDK の両方を記録してください。必要な権限は、その組み合わせによって異なります。
Android 12 以降で Android 12 以降をターゲットとする最新のアプリの場合：
- 検出には BLUETOOTH_SCAN を宣言してリクエストします。
- 接続操作と、ワークフローで使用する保護対象の Bluetooth API には、BLUETOOTH_CONNECT をリクエストします。
- スマートフォン自体がアドバタイズする場合にのみ、BLUETOOTH_ADVERTISE をリクエストします。
- 該当する API を呼び出す前に、実際の実行時権限の付与状態を確認してください。
古い Android バージョンでは、BLE スキャンに従来の Bluetooth と位置情報権限のモデルが使用されます。Android 10 および 11 では、フォアグラウンドでの検出には通常、正確な位置情報の権限が必要です。バックグラウンドでの検出には、追加の位置情報要件があります。
マニフェストで宣言するだけでは、実行時アクセスは付与されません。従来の構成で結果が空になる問題を診断する際は、スマートフォンの位置情報設定も確認してください。
neverForLocation フラグは、アプリがスキャン結果から物理的な位置情報を実際に導出しない場合にのみ適切です。Android は、このフラグによって一部の BLE ビーコンが除外される可能性があると警告しています。特定のアドバタイズが表示されない場合は、アプリの権限モデルを確認せずにフラグを削除するのではなく、この点を確認してください。
サポート対象の構成を検証するには、Android Bluetooth 権限ガイド（https://developer.android.com/develop/connectivity/bluetooth/bt-permissions) を使用してください。
スキャン開始前に Bluetooth の状態を確認する
スキャン状態に入る前に、BLE のサポートと Bluetooth の利用可否を確認してください。
Android は BluetoothAdapter を通じて BluetoothLeScanner を提供します。Bluetooth が無効になっていると、スキャナーを利用できない場合があります。
明確な事前確認手順は次のとおりです：
- スマートフォンが BLE をサポートしていることを確認します。
- Bluetooth アダプターを取得します。
- 呼び出す操作に必要な権限を確認します。
- Bluetooth が有効であることを確認します。
- スキャナーを取得します。
- 時間を制限したスキャンを開始します。
前提条件が満たされていない場合は、画面上で説明してください。「デバイスが見つかりません」よりも、「付近のデバイスへのアクセスを許可してください」や「Bluetooth をオンにしてください」の方が有用です。
権限関連の例外を捕捉して報告してください。すべての例外を空のリストに置き換えないでください。
Android の BLE デバイス検索ガイド（https://developer.android.com/develop/connectivity/bluetooth/ble/find-ble-devices) では、スキャンに時間制限を設け、目的のデバイスが見つかったら停止することを推奨しています。
条件を揃えたフォアグラウンドテストではフィルターを外す
誤ったフィルターにより、正常に動作するスキャナーが故障しているように見えることがあります。
診断では、画面をオンにした状態で、短時間のフィルターなしフォアグラウンドスキャンを実行してください。製品固有のルールを適用する前に、受信した結果をログに記録します。不一致を特定した後、適切なフィルターを元に戻してください。
設定されたサービス UUID、アドバタイズ名、メーカー識別子、ペイロードパターン、マスクを確認してください。
検出に使用するサービス UUID は、照合対象のアドバタイズデータに含まれている必要があります。GATT 接続後に公開されるサービスが、アドバタイズにも含まれているとは限りません。
同様に、メーカーデータの照合は、実際にアドバタイズされるレイアウトに従う必要があります。オフセットを変更するファームウェアの改訂により、アプリケーションの前提が無効になることがあります。
ScanFilter 内のフィールドは、すべて満たす必要がある照合条件として組み合わされます。UUID 条件に名前条件を追加すると、アドバタイズに名前を含めていないデバイスが除外される可能性があります。Android ScanFilter リファレンス（https://developer.android.com/reference/android/bluetooth/le/ScanFilter). を参照してください。
アプリケーションのフィルターも確認する
プラットフォームのフィルターは一層にすぎません。独自のコードが次の理由で結果を拒否していないか確認してください：
- 名前がない、またはプレフィックスと一致しない。
- RSSI がしきい値を下回っている。
- アドバタイズのペイロードバージョンが認識されていない。
- キャッシュされたデバイス識別子が一致しなくなった。
- デバイスが重複と見なされている。
- 結果が古いスキャンセッションに属している。
拒否理由をログに記録してください。そうしないと、「受信していない」と「受信したが破棄した」を区別できません。
名前だけに頼らずアドバタイズデータを調べる
アドバタイズ名は表示には便利ですが、製品を識別する唯一の根拠にすべきではありません。
Android の ScanRecord では、ローカル名、サービス UUID、サービスデータ、メーカーデータ、生のアドバタイズバイトを取得できます。ローカル名は null の場合があります。
これらのフィールドをまとめて調べ、ファームウェアのドキュメントと照合してください。Android ScanRecord リファレンス（https://developer.android.com/reference/android/bluetooth/le/ScanRecord) には、利用可能なデータが記載されています。
診断ログには、照合動作の説明に必要なフィールドだけを記録してください。ログを共有する際は識別子を伏せてください。
デバイスの識別設計がその前提を明示的にサポートしていない限り、観測された Bluetooth アドレスを永続的な製品 ID として扱わないでください。
ファームウェアチームと検出仕様を文書化してください：
- 製品ファミリーを識別するフィールドはどれですか？
- 該当する場合、個々のデバイスを識別するフィールドはどれですか？
- セットアップ中または通常動作中に何が変化しますか？
- ペイロードのバージョンはどのように区別されますか？
- ファームウェアの更新によって、アドバタイズ名やデータレイアウトが変わる可能性はありますか？
これにより、検出は推測の集まりではなく、テスト可能なインターフェースになります。
スキャンコールバックと失敗コードを処理する
結果の処理と同じくらい慎重に失敗処理を実装してください。
ScanCallback には onScanResult、onBatchScanResults、onScanFailed があります。バッチ処理を設定している場合は、すべての結果が個別に届くと想定せず、バッチコールバックを確認してください。
有用な失敗カテゴリには次のものがあります：
- すでに開始済み： 重複したスキャンリクエストを確認してください。
- アプリケーションの登録に失敗： 構成を記録し、スキャナーの登録を調査してください。
- 機能がサポートされていない： リクエストしたスキャンオプションを確認してください。
- 内部エラー： 復旧する前に診断用の証拠を保存してください。
- ハードウェアリソース不足： 構成を簡素化し、同時実行中のスキャンを確認してください。
- スキャン頻度が高すぎる： 短時間での再試行を停止し、回数や時間を制限した復旧ポリシーを適用してください。
すべての定数が、すべての Android API レベルで利用できるわけではありません。解釈した名前とともに数値コードも保存してください。Android ScanCallback リファレンス（https://developer.android.com/reference/android/bluetooth/le/ScanCallback). を参照してください。
スキャン開始の失敗と、結果が0件のまま完了したスキャンは、アプリケーション上で異なる状態として扱う必要があります。
また、コールバックベースのスキャンを停止する際は、同じコールバックインスタンスを使用してください。クリーンアップ用に新しいインスタンスを作成すると、元のセッションが管理されないまま残る可能性があります。
スキャンのライフサイクルを制御する
スキャンの重複開始は、画面のコールバック、再試行タイマー、権限の結果、スキャンボタンの2回目のタップなど、複数の場所から発生する可能性があります。
スキャンの管理元を1つにし、その状態を明示的にモデル化してください：
- 待機中。
- 前提条件を確認中。
- スキャン中。
- 停止中。
- 完了。
- 失敗。
セッション識別子を割り当て、以前のスキャンから遅れて実行された処理が現在の結果リストを上書きしないようにしてください。
各スキャンの開始理由と停止理由を記録してください。古いタイムアウトが誤って新しいセッションを停止するケースには、特に注意してください。
診断用のフォアグラウンドスキャンでは、即時レポートを使用し、周辺機器のアドバタイズ動作に適した時間制限を設けてください。デューティ比の高いスキャンは比較には役立ちますが、権限不足や誤ったフィルターを修正するものではありません。
結果リストが空だからといって、開始と停止を無限に繰り返さないでください。
画面オフ時とバックグラウンドでの動作を個別にテストする
フォアグラウンドスキャンが成功しても、バックグラウンド検出が正しく動作するとは限りません。
Android のドキュメントによると、フィルターなしのスキャンは画面がオフになると停止し、オンになると再開します。画面オフ時の検出が必要なワークフローでは、適切なフィルターを使用してください。BluetoothLeScanner リファレンス（https://developer.android.com/reference/android/bluetooth/le/BluetoothLeScanner). を参照してください。
次の状況を個別にテストしてください：
- アプリが表示され、画面がオン。
- アプリは表示されていないが、プロセスは実行中。
- 画面がオフ。
- プロセスが終了。
- スマートフォンを再起動。
コールバックベースのワークフローは、アプリのプロセスが存続していることに依存します。Android は、バックグラウンド BLE ガイド（https://developer.android.com/develop/connectivity/bluetooth/ble/background). で、適切なバックグラウンド用途向けの PendingIntent ベースのスキャンとコンパニオンデバイスのオプションについて説明しています。
製品要件に合わせて仕組みを選択してください。フォアグラウンドサービスは、検出失敗に対する万能な解決策ではありません。
再現可能な診断記録を取得する
有用なバグレポートでは、1回のスキャンセッション中に何が起きたかを正確に説明する必要があります。
次の情報を取得してください：
- スマートフォンのメーカー、モデル、Android バージョン。
- アプリのバージョンとターゲット SDK。
- 実行時権限の付与状態。
- Bluetooth の状態と、関連する従来の位置情報設定。
- 周辺機器のハードウェアとファームウェアのバージョン。
- 周辺機器のアドバタイズモードと既存の接続。
- スキャンフィルター、レポート遅延、コールバックタイプ。
- スキャンの開始時刻、停止時刻、停止理由。
- 失敗コールバックのコードまたは例外。
- アプリケーションのフィルタリング前後の結果件数。
- 対象のアドバタイズについて、識別情報を伏せた証拠。
一度に1つの変数だけを変更し、前のセッションと比較してください。
Bluetooth を再起動すると一時的に改善する場合は、その観察結果を保存してください。それだけでは、元の原因がライフサイクル管理、リソース枯渇、または別の状態のいずれであったかはまだ説明できません。
実機で修正を検証する
修正によって別の検出問題が発生することなく、元の不具合が解消されることを確認してください。
次の項目をテストしてください：
- 新規インストールと最初の権限リクエスト。
- 権限の拒否、後からの付与、取り消し。
- スキャン開始時に Bluetooth が無効。
- 周辺機器が遅れてアドバタイズモードに入る。
- ローカル名のないアドバタイズ。
- サポート対象のファームウェアペイロードバージョン。
- ユーザーが繰り返し開始するスキャン。
- スキャン中に別の画面へ移動。
- 必要な場合は画面オフ時の動作。
- 必要な場合はバックグラウンド検出。
複数のスマートフォンモデルと、製品がサポートする Android バージョンを含めてください。
測定可能なワークフローとして成功条件を定義してください。対象が文書化された検出時間内に認識され、重複セッションが制御され、画面に不足している前提条件が正確に表示されることです。
デバイスの検出は1つのマイルストーンです。接続、サービス検出、コマンド交換についても、それぞれ検証が必要です。
よくある質問
BLE 検査アプリではデバイスが見つかるのに、自分のアプリでは見つからないのはなぜですか？
権限、フィルター、スキャン設定、アドバタイズデータの処理を比較してください。検査アプリには表示されるアドバタイズを、自分のアプリケーションが拒否している可能性があります。
まず条件を揃えたフィルターなしのフォアグラウンドスキャンを実行し、その後、製品固有の照合ルールを1つずつ追加してください。
スキャン時間を延ばせば問題は解決しますか？
スキャン時間を延ばすと、頻度の低いアドバタイズを検出しやすくなる場合があります。ただし、無効なフィルター、拒否された権限、またはアドバタイズしていない周辺機器の問題は解決しません。
検出時間を決める前に、アドバタイズ動作を測定してください。
デバイス名でフィルタリングすべきですか？
名前は判断材料の1つとして使用してください。ファームウェアが名前の存在と不変性を保証しているか確認してください。
可能であれば、文書化されたサービスデータまたはメーカーデータを基準に検出を定義し、接続後のワークフローでデバイス ID を検証してください。
スキャン結果が空になるたびに Bluetooth をリセットすべきですか？
通常のアプリケーション動作としてではなく、条件を揃えた診断手順として使用してください。
まず失敗コールバック、スキャンの管理元、フィルター、周辺機器の状態を確認してください。リセットを繰り返すと、原因の特定に必要な証拠が隠れる可能性があります。
予測可能なデバイス検出ワークフローを構築する
信頼性の高い検出には、ファームウェアのアドバタイズ動作、Android の権限、スキャン構成、アプリケーションの照合ルールが整合している必要があります。
YUNJI の BLE アプリ開発サービス（https://yunji-node.com/solutions/ble-app-development) は、検出、デバイス統合、接続状態、実機検証に対応しています。
トラブルシューティングレビューに備えて、影響を受けるスマートフォンの構成、ファームウェアのバージョン、アドバタイズのサンプル、対象を検出できなかったスキャンセッションのログを用意してください。
