meshcore-packet-capture

MeshCore パケットキャプチャ

meshcore-packet-capture の操作、設定、デプロイ、トラブルシューティングを行う際に、このスキルを使用してください。特に、Companion 無線機、BLE／シリアル／TCP キャプチャ、MQTT パブリッシング、LetsMesh、TOML 設定、Docker、systemd、launchd、NixOS に関するリクエストが対象です。

対象範囲

このプロジェクトがキャプチャするのは、MeshCore の Companion 無線機のみです。リピーターや RoomServer のキャプチャには使用せず、代わりに meshcoretomqtt を使用してください。

運用ワークフロー

1. 設定を変更する前に、トランスポートを特定してください。
   • ble：直接アドレス、デバイス名、または一般スキャン。
   • serial：1 つ以上のシリアルポート。ランタイムでは、設定された最初のポートが使用されます。
   • tcp：ホストとポート。SDK による自動再接続は、デフォルトで有効です。
2. インストール済みの CLI を優先してください。

   meshcore-packet-capture --help
   meshcore-packet-capture --debug
   

   チェックアウトしたリポジトリでは、python3 -m meshcore_packet_capture または python3 packet_capture.py を使用してください。 検証済みの CLI の範囲（v2.2.0）： パーサーが公開しているのは、--output、--verbose、--debug、--no-mqtt、繰り返し指定可能な --config、および隣接ノード検出のオンデマンド用オプション --neighbors-now／--neighbors-exit の組み合わせです（1 回のゼロホップ隣接ノード検出とスコープのサイクルを直ちに実行し、--neighbors-exit を指定するとサイクルの完了時に終了します）。--show-config やドライランのフラグは公開されていません。他のフラグを記載または使用する前に、実際にインストールされたバイナリで --help を実行してください。設定プレビュー用のコマンドを作り出してはいけません。
3. ネットワークへのアップロードを行う前に、IATA コードを 1 つと、少なくとも 1 つの MQTT ブローカーを設定してください。LOC はプレースホルダーであり、デプロイで使用できる識別情報ではありません。
4. 無線接続を切り分ける際は、まず --no-mqtt を使用してください。デバイスがパケットをローカルでキャプチャできた後に、MQTT を追加してください。
5. 変更のたびに、実際の動作境界を確認してください。デバイス接続ログ、パケット出力、ブローカー接続、サービス／コンテナーの状態を確認します。インストールの成功だけで、キャプチャが正常に動作していると判断してはいけません。

変更ゲート： リクエストが読み取り専用または計画のみの場合、実行するアクションとして停止／開始／編集／削除／再起動コマンドを提示してはいけません。将来の変更は分けて説明し、すべての例に未実行であることを明記してください。また、最初の変更を行う前に、対象、範囲、ロールバックの確認を必須としてください。

設定ルール

設定の優先順位は高いものから低いものへ、次のとおりです。

1. 実際の PACKETCAPTURE_* プロセス環境変数。
2. TOML：/etc/meshcore-packet-capture/config.toml、続いてソート順の config.d/*.toml。
3. 作業ディレクトリ／パッケージディレクトリ内のレガシーな .env.local、続いて .env。

--config PATH を複数回使用すると、指定した TOML ファイルのみを順番に読み込みます。後に読み込まれたファイルが、前のファイルを上書きします。TOML のブローカーブロックは name によってマージされ、有効なブローカーは連番の PACKETCAPTURE_MQTT<n>_* スロットに展開されます。ユーザーによる上書き設定は config.d/99-user.toml に保存してください。

最小限の TOML 構成：

[general]
iata = "SEA"

[capture]
connection_type = "serial"
# ble_pin = "123456"   # optional six-digit PIN for BLE connections

[serial]
ports = ["/dev/ttyUSB0"]

[[broker]]
name = "home"
enabled = true
server = "mqtt.example.com"
port = 1883
transport = "tcp"
# include_decoded = true   # publish the nested "decoded" object to this broker
# neighbors = true         # publish the neighbors snapshot to this broker

[broker.auth]
method = "password"
username = "user"
password = "secret"

すべてのオプションの対応表、ブローカー認証、トピックテンプレート、パケットフィルター、優先順位に関する例外については、references/configuration.md を参照してください。

オプション機能ブロック（v2.1.0+）

• ペイロードのデコード（decode_payloads、include_decoded、decode_hashtag_channels、decode_channel_keys、decode_include_public）：プレーンテキスト／構造化フィールドを含むネストされたdecodedオブジェクトを追加します。GRP_TXT チャネルメッセージは復号され（送信者、テキスト）、ADVERT は解析され（名前、役割、緯度／経度）、人が読みやすいタイプ／ルートのラベルとパスが含まれます。生のフィールドは変更されません。ダイレクトメッセージ（TXT_MSG）は、受動的な監視者には復号できません。デフォルトでは無効です。オプトインするには、各ブローカーの[[broker]]ブロックでinclude_decoded = trueを設定します。
• 近隣ノードの公開（ブローカーごとのneighborsに加え、neighbors_interval_hours、neighbors_discover_window、neighbors_command_timeout、neighbors_scope_timeout、neighbors_scope_min_timeout、neighbors_scope_gap、neighbors_cycle_timeout、neighbors_max、neighbors_self_scopes）：定期的なゼロホップ近隣ノードテーブルと、各近隣ノードの地域スコープをneighborsトピックに公開します。デフォルトでは無効です。少なくとも1つの有効なブローカーでneighbors = trueに設定されている場合にのみ、サイクルが実行されます。IATA（または明示的な[broker.topics] neighbors）が必要です。監視用ファームウェアに合わせて、間隔は12～336時間に制限されます。--neighbors-now／--neighbors-exitを指定すると、サイクルをオンデマンドで実行します。
• ログローテーション（log_rotation = off|size|time、log_max_bytes、log_rotation_when、log_backup_count）：--outputで出力ファイルを指定した場合にのみ適用されます。

MQTT と認証

• ブローカーは順番に処理され、固定の上限はありません。MQTT<n>_ENABLEDが見つからないと検出が終了するため、番号を飛ばさないでください。
• 対応するトランスポートはtcpとwebsocketsです。安全なトランスポートを使用するには、TLSを明示的に指定してください。
• パスワード認証ではusernameとpasswordを使用します。
• トークン認証では、Ed25519 JWT形式のトークンを使用します。接続された無線機が対応している場合はデバイス上での署名が推奨されます。利用可能な64バイトの秘密鍵がある場合は、Pythonによる署名がフォールバックとして使用されます。
• 秘密鍵を公開スキル、コマンドの記録、コミット済みの.env、共有Docker Composeファイルに含めないでください。保護されたキーファイルまたはシークレットの注入を優先してください。
• トピックのプレースホルダーは{IATA}、{IATA_lower}、{PUBLIC_KEY}、{TOKEN}です。ブローカーごとのトピック設定はグローバルなトピック設定より優先されます。RAWは明示的に設定されていない限り公開されません。ブローカーごとのトピックは、status、packets、decoded、debug、raw、neighborsです。decodedトピックには、include_decodedが有効な場合にネストされたデコード済みオブジェクトが含まれます。neighborsトピックには、neighborsが有効な場合に定期的な近隣ノードのスナップショットが含まれます。
• トークン認証を使用するブローカーでは、ブローカーごとのownerとemailが、グローバル設定のcapture.owner_public_key／capture.owner_emailより優先されます。
• LetsMesh Analyzerのブローカーには、設定済みのIATAが必要です。LetsMeshのデプロイで、デフォルトのLOCを黙って受け入れないでください。

デプロイの既定値

レガシーなハイブリッド構成でのインストールも可能です。systemd または launchd のユニットで、ユーザーのホームディレクトリ配下にあるチェックアウトをラップし、/opt や /etc の TOML ファイルを使わずに .env.local を読み込むことがあります。最新の管理対象インストール方法を選ぶ前に、実行中のコマンド、作業ディレクトリ、サービスユニット、環境変数／設定の読み込み元を確認してください。

• 手動／PyPI： pipx install meshcore-packet-capture を実行すると CLI がインストールされます。バックグラウンドサービスはインストールされません。
• 管理対象の Linux／macOS： root で実行するブートストラップインストーラーにより、/opt/meshcore-packet-capture、/etc/meshcore-packet-capture、仮想環境、システムサービスが作成されます。既定では公開済みの最新リリースがインストールされます。バージョンを固定するには --tag または --branch を使用してください。
• ユーザーサービス（v2.1.0+）： Linux 上のローカルチェックアウトでは、./install.sh --user-service を実行すると、チェックアウトの .venv から実行するユーザーごとの systemd サービスが作成されます（チェックアウトがスクリプトのディレクトリにない場合は --repo-dir PATH を渡してください）。設定ファイルはリポジトリ自体にあります（.env、.env.local、config.toml、config.d/）。同じチェックアウトから ./uninstall.sh --user-service を実行して削除してください。ローカルの .venv も削除するには --remove-venv を追加します。systemctl --user status|restart meshcore-packet-capture と journalctl --user -u meshcore-packet-capture -f で管理できます。
• macOS BLE： Bluetooth の権限はログインユーザーに属するため、ユーザーごとの LaunchAgent を使用してください。シリアル／TCP には LaunchDaemon を使用できます。
• Docker： 公開済みのイメージを使用するか、docker compose up -d を実行してください。シリアル接続にはデバイスのマッピングが必要です。BLE では通常 privileged: true が必要で、ホストネットワークも必要になることがあります。ハードウェアアクセスには Linux が最も信頼性の高いコンテナホストです。
• NixOS： services.meshcore-packet-capture を使用し、sudo nixos-rebuild switch で再構築してください。

サービスコマンド、Docker のハードウェアアクセス、移行／更新時の動作、範囲を限定した診断については、references/deployment-and-troubleshooting.md をお読みください。

出力と検証

通常モードでは、最小限のパケット情報が出力されます。--verbose を指定すると JSON パケットデータが追加され、--debug を指定すると接続、再試行、パケット解析、MQTT の診断情報が追加されます。--output PATH を指定すると、パケットデータがファイルに書き込まれます。キャプチャされたレコードには、デバイス識別情報、タイムスタンプ、パケットタイプ、ルート、ペイロードの長さ、生の 16 進数データ、SNR、RSSI、ハッシュが含まれます。decode_payloads が有効な場合、人が読めるフィールド（チャネルメッセージの送信者／テキスト、ADVERT の名前／役割／座標、タイプ／ルートのラベル）を含むネストされた decoded オブジェクトもレコードに追加されます。

トラブルシューティングでは、次の順序で証拠を収集してください。

1. meshcore-packet-capture --debug --no-mqtt を実行し、実際に BLE、シリアル、または TCP 接続が確立されることを確認します。
2. コンソールまたは --output ファイルにパケットレコードが表示されることを確認します。
3. ブローカーを 1 つ有効にし、ブローカーへの接続／再接続メッセージを確認します。
4. 機密情報を表示せずに、解決された環境変数／設定とトピック名を確認します。
5. 管理対象サービスの場合は、サービス独自のログとステータスを確認します。Docker の場合は、docker compose config、docker compose ps、docker compose logs を使用します。

診断中にインストールディレクトリ、状態ディレクトリ、設定を削除しないでください。アンインストーラーは対話式で、ユーザー設定をバックアップしますが、確認後にのみ破壊的な削除を実行します。

使用しない場合

MeshCore リピーターまたは RoomServer のパケットキャプチャ、一般的な MQTT 管理、アップストリームリポジトリ内での変更実装には、このスキルを使用しないでください。コードを変更する場合は、リポジトリのコントリビューションワークフローに従い、プロジェクトのテストを別途実行して検証してください。

参考資料

ファイル	読み込むタイミング
references/configuration.md	TOML／環境変数の設定、MQTT トピック、認証、またはパケットフィルターを記述するとき
references/deployment-and-troubleshooting.md	インストール、アップグレード、Docker／systemd／launchd／NixOS の実行、またはサービスの起動失敗をデバッグするとき
references/source-index.md	ソースのカバレッジやバージョンマーカーを確認するとき、またはこのスキルをアップストリームに照らして再検証するとき

完了条件

選択したトランスポートが接続され、パケットがローカルで観測され、MQTT が対象範囲に含まれる場合は意図した MQTT トピックがデータを受信し、関連するサービス／コンテナーが正常と報告されるまで続行します。ハードウェア、認証情報、またはブローカーへのアクセスが利用できない場合は、成功したと主張せず、未検証の範囲を正確に報告してください。