From d95973ab68f9e149673293299c02836d1c9b97a1 Mon Sep 17 00:00:00 2001
From: Tony Cao <tonycao@kanghexin.work>
Date: Wed, 12 Aug 2026 17:39:50 +0800
Subject: [PATCH] Soak sampler: add atomic nMatchLag freshness monitoring; add
 lag sampling script

---
 scripts/tc-ads-lag.ps1  | 23 +++++++++++++++++++++++
 scripts/tc-ads-soak.ps1 | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)
 create mode 100644 scripts/tc-ads-lag.ps1
 create mode 100644 scripts/tc-ads-soak.ps1

diff --git a/scripts/tc-ads-lag.ps1 b/scripts/tc-ads-lag.ps1
new file mode 100644
index 0000000..79266e0
--- /dev/null
+++ b/scripts/tc-ads-lag.ps1
@@ -0,0 +1,23 @@
+param([int]$Samples = 20, [int]$IntervalMs = 500)
+$ErrorActionPreference = 'Stop'
+$adsDll = 'C:\Program Files (x86)\Beckhoff\TwinCAT\3.1\Components\Base\v170\TwinCAT.Ads.dll'
+Add-Type -Path $adsDll
+$c = New-Object TwinCAT.Ads.TcAdsClient
+$c.Connect('169.254.176.217.1.1', 851)
+function ReadSym($name, $type) {
+    $h = $c.CreateVariableHandle($name)
+    $v = $c.ReadAny($h, $type)
+    $c.DeleteVariableHandle($h)
+    return $v
+}
+$lags = New-Object System.Collections.Generic.List[int]
+for ($k = 0; $k -lt $Samples; $k++) {
+    $lag = ReadSym 'GVL_Sync.nMatchLag' ([int])
+    $bs  = ReadSym 'GVL_Sync.bSync' ([bool])
+    $lags.Add($lag)
+    Write-Host ("{0}  lag={1,4} cyc  bSync={2}" -f (Get-Date -Format 'HH:mm:ss'), $lag, $bs)
+    if ($k -lt $Samples - 1) { Start-Sleep -Milliseconds $IntervalMs }
+}
+$s = $lags | Sort-Object
+Write-Host ("min={0} p50={1} max={2} mean={3:F2}" -f $s[0], $s[[int]($Samples/2)], $s[$Samples-1], (($lags | Measure-Object -Average).Average))
+$c.Dispose()
diff --git a/scripts/tc-ads-soak.ps1 b/scripts/tc-ads-soak.ps1
new file mode 100644
index 0000000..833577a
--- /dev/null
+++ b/scripts/tc-ads-soak.ps1
@@ -0,0 +1,32 @@
+param([int]$Minutes = 190, [string]$LogFile = "$env:TEMP\soak.log")
+$ErrorActionPreference = 'Stop'
+$adsDll = 'C:\Program Files (x86)\Beckhoff\TwinCAT\3.1\Components\Base\v170\TwinCAT.Ads.dll'
+Add-Type -Path $adsDll
+$c = New-Object TwinCAT.Ads.TcAdsClient
+$c.Connect('169.254.176.217.1.1', 851)
+function ReadSym($name, $type) {
+    $h = $c.CreateVariableHandle($name)
+    $v = $c.ReadAny($h, $type)
+    $c.DeleteVariableHandle($h)
+    return $v
+}
+$prevMism = $null
+$prevCyc = $null
+for ($k = 0; $k -lt $Minutes; $k++) {
+    try {
+        $nc  = ReadSym 'GVL_Sync.nCycles' ([uint64])
+        $bs  = ReadSym 'GVL_Sync.bSync' ([bool])
+        $nm  = ReadSym 'GVL_Sync.nMismatch' ([int])
+        $lag = ReadSym 'GVL_Sync.nMatchLag' ([int])
+        $dmism = if ($null -ne $prevMism) { $nm - $prevMism } else { 0 }
+        $rate = if ($null -ne $prevCyc) { ([int64]$nc - $prevCyc) / 60.0 } else { 0 }
+        $prevMism = $nm
+        $prevCyc = [int64]$nc
+        $line = "{0}  k={1,3}  nCycles={2,-9} rate={3,7:F1}/s  bSync={4}  lag={5,4}  nMismatch={6}  dMism={7}" -f (Get-Date -Format 'HH:mm:ss'), $k, $nc, $rate, $bs, $lag, $nm, $dmism
+    } catch {
+        $line = "{0}  k={1,3}  ADS ERROR: {2}" -f (Get-Date -Format 'HH:mm:ss'), $k, $_.Exception.Message
+    }
+    Add-Content -Path $LogFile -Value $line
+    Start-Sleep -Seconds 60
+}
+$c.Dispose()