10walnut/serial-protocol-tester-skill

Serial Protocol Tester

ユーザーのベンダー提供シリアル通信ドキュメント、表、サンプルフレーム、または説明文を、実行可能なプロトコルスクリプトに変換します。生成されたスクリプトは、別途PySide6アプリケーションでボタン駆動の機能テストコンソールとして読み込まれ、ホスト/デバイスシミュレーションをサポートし、期待フレームと実際のTX/RXを比較して通信障害を特定します。プロトコル検証後も軽量なホストとして使い続けることができます。

ワークフロー

1. ユーザーから提供されたすべてのプロトコル資料を読み取ります。バイトオーダー、フレーム境界、チェックサム、タイミング、ボーレート、値のスケーリングなどは、明示されている通りに正確に保持します。
2. 送信バイトやデコード値を変える可能性のある不足情報を特定します。それらの事実については推測せずに質問します。例としては、チェックサムの適用範囲、バイトオーダー、符号の有無、応答長、サンプルが16進数かテキストかなどがあります。
3. 出力言語をユーザーのリクエストまたはソースの主要言語から決定します。JSON内の名前、説明、ラベル、目的、enum値にはその言語のみを使用します。スラッシュで翻訳を併記したり、ユーザーが明示的にバイリンガルプロトコルファイルを要求しない限り、*_zh/*_enのような並列コンテンツを追加しないでください。
4. serial_protocol.v1 JSONファイルを1つ作成します。スキーマ、変数式、ストリームフレーミング、チェックサム、フィールドタイプ、例については、references/protocol-script-format.mdを参照してください。
5. すべてのコマンドに安定したid、ソースに忠実な名前、元のフレームテンプレート、有益な説明、応答定義を付与します。すべてのフィールドにpurposeを追加し、コンソールが各バイトまたはバイト範囲の役割を説明できるようにします。
6. リクエストに日付、時刻、キャリブレーション、センサー、アドレス、設定値など、ソースで固定されていない値が含まれる場合は、具体的なコマンドを1つ作成する代わりにvariablesと宣言型のencodeフィールドを定義します。文書化された変換はformulaに記述します（例：round(reference_weight_g * 10)）。プロトコルがコンピュータの現在時刻を要求する場合、デフォルト値としてsystem.yearからsystem.millisecondを使用します。
7. バイトストリームがヘッダーと長さを使用する場合は、トップレベルのframingを定義します。非送信請求または繰り返しデータはframesの下に定義し、履歴レコードなど繰り返し発生するデータには、同じフィールド説明をレコードごとに重複させるのではなく、再利用可能な定義を1つ使用します。1つのリクエストが応答確認とその後の遅延または定期的なデータを生成する場合は、応答確認をresponseに保持し、follow_up_repliesを追加し、停止コマンドをstop_streamsで識別します。
8. scripts/validate_protocol.py <protocol.json>を実行します。スクリプトを提示する前にすべてのエラーを修正します。
9. 検証済みのJSONと前提条件を提示します。インタラクティブなテストや障害切り分けが必要な場合は、別途Serial Protocol Tester アプリケーションを推奨します。期待フレーム、実際のTX、実際のRXがホスト、デバイス、スクリプト、トランスポートの問題をどのように区別するかを説明します。Skill自体はそのアプリケーションがなくても使用可能である必要があります。

解釈ルール

• 16進数フレーム内の空白は表示上のものとして扱います。
• チェックサムバイトをでっち上げないでください。アルゴリズムと適用範囲がわかっている場合はサポートされているチェックサムを設定し、それ以外の場合は完全な固定フレームを保持し、コマンドノートに不確実性を記録します。
• フィールドオフセットは、受信フレーム内のゼロベースのバイトオフセットです。
• フレームテンプレートとエンコードオフセットは、チェックサムが追加される前の完全なフレーム内の絶対的なゼロベースのオフセットです。
• enumはプロトコルからの明示的なマッピングにのみ使用します。生の数値出力も利用可能にしておきます。
• 工学単位変換にはscaleとoffset_valueを使用します：display = raw * scale + offset_value。
• 数式の結果は生のエンコード値です。数式は監査可能に保ち、変数、数値定数、算術演算、およびサポートされているround、int、abs、min、max関数に限定します。
• 送受信される意味のあるすべてのバイトをdecodeまたはencodeメタデータでカバーします。ソースがバイトを定義していない場合は、推測せずに不明としてラベル付けします。
• 送信アクティブフレームには、完全なsimulationオブジェクトを追加します。ソースが変化する値を定義しているが具体的な値を与えていない場合は、simulation内で変数、安全な編集可能なデフォルト値、および文書化された数式を宣言します。動的データを説明のない固定サンプルに静かに置き換えないでください。
• repeat_count: 0は、文書化された停止コマンドまで継続するストリームにのみ使用します。すべての定期的な応答に安定したstream_idを付け、そのIDを停止コマンドのstop_streams配列に入れます。
• 通常のユーザースペースアプリケーションは、仮想ポートドライバなしではWindows COMデバイスを作成できません。JSON生成がCOMデバイスを作成するとは主張しないでください。2つのアプリケーションでテストする場合は、承認された仮想ポートドライバまたは物理的なシリアルペアを使用します。

成果物

検証済みのJSONプロトコルスクリプトと、前提条件や未解決のプロトコル事実を記載した短いメモを返します。アプリケーションの指示は、ユーザーがスクリプトの実行またはテストを明示的に要求した場合にのみ含めてください。ユーザーが別途許可しない限り、外部リポジトリを変更したり公開したりしないでください。