How Calibration Guard Works

Calibration Guard runs as a background Windows process and continuously monitors one or more .ini files. This page explains the full lifecycle — from startup through file change detection to the allow/revert decision.

Startup sequence

When guard.exe starts (triggered by the Windows Scheduled Task on user logon):

1. Loads guard-config.json from the same directory (or the path passed via --config).
2. Reads the current license key from the Windows Registry (HKLM\SOFTWARE\ViciCalibGuard\LicenseKey).
3. Validates the key: checks format, decodes the validity window, compares to today's date.
4. For each path listed in watchPaths:
5. Checks that the file exists (logs a warning if missing, but continues).
6. Registers a file system watcher using Node's fs.watch.
7. Reads the current state of the protected sections and saves a backup (if the license is valid).
8. Starts an interval timer (default: every 5 minutes) as a secondary check in case the file watcher misses an event.

File change detection

The guard uses two detection mechanisms in parallel:

Primary: fs.watch (event-based) Node's fs.watch fires immediately when the OS reports a write to the watched file. This is low-latency but can miss events if the application writes the file in a way that bypasses normal write notifications (e.g., write-then-rename).

Secondary: interval polling (every checkIntervalMinutes minutes) Every N minutes the guard re-reads the protected sections and compares them against the backup. This catches any changes the watcher might have missed.

The allow/revert decision

Every time a change is detected (via either mechanism):

Change detected on C:\ViciVision\mtl.ini
  └─ Read current license from HKLM\SOFTWARE\ViciCalibGuard\LicenseKey
       ├─ License valid and not expired
       │    └─ Update backup with current protected section values
       │    └─ Log: INFO Backup updated (license valid until YYYYMMDD)
       └─ License expired or missing
            └─ Restore protected sections from backup JSON
            └─ Write patched file back to disk
            └─ Show Windows notification dialog
            └─ Log: REVERT + REASON

Backup is only updated when the license is valid

If a change is detected while the license is expired, the guard reverts immediately using the most recent backup from when the license was last valid. It does not update the backup from the expired state.

Protected sections

The sections listed in config.json under protectedSections are the only ones Calibration Guard monitors. All other sections in the .ini file are untouched — the guard only reads and writes the specific sections it is configured to protect.

Default protected sections:

Section	Contains
LOOKUP	Horizontal calibration lookup table (Step0–Step15)
LOOKUP_VERT	Vertical calibration lookup table (Step0–Step12, SEkneeDiameter)

Optional sections you can add to protectedSections:

Section	Contains
GAUGE	Temperature sensor calibration (ReferenceTemperatureNTC2/3)
TOOLS	Plane offset (PianoCalibrationUP-DOWN-SX-DX)
CALIBRATION	CoarseCalibration

Do not protect ViciVision's own backup sections

The .ini file contains [LOOKUP_BACKUP], [LOOKUP_VERT_BACKUP], and [GAUGE BACKUP] sections managed by ViciVision firmware. Do not add these to protectedSections — doing so will cause Calibration Guard to conflict with firmware writes.

Backup storage

Backups are stored as JSON files in C:\ProgramData\ViciCalibGuard\backups\. Each file is named using a 16-character prefix of the SHA-256 hash of the watched file path, so each .ini file has its own backup.

Example backup:

{
  "sourcePath": "C:\\ViciVision\\mtl.ini",
  "savedAt": "2026-03-05T14:00:01.000Z",
  "sections": {
    "LOOKUP": {
      "NumStep": "16",
      "Interpolation": "1",
      "Step0": "1885.647...,2224.132...,1.365..."
    },
    "LOOKUP_VERT": {
      "NumStep": "13",
      "SEkneeDiameter": "46.000",
      "Step0": "1902.441...,2241.823...,1.391..."
    }
  }
}

Corrupted backup?

If you suspect the backup was captured from a bad state, delete the JSON file from the backups directory. The guard will create a new one the next time the license is valid and a change is detected.

Windows notification dialog

When the guard reverts a change, it invokes PowerShell to display a Windows message box:

ViciCalibGuard — Calibration Locked

Calibration data has been restored to the authorized backup.
Reason: License expired (ValidTo: 20260228)

Contact ViciVision to request a new license key.

Log file

The log is written to C:\ProgramData\ViciCalibGuard\guard.log (configurable).

[2026-03-05 14:00:01] INFO    ViciCalibGuard started
[2026-03-05 14:00:01] INFO    Watching: C:\ViciVision\mtl.ini
[2026-03-05 14:00:01] INFO    Backup updated for C:\ViciVision\mtl.ini (license valid until 20260401)
[2026-03-05 15:30:22] INFO    Change detected: C:\ViciVision\mtl.ini
[2026-03-05 15:30:22] REVERT  C:\ViciVision\mtl.ini  Sections: LOOKUP, LOOKUP_VERT
[2026-03-05 15:30:22] REASON  License expired (ValidTo: 20260228)

Log levels:

Level	Meaning
INFO	Normal operation — startup, backup updates, change detections
REVERT	A revert was performed — includes file path and section names
REASON	Why the revert happened — license expired, missing, or invalid format
WARN	Non-fatal issue — watched file not found at startup
ERROR	Something failed — PowerShell dialog couldn't launch, registry read error

Expiry warning

If expiryWarningDays is set (default: 7), the guard shows a warning dialog N days before the license expiration date:

ViciCalibGuard — License Expiring Soon

Your calibration license expires in 5 days (20260401).
Contact ViciVision to renew before calibration changes are locked.

This warning is shown once per day while within the warning window.