OpenProtocolInterpreter

For complex applications, you can create a dispatch system that maps MID types to specific actions using delegates.

1. Define a delegate (e.g., ReceivedCommandActionDelegate) that accepts ReceivedMidEventArgs.
2. Create a dictionary mapping Type to your delegate.
3. When a package is received, parse it using the interpreter, look up the type in your dictionary, and invoke the corresponding delegate.

// 1. Define delegate and args
protected delegate void ReceivedCommandActionDelegate(ReceivedMidEventArgs e);

public class ReceivedMidEventArgs : EventArgs
{
    public Mid ReceivedMid { get; set; }
}

// 2. Register MIDs to delegates
protected Dictionary<Type, ReceivedCommandActionDelegate> RegisterOnAsyncReceivedMids()
{
    var receivedMids = new Dictionary<Type, ReceivedCommandActionDelegate>();
    receivedMids.Add(typeof(Mid0005), new ReceivedCommandActionDelegate(OnCommandAcceptedReceived));
    return receivedMids;
}

// 3. Dispatch on receipt
protected void OnPackageReceived(string message)
{
    var mid = Interpreter.Parse(message);
    if (OnReceivedMid.TryGetValue(mid.GetType(), out var action))
    {
        action(new ReceivedMidEventArgs { ReceivedMid = mid });
    }
}

MIDs 0006 (request), 0008 (subscription), and 0009 (unsubscription) contain free-form payloads that depend on the specific MID being requested. These are modeled using ExtraData classes.

Packing: Use SetExtraData on the container MID. This automatically populates SubscriptionMid, WantedRevision, ExtraDataLength, and ExtraData.

Parsing: First, parse the container MID. Then, instantiate the appropriate ExtraData class using the WantedRevision from the container and pass the ExtraData bytes to its .Parse() method.

// Packing extra data
var subscription = new Mid0008();
subscription.SetExtraData(new Mid1201ExtraDataSubscription
{
    SendAlternatives = 1,
    DataIdentifierTimestamp = new DateTime(2026, 8, 7, 13, 45, 0),
    SendObjectData = true
});
var package = subscription.Pack();

// Parsing extra data
var mid08 = interpreter.Parse<Mid0008>(package);
var extraData = (Mid1201ExtraDataSubscription)new Mid1201ExtraDataSubscription(mid08.WantedRevision)
                                                    .Parse(mid08.ExtraData);

When adding new benchmarks to the suite, follow these guidelines:

1. Use Sample Packages: Do not inline raw strings. Add new sample packages to Packages.cs (copied from the test suite) to ensure they are valid and known to the parser.
2. Group by Direction: Keep packages grouped by direction (IController mids are sent by the controller, IIntegrator mids by the integrator) to ensure mode benchmarks remain accurate.
3. Avoid Assertions: Benchmark bodies must not contain assertions. Assertions measure the cost of the assertion itself rather than the code being benchmarked. Correctness should be verified in MIDTesters.Core.
4. Use [GlobalSetup] for Validation: If a benchmark depends on successful package parsing, perform a single check inside a [GlobalSetup] method. This ensures that a broken sample fails the run immediately rather than reporting the cost of an exception during the benchmark loop.

To parse packages, you must first instantiate a MidInterpreter and configure it with the MIDs it should recognize. Use UseAllMessages() to enable all known MIDs.

Parsing Strategies

• Known MID: Use the generic Parse<T>(package) method when you know the expected MID type. This returns the specific class (e.g., Mid0004). Note that this throws an InvalidCastException if the package does not match the requested type.
• Unknown MID: Use the non-generic Parse(package) method when you do not know which MID is arriving. This returns a base Mid object.

Both string and byte[] packages are supported.

// Setup the interpreter
var interpreter = new MidInterpreter().UseAllMessages();

// Parsing a specific known MID
var midPackage = "00260004001         001802";
var myMid04 = interpreter.Parse<Mid0004>(midPackage);

// Accessing properties
int myFailedMid = myMid04.FailedMid;    // 18
Error errorCode = myMid04.ErrorCode;    // Error.ParameterSetIdNotPresent

// Parsing when the MID type is unknown
byte[] rawPackage = socket.Receive();
var mid = interpreter.Parse(rawPackage); // returns base Mid

You can inject MIDs that are not part of the official documentation using the UseCustomMessage method. This method accepts a Dictionary<int, Type> mapping the MID integer to your custom class.

Your custom class must inherit from Mid and define its own data fields using attributes like [TimestampDataFieldDefinition] or [StringDataFieldDefinition] to specify how the raw bytes should be mapped to properties.

Note: Custom messages may be slower than built-in MIDs because they lack specific lookup optimizations.

var interpreter = new MidInterpreter()
                        .UseAllMessages()
                        .UseCustomMessage(new Dictionary<int, Type> { { NewMid0083.MID, typeof(NewMid0083) } });

public class NewMid0083 : Mid
{
    public const int MID = 83;

    [TimestampDataFieldDefinition(revision: 1, field: 1, Index = 20, HasPrefix = false)]
    public DateTime Time { get; set; }

    [StringDataFieldDefinition(revision: 1, field: 2, Index = 39, Size = 2, HasPrefix = false)]
    public string TimeZone { get; set; }

    public NewMid0083() : base(MID, DEFAULT_REVISION) { }
    public NewMid0083(Header header) : base(header) { }
}

To improve performance and reduce memory footprint, you can restrict the MidInterpreter to only recognize a specific subset of MIDs. You can register specific types using UseAllMessages or register entire categories using specialized extension methods like UseCommunicationMessages, UseTighteningMessages, or UseAlarmMessages.

When registering categories, you can specify an InterpreterMode to filter messages based on whether the device is acting as a Controller or an Integrator:

• InterpreterMode.Integrator: Keeps only MIDs a controller can send to you.
• InterpreterMode.Controller: Keeps only MIDs an integrator can send to you.
• InterpreterMode.Both: Keeps everything (default).

Extension methods accept a mode, an IEnumerable<Type>, or an IDictionary<int, Type>.

// Register specific MIDs
var myCustomInterpreter = new MidInterpreter()
                                .UseAllMessages(new Type[]
                                {
                                    typeof(Mid0001),
                                    typeof(Mid0002),
                                    typeof(Mid0003),
                                    typeof(Mid0004),
                                    typeof(Mid0106)
                                });

// Register categories with a specific mode
var interpreter = new MidInterpreter()
                        .UseCommunicationMessages(InterpreterMode.Integrator)
                        .UseTighteningMessages(InterpreterMode.Integrator)
                        .UseAlarmMessages(InterpreterMode.Integrator);