twFathom

AIでデータを深く理解する。CSV、MQTT、APIソースを、pywebviewを通じて知的に分析・可視化するTWSNMPシリーズプロジェクト。

twFathom は、ローカルファイル（CSV/JSON）、MQTT、および外部のHTTPS APIからデータを定期的に収集し、美しくインタラクティブなダッシュボード上で知的に分析・可視化するためのオープンソースのデスクトップアプリケーションです。

twFathom インフォグラフィック

🌟 主な特徴

最新OS対応: Apple Silicon (M1/M2/M3) Mac および Windows 11 に完全対応しています。
プライバシー重視: 収集したデータは一切クラウドには送信されず、あなたのPC内のローカルデータベース (SQLite) にのみ保存されます。
柔軟なデータソース: HTTPSポーリング、ローカルファイル監視（CSV/JSON）、MQTTサブスクリプションの3つのデータソースをサポート。
データ自動判別・パース: 入力されたデータ形式を判別し、環境データ、トラフィックデータ、またはシステムメトリクス（CPU/メモリ等）に自動マッピング。
インタラクティブな推移グラフ: スムーズでズーム可能な美しいグラフ表示により、時系列データの詳細な変化をキャッチ。
時系列異常検知 (Hotelling’s T^2): 各種メトリクスから自動で異常度を算出。通常とは異なる変化パターンを日本語の検知メッセージとステータスで表示。
リアルタイム警報＆通知 (CRITICAL ALERT): 熱中症警戒アラート (WBGT)、CO2換気アラート、ドア開閉や振動検知に対応。ダイナミックなフルスクリーン警告表示とBEEP音・自動消音タイマー機能を提供。
スマートなダッシュボード管理: 起動した複数ウィンドウを自動で格子状に整列（Auto-Arrange）。ウィンドウ位置・サイズ（枠なし状態含む）、グラフ設定を自動保存・復元。ダッシュボードからメイン画面を即座に最前面に呼び出す機能や、表示範囲外データの手動一括削除機能を搭載。
信頼の ‘tw’ シリーズ: ネットワーク管理ツール「TWSNMP」シリーズの開発者による、透明性の高いプロジェクトです。

📊 サポートする測定項目

アプリは自動的にデータソースを解析し、以下のいずれかのスキーマにデータをマッピングします：

🌡️ 環境 (Environment) データ

温度 (Temperature)
湿度 (Humidity)
気圧 (Pressure)
CO2 濃度 (CO2)
土壌水分 (Soil Moisture)
照度 (Illuminance)

🚪 窓開閉・コンタクト (Contact) センサーデータ

開閉状態 (Contact: 閉/開)
バッテリー残量 (Battery)
デバイス温度 (Device Temperature)
電波強度 / RSSI (Linkquality / RSSI)
電圧 (Voltage)
停電・トリガー回数 (Power Outage / Trigger Count)

🚶 人感・動体 (Occupancy / Motion) センサーデータ

人感・動体検知 (Occupancy / Motion: SwitchBot MotionSensor 等に対応)
照度 (Illuminance)
バッテリー残量 (Battery)
デバイス温度 (Device Temperature)
電波強度 / RSSI (Linkquality / RSSI)
電圧 (Voltage)

🌧️ 降雨・天候 (Rain) センサーデータ

降雨検知 (Rain)
降雨強度 (Rain Intensity)
照度 (Illuminance: 20分平均 / 本日最大含む)
清掃リマインダー (Cleaning Reminder)
バッテリー残量 / 電圧 / デバイス温度 / 電波強度

📳 振動・傾斜 (Vibration / Tilt) センサーデータ

振動・投函検知 (Vibration)
動作イベント (Action: vibration / tilt / drop)
振動強度 (Vibration Strength)
傾斜角度 (Angle / X, Y, Z Axis)
センサー感度 (Sensitivity)
バッテリー残量 / 電圧 / デバイス温度 / 電波強度

🔌 通信トラフィック (Traffic) データ

受信パケット数 (Rx PPS)
送信パケット数 (Tx PPS)
受信帯域幅 (Rx BPS)
送信帯域幅 (Tx BPS)

💻 システム (System) データ

CPU/メモリ/ディスク (CPU, Memory, Disk)
プロセス/ロード (Process, Load)
送受信速度 / バイト数 (Tx/Rx Speed, Sent/Recv Bytes)

📱 対応データソース仕様

1. HTTPS (API ポーリング)

指定したURLに対し、GETまたはPOSTリクエストを定期送信してJSONデータを取得します。

2. FILE (ローカルファイル監視)

ローカルのCSVやJSONファイルの更新（mtimeの変化）を自動的に検知し、最新データを読み込みます。

3. MQTT (リアルタイム受信)

MQTTブローカーに接続し、指定したトピックにパブリッシュされるデータをリアルタイムに受信します。

🚨 センサー警報機能 (Alert Management)

twFathom は、センサーデータが特定の閾値や異常状態に達した際に、直ちにユーザーへ通知するリアルタイム警報機能を搭載しています。

⚙️ 警報モード（警報種別）

熱中症警戒アラート (温湿度 WBGT):
- 気温と湿度から湿球黒球温度 (WBGT) を自動計算し、厳重警戒 (28.0°C以上) や危険 (31.0°C以上) などの閾値超過で発火。ヒステリシス制御により連続発火・誤検知を防止します。
環境温度アラート (温度単体):
- 湿度データのない温度センサーにおいて、設定した上限温度／下限温度の超過を判定します。
CO2 濃度警戒アラート:
- 室内の CO2 濃度が設定閾値 (デフォルト 1000 ppm) を超えた場合に換気リマインダー警報を発火します。
状態変化・イベント検知アラート (State Alert):
- ドア・窓の開閉 (Contact)、人感・動体検知 (Occupancy)、降雨検知 (Rain)、振動・傾き検知 (Vibration) などのバイナリ状態変化や急激なイベント発生を即時に捉えて警報を表示します。

🔔 警報の通知と運用機能

CRITICAL ALERT オーバーレイ画面: 警報発火時には画面全体に赤色の警告演出（パトランプ風グラフィック）と検出値・センサー名が表示されます。
BEEP音による音声通知: 視覚的な警告に加えて BEEP 音を再生し、画面から離れた場所にいても異常に気付くことができます。
放置時の自動消音機能: 夜間や不在時の鳴りっぱなしを防止するため、一定時間 (10秒 / 30秒 / 60秒など) 経過後に自動で消音・復元する安全機能を搭載しています。
テスト警報実行: 設定ダイアログ内の「テスト警報実行」ボタンから、実際の警報画面および音声通知の確認・動作テストが可能です。
警報確認 (DISMISS): 警報表示画面の「警報確認 (DISMISS)」を押すと、直ちに警報を解除して通常の監視画面に戻ります。

📦 インストール方法

macOS

最新のリリースから .pkg インストーラーをダウンロードして実行してください。 注意: アプリは Apple による公証(Notarized)を受けており、安全に実行できます。

Windows

最新のリリースから .msi インストーラーをダウンロードして実行してください。

Linux (AppImage)

最新のリリースから .AppImage パッケージをダウンロードして実行してください。

推奨環境: Ubuntu 22.04 / 24.04 などの主要な Linux ディストリビューション (GNOME / KDE などのデスクトップ環境推奨)
起動方法:
1. ダウンロードした .AppImage ファイルに実行権限を付与します：
```
chmod +x twFathom-Linux.AppImage
```
2. ファイルをダブルクリックするか、ターミナルから以下のように実行します：
```
./twFathom-Linux.AppImage
```
  注意: ポータブル形式（AppImage）のため、システムへのインストール作業なしにそのまま実行可能です。

🚀 使い方

データソースの追加: アプリを起動し、「ソース追加」から新しいデータソースを登録します。ソースの種別（HTTPS / FILE / MQTT）を選択し、URL、ファイルパス、ブローカー情報を入力します。
データの収集開始: 登録したソースを「有効 (Active)」に設定すると、バックグラウンドコレクターがデータの収集を定期的に開始します。
ダッシュボードでの可視化: ソースリストからダッシュボードを開くと、個別の分析ウィンドウ（初期サイズ 640x480）が開きます。複数のダッシュボードウィンドウがある場合、「自動整列 (Auto-Arrange)」機能で格子状に綺麗に配置できます。ウィンドウの位置、サイズ（枠なし状態含む）、表示期間、グラフ設定は次回起動時もそのまま復元されます。ヘッダーの「メインコンソール表示」ボタンで裏に隠れた管理画面を最前面に呼び出すことができ、グラフでズーム・選択した表示範囲外の古いデータは「表示範囲外データ削除」ボタンで手動で一括削除・整理できます。
警報（アラート）の設定: ダッシュボードのヘッダーにある警報設定アイコン（🚨）をクリックすると、「センサー警報設定」ダイアログが開きます。熱中症警戒アラート (WBGT)、環境温度上下限、CO2濃度、状態変化検知などのモードを選択し、発火閾値や BEEP 音の有無、放置時の自動消音時間を設定して保存します。「テスト警報実行」で動作確認を行うことも可能です。

💾 データの保存場所

すべてのデータは、お使いの PC 内のローカル SQLite データベースに保存されます。

保存先ディレクトリ: ~/.twfathom/twfathom.db (ホームディレクトリ下の .twfathom フォルダ内)
- macOS: /Users/ユーザー名/.twfathom/twfathom.db
- Windows: C:\Users\ユーザー名\.twfathom\twfathom.db
- Linux: /home/ユーザー名/.twfathom/twfathom.db

📸 デモ & スクリーンショット

アプリケーション画面

ダッシュボード & 分析

| 環境モニター画面 | トラフィックモニター画面 | | :—: | :—: | | | |

🚨 センサー警報 & アラート表示

| センサー警報設定 | CRITICAL ALERT 画面 | | :—: | :—: | | | |

🛠 開発者向け

このプロジェクトは、TWSNMP の開発者によって維持されている ‘tw’シリーズの一部です。

開発環境のセットアップ

mise が必要です：

# 必要なバージョンのPython等のインストール
mise install
# 仮想環境の構築と依存パッケージのインストール
mise run setup

開発・ビルドコマンド

開発実行: mise run dev (briefcase 開発モードでアプリ起動)
テスト実行: mise run test
ビルド（ローカル確認用）: mise run build

リリース・パッケージング

macOS (署名・公証付き): 環境変数 DEVELOPER_ID_APPLICATION および DEVELOPER_ID_INSTALLER に開発者IDを設定した状態で実行します。
```
mise run release-mac
```
Windows: リポジトリの main ブランチにプッシュされると、GitHub Actions が自動的にビルドを開始し、.msi インストーラーを生成します。
Linux: リポジトリの main ブランチにプッシュされると、GitHub Actions が自動的にビルドを開始し、ポータブルな .AppImage パッケージを生成します。

📄 ライセンス

Apache License 2.0 の下で公開されています。詳細は LICENSE を参照してください。