179 lines
7.2 KiB
Markdown
179 lines
7.2 KiB
Markdown
# Thor Watcher
|
|
|
|
**Version:** 0.3.0
|
|
|
|
Micromate (Series 4) watcher agent for Terra-View fleet management. Runs as a Windows system tray application, scans THORDATA for Micromate unit activity, sends heartbeat data to Terra-View, and (optionally) forwards `.IDFH`/`.IDFW` event files to a seismo-relay SFM server.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Thor Watcher monitors `C:\THORDATA\<Project>\<UM####>\*.MLG` files, determines each unit's last activity from the MLG filename timestamp, and periodically posts a heartbeat payload to the Terra-View backend. It runs silently in the system tray and auto-starts on login.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
1. Run `thor-watcher-setup.exe`
|
|
2. On first launch the setup wizard will appear — enter your THORDATA path and Terra-View URL
|
|
3. The app starts in the system tray and launches automatically on login
|
|
|
|
---
|
|
|
|
## Building from Source
|
|
|
|
Requires Python 3.10+ and pip on PATH.
|
|
|
|
```bat
|
|
build.bat
|
|
```
|
|
|
|
Produces:
|
|
- `dist\thor-watcher-0.3.0.exe` — upload to Gitea release
|
|
- `dist\thor-watcher.exe` — use with Inno Setup
|
|
|
|
Then run Inno Setup Compiler on `installer.iss` to produce `thor-watcher-setup.exe`.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Config is stored at:
|
|
```
|
|
%LOCALAPPDATA%\ThorWatcher\config.json
|
|
```
|
|
|
|
Managed through the Settings dialog (right-click tray icon → Settings). A `config.example.json` is included as reference.
|
|
|
|
### Config Keys
|
|
|
|
| Key | Type | Default | Description |
|
|
|-----|------|---------|-------------|
|
|
| `thordata_path` | string | `C:\THORDATA` | Root THORDATA directory |
|
|
| `scan_interval` | integer | `60` | Seconds between scans |
|
|
| `api_url` | string | `""` | Terra-View heartbeat URL (e.g. `http://10.0.0.40:8000/api/series4/heartbeat`) |
|
|
| `api_timeout` | integer | `5` | HTTP request timeout in seconds |
|
|
| `api_interval` | integer | `300` | Seconds between API heartbeat POSTs |
|
|
| `source_id` | string | hostname | Identifier for this machine in Terra-View |
|
|
| `source_type` | string | `series4_watcher` | Agent type (do not change) |
|
|
| `local_timezone` | string | `America/New_York` | Timezone of the field machine — used to convert MLG timestamps to UTC |
|
|
| `enable_logging` | boolean | `true` | Write log file |
|
|
| `log_file` | string | `%LOCALAPPDATA%\ThorWatcher\agent_logs\thor_watcher.log` | Log file path |
|
|
| `log_retention_days` | integer | `30` | Days before log is auto-cleared |
|
|
| `update_source` | string | `gitea` | Auto-update source: `gitea`, `url`, or `disabled` |
|
|
| `update_url` | string | `""` | Base URL for `url` mode (e.g. Terra-View server) |
|
|
| `sfm_forward_enabled` | boolean | `false` | Forward `.IDFH`/`.IDFW` event files to a seismo-relay SFM server |
|
|
| `sfm_url` | string | `""` | Base URL of the seismo-relay SFM server (e.g. `http://10.0.0.44:8200`) |
|
|
| `sfm_forward_interval` | integer | `60` | Seconds between forwarder passes |
|
|
| `sfm_quiescence_seconds` | integer | `5` | Skip files modified within the last N seconds (avoid in-flight files) |
|
|
| `sfm_missing_report_grace_seconds` | integer | `60` | Forward a binary without its `.txt` sidecar if it hasn't appeared after N seconds |
|
|
| `sfm_http_timeout` | integer | `60` | HTTP timeout per forward POST |
|
|
| `sfm_state_file` | string | `""` | Path to the sha256-keyed state file. Blank → `<log_dir>\thor_forwarded.json` |
|
|
| `sfm_max_forwards_per_pass` | integer | `500` | Cap per pass to drip-feed large backfills |
|
|
| `sfm_max_event_age_days` | integer | `365` | Skip event files older than this many days |
|
|
|
|
---
|
|
|
|
## Event Forwarding
|
|
|
|
When `sfm_forward_enabled` is true and `sfm_url` is set, Thor Watcher walks the THORDATA tree each `sfm_forward_interval` seconds, finds `.IDFH` (histogram) and `.IDFW` (waveform) event binaries plus their `TXT/<basename>.txt` ASCII sidecars, and POSTs them to seismo-relay's `/db/import/idf_file` endpoint.
|
|
|
|
- **Idempotent.** Every forwarded file is recorded by sha256 in `thor_forwarded.json`. Re-scans never re-POST.
|
|
- **Default off.** Operators must explicitly enable from the Settings → SFM Forward tab.
|
|
- **Re-pair logic.** If a binary is forwarded before its TXT sidecar appears (after the grace period), it's flagged `had_report=false` and re-forwarded once the TXT arrives so the SFM database row can be refreshed with device-authoritative PPV/ZCFreq/peak values.
|
|
- **TXT export must be enabled in Thor.** Thor's TXT sidecars are not produced automatically — operators should enable TXT export so the relay can extract rich metadata. Forwards without a TXT are still useful (binary gets indexed; rich fields stay NULL).
|
|
- **Backfill seeding.** To skip a large historical archive on first deploy, run `python event_forwarder.py --seed-state --thordata C:\THORDATA --state <state file>` before flipping the switch.
|
|
|
|
---
|
|
|
|
## Tray Icon Colors
|
|
|
|
| Color | Meaning |
|
|
|-------|---------|
|
|
| Green | Running, API reporting OK (and SFM forwarder healthy when enabled) |
|
|
| Amber | Running, API disabled OR SFM forwarder failing while API is healthy |
|
|
| Red | Running, API failing |
|
|
| Purple | Error — check logs |
|
|
| Grey | Starting up |
|
|
|
|
---
|
|
|
|
## Auto-Updater
|
|
|
|
Thor Watcher checks for updates every ~5 minutes. When a new release is found it downloads and validates the exe, then relaunches via a swap bat — no manual intervention needed.
|
|
|
|
**Update sources:**
|
|
- `gitea` — checks the Gitea release page (default)
|
|
- `url` — fetches `version.txt` and `thor-watcher.exe` from a custom server (e.g. Terra-View)
|
|
- `disabled` — no automatic checks; remote push from Terra-View still works
|
|
|
|
**Download validation:** 100 KB minimum size, 50% relative size floor vs current exe, MZ magic bytes check.
|
|
|
|
Remote update push from Terra-View Watcher Manager works regardless of `update_source` setting.
|
|
|
|
---
|
|
|
|
## Heartbeat Payload
|
|
|
|
Posted to `api_url` on each API interval:
|
|
|
|
```json
|
|
{
|
|
"source_id": "THOR-PC",
|
|
"source_type": "series4_watcher",
|
|
"version": "0.3.0",
|
|
"generated_at": "2026-03-20T14:30:00Z",
|
|
"log_tail": ["...last 25 log lines..."],
|
|
"units": [
|
|
{
|
|
"unit_id": "UM11719",
|
|
"last_call": "2026-03-20T13:18:00Z",
|
|
"age_minutes": 72,
|
|
"mlg_path": "C:\\THORDATA\\Project A\\UM11719\\UM11719_20260320131800.MLG",
|
|
"project_hint": "Project A"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## THORDATA Directory Structure
|
|
|
|
```
|
|
C:\THORDATA\
|
|
├── Project A\
|
|
│ ├── UM11719\
|
|
│ │ ├── UM11719_20260320131800.MLG
|
|
│ │ └── UM11719_20260319095430.MLG
|
|
│ └── UM12345\
|
|
│ └── UM12345_20260318091530.MLG
|
|
└── Project B\
|
|
└── UM98765\
|
|
└── UM98765_20260301082215.MLG
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
**Tray icon is amber:** API URL is not configured or disabled — open Settings and enter Terra-View URL.
|
|
|
|
**Tray icon is red:** API is failing — check Terra-View is reachable, URL is correct, and the network is up.
|
|
|
|
**Units showing wrong time in Terra-View:** Check `local_timezone` in Settings matches the field machine's timezone.
|
|
|
|
**No units found:** Verify `thordata_path` is correct and MLG files exist following the `UM####_YYYYMMDDHHMMSS.MLG` naming convention.
|
|
|
|
**Auto-updater not working:** Check the log file for `[updater]` lines. On first deploy, verify the Gitea release has a `thor-watcher-X.X.X.exe` asset (not a setup exe).
|
|
|
|
---
|
|
|
|
## Version History
|
|
|
|
See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
|
|
|
|
---
|
|
|
|
*Proprietary — Terra-Mechanics Inc. Internal use only.*
|