Files

T

serversdown 815c643fb2 feat(forward): rate cap + seed-state mode for safe backfill (v1.5.2)

Two safety nets for first-deploy on Blastware ACH machines that
have accumulated tens or hundreds of thousands of historical events
in the watch folder.

1. SFM_MAX_FORWARDS_PER_PASS (default 500, 0=unlimited)
   ---------------------------------------------------
   Cap on the number of events forwarded per scan tick.  At the
   60-second default interval that's ~30K events/hour throughput —
   the SFM server gets a steady drip instead of one giant burst.
   Scan now sorts by mtime ascending so backfill advances
   chronologically (oldest first) and successive scans always
   make progress instead of re-considering the same N newest files.

   Wired into:
     - event_forwarder.find_pending_events / forward_pending
     - series3_watcher.run_watcher loop
     - config-template.ini
     - settings_dialog SFM Forward tab (new "Max Events Per Pass"
       spinbox, validated in _on_save)

2. event_forwarder.py --seed-state CLI
   -----------------------------------
   One-shot mode that walks the watch folder, sha256s every in-window
   event binary, and marks them all as already-forwarded WITHOUT
   POSTing anything.  Run before flipping SFM_FORWARD_ENABLED=true
   to skip the historical backfill entirely — the watcher then only
   forwards events that appear AFTER the seed.

   Usage:
       python event_forwarder.py --seed-state \
           --watch "C:\Blastware 10\Event\autocall home" \
           --state "C:\...\sfm_forwarded.json" \
           [--max-age-days 365]

7 new unit tests:
  - max_per_pass cap enforcement (=N, =0 unlimited, oldest-first
    ordering)
  - seed-state mode (in-window seeding, max-age skip,
    end-to-end skip-after-seed, idempotent re-runs)

README adds a "First-time deployment" section walking through both
options.  Bumps to v1.5.2.

2026-05-10 00:20:10 +00:00

7.5 KiB

Raw Blame History

Series 3 Watcher v1.5.2

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.

Download series3-watcher-setup.exe from the latest release on Gitea.
Run the installer on the target machine. It installs to C:\Program Files\Series3Watcher\ and adds a shortcut to the user's Startup folder.
On first launch the Setup Wizard opens automatically — fill in the terra-view URL and Blastware path, then click Save & Start.
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 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 & Releasing

See BUILDING.md for the full step-by-step process covering:

First-time build and installer creation
Publishing a release to Gitea
Releasing hotfix updates (auto-updater picks them up automatically)

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 base URL, e.g. `http://192.168.1.10:8000` — the `/api/series3/heartbeat` endpoint is appended automatically
`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`)
`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`)

Auto-Updater

Key	Description
`UPDATE_SOURCE`	`gitea` (default) or `url` — where to check for updates
`UPDATE_URL`	Base URL of the update server when `UPDATE_SOURCE = url` (e.g. terra-view URL). The watcher fetches `/api/updates/series3-watcher/version.txt` and `/api/updates/series3-watcher/series3-watcher.exe` from this base.

SFM Event Forwarder (v1.5.2+)

Forwards each Blastware event binary (and its paired <binary>.TXT ASCII report when present) to an SFM server's /db/import/blastware_file endpoint, where the report is parsed and the rich per-channel stats (PPV, ZC Freq, Time of Peak, Peak Acceleration / Displacement, sensor self-check) land in a searchable database. Default-off — existing deployments keep their old behaviour after auto-updating until the operator opts in.

Key	Description
`SFM_FORWARD_ENABLED`	`true` to enable forwarding (default `false`)
`SFM_URL`	Base URL of the SFM server, e.g. `http://10.0.0.44:8200`
`SFM_FORWARD_INTERVAL_SECONDS`	Scan-and-forward cadence (default `60`); independent of the heartbeat interval
`SFM_QUIESCENCE_SECONDS`	Skip files modified within this many seconds (default `5`) — avoids forwarding mid-write
`SFM_MISSING_REPORT_GRACE_SECONDS`	If a `.TXT` partner hasn't appeared after this many seconds, forward the binary alone (default `60`)
`SFM_HTTP_TIMEOUT`	Per-request HTTP timeout in seconds (default `60`)
`SFM_STATE_FILE`	Path to the JSON state file tracking sha256 of forwarded events. Leave blank to default to `<log dir>/sfm_forwarded.json`
`SFM_MAX_FORWARDS_PER_PASS`	Max events forwarded per scan tick (default `500`, `0` = unlimited). Drip-feeds backfill so a folder with thousands of qualifying events doesn't hammer the SFM server in one giant burst.

Forwarded files are tracked by sha256 in the state file, so re-scans / restarts / auto-updates never re-POST the same content. A failed POST stays in the pending pool and is retried on the next interval.

First-time deployment on a folder with a large historical archive

If you're enabling SFM forwarding on a Blastware ACH machine that's been accumulating events for years (tens or hundreds of thousands of files in the watch folder), you almost certainly don't want the watcher to forward all of them on first run. Two options:

Skip the historical backfill (recommended). Run the seed-state CLI once before flipping SFM_FORWARD_ENABLED=true. It walks the folder, sha256s every existing in-window event, and marks them all as already-forwarded — without POSTing anything. The watcher then only forwards events that appear after the seed run.
```
python event_forwarder.py --seed-state ^
    --watch "C:\Blastware 10\Event\autocall home" ^
    --state "C:\Users\<you>\AppData\Local\Series3Watcher\agent_logs\sfm_forwarded.json" ^
    --max-age-days 365
```
Throttle the backfill. Leave SFM_MAX_FORWARDS_PER_PASS at its 500 default and let the watcher drip-feed. With a 60-second SFM_FORWARD_INTERVAL_SECONDS that's ~30K events/hour throughput. Backfill of 30K events takes about an hour, 100K takes ~3.5 hours. The cap fires per scan, so heartbeat and forwarding share the watcher's main loop without saturating it.

Combine both for a fully controlled rollout: seed-state to skip the deep archive, then leave the cap on as a steady-state safety net.

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.5.2. See CHANGELOG.md for full history.

License

Private / internal — Terra-Mechanics Inc.

7.5 KiB Raw Blame History