From 4fd8a0a7610ede3b8bfa490e67e85e026aba3c2d Mon Sep 17 00:00:00 2001 From: Siwat Sirichai Date: Mon, 1 Jan 2024 23:40:32 +0700 Subject: [PATCH] Web Server Comments --- .../lib/ESPMegaPRO/ESPMegaWebServer.cpp | 137 ++++++++++++++++++ .../lib/ESPMegaPRO/ESPMegaWebServer.hpp | 5 + ESPMegaPRO-firmware/platformio.ini | 2 +- 3 files changed, 143 insertions(+), 1 deletion(-) diff --git a/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaWebServer.cpp b/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaWebServer.cpp index a9ad3a3..83ff910 100644 --- a/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaWebServer.cpp +++ b/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaWebServer.cpp @@ -1,5 +1,20 @@ +/** + * @file ESPMegaWebServer.cpp + * @brief Implementation file for the ESPMegaWebServer class. + * + * This file contains the implementation of the ESPMegaWebServer class, which is responsible for handling web server functionality for the ESPMegaPRO firmware. + * The ESPMegaWebServer class provides methods for starting the web server, handling HTTP requests, and managing credentials and configurations. + */ #include +/** + * @brief Construct a new ESPMegaWebServer::ESPMegaWebServer objecy + * + * @note Although you can instantiate this class directly, it is recommended to use the ESPMegaPRO.webServer object instead. + * + * @param port The TCP port to listen on + * @param iot A pointer to the ESPMegaIoT object + */ ESPMegaWebServer::ESPMegaWebServer(uint16_t port, ESPMegaIoT *iot) { this->port = port; @@ -8,11 +23,22 @@ ESPMegaWebServer::ESPMegaWebServer(uint16_t port, ESPMegaIoT *iot) this->saveConfigHandler = new AsyncCallbackJsonWebHandler("/save_config", std::bind(&ESPMegaWebServer::saveConfigJSONHandler, this, std::placeholders::_1, std::placeholders::_2)); } +/** + * @brief Destroy the ESPMegaWebServer::ESPMegaWebServer object + */ ESPMegaWebServer::~ESPMegaWebServer() { delete this->server; } +/** + * @brief Start the web server + * + * This method starts the web server and registers the necessary handlers. + * + * @note This method should be called after the ESPMegaIoT object has been initialized. + * @note This method is automatically called if you use ESPMegaPRO::enableWebServer() + */ void ESPMegaWebServer::begin() { this->loadCredentialsFromFRAM(); @@ -27,16 +53,38 @@ void ESPMegaWebServer::begin() this->server->on("/ota_update", HTTP_POST, bindedOtaRequestHandler, bindedOtaUploadHandler); } +/** + * @brief The loop function for the web server + * + * @note This method is not used by the ESPMegaWebServer class as of now. + */ void ESPMegaWebServer::loop() { // AsyncWebServer doesn't have a loop function } +/** + * @brief Bind the FRAM object to the web server + * + * This method binds the FRAM object to the web server so that the web server can read and write credentials to the FRAM. + * + * @note The FRAM object must be bound to the web server before calling ESPMegaWebServer::begin() + * @note This class takes 64 bytes of FRAM starting from address 301, however address 301-400 is reserved for it. + * + * @param fram A pointer to the FRAM object + */ void ESPMegaWebServer::bindFRAM(FRAM *fram) { this->fram = fram; } +/** + * @brief Load web username and password from FRAM + * + * This method loads the web server credentials from the FRAM. + * + * @note This method is automatically called by ESPMegaWebServer::begin() + */ void ESPMegaWebServer::loadCredentialsFromFRAM() { this->fram->read(301, (uint8_t *)this->webUsername, 32); @@ -75,12 +123,24 @@ void ESPMegaWebServer::loadCredentialsFromFRAM() } } +/** + * @brief Save web username and password to FRAM + * + * This method saves the web server credentials to the FRAM. + */ void ESPMegaWebServer::saveCredentialsToFRAM() { this->fram->write(301, (uint8_t *)this->webUsername, 32); this->fram->write(333, (uint8_t *)this->webPassword, 32); } +/** + * @brief Reset web username and password to default + * + * This method resets the web server credentials to the default username and password. + * + * @note The default username and password is both "admin" + */ void ESPMegaWebServer::resetCredentials() { // The default username and password is "admin" @@ -89,26 +149,55 @@ void ESPMegaWebServer::resetCredentials() this->saveCredentialsToFRAM(); } +/** + * @brief Get the web username + * + * @warning The returned pointer should not be freed or modified. + * + * @return The web username + */ char *ESPMegaWebServer::getWebUsername() { return this->webUsername; } +/** + * @brief Get the web password + * + * @warning The returned pointer should not be freed or modified. + * + * @return The web password + */ char *ESPMegaWebServer::getWebPassword() { return this->webPassword; } +/** + * @brief Set the web username + * + * @param username The new web username + */ void ESPMegaWebServer::setWebUsername(const char *username) { strcpy(this->webUsername, username); } +/** + * @brief Set the web password + * + * @param password The new web password + */ void ESPMegaWebServer::setWebPassword(const char *password) { strcpy(this->webPassword, password); } +/** + * @brief Handle HTTP requests to the dashboard (/) page + * + * @param request The AsyncWebServerRequest object + */ void ESPMegaWebServer::dashboardHandler(AsyncWebServerRequest *request) { if (!request->authenticate(this->webUsername, this->webPassword)) @@ -119,6 +208,12 @@ void ESPMegaWebServer::dashboardHandler(AsyncWebServerRequest *request) request->send_P(200, "text/html", ota_html, bindedDashboardProcessor); } +/** + * @brief Replace placeholders in the dashboard HTML with values + * + * @param var The placeholder name + * @return The value to replace the placeholder with + */ String ESPMegaWebServer::dashboardProcessor(const String &var) { if (var == "hostname") @@ -157,6 +252,11 @@ String ESPMegaWebServer::dashboardProcessor(const String &var) return ""; } +/** + * @brief Handle HTTP requests to the config (/config) page + * + * @param request The AsyncWebServerRequest object + */ void ESPMegaWebServer::configHandler(AsyncWebServerRequest *request) { if (!request->authenticate(this->webUsername, this->webPassword)) @@ -167,6 +267,13 @@ void ESPMegaWebServer::configHandler(AsyncWebServerRequest *request) request->send_P(200, "text/html", config_html, bindedConfigProcessor); } +/** + * @brief Replace placeholders in the config HTML with values + * + * @param var The placeholder name + * + * @return The value to replace the placeholder with + */ String ESPMegaWebServer::configProcessor(const String &var) { MqttConfig *mqttConfig = this->iot->getMqttConfig(); @@ -226,6 +333,11 @@ String ESPMegaWebServer::configProcessor(const String &var) return ""; } +/** + * @brief Handle HTTP requests to the OTA update (/ota_update) page + * + * @param request The AsyncWebServerRequest object + */ void ESPMegaWebServer::otaRequestHandler(AsyncWebServerRequest *request) { // Prepare to receive firmware @@ -240,6 +352,16 @@ void ESPMegaWebServer::otaRequestHandler(AsyncWebServerRequest *request) ESP.restart(); } +/** + * @brief Handle HTTP upload session to the OTA update (/ota_update) page + * + * @param request The AsyncWebServerRequest object + * @param filename The filename of the firmware + * @param index The index of the firmware + * @param data The firmware data + * @param len The length of the firmware data + * @param final Whether this is the final chunk of firmware + */ void ESPMegaWebServer::otaUploadHandler(AsyncWebServerRequest *request, String filename, size_t index, uint8_t *data, size_t len, bool final) { // Receive firmware @@ -277,6 +399,12 @@ void ESPMegaWebServer::otaUploadHandler(AsyncWebServerRequest *request, String f } } +/** + * @brief Handle JSON POST requests to the save_config (/save_config) page + * + * @param request The AsyncWebServerRequest object + * @param json The JSON object representing the request body + */ void ESPMegaWebServer::saveConfigJSONHandler(AsyncWebServerRequest *request, JsonVariant &json) { /** @@ -376,4 +504,13 @@ void ESPMegaWebServer::saveConfigJSONHandler(AsyncWebServerRequest *request, Jso // Send response request->send(200, "text/plain", "OK"); ESP.restart(); +} + +/** + * @brief Get the AsyncWebServer object + * + * @return The AsyncWebServer object + */ +AsyncWebServer *ESPMegaWebServer::getServer() { + return this->server; } \ No newline at end of file diff --git a/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaWebServer.hpp b/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaWebServer.hpp index ed5de4d..00a4c9e 100644 --- a/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaWebServer.hpp +++ b/ESPMegaPRO-firmware/lib/ESPMegaPRO/ESPMegaWebServer.hpp @@ -12,6 +12,10 @@ /** * @brief Provides a web server for ESPMegaPRO * + * This class provides a web server for ESPMegaPRO. It is used to configure the device and to update the firmware. + * This class also allows to save the credentials to access the web server in the FRAM memory. + * User can also add custom endpoints to the web server. + * * This class use FRAM address 301-400 */ class ESPMegaWebServer @@ -29,6 +33,7 @@ class ESPMegaWebServer void bindFRAM(FRAM *fram); void loadCredentialsFromFRAM(); void saveCredentialsToFRAM(); + AsyncWebServer* getServer(); private: // FRAM FRAM *fram; diff --git a/ESPMegaPRO-firmware/platformio.ini b/ESPMegaPRO-firmware/platformio.ini index 4e216a6..c726d5b 100644 --- a/ESPMegaPRO-firmware/platformio.ini +++ b/ESPMegaPRO-firmware/platformio.ini @@ -31,5 +31,5 @@ lib_deps = adafruit/Adafruit PWM Servo Driver Library@^2.4.1 https://github.com/me-no-dev/ESPAsyncWebServer.git bblanchon/ArduinoJson@^6.21.4 monitor_speed = 115200 -build_flags = -DCORE_DEBUG_LEVEL=5 +build_flags = -DCORE_DEBUG_LEVEL=1 extra_scripts = pre:helper_scripts/html2cpp.py \ No newline at end of file