From f8661dd4a193437cfe986c6d62b04aeee1bbf81b Mon Sep 17 00:00:00 2001 From: Siwat Sirichai Date: Mon, 1 Jan 2024 12:56:52 +0700 Subject: [PATCH] Display Comment --- .../lib/ESPMegaPRO/InternalDisplay.cpp | 175 +++++++++++++++++- .../lib/ESPMegaPRO/InternalDisplay.hpp | 13 ++ 2 files changed, 185 insertions(+), 3 deletions(-) diff --git a/ESPMegaPRO-firmware/lib/ESPMegaPRO/InternalDisplay.cpp b/ESPMegaPRO-firmware/lib/ESPMegaPRO/InternalDisplay.cpp index 1fcb998..3f30965 100644 --- a/ESPMegaPRO-firmware/lib/ESPMegaPRO/InternalDisplay.cpp +++ b/ESPMegaPRO-firmware/lib/ESPMegaPRO/InternalDisplay.cpp @@ -1,5 +1,13 @@ #include +/** + * @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 getRtcTime) { this->iot = iot; @@ -20,6 +28,11 @@ void InternalDisplay::begin(ESPMegaIoT *iot, std::function 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] -// fan_speed: [auto, low, medium, high] +/** + * @brief Set the climate card to be be shown on the AC page + * + * 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 diff --git a/ESPMegaPRO-firmware/lib/ESPMegaPRO/InternalDisplay.hpp b/ESPMegaPRO-firmware/lib/ESPMegaPRO/InternalDisplay.hpp index aa65910..21d7ff3 100644 --- a/ESPMegaPRO-firmware/lib/ESPMegaPRO/InternalDisplay.hpp +++ b/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);