Web Server Comments

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 <ESPMegaWebServer.hpp>
 
+/**
+ * @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;
 }

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;

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