diff --git a/ESPMegaPRO-firmware/lib/ESPMegaPRO/AnalogCard.hpp b/ESPMegaPRO-firmware/lib/ESPMegaPRO/AnalogCard.hpp index 86134c2..2b0ad1c 100644 --- a/ESPMegaPRO-firmware/lib/ESPMegaPRO/AnalogCard.hpp +++ b/ESPMegaPRO-firmware/lib/ESPMegaPRO/AnalogCard.hpp @@ -16,6 +16,15 @@ #define DAC2_ADDRESS 0x62 #define DAC3_ADDRESS 0x63 +/** + * @brief This class represents the Analog Card. + * + * The analog card has 8 analog inputs accross two banks, and 4 DAC outputs. + * + * @note You do not need to specify the ESPMega I/O Address when creating an instance of this class as there can only be one Analog Card installed in the ESPMegaPRO board. + * @warning There can only be one Analog Card installed in the ESPMegaPRO board. + * + */ class AnalogCard : public ExpansionCard { public: AnalogCard(); diff --git a/ESPMegaPRO-firmware/lib/ESPMegaPRO/AnalogIoT.hpp b/ESPMegaPRO-firmware/lib/ESPMegaPRO/AnalogIoT.hpp index b806b84..1695469 100644 --- a/ESPMegaPRO-firmware/lib/ESPMegaPRO/AnalogIoT.hpp +++ b/ESPMegaPRO-firmware/lib/ESPMegaPRO/AnalogIoT.hpp @@ -11,6 +11,13 @@ #define DAC_PUBLISH_ENABLE_TOPIC "/publish_enable" #define REQUEST_STATE_TOPIC "requeststate" +/** + * @brief The AnalogIoT class is a class for connecting the Analog Card to the IoT module. + * + * This function allows you to control the Analog Card using MQTT. + * + * @warning You should not instantiate this class directly, instead use ESPMegaIoT's registerCard function. + */ class AnalogIoT : public IoTComponent { public: AnalogIoT(); diff --git a/ESPMegaPRO-firmware/lib/ESPMegaPRO/ClimateCard.hpp b/ESPMegaPRO-firmware/lib/ESPMegaPRO/ClimateCard.hpp index a194bd0..f4fa416 100644 --- a/ESPMegaPRO-firmware/lib/ESPMegaPRO/ClimateCard.hpp +++ b/ESPMegaPRO-firmware/lib/ESPMegaPRO/ClimateCard.hpp @@ -54,6 +54,15 @@ struct AirConditioner { }; // This requires 3 bytes of FRAM +/** + * @brief The ClimateCard class is a class for controlling an air conditioner + * + * This class allows you to control an air conditioner using an IR LED. + * It is meant to be used with the ESPMega Climate Card. + * + * @note You can also use a DHT22 or DS18B20 temperature sensor to get the room temperature (and humidity if using a DHT22). Although, this is optional. + * + */ class ClimateCard : public ExpansionCard { public: ClimateCard(uint8_t ir_pin, AirConditioner ac, uint8_t sensor_type, uint8_t sensor_pin); diff --git a/ESPMegaPRO-firmware/lib/ESPMegaPRO/ClimateIoT.hpp b/ESPMegaPRO-firmware/lib/ESPMegaPRO/ClimateIoT.hpp index 072b3de..b376afd 100644 --- a/ESPMegaPRO-firmware/lib/ESPMegaPRO/ClimateIoT.hpp +++ b/ESPMegaPRO-firmware/lib/ESPMegaPRO/ClimateIoT.hpp @@ -14,6 +14,13 @@ #define AC_HUMIDITY_REPORT_TOPIC "humidity" #define AC_REQUEST_STATE_TOPIC "request_state" +/** + * @brief The ClimateIoT class is a class for connecting the Climate Card to the IoT module. + * + * This function allows you to control the Climate Card using MQTT. + * + * @warning You should not instantiate this class directly, instead use ESPMegaIoT's registerCard function. + */ class ClimateIoT : public IoTComponent { public: ClimateIoT(); diff --git a/ESPMegaPRO-firmware/lib/ESPMegaPRO/DigitalInputCard.hpp b/ESPMegaPRO-firmware/lib/ESPMegaPRO/DigitalInputCard.hpp index 0464347..a140029 100644 --- a/ESPMegaPRO-firmware/lib/ESPMegaPRO/DigitalInputCard.hpp +++ b/ESPMegaPRO-firmware/lib/ESPMegaPRO/DigitalInputCard.hpp @@ -6,6 +6,15 @@ // Card Type #define CARD_TYPE_DIGITAL_INPUT 0x01 +/** + * @brief ESPMegaPRO Digital Input Card + * + * This class represents the ESPMegaPRO Digital Input Card. + * It allows you to read the state of the digital inputs from the ESPMegaPRO Digital Input Card. + * It also allows you to register callback functions to be called when a pin changes. + * The callback function also support debouncing. + * + */ class DigitalInputCard : public ExpansionCard { public: // Instantiate the card with the specified address diff --git a/ESPMegaPRO-firmware/lib/ESPMegaPRO/DigitalInputIoT.hpp b/ESPMegaPRO-firmware/lib/ESPMegaPRO/DigitalInputIoT.hpp index 7b1a636..978135f 100644 --- a/ESPMegaPRO-firmware/lib/ESPMegaPRO/DigitalInputIoT.hpp +++ b/ESPMegaPRO-firmware/lib/ESPMegaPRO/DigitalInputIoT.hpp @@ -7,6 +7,13 @@ // MQTT Topics #define PUBLISH_ENABLE_TOPIC "publish_enable" +/** + * @brief The DigitalInputIoT class is a class for connecting the Digital Input Card to the IoT module. + * + * This function allows you to control the Digital Input Card using MQTT. + * + * @warning You should not instantiate this class directly, instead use ESPMegaIoT's registerCard function. + */ class DigitalInputIoT : public IoTComponent { public: bool begin(uint8_t card_id, ExpansionCard *card, PubSubClient *mqtt, char *base_topic); diff --git a/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaPRO_OOP.cpp b/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaPRO_OOP.cpp index 4027aea..678bdcb 100644 --- a/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaPRO_OOP.cpp +++ b/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaPRO_OOP.cpp @@ -4,9 +4,23 @@ // (34 Bytes) Address 0-33 for Built-in Digital Output Card // (266 Bytes) Address 34-300 for ESPMegaPRO IoT Module +/** + * @brief Create a new ESPMegaPRO object + * + * @warning Only one ESPMegaPRO object can be created, creating more than one will result in undefined behavior + */ ESPMegaPRO::ESPMegaPRO() { } + +/** + * @brief Initializes the ESPMegaPRO object. + * + * This function initializes the ESPMegaPRO object and all of its components. + * It also initializes the built-in Digital Input and Digital Output cards. + * + * @return True if the initialization is successful, false otherwise. + */ bool ESPMegaPRO::begin() { Wire.begin(14, 33); fram.begin(FRAM_ADDRESS); @@ -24,6 +38,15 @@ bool ESPMegaPRO::begin() { inputs.loadPinMap(pinMap); return true; } + +/** + * @brief The main loop for the ESPMegaPRO object. + * + * @note This function must be called in the main loop of the program. + * + * It will call the loop() function of all installed expansion cards, the ESPMegaIoT module, and the internal display. + * + */ void ESPMegaPRO::loop() { inputs.loop(); outputs.loop(); @@ -39,6 +62,17 @@ void ESPMegaPRO::loop() { display->loop(); } } + +/** + * @brief Installs an expansion card to the specified slot. + * + * @note This function automatically initializes the expansion card. + * + * @param slot The slot to install the card to. + * @param card Pointer to the ExpansionCard object. + * + * @return True if the installation is successful, false otherwise. + */ bool ESPMegaPRO::installCard(uint8_t slot, ExpansionCard* card) { if (slot > 255) return false; if (cardInstalled[slot]) { @@ -53,8 +87,15 @@ bool ESPMegaPRO::installCard(uint8_t slot, ExpansionCard* card) { cardInstalled[slot] = true; cardCount++; return true; - } + +/** + * @brief Updates the internal RTC from NTP. + * + * @note Network must be connected before calling this function (see ESPMegaPRO.ESPMegaIoT::connectNetwork()). + * + * @return True if the update is successful, false otherwise. + */ bool ESPMegaPRO::updateTimeFromNTP() { struct tm timeinfo; if (getLocalTime(&timeinfo)) @@ -72,6 +113,12 @@ bool ESPMegaPRO::updateTimeFromNTP() { } return false; } + +/** + * @brief Gets the current time from the internal RTC. + * + * @return The current time as a rtctime_t struct. + */ rtctime_t ESPMegaPRO::getTime() { tmElements_t timeElement; RTC.read(timeElement); @@ -85,6 +132,16 @@ rtctime_t ESPMegaPRO::getTime() { return time; } +/** + * @brief Sets the current time of the internal RTC. + * + * @param hours The hours. + * @param minutes The minutes. + * @param seconds The seconds. + * @param day The day. + * @param month The month. + * @param year The year. + */ void ESPMegaPRO::setTime(int hours, int minutes, int seconds, int day, int month, int year) { tmElements_t timeElement; @@ -97,6 +154,11 @@ void ESPMegaPRO::setTime(int hours, int minutes, int seconds, int day, int month RTC.write(timeElement); } +/** + * @brief Enables, Instanitates, and Initializes the ESPMegaIoT module. + * + * @note This function must be called before using the ESPMegaIoT module. + */ void ESPMegaPRO::enableIotModule() { if (iotEnabled) return; this->iot = new ESPMegaIoT(); @@ -105,12 +167,27 @@ void ESPMegaPRO::enableIotModule() { iotEnabled = true; } +/** + * @brief Gets the expansion card installed at the specified slot. + * + * @param slot The slot to get the card from. + * + * @return Pointer to the ExpansionCard object, or nullptr if no card is installed at the specified slot. + */ ExpansionCard* ESPMegaPRO::getCard(uint8_t slot) { if (slot > 255) return nullptr; if (!cardInstalled[slot]) return nullptr; return cards[slot]; } +/** + * @brief Enables, Instanitates, and Initializes the internal display. + * + * @note This function can only be called if the ESPMegaIoT module is enabled. + * @note This function must be called before using the internal display. + * + * @param serial Pointer to the HardwareSerial object to use for the internal display (Serial for ESPMegaPRO R3). + */ void ESPMegaPRO::enableInternalDisplay(HardwareSerial *serial) { if (internalDisplayEnabled) return; if (!iotEnabled) { @@ -130,6 +207,12 @@ void ESPMegaPRO::enableInternalDisplay(HardwareSerial *serial) { } +/** + * @brief Dumps the contents of the internal FRAM to the serial port. + * + * @param start The starting address. + * @param end The ending address. + */ void ESPMegaPRO::dumpFRAMtoSerial(uint16_t start, uint16_t end) { for (int i = start; i <=end; i++) { if (i % 16 == 0) { @@ -139,6 +222,12 @@ void ESPMegaPRO::dumpFRAMtoSerial(uint16_t start, uint16_t end) { } } +/** + * @brief Dumps the contents of the internal FRAM to the serial port in ASCII. + * + * @param start The starting address. + * @param end The ending address. + */ void ESPMegaPRO::dumpFRAMtoSerialASCII(uint16_t start, uint16_t end) { for (int i = 0; i < 500; i++) { Serial.printf("%d: %c\n", i,this->fram.read8(i)); diff --git a/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaPRO_OOP.hpp b/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaPRO_OOP.hpp index 24201e1..318da1f 100644 --- a/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaPRO_OOP.hpp +++ b/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaPRO_OOP.hpp @@ -16,12 +16,26 @@ #include #include +// ESPMega Pro R3 Board Address #define FRAM_ADDRESS 0x56 #define INPUT_BANK_A_ADDRESS 0x21 #define INPUT_BANK_B_ADDRESS 0x22 #define PWM_BANK_ADDRESS 0x5F #define RTC_ADDRESS 0x68 +/** + * @brief The ESPMegaPRO class is the main class for the ESPMegaPRO library. + * + * This class provides functions for managing the ESPMegaPRO board, such as installing expansion cards, managing the internal RTC, and managing the internal FRAM. + * This class also provides functions for managing the ESPMegaIoT module and the internal display. + * + * This class provide a Object Oriented Programming (OOP) interface for the ESPMegaPRO board. + * If you are looking for a more simple and a more procedural interface, please use the ESPMegaPRO class in ESPMegaPRO.hpp. + * But note that the ESPMegaPRO class only interfaces with the built-in Digital Input and Digital Output cards and other onboard components. + * It does not provide an interface for expansion cards, the ESPMegaIoT module, and the internal display. + * + * @warning Only one ESPMegaPRO object can be created, creating more than one will result in undefined behavior. + */ class ESPMegaPRO { public: ESPMegaPRO(); diff --git a/ESPMegaPRO-firmware/lib/ESPMegaPRO/TimeStructure.hpp b/ESPMegaPRO-firmware/lib/ESPMegaPRO/TimeStructure.hpp index 39d7085..0df7971 100644 --- a/ESPMegaPRO-firmware/lib/ESPMegaPRO/TimeStructure.hpp +++ b/ESPMegaPRO-firmware/lib/ESPMegaPRO/TimeStructure.hpp @@ -1,6 +1,13 @@ #pragma once #include +/** + * @brief The rtctime_t struct is a structure for storing the time. + * + * This structure is used by the ESPMegaPRO library to store the time. + * + * @warning This structure is not compatible with the Arduino Time library. + */ struct rtctime_t { uint8_t hours; uint8_t minutes;