/// <summary>
/// Creates a new <see cref="CommandFrame"/> from the given <paramref name="buffer"/>.
/// </summary>
/// <param name="buffer">Binary image to parse.</param>
/// <param name="startIndex">Start index into <paramref name="buffer"/> to begin parsing.</param>
/// <param name="length">Length of valid data within <paramref name="buffer"/>.</param>
/// <remarks>
/// This constructor is used by a consumer to parse a received SEL Fast Message command frame. Typically
/// command frames are sent to a device. This constructor would used if this code was being used
/// inside of a phasor measurement device.
/// </remarks>
/// <exception cref="ArgumentOutOfRangeException"><paramref name="length"/> is not large enough to parse frame.</exception>
public CommandFrame(byte[] buffer, int startIndex, int length)
: base(new CommandCellCollection(0), PhasorProtocols.DeviceCommand.ReservedBits)
{
if (length < 16)
throw new ArgumentOutOfRangeException(nameof(length));
// Validate check-sum
if (!ChecksumIsValid(buffer, startIndex))
throw new InvalidOperationException("Invalid binary image detected - check sum of " + this.GetType().Name + " did not match");
// Validate SEL Fast Message data image
if (buffer[startIndex] != Common.HeaderByte1 || buffer[startIndex + 1] != Common.HeaderByte2)
throw new InvalidOperationException("Bad data stream, expected header bytes 0xA546 as first bytes in SEL Fast Message command frame, got 0x" + buffer[startIndex].ToString("X").PadLeft(2, '0') + buffer[startIndex + 1].ToString("X").PadLeft(2, '0'));
Command = (DeviceCommand)buffer[startIndex + 9];
if (Command == DeviceCommand.EnableUnsolicitedMessages)
m_messagePeriod = (MessagePeriod)BigEndian.ToUInt16(buffer, startIndex + 14);
// Validate check-sum
int sumLength = FrameSize - 2;
if (BigEndian.ToUInt16(buffer, startIndex + sumLength) != CalculateChecksum(buffer, startIndex, sumLength))
throw new InvalidOperationException("Invalid binary image detected - check sum of " + this.GetType().Name + " did not match");
}
/// <summary>
/// Creates a new <see cref="FrameParser"/> from specified parameters.
/// </summary>
/// <param name="checkSumValidationFrameTypes">Frame types that should perform check-sum validation; default to <see cref="GSF.PhasorProtocols.CheckSumValidationFrameTypes.AllFrames"/></param>
/// <param name="trustHeaderLength">Determines if header lengths should be trusted over parsed byte count.</param>
/// <param name="messagePeriod">The desired <see cref="SelFastMessage.MessagePeriod"/> for SEL device connection.</param>
public FrameParser(CheckSumValidationFrameTypes checkSumValidationFrameTypes = CheckSumValidationFrameTypes.AllFrames, bool trustHeaderLength = true, MessagePeriod messagePeriod = MessagePeriod.DefaultRate)
: base(checkSumValidationFrameTypes, trustHeaderLength)
{
// Initialize protocol synchronization bytes for this frame parser
base.ProtocolSyncBytes = new[] { Common.HeaderByte1, Common.HeaderByte2 };
m_messagePeriod = messagePeriod;
}
/// <summary>
/// Creates a new <see cref="ConfigurationFrame"/> from serialization parameters.
/// </summary>
/// <param name="info">The <see cref="SerializationInfo"/> with populated with data.</param>
/// <param name="context">The source <see cref="StreamingContext"/> for this deserialization.</param>
protected ConfigurationFrame(SerializationInfo info, StreamingContext context)
: base(info, context)
{
// Deserialize configuration frame
m_frameSize = (FrameSize)info.GetValue("frameSize", typeof(FrameSize));
m_messagePeriod = (MessagePeriod)info.GetValue("messagePeriod", typeof(MessagePeriod));
m_idCode = info.GetUInt32("idCode32Bit");
}
/// <summary>
/// Creates a new <see cref="ConfigurationFrame"/>.
/// </summary>
/// <remarks>
/// This constructor is used by a consumer to generate a SEL Fast Message configuration frame.
/// </remarks>
/// <param name="frameSize">A <see cref="FrameSize"/> object.</param>
/// <param name="idCode">An <see cref="uint"/> as the id code.</param>
/// <param name="messagePeriod">A <see cref="MessagePeriod"/> object.</param>
public ConfigurationFrame(FrameSize frameSize, MessagePeriod messagePeriod, uint idCode)
: base(0, new ConfigurationCellCollection(), 0, 0)
{
FrameSize = frameSize;
MessagePeriod = messagePeriod;
IDCode = idCode;
ConfigurationCell configCell = new(this);
// Assign station name
configCell.StationName = $"SEL Unit - {idCode}";
// Add a single frequency definition
configCell.FrequencyDefinition = new FrequencyDefinition(configCell, "Line frequency");
// Add phasors based on frame size
switch (frameSize)
{
case FrameSize.V1:
// Add a single positive sequence voltage phasor definition
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "V1", PhasorType.Voltage, null));
break;
case FrameSize.V:
// Add three-phase and positive sequence voltage phasors
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "VA", PhasorType.Voltage, null));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "VB", PhasorType.Voltage, null));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "VC", PhasorType.Voltage, null));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "V1", PhasorType.Voltage, null));
break;
case FrameSize.A:
// Add three-phase and positive sequence voltage and current phasors
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "VA", PhasorType.Voltage, null));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "VB", PhasorType.Voltage, null));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "VC", PhasorType.Voltage, null));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "V1", PhasorType.Voltage, null));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "IA", PhasorType.Current, configCell.PhasorDefinitions[0] as PhasorDefinition));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "IB", PhasorType.Current, configCell.PhasorDefinitions[1] as PhasorDefinition));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "IC", PhasorType.Current, configCell.PhasorDefinitions[2] as PhasorDefinition));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "I1", PhasorType.Current, configCell.PhasorDefinitions[3] as PhasorDefinition));
break;
}
// SEL Fast Message protocol sends data for one device
Cells.Add(configCell);
// Define message rate (best-fit)
FrameRate = messagePeriod switch
{
MessagePeriod.DefaultRate or MessagePeriod.TwentyPerSecond => 20,
MessagePeriod.TenPerSecond => 10,
MessagePeriod.FivePerSecond => 5,
MessagePeriod.FourPerSecond => 4,
MessagePeriod.TwoPerSecond => 2,
MessagePeriod.OnePerSecond => 1,
_ => 0,
};
}
/// <summary>
/// Creates a new <see cref="CommandFrame"/> from specified parameters.
/// </summary>
/// <param name="command">The <see cref="PhasorProtocols.DeviceCommand"/> for this <see cref="CommandFrame"/>.</param>
/// <param name="messagePeriod">The desired <see cref="SelFastMessage.MessagePeriod"/> for SEL device connection.</param>
/// <remarks>
/// This constructor is used by a consumer to generate an SEL Fast Message command frame.
/// </remarks>
public CommandFrame(PhasorProtocols.DeviceCommand command, MessagePeriod messagePeriod)
: base(new CommandCellCollection(0), command)
{
if (command != PhasorProtocols.DeviceCommand.EnableRealTimeData && command != PhasorProtocols.DeviceCommand.DisableRealTimeData)
{
throw new ArgumentException($"SEL Fast Message does not support {command} device command.", nameof(command));
}
m_messagePeriod = messagePeriod;
}
/// <summary>
/// Creates a new <see cref="ConnectionParameters"/> from serialization parameters.
/// </summary>
/// <param name="info">The <see cref="SerializationInfo"/> with populated with data.</param>
/// <param name="context">The source <see cref="StreamingContext"/> for this deserialization.</param>
protected ConnectionParameters(SerializationInfo info, StreamingContext context)
{
// Deserialize connection parameters
m_messagePeriod = info.GetOrDefault("messagePeriod", MessagePeriod.DefaultRate);
}
/// <summary>
/// Creates a new <see cref="ConnectionParameters"/>.
/// </summary>
public ConnectionParameters()
{
m_messagePeriod = MessagePeriod.DefaultRate;
}
/// <summary>
/// Creates a new <see cref="CommandFrame"/> from serialization parameters.
/// </summary>
/// <param name="info">The <see cref="SerializationInfo"/> with populated with data.</param>
/// <param name="context">The source <see cref="StreamingContext"/> for this deserialization.</param>
protected CommandFrame(SerializationInfo info, StreamingContext context)
: base(info, context)
{
// Deserialize command frame
m_messagePeriod = (MessagePeriod)info.GetValue("messagePeriod", typeof(MessagePeriod));
}
/// <summary>
/// Creates a new <see cref="CommandFrame"/> from specified parameters.
/// </summary>
/// <param name="command">The <see cref="GSF.PhasorProtocols.DeviceCommand"/> for this <see cref="CommandFrame"/>.</param>
/// <param name="messagePeriod">The desired <see cref="SelFastMessage.MessagePeriod"/> for SEL device connection.</param>
/// <remarks>
/// This constructor is used by a consumer to generate an SEL Fast Message command frame.
/// </remarks>
public CommandFrame(PhasorProtocols.DeviceCommand command, MessagePeriod messagePeriod)
: base(new CommandCellCollection(0), command)
{
if (command != PhasorProtocols.DeviceCommand.EnableRealTimeData && command != PhasorProtocols.DeviceCommand.DisableRealTimeData)
throw new ArgumentException("SEL Fast Message does not support " + command + " device command.", nameof(command));
m_messagePeriod = messagePeriod;
}
/// <summary>
/// Creates a new <see cref="CommandFrame"/> from serialization parameters.
/// </summary>
/// <param name="info">The <see cref="SerializationInfo"/> with populated with data.</param>
/// <param name="context">The source <see cref="StreamingContext"/> for this deserialization.</param>
protected CommandFrame(SerializationInfo info, StreamingContext context)
: base(info, context)
{
// Deserialize command frame
m_messagePeriod = (MessagePeriod)info.GetValue("messagePeriod", typeof(MessagePeriod));
}
/// <summary>
/// Creates a new <see cref="ConfigurationFrame"/>.
/// </summary>
/// <remarks>
/// This constructor is used by a consumer to generate a SEL Fast Message configuration frame.
/// </remarks>
public ConfigurationFrame(FrameSize frameSize, MessagePeriod messagePeriod, uint idCode)
: base(0, new ConfigurationCellCollection(), 0, 0)
{
m_frameSize = frameSize;
m_messagePeriod = messagePeriod;
IDCode = idCode;
ConfigurationCell configCell = new ConfigurationCell(this);
// Assign station name
configCell.StationName = "SEL Unit - " + idCode;
// Add a single frequency definition
configCell.FrequencyDefinition = new FrequencyDefinition(configCell, "Line frequency");
// Add phasors based on frame size
switch (frameSize)
{
case FrameSize.V1:
// Add a single positive sequence voltage phasor definition
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "V1", PhasorType.Voltage, null));
break;
case FrameSize.V:
// Add three-phase and positive sequence voltage phasors
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "VA", PhasorType.Voltage, null));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "VB", PhasorType.Voltage, null));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "VC", PhasorType.Voltage, null));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "V1", PhasorType.Voltage, null));
break;
case FrameSize.A:
// Add three-phase and positive sequence voltage and current phasors
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "VA", PhasorType.Voltage, null));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "VB", PhasorType.Voltage, null));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "VC", PhasorType.Voltage, null));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "V1", PhasorType.Voltage, null));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "IA", PhasorType.Current, configCell.PhasorDefinitions[0] as PhasorDefinition));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "IB", PhasorType.Current, configCell.PhasorDefinitions[1] as PhasorDefinition));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "IC", PhasorType.Current, configCell.PhasorDefinitions[2] as PhasorDefinition));
configCell.PhasorDefinitions.Add(new PhasorDefinition(configCell, "I1", PhasorType.Current, configCell.PhasorDefinitions[3] as PhasorDefinition));
break;
}
// SEL Fast Message protocol sends data for one device
Cells.Add(configCell);
// Define message rate (best-fit)
switch (messagePeriod)
{
case MessagePeriod.DefaultRate:
case MessagePeriod.TwentyPerSecond:
FrameRate = 20;
break;
case MessagePeriod.TenPerSecond:
FrameRate = 10;
break;
case MessagePeriod.FivePerSecond:
FrameRate = 5;
break;
case MessagePeriod.FourPerSecond:
FrameRate = 4;
break;
case MessagePeriod.TwoPerSecond:
FrameRate = 2;
break;
case MessagePeriod.OnePerSecond:
FrameRate = 1;
break;
default:
FrameRate = 0;
break;
}
}
/// <summary>
/// Creates a new <see cref="ConfigurationFrame"/> from serialization parameters.
/// </summary>
/// <param name="info">The <see cref="SerializationInfo"/> with populated with data.</param>
/// <param name="context">The source <see cref="StreamingContext"/> for this deserialization.</param>
protected ConfigurationFrame(SerializationInfo info, StreamingContext context)
: base(info, context)
{
// Deserialize configuration frame
m_frameSize = (FrameSize)info.GetValue("frameSize", typeof(FrameSize));
m_messagePeriod = (MessagePeriod)info.GetValue("messagePeriod", typeof(MessagePeriod));
m_idCode = info.GetUInt32("idCode32Bit");
}
// Attempts to cast given frame into a SEL Fast Message configuration frame - theoretically this will
// allow the same configuration frame to be used for any protocol implementation
internal static ConfigurationFrame CastToDerivedConfigurationFrame(IConfigurationFrame sourceFrame, MessagePeriod messagePeriod)
{
// See if frame is already a SEL Fast Message frame (if so, we don't need to do any work)
ConfigurationFrame derivedFrame = sourceFrame as ConfigurationFrame;
if (derivedFrame == null)
{
// Create a new SEL Fast Message configuration frame converted from equivalent configuration information; SEL Fast Message only supports one device
if (sourceFrame.Cells.Count > 0)
{
IConfigurationCell sourceCell = sourceFrame.Cells[0];
switch (sourceCell.PhasorDefinitions.Count)
{
case 8:
derivedFrame = new ConfigurationFrame(FrameSize.A, messagePeriod, sourceFrame.IDCode);
break;
case 4:
derivedFrame = new ConfigurationFrame(FrameSize.V, messagePeriod, sourceFrame.IDCode);
break;
default:
derivedFrame = new ConfigurationFrame(FrameSize.V1, messagePeriod, sourceFrame.IDCode);
break;
}
// Create new derived configuration cell
ConfigurationCell derivedCell = new ConfigurationCell(derivedFrame);
IFrequencyDefinition sourceFrequency;
// Create equivalent derived phasor definitions
foreach (IPhasorDefinition sourcePhasor in sourceCell.PhasorDefinitions)
{
derivedCell.PhasorDefinitions.Add(new PhasorDefinition(derivedCell, sourcePhasor.Label, sourcePhasor.PhasorType, null));
}
// Create equivalent derived frequency definition
sourceFrequency = sourceCell.FrequencyDefinition;
if (sourceFrequency != null)
{
derivedCell.FrequencyDefinition = new FrequencyDefinition(derivedCell, sourceFrequency.Label);
}
// Add cell to frame
derivedFrame.Cells.Add(derivedCell);
}
}
return(derivedFrame);
}
/// <summary>
/// Creates a new <see cref="ConnectionParameters"/> from serialization parameters.
/// </summary>
/// <param name="info">The <see cref="SerializationInfo"/> with populated with data.</param>
/// <param name="context">The source <see cref="StreamingContext"/> for this deserialization.</param>
protected ConnectionParameters(SerializationInfo info, StreamingContext context)
{
// Deserialize connection parameters
m_messagePeriod = (MessagePeriod)info.GetValue("messagePeriod", typeof(MessagePeriod));
}
/// <summary>
/// Creates a new <see cref="ConnectionParameters"/>.
/// </summary>
public ConnectionParameters()
{
m_messagePeriod = MessagePeriod.DefaultRate;
}
/// <summary>
/// Creates a new <see cref="ConnectionParameters"/> from serialization parameters.
/// </summary>
/// <param name="info">The <see cref="SerializationInfo"/> with populated with data.</param>
/// <param name="context">The source <see cref="StreamingContext"/> for this deserialization.</param>
protected ConnectionParameters(SerializationInfo info, StreamingContext context)
{
// Deserialize connection parameters
m_messagePeriod = info.GetOrDefault("messagePeriod", MessagePeriod.DefaultRate);
}
