フロー制御は、アプリが印刷データをデバイスへ書き込むときに「どれくらい小さく分けるか、どれくらい速く書くか、いつ待つか」を決めます。初めて導入する場合は、まず次の 3 点として理解できます。

1. まとまった命令バイト列を複数の chunk に分ける。
2. 1 回ごとに、現在の転送方式が安定して処理できるサイズだけを書き込む。
3. BLE デバイスが credit を要求する場合は、デバイス通知を待ってから続きの書き込みを行う。

Dialect builder は ESC、TSPL、CPCL バイト列を生成するだけです。分割サイズ、書き込みモード、BLE credit、失敗処理は、device、connection、または print session 層に置くべきです。

通常の分割

通常の分割は印刷命令の意味を解釈せず、最終 payload をバイト数だけで分けます。たとえば 3000 バイトのデータを 1024 バイトで分割する場合、1024、1024、952 の 3 回に分けて書き込みます。

各言語 core の通常分割のデフォルトサイズは異なります。

SDK	デフォルト chunk size
TypeScript	512 bytes
Dart	1024 bytes
Java	1024 bytes
Swift	512 bytes
Objective-C	512 bytes

これらのデフォルト値は通常転送の開始点として適していますが、すべての BLE デバイスにとって最適とは限りません。パケットロス、書き込み失敗、印刷が途中で止まる問題がある場合は、まずデバイスの最大書き込み長、プラットフォーム write API の制限、BLE credit が必要かを確認してください。

BLE MTU

BLE の MTU は 1 つの ATT データパケットの上限であり、アプリが完全な業務データを自由に書き込めるサイズではありません。保守的な開始値は 20 bytes です。プラットフォームまたはデバイスが MTU をネゴシエートできた場合、NIB の BLE helper は mtu - 3 を payload サイズとして使用します。ATT header は通常 3 bytes を占めるためです。

たとえばネゴシエートされた MTU が 185 の場合、推奨 payload は 182 bytes です。これもなお「分割書き込み」であり、分割サイズが通常のデフォルト値ではなく BLE MTU から来るだけです。

BLE Credit

一部の BLE プリンターは、アプリからの連続書き込みを許可しません。デバイスは notify を通じて、SDK が現在あと何パケット書けるかを知らせます。SDK は 1 credit を消費して 1 chunk を書き込み、credit が尽きたら次の通知を待ちます。

NIB には現在 2 種類の credit 戦略があります。今後、新しい戦略やデバイスファミリー専用戦略が追加される可能性があります。

戦略	仕組み	適したケース
lane-credit	デバイスの credit notify を読みます。通知は MTU と書き込み可能 credit を同時に更新できます。payload chunk を 1 つ書くごとに 1 credit を消費します。	デバイスに固定の read/notify/credit 特徴値があり、credit 通知が主書き込みチャネルの容量を表す場合。
signal-credit	専用の signal/credit 通知で書き込みを制御します。MTU 通知は別に届くことがあり、credit 通知が届いて初めて書き込みが解放されます。	デバイスが「信号」と通常の読み取り応答を分けている場合、または専用の信号特徴値でペース制御する必要がある場合。

lane-credit のデフォルト BLE credit 開始値は、通常「有効な通知を観測した後に credit に従って書く」ケースに適しています。signal-credit のデフォルト credit は 0 で、正の credit 通知を待つまで書き込みません。導入時には service UUID、書き込み特徴値、読み取り/通知特徴値、credit 特徴値、MTU 形式、credit 通知形式を確認してください。

fallback / fail / bypass-write

Credit モードで最もよくある問題は、アプリが credit を有効にしたものの、デバイスが期待どおり notify を送らないことです。NIB はこの状況を 2 種類に分けて扱います。

モード	動作
fail	credit を待っても届かない場合に直接失敗します。書き込みまたは BLE credit タイムアウトとして表面化します。正式導入と厳格な検証に適しています。
bypass-write	credit が有効化されていない、または待機がタイムアウトした場合に、credit を迂回して残りのデータを通常の書き込み経路で送ります。結合テスト、互換性テスト、またはデバイスが実は credit を必要としないかを確認する場合に適しています。

bypass-write を長期的なデフォルト値にしないでください。これは「credit がなくてもデバイスは印刷できるか」を判断する助けになりますが、デバイスが本当に credit に依存している場合、迂回後もパケットロス、停止、部分印刷が起こる可能性があります。

選び方

単純なものから複雑なものへ、次の順に選びます。

1. USB、ネットワーク、クラシック Bluetooth など安定したストリーム転送: まず SDK デフォルトの通常分割を使います。
2. BLE だがデバイス専用要件がない: まず保守的な 20 bytes を使うか、プラットフォームが提供する maximum write length を使います。
3. BLE で MTU がネゴシエート済み: mtu - 3 を payload 分割として使います。
4. BLE ドキュメントまたはパケットキャプチャで credit notify が確認できる: デバイスプロトコルに従って lane-credit または signal-credit を有効にします。
5. credit が必要か不明: 結合テスト段階では短時間だけ bypass-write で比較できます。正式リリース前には、明確な credit 戦略または通常分割戦略へ切り替えてください。

「小さなテキストは正常だが、大きな画像や長いラベルが失敗する」場合、通常は命令生成の問題ではなく、分割、MTU、credit、またはプラットフォームの書き込みモードがデバイスと合っていないことが原因です。