add doc

src/ES32A08.cpp

@@ -1,6 +1,29 @@
 #include "ES32A08.h"
 
-// Initialize the board and reset it
+
+/**
+ * @brief Initializes the ES32A08 module.
+ * 
+ * This function sets up the necessary pin modes and initial states for the 
+ * 74HC595D shift register (used for Relay and 7-Segment display), the power 
+ * LED, and the digital input shift register. It also configures the button 
+ * pins as input with pull-up resistors. Finally, it creates a task to update 
+ * the registers periodically.
+ * 
+ * Pin configurations:
+ * - DATA_PIN: Output for shift register data
+ * - LATCH_PIN: Output for shift register latch
+ * - CLOCK_PIN: Output for shift register clock
+ * - OE_PIN: Output for shift register output enable
+ * - PWR_LED_PIN: Output for power LED
+ * - buttonPins[0-3]: Input with pull-up for buttons
+ * - LOAD165_PIN: Output for digital input shift register load
+ * - CLK165_PIN: Output for digital input shift register clock
+ * - DATA165_PIN: Input for digital input shift register data
+ * 
+ * The function also calls the reset() method to initialize the module state 
+ * and creates a FreeRTOS task to handle register updates.
+ */
 void ES32A08::begin() {
   // 74HC595D shift register config (Relay + 7-Seg disp.)
   pinMode(DATA_PIN, OUTPUT);
@@ -37,14 +60,36 @@ void ES32A08::begin() {
   );
 }
 
-// Open relays and clear display
+
+/**
+ * @brief Resets the ES32A08 device to its initial state.
+ *
+ * This function performs the following actions:
+ * - Turns on the power LED to indicate a reset state.
+ * - Sets the current relay states to either all on or all off based on the RESET_RELAY_ON flag.
+ * - Clears the display, which also triggers sending data to the shift register.
+ */
 void ES32A08::reset() {
   setPWRLED(RESET_LED_ON);
   currentRelays = RESET_RELAY_ON ? 0b11111111 : 0b00000000;
   clearDisplay(); // it also calls sendToShiftRegister()
 }
 
-// Send relays and display settings to the s.r.
+/**
+ * @brief Sends the current state of relays, digits, and segments to the shift registers.
+ *
+ * This function updates the shift registers with the current state of the relays, digits,
+ * and segments by shifting out the data bits and latching the output. It controls three
+ * shift registers, each handling 8 bits, for a total of 24 bits.
+ *
+ * @details
+ * - The function first sets the latch pin to LOW to prepare for data transmission.
+ * - It then shifts out the bits for the relays, digits, and segments in MSB first order.
+ * - After shifting out the data, it sets the latch pin to HIGH to update the output.
+ * - Finally, it introduces a small delay to ensure the data is properly latched.
+ *
+ * @note The delay is specified in microseconds and is defined by the DIGIT_PERS constant.
+ */
 void ES32A08::sendToShiftRegister() {
   digitalWrite(LATCH_PIN, LOW);
   shiftOut(DATA_PIN, CLOCK_PIN, MSBFIRST, currentRelays);
@@ -54,12 +99,27 @@ void ES32A08::sendToShiftRegister() {
   delayMicroseconds(DIGIT_PERS);
 } // There are 3 shift registers for a total of 24 bits
 
-// Clear entire 7-seg display
+
+/**
+ * @brief Clears the display buffer.
+ *
+ * This function sets all elements of the display buffer to zero, effectively
+ * clearing the display.
+ */
 void ES32A08::clearDisplay() {
   memset(displayBuffer, 0, sizeof(displayBuffer));
 }
 
-// Task to continuosly feed the registers
+
+/**
+ * @brief Updates the display registers continuously.
+ *
+ * This function runs an infinite loop that updates the display registers.
+ * It iterates through the display buffer and updates the current digits and segments,
+ * then sends the data to the shift register.
+ *
+ * @param instance A pointer to an instance of the ES32A08 class.
+ */
 void ES32A08::updateRegisters(void *instance) {
   ES32A08 *self = static_cast<ES32A08 *>(instance); // Cast del puntatore
   for (;;) {
@@ -71,7 +131,18 @@ void ES32A08::updateRegisters(void *instance) {
   }
 }
 
-// Char to segment conversion by LUT
+/**
+ * @brief Converts a character to its corresponding 7-segment display encoding.
+ *
+ * This function takes a character as input and returns the corresponding
+ * 8-bit binary encoding for a 7-segment display. The encoding is based on
+ * the common cathode 7-segment display configuration.
+ *
+ * @param c The character to be converted. Supported characters include:
+ *          '0'-'9', 'A'-'Z', 'a'-'z', ' ', '.', '-', '_'.
+ * @return uint8_t The 8-bit binary encoding for the 7-segment display.
+ *         If the character is not recognized, it returns 0b00000000 (blank).
+ */
 uint8_t ES32A08::charToSegments(char c) {
   switch (c) {
   case '0':
@@ -181,14 +252,34 @@ uint8_t ES32A08::charToSegments(char c) {
   }
 }
 
-// Show a 4-char message on the display
+
+/**
+ * @brief Displays a message on the ES32A08 display.
+ *
+ * This function clears the display buffer and then converts each character
+ * in the provided message to its corresponding segment representation,
+ * storing it in the display buffer. The message is truncated to a maximum
+ * of 4 characters.
+ *
+ * @param message The message to be displayed. It should be a null-terminated
+ *                string with a maximum length of 4 characters.
+ */
 void ES32A08::display(const char *message) {
   memset(displayBuffer, 0, sizeof(displayBuffer));
   for (int pos = 0; message[pos] != '\0' && pos < 4; pos++)
     displayBuffer[pos] = charToSegments(message[pos]);
 }
 
-// Show a number on the 4-digit display
+
+/**
+ * @brief Displays a given integer number on a 4-digit 7-segment display.
+ *
+ * This function takes an integer number and displays it on a 4-digit 7-segment display.
+ * If the number is outside the range of -999 to 9999, it displays " -- ".
+ * Otherwise, it formats the number to fit within 4 characters and updates the display buffer.
+ *
+ * @param number The integer number to be displayed. Valid range is -999 to 9999.
+ */
 void ES32A08::display(int number) {
   if (number > 9999 || number < -999)
     display(" -- ");
@@ -201,7 +292,16 @@ void ES32A08::display(int number) {
   }
 }
 
-// Show a float on the 4-digit display
+/**
+ * @brief Displays a floating-point number on a 7-segment display.
+ * 
+ * This function takes a floating-point number and converts it into a format
+ * suitable for displaying on a 7-segment display. The number is formatted to
+ * two decimal places. If the number is outside the range of -999 to 9999, 
+ * it displays " -- " to indicate an out-of-range value.
+ * 
+ * @param number The floating-point number to be displayed.
+ */
 void ES32A08::display(float number) {
   memset(displayBuffer, 0, sizeof(displayBuffer));
   if (number > 9999 || number < -999)
@@ -227,7 +327,16 @@ void ES32A08::display(float number) {
   }
 }
 
-// Read single 4-20mA input
+/**
+ * @brief Reads the analog current in milliamps from the specified channel.
+ *
+ * This function reads the analog value from the specified channel, converts it
+ * to a current value in milliamps, and returns the result. The conversion is
+ * based on a 12-bit ADC (Analog-to-Digital Converter) with a range of 0 to 4095.
+ *
+ * @param channel The analog input channel to read from. Valid values are 0 to 3.
+ * @return The current in milliamps. If the channel is out of range, the function returns 0.
+ */
 float ES32A08::readAnalogmA(int channel) {
   if (channel < 0 || channel > 3)
     return 0;
@@ -236,7 +345,17 @@ float ES32A08::readAnalogmA(int channel) {
   return current;
 }
 
-// Read single 0-10V input
+
+/**
+ * @brief Reads the analog voltage from a specified channel.
+ *
+ * This function reads the analog value from the specified channel, converts it
+ * to a voltage, and returns the result. The conversion assumes a 12-bit ADC
+ * with a reference voltage of 10V and applies a scaling factor.
+ *
+ * @param channel The analog input channel to read from (valid values are 0 to 3).
+ * @return The converted voltage value. Returns 0 if the channel is out of range.
+ */
 float ES32A08::readAnalogVoltage(int channel) {
   if (channel < 0 || channel > 3)
     return 0;
@@ -245,7 +364,17 @@ float ES32A08::readAnalogVoltage(int channel) {
   return voltage;
 }
 
-// Raw read single 0-10V input
+
+/**
+ * @brief Reads the raw analog voltage from the specified channel.
+ *
+ * This function reads the analog voltage from one of the predefined input pins
+ * corresponding to the given channel. The channel must be between 0 and 3 inclusive.
+ * If the channel is out of this range, the function returns 0.
+ *
+ * @param channel The analog input channel to read from (0-3).
+ * @return The raw analog voltage value read from the specified channel, or 0 if the channel is invalid.
+ */
 int ES32A08::rawReadAnalogVoltage(int channel) {
   if (channel < 0 || channel > 3)
     return 0;

src/ES32A08.h

@@ -26,6 +26,112 @@
 
 // ######### CLASS DEFINITION REGION #####################################
 
+/**
+ * @class ES32A08
+ * @brief A class to interface with the ES32A08 board.
+ * 
+ * This class provides methods to initialize the board, read analog and digital inputs,
+ * control relays, and display numbers or messages on a 4-digit 7-segment display.
+ */
+ 
+/**
+ * @brief Initialize the board and reset it.
+ */
+void begin();
+
+/**
+ * @brief Read a single 4-20mA input.
+ * @param channel The channel number to read from (0-3).
+ * @return The current in mA.
+ */
+float readAnalogmA(int channel);
+
+/**
+ * @brief Read a single 0-10V input.
+ * @param channel The channel number to read from (0-3).
+ * @return The voltage.
+ */
+float readAnalogVoltage(int channel);
+
+/**
+ * @brief Raw read of a single 0-10V input.
+ * @param channel The channel number to read from (0-3).
+ * @return The raw ADC value.
+ */
+int rawReadAnalogVoltage(int channel);
+
+/**
+ * @brief Read the state of a single button.
+ * @param buttonNumber The button number to read (0-3).
+ * @return True if the button is pressed, false otherwise.
+ */
+bool readButton(int buttonNumber);
+
+/**
+ * @brief Read the state of a single digital input.
+ * @param inputNumber The input number to read (0-3).
+ * @return True if the input is high, false otherwise.
+ */
+bool readDigitalInput(int inputNumber);
+
+/**
+ * @brief Read the state of all digital inputs.
+ * @return A byte representing the state of all digital inputs.
+ */
+uint8_t readDigitalInputs();
+
+/**
+ * @brief Set the state of a single relay.
+ * @param relay The relay number to set (0-7).
+ * @param state The state to set the relay to (true for on, false for off).
+ */
+void setRelay(int relay, bool state);
+
+/**
+ * @brief Set the state of all relays.
+ * @param relayStates A byte representing the state of all relays (e.g., 0b00000000).
+ */
+void setRelays(unsigned long relayStates);
+
+/**
+ * @brief Set the state of the "PWR" onboard LED.
+ * @param state The state to set the LED to (true for on, false for off).
+ */
+void setPWRLED(bool state);
+
+/**
+ * @brief Reset the board by opening all relays and clearing the display.
+ */
+void reset();
+
+/**
+ * @brief Clear the entire 7-seg display.
+ */
+void clearDisplay();
+
+/**
+ * @brief Show a number on the 4-digit display.
+ * @param number The number to display.
+ */
+void display(int number);
+
+/**
+ * @brief Show a float on the 4-digit display.
+ * @param number The float number to display.
+ */
+void display(float number);
+
+/**
+ * @brief Show a 4-character message on the display.
+ * @param message The message to display.
+ */
+void display(const char *message);
+
+/**
+ * @brief Task to continuously feed the registers.
+ * @param instance A pointer to the instance of the class.
+ */
+static void updateRegisters(void *instance);
 class ES32A08 {
 public:
   void begin(); // Initialize the board and reset it