Example C# Code For Serial Communications Protocol

This is an C# example/library of my serial communications protocol which implements checksums, acknowledge and repeat commands to normal serial communication, while still keeping the end user experience simple and intuitive.

Command Packet Contents

Bellow is an illustration of a command packet which is sent out by the library.

Each command packet consists of an instructions packet, a checksum and an end bit, with each part being seperated by a separator bit. The istructions packet consists of a command and a data part, which are again separated by a bit. In the current form of the protocol the separator bit is a # and the terminator bit is a @.

An example command would look something like this ERR#Something went wrong#4342@. In the that example we are sending a command ERR with the arguments of Something went wrong and the 4342 is an auto generated checksum.

All the data is currently being transmitted in plain-text, however in future versions of the library they will be encoded in hex and sent that way.

High Level Communications Overview

Bellow is a high level overview on how the communications protocol works and what gets sent between the two communicating devices. The left side of the diagram represents the communication when the command arrives to the receiver intact and on the right is a representation of what happens when the checksum is wrong(i.e. The command packet is malformed).

It is important to note that the user never sees the ACKG/RPT commands be sent or the validation process take place. All the end user sees is the action assigned to a given command be executed once it's been confirmed as intact.

Using The Library

This libray is intended to be used in an environment where System.IO.Ports can be imported.

Importing In To A New Project

The library consists of a single file which needs to be coppied in to your new project and that is SerialConnector.cs. To get the library to parse incomming packets you need to create an instance of the SerialConnector class, assign it a serial port and call it's cycle method to check for incomming packets.

using SerialComms;

class Example
{
    SerialConnector serialConnector = new SerialConnector();

    void runOnce()
    {
        serialConnector.SetSerialPort("COM9");
    }

    void loop()
    {
        serialConnector.Cycle();
    }
}

This will now scan the serial port continuously for any incomming commands.

Sending Commands

The instance of the SerialConnector class contains a method called sendCommand which takes in two parameters as Strings. The first parameter is the name of the command being sent and the second parameter are any arguments associated with the command. So if we wanted to send the example command from above ERR#Something went wrong#4342@ it would look something like this

using SerialComms;

class Example
{
    SerialConnector serialConnector = new SerialConnector();

    void runOnce()
    {
        serialConnector.sendCommand("ERR", "Something went wrong");
    }
}

The code above will automatically generate the command packet and send it, and process the incomming acknowledge or repeat packets from the receiver.

Registering A New Command

The instance of the SerialConnector class contains a method called onCommand which takes in two arguments. The first one is a string which is the name of the command and the second argument is a function which accepts a string as an argument. So registering an error function would look like this.

using SerialComms;

class Example
{
    SerialConnector serialConnector = new SerialConnector();

    void error(string args)
    {
        Console.WriteLine(args);
    }

    void runOnce()
    {
        serialConnector.onCommand("ERR", error);
    }
}

The code above will call the error function whenever an ERR command is received and it will automatically pass on any data in to the args of the error function.