5. GitLabでの開発・連携メモ」②（SatNOGS-decoders編 Kaitai構文とデコード設計の工夫）

---

Kaitai構文とデコード設計の工夫（rsp03.ksy）

RSP-03衛星のGMSKビーコンデータは AX.25フレーム内に格納されており、ペイロード部の内容は packet_type によって切り替わります。

これをKaitai Structで構文定義するために、以下のような工夫を行いました。

---

📐 Step 1：Kaitai Struct構文の基本（meta, instance, case）

.ksy ファイルで用いる主な構文：

構文	説明
meta:	ファイルのエンコーディングやフォーマット名を定義
seq:	バイナリを読み取る順番・フィールド構造を定義
types:	ネスト構造やswitch-caseによるサブ構造体定義
switch-on:	条件に応じて型（packet1〜3など）を切り替える
instance:	バイナリの一部を変数として再解釈したいときに使用
enums:	packet_typeなど数値にラベルをつけるときに使う

types:
  payload_type:
    seq:
      - id: packet_type
        type: u1
      - id: body
        type:
          switch-on: packet_type
          cases:
            1: packet1
            2: packet2
            3: packet3

🧱 Step 2：インデントとの闘い

YAMLベースの .ksy は、インデント1つで構文エラーになるため注意が必要です。

• seq: の下は 2スペースインデント
• types: や instances: の下も 統一したインデント深さが必要
• switch-on の cases: は さらに1段階深くなる
• 開発初期には以下のようなミスが頻出：

yaml

- id: body
   type:  # ← ここで1スペース多いとエラーに

→ Kaitai Struct IDE　https://ide.kaitai.io
で構文をテストしながら少しずつ修正するのがコツです。

🛰️ Step 3：SatNOGS固有の :fields 定義とデータ視覚化

SatNOGSでは、Kaitai構文によって得られた各変数を、Web上の可視化ツール（Grafanaなど）に連携させるため、通常の .ksy 定義とは別に、特殊な補足記述 :fields を求められます。

※ fields: ではなく、先頭にコロンがついた :fields です。これはSatNOGSのデコーダ構造に特化した追加仕様です。

以下のような記述が要求されます,HK Beacon Formatの変数と、ksyファイルの関係を示すものです

yaml

doc: |
  :field dest_callsign: ax25_frame.ax25_header.dest_callsign_raw.callsign_ror.callsign
  :field system_time: ax25_frame.payload.packet1.system_time
  :field temperature: ax25_frame.payload.packet1.temperature_c
  :field antenna_deploy: ax25_frame.payload.packet1.antenna_deploy_status

この :field 記法は、SatNOGSが .ksy で定義されたデータ構造の中から、GrafanaやCSVエクスポート時に出力するべき項目を指定するために使われます。

⚠ 苦労ポイント

• Kaitaiの入れ子構造のパスをすべて書く必要がある　ex)ax25_frame.payload.packet1.system_time

• .ksy を変更するたびに、この :field も連動して修正が必要

• フィールド名とpathの整合性を一度間違えると、表示が一切されないため、デバッグに非常に時間がかかります

🧩 Step 3.5：Kaitai Structと :fields の紐づけ例

yaml

meta:
  id: rsp03
  endian: le

seq:
  - id: ax25_frame
    type: ax25_ui_frame

doc: |
  :field dest_callsign: ax25_frame.ax25_header.dest_callsign_raw.callsign_ror.callsign
  :field source_callsign: ax25_frame.ax25_header.source_callsign_raw.callsign_ror.callsign
  :field packet_type: ax25_frame.payload.packet_type
  :field temperature: ax25_frame.payload.packet1.temperature_c
  :field system_time: ax25_frame.payload.packet1.system_time

このように定義しておくことで、SatNOGSのデコードUI上で正しく項目が抽出・表示されるようになります。

📊 pandas / Grafana連携にも効果大

• :field 定義された項目のみがCSV・Grafanaに流れるため、事前に定義しないと一切可視化されません
• scale, desc 等は .yaml 側で指定可能（.ksy には入れない）

📊 Step 4：Grafana／pandas連携を見据えた設計

• フィールド名は英語で統一：GrafanaやLooker Studioのキーにそのまま反映されるため単位やスケールを補足：温度 *0.1、電圧 *0.001 など、読みやすい形式に変換できる

• 時刻情報はUNIX時間形式に統一：pandas等で時系列解析しやすくなる

🔚 おわりに

この .ksy ファイルはGitLabの satnogs-decoders にMerge Request済であり、SatNOGSデコーダとして今後の運用に活用される予定です。

次のセクションでは、Libre Space ForumやGitLab上でのレビュー対応、コメントへの調整を紹介します。

関連記事リンク

0. 初めに — リーマンサット RSP-03 受信チャレンジの歩み
5. GitLabでの開発・連携メモ①（SatNOGS-decoders編）
6.SatNOGSコミュニティとのやりとり
7トラブルとその解決の記録