OpenProtocolInterpreter

OpenProtocol communication utility

Missing OpenProtocolInterpreter v1.0.0 ? >It's here!<

Missing OpenProtocolInterpreter v2.2.1 ? >It's here!<

What is Open Protocol at all?
What is OpenProtocolInterpreter?
Changelog version 3.0.0
How does it work?
Usage examples
Available on package managers
Advanced section
Tips
Contribute to the project
Still unavailable mids
Next steps

What is Open Protocol at all?

Open Protocol, as the name says, it's a protocol to communicate with Atlas Copco Tightening Controllers or whatever that implement that protocol. Most common Tightening Controllers from Atlas Copco company are PowerFocus4000 and PowerMacs.

Although, some other companies adhered to use the same protocol.

What is OpenProtocolInterpreter?

OpenProtocolInterpreter is a library that converts the ugly string that came from Open Protocol packages, which is commonly called MID, to an object. "Substringing" packages is such a boring thing to do, so let OpenProtocolIntepreter do it for you!

If you're curious, just take a look at their documentation.

Changelog for version 3.0.0

Reworked on how to instantiate a Mid class when parsing to fix a bug where the parse method updates the same instance instead of creating a new;
Pack methods added to MidInterpreter as Pack(Mid mid) and PackBytes(Mid mid);
Added extension methods to MidInterpreter to use the desired Mids/Message parsers;
Now you can instantiate MidIntepreter telling if you're the Controller or the Integrator;
Upgraded it from .net framework 4.5.1 to .net standard 2.0 to include .net core projects;

How does it work?

It's simple, you give us your byte[] or string package and we deliver you an object, simple as that!

For example, let's imagine you received the following string package:

string package = "00240005001         0018";

It's MID 5, so OpenProtocolIntepreter will return a Mid0005 class for you with all his datafields and the package entire translated to an object.

Let's see some examples of usage

A simple usage:

var interpreter = new MidInterpreter();
var midPackage = @"00260004001         001802";
var myMid04 = interpreter.Parse<Mid0004>(midPackage);
//MID 0004 is an error mid which contains which MID Failed and its error code
//Int value of the Failed Mid
int myFailedMid = myMid04.FailedMid;
//An enum with Error Code
Error errorCode = myMid04.ErrorCode;

It can generate an object from a string, but can it make it to the other way?? FOR SURE!

var jobUploadRequest = new Mid0032(1, 2); //Job id 1, revision 2
var package = jobUploadRequest.Pack();
//Generated package => 00240032002         0001

Get it on NuGet!

Install-Package OpenProtocolInterpreter

Advanced Section!

Now we will get real! Put one thing in mind, in real world we will always need to build something more complex than the dummies examples we give to you. With this in mind, this section is for you:

How it was built?

It used to rely on Chain Of Responsabilities design pattern, but since we had some problems with instance references, it changed! For now, instead of iterating through all Mids of the same category, it relies on a Dictionary, which every category knows which mid it attends, once it found it creates a new Instance via System.Reflection and parse it.

MIDs Identifying Customization

We have several MIDs inside Open Protocol documentation, but do you really need all of them? The answer is... NO!

You will probably need only to use a range of MIDs, with this in mind, we did something to make things faster. You can tell us which MIDs we should considerate!

*NOTE: You can register only mids you need to call "Parse" method

Here is an example:

string package = "00260004001         001802";
var myCustomInterpreter = new MidInterpreter()
								.UseAllMessages(new Type[]
		                        {
		                            typeof(Mid0001),
		                            typeof(Mid0002),
		                            typeof(Mid0003),
		                            typeof(Mid0004),
		                            typeof(Mid0106)
		                        });
//Will work:
var myMid04 = myCustomInterpreter.Parse<Mid0004>(package);
//Won't work, will throw NotImplementedException:
var myMid30 = myCustomInterpreter.Parse<Mid0030>(package);        
//Won't work, will throw InvalidCastException:
var myMid01 = myCustomInterpreter.Parse<Mid0001>(package);

When you don't know which package will come, use Parse overload, not Parse<DesiredMid>. If you want, take a look at the sample on this repository.

If necessary, there is a new overload where you can define if you're the controller or the integrator, which will automatically handle implemented mids

Advanced Example

Declared a delegate:

protected delegate void ReceivedCommandActionDelegate(ReceivedMIDEventArgs e);

ReceivedMIDEventArgs class:

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

Created a method to register all those MID types by delegates:

protected Dictionary<Type, ReceivedCommandActionDelegate> RegisterOnAsyncReceivedMids()
{
    var receivedMids = new Dictionary<Type, ReceivedCommandActionDelegate>();
    receivedMids.Add(typeof(Mid0005), new ReceivedCommandActionDelegate(OnCommandAcceptedReceived));
    receivedMids.Add(typeof(Mid0004), new ReceivedCommandActionDelegate(OnErrorReceived));
    receivedMids.Add(typeof(Mid0071), new ReceivedCommandActionDelegate(OnAlarmReceived));
    receivedMids.Add(typeof(Mid0061), new ReceivedCommandActionDelegate(OnTighteningReceived));
    receivedMids.Add(typeof(Mid0035), new ReceivedCommandActionDelegate(OnJobInfoReceived));
    return receivedMids;
}

What was done is registering in a dictionary the correspondent delegate for a determinated MID, once done that we just need to invoke the delegate everytime you face a desired MID.

When a package income:

protected void OnPackageReceived(string message)
{
    try
    {
        //Parse to mid class
        var mid = Interpreter.Parse(message);

        //Get Registered delegate for the MID that was identified
        var action = OnReceivedMid.FirstOrDefault(x => x.Key == mid.GetType());
        
        if (action.Equals(default(KeyValuePair<Type, ReceivedCommandActionDelegate>)))
           return; //Stop if there is no delegate registered for the message that arrived

         action.Value(new ReceivedMidEventArgs() { ReceivedMid = mid }); //Call delegate
     }
     catch (Exception ex)
     {
        Console.log(ex.Message);
     }
}

This would call the registered delegate which you're sure what mid it is. For example when a MID_0061 (last tightening) pop up, the onTighteningReceived delegate will be called:

protected void OnTighteningReceived(ReceivedMidEventArgs e)
{
    try
    {
        Mid0061 tighteningMid = e.ReceivedMID as Mid0061; //Casting to the right mid

        //This method just send the ack from tightening mid
        BuildAndSendAcknowledge(tighteningMid); 
        Console.log("TIGHTENING ARRIVED")
     }
     catch (Exception ex)
     {
         Console.log(ex.Message);
     }
}

protected void BuildAndSendAcknowledge(Mid mid)
{
     TcpClient.GetStream().Write(new Mid0062().Pack()); //Send acknowledge to controller
}

Tips

Instantiate the MIDIdentifier class just once and keep working with it!

Controller Implementation Tip: Always TRY to register used MIDs, not all Tightening Controllers use every available MID.

Integrator Implementation Tip: Always DO register used MIDs, I'm pretty sure you won't need all of them to your application.

Contribute to the project

Lot's of effort were given to this project and by seen people using it motivated me a lot to improve it more and more.

Does it help you a lot? That's awesome and very rewarding! But if you wish, you can support and help to motivate the constant improving of this library:

List of still unavailable Mids

Mid 0009;
Mid 0100;
Mid 0700;
Mid 0900;
Mid 0901;
Mid 2500;
Mid 2501;
Mid 2505;
Mid 2600;
Mid 2601;
Mid 2602;
Mid 2603;
Mid 2604;
Mid 2605;
Mid 2606;
Mid 9997;
Mid 9998.

Feel free to fork and contribute to add any of those mids.

Next Steps

Add missing mids;
Create wiki.

sgmcumt/OpenProtocolInterpreter