architecture.md

AzaraC アーキテクチャドキュメント

概要

AzaraCは準天頂衛星システム（QZSS）のL1S信号から災危通報メッセージをデコードするArduinoライブラリです。本ドキュメントでは、ライブラリの内部アーキテクチャと設計思想について解説します。

ファイル構成は開発者ガイドを参照してください。

システム構成図

graph TD
    GNSS["GNSS モジュール<br/>(u-blox, Furuno, Sony 等)"]
    GNSS -->|"UART: NMEA $QZQSM / UBX-RXM-SFRBX"| Parser

    subgraph Parser
        FramerAuto["フレーマー自動判別<br/>(UBX/NMEA)"]
        UBX["UbxFramer"]
        NMEA["NmeaFramer"]
        FramerAuto --> UBX
        FramerAuto --> NMEA
        Custom["CustomFramer<br/>(排他モード: IFramer)"]
        UBX --> Frame
        NMEA --> Frame
        Custom --> Frame
        Frame["Frame (ビット列)"]
        Frame --> Decoder
        Decoder["Decoder<br/>CRC-24Q → msg_type 分岐"]
        Decoder --> MT43["MT=43 QZQSM<br/>(12カテゴリ)"]
        Decoder --> MT44["MT=44 DCX/CAMF<br/>(A1-A18, B1-B4)"]
        MT43 --> Msg["Message"]
        MT44 --> Msg
        Msg --> Nankai{"MT=43 cat.4?"}
        Nankai -->|"Yes"| NankaiBuf["NankaiPageBuffer<br/>ページ集約"]
        Nankai -->|"No"| Dedup["DedupFilter<br/>{svid, msg_type, crc24}"]
        NankaiBuf --> Dedup
        Dedup --> Out["Message 出力"]
    end

    Out --> Serializer
    Serializer["JsonSerializer<br/>Message → JSON → Print&"]

Loading

コンポーネント詳細

1. Parser (パーサー)

Parserはライブラリのメインエントリーポイントです。

• フレーマー自動判別: 入力バイトストリームからUBX/NMEAを自動判別（UBX同期文字0xB5 0x62、NMEA$文字で判定）
• メッセージデコード: フレームの復号とCRC検証
• 重複除去 + 南海トラフページ集約: postDecode() がNankai集約・重複チェック・メッセージ出力を一元管理

graph LR
    A["feed(byte)"] --> B["Framer"]
    B --> C["Decoder.decode()"]
    C --> D["postDecode()"]
    D --> E["NankaiPageBuffer<br/>(MT=43 cat.4)"]
    E --> F["DedupFilter: 重複チェック"]
    F --> G["out"]

Loading

2. Framer (フレーマー)

IFramerインターフェースを実装:

フレーマー	プロトコル	対応デバイス
UbxFramer	UBX-RXM-SFRBX	u-blox M10, ZED-F9P
NmeaFramer	NMEA $QZQSM	Furuno GT-87, 汎用GNSS
Custom (IFramer)	任意	Sony, その他

3. Decoder (デコーダー)

Decoderはビット列からメッセージフィールドを抽出します。

共通処理: CRC-24Q検証（IS-QZSS-L1S §3.2.8準拠）、MSB-firstビット抽出、UNIX時刻ベースの年月補正。

MT=43: DecoderQzqsmがX-macroテーブルAZARAC_DC_CATEGORIESから全12カテゴリのサポート判定・ディスパッチを生成。カテゴリ一覧はAPIリファレンスを参照。

MT=44: 階層構造のCAMFフォーマット（A1-A18 + B1-B4拡張）を解析。サービス種別（L-Alert, J-Alert 等）の判定条件はAPIリファレンスを参照。

4. DedupFilter (重複除去)

DedupFilterは{svid, msg_type, crc24}によるリングバッファで重複除去。デフォルト8スロット。複数衛星受信時は AZARAC_DEDUP_SLOTSを増やす。

5. NankaiPageBuffer (南海トラフページ集約)

NankaiPageBufferは最大63ページに分割される南海トラフ地震メッセージを集約。受信したページのみを保持し、典型的なメッセージ（1〜5ページ）では70〜80%のメモリ削減。バッファが全て使用中の場合はLRUエビクションで最も古いバッファを解放。

6. JsonSerializer (JSONシリアライザ)

JsonSerializerはMessageをJSON形式にシリアライズ。ヒープアロケーションなし、固定バッファで処理。Print& 経由で出力（Serial, WiFiClient 等）。日本語/英語ラベルの選択的コンパイル対応。

データフロー

graph TD
    A["GNSSモジュール"] -->|"1バイトずつ"| B["Parser::feed()"]
    B --> C["Framer: フレーム境界検出"]
    C --> D["Decoder: CRC検証 → デコード"]
    D --> E{"MT=43 cat.4?"}
    E -->|"Yes"| E2["NankaiPageBuffer: ページ集約"]
    E -->|"No"| F["DedupFilter: 重複チェック"]
    E2 --> F
    F --> G["Message出力"]
    G --> H["toJson()"]
    H --> I["Print& (Serial, WiFiClient 等)"]

Loading

メモリ設計

コンポーネント	メモリ使用量	備考
DedupFilter	AZARAC_DEDUP_SLOTS × 6 B	デフォルト48B
NankaiPageBuffer	可変（~200B + ページ数 × 20B）	LRUエビクション
定義テーブル	約15-30KB	AVR では Flash (PROGMEM) 配置

関連ドキュメント

• API リファレンス
• 開発者ガイド