CM4からcrane・メインPCへ送る共通状態パケット（仮仕様）¶

目的と範囲¶

craneが制御に使う位置・グローバル速度・ボール検出・yawと、監視に使う温度・電圧・電流・エラーを、CM4が固定の形式に変換して送る。Mainの共通feedback packetを変更しても、craneとメインPCはその配置を解釈しない。変換はCM4に閉じ込める。

この文書は**仮仕様**であり、共通パケット生成・crane側の受信・メインPCの共通監視ツール・4WS Mainの生データ配信は未実装。両機種のMain→CM4の仕様はフィードバックパケット、CM4→Mainの仕様は制御パケットに記す。

送信データのブロック図¶

flowchart LR
    orion_main["OrionMain<br/>UARTフィードバック"]
    ws["4WS Main<br/>SPI feedback packet（予定）"]

    subgraph cm4["CM4"]
        hw["機体設定<br/>ローカルカメラ搭載有無"]
        orion_adapter["UART受信（OrionMain）"]
        ws_adapter["SPI受信（4WS、予定）"]
        decode["共通feedbackデコーダ<br/>128B・同期・CRCを検証"]
        raw_type["UDP転送コピー<br/>4WSのみbyte 1を0xEBに変更"]
        common["共通状態<br/>位置・グローバル速度・yaw・ボールセンサ・status<br/>値の単位を統一"]
        serialize["共通パケット生成<br/>version 1 / 55B<br/>機体タイプ・ハードウェア仕様フラグを付与"]
        multicast["機体別UDP multicast<br/>224.5.20.(100+N):50200+N"]
        raw_multicast["生フィードバック multicast<br/>224.5.20.(100+N):50100+N"]
        orion_adapter --> decode
        ws_adapter -.-> decode
        decode --> common
        decode --> raw_type --> raw_multicast
        common --> serialize
        hw --> serialize
        serialize --> multicast
    end

    orion_main --> orion_adapter
    ws -.-> ws_adapter
    multicast --> crane["crane受信器<br/>位置・グローバル速度・yaw・ボール検出を制御へ<br/>statusを監視へ"]
    multicast --> pc["メインPCの共通監視ツール<br/>共通statusを表示・記録"]
    raw_multicast --> debug["Orion/4WS両対応デバッグツール<br/>同期値で機体を判別し共通配置を解析"]

ローカルカメラのボール検出はCM4内部のmode 7・8制御で使う別入力である。このパケットのball_detectは**機体のボールセンサ**を表し、カメラの検出結果とは混ぜない。 hardware_flagsのカメラ搭載ビットはハードウェア構成を表し、カメラの稼働状態やボール検出状態では変化しない。 OrionMainのUARTは現在の受信処理1か所で読み、検証後に診断配信と共通状態への変換を分岐させる。4WSのSPIでも同じfeedbackデコーダを使う。

CM4からの送信系統とPCツール¶

1台のCM4に接続するMainは設定で1種類に確定するため、生フィードバックは機体タイプごとにポートを増やさない。Main→CM4はどちらも共通の128バイトfeedback packetで同期値は0xAB 0xEA。CM4は長さ・同期・CRCを検証して共通状態への変換と生データ配信へ分岐する。OrionMainはフレームをそのまま配信する。4WSではUDP転送コピーのbyte 1だけを0xEBに変え、デバッグツールが機体を判別できるようにする。CRC対象はbyte 3..127なので再計算は不要である。

メインPCの共通監視ツールは生フィードバックを購読しない。robot-feedback-receiverとrobot-feedback-viewerはOrionMainと4WS Mainの生データを扱うデバッグツールであり、機体タイプを判別した後は共通のfeedback配置を使う。4WS MainのSPI通信とCM4からの配信は未実装である。共通状態パケット自体の意味を変える場合だけ、versionを更新して共通監視ツールとcraneの受信処理を揃える。

通信と受信規則¶

• 機体番号をNとし、送信先は224.5.20.(100+N):50200+Nとする。craneとメインPCの共通監視ツールは同じグループへ参加する。Mainの生フィードバック50100+Nとはポートを分ける。
• 有効な機体側の状態を1件受けるごとに1件送る。入力が途絶えた場合、最後の値を新しいパケットとして繰り返さない。受信側は到着時刻を基準に100 msを超えた状態を制御に使わない。送信周期は機体側の状態更新に従い、固定周期を要求しない。
• UDPの送信先ポートでこのパケットを識別する。受信側は56バイト以上のバッファを用意し、recvfrom等で得たデータ長が55バイトであること、versionが1であること、machine_typeが定義済みの値であることを確認する。機体番号は参加したmulticastグループとポートで識別する。送信側はUDPチェックサムを有効にする。
• ペイロード内にmagic、長さ、機体番号、独自CRC、連番、送信時刻、予約バイトは設けない。ポート・受信長・UDPチェックサムで確認できる情報を重複させず、鮮度は受信側の到着時刻で判定する。
• 位置・グローバル速度・yaw・ボール検出が揃い、かつ数値が有限である場合に送信する。いずれかが取得できない場合は共通パケットを生成しない。craneは受信鮮度を確認して制御に使う。
• 機体側の長さ・同期・CRCが不正な場合も共通パケットを生成しない。通常feedbackが停止するFW更新中は、更新応答を共通状態の入力として扱わない。
• 温度を持たない箇所は0で埋める。温度は高温の判定にだけ使用し、0を実測値や正常動作の証明として扱わない。その他のstatus項目は送信前に取得できることを前提とする。

ペイロード案¶

UDPペイロードは55バイト固定。整数はlittle-endian、浮動小数点はIEEE 754 binary32のlittle-endian。値の単位と意味は機体側のパケット配置に依存させない。

versionはポートによるパケット種別の識別とは別に、同じポートで受けた共通パケットの配置を判定するために残す。配置や意味を変える場合は値を更新し、未対応の受信側は破棄する。 machine_typeは機体番号とは独立した駆動機構の種類を表す。CM4の機体設定から決定し、OrionMain接続機はOrionMain=1、4WS Main接続機は4WS=2を送る。未定義の値は受信側で破棄する。 hardware_flagsはbit 0のみ定義する。1はCM4にローカルカメラを搭載、0は非搭載を表す。送信側はbit 1..7を0にし、受信側はこれらのビットを無視する。搭載機でカメラが停止・故障していてもbit 0は1のままとする。

Orionにステアモーターがない場合はsteering_motor_temp[4]を0にする。エラー情報の意味は共通のエラーID定義ができるまでは機体依存とし、craneは0/非0と表示用の数値として扱う。

yawは位置と同じフィールド座標に合わせる。OrionMainのimu_yaw_degはCM4で角度単位と原点を変換する。フィールド原点との対応が確定できない場合は共通パケットを送信しない。

OrionMain受信アダプタでは、vision_based_position_x/yを位置、global_odom_speed_x/yをグローバル速度、ball_detection[0]をball_detect、imu_yaw_degをyawの入力候補とする。電圧・温度・電流・エラーはフィードバックパケットの同名フィールドから変換する。

変更時の担当範囲¶

craneの制御・監視とメインPCの共通監視ツールは共通パケットだけに依存させる。