# Series 3 Watcher v1.4

Monitors Instantel **Series 3 (Minimate)** call-in activity on a Blastware server. Runs as a **system tray app** that starts automatically on login, reports heartbeats to terra-view, and self-updates from Gitea.

---

## Deployment (Recommended — Installer)

The easiest way to deploy to a field machine is the pre-built Windows installer.

1. Download `series3-watcher-setup.exe` from the [latest release](https://gitea.serversdown.net/serversdown/series3-watcher/releases) on Gitea.
2. Run the installer on the target machine. It installs to `C:\Program Files\Series3Watcher\` and adds a shortcut to the user's Startup folder.
3. On first launch the **Setup Wizard** opens automatically — fill in the terra-view URL and Blastware path, then click **Save & Start**.
4. A coloured dot appears in the system tray. Done.

The watcher will auto-start on every login from that point on.

### Auto-Updates

The watcher checks [Gitea](https://gitea.serversdown.net/serversdown/series3-watcher) for a newer release approximately every 5 minutes. When a newer `.exe` is found it downloads it silently, swaps the file, and relaunches — no user action required.

Updates can also be pushed remotely from terra-view → **Settings → Developer → Watcher Manager**.

---

## Building from Source

Prerequisites (on a **Python 3.8** machine — required for Win7 compatibility):

```
pip install pystray Pillow pyinstaller
```

Then run:

```
build.bat
```

This produces `dist\series3-watcher.exe`. To build the installer, open `installer.iss` in [Inno Setup](https://jrsoftware.org/isinfo.php) and click Build.

---

## Running Without the Installer (Dev / Debug)

```
pip install -r requirements.txt
python series3_tray.py        # tray app (recommended)
python series3_watcher.py     # console-only, no tray
```

`config.ini` must exist in the same directory. Copy `config-template.ini` to `config.ini` and edit it, or just run `series3_tray.py` — the wizard will create it on first run.

---

## Configuration

All settings live in `config.ini`. The Setup Wizard covers every field, but here's the reference:

### API / terra-view

| Key | Description |
|-----|-------------|
| `API_ENABLED` | `true` to send heartbeats to terra-view |
| `API_URL` | terra-view heartbeat endpoint, e.g. `http://192.168.1.10:8000/api/series3/heartbeat` |
| `API_INTERVAL_SECONDS` | How often to POST (default `300`) |
| `SOURCE_ID` | Identifier for this machine (defaults to hostname) |
| `SOURCE_TYPE` | Always `series3_watcher` |

### Paths

| Key | Description |
|-----|-------------|
| `SERIES3_PATH` | Blastware autocall folder, e.g. `C:\Blastware 10\Event\autocall home` |
| `MAX_EVENT_AGE_DAYS` | Ignore `.MLG` files older than this (default `365`) |
| `LOG_FILE` | Path to the log file |

### Scanning

| Key | Description |
|-----|-------------|
| `SCAN_INTERVAL_SECONDS` | How often to scan the folder (default `300`) |
| `OK_HOURS` | Age threshold for OK status (default `12`) |
| `MISSING_HOURS` | Age threshold for Missing status (default `24`) |
| `MLG_HEADER_BYTES` | Bytes to read from each `.MLG` header for unit ID (default `2048`) |
| `RECENT_WARN_DAYS` | Log unsniffable files newer than this window |

### Logging

| Key | Description |
|-----|-------------|
| `ENABLE_LOGGING` | `true` / `false` |
| `LOG_RETENTION_DAYS` | Auto-clear log after this many days (default `30`) |
| `COLORIZE` | ANSI colours in console — leave `false` on Win7 |

---

## Tray Icon

| Colour | Meaning |
|--------|---------|
| Grey | Starting / no scan yet |
| Green | All detected units OK |
| Yellow | At least one unit Pending |
| Red | At least one unit Missing, or error |

Right-click the icon for: status, per-unit list, Settings, Open Log Folder, Exit.

---

## terra-view Integration

When `API_ENABLED = true`, the watcher POSTs a telemetry payload to terra-view on each heartbeat interval. terra-view updates the emitter table and tracks the watcher process itself (version, last seen, log tail) in the Watcher Manager.

To view connected watchers: **Settings → Developer → Watcher Manager**.

---

## Requirements

- Windows 7 or later
- Python 3.8 (only needed if running from source — not needed with the installer)
- Blastware 10 event folder accessible on the local machine

---

## Versioning

Follows **Semantic Versioning**. Current release: **v1.4.0**.
See `CHANGELOG.md` for full history.

---

## License

Private / internal — Terra-Mechanics Inc.