# 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.

```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

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:

```json
{
  "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](CHANGELOG.md) for detailed version history.

---

*Proprietary — Terra-Mechanics Inc. Internal use only.*