通信パターン別 Recipes
この索引は、やりたいシリアル通信の目的から既存の Guide / Recipe ページへ辿るためのハブです。通信パターンが分かっているときに使ってください。フレームワーク別の配線例は Examples を参照してください。
Parent: #555 · Issue: #558
スコープ
| 項目 |
判断 |
| 軸 |
通信パターン（デバイスブランドではない） |
| デバイス名 |
製品名を互換性の保証として扱わない |
| 新規の長文ページ |
既存 Guide / Recipe への リンクを優先 |
| バイナリ受信 |
未対応 — #545 と 対応範囲 を参照 |
カタログ
基本のテキスト送受信
|
|
| 対象 API |
createSerialSession, connect$, lines$, send$, disconnect$ / dispose$, state$, errors$ |
| 適している用途 |
初回接続、ログ風の行受信、単純な文字列送信 |
| 適していない用途 |
カスタムフレーミング、コマンド／応答の対応付け、バイナリ線上プロトコル |
| 詳細 |
クイックスタート · ストリーム選択は 選び方 |
行指向プロトコル
|
|
| 対象 API |
lines$（既定）。組み込みフレーミングで足りないときだけ receive$ + RxJS |
| 適している用途 |
改行区切りログ、JSON Lines、1 行のステータス応答 |
| 適していない用途 |
改行のないプロンプト、\r 再描画ターミナル（receive$ / terminalText$ を優先） |
| 詳細 |
高度な使用方法 – 行フレーミング · ストリームの選び方 |
ターミナル / CR 処理
|
|
| 対象 API |
terminalText$, receive$（および SerialSessionOptions.terminalBuffer） |
| 適している用途 |
ターミナル風 UI へのバインド、\r 再描画の折りたたみ、任意の ANSI 除去 |
| 適していない用途 |
厳密な行パーサ（lines$ を使う）；ワイヤ Uint8Array 受信の期待 |
| 詳細 |
ストリームの選び方 · 高度な使用方法 · createTerminalBuffer |
Command / Response
|
|
| 対象 API |
lines$ または receive$、send$（待ち→送信を組み立てる。コア request$ はない） |
| 適している用途 |
コマンド送信後に一致する行／プロンプトを待つ、concatMap で直列化 |
| 適していない用途 |
送信のみのログ；遅れて購読しても過去の emit が再生されると期待すること |
| 詳細 |
Request / Response レシピ |
タイムアウト
|
|
| 対象 API |
connect$ や応答待ちまわりの RxJS timeout（アプリ方針。コアの接続リースではない） |
| 適している用途 |
ポート選択／接続待ちや応答待ちの上限 |
| 適していない用途 |
タイムアウト＝非冪等コマンドの「安全な再送」とみなすこと |
| 詳細 |
接続のタイムアウト · 応答待機のタイムアウト |
キャンセル
|
|
| 対象 API |
takeUntil、購読解除、Component / Hook の破棄 |
| 適している用途 |
UI 破棄時に処理を止める；ユーザーキャンセルとデバイス障害の区別 |
| 適していない用途 |
OPERATION_CANCELLED のあとポート選択を自動で開き直すこと |
| 詳細 |
takeUntil によるキャンセル · 破棄時のキャンセル |
再接続ポリシー
|
|
| 対象 API |
state$, connect$, errors$；dispose$ 後は新しい SerialSession |
| 適している用途 |
アプリ側の回数制限付き再試行／復旧可能な失敗後の手動再接続 |
| 適していない用途 |
コア自動再接続；disposed セッションへの再接続；無限再試行 |
| 詳細 |
disposed では再接続しない · 致命的エラー時の再接続 · 再試行してよい処理 |
Fake SerialSession テスト
|
|
| 対象 API |
差し替え可能な SerialSession 契約を満たす Fake（npm 非同梱） |
| 適している用途 |
USB 実機なしの単体／結合テスト、CI での失敗注入 |
| 適していない用途 |
本番で本物の Web Serial スタックを置き換えること |
| 詳細 |
実機なしテスト · 差し替え可能な公開契約 |
バイナリ送信（Uint8Array）
|
|
| 対象 API |
send$(Uint8Array) — バイト列をそのまま書き込む |
| 適している用途 |
対向が既に理解している不透明なバイナリペイロードの送信 |
| 適していない用途 |
バイナリ受信（receiveBytes$ / Uint8Array 受信ストリームなし）；Modbus RTU / COBS / SLIP をライブラリ機能として期待すること |
| 詳細 |
対応範囲 · 設計検討 #545 |
短い例（送信のみ。受信は引き続き UTF-8 テキスト）:
import { firstValueFrom } from 'rxjs';
import { createSerialSession } from '@gurezo/web-serial-rxjs';
const session = createSerialSession({ baudRate: 115200 });
await firstValueFrom(session.connect$());
const payload = new Uint8Array([0x01, 0x02, 0x03]);
await firstValueFrom(session.send$(payload));
関連