エラー処理の目的は、例外を握りつぶすことではなく、どのレイヤーで発生したかを判断することです。レイヤーを明確にできれば、調査はかなり速くなります。接続問題でテンプレートを直さず、非対応命令をリトライで解決しようとせず、用紙切れを BLE MTU の問題として扱わないでください。

エラー分類

種類	よくある原因	対処の方向
接続エラー	Bluetooth 権限が無効、デバイス未ペアリング、service/characteristic UUID 不一致、ネットワーク到達不可、接続タイムアウト。	接続フローに戻り、権限、デバイス選択、UUID、アドレス、プラットフォーム状態を確認します。
書き込みエラー	接続中断、プラットフォーム write API の失敗、分割サイズ過大、write with/without response モード不一致。	分割サイズを小さくし、書き込みモードを確認し、何番目の chunk で失敗したかを記録します。
フロー制御エラー	BLE credit が到着しない、MTU/credit notify 形式不一致、credit タイムアウト、bypass-write の誤用。	lane-credit または signal-credit が必要か確認し、notify が購読され flow control へルーティングされているかを確認します。
クエリエラー	pending query タイムアウト、matcher 不一致、receive source 未起動、デバイスがそのクエリに非対応。	クエリ命令、timeout、notify/read ソース、方言 parser を確認します。
命令エラー	デバイスが現在の ESC、TSPL、CPCL 命令に対応していない、または誤った方言を使っている。	デバイスが対応する命令セットへ切り替え、デバイス非対応の拡張コマンドを減らします。
内容エラー	紙幅不一致、画像幅過大、エンコーディング非互換、ラベル座標がページ外、payload 過大。	テンプレートと画像処理層に戻り、幅、エンコーディング、座標、最終バイトサイズを確認します。

初心者向け調査順序

次の順序で調査すると、誤ったレイヤーで迷うことを避けやすくなります。

1. まず接続を確認します。デバイスが本当に connected か、権限、UUID、アドレス、システム Bluetooth 状態が正しいかを確認します。
2. 次に最小内容を送ります。短いテキストまたは単純なラベルだけを印刷し、基本的な書き込みが使えるかを確認します。
3. 次に分割と BLE を見ます。小さな内容は正常で大きな内容が失敗する場合、chunk size、MTU、write mode、credit を確認します。
4. 次にステータスクエリを見ます。印刷はできるがステータスを読めない場合、receive source、notify/read、pending query timeout、parser を確認します。
5. 最後にテンプレート内容を見ます。特定のテンプレートだけが失敗する場合、紙幅、画像幅、エンコーディング、バーコード/QR コードのパラメーター、命令対応を確認します。

ログの残し方

ログは段階を特定できる必要がありますが、機密性のある印刷内容を記録してはいけません。次のような記録をおすすめします。

記録してよいもの	記録を避けるもの
SDK 言語とバージョン、プラットフォーム、転送方式。	レシート本文、受取人、電話番号、住所、注文明細などの機密内容。
デバイス名またはマスク済みデバイス ID、service/characteristic UUID。	完全な業務 payload または未マスクのユーザーデータ。
命令ファミリー、総バイト数、chunk size、chunk index、write mode。	印刷内容を復元できる raw bytes。
MTU、payload MTU、credit 戦略、credit timeout、fallback mode。	本番環境で長期的に有効な過剰に詳細なバイナリ dump。
クエリ種類、timeout、raw response を受け取ったか、parser 結果タイプ。	顧客情報を含む parser テキストフィールド。

デバッグ段階で raw bytes を見る必要がある場合は、まず長さ、先頭数バイト、hash、またはマスク済み hex 断片だけを記録し、長期の本番ログに入らないようにしてください。

症状対応表

症状	可能性のあるレイヤー	次に確認すること
デバイスをスキャンできない	接続	権限、Bluetooth スイッチ、デバイスが advertising しているか、プラットフォーム discovery filter。
スキャンできるが接続失敗	接続	アドレス/デバイスオブジェクトが期限切れでないか、service UUID が一致するか、接続タイムアウトが短すぎないか。
接続成功だがまったく印刷しない	書き込み / 命令	write characteristic が正しいか、最小テキストを印刷できるか、命令ファミリーに対応しているか。
半分だけ印刷される、または大きな画像が失敗する	書き込み / フロー制御 / 内容	chunk size、BLE MTU、credit、画像幅、payload 総サイズ。
credit 有効化後に止まる	フロー制御	credit notify の購読に成功しているか、通知が lane-credit または signal-credit に入っているか、timeout が妥当か。
bypass-write では印刷できるが、fail モードではタイムアウトする	フロー制御	デバイスが credit を必要としていない可能性、または credit 特徴値/通知形式の設定が誤っている可能性。
ステータスクエリがずっとタイムアウトする	クエリ / 受信	receive source が起動しているか、notify/read にデータがあるか、matcher とクエリ命令が一致しているか。
response は受け取ったが結果が unknown	クエリ / parser	raw bytes は到達済みです。方言、クエリ種類、ファームウェア応答形式を確認します。
レシートが文字化けする	内容 / 命令	文字エンコーディング、コードページ、フォント、デバイス言語設定。
用紙切れでも書き込みが続く	ステータス / プロダクトロジック	デバイスが用紙切れステータスに対応しているか、アプリが書き込み前/書き込み中にステータスを読み取って処理しているか。

調査時は「どのレイヤーで発生したか」という生のエラー情報をできるだけ残し、その後で「プリンターに用紙があるか確認してください」や「プリンターに再接続してください」のような、ユーザーが理解できる案内に変換してください。