#pragma once
#include <Arduino.h>

/**
 * @file serialConnector.h
 * @author Lyubomir Penev (me@lpenev.com)
 * @brief This file contains all the code to send and receive data over the the Arduino's serial port while ensuring complete data integrity
 * @version 1
 * @date 2026-01-25
 *
 * @copyright Copyright (c) 2026
 *
 */

class SerialConnector
{

private:
    String previouSent;
    String received;
    String command;

    void (*acknowledgeHandler)(String args);
    void (*repeatHandler)(String args);
    void (*calibrationBeginHandler)(String args);
    void (*calibrationInteruptHandler)(String args);

    /**
     * Convert a string into its hexadecimal representation.
     * @param cmd Input string to convert.
     * @return Hexadecimal representation of the input string.
     */
    String stringToHex(String cmd);

    /**
     * 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);

    /**
     * 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);

    /**
     * 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);

    /**
     * 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);

    /**
     * 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 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 other side.
     * This will send the protocol message that instructs the peer to re-send.
     */
    void repeat();

    /**
     * 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, 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 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);
};