2026-03-20 18:23:43 -04:00
2 changed files with 107 additions and 155 deletions
--- a/.gitignore
+++ b/.gitignore
--- a/README.md
+++ b/README.md
@@ -1,205 +1,157 @@
-# Series 4 Ingest Agent
+# Thor Watcher

-**Version:** 0.1.2
+**Version:** 0.2.0

-Micromate (Series 4) ingest agent for Seismo Fleet Manager (SFM).
+Micromate (Series 4) watcher agent for Terra-View fleet management. Runs as a Windows system tray application, scans THORDATA for Micromate unit activity, and sends heartbeat data to Terra-View.
+
+---

 ## Overview

-Series 4 Ingest Agent is a Python-based monitoring tool that scans for Micromate unit activity logs and reports their status. It monitors MLG (Micromate Log) files in the THORDATA directory structure, determines unit health based on last activity, and optionally transmits heartbeat data to a Seismo Fleet Manager backend.
+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.

-## Features
-
- **Automatic MLG File Discovery**: Scans `C:\THORDATA\<Project>\<UM####>\*.MLG` for Micromate units
- **Intelligent Unit Tracking**: Automatically identifies the newest MLG file per unit based on timestamp
- **Status Classification**: Categorizes units as OK, LATE, or STALE based on configurable age thresholds
- **Console Heartbeat Display**: Real-time status dashboard with formatted output
- **SFM Backend Integration**: Optional HTTP POST of JSON telemetry to Fleet Manager
- **External Configuration**: JSON-based configuration file for easy customization
- **Robust Error Handling**: Graceful degradation with informative warnings
- **No External Dependencies**: Uses Python standard library only (urllib, json, datetime, etc.)
-
-## Requirements
-
- Python 3.6 or higher
- Windows OS (designed for THOR PC/VM environments)
- Access to THORDATA directory structure
+---

 ## Installation

-1. Clone or copy this repository to your THOR PC/VM
-2. Ensure Python 3.6+ is installed
-3. Configure `config.json` (see Configuration section)
-4. Run the agent:
+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

-```bash
-python series4_ingest.py
+---
+
+## Building from Source
+
+Requires Python 3.10+ and pip on PATH.
+
+```bat
+build.bat
 ```

+Produces:
+- `dist\thor-watcher-0.2.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

-All configuration is managed through `config.json` in the same directory as the script.
+Config is stored at:
+```
+%LOCALAPPDATA%\ThorWatcher\config.json
+```

-### config.json Structure
+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) |
+
+---
+
+## Tray Icon Colors
+
+| Color | Meaning |
+|-------|---------|
+| Green | Running, API reporting OK |
+| Amber | Running, API disabled or not configured |
+| 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
 {
-  "thordata_path": "C:\\THORDATA",
-  "scan_interval": 60,
-  "late_days": 2,
-  "stale_days": 60,
-  "sfm_endpoint": "http://<sfm backend ip>:8001/api/series4/heartbeat"
-  "sfm_timeout": 5,
-  "debug": true
-}
-```
-
-### Configuration Options
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `thordata_path` | string | `C:\THORDATA` | Root directory containing project/unit MLG files |
-| `scan_interval` | integer | `60` | Time in seconds between scans |
-| `late_days` | integer | `2` | Days before a unit is marked as LATE |
-| `stale_days` | integer | `60` | Days before a unit is marked as STALE |
-| `sfm_endpoint` | string | `""` | SFM backend URL (leave empty to disable HTTP) |
-| `sfm_timeout` | integer | `5` | HTTP request timeout in seconds |
-| `debug` | boolean | `true` | Enable/disable debug logging |
-
-### Fallback Behavior
-
-If `config.json` is missing or malformed, the agent will:
- Display a warning message
- Use built-in default values
- Continue running normally
-
-## Usage
-
-### Start the Agent
-
-```bash
-python series4_ingest.py
-```
-
-### Console Output Example
-
-```
-Series 4 Ingest Agent — Micromate Heartbeat (v0.1.2)
-THORDATA root: C:\THORDATA
-Now: 2025-12-08 14:30:00
--------------------------------------------------------------------------------
-UM11719  OK     Age: 1h 12m  Last: 2025-12-08 13:18:00  Project: Clearwater - ECMS 57940
-UM12345  LATE   Age: 3d 5h   Last: 2025-12-05 09:15:30  Project: Site Alpha
-UM98765  STALE  Age: 65d     Last: 2025-10-04 08:22:15  Project: Legacy Site
--------------------------------------------------------------------------------
-Total units: 3
-Next scan in 60 seconds...
-```
-
-### Stop the Agent
-
-Press `Ctrl+C` to gracefully stop the agent.
-
-## Status Classification
-
-Units are classified based on the age of their last MLG file:
-
- **OK**: Last activity within `late_days` threshold (default: < 2 days)
- **LATE**: Last activity between `late_days` and `stale_days` (default: 2-60 days)
- **STALE**: Last activity exceeds `stale_days` threshold (default: ≥ 60 days)
-
-## SFM Backend Integration
-
-When `sfm_endpoint` is configured, the agent sends JSON payloads to the Seismo Fleet Manager:
-
-### Payload Structure
-
-```json
-{
-  "source": "series4_ingest",
-  "generated_at": "2025-12-08T14:30:00",
+  "source_id": "THOR-PC",
+  "source_type": "series4_watcher",
+  "version": "0.2.0",
+  "generated_at": "2026-03-20T14:30:00Z",
+  "log_tail": ["...last 25 log lines..."],
  "units": [
    {
      "unit_id": "UM11719",
-      "type": "micromate",
-      "project_hint": "Clearwater - ECMS 57940",
-      "last_call": "2025-12-08T13:18:00",
-      "status": "OK",
-      "age_days": 0.05,
-      "age_hours": 1.2,
-      "mlg_path": "C:\\THORDATA\\Clearwater - ECMS 57940\\UM11719\\UM11719_20251208131800.MLG"
+      "last_call": "2026-03-20T13:18:00Z",
+      "age_minutes": 72,
+      "mlg_path": "C:\\THORDATA\\Project A\\UM11719\\UM11719_20260320131800.MLG",
+      "project_hint": "Project A"
    }
  ]
 }
 ```

-### Disabling SFM Integration
+---

-Set `sfm_endpoint` to an empty string in `config.json`:
-
-```json
-{
-  "sfm_endpoint": ""
-}
-```
-
-## MLG File Format
-
-The agent expects MLG files to follow this naming convention:
-
-```
-UM<unit_number>_YYYYMMDDHHMMSS.MLG
-```
-
-Example: `UM11719_20251208131800.MLG`
-
- `UM11719`: Unit ID
- `20251208131800`: Timestamp (2025-12-08 13:18:00)
- `.MLG`: Micromate Log file extension
-
-## Directory Structure
-
-Expected THORDATA folder structure:
+## THORDATA Directory Structure

 ```
 C:\THORDATA\
 ├── Project A\
 │   ├── UM11719\
-│   │   ├── UM11719_20251208131800.MLG
-│   │   ├── UM11719_20251207095430.MLG
-│   │   └── ...
+│   │   ├── UM11719_20260320131800.MLG
+│   │   └── UM11719_20260319095430.MLG
 │   └── UM12345\
-│       └── UM12345_20251205091530.MLG
+│       └── UM12345_20260318091530.MLG
 └── Project B\
    └── UM98765\
-        └── UM98765_20251004082215.MLG
+        └── UM98765_20260301082215.MLG
 ```

+---
+
 ## Troubleshooting

-### Config file not found
-If you see `[WARN] Config file not found`, create `config.json` in the same directory as `series4_ingest.py`.
+**Tray icon is amber:** API URL is not configured or disabled — open Settings and enter Terra-View URL.

-### THORDATA path doesn't exist
-Verify the `thordata_path` in `config.json` points to the correct directory.
+**Tray icon is red:** API is failing — check Terra-View is reachable, URL is correct, and the network is up.

-### No units found
-Ensure MLG files exist in the expected directory structure and follow the naming convention.
+**Units showing wrong time in Terra-View:** Check `local_timezone` in Settings matches the field machine's timezone.

-### SFM POST failures
-Check that:
- `sfm_endpoint` URL is correct and accessible
- Network connectivity is available
- SFM backend is running and accepting requests
+**No units found:** Verify `thordata_path` is correct and MLG files exist following the `UM####_YYYYMMDDHHMMSS.MLG` naming convention.

-## License
+**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).

-Proprietary - Internal use only
+---

 ## Version History

 See [CHANGELOG.md](CHANGELOG.md) for detailed version history.

-## Support
+---

-For issues or questions, contact the Seismo development team.
+*Proprietary — Terra-Mechanics Inc. Internal use only.*