Meshyface

Meshyface は、単一の Python サービスとして動作し、HTTP 経由でシングルページの Web UI を提供する、チャットファーストの Meshtastic ダッシュボードです。

現在のアプリケーション領域

現在の UI は以下を提供します:

• チャットおよびダイレクトピア会話
• ネットワークワークスペース（マップ、概要、リンク、ルート、センサー、トップ10ランキング、ノード詳細、オンデマンド履歴）
• コンソールワークスペース（ライブパケット/ログ出力）
• アプリワークスペース（ゲームと、ファイル転送が有効な場合のファイルタブ）
• 設定ワークスペース（ラジオ、デバイス、接続、ロケーション、チャンネル、ティッカー、リスト、外観、概要ペイン）
• SQLite ベースの履歴、検索、ロールアップ、テーマ永続化、カスタムテレメトリルール永続化

コンソールワークスペース

コンソールワークスペースは、パケットトラフィック、履歴検索、メッシュユーティリティコマンドのための端末スタイルの制御画面です。

• コマンド名を入力すると、オートコンプリートの提案が開きます。Tab または Enter で確定、ArrowRight でゴーストされたサフィックスを受け入れ、ArrowUp / ArrowDown でポップアップ内を移動します。
• ノードターゲットを指定するコマンドでは、名前、ID、絵文字、タグ、ステータス、ホップ、GPS、最終受信状態、ポート、ノード番号を含むリッチなノード提案が表示されます。通常のテキストはノード名とタグで絞り込み、! はノードIDで絞り込みます。
• live は Ctrl+C または q までパケットトラフィックをストリーミングします。live grep <text>、live rg <text>、live filter=<text>、または単に live <text> を使用して、一致するライブパケットグループのみをストリーミングします。レイヤーと詳細度フィルターは引き続き適用されます。例: live rg TEXT_MESSAGE_APP -vv --layer=2
• grep <text> および rg <text> は、保持されたパケット/チャット履歴をコンテキストウィンドウ、制限、パケット/チャットソースフィルター、概要/パケットスコープフィルターで検索します。
• /search <text> は、プロンプトから表示中のコンソール出力をフィルタリングします（保持履歴検索は開始しません）。

スクリーンショット

ライブネットワークマップ

ノードの位置、リンク、共通パス、クラスター、信号ヒートマップを含むマップビュー。

ネットワーク概要

ノード数、オンラインステータス、新しいノード、位置報告の履歴ビュー。

リンクトポロジ

選択したルートノードから観測されたリンクを示すトポロジビュー。

ルートトレース

送信元、宛先、近隣リンク、ホップごとのパケット詳細のトレースビュー。

センサー履歴

複数のノードにわたるセンサー履歴を比較するテレメトリーグラフ。

ステータスカード

無線アクティビティ、ノード数、パケット、リンク、バッテリー、チャンネル使用状況のトップカード。

テーマのカスタマイズ

テーマは、カスタムカラー、グラデーション、透明度、ぼかし、フォント、パーティクル、またはライブマップ背景でダッシュボード全体を変形できます。以下のパレットはカスタムテーマの例です。任意のプレビューを選択すると、フル解像度のスクリーンショットが表示されます。

シグナルグリーン	ネオンマゼンタ	オーロラリレー

共有ノード外観

Meshyface ノードは、ノードテーマレシピとオプションのゴーストまたはウォーターマークを含むコンパクトな外観パケットを共有できます。Settings > Appearance > Node Appearance でノードを設定およびプレビューし、Share node appearance を有効にしてから Broadcast appearance を使用して公開します。

• 外観パケットは、設定されたプロファイルの送信チャンネルを使用し、ラジオのホップ制限設定を継承します。Meshyface は別のホップ制限を課しません。
• 受信した外観は、受信側ダッシュボードのテーマを置き換えることなく、チャット、名簿、ノード詳細、マップ、グラフ、センサー、ティッカー内のノード識別情報をスタイル設定できます。
• Share node appearance をオフにすると、この機能の両側が無効になります。ブロードキャストが停止され、受信した外観ペイロードがデコード、キャッシュ、または永続化される前にプロファイル受信パスをバイパスします。キャッシュされた共有外観はクリアされ、受信した外観はレンダリングされません。
• 履歴が有効な場合、受信したプロファイルとローカルの共有設定は履歴 SQLite データベースに保持されます。
• 共有外観は装飾的なメタデータです。受信した外観がラジオ設定、チャンネル、またはダッシュボードの保存されたパッケージテーマを変更することはありません。

システムアーキテクチャ

flowchart LR
  Browser["ブラウザ<br/>シングルページUI"]
  CDN["ベンダーブラウザアセット<br/>Leaflet + leaflet.heat + particles.js"]
  Tiles["ベースマッププロバイダー<br/>OpenStreetMap タイルサービス"]
  Server["ThreadingHTTPServer<br/>HTMLシェル + JSON API"]
  Assets["Pythonテンプレートアセンブリ<br/>meshdash/html* + meshdash/assets/*"]
  State["ステートローダー<br/>ライブスナップショット + 履歴リーダー"]
  Services["書き込みサービス<br/>チャット、設定、ツール、ゲーム、オプションのファイル"]
  Tracker["DashboardTracker<br/>ライブ受信パス + インメモリバッファ"]
  History["HistoryStore / SQLite (WAL)<br/>チャット、パケット、ロールアップ、設定"]
  Radio["Meshtastic インターフェース<br/>シリアルまたはTCP"]
  Mesh["Meshtastic ラジオ / メッシュ"]
  Atlas["バンドルされたオフライン地図帳<br/>参照ベースマップフォールバック"]

  Browser -->|GET /| Server
  Browser -->|GET /api/*| Server
  Browser -->|POST 書き込みAPI| Server
  Browser --> CDN
  Browser --> Tiles
  Browser -->|フォールバックベースマップデータ| Atlas
  Server --> Assets
  Server --> State
  Server --> Services
  State <--> Tracker
  State <--> History
  Services <--> History
  Services <--> Radio
  Radio <--> Mesh
  Radio -->|受信コールバック| Tracker

インストール

前提条件と依存関係から始め、次にいずれかのインストールパスを選択します:

• 手動フォアグラウンド実行: どこかにクローンして、ダッシュボードを直接実行します。
• 推奨の systemd サービス: /opt/meshyface にクローンして、GitHub で更新可能な永続的なホストを設定します。
• Docker: コンテナ内で同じアプリエントリポイントを実行し、/data を永続状態用にマウントします。
• ワークステーションプッシュデプロイ: ローカルチェックアウトを SSH 経由でターゲットにコピーします。
• Proxmox ランタイムトポロジ: VM/LXC インストールのための TCP または USB ラジオ配置を選択します。
• オフラインマップパック: エアギャップまたは低接続のダッシュボード用に詳細なローカルマップデータを追加します。

データとストレージ

共有履歴データベース

--history-db は、ディスク上の最終的な SQLite ファイル名です。ダッシュボードは接続されたラジオのサフィックスを追加しなくなったため、ダッシュボードに接続された任意のラジオが同じ永続化されたパケット、チャット、ノード、ロールアップ履歴に貢献します。

履歴モード

• デフォルトモードは、チャット、パケット、接続イベント、ノード分析、不正形式テキストレコード、環境メトリクス、サマリロールアップを SQLite に永続化します。
• --no-history は永続ストアを無効にし、ライブのインメモリバッファのみを保持します。
• 履歴が有効な場合、サマリロールアップもダッシュボード実行中にバックグラウンドでサンプリングされます。

テーマとローカル設定

• テーマプリセットの選択は、デフォルトで mesh_dashboard_theme_settings.json に永続化されます。または --theme-settings-file で指定されたファイルに永続化されます。
• カスタムテレメトリールールは履歴 SQLite データベースに保存されます。

メンテナンスコマンド

ローカルダッシュボードデータを検査または修復する運用コマンドは、docs/maintenance.md に文書化されています。

リンクビューのセマンティクス

Links サブビューはトポロジビューであり、パケットルートの再生ではありません。

• History モードは、SQLite に保存されたリンク履歴から描画します。
• Live モードは、現在のセッションのリンク観測のみから描画します。
• 番号付きのリングは、観測されたリンクグラフ上での幅優先探索による、現在のルートからの最短グラフ距離を示します。
• それらのリング番号は、実際の Meshtastic 転送ホップではなく、リアルタイムのパケットトレースでもありません。
• パケットホップメタデータが利用可能な場合でも、ノードまたはエッジの詳細にパケットホップ値として個別に表示されます。

現在のルートは、グラフが中心となるノードです。別のノードを選択するとルートが変更され、そのノードからの番号付き距離リングが再計算されます。

設定リファレンス

接続とトランスポート

• --mesh-host <ip-or-dns>: TCP ラジオホスト
• --mesh-tcp-port <port>: TCP ラジオポート、デフォルト 4403
• --mesh-port <path>: シリアルデバイスパス
• --default-gateway-host <host>: --mesh-host が指定されておらず、シリアルが依然としてデフォルトパスにある場合のフォールバック TCP ホスト
• --default-gateway-port <port>: --default-gateway-host のフォールバック TCP ポート
• --no-default-gateway: --mesh-host が明示的に設定されない限り、シリアルを強制する

関連する環境変数:

• MESH_GATEWAY_HOST
• MESH_GATEWAY_PORT
• MESH_DASH_MESH_PORT (デフォルトシリアルパス用)

HTTP、UI、セキュリティ

• --http-host <host>: バインドホスト、デフォルト 0.0.0.0
• --http-port <port>: バインドポート、デフォルト 8877
• --refresh-ms <ms>: ブラウザポーリング間隔、デフォルト 3000
• --packet-limit <n>: 最近のライブパケットバッファサイズ、デフォルト 250
• --reset-ticker-scale-on-restart / --no-reset-ticker-scale-on-restart
• --show-secrets: raw JSON パネルで秘密鍵/パスワード/PSK を表示する
• --debug-mode / --no-debug-mode: 高度なネットワーク診断などのデバッグ専用ダッシュボード画面を公開する
• --private-mode / : 公開チャットスライスを削除し、選択された公開エンドポイントをブロックする

関連する環境変数:

• MESH_DASH_PRIVATE_MODE
• MESH_DASH_API_TOKEN
• MESH_DASH_GAMES_ENABLE
• MESH_DASH_VERSION
• MESH_DASH_GIT_COMMIT
• MESH_DASH_PR_NUMBER

ランタイム識別情報は、12文字のgitコミットと、それに続くオプションのプルリクエスト番号で構成されます（例: abc123456789 · PR #43）。Softwareパネルは、パッケージバージョンの代わりにこの単一のリビジョンを表示します。GitHubのマージ/スカッシュコミットの件名は自動的に検出されます。マージされていないプレビューデプロイメントでは、MESH_DASH_PR_NUMBER を明示的に設定できます。

/api/revision は正規の識別エンドポイントです。その revision フィールドと build_ref フィールドはランタイムリビジョンを報告し、commit と pr_number は構造化フィールドとして引き続き利用可能です。/api/version はレガシーエンドポイントとして残り、その version フィールドはリリース/パッケージメタデータを保持します。MESH_DASH_VERSION も同様に明示的なリリースパッケージング用に予約されており、ダッシュボードには表示されません。

ファイル転送

• --file-transfer-enable: ファイルアプリを有効にする。--accept-file-transfer-traffic-disclaimer が必要
• --file-transfer-auto-accept: ブラウザでの確認なしに受信ダイレクト転送を自動承認する
• --file-transfer-max-bytes <bytes>: ファイルあたりの制限、デフォルト 65536、範囲は 1024-524288

転送はベータ版の MF_FILE_V2 プロトコルをプライベートポート 258 で使用し、以前のテキストメッセージトランスポートとは互換性がありません。宛先に使用可能な検出ホップ数がある場合、Meshyface はその数に 1 を加えた値（設定されたラジオホップ制限で上限が決まる）を使用します。1 時間以上経過したホップデータは設定された制限にフォールバックします。Files アプリは選択された制限とそのソースを表示します。

関連する環境変数:

• MESH_DASH_FILE_TRANSFER_ENABLE
• MESH_DASH_FILE_TRANSFER_AUTO_ACCEPT
• MESH_DASH_FILE_TRANSFER_MAX_BYTES
• MESH_DASH_ACCEPT_FILE_TRANSFER_TRAFFIC_DISCLAIMER

履歴と分析

• --history-db <path>: ベースの SQLite DB パス
• --history-max-rows <n>: デフォルト 200000
• --history-retention-days <days>: デフォルト 30、0 を使用すると期間によるプルーニングを無効にする
• --history-event-max-rows <n>: 追記専用パケットイベントの上限、デフォルト 200000
• --history-event-retention-days <days>: デフォルト 30
• --history-rollup-retention-days <days>: デフォルト 365
• --no-history: メモリのみモード
• --seed-from-node-db: 接続されたラジオの NodeDB からライブトラッカーをブートストラップする

関連する環境変数:

• MESH_DASH_HISTORY_DB

テーマ

• --theme-presets <json>: オプションのカスタムテーマプリセットファイル
• --theme-preset <name>: 選択されたプリセット名
• --theme-settings-file <json>: 永続化されたランタイムテーマ選択ファイル

組み込みプリセット:

• default (安全な Meshyface ブルー、パーティクル無効)
• custom (パーティクルと背景効果が有効なショーケーステーマ)

新規インストールでは、永続化されたテーマ設定ファイルまたは MESH_DASH_THEME_PRESET が別のプリセットを選択しない限り、デフォルトで default になります。

関連する環境変数:

• MESH_DASH_THEME_PRESETS
• MESH_DASH_THEME_PRESET
• MESH_DASH_THEME_SETTINGS_FILE

セキュリティ

• このダッシュボードは、信頼された LAN/VPN 環境を想定しています。
• リバースプロキシとアクセス制御なしに、直接パブリックインターネットに公開しないでください。
• より厳格な書き込みパス制御には、--private-mode や API トークンを使用してください。
• 共有ホストやマルチユーザーホストでは、--api-token よりも MESH_DASH_API_TOKEN を優先してください。コマンドラインのトークンはプロセス一覧に表示され、シェル履歴に残る可能性があります。
• 組み込みの Join Meshyface チャンネルプリセットは、このソフトウェアのユーザー間の相互運用性のために、意図的に公開共有の Meshyface PSK を使用します。プライベートトラフィックにはその公開チャンネルを使用しないでください。
• --show-secrets は raw JSON パネルで機密値を公開します。共有ディスプレイで軽率に有効にしないでください。
• Raw パケットデータベースのダウンロードは、メッセージやテレメトリの内容を公開する可能性があります。共有ホストでは、API トークンを要求し、--no-allow-tokenless-raw-packet-download を使用してください。
• ファイル転送はメッシュのエアタイムを大量に消費する可能性があります。そのトレードオフを明示的に受け入れていない限り、無効にしておいてください。

テストとカバレッジ

通常のテストスイートを実行:

python -m pytest

Ruff を CI と同じ方法で実行:

scripts/run_ruff_local.sh

アドバイザリーアプリカバレッジレポートを実行:

python -m pytest \
  --cov=meshdash \
  --cov=mesh_dashboard \
  --cov=mesh_connection \
  --cov-report=term

より厳格な 85% 以上のローカルカバレッジゲートを実行:

scripts/run_coverage_local.sh

PR 前にローカル GUI 応答性ベンチマークを実行:

scripts/run_gui_responsiveness_local.sh

カバレッジは意図的に移植された Zork エンジンパッケージをスコアリングから除外しますが、スタンドアロンの Zork およびルーティングテストは引き続き実行されます。GitHub Actions は同じカバレッジレポートをアドバイザリー PR コメントおよびアーティファクトとして公開します。CI は 80% 未満で失敗します。ローカルゲートは CI より 5 パーセンテージポイント高いままです。