diff --git a/sdk/librishka.h b/sdk/librishka.h index f11e7d0..912eddb 100644 --- a/sdk/librishka.h +++ b/sdk/librishka.h @@ -15,18 +15,37 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ +/** + * @file librishka.h + * @author [Nathanne Isip](https://github.com/nthnn) + * @brief Main header file for the Rishka SDK. + * + * This header file includes all the necessary headers from the Rishka SDK + * for easy integration and usage of Rishka functionalities in your projects. + */ + #ifndef LIBRISHKA_H #define LIBRISHKA_H -#include <librishka/args.h> -#include <librishka/fs.h> -#include <librishka/gpio.h> -#include <librishka/i2c.h> -#include <librishka/int.h> -#include <librishka/io.h> -#include <librishka/memory.h> -#include <librishka/spi.h> -#include <librishka/sys.h> -#include <librishka/types.h> +/** + * @defgroup Rishka_SDK Rishka SDK + * @brief Rishka SDK provides a collection of headers for accessing various + * functionalities on ESP32-WROVER microcontrollers. + * + * The Rishka SDK includes headers for GPIO, filesystem, I2C, SPI, interrupts, + * system calls, and other essential components for developing applications + * on the Rishka platform. + */ + +#include <librishka/args.h> /**< @ingroup Rishka_SDK */ +#include <librishka/fs.h> /**< @ingroup Rishka_SDK */ +#include <librishka/gpio.h> /**< @ingroup Rishka_SDK */ +#include <librishka/i2c.h> /**< @ingroup Rishka_SDK */ +#include <librishka/int.h> /**< @ingroup Rishka_SDK */ +#include <librishka/io.h> /**< @ingroup Rishka_SDK */ +#include <librishka/memory.h> /**< @ingroup Rishka_SDK */ +#include <librishka/spi.h> /**< @ingroup Rishka_SDK */ +#include <librishka/sys.h> /**< @ingroup Rishka_SDK */ +#include <librishka/types.h> /**< @ingroup Rishka_SDK */ -#endif \ No newline at end of file +#endif /* LIBRISHKA_H */ \ No newline at end of file diff --git a/sdk/librishka/args.h b/sdk/librishka/args.h index 91f9505..c31e2d8 100644 --- a/sdk/librishka/args.h +++ b/sdk/librishka/args.h @@ -15,15 +15,50 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ +/** + * @file args.h + * @author [Nathanne Isip](https://github.com/nthnn) + * @brief Header file for handling command line arguments in Rishka applications. + * + * This header file defines the Args class, which provides functionalities + * for accessing and handling command line arguments passed to Rishka applications. + */ + #ifndef LIBRISHKA_ARGS_H #define LIBRISHKA_ARGS_H #include <librishka/types.h> +/** + * @class Args + * @brief Class for handling command line arguments in Rishka applications. + * + * The Args class provides static methods for accessing command line arguments + * passed to the Rishka application. It allows developers to retrieve the number + * of command line arguments and obtain the values of individual arguments. + */ class Args final { public: + /** + * @brief Get the number of command line arguments. + * + * This method returns the total number of command line arguments passed + * to the Rishka application. + * + * @return The number of command line arguments. + */ static i32 count(); + + /** + * @brief Get the value of a command line argument at a specific index. + * + * This method retrieves the value of a command line argument at the specified + * index. The index should be within the range [0, count() - 1]. + * + * @param index The index of the command line argument. + * @return The value of the command line argument at the specified index. + */ static string value(u8 index); }; -#endif \ No newline at end of file +#endif /* LIBRISHKA_ARGS_H */ \ No newline at end of file diff --git a/sdk/librishka/fs.h b/sdk/librishka/fs.h index 3af4135..2d18987 100644 --- a/sdk/librishka/fs.h +++ b/sdk/librishka/fs.h @@ -15,55 +15,280 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ +/** + * @file fs.h + * @author [Nathanne Isip](https://github.com/nthnn) + * @brief Header file for file system operations in Rishka applications. + * + * This header file defines the File and FS classes, which provide functionalities + * for interacting with files and directories in the file system on ESP32-WROVER microcontrollers. + */ + #ifndef LIBRISHKA_FS_H #define LIBRISHKA_FS_H #include <librishka/types.h> +/** + * @class File + * @brief Class for handling file operations in Rishka applications. + * + * The File class provides methods for performing various file operations, + * such as opening, reading, writing, and closing files. It also includes + * functionalities for file navigation and querying file attributes. + */ class File final { private: - i32 handle; + i32 handle; /**< File handle for accessing file operations */ protected: - File(i32 _handle); + File(i32 _handle); /**< Protected constructor for creating a file object */ public: + /** + * @brief Open a file with the specified name and mode. + * + * This method opens a file with the given name and mode. The mode + * parameter specifies the access mode for the file (e.g., "r" for reading, + * "w" for writing). + * + * @param file The name of the file to open. + * @param mode The mode in which to open the file (e.g., "r" for reading, "w" for writing). + * @return A File object representing the opened file. + */ static File open(string file, string mode); + /** + * @brief Check if the object represents a file. + * + * This method checks whether the File object represents a file. + * + * @return True if the object represents a file, false otherwise. + */ bool is_file(); + + /** + * @brief Check if the object represents a directory. + * + * This method checks whether the File object represents a directory. + * + * @return True if the object represents a directory, false otherwise. + */ bool is_dir(); + /** + * @brief Check if the object represents a directory. + * + * This method checks whether the File object represents a directory. + * + * @return True if the object represents a directory, false otherwise. + */ i32 available(); + + /** + * @brief Peek at the next byte in the file without consuming it. + * + * This method peeks at the next byte in the file without consuming it. + * + * @return The next byte in the file, or -1 if the end of the file is reached. + */ i32 peek(); + + /** + * @brief Get the timestamp of the last write operation on the file. + * + * This method returns the timestamp of the last write operation performed on the file. + * + * @return The timestamp of the last write operation. + */ u64 lastwrite(); + + /** + * @brief Set the buffer size for the file. + * + * This method sets the buffer size for the file. It determines the + * amount of data buffered in memory before being written to the file. + * + * @param size The buffer size to set, in bytes. + * @return True if the buffer size was successfully set, false otherwise. + */ bool bufsize(usize size); + + /** + * @brief Set the current position within the file. + * + * This method sets the current position within the file to the specified position. + * + * @param pos The position to set. + * @return True if the position was successfully set, false otherwise. + */ bool seek(u32 pos); + + /** + * @brief Set the current position within the directory. + * + * This method sets the current position within the directory to the specified position. + * + * @param position The position to set. + * @return True if the position was successfully set, false otherwise. + */ bool seek_dir(u64 position); + /** + * @brief Get the size of the file. + * + * This method returns the size of the file. + * + * @return The size of the file, in bytes. + */ usize size(); + + /** + * @brief Get the current position within the file. + * + * This method returns the current position within the file. + * + * @return The current position within the file. + */ usize position(); + /** + * @brief Read a byte from the file. + * + * This method reads a byte from the file and advances the file pointer. + * + * @return The byte read from the file, or -1 if the end of the file is reached. + */ i32 read(); + + /** + * @brief Write a byte to the file. + * + * This method writes a byte to the file at the current position. + * + * @param data The byte to write to the file. + */ void write(u8 data); + + /** + * @brief Write a string to the file. + * + * This method writes a string to the file at the current position. + * + * @param data The string to write to the file. + */ void write(string data); + /** + * @brief Get the path of the file. + * + * This method returns the path of the file. + * + * @return The path of the file. + */ string path(); + + /** + * @brief Get the name of the file. + * + * This method returns the name of the file. + * + * @return The name of the file. + */ string name(); + /** + * @brief Get the next file in the directory. + * + * This method returns the next file in the directory and advances + * the directory pointer. The mode parameter specifies the mode in + * which to open the next file (e.g., "r" for reading, "w" for writing). + * + * @param mode The mode in which to open the next file (e.g., "r" for reading, "w" for writing). + * @return A File object representing the next file in the directory. + */ File next(string mode); + + /** + * @brief Get the name of the next file in the directory. + * + * This method returns the name of the next file in the directory + * without advancing the directory pointer. + * + * @return The name of the next file in the directory. + */ string next_name(); + /** + * @brief Flush the file buffer. + * + * This method flushes the file buffer, writing any buffered data to the file. + */ void flush(); + + /** + * @brief Close the file. + * + * This method closes the file, releasing any associated resources. + */ void close(); + + /** + * @brief Rewind the file pointer to the beginning of the file. + * + * This method rewinds the file pointer to the beginning of the file. + */ void rewind(); }; +/** + * @class FS + * @brief Class for file system operations in Rishka applications. + * + * The FS class provides static methods for performing file system operations, + * such as creating, deleting, and checking the existence of directories and files. + */ class FS final { public: + /** + * @brief Create a directory with the specified path. + * + * This method creates a directory with the given path. + * + * @param path The path of the directory to create. + * @return True if the directory was successfully created, false otherwise. + */ static bool mkdir(const char* path); + + /** + * @brief Remove a directory with the specified path. + * + * This method removes a directory with the given path. + * + * @param path The path of the directory to remove. + * @return True if the directory was successfully removed, false otherwise. + */ static bool rmdir(const char* path); + + /** + * @brief Remove a file with the specified path. + * + * This method removes a file with the given path. + * + * @param path The path of the file to remove. + * @return True if the file was successfully removed, false otherwise. + */ static bool remove(const char* path); + + /** + * @brief Check if a file or directory exists at the specified path. + * + * This method checks if a file or directory exists at the given path. + * + * @param path The path to check. + * @return True if a file or directory exists at the specified path, false otherwise. + */ static bool exists(const char* path); }; -#endif \ No newline at end of file +#endif /* LIBRISHKA_FS_H */ \ No newline at end of file diff --git a/sdk/librishka/gpio.h b/sdk/librishka/gpio.h index 17fcd38..bbd22fe 100644 --- a/sdk/librishka/gpio.h +++ b/sdk/librishka/gpio.h @@ -15,40 +15,179 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ +/** + * @file gpio.h + * @author [Nathanne Isip](https://github.com/nthnn) + * @brief Header file for GPIO operations in Rishka applications. + * + * This header file defines the Gpio class, which provides functionalities + * for interacting with General Purpose Input/Output (GPIO) pins on ESP32-WROVER microcontrollers. + */ + #ifndef LIBRISHKA_GPIO_H #define LIBRISHKA_GPIO_H #include <librishka/types.h> +/** + * @brief Enum representing the pin modes for GPIO pins. + * + * This enum specifies the available pin modes for configuring GPIO pins. + * - GPIO_INPUT: Configures the pin as an input. + * - GPIO_OUTPUT: Configures the pin as an output. + * - GPIO_INPUT_PULLUP: Configures the pin as an input with a pull-up resistor enabled. + */ typedef enum { - GPIO_INPUT = 0x01, - GPIO_OUTPUT = 0x03, - GPIO_INPUT_PULLUP = 0x05 + GPIO_INPUT = 0x01, /**< Input mode */ + GPIO_OUTPUT = 0x03, /**< Output mode */ + GPIO_INPUT_PULLUP = 0x05 /**< Input mode with pull-up resistor */ } gpio_pin_mode_t; +/** + * @brief Enum representing the digital modes for GPIO pins. + * + * This enum specifies the digital modes for GPIO pins. + * - GPIO_LOW: Represents a low digital value (0). + * - GPIO_HIGH: Represents a high digital value (1). + */ typedef enum { - GPIO_LOW = 0x0, - GPIO_HIGH = 0x1 + GPIO_LOW = 0x0, /**< Low digital value */ + GPIO_HIGH = 0x1 /**< High digital value */ } gpio_mode_t; +/** + * @class Gpio + * @brief Class for handling GPIO operations in Rishka applications. + * + * The Gpio class provides static methods for configuring and manipulating + * General Purpose Input/Output (GPIO) pins on ESP32-WROVER microcontrollers. + * It includes functionalities for setting pin modes, reading digital and analog + * values, generating pulses, and controlling digital communication protocols. + */ class Gpio final { public: + /** + * @brief Set the mode of a GPIO pin. + * + * This method sets the mode of the specified GPIO pin to the given mode. + * + * @param pin The GPIO pin number. + * @param mode The mode to set for the GPIO pin (GPIO_INPUT, GPIO_OUTPUT, or GPIO_INPUT_PULLUP). + */ static void pin_mode(u8 pin, gpio_pin_mode_t mode); + /** + * @brief Read the digital value of a GPIO pin. + * + * This method reads the digital value (LOW or HIGH) of the specified GPIO pin. + * + * @param pin The GPIO pin number. + * @return The digital value of the GPIO pin (0 for LOW, 1 for HIGH). + */ static i32 digital_read(u8 pin); + + /** + * @brief Write a digital value to a GPIO pin. + * + * This method writes the digital value (LOW or HIGH) to the specified GPIO pin. + * + * @param pin The GPIO pin number. + * @param mode The digital value to write to the GPIO pin (GPIO_LOW or GPIO_HIGH). + */ static void digital_write(u8 pin, gpio_mode_t mode); + /** + * @brief Read the analog value of a GPIO pin. + * + * This method reads the analog value (0-1023) of the specified GPIO pin. + * + * @param pin The GPIO pin number. + * @return The analog value of the GPIO pin (0-1023). + */ static i32 analog_read(u8 pin); + + /** + * @brief Write an analog value to a GPIO pin. + * + * This method writes the analog value (0-255) to the specified GPIO pin. + * + * @param pin The GPIO pin number. + * @param value The analog value to write to the GPIO pin (0-255). + */ static void analog_write(u8 pin, u8 value); + /** + * @brief Measure the duration of a pulse on a GPIO pin. + * + * This method measures the duration of a pulse of the specified state (HIGH or LOW) + * on the specified GPIO pin, with the specified timeout in microseconds. + * + * @param pin The GPIO pin number. + * @param state The state of the pulse to measure (GPIO_LOW or GPIO_HIGH). + * @param timeout The timeout in microseconds. + * @return The duration of the pulse in microseconds, or 0 if the timeout occurred. + */ static u64 pulse_in(u8 pin, u8 state, u64 timeout); + + /** + * @brief Measure the duration of a long pulse on a GPIO pin. + * + * This method measures the duration of a long pulse of the specified state (HIGH or LOW) + * on the specified GPIO pin, with the specified timeout in microseconds. + * + * @param pin The GPIO pin number. + * @param state The state of the pulse to measure (GPIO_LOW or GPIO_HIGH). + * @param timeout The timeout in microseconds. + * @return The duration of the long pulse in microseconds, or 0 if the timeout occurred. + */ static u64 pulse_in_long(u8 pin, u8 state, u64 timeout); + /** + * @brief Shift in data from a digital input pin. + * + * This method shifts in data from a digital input pin using the specified clock pin + * and bit order (LSBFIRST or MSBFIRST). + * + * @param data The digital input pin number. + * @param clock The clock pin number. + * @param bit_order The bit order (LSBFIRST or MSBFIRST). + * @return The shifted-in data byte. + */ static u8 shift_in(u8 data, u8 clock, u8 bit_order); + + /** + * @brief Shift out data to a digital output pin. + * + * This method shifts out data to a digital output pin using the specified clock pin, + * bit order (LSBFIRST or MSBFIRST), and data value. + * + * @param data The digital output pin number. + * @param clock The clock pin number. + * @param bit_order The bit order (LSBFIRST or MSBFIRST). + * @param value The data value to shift out. + */ static void shift_out(u8 data, u8 clock, u8 bit_order, u8 value); + /** + * @brief Generate a tone of the specified frequency and duration on a GPIO pin. + * + * This method generates a tone of the specified frequency and duration on the + * specified GPIO pin using pulse-width modulation (PWM). + * + * @param pin The GPIO pin number. + * @param frequency The frequency of the tone in Hertz (Hz). + * @param duration The duration of the tone in microseconds (0 for continuous). + */ static void tone(u8 pin, u32 frequency, u64 duration); + + /** + * @brief Stop generating a tone on a GPIO pin. + * + * This method stops generating a tone on the specified GPIO pin. + * + * @param pin The GPIO pin number. + */ static void no_tone(u8 pin); }; -#endif \ No newline at end of file +#endif /* LIBRISHKA_GPIO_H */ \ No newline at end of file diff --git a/sdk/librishka/i2c.h b/sdk/librishka/i2c.h index a306d2a..bfc5cfc 100644 --- a/sdk/librishka/i2c.h +++ b/sdk/librishka/i2c.h @@ -15,38 +15,232 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ +/** + * @file i2c.h + * @author [Nathanne Isip](https://github.com/nthnn) + * @brief Header file for I2C (Inter-Integrated Circuit) operations in Rishka applications. + * + * This header file defines the I2C class, which provides functionalities + * for communicating with I2C devices on ESP32-WROVER microcontrollers. + */ + #ifndef LIBRISHKA_I2C_H #define LIBRISHKA_I2C_H #include <librishka/types.h> +/** + * @class I2C + * @brief Class for handling I2C operations in Rishka applications. + * + * The I2C class provides static methods for initializing, configuring, and + * communicating with I2C devices on ESP32-WROVER microcontrollers. It includes + * functionalities for setting up the I2C bus, beginning and ending I2C transactions, + * reading and writing data, registering callbacks for I2C events, and setting the clock + * frequency and timeout. + */ class I2C final { public: + /** + * @brief Initialize the I2C communication with the specified address. + * + * This method initializes the I2C communication with the specified 7-bit address. + * It should be called before any other I2C communication functions are used. + * + * @param address The 7-bit address of the I2C device. + * @return True if initialization was successful, false otherwise. + */ static bool begin(u8 address); + + /** + * @brief End the I2C communication. + * + * This method ends the I2C communication and releases the associated resources. + * It should be called to clean up the I2C interface after use. + * + * @return True if ending the communication was successful, false otherwise. + */ static bool end(); + + /** + * @brief Set the SDA and SCL pins for the I2C communication. + * + * This method sets the SDA (data) and SCL (clock) pins for the I2C communication. + * It should be called to configure the GPIO pins used for I2C communication. + * + * @param sda The pin number for the SDA (data) line. + * @param scl The pin number for the SCL (clock) line. + * @return True if setting the pins was successful, false otherwise. + */ static bool pins(u8 sda, u8 scl); + + /** + * @brief Flush the I2C buffer. + * + * This method flushes the I2C buffer, discarding any unread data. + * It can be called to clear the buffer before initiating a new transaction. + */ static void flush(); + /** + * @brief Begin an I2C transmission to the specified device address. + * + * This method begins an I2C transmission to the specified device address. + * Subsequent write operations will send data to the specified device. + * + * @param address The 7-bit address of the I2C device. + */ static void begin_transmission(u8 address); + + /** + * @brief End an I2C transmission with an optional stop bit. + * + * This method ends an I2C transmission with an optional stop bit. + * If the stop_bit parameter is true, a stop condition will be generated + * on the bus after the transmission is complete. + * + * @param stop_bit True to generate a stop condition, false otherwise. + * @return The status of the transmission (0 for success, non-zero for error). + */ static u8 end_transmission(bool stop_bit); + /** + * @brief Write data to the I2C bus. + * + * This method writes data to the I2C bus for transmission to the device + * specified in the begin_transmission() method. + * + * @param data Pointer to the data buffer. + * @param size The number of bytes to write. + * @return The number of bytes written. + */ static usize write(u8* data, usize size); + + /** + * @brief Write data to the I2C bus as a slave device. + * + * This method writes data to the I2C bus as a slave device. + * It is typically used in response to a master device's request. + * + * @param data Pointer to the data buffer. + * @param size The number of bytes to write. + * @return The number of bytes written. + */ static usize slave_write(u8* data, usize size); + + /** + * @brief Set the buffer size for I2C transactions. + * + * This method sets the buffer size for I2C transactions. + * It should be called before beginning an I2C transmission. + * + * @param size The buffer size in bytes. + * @return True if setting the buffer size was successful, false otherwise. + */ static usize set_buffersize(usize size); + /** + * @brief Read data from the I2C bus. + * + * This method reads data from the I2C bus received from the device + * specified in the begin_transmission() method. + * + * @return The received data byte. + */ static i32 read(); + + /** + * @brief Peek at the next byte on the I2C bus. + * + * This method peeks at the next byte on the I2C bus without removing it + * from the buffer. It is useful for checking if data is available for reading. + * + * @return The next byte on the I2C bus, or -1 if no data is available. + */ static i32 peek(); + + /** + * @brief Get the number of bytes available for reading on the I2C bus. + * + * This method returns the number of bytes available for reading on the I2C bus. + * It can be used to determine the amount of data available for reading. + * + * @return The number of bytes available for reading. + */ static i32 available(); + /** + * @brief Request data from a remote I2C device. + * + * This method requests data from a remote I2C device with the specified address + * and size, optionally generating a stop condition after the request. + * + * @param address The 7-bit address of the remote I2C device. + * @param size The number of bytes to request. + * @param stop_bit True to generate a stop condition after the request, false otherwise. + * @return The number of bytes requested. + */ static usize request(u8 address, usize size, bool stop_bit); + + /** + * @brief Register a callback function for I2C receive events. + * + * This method registers a callback function to be called when data is received + * on the I2C bus as a slave device. The callback function should take an integer + * parameter representing the number of bytes received. + * + * @param callback Pointer to the callback function. + */ static void on_receive(void (*callback)(int)); + + /** + * @brief Register a callback function for I2C request events. + * + * This method registers a callback function to be called when a master device + * requests data from the I2C slave device. The callback function should not + * take any parameters. + * + * @param callback Pointer to the callback function. + */ static void on_request(void (*callback)(void)); + /** + * @brief Set the timeout for I2C operations. + * + * This method sets the timeout for I2C operations in microseconds. + * It specifies the maximum time allowed for an I2C operation to complete. + * + * @param timeout The timeout value in microseconds. + */ static void set_timeout(u16 timeout); + + /** + * @brief Get the current timeout for I2C operations. + * + * This method returns the current timeout for I2C operations in microseconds. + * + * @return The current timeout value in microseconds. + */ static u16 get_timeout(); + /** + * @brief Set the clock frequency for I2C communication. + * + * This method sets the clock frequency for I2C communication in Hertz (Hz). + * + * @param clock The clock frequency in Hertz (Hz). + * @return True if setting the clock frequency was successful, false otherwise. + */ static bool set_clock(u32 clock); + + /** + * @brief Get the current clock frequency for I2C communication. + * + * This method returns the current clock frequency for I2C communication in Hertz (Hz). + * + * @return The current clock frequency in Hertz (Hz). + */ static u32 get_clock(); }; -#endif \ No newline at end of file +#endif /* LIBRISHKA_I2C_H */ \ No newline at end of file diff --git a/sdk/librishka/int.h b/sdk/librishka/int.h index f925394..2c04478 100644 --- a/sdk/librishka/int.h +++ b/sdk/librishka/int.h @@ -15,24 +15,79 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ +/** + * @file int.h + * @author [Nathanne Isip](https://github.com/nthnn) + * @brief Header file for interrupt handling in Rishka applications. + * + * This header file defines the Int class, which provides functionalities + * for managing interrupts on ESP32-WROVER microcontrollers. + */ + #ifndef LIBRISHKA_INT_H #define LIBRISHKA_INT_H #include <librishka/types.h> +/** + * @brief Enum representing interrupt modes for GPIO pins. + * + * This enum specifies the interrupt modes available for configuring GPIO pin interrupts. + * - INT_CHANGE: Interrupt triggered on pin state change. + * - INT_FAILING: Interrupt triggered on falling edge. + * - INT_RISING: Interrupt triggered on rising edge. + */ typedef enum { - INT_CHANGE = 0x1, - INT_FAILING = 0x2, - INT_RISING = 0x3 + INT_CHANGE = 0x1, /**< Interrupt triggered on pin state change */ + INT_FAILING = 0x2, /**< Interrupt triggered on falling edge */ + INT_RISING = 0x3 /**< Interrupt triggered on rising edge */ } int_mode_t; +/** + * @class Int + * @brief Class for handling interrupt operations in Rishka applications. + * + * The Int class provides static methods for enabling/disabling interrupts, + * attaching/detaching interrupt handlers, and configuring interrupt modes + * for GPIO pins on ESP32-WROVER microcontrollers. + */ class Int final { public: + /** + * @brief Enable interrupts globally. + * + * This method enables interrupts globally, allowing interrupt handlers to be called. + */ static void enable(); + + /** + * @brief Disable interrupts globally. + * + * This method disables interrupts globally, preventing interrupt handlers from being called. + */ static void disable(); + /** + * @brief Attach an interrupt handler to a GPIO pin. + * + * This method attaches an interrupt handler function to the specified GPIO pin. + * The interrupt handler will be called when the specified interrupt mode is triggered. + * + * @param pin The GPIO pin number. + * @param callback Pointer to the interrupt handler function. + * @param mode The interrupt mode (INT_CHANGE, INT_FAILING, or INT_RISING). + */ static void attach(u8 pin, void (*callback)(void), int_mode_t mode); + + /** + * @brief Detach the interrupt handler from a GPIO pin. + * + * This method detaches the interrupt handler function from the specified GPIO pin. + * The interrupt handler will no longer be called for interrupts on the specified pin. + * + * @param pin The GPIO pin number. + */ static void detach(u8 pin); }; -#endif \ No newline at end of file +#endif /* LIBRISHKA_INT_H */ \ No newline at end of file diff --git a/sdk/librishka/io.h b/sdk/librishka/io.h index b74f9f5..ba58a8d 100644 --- a/sdk/librishka/io.h +++ b/sdk/librishka/io.h @@ -15,29 +15,142 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ +/** + * @file io.h + * @author [Nathanne Isip](https://github.com/nthnn) + * @brief Header file for input/output operations in Rishka applications. + * + * This header file defines the IO class, which provides functionalities + * for input/output operations on ESP32-WROVER microcontrollers. + */ + #ifndef LIBRISHKA_IO_H #define LIBRISHKA_IO_H #include <librishka/types.h> +/** + * @class IO + * @brief Class for handling input/output operations in Rishka applications. + * + * The IO class provides static methods for performing input/output operations, + * such as printing text and numbers, reading input, searching for patterns, + * and setting timeouts for input operations on ESP32-WROVER microcontrollers. + */ class IO final { public: + /** + * @brief Print text to the output stream. + * + * This method prints the specified text to the output stream. + * + * @param text The text to be printed. + */ static void print(const string text); + + /** + * @brief Print an integer number to the output stream. + * + * This method prints the specified integer number to the output stream. + * + * @param number The integer number to be printed. + */ static void print(i64 number); + + /** + * @brief Print a floating-point number to the output stream. + * + * This method prints the specified floating-point number to the output stream. + * + * @param number The floating-point number to be printed. + */ static void print(double number); + /** + * @brief Read a character from the input stream. + * + * This method reads a character from the input stream. + * + * @return The character read from the input stream. + */ static i32 read(); + + /** + * @brief Check if there is data available to read from the input stream. + * + * This method checks if there is data available to read from the input stream. + * + * @return The number of bytes available to read, or 0 if no data is available. + */ static i32 available(); + + /** + * @brief Peek at the next character in the input stream. + * + * This method peeks at the next character in the input stream without removing it. + * + * @return The next character in the input stream, or -1 if no data is available. + */ static i32 peek(); + /** + * @brief Search for a target string in the input stream. + * + * This method searches for the specified target string in the input stream. + * + * @param target The target string to search for. + * @param size The size of the target string. + * @return True if the target string is found, false otherwise. + */ static bool find(string target, usize size); + + /** + * @brief Search for a target string in the input stream until a terminator is encountered. + * + * This method searches for the specified target string in the input stream until + * the specified terminator string is encountered. + * + * @param target The target string to search for. + * @param terminator The terminator string. + * @return True if the target string is found before the terminator, false otherwise. + */ static bool find_until(string target, string terminator); + /** + * @brief Set the timeout for input operations. + * + * This method sets the timeout for input operations in microseconds. + * + * @param timeout The timeout value in microseconds. + */ static void set_timeout(u64 timeout); + + /** + * @brief Get the current timeout for input operations. + * + * This method returns the current timeout for input operations in microseconds. + * + * @return The current timeout value in microseconds. + */ static u64 get_timeout(); + /** + * @brief Read a Unicode character from the input stream. + * + * This method reads a Unicode character from the input stream. + * + * @return The Unicode character read from the input stream. + */ static rune readch(); + + /** + * @brief Read a line of text from the input stream. + * + * This method reads a line of text from the input stream. + * + * @return The line of text read from the input stream. + */ static string readline(); }; -#endif \ No newline at end of file +#endif /* LIBRISHKA_IO_H */ \ No newline at end of file diff --git a/sdk/librishka/memory.h b/sdk/librishka/memory.h index 9f32f68..501606a 100644 --- a/sdk/librishka/memory.h +++ b/sdk/librishka/memory.h @@ -15,18 +15,82 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ +/** + * @file memory.h + * @author [Nathanne Isip](https://github.com/nthnn) + * @brief Header file for memory management in Rishka applications. + * + * This header file defines the Memory class, which provides functionalities + * for dynamic memory management on ESP32-WROVER microcontrollers. + */ + #ifndef LIBRISHKA_MEM_H #define LIBRISHKA_MEM_H #include <librishka/types.h> +/** + * @class Memory + * @brief Class for handling memory management operations in Rishka applications. + * + * The Memory class provides static methods for allocating, reallocating, and freeing memory, + * as well as functions for setting memory values on ESP32-WROVER microcontrollers. + */ class Memory final { public: + /** + * @brief Allocate memory. + * + * This method allocates a block of memory of the specified size. + * + * @param dest Pointer to the destination memory block. + * @param size The size of the memory block to allocate in bytes. + */ static void alloc(any dest, usize size); + + /** + * @brief Allocate and clear memory. + * + * This method allocates a block of memory of the specified size and initializes it to zero. + * + * @param dest Pointer to the destination memory block. + * @param num The number of elements in the memory block. + * @param size The size of each element in bytes. + */ static void calloc(any dest, usize num, usize size); + + /** + * @brief Reallocate memory. + * + * This method reallocates a block of memory to the specified size. + * + * @param dest Pointer to the destination memory block. + * @param ptr Pointer to the previously allocated memory block. + * @param size The new size of the memory block in bytes. + */ static void realloc(any dest, any ptr, usize size); + + + /** + * @brief Free memory. + * + * This method frees the memory block previously allocated by alloc, calloc, or realloc. + * + * @param ptr Pointer to the memory block to free. + */ static void free(any ptr); + + /** + * @brief Set memory values. + * + * This method sets the first n bytes of the memory block pointed to by dest to the specified value. + * + * @param dest Pointer to the destination memory block. + * @param c The value to set. + * @param n The number of bytes to set. + * @return Pointer to the memory block. + */ static any set(any dest, i32 c, usize n); }; -#endif \ No newline at end of file +#endif /* LIBRISHKA_MEM_H */ \ No newline at end of file diff --git a/sdk/librishka/spi.h b/sdk/librishka/spi.h index d01e10c..43240b1 100644 --- a/sdk/librishka/spi.h +++ b/sdk/librishka/spi.h @@ -15,41 +15,244 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ +/** + * @file spi.h + * @author [Nathanne Isip](https://github.com/nthnn) + * @brief Header file for SPI (Serial Peripheral Interface) communication in Rishka applications. + * + * This header file defines the SPI class, which provides functionalities + * for SPI communication on ESP32-WROVER microcontrollers. + */ + #ifndef LIBRISHKA_SPI_H #define LIBRISHKA_SPI_H #include <librishka/types.h> +/** + * @enum spi_mode_t + * @brief Enumeration for SPI data modes. + * + * The spi_mode_t enumeration defines different SPI data modes + * that control the clock polarity and phase during SPI communication. + */ +typedef enum { + SPI_MODE0 = 0x00, /**< Clock polarity (CPOL) = 0, Clock phase (CPHA) = 0 */ + SPI_MODE1 = 0x01, /**< Clock polarity (CPOL) = 0, Clock phase (CPHA) = 1 */ + SPI_MODE2 = 0x02, /**< Clock polarity (CPOL) = 1, Clock phase (CPHA) = 0 */ + SPI_MODE3 = 0x03 /**< Clock polarity (CPOL) = 1, Clock phase (CPHA) = 1 */ +} spi_mode_t; + +/** + * @class SPI + * @brief Class for handling SPI communication in Rishka applications. + * + * The SPI class provides static methods for initializing SPI communication, + * transferring data over SPI, and configuring SPI parameters on ESP32-WROVER microcontrollers. + */ class SPI final { public: + /** + * @brief Initialize SPI communication. + * + * This method initializes SPI communication with the specified pins. + * + * @param sck The pin number for the SPI clock (SCK). + * @param miso The pin number for the SPI Master In Slave Out (MISO) line. + * @param mosi The pin number for the SPI Master Out Slave In (MOSI) line. + * @param ss The pin number for the Slave Select (SS) line. + */ static void begin(u8 sck, u8 miso, u8 mosi, u8 ss); + + /** + * @brief End SPI communication. + * + * This method ends SPI communication and releases the SPI resources. + */ static void end(); - static void begin_transaction(u8 clock, u8 bit_order, u8 data_mode); + /** + * @brief Begin a SPI transaction. + * + * This method begins a SPI transaction with the specified clock frequency, + * bit order, and data mode. + * + * @param clock The clock frequency for the SPI transaction. + * @param bit_order The bit order for the SPI transaction (MSBFIRST or LSBFIRST). + * @param data_mode The data mode for the SPI transaction (SPI_MODE0, SPI_MODE1, SPI_MODE2, or SPI_MODE3). + */ + static void begin_transaction(u8 clock, u8 bit_order, spi_mode_t data_mode); + + /** + * @brief End a SPI transaction. + * + * This method ends the current SPI transaction. + */ static void end_transaction(); + /** + * @brief Transfer an 8-bit data over SPI. + * + * This method transfers an 8-bit data over SPI and returns the received data. + * + * @param data The 8-bit data to be transferred. + * @return The received 8-bit data. + */ static u8 transfer8(u8 data); + + /** + * @brief Transfer a 16-bit data over SPI. + * + * This method transfers a 16-bit data over SPI and returns the received data. + * + * @param data The 16-bit data to be transferred. + * @return The received 16-bit data. + */ static u16 transfer16(u16 data); + + /** + * @brief Transfer a 32-bit data over SPI. + * + * This method transfers a 32-bit data over SPI and returns the received data. + * + * @param data The 32-bit data to be transferred. + * @return The received 32-bit data. + */ static u32 transfer32(u32 data); + /** + * @brief Transfer data bytes over SPI. + * + * This method transfers a specified number of bytes of data over SPI. + * + * @param data Pointer to the data buffer to be transferred. + * @param out Pointer to the output buffer to store received data. + * @param size The number of bytes to transfer. + */ static void transfer_bytes(u8* data, u8* out, u32 size); + + /** + * @brief Transfer bits over SPI. + * + * This method transfers a specified number of bits of data over SPI. + * + * @param data The data to be transferred. + * @param out Pointer to the output buffer to store received data. + * @param bits The number of bits to transfer. + */ static void transfer_bits(u32 data, u32* out, u8 bits); + /** + * @brief Set the hardware chip select (CS) pin usage. + * + * This method enables or disables the use of hardware chip select (CS) pin. + * + * @param use True to enable hardware CS, false to disable. + */ static void set_hwcs(bool use); + + /** + * @brief Set the bit order for SPI data transfer. + * + * This method sets the bit order for SPI data transfer (MSBFIRST or LSBFIRST). + * + * @param bit_order The bit order for SPI data transfer. + */ static void set_bit_order(u8 bit_order); - static void set_data_mode(u8 data_mode); + + /** + * @brief Set the SPI data mode. + * + * This method sets the SPI data mode (clock polarity and phase). + * + * @param data_mode The SPI data mode (SPI_MODE0, SPI_MODE1, SPI_MODE2, or SPI_MODE3). + */ + static void set_data_mode(spi_mode_t data_mode); + + /** + * @brief Set the SPI clock frequency. + * + * This method sets the SPI clock frequency in Hz. + * + * @param frequency The SPI clock frequency in Hz. + */ static void set_frequency(u32 frequency); + /** + * @brief Set the SPI clock divider. + * + * This method sets the SPI clock divider. + * + * @param clock_div The SPI clock divider. + */ static void set_clock_div(u32 clock_div); + + /** + * @brief Get the SPI clock divider. + * + * This method returns the current SPI clock divider. + * + * @return The current SPI clock divider. + */ static u32 get_clock_div(); + /** + * @brief Write an 8-bit data over SPI. + * + * This method writes an 8-bit data over SPI. + * + * @param data The 8-bit data to be written. + */ static void write8(u8 data); + + /** + * @brief Write a 16-bit data over SPI. + * + * This method writes a 16-bit data over SPI. + * + * @param data The 16-bit data to be written. + */ static void write16(u16 data); + + /** + * @brief Write a 32-bit data over SPI. + * + * This method writes a 32-bit data over SPI. + * + * @param data The 32-bit data to be written. + */ static void write32(u32 data); + /** + * @brief Write data bytes over SPI. + * + * This method writes a specified number of bytes of data over SPI. + * + * @param data Pointer to the data buffer to be written. + * @param size The number of bytes to write. + */ static void write_bytes(u8* data, u32 size); + + /** + * @brief Write pixel data over SPI. + * + * This method writes pixel data over SPI. + * + * @param data Pointer to the pixel data buffer to be written. + * @param size The size of the pixel data buffer. + */ static void write_pixels(void* data, u32 size); + + /** + * @brief Write pattern data over SPI. + * + * This method writes a specified pattern data over SPI. + * + * @param data Pointer to the pattern data buffer to be written. + * @param size The size of the pattern data buffer. + * @param pattern The pattern to be written. + */ static void write_pattern(u8* data, u8 size, u32 pattern); }; -#endif \ No newline at end of file +#endif /* LIBRISHKA_SPI_H */ \ No newline at end of file diff --git a/sdk/librishka/sys.h b/sdk/librishka/sys.h index f0df1b8..bbd980b 100644 --- a/sdk/librishka/sys.h +++ b/sdk/librishka/sys.h @@ -15,58 +15,157 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ +/** + * @file sys.h + * @author [Nathanne Isip](https://github.com/nthnn) + * @brief Header file for system utilities in Rishka applications. + * + * This header file defines the Sys class, which provides functionalities + * for accessing system information and executing system commands on ESP32-WROVER microcontrollers. + */ + #ifndef LIBRISHKA_SYS_H #define LIBRISHKA_SYS_H #include <librishka/types.h> +/** + * @enum sysinfon_t + * @brief Enumeration for system information numeric keys. + * + * The sysinfon_t enumeration defines numeric keys used to retrieve + * various system information such as chip cores, CPU frequency, memory usage, etc. + */ typedef enum { - SYSINFO_CHIPCORES, - SYSINFO_CHIP_REV, - SYSINFO_CPU_FREQ, - SYSINFO_CYCLE_COUNT, - SYSINFO_EFUSE_MAC, - SYSINFO_FLASH_MODE, - SYSINFO_FLASH_SPEED, - SYSINFO_FREE_HEAP, - SYSINFO_FREE_PSRAM, - SYSINFO_HEAP_SIZE, - SYSINFO_MAX_ALLOC_HEAP, - SYSINFO_MIN_FREE_HEAP, - SYSINFO_MIN_FREE_PSRAM, - SYSINFO_PSRAM_SIZE, - SYSINFO_TEMP_VAL, - SYSINFO_CARD_TYPE, - SYSINFO_CARD_SIZE, - SYSINFO_NUM_SECTORS, - SYSINFO_SECTOR_SIZE, - SYSINFO_TOTAL_STORAGE, - SYSINFO_USED_STORAGE + SYSINFO_CHIPCORES, /**< Number of CPU cores */ + SYSINFO_CHIP_REV, /**< Chip revision */ + SYSINFO_CPU_FREQ, /**< CPU frequency in Hz */ + SYSINFO_CYCLE_COUNT, /**< CPU cycle count */ + SYSINFO_EFUSE_MAC, /**< EFUSE MAC address */ + SYSINFO_FLASH_MODE, /**< Flash mode */ + SYSINFO_FLASH_SPEED, /**< Flash speed */ + SYSINFO_FREE_HEAP, /**< Free heap memory */ + SYSINFO_FREE_PSRAM, /**< Free PSRAM memory */ + SYSINFO_HEAP_SIZE, /**< Total heap size */ + SYSINFO_MAX_ALLOC_HEAP, /**< Maximum allocatable heap */ + SYSINFO_MIN_FREE_HEAP, /**< Minimum free heap */ + SYSINFO_MIN_FREE_PSRAM, /**< Minimum free PSRAM */ + SYSINFO_PSRAM_SIZE, /**< Total PSRAM size */ + SYSINFO_TEMP_VAL, /**< Chip temperature */ + SYSINFO_CARD_TYPE, /**< SD card type */ + SYSINFO_CARD_SIZE, /**< SD card size */ + SYSINFO_NUM_SECTORS, /**< Number of SD card sectors */ + SYSINFO_SECTOR_SIZE, /**< SD card sector size */ + SYSINFO_TOTAL_STORAGE, /**< Total storage capacity */ + SYSINFO_USED_STORAGE /**< Used storage capacity */ } sysinfon_t; +/** + * @enum sysinfos_t + * @brief Enumeration for system information string keys. + * + * The sysinfos_t enumeration defines string keys used to retrieve + * various system information such as chip model, SDK version, etc. + */ typedef enum { - SYSINFO_CHIPMODEL, - SYSINFO_SDK_VERSION, - SYSINFO_SKETCH_MD5 + SYSINFO_CHIPMODEL, /**< Chip model */ + SYSINFO_SDK_VERSION, /**< SDK version */ + SYSINFO_SKETCH_MD5 /**< Sketch MD5 hash */ } sysinfos_t; +/** + * @enum sdcard_t + * @brief Enumeration for SD card types. + * + * The sdcard_t enumeration defines the types of SD cards supported. + */ typedef enum { - SD_CARD_NONE, - SD_CARD_MMC, - SD_CARD_SD, - SD_CARD_SDHC, - SD_CARD_UNKNOWN + SD_CARD_NONE, /**< No SD card */ + SD_CARD_MMC, /**< MMC SD card */ + SD_CARD_SD, /**< Standard SD card */ + SD_CARD_SDHC, /**< SDHC SD card */ + SD_CARD_UNKNOWN /**< Unknown SD card type */ } sdcard_t; +/** + * @class Sys + * @brief Class for handling system utilities in Rishka applications. + * + * The Sys class provides static methods for delaying execution, accessing system time, + * executing shell commands, retrieving system information, and exiting the application. + */ class Sys final { public: + /** + * @brief Delay execution for a specified duration. + * + * This method suspends program execution for the specified number of milliseconds. + * + * @param ms The duration to delay in milliseconds. + */ static void delay(u64 ms); + + /** + * @brief Get the current system time in microseconds. + * + * This method returns the current system time in microseconds since boot. + * + * @return The current system time in microseconds. + */ static u64 micros(); + + /** + * @brief Get the current system time in milliseconds. + * + * This method returns the current system time in milliseconds since boot. + * + * @return The current system time in milliseconds. + */ static u64 millis(); + + /** + * @brief Execute a shell command. + * + * This method executes a shell command with the specified binary + * program file name, argument count, and argument array. + * + * @param program The file name of the binary program to execute. + * @param argc The number of arguments in the argument array. + * @param argv The array of arguments for the shell command. + * @return The exit status of the shell command. + */ static i32 shellexec(string program, i32 argc, string* argv); + + /** + * @brief Terminate the application with an exit code. + * + * This method terminates the application with the specified exit code. + * + * @param code The exit code for the application. + */ static void exit(i32 code); + + /** + * @brief Get system information as a string. + * + * This method retrieves system information specified by the key + * as a string representation. + * + * @param key The key for the system information. + * @return The system information as a string. + */ static string info_str(sysinfos_t key); + + /** + * @brief Get system information as a numeric value. + * + * This method retrieves system information specified by the key + * as a numeric value. + * + * @param key The key for the system information. + * @return The system information as a numeric value. + */ static i64 info_num(sysinfon_t key); }; -#endif \ No newline at end of file +#endif /* LIBRISHKA_SYS_H */ \ No newline at end of file diff --git a/sdk/librishka/types.h b/sdk/librishka/types.h index 653407d..da2ddfe 100644 --- a/sdk/librishka/types.h +++ b/sdk/librishka/types.h @@ -15,29 +15,112 @@ * along with this program. If not, see <http://www.gnu.org/licenses/>. */ +/** + * @file types.h + * @author [Nathanne Isip](https://github.com/nthnn) + * @brief Header file for common data types used in Rishka applications. + * + * This header file defines common Rust-inspired data types and macros used throughout + * Rishka applications, including typedefs for integer types, string type, and boolean values. + */ + #ifndef LIBRISHKA_TYPES_H #define LIBRISHKA_TYPES_H +/** + * @typedef rune + * @brief Alias for the Unicode character type. + */ typedef char rune; + +/** + * @typedef string + * @brief Alias for the string type. + */ typedef char* string; +/** + * @typedef i8 + * @brief Alias for the signed 8-bit integer type. + */ typedef signed char i8; + +/** + * @typedef i16 + * @brief Alias for the signed 16-bit integer type. + */ typedef signed short int i16; + +/** + * @typedef i32 + * @brief Alias for the signed 32-bit integer type. + */ typedef signed int i32; + +/** + * @typedef i64 + * @brief Alias for the signed 64-bit integer type. + */ typedef signed long int i64; +/** + * @typedef u8 + * @brief Alias for the unsigned 8-bit integer type. + */ typedef unsigned char u8; + +/** + * @typedef u16 + * @brief Alias for the unsigned 16-bit integer type. + */ typedef unsigned short int u16; + +/** + * @typedef u32 + * @brief Alias for the unsigned 32-bit integer type. + */ typedef unsigned int u32; + +/** + * @typedef u64 + * @brief Alias for the unsigned 64-bit integer type. + */ typedef unsigned long int u64; +/** + * @typedef usize + * @brief Alias for the unsigned integer type representing size. + */ typedef u32 usize; + +/** + * @typedef any + * @brief Alias for the generic pointer type. + */ typedef void* any; +/** + * @def F(str) + * @brief Macro to convert a string literal to a char pointer. + */ #define F(str) ((char*) str) + +/** + * @def nil + * @brief Macro representing a null pointer. + */ #define nil ((void*) 0) +/** + * @def false + * @brief Macro representing the boolean value false. + */ #define false 0 + +/** + * @def true + * @brief Macro representing the boolean value true. + */ #define true 1 -#endif \ No newline at end of file +#endif /* LIBRISHKA_TYPES_H */ \ No newline at end of file diff --git a/sdk/librishka_impl.cpp b/sdk/librishka_impl.cpp index 184229d..5ddedde 100644 --- a/sdk/librishka_impl.cpp +++ b/sdk/librishka_impl.cpp @@ -572,7 +572,7 @@ void SPI::end() { rishka_sc_0(RISHKA_SC_SPI_END); } -void SPI::begin_transaction(u8 clock, u8 bit_order, u8 data_mode) { +void SPI::begin_transaction(u8 clock, u8 bit_order, spi_mode_t data_mode) { rishka_sc_3(RISHKA_SC_SPI_BEGIN_TRANSACTION, (i64) clock, (i64) bit_order, (i64) data_mode); } @@ -608,7 +608,7 @@ void SPI::set_bit_order(u8 bit_order) { rishka_sc_1(RISHKA_SC_SPI_SET_BIT_ORDER, (i64) bit_order); } -void SPI::set_data_mode(u8 data_mode) { +void SPI::set_data_mode(spi_mode_t data_mode) { rishka_sc_1(RISHKA_SC_SPI_SET_DATA_MODE, (i64) data_mode); }