Display Comment

ESPMegaPRO-firmware/lib/ESPMegaPRO/InternalDisplay.cpp

@@ -1,5 +1,13 @@
 #include <InternalDisplay.hpp>
 
+/**
+ * @brief Initialize the Internal Display
+ * 
+ * @note You should not call this function directly, instead use ESPMegaIoT::enableInternalDisplay()
+ * 
+ * @param iot The ESPMegaIoT object
+ * @param getRtcTime A function that returns the current time
+ */
 void InternalDisplay::begin(ESPMegaIoT *iot, std::function<rtctime_t()> getRtcTime)
 {
     this->iot = iot;
@@ -20,6 +28,11 @@ void InternalDisplay::begin(ESPMegaIoT *iot, std::function<rtctime_t()> getRtcTi
     this->jumpToPage(1);
 }
 
+/**
+ * @brief The main loop of the Internal Display
+ * 
+ * @note You should not call this function directly, instead use ESPMega::loop()
+ */
 void InternalDisplay::loop()
 {
     // Keep reading the Serial Adapter
@@ -41,6 +54,12 @@ void InternalDisplay::loop()
     }
 }
 
+/**
+ * @brief Update the display in response to a change in the input state
+ * 
+ * @param pin The pin that changed
+ * @param state The new state of the pin
+ */
 void InternalDisplay::handleInputStateChange(uint8_t pin, bool state)
 {
     // If the input card is binded to the display and the current page is the input page
@@ -51,6 +70,13 @@ void InternalDisplay::handleInputStateChange(uint8_t pin, bool state)
     this->setInputMarker(pin, state);
 }
 
+/**
+ * @brief Update the display in response to a change in the PWM state
+ * 
+ * @param pin The pin that changed
+ * @param state The new state of the pin
+ * @param value The new value of the pin
+ */
 void InternalDisplay::handlePwmStateChange(uint8_t pin, bool state, uint16_t value)
 {
     // If the output card is binded to the display and the current page is the output page
@@ -67,12 +93,20 @@ void InternalDisplay::handlePwmStateChange(uint8_t pin, bool state, uint16_t val
     }
 }
 
+/**
+ * @brief Update the display in response to page change
+ * 
+ * @param page The new page
+ */
 void InternalDisplay::handlePageChange(uint8_t page)
 {
     // Refresh the page
     this->refreshPage(page);
 }
 
+/**
+ * @brief Save the network config to the FRAM
+ */
 void InternalDisplay::saveNetworkConfig()
 {
     // The network config page have the following components:
@@ -141,6 +175,9 @@ void InternalDisplay::saveNetworkConfig()
     ESP.restart();
 }
 
+/**
+ * @brief Save the MQTT config to the FRAM
+ */
 void InternalDisplay::saveMQTTConfig()
 {
     // The MQTT config page have the following components:
@@ -180,12 +217,21 @@ void InternalDisplay::saveMQTTConfig()
     ESP.restart();
 }
 
+/**
+ * @brief Update the status icons on the Internal Display's top bar
+ * 
+ * @param networkStatus The network status
+ * @param mqttStatus The MQTT status
+ */
 void InternalDisplay::updateStatusIcons(bool networkStatus, bool mqttStatus)
 {
     this->setNumber("server.pic", mqttStatus ? PIC_MQTT_CONNECTED : PIC_MQTT_DISCONNECTED);
     this->setNumber("lan.pic", networkStatus ? PIC_LAN_CONNECTED : PIC_LAN_DISCONNECTED);
 }
 
+/**
+ * @brief Update the clock on the Internal Display's top bar
+ */
 void InternalDisplay::updateClock()
 {
     rtctime_t time = this->getRtcTime();
@@ -193,11 +239,21 @@ void InternalDisplay::updateClock()
     this->sendStopBytes();
 }
 
+/**
+ * @brief Send data to display element on the current page
+ */
 void InternalDisplay::refreshPage()
 {
     this->refreshPage(this->currentPage);
 }
 
+/**
+ * @brief Send data to display element on the specified page
+ * 
+ * @note The current page must be the specified page
+ * 
+ * @param page The page to refresh
+ */
 void InternalDisplay::refreshPage(uint8_t page)
 {
     switch (page)
@@ -243,6 +299,9 @@ void InternalDisplay::refreshPage(uint8_t page)
     }
 }
 
+/**
+ * @brief Send data to display element on the dashboard page
+ */
 void InternalDisplay::refreshDashboard()
 {
     // The dashboard have the following components:
@@ -264,6 +323,9 @@ void InternalDisplay::refreshDashboard()
     this->setString("status_txt.txt", this->iot->mqttConnected() ? MSG_MQTT_CONNECTED : MSG_MQTT_DISCONNECTED);
 }
 
+/**
+ * @brief Send data to display element on the input page
+ */
 void InternalDisplay::refreshInput()
 {
     for (uint8_t i = 0; i < 16; i++)
@@ -272,6 +334,9 @@ void InternalDisplay::refreshInput()
     }
 }
 
+/**
+ * @brief Send data to display element on the output page
+ */
 void InternalDisplay::refreshOutput()
 {
     for (uint8_t i = 0; i < 16; i++)
@@ -281,6 +346,9 @@ void InternalDisplay::refreshOutput()
     }
 }
 
+/**
+ * @brief Send data to display element on the AC page
+ */
 void InternalDisplay::refreshAC()
 {
     this->displayAdapter->print("temp.txt=\"");
@@ -334,6 +402,12 @@ void InternalDisplay::refreshAC()
     }
 }
 
+/**
+ * @brief Set the PWM status output bar value (Fullness of the bar)
+ * 
+ * @param pin The pin of the PWM
+ * @param value The value of the PWM (0 - 4095)
+ */
 void InternalDisplay::setOutputBar(uint8_t pin, uint16_t value)
 {
     // Write the value to the output bar
@@ -344,6 +418,12 @@ void InternalDisplay::setOutputBar(uint8_t pin, uint16_t value)
     this->sendStopBytes();
 }
 
+/**
+ * @brief Set the PWM status output bar color to match the PWM state
+ * 
+ * @param pin The pin of the PWM
+ * @param state The state of the PWM
+ */
 void InternalDisplay::setOutputStateColor(uint8_t pin, bool state)
 {
     this->displayAdapter->print("j");
@@ -353,6 +433,12 @@ void InternalDisplay::setOutputStateColor(uint8_t pin, bool state)
     this->sendStopBytes();
 }
 
+/**
+ * @brief Set Input Marker to match the input state
+ * 
+ * @param pin The pin of the input
+ * @param state The state of the input
+ */
 void InternalDisplay::setInputMarker(uint8_t pin, bool state)
 {
     this->displayAdapter->print("I");
@@ -362,6 +448,11 @@ void InternalDisplay::setInputMarker(uint8_t pin, bool state)
     this->sendStopBytes();
 }
 
+/**
+ * @brief Create a new Internal Display object
+ * 
+ * @param displayAdapter The HardwareSerial object that is connected to the display
+ */
 InternalDisplay::InternalDisplay(HardwareSerial *displayAdapter) : ESPMegaDisplay(displayAdapter)
 {
     this->currentPage = INTERNAL_DISPLAY_DASHBOARD_PAGE;
@@ -372,6 +463,11 @@ InternalDisplay::InternalDisplay(HardwareSerial *displayAdapter) : ESPMegaDispla
     this->pmwAdjustmentPin = 0;
 }
 
+/**
+ * @brief Set the input card to be be shown on the input page
+ * 
+ * @param inputCard The input card object to be shown
+ */
 void InternalDisplay::bindInputCard(DigitalInputCard *inputCard)
 {
     // Check if the input card is already binded
@@ -386,6 +482,9 @@ void InternalDisplay::bindInputCard(DigitalInputCard *inputCard)
         this->inputCard->registerCallback(bindedInputStateChangeCallback);
 }
 
+/**
+ * @brief Unbind the input card from the display
+ */
 void InternalDisplay::unbindInputCard()
 {
     if (this->inputCard == nullptr)
@@ -394,6 +493,11 @@ void InternalDisplay::unbindInputCard()
     this->inputCard = nullptr;
 }
 
+/**
+ * @brief Set the output card to be be shown on the output page
+ * 
+ * @param outputCard The output card object to be shown
+ */
 void InternalDisplay::bindOutputCard(DigitalOutputCard *outputCard)
 {
     // Check if the output card is already binded
@@ -406,6 +510,9 @@ void InternalDisplay::bindOutputCard(DigitalOutputCard *outputCard)
         this->outputCard->registerChangeCallback(bindedPwmStateChangeCallback);
 }
 
+/**
+ * @brief Unbind the output card from the display
+ */
 void InternalDisplay::unbindOutputCard()
 {
     if (this->outputCard == nullptr)
@@ -414,9 +521,15 @@ void InternalDisplay::unbindOutputCard()
     this->outputCard = nullptr;
 }
 
-// This assume that your ClimeateCard has the mode and fan speed names in the following order:
+/**
-// mode: [off, fan_only, cool]
+ * @brief Set the climate card to be be shown on the AC page
-// fan_speed: [auto, low, medium, high]
+ * 
+ * This assume that your ClimeateCard has the mode and fan speed names in the following order:
+ * mode: [off, fan_only, cool]
+ * fan_speed: [auto, low, medium, high]
+ * 
+ * @param climateCard The climate card object to be shown
+ */
 void InternalDisplay::bindClimateCard(ClimateCard *climateCard)
 {   
     // Check if the climate card is already binded
@@ -429,6 +542,9 @@ void InternalDisplay::bindClimateCard(ClimateCard *climateCard)
         this->climateCard->registerChangeCallback(bindedACStateChangeCallback);
 }
 
+/**
+ * @brief Unbind the climate card from the display
+ */
 void InternalDisplay::unbindClimateCard()
 {
     if (this->climateCard == nullptr)
@@ -437,6 +553,9 @@ void InternalDisplay::unbindClimateCard()
     this->climateCard = nullptr;
 }
 
+/**
+ * @brief Send data to display element on the PWM Adjustment page
+ */
 void InternalDisplay::refreshPWMAdjustment()
 {
     // The PWM Adjustment page have the following components:
@@ -452,6 +571,9 @@ void InternalDisplay::refreshPWMAdjustment()
     this->refreshPWMAdjustmentState();
 }
 
+/**
+ * @brief Send the PWM pin id to the display on the PWM Adjustment page
+ */
 void InternalDisplay::refreshPWMAdjustmentId()
 {
     // Send the PWM pin
@@ -461,6 +583,9 @@ void InternalDisplay::refreshPWMAdjustmentId()
     this->sendStopBytes();
 }
 
+/**
+ * @brief Send the PWM value to the display on the PWM Adjustment page
+ */
 void InternalDisplay::refreshPWMAdjustmentSlider()
 {
     // Send the PWM value
@@ -469,6 +594,9 @@ void InternalDisplay::refreshPWMAdjustmentSlider()
     this->sendStopBytes();
 }
 
+/**
+ * @brief Send the PWM state to the display on the PWM Adjustment page
+ */
 void InternalDisplay::refreshPWMAdjustmentState()
 {
     // Send the PWM state
@@ -478,6 +606,13 @@ void InternalDisplay::refreshPWMAdjustmentState()
     this->sendStopBytes();
 }
 
+/**
+ * @brief Handle the touch event on the display
+ * 
+ * @param page The page that the touch event occured
+ * @param component The component that the touch event occured
+ * @param type The type of the touch event
+ */
 void InternalDisplay::handleTouch(uint8_t page, uint8_t component, uint8_t type)
 {
     // Switch based on the page
@@ -502,6 +637,12 @@ void InternalDisplay::handleTouch(uint8_t page, uint8_t component, uint8_t type)
     }
 }
 
+/**
+ * @brief Handle the touch event on the AC page
+ * 
+ * @param type The type of the touch event
+ * @param component The component that the touch event occured
+ */
 void InternalDisplay::handleACTouch(uint8_t type, uint8_t component)
 {
     // b1 [component 18] -> inclement AC temperature by 1
@@ -565,6 +706,12 @@ void InternalDisplay::handleACTouch(uint8_t type, uint8_t component)
     }
 }
 
+/**
+ * @brief Handle the touch event on the PWM Adjustment page
+ * 
+ * @param type The type of the touch event
+ * @param component The component that the touch event occured
+ */
 void InternalDisplay::handlePWMAdjustmentTouch(uint8_t type, uint8_t component)
 {
     // b0 [component 5] -> decrement the PWM id if its greater than 0, else set it to 15
@@ -603,6 +750,9 @@ void InternalDisplay::handlePWMAdjustmentTouch(uint8_t type, uint8_t component)
     }
 }
 
+/**
+ * @brief Send data to display element on the network config page
+ */
 void InternalDisplay::refreshNetworkConfig()
 {
     // The network config page have the following components:
@@ -639,6 +789,9 @@ void InternalDisplay::refreshNetworkConfig()
     this->sendStopBytes();
 }
 
+/**
+ * @brief Send data to display element on the mqtt config page
+ */
 void InternalDisplay::refreshMQTTConfig()
 {
     // The MQTT config page have the following components:
@@ -679,6 +832,13 @@ void InternalDisplay::refreshMQTTConfig()
     this->sendStopBytes();
 }
 
+/**
+ * @brief Write an ip address to the display
+ * 
+ * @note This function only writes the ip address to the display, you need to send the prefix and suffix yourself
+ * 
+ * @param ip The ip address to send
+ */
 void InternalDisplay::sendIpToDisplay(IPAddress ip)
 {
     // Send the ip address
@@ -691,6 +851,15 @@ void InternalDisplay::sendIpToDisplay(IPAddress ip)
     this->displayAdapter->print(ip[3]);
 }
 
+/**
+ * @brief Handle the AC state change
+ * 
+ * @note This function is registered as a callback to the ClimateCard
+ * 
+ * @param mode The new mode
+ * @param fan_speed The new fan speed
+ * @param temperature The new temperature
+ */
 void InternalDisplay::handleACStateChange(uint8_t mode, uint8_t fan_speed, uint8_t temperature)
 {
     // If the climate card is binded to the display and the current page is the AC page

ESPMegaPRO-firmware/lib/ESPMegaPRO/InternalDisplay.hpp

@@ -65,6 +65,19 @@
 #define TOUCH_TYPE_PRESS 0x01
 #define TOUCH_TYPE_RELEASE 0x0
 
+/**
+ * @brief The internal display of the ESPMegaPRO
+ * 
+ * This is the display that is installed on some ESPMegaPRO Chassis. It is a 3.5" TFT LCD with a resistive touch screen.
+ * 
+ * You can use this display to monitor the status of the ESPMegaPRO and also to control the various components of the
+ * ESPMegaPRO. 
+ * 
+ * If you are using a custom display, you need to create a class that inherits from ESPMegaDisplay and implement the
+ * methods in that class, you may refer to this class for reference.
+ * 
+ * @note This class is automatically instantiated by the ESPMegaPRO and can be accessed via the `display` variable.
+ */
 class InternalDisplay : public ESPMegaDisplay {
     public:
         InternalDisplay(HardwareSerial *displayAdapter);