doc: update readme v1.4

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  
+## Deployment (Recommended — Installer)
-- Age since last call-in  
-- OK / Pending / Missing states  
-- Detected units (no roster required)  
-- Optional API heartbeat to Seismograph Fleet Manager backend
 
-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)  
+- Windows 7 or later
-- Blastware 10 event folder available locally  
+- Python 3.8 (only needed if running from source — not needed with the installer)
-- `config.ini` in the same directory as the script  
+- Blastware 10 event folder accessible on the local machine
-
-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.
 
 ---
 
 ## Versioning
 
-This repo follows **Semantic Versioning (SemVer)**.
+Follows **Semantic Versioning**. Current release: **v1.4.0**.
-
+See `CHANGELOG.md` for full history.
-Current release: **v1.3.0** — renamed to series3-watcher.
-See `CHANGELOG.md` for details.
 
 ---
 
 ## License
 
-Private / internal project.
+Private / internal — Terra-Mechanics Inc.