thor-watcher/README.md

Thor Watcher

Version: 0.2.0

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

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.

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

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)

---

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:

{
  "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",
      "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 for detailed version history.

---

Proprietary — Terra-Mechanics Inc. Internal use only.