Merge pull request #477 from GridProtectionAlliance/sel-cws-updates

ritchiecarroll · web-flow · commit 63387dfed3da · 2026-01-02T01:39:12.000-06:00
Updates to SEL CWS rolling phase estimator
diff --git a/Source/Libraries/GSF.PhasorProtocols/GSF.PhasorProtocols.csproj b/Source/Libraries/GSF.PhasorProtocols/GSF.PhasorProtocols.csproj
@@ -60,6 +60,10 @@
     <Reference Include="System.Data.DataSetExtensions" />
     <Reference Include="System.Design" />
     <Reference Include="System.Drawing" />
+    <Reference Include="System.Memory, Version=4.0.2.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51, processorArchitecture=MSIL">
+      <SpecificVersion>False</SpecificVersion>
+      <HintPath>..\..\Dependencies\NuGet\System.Memory.4.5.5\lib\net461\System.Memory.dll</HintPath>
+    </Reference>
     <Reference Include="System.Runtime.Serialization" />
     <Reference Include="System.Runtime.Serialization.Formatters.Soap" />
     <Reference Include="System.Windows.Forms" />
@@ -157,6 +161,7 @@
     <Compile Include="IHeaderFrameParsingState.cs" />
     <Compile Include="IPhasorDefinition.cs" />
     <Compile Include="IPhasorValue.cs" />
+    <Compile Include="IsExternalInit.cs" />
     <Compile Include="MultiProtocolFrameParser.cs" />
     <Compile Include="NamespaceDoc.cs" />
     <Compile Include="PhasorDefinitionBase.cs" />
@@ -291,6 +296,8 @@
     <Compile Include="Macrodyne\FrequencyValue.cs" />
     <Compile Include="Macrodyne\PhasorDefinition.cs" />
     <Compile Include="Macrodyne\PhasorValue.cs" />
+    <Compile Include="ReplayTimer.cs" />
+    <Compile Include="RequiredMemberAttribute.cs" />
     <Compile Include="SelCWS\AnalogDefinition.cs" />
     <Compile Include="SelCWS\AnalogValue.cs" />
     <Compile Include="SelCWS\Common.cs" />
diff --git a/Source/Libraries/GSF.PhasorProtocols/IsExternalInit.cs b/Source/Libraries/GSF.PhasorProtocols/IsExternalInit.cs
@@ -0,0 +1,6 @@
+﻿// ReSharper disable once CheckNamespace
+namespace System.Runtime.CompilerServices;
+
+// Class defined in .NET 5.0 and later, but not in .NET Framework or Standard 2.x.
+// Declared manually here to allow 'init' property operations.
+internal static class IsExternalInit { }
diff --git a/Source/Libraries/GSF.PhasorProtocols/MultiProtocolFrameParser.cs b/Source/Libraries/GSF.PhasorProtocols/MultiProtocolFrameParser.cs
@@ -83,6 +83,7 @@
 using GSF.Parsing;
 using GSF.PhasorProtocols.IEEEC37_118;
 using GSF.PhasorProtocols.Macrodyne;
+using GSF.PhasorProtocols.SelCWS;
 using GSF.PhasorProtocols.SelFastMessage;
 using GSF.Threading;
 using GSF.TimeSeries;
@@ -1460,14 +1461,14 @@ private void SharedClient_SendDataException(object sender, EventArgs<Exception>
         private IClient m_commandChannel;
         private IPAddress m_receiveFromAddress;
         private IPAddress m_multicastServerAddress;
+        private ReplayTimer m_replayTimer;
         private PrecisionInputTimer m_inputTimer;
         private ShortSynchronizedOperation m_readNextBuffer;
         private SharedTimer m_rateCalcTimer;
         private IConfigurationFrame m_configurationFrame;
         private CheckSumValidationFrameTypes m_checkSumValidationFrameTypes;
         private long m_dataStreamStartTime;
         private long m_missingFramesOverflow;
-        private long m_lastFrameReceivedTime;
         private int m_frameRateTotal;
         private int m_byteRateTotal;
         private int m_parsingExceptionCount;
@@ -2553,11 +2554,41 @@ private void InitializeFrameParser(Dictionary<string, string> settings)
                         if (settings.TryGetValue("calculatePhaseEstimates", out setting))
                             selCWSParameters.CalculatePhaseEstimates = setting.ParseBoolean();
 
-                        if (settings.TryGetValue("frameRate", out setting) && ushort.TryParse(setting, out ushort frameRate))
-                            selCWSParameters.FrameRate = frameRate;
-
                         if (settings.TryGetValue("nominalFrequency", out setting) && Enum.TryParse(setting, true, out LineFrequency nominalFrequency))
                             selCWSParameters.NominalFrequency = nominalFrequency;
+
+                        if (settings.TryGetValue("calculationFrameRate", out setting) && ushort.TryParse(setting, out ushort calculationFrameRate))
+                            selCWSParameters.CalculationFrameRate = calculationFrameRate;
+
+                        if (settings.TryGetValue("repeatLastCalculatedValueWhenDownSampling", out setting))
+                            selCWSParameters.RepeatLastCalculatedValueWhenDownSampling = setting.ParseBoolean();
+
+                        if (settings.TryGetValue("referenceChannel", out setting) && Enum.TryParse(setting, true, out PhaseChannel referenceChannel))
+                            selCWSParameters.ReferenceChannel = referenceChannel;
+
+                        if (settings.TryGetValue("targetCycles", out setting) && int.TryParse(setting, out int targetCycles))
+                            selCWSParameters.TargetCycles = targetCycles;
+
+                        if (settings.TryGetValue("publishAnglesTauSeconds", out setting) && double.TryParse(setting, out double publishAnglesTauSeconds))
+                            selCWSParameters.PublishAnglesTauSeconds = publishAnglesTauSeconds;
+
+                        if (settings.TryGetValue("publishMagnitudesTauSeconds", out setting) && double.TryParse(setting, out double publishMagnitudesTauSeconds))
+                            selCWSParameters.PublishMagnitudesTauSeconds = publishMagnitudesTauSeconds;
+
+                        if (settings.TryGetValue("publishFrequencyTauSeconds", out setting) && double.TryParse(setting, out double publishFrequencyTauSeconds))
+                            selCWSParameters.PublishFrequencyTauSeconds = publishFrequencyTauSeconds;
+
+                        if (settings.TryGetValue("publishRocofTauSeconds", out setting) && double.TryParse(setting, out double publishRocofTauSeconds))
+                            selCWSParameters.PublishRocofTauSeconds = publishRocofTauSeconds;
+
+                        if (settings.TryGetValue("sampleFrequencyTauSeconds", out setting) && double.TryParse(setting, out double sampleFrequencyTauSeconds))
+                            selCWSParameters.SampleFrequencyTauSeconds = sampleFrequencyTauSeconds;
+
+                        if (settings.TryGetValue("sampleRocofTauSeconds", out setting) && double.TryParse(setting, out double sampleRocofTauSeconds))
+                            selCWSParameters.SampleRocofTauSeconds = sampleRocofTauSeconds;
+
+                        if (settings.TryGetValue("recalculationCycles", out setting) && int.TryParse(setting, out int recalculationCycles))
+                            selCWSParameters.RecalculationCycles = recalculationCycles;
                     }
                     break;
                 default:
@@ -3574,19 +3605,12 @@ private long MaintainCapturedFrameReplayTiming()
         {
             if (m_inputTimer is null)
             {
-                if (m_lastFrameReceivedTime > 0L)
-                {
-                    // To maintain timing on "frames per second", we wait for defined frame rate interval
-                    double sleepTime = 1.0D / m_definedFrameRate - (DateTime.UtcNow.Ticks - m_lastFrameReceivedTime) / (double)Ticks.PerSecond;
-
-                    // Thread sleep time is a minimum suggested sleep time depending on system activity, when not using high-resolution
-                    // input timer we assume getting close is good enough
-                    if (sleepTime > 0.0D)
-                        Thread.Sleep((int)(sleepTime * 1000.0D));
-                }
+                if (m_replayTimer?.DefinedFrameRate != m_definedFrameRate)
+                    m_replayTimer = new ReplayTimer(m_definedFrameRate);
 
-                m_lastFrameReceivedTime = DateTime.UtcNow.Ticks;
-                return Ticks.AlignToMillisecondDistribution(m_lastFrameReceivedTime, m_definedFrameRate).Value;
+                m_replayTimer.WaitNext();
+                
+                return Ticks.AlignToMillisecondDistribution(DateTime.UtcNow.Ticks, m_definedFrameRate).Value;
             }
 
             // When high resolution input timing is requested, we only need to wait for the next signal...
@@ -3608,7 +3632,7 @@ private void m_frameParser_ReceivedChannelFrame(object sender, EventArgs<IChanne
                     frame.Timestamp = Ticks.AlignToMillisecondDistribution(DateTime.UtcNow.Ticks, m_definedFrameRate);
 
                 // Keep reading file data
-                if (m_transportProtocol == TransportProtocol.File && QueuedOutputs < 2 && QueuedBuffers < 10)
+                if (m_transportProtocol == TransportProtocol.File && (QueuedOutputs < 2 || QueuedBuffers < 10))
                     m_readNextBuffer?.RunOnceAsync();
 
                 if (ReceivedChannelFrame is not null && e.Argument2)
diff --git a/Source/Libraries/GSF.PhasorProtocols/ReplayTimer.cs b/Source/Libraries/GSF.PhasorProtocols/ReplayTimer.cs
@@ -0,0 +1,102 @@
+﻿//******************************************************************************************************
+//  ReplayTimer.cs - Gbtc
+//
+//  Copyright © 2025, Grid Protection Alliance.  All Rights Reserved.
+//
+//  Licensed to the Grid Protection Alliance (GPA) under one or more contributor license agreements. See
+//  the NOTICE file distributed with this work for additional information regarding copyright ownership.
+//  The GPA licenses this file to you under the MIT License (MIT), the "License"; you may not use this
+//  file except in compliance with the License. You may obtain a copy of the License at:
+//
+//      http://opensource.org/licenses/MIT
+//
+//  Unless agreed to in writing, the subject software distributed under the License is distributed on an
+//  "AS-IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. Refer to the
+//  License for the specific language governing permissions and limitations.
+//
+//  Code Modification History:
+//  ----------------------------------------------------------------------------------------------------
+//  12/29/2025 - J. Ritchie Carroll
+//       Generated original version of source code.
+//
+//******************************************************************************************************
+
+using System;
+using System.Diagnostics;
+using System.Threading;
+
+namespace GSF.PhasorProtocols;
+
+/// <summary>
+/// Replay timer class used to pace frame publication for file-based playback.
+/// </summary>
+/// <remarks>
+/// This class uses a combination of coarse sleeping, yielding, and spinning for
+/// accurate wait times with minimal CPU usage. Supports common frame rates, e.g.,
+/// 30 or 60, and very high frame rates, e.g., 3000.
+/// </remarks>
+public sealed class ReplayTimer
+{
+    private readonly long m_periodTicks;    // Query Performance Counter (QPC) ticks per frame
+    private long m_nextTick;                // Next scheduled QPC tick (not equal to DateTime ticks)
+
+    /// <summary>
+    /// Creates a new <see cref="ReplayTimer"/> instance.
+    /// </summary>
+    /// <param name="definedFrameRate">The defined frame rate in frames per second.</param>
+    public ReplayTimer(int definedFrameRate)
+    {
+        if (definedFrameRate <= 0)
+            throw new ArgumentOutOfRangeException(nameof(definedFrameRate));
+
+        m_periodTicks = (long)Math.Round(Stopwatch.Frequency / (double)definedFrameRate);
+        m_nextTick = Stopwatch.GetTimestamp();
+
+        DefinedFrameRate = definedFrameRate;
+    }
+
+    /// <summary>
+    /// Gets the defined frame rate for this timer.
+    /// </summary>
+    public int DefinedFrameRate { get; }
+
+    /// <summary>
+    /// Blocks until the next scheduled frame rate interval.
+    /// </summary>
+    public void WaitNext()
+    {
+        m_nextTick += m_periodTicks;
+
+        while (true)
+        {
+            long now = Stopwatch.GetTimestamp();
+            long ticksRemaining = m_nextTick - now;
+
+            if (ticksRemaining <= 0L)
+                return;
+
+            // Convert to milliseconds for coarse decisions
+            double remaining = ticksRemaining * 1000.0 / Stopwatch.Frequency;
+
+            switch (remaining)
+            {
+                case >= 2.0D:
+                    // Coarse sleep -- 1ms is the finest useful Sleep on Windows
+                    Thread.Sleep(1);
+                    break;
+                case >= 0.3D:
+                    // Yield to reduce CPU but avoid oversleeping
+                    Thread.Yield();
+                    break;
+                default:
+                    // Just spin to hit sub-millisecond cadence
+                    SpinWait sw = new();
+                        
+                    while (Stopwatch.GetTimestamp() < m_nextTick)
+                        sw.SpinOnce();
+                        
+                    return;
+            }
+        }
+    }
+}
diff --git a/Source/Libraries/GSF.PhasorProtocols/RequiredMemberAttribute.cs b/Source/Libraries/GSF.PhasorProtocols/RequiredMemberAttribute.cs
@@ -0,0 +1,52 @@
+﻿#pragma warning disable
+
+using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
+
+namespace System.Runtime.CompilerServices
+{
+#if !NET7_0_OR_GREATER
+
+#if (NET40_OR_GREATER || NETSTANDARD2_0_OR_GREATER || NETCOREAPP2_0_OR_GREATER || NET5_0_OR_GREATER)
+    [ExcludeFromCodeCoverage]
+#endif
+    [DebuggerNonUserCode]
+    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Field | AttributeTargets.Property, AllowMultiple = false, Inherited = false)]
+    internal sealed class RequiredMemberAttribute : Attribute { }
+
+#if (NET40_OR_GREATER || NETSTANDARD2_0_OR_GREATER || NETCOREAPP2_0_OR_GREATER || NET5_0_OR_GREATER)
+    [ExcludeFromCodeCoverage]
+#endif
+    [DebuggerNonUserCode]
+    [AttributeUsage(AttributeTargets.All, AllowMultiple = true, Inherited = false)]
+    internal sealed class CompilerFeatureRequiredAttribute : Attribute
+    {
+        public CompilerFeatureRequiredAttribute(string featureName)
+        {
+            FeatureName = featureName;
+        }
+
+        public string FeatureName { get; }
+
+        public bool IsOptional { get; set; } // Originally, this was 'Init', but that does not seem necessary and may collide with the IsExternalInit package
+
+        public const string RefStructs = nameof(RefStructs);
+        public const string RequiredMembers = nameof(RequiredMembers);
+    }
+
+#endif // !NET7_0_OR_GREATER
+}
+
+namespace System.Diagnostics.CodeAnalysis
+{
+#if !NET7_0_OR_GREATER
+#if (NET40_OR_GREATER || NETSTANDARD2_0_OR_GREATER || NETCOREAPP2_0_OR_GREATER || NET5_0_OR_GREATER)
+    [ExcludeFromCodeCoverage]
+#endif
+    [DebuggerNonUserCode]
+    [AttributeUsage(AttributeTargets.Constructor, AllowMultiple = false, Inherited = false)]
+    internal sealed class SetsRequiredMembersAttribute : Attribute { }
+#endif
+}
+
+#pragma warning restore
diff --git a/Source/Libraries/GSF.PhasorProtocols/SelCWS/Common.cs b/Source/Libraries/GSF.PhasorProtocols/SelCWS/Common.cs
@@ -24,6 +24,7 @@
 //       Modified Header.
 //
 //******************************************************************************************************
+// ReSharper disable InconsistentNaming
 
 using System;
 using GSF.Units.EE;
@@ -48,6 +49,37 @@ public enum FrameType : byte
     ConfigurationFrame = 0x01
 }
 
+/// <summary>
+/// Phase channels for SEL CWS PoW analogs.
+/// </summary>
+public enum PhaseChannel
+{ 
+    /// <summary>
+    /// Phase A current (IA).
+    /// </summary>
+    IA = 0,
+    /// <summary>
+    /// Phase B current (IB).
+    /// </summary>
+    IB = 1,
+    /// <summary>
+    /// Phase C current (IC).
+    /// </summary>
+    IC = 2,
+    /// <summary>
+    /// Phase A voltage (VA).
+    /// </summary>
+    VA = 3,
+    /// <summary>
+    /// Phase B voltage (VB).
+    /// </summary>
+    VB = 4,
+    /// <summary>
+    /// Phase C voltage (VC).
+    /// </summary>
+    VC = 5
+}
+
 #endregion
 
 /// <summary>
diff --git a/Source/Libraries/GSF.PhasorProtocols/SelCWS/CommonFrameHeader.cs b/Source/Libraries/GSF.PhasorProtocols/SelCWS/CommonFrameHeader.cs
@@ -37,7 +37,8 @@ namespace GSF.PhasorProtocols.SelCWS;
 /// <summary>
 /// Represents the common header for a SEL CWS frame of data.
 /// </summary>
-public class CommonFrameHeader : CommonHeaderBase<FrameType>
+[Serializable]
+public class CommonFrameHeader : CommonHeaderBase<FrameType>, ISerializable
 {
     #region [ Members ]
 
@@ -173,7 +174,7 @@ public FundamentalFrameType FundamentalFrameType
     /// <param name="attributes">Dictionary to append header specific attributes to.</param>
     internal void AppendHeaderAttributes(Dictionary<string, string> attributes)
     {
-        attributes.Add("Frame Type", $"{(ushort)m_frameType}: {m_frameType}");
+        attributes.Add("Frame Type", $"{(byte)m_frameType}: {m_frameType}");
         attributes.Add("Frame Length", FrameLength.ToString());
         attributes.Add("Version", $"0x{Common.Version:X2}");
         attributes.Add("Channel ID", ChannelID.ToString());
diff --git a/Source/Libraries/GSF.PhasorProtocols/SelCWS/ConnectionParameters.cs b/Source/Libraries/GSF.PhasorProtocols/SelCWS/ConnectionParameters.cs
diff --git a/Source/Libraries/GSF.PhasorProtocols/SelCWS/FrameParser.cs b/Source/Libraries/GSF.PhasorProtocols/SelCWS/FrameParser.cs
diff --git a/Source/Libraries/GSF.PhasorProtocols/SelCWS/RollingPhaseEstimator.cs b/Source/Libraries/GSF.PhasorProtocols/SelCWS/RollingPhaseEstimator.cs
