Serial-Comms-Protocol-CS/SerialConnector.cs

using System;
using System.Collections.Generic;
using System.IO.Ports;
using System.Text;

namespace SerialComms
{
    internal class SerialConnector
    {
        private static SerialPort serial = new SerialPort(); // The serial port used for all communications
        private static Dictionary<string, Action<string>> commands = new Dictionary<string, Action<string>>(); // Stores all the names of the incomming commands and their callback functions
        public bool EnableDebugLogs { get; set; } // Enables or disables debugging console logs

        /// <summary>
        /// Initializes a new instance of the <see cref="SerialConnector"/> class with the specified debug logging
        /// option and baud rate.
        /// </summary>
        /// <remarks>Use this constructor to configure the serial connection's baud rate and optionally
        /// enable debug logging for troubleshooting or development purposes.</remarks>
        /// <param name="enableDebugLogs"><see langword="true"/> to enable detailed debug logging for serial communication; otherwise, <see
        /// langword="false"/>. The default is <see langword="false"/>.</param>
        /// <param name="baudRate">The baud rate to use for the serial connection. Must be a positive integer. The default is 9600.</param>
        public SerialConnector(bool enableDebugLogs = false, int baudRate = 9600)
        {
            serial.BaudRate = baudRate;
            this.EnableDebugLogs = enableDebugLogs;
        }

        /// <summary>
        /// Sets the serial port to the specified port name and opens the connection for communication.
        /// </summary>
        /// <remarks>If a serial port connection is already open, it is closed before setting the new port
        /// name and opening the connection.</remarks>
        /// <param name="port">The name of the serial port to use (for example, "COM1" or "/dev/ttyUSB0").</param>
        public void SetSerialPort(string port)
        {

            // If a port is already open, close it first to ensure a clean state before reconfiguring.
            if (serial.IsOpen)
                serial.Close();

            // Optional debug log to indicate which port will be used.
            if (EnableDebugLogs)
                Console.WriteLine("Setting serial port to: " + port);

            // Assign the requested port name to the SerialPort instance.
            serial.PortName = port;

            try
            {
                // Attempt to open the configured serial port. Opening can fail if the port doesn't exist
                // or is already in use by another process.
                if (EnableDebugLogs)
                    Console.WriteLine("Attempting to open serial port");
                serial.Open();

                // Clear any leftover data in the input buffer so subsequent reads start fresh.
                serial.DiscardInBuffer();

                if (EnableDebugLogs)
                    Console.WriteLine("Opened serial port");
            }
            catch (Exception ex)
            {
                throw ex;
            }
        }

        /// <summary>
        /// Processes incoming serial data, verifies its integrity, and executes the corresponding command if valid.
        /// </summary>
        /// <remarks>This method reads available data from the serial buffer, validates the data using a
        /// check bit, acknowledges receipt, and dispatches the command for execution. If the data fails integrity
        /// checks or cannot be parsed, the method asks the sender to repeat the command or throws an exception. Debug
        /// logging is performed if enabled.</remarks>
        /// <exception cref="Exception">Thrown if the check bit verification fails due to parsing errors or if command execution fails.</exception>
        public void Cycle()
        {
            // Only proceed if there is data waiting in the serial input buffer.
            if (serial.BytesToRead > 0)
            {
                if (EnableDebugLogs)
                    Console.WriteLine("Starting to read from serial buffer");

                // Read until the protocol terminator '@' is encountered.
                string raw = serial.ReadTo("@");

                if (EnableDebugLogs)
                    Console.WriteLine("Read: '" + raw + "' from serial buffer");

                // Split the incoming packet into its three components: command, args, checkBit.
                string[] data = raw.Split('#');

                if (EnableDebugLogs)
                    Console.WriteLine("Split serial buffer in to: " + data[0] + ", " + data[1] + ", " + data[2]);

                try
                {
                    if (EnableDebugLogs)
                        Console.WriteLine("Attempting to verify check bit");

                    // Verify integrity using the provided check bit; parse the check bit to an integer.
                    if (!VerifyCheckBit(data[0], data[1], Int32.Parse(data[2])))
                    {
                        if (EnableDebugLogs)
                            Console.WriteLine("Check failed");

                        // Ask the sender to repeat the command if the integrity check failed and return early.
                        Repeat();
                        return;
                    }
                }
                catch (Exception ex)
                {
                    // Wrap parsing/verification errors with context and rethrow.
                    throw new Exception("Failed to verify check bit. Was unable to parse command: " + raw + "\n" + ex.Message);
                }

                if (EnableDebugLogs)
                    Console.WriteLine("Command integrity verified successfuly");

                // Send an acknowledgement back to the sender using the parsed check bit.
                Acknowledge(Int32.Parse(data[2]));

                try
                {
                    // If a handler for this command is registered, invoke it with the argument string.
                    if (commands.ContainsKey(data[0]))
                        commands[data[0]](data[1]);
                }
                catch
                {
                    // Provide context that execution of the command handler failed.
                    throw new Exception("Failed to get and execute command: " + data[0]);
                }
            }
        }

        /// <summary>
        ///     Receives all three parts of an icomming packet and check for the commands integrity using it's check bit.
        /// </summary>
        /// <param name="cmd">The command</param>
        /// <param name="args">The arguments to the command</param>
        /// <param name="checkBit">The check bit of the packet</param>
        /// <returns>true if the packet is intact, false if it's malformed</returns>
        private bool VerifyCheckBit(string cmd, string args, int checkBit)
        {
            // Recreate the portion of the packet which was used to generate the original checksum.
            string toCheck = cmd + "#" + args;

            // Compute the numeric checksum and compare to the provided check bit.
            if (StringToCheckNum(toCheck) == checkBit)
                return true;
            else
                return false;
        }

        /// <summary>
        ///     Generates a checksum for a given string
        /// </summary>
        /// <param name="str">The string for which a checksum is needed</param>
        /// <returns></returns>
        private int StringToCheckNum(string str)
        {
            // Initialize accumulator for checksum.
            int x = 0;

            // Convert the input string to bytes using the system default encoding.
            byte[] ba = Encoding.Default.GetBytes(str);

            // Convert the byte array to a hex string representation (e.g. "DE-AD-BE-EF").
            var hexString = BitConverter.ToString(ba);

            // Remove the hyphens so the string is a contiguous sequence of hex digits.
            hexString = hexString.Replace("-", "");

            // Sum the numeric value of each element in the hexString.
            foreach (byte bit in hexString)
            {
                x += bit;
            }

            // Return the computed checksum.
            return x;
        }

        /// <summary>
        /// Sends a command to the serial device to request repetition of the last operation.
        /// </summary>
        /// <remarks>This method transmits a predefined repeat command to the connected serial device. If
        /// debug logging is enabled, a message is written to the console indicating that a repeat request has been
        /// sent.</remarks>
        /// <exception cref="Exception">Thrown if the repeat command cannot be sent to the serial device.</exception>
        private void Repeat()
        {
            // Pre-built repeat packet according to the protocol.
            string cmd = "RPT##410@";

            try
            {
                // Send the repeat request downstream.
                serial.Write(cmd);
            }
            catch (Exception ex)
            {
                // Wrap and rethrow serial write exceptions for callers to handle.
                throw new Exception("Failed to send RPT.\n" + ex.Message);
            }

            if (EnableDebugLogs)
                Console.WriteLine("Asking for repeat of last command");
        }

        /// <summary>
        /// Sends an acknowledgment command with the specified check bit to the connected device.
        /// </summary>
        /// <param name="checkBit">The check bit value to include in the acknowledgment command. This value is used to confirm receipt of a
        /// previous message or command.</param>
        /// <exception cref="Exception">Thrown if the acknowledgment command cannot be sent to the device.</exception>
        private void Acknowledge(int checkBit)
        {
            // Build the acknowledge payload and compute its checksum to form a complete packet.
            string cmd = "ACKG";
            string toSend = cmd + "#" + checkBit;
            int checkNum = StringToCheckNum(toSend);
            string final = toSend + "#" + checkNum + "@";

            try
            {
                // Transmit the ACKG packet.
                serial.Write(final);
            }
            catch (Exception ex)
            {
                // Wrap and rethrow serial write exceptions for callers to handle.
                throw new Exception("Failed to send ACKG.\n" + ex.Message);
            }

            if (EnableDebugLogs)
                Console.WriteLine("Acknowledged last command: " + final);

        }

        /// <summary>
        /// Sends a command with the specified arguments to the connected device over the serial interface.
        /// </summary>
        /// <remarks>The method formats the command and arguments according to the device protocol and
        /// transmits them over the serial connection. If debug logging is enabled, the formatted command is written to
        /// the console output.</remarks>
        /// <param name="cmd">The command to send. Cannot be <see langword="null"/> or empty.</param>
        /// <param name="args">The arguments to include with the command. Cannot be <see langword="null"/>; may be empty if the command
        /// does not require arguments.</param>
        /// <exception cref="Exception">An error occurred while sending the command or during post-send validation.</exception>
        public void SendCommand(string cmd, string args)
        {
            // Compose the command payload and compute its checksum to create the final packet string.
            string toSend = cmd + "#" + args;
            int checkNum = StringToCheckNum(toSend);
            string final = toSend + "#" + checkNum + "@";

            try
            {
                // Send the final packet over serial.
                serial.Write(final);
                if (EnableDebugLogs)
                    Console.WriteLine("Sending command: " + final);
            }
            catch (Exception ex)
            {
                // Provide context about the failed send and propagate the error.
                throw new Exception("Failed to send command: " + final + "\n" + ex.Message);
            }

            try
            {
                // Perform additional response handling after sending the command (e.g. check for ACKG or RPT).
                AfterSendCheck(final);
            }
            catch (Exception ex)
            {
                // Rethrow any errors produced by the after-send logic.
                throw new Exception(ex.Message);
            }
        }

        /// <summary>
        /// Performs post-send validation and handling based on the response received from the serial device after
        /// sending a command.
        /// </summary>
        /// <remarks>This method reads the response from the serial device and processes it to determine
        /// whether the command should be repeated or acknowledged.  If the response indicates a repeat request, the
        /// original command is resent. If the response is an acknowledgment, the method verifies the integrity of the
        /// acknowledgment using check values.</remarks>
        /// <param name="cmd">The command string that was sent to the serial device.</param>
        /// <exception cref="Exception">Thrown if the response from the serial device cannot be parsed, or if the check values in the acknowledgment
        /// cannot be converted to integers.</exception>
        private void AfterSendCheck(string cmd)
        {
            // Read the next response packet.
            string raw = serial.ReadTo("@");

            // If an empty string was returned, attempt to read again recursively.
            if (raw == "")
                AfterSendCheck(cmd);

            if (EnableDebugLogs)
                Console.WriteLine("Performing after send checks");

            // Split the incoming response into components.
            string[] data = raw.Split('#');
            if (data.Length < 1)
                throw new Exception("Failed to parse Data after send packet");

            if (EnableDebugLogs)
                Console.WriteLine("Data array: " + data[0] + ", " + data[1]);

            // Parse the original command that was sent (remove terminator, then split).
            string[] dataCmd = cmd.Replace("@", "").Split('#');
            if (dataCmd.Length < 2)
                throw new Exception("Failed to parse DataCmd after send packet");

            if (EnableDebugLogs)
                Console.WriteLine("DataCmd array: " + data[0] + ", " + data[1] + ", " + data[2]);

            // If the remote requested a repeat, resend the original command.
            if (data[0] == "RPT")
            {
                if (EnableDebugLogs)
                    Console.WriteLine("Repeat command received");
                SendCommand(dataCmd[0], dataCmd[1]);
            }
            else if (data[0] == "ACKG")
            {
                if (EnableDebugLogs)
                    Console.WriteLine("Command acknowledged");

                int check, cmdCheck;
                try
                {
                    // Convert the received check value to an integer.
                    check = Int32.Parse(data[1]);
                }
                catch
                {
                    throw new Exception("Failed to convert check bit to int");
                }

                try
                {
                    // Extract the checksum portion of the original sent command for comparison.
                    cmdCheck = Int32.Parse(dataCmd[2]);
                }
                catch
                {
                    throw new Exception("Failed to convert checkCmd bit in to int");
                }

                // Compare the two check values and optionally log the result.
                if (check != cmdCheck)
                {
                    if (EnableDebugLogs)
                        Console.WriteLine("Acknowledge check bad");
                }
                else
                {
                    if (EnableDebugLogs)
                        Console.WriteLine("Acknowledge check good");
                }
            }
        }

        /// <summary>
        /// Registers a callback to be invoked when the specified command is triggered.
        /// </summary>
        /// <remarks>Use this method to associate a handler with a command name. Attempting to register
        /// the same command more than once will result in an exception.</remarks>
        /// <param name="command">The name of the command to register. Cannot be null or empty. Must be unique among registered commands.</param>
        /// <param name="callback">The callback action to execute when the command is triggered. Cannot be null.</param>
        /// <exception cref="Exception">Thrown if the command already exists</exception>
        public void OnCommand(string command, Action<string> callback)
        {
            // Add the callback to the commands dictionary if it does not already exist.
            if (!commands.ContainsKey(command))
                commands.Add(command, callback);
            else
                // Provide a clear exception if the command name is already registered.
                throw new Exception("Unable to register command: " + command + " as command already exists");
        }

        /// <summary>
        /// Closes the serial port connection if it is currently open.
        /// </summary>
        /// <remarks>Calling this method when the serial port is already closed has no effect.</remarks>
        public void CloseSerial()
        {
            // Optionally log that the serial port is being closed.
            if (EnableDebugLogs)
                Console.WriteLine("Closing serial port");

            // Only attempt to close if the port is currently open.
            if (serial.IsOpen) serial.Close();
        }

    }
}