diff --git a/README.md b/README.md index d92c78e..c140a90 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,136 @@ -# Series 3 Watcher v1.3 +# Series 3 Watcher v1.4 -A lightweight Python script that monitors Instantel **Series 3 (Minimate)** call-in activity on a Blastware server. +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. -It scans the event folder, reads `.MLG` headers to identify unit IDs, and prints a live status table showing: +--- -- Last event received -- Age since last call-in -- OK / Pending / Missing states -- Detected units (no roster required) -- Optional API heartbeat to Seismograph Fleet Manager backend +## Deployment (Recommended — Installer) -This script is part of the larger **Seismograph Fleet Manager** project. +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 -- Python 3.8 (Windows 7 compatible) -- Blastware 10 event folder available locally -- `config.ini` in the same directory as the script - -Install dependencies with: - -`pip install -r requirements.txt` - ---- - -## Usage - -Run the agent from the folder containing the script: - -`python series3_watcher.py` - -The script will: - -1. Scan the Blastware event folder for `.MLG` files (within a max age window). -2. Sniff each file header for the unit ID. -3. Print a status line for each detected unit (OK / Pending / Missing). -4. Optionally POST a heartbeat payload on an interval when `API_ENABLED=true`. -5. Write logs into the `agent_logs/` folder and auto-clean old logs. - ---- - -## Config - -All settings are stored in `config.ini`. - -Key fields: - -- `SERIES3_PATH` — folder containing `.MLG` files -- `SCAN_INTERVAL_SECONDS` — how often to scan -- `OK_HOURS` / `MISSING_HOURS` — thresholds for status -- `MLG_HEADER_BYTES` — how many bytes to sniff from each `.MLG` header -- `RECENT_WARN_DAYS` — log unsniffable files newer than this window -- `MAX_EVENT_AGE_DAYS` — ignore events older than this many days -- `API_ENABLED` — enable/disable heartbeat POST -- `API_URL` — heartbeat endpoint -- `API_INTERVAL_SECONDS` — heartbeat frequency -- `SOURCE_ID` / `SOURCE_TYPE` — identifiers included in the API payload -- `LOG_RETENTION_DAYS` — auto-delete logs older than this many days -- `COLORIZE` — ANSI color output (off by default for Win7) - ---- - -## Logs - -Logs are stored under `agent_logs/`. -Git ignores all log files but keeps the folder itself. +- 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 -This repo follows **Semantic Versioning (SemVer)**. - -Current release: **v1.3.0** — renamed to series3-watcher. -See `CHANGELOG.md` for details. +Follows **Semantic Versioning**. Current release: **v1.4.0**. +See `CHANGELOG.md` for full history. --- ## License -Private / internal project. +Private / internal — Terra-Mechanics Inc.