diff --git a/include/serialConnector.h b/include/serialConnector.h index 6c2c2e9..f7dedf5 100644 --- a/include/serialConnector.h +++ b/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). - // Returns an integer suitable for use as a check-bit value. + /** + * Convert a string into a numeric checksum used by the protocol. + * @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); }; \ No newline at end of file diff --git a/src/main.cpp b/src/main.cpp index 8e74fa0..7db3e1b 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -2,8 +2,18 @@ #include 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++) diff --git a/src/serialConnector.cpp b/src/serialConnector.cpp index 699f25c..18c9b3d 100644 --- a/src/serialConnector.cpp +++ b/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 -// integer representation. This mirrors the protocol used for check-bits. +/** + * Convert a string into a numeric checksum used by the protocol. + * @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: ##@ — this returns . +/** + * 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 `#`. -// 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 -// original command. For ACKG, verify the returned check-bit matches. +/** + * 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 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;