diff --git a/src/ES32A08.cpp b/src/ES32A08.cpp index fe88c03..71a2547 100644 --- a/src/ES32A08.cpp +++ b/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(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; diff --git a/src/ES32A08.h b/src/ES32A08.h index 36796e9..0a80138 100644 --- a/src/ES32A08.h +++ b/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