kbf/include/kbf/uart.h

#ifndef KBF_UART_H
#define KBF_UART_H

#include <string>
#include <mutex>

#include <freertos/FreeRTOS.h>
#include <freertos/queue.h>

#include "task.h"

using std::string;

namespace kbf {
    /**
     * @brief Universal Asynchronous Receiver-Transmitter functions.
     */
    class UART {
    public:
        /** @brief Tag used for logging */
        static constexpr const char *TAG = "kbf::uart";

        /** @brief RX buffer size. */
        static constexpr const int BUFFER_SIZE = 2048; // TODO use Kconfig or provide runtime config option?

        /** @brief pass this to setPins to leave a pin unchanged */
        static constexpr const int NO_CHANGE = -1;

        /** @brief maximum number of RTOS ticks to wait in destructor for TX FIFO */
        static constexpr const int WAIT_ON_DESTROY = 100;

        /**
         * @brief Installs and initializes the UART driver and starts the event handler task.
         *
         * @note This function will abort if the driver has already been initialized. Use the #isDriverInstalled()
         * static function to check in advance
         *
         * @param port UART port to use; 0 is used for programming / logging, so you probably want >0; default is 1
         * @param baudRate Baud rate to use; default is 115200
         */
        explicit UART(int port = 1, int baudRate = 115200);

        /**
         * @brief Uninstalls the UART driver.
         *
         * @note May wait #WAIT_ON_DESTROY RTOS ticks for the TX FIFO to finish.
         */
        ~UART();

        /**
         * @brief Sets the GPIO pins used by UART for the current port.
         *
         * @param rx RX pin
         * @param tx TX pin
         * @param rts RTS pin
         * @param cts CTS pin
         */
        void setPins(int rx, int tx, int rts, int cts) const;

        /**
         * @brief Checks whether the UART driver is installed for a given port.
         *
         * @param port UART port to use; default is 1
         * @return true if the UART driver is already installed; false otherwise
         */
        static bool isDriverInstalled(int port = 1);

        /**
         * @brief Sends data.
         *
         * @param data data to be sent
         */
        void write(const string &data) const;

        /**
         * @brief Reads data, blocking execution.
         *
         * @note For filtering data, see #onRead(). It will be called before this function returns.
         *
         * @return read data
         */
        [[nodiscard]] string read();

        /**
         * @brief Called when data is received.
         *
         * @note This function will be called before #read() or #waitFor() returns, thus enabling
         * data filtering by modifying the contents of the first argument, &data.
         *
         * @param data data being read
         * @param uartInstance UART class instance
         */
        void (*onRead)(string &data, UART &uartInstance) = nullptr;

        /**
         * @brief Blocks execution until the specified signal is received.
         *
         * @note #onRead() will be called before this function returns.
         *
         * @param signal data to wait for
         */
        void waitFor(const string &signal);

        /** @brief UART port; default is 1 (set by ctor) */
        const int port;

    private:
        string     buffer{};
        std::mutex mutex;

        QueueHandle_t queue{};

        kbf::Task *task;

        [[noreturn]] static void taskFunc(void *uartInstance);

    };
}

#endif //KBF_UART_H