Added comments to all functions

include/serialConnector.h

@@ -25,53 +25,92 @@ private:
     void (*calibrationBeginHandler)(String args);
     void (*calibrationInteruptHandler)(String args);
 
-    // Convert each character of `cmd` to its hexadecimal representation
+    /**
-    // and return the concatenated hex string.
+     * Convert a string into its hexadecimal representation.
+     * @param cmd Input string to convert.
+     * @return Hexadecimal representation of the input string.
+     */
     String stringToHex(String cmd);
 
-    // Compute a numeric 'check' value from `cmd` by converting chars to
+    /**
-    // their hex digits and summing/concatenating (project-specific logic).
+     * Convert a string into a numeric checksum used by the protocol.
-    // Returns an integer suitable for use as a check-bit value.
+     * @param cmd Input string to convert.
+     * @return Integer checksum computed from the input string.
+     */
     int stringToCheckNum(String cmd);
 
-    // Return the index of character `ch` in `str`, or -1 if not found.
+    /**
+     * Find the index of a character inside a string.
+     * @param ch Character to search for.
+     * @param str String to search within.
+     * @return Index of the character if found, -1 otherwise.
+     */
     int getCharIndex(char ch, String str);
 
-    // Parse an incoming framed message and return the command portion
+    /**
-    // (everything before the first '#').
+     * Extract the command portion from an incoming raw message.
+     * The message format is expected to be: CMD#ARGS#CHECK@ (terminator '@').
+     * @param incomming Raw incoming message string.
+     * @return The command portion of the incoming message.
+     */
     String getCommandFromIncomming(String incomming);
 
-    // Parse an incoming framed message and return the arguments portion
+    /**
-    // (text between the first and second '#').
+     * Extract the arguments portion from an incoming raw message.
+     * @param incomming Raw incoming message string.
+     * @return The arguments portion of the incoming message.
+     */
     String getArgsFromIncomming(String incomming);
 
-    // Parse an incoming framed message and return the final check-bit
+    /**
-    // portion (everything after the second '#').
+     * Extract the check bit (checksum) portion from an incoming raw message.
+     * @param incomming Raw incoming message string.
+     * @return The check bit (as string) of the incoming message.
+     */
     String getCheckBitFromIncomming(String incomming);
 
-    // Verify that the provided `checkBit` matches the computed check for
+    /**
-    // the combination of `cmd` and `args`. Returns true when valid.
+     * Verify that the provided checkBit matches the computed checksum for cmd and args.
+     * @param cmd Command portion.
+     * @param args Arguments portion.
+     * @param checkBit Integer check bit to verify against.
+     * @return true if checksum matches, false otherwise.
+     */
     bool verifyCheckBit(String cmd, String args, int checkBit);
 
-    // Send a repeat request to the remote side to indicate the last
+    /**
-    // message should be re-sent.
+     * Send a repeat request to the other side.
+     * This will send the protocol message that instructs the peer to re-send.
+     */
     void repeat();
 
-    // Send an acknowledgement message containing `checkBit` back to the
+    /**
-    // remote side.
+     * Send an acknowledgement for a received message.
+     * @param checkBit Check bit value to include in the acknowledgement.
+     */
     void acknowledge(int checkBit);
 
-    // After sending a command, wait for and handle any follow-up messages
+    /**
-    // (repeat or acknowledgement) related to `cmd`.
+     * After sending a command, read for the peer's reply (ACKG or RPT) and act accordingly.
+     * @param cmd The full command string that was sent (including checksum and terminator).
+     */
     void afterSendCheck(String cmd);
 
 public:
+    /**
+     * Periodically called to process incoming serial data and dispatch events.
+     * Should be called frequently from the main loop.
+     */
     void cycle();
 
-    void onAcknowledge(void (*handler)(String args));
-    void onRepeat(void (*handler)(String args));
     void onCalibrationBegin(void (*handler)(String args));
     void onCalibrationInterupt(void (*handler)(String args));
 
+    /**
+     * Send a command using the defined protocol. The function composes the message,
+     * computes the checksum and sends the final string terminated with '@'.
+     * @param cmd Command name (e.g., "READ").
+     * @param args Arguments for the command.
+     */
     void sendCommand(String cmd, String args);
 };

src/main.cpp

@@ -2,8 +2,18 @@
 #include <serialConnector.h>
 
 SerialConnector *conn = new SerialConnector();
+
+/**
+ * Handler called when calibration begin/interrupt commands are received.
+ * Declared before setup so it can be registered as a callback.
+ * @param args Arguments string passed from the incoming command.
+ */
 void calibrationBegin(String args);
 
+/**
+ * Setup is called once when the Arduino boots.
+ * Configure pin modes, initialize Serial, and register callbacks here.
+ */
 void setup()
 {
     pinMode(11, OUTPUT);
@@ -19,6 +29,10 @@ void setup()
     conn->onCalibrationInterupt(&calibrationBegin);
 }
 
+/**
+ * Main loop called repeatedly by the Arduino runtime.
+ * It processes incoming serial messages and checks input pins to send commands.
+ */
 void loop()
 {
     conn->cycle();
@@ -41,6 +55,10 @@ void loop()
     delay(300);
 }
 
+/**
+ * Blink an output pin a number of times based on the provided argument.
+ * @param args A string containing a numeric value indicating how many blinks to perform.
+ */
 void calibrationBegin(String args)
 {
     for (int i = 0; i < args.toInt(); i++)

src/serialConnector.cpp

@@ -11,8 +11,10 @@
  *
  */
 
-// Main polling loop: read incoming serial frames, validate the check-bit,
+/**
-// acknowledge valid messages and dispatch handlers based on the command.
+ * Periodically called to process incoming serial data and dispatch events.
+ * Should be called frequently from the main loop.
+ */
 void SerialConnector::cycle()
 {
     if (Serial.available() > 3)
@@ -44,8 +46,11 @@ void SerialConnector::cycle()
     }
 }
 
-// Convert each character in `cmd` into its ASCII hexadecimal representation
+/**
-// and return the concatenated hex string. Example: "A" -> "41".
+ * Convert a string into its hexadecimal representation.
+ * @param cmd Input string to convert.
+ * @return Hexadecimal representation of the input string.
+ */
 String SerialConnector::stringToHex(String cmd)
 {
     int hex_dec;
@@ -83,9 +88,11 @@ String SerialConnector::stringToHex(String cmd)
     return output;
 }
 
-// Produce a numeric check value for `cmd` by converting characters to
+/**
-// their hexadecimal digits and summing their digit characters into an
+ * Convert a string into a numeric checksum used by the protocol.
-// integer representation. This mirrors the protocol used for check-bits.
+ * @param cmd Input string to convert.
+ * @return Integer checksum computed from the input string.
+ */
 int SerialConnector::stringToCheckNum(String cmd)
 {
     int hex_dec;
@@ -123,7 +130,12 @@ int SerialConnector::stringToCheckNum(String cmd)
     return output;
 }
 
-// Return the index of `ch` inside `str`. Returns -1 if `ch` is not found.
+/**
+ * Find the index of a character inside a string.
+ * @param ch Character to search for.
+ * @param str String to search within.
+ * @return Index of the character if found, -1 otherwise.
+ */
 int SerialConnector::getCharIndex(char ch, String str)
 {
     for (int i = 0; i < str.length(); i++)
@@ -135,16 +147,23 @@ int SerialConnector::getCharIndex(char ch, String str)
     return -1;
 }
 
-// Extract the command portion from an incoming framed message. The
+/**
-// protocol format is: <CMD>#<ARGS>#<CHECK>@ — this returns <CMD>.
+ * Extract the command portion from an incoming raw message.
+ * The message format is expected to be: CMD#ARGS#CHECK@ (terminator '@').
+ * @param incomming Raw incoming message string.
+ * @return The command portion of the incoming message.
+ */
 String SerialConnector::getCommandFromIncomming(String incomming)
 {
     int cmdEnd = getCharIndex('#', incomming);
     return incomming.substring(0, cmdEnd);
 }
 
-// Extract the arguments portion from an incoming message: returns the
+/**
-// text between the first and second '#' characters.
+ * Extract the arguments portion from an incoming raw message.
+ * @param incomming Raw incoming message string.
+ * @return The arguments portion of the incoming message.
+ */
 String SerialConnector::getArgsFromIncomming(String incomming)
 {
     int cmdEnd = getCharIndex('#', incomming);
@@ -155,8 +174,11 @@ String SerialConnector::getArgsFromIncomming(String incomming)
     return afterCmd.substring(0, cmdArgsEnd);
 }
 
-// Extract the check-bit (final field) from an incoming message: the text
+/**
-// after the second '#' character (up to the '@' frame terminator).
+ * Extract the check bit (checksum) portion from an incoming raw message.
+ * @param incomming Raw incoming message string.
+ * @return The check bit (as string) of the incoming message.
+ */
 String SerialConnector::getCheckBitFromIncomming(String incomming)
 {
     int cmdEnd = getCharIndex('#', incomming);
@@ -167,8 +189,13 @@ String SerialConnector::getCheckBitFromIncomming(String incomming)
     return afterCmd.substring(cmdArgsEnd + 1, afterCmd.length());
 }
 
-// Verify that `checkBit` equals the computed check for `<cmd>#<args>`.
+/**
-// Returns true when they match, false otherwise.
+ * Verify that the provided checkBit matches the computed checksum for cmd and args.
+ * @param cmd Command portion.
+ * @param args Arguments portion.
+ * @param checkBit Integer check bit to verify against.
+ * @return true if checksum matches, false otherwise.
+ */
 bool SerialConnector::verifyCheckBit(String cmd, String args, int checkBit)
 {
     String toCheck = cmd + "#" + args;
@@ -179,15 +206,20 @@ bool SerialConnector::verifyCheckBit(String cmd, String args, int checkBit)
         return false;
 }
 
-// Send a repeat (RPT) frame asking the remote to resend the last message.
+/**
+ * Send a repeat request to the other side.
+ * This will send the protocol message that instructs the peer to re-send.
+ */
 void SerialConnector::repeat()
 {
     String cmd = "RPT##410@";
     Serial.print(cmd);
 }
 
-// Send an acknowledgement (ACKG) frame that includes the original
+/**
-// command's check-bit so the sender can confirm delivery.
+ * Send an acknowledgement for a received message.
+ * @param checkBit Check bit value to include in the acknowledgement.
+ */
 void SerialConnector::acknowledge(int checkBit)
 {
     String cmd = "ACKG";
@@ -197,8 +229,12 @@ void SerialConnector::acknowledge(int checkBit)
     Serial.print(final);
 }
 
-// Build and send a framed command with `cmd` and `args`. Appends a computed
+/**
-// check-bit and frame terminator, then waits for follow-up (ack/repeat).
+ * Send a command using the defined protocol. The function composes the message,
+ * computes the checksum and sends the final string terminated with '@'.
+ * @param cmd Command name (e.g., "READ").
+ * @param args Arguments for the command.
+ */
 void SerialConnector::sendCommand(String cmd, String args)
 {
     String toSend = cmd + "#" + args;
@@ -209,9 +245,10 @@ void SerialConnector::sendCommand(String cmd, String args)
     afterSendCheck(final);
 }
 
-// After sending a command, read the next frame and handle either a
+/**
-// repeat (RPT) request or an acknowledgement (ACKG). For RPT, resend the
+ * After sending a command, read for the peer's reply (ACKG or RPT) and act accordingly.
-// original command. For ACKG, verify the returned check-bit matches.
+ * @param cmd The full command string that was sent (including checksum and terminator).
+ */
 void SerialConnector::afterSendCheck(String cmd)
 {
     String raw = Serial.readStringUntil('@');
@@ -239,29 +276,11 @@ void SerialConnector::afterSendCheck(String cmd)
     }
 }
 
-// Register a callback to be invoked when an acknowledgement frame is
-// received. The callback receives the acknowledgement's args string.
-void SerialConnector::onAcknowledge(void (*handler)(String args))
-{
-    acknowledgeHandler = handler;
-}
-
-// Register a callback to be invoked when a repeat (RPT) frame is
-// received. The handler receives the repeat frame's args.
-void SerialConnector::onRepeat(void (*handler)(String args))
-{
-    repeatHandler = handler;
-}
-
-// Register a callback for the 'CAL-BGN' command. The handler receives the
-// calibration arguments string when calibration begins.
 void SerialConnector::onCalibrationBegin(void (*handler)(String args))
 {
     calibrationBeginHandler = handler;
 }
 
-// Register a callback for the 'CAL-INT' command. The handler receives the
-// calibration interrupt arguments string when an interrupt occurs.
 void SerialConnector::onCalibrationInterupt(void (*handler)(String args))
 {
     calibrationInteruptHandler = handler;