feat(hosted): Document inline the source code

Author: me-no-dev

libraries/ESP_HostedOTA/examples/ESP_HostedOTA/ESP_HostedOTA.ino

@@ -1,33 +1,62 @@
-#include "WiFi.h"
-#include "ESP_HostedOTA.h"
+/*
+ * ESP-Hosted OTA Update Example
+ * 
+ * This example demonstrates how to update the ESP-Hosted co-processor firmware
+ * over-the-air (OTA). The ESP-Hosted solution allows an ESP32 to act as a WiFi
+ * co-processor for other microcontrollers.
+ * 
+ * Prerequisites:
+ * - ESP32 with ESP-Hosted firmware configured as WiFi co-processor
+ * - Network connectivity to download firmware updates
+ * - Valid WiFi credentials
+ */
 
-const char *ssid = "your-ssid";          // Change this to your WiFi SSID
-const char *password = "your-password";  // Change this to your WiFi password
+#include "WiFi.h"           // WiFi library for network connectivity
+#include "ESP_HostedOTA.h"  // ESP-Hosted OTA update functionality
+
+// WiFi network credentials - CHANGE THESE TO YOUR NETWORK SETTINGS
+const char *ssid = "your-ssid";          // Replace with your WiFi network name
+const char *password = "your-password";  // Replace with your WiFi password
 
 void setup() {
+  // Step 1: Initialize serial communication for debugging output
   Serial.begin(115200);
 
+  // Step 2: Initialize the ESP-Hosted WiFi station mode
+  // This prepares the ESP-Hosted co-processor for WiFi operations
   WiFi.STA.begin();
 
+  // Step 3: Display connection attempt information
   Serial.println();
   Serial.println("******************************************************");
   Serial.print("Connecting to ");
   Serial.println(ssid);
 
+  // Step 4: Attempt to connect to the specified WiFi network
   WiFi.STA.connect(ssid, password);
 
+  // Step 5: Wait for WiFi connection to be established
+  // Display progress dots while connecting
   while (WiFi.STA.status() != WL_CONNECTED) {
-    delay(500);
-    Serial.print(".");
+    delay(500);           // Wait 500ms between connection attempts
+    Serial.print(".");    // Show connection progress
   }
   Serial.println();
 
+  // Step 6: Display successful connection information
   Serial.println("WiFi connected");
   Serial.print("IP address: ");
   Serial.println(WiFi.STA.localIP());
 
+  // Step 7: Attempt to update the ESP-Hosted co-processor firmware
+  // This function will:
+  // - Check if ESP-Hosted is initialized
+  // - Verify if an update is available
+  // - Download and install the firmware update if needed
   if (updateEspHostedSlave()) {
-  	// Currently it's required to restart the host
+    // Step 8: Restart the host ESP32 after successful update
+    // This is currently required to properly activate the new firmware
+    // on the ESP-Hosted co-processor
     ESP.restart();
   }
 }

libraries/ESP_HostedOTA/src/ESP_HostedOTA.cpp

@@ -1,105 +1,159 @@
+// Include necessary headers for SDK configuration, Arduino framework, and networking
 #include "sdkconfig.h"
 #include <stdbool.h>
 #if CONFIG_ESP_WIFI_REMOTE_ENABLED
 #include "Arduino.h"
-#include "esp32-hal-hosted.h"
-#include "Network.h"
-#include "HTTPClient.h"
-#include "NetworkClientSecure.h"
+#include "esp32-hal-hosted.h"  // ESP-Hosted specific functions
+#include "Network.h"           // Network connectivity management
+#include "HTTPClient.h"        // HTTP client for downloading updates
+#include "NetworkClientSecure.h" // Secure network client for HTTPS
 #endif
 
+/**
+ * Updates the ESP-Hosted co-processor firmware over-the-air (OTA)
+ * This function downloads and installs firmware updates for the ESP-Hosted slave device
+ * @return true if update was successful, false otherwise
+ */
 bool updateEspHostedSlave() {
 #if CONFIG_ESP_WIFI_REMOTE_ENABLED
   bool updateSuccess = false;
+  
+  // Step 1: Verify ESP-Hosted is properly initialized
   if (!hostedIsInitialized()) {
     Serial.println("ERROR: esp-hosted is not initialized. Did you call WiFi.STA.begin()?");
     return updateSuccess;
   }
+  
+  // Step 2: Check if an update is actually available
   if (!hostedHasUpdate()) {
-    // esp-hosted is already the latest version
+    // esp-hosted is already the latest version - no update needed
     return updateSuccess;
   }
+  
+  // Step 3: Ensure network connectivity is available
   if (!Network.isOnline()) {
     Serial.println("ERROR: Network is not online! Did you call WiFi.STA.connect(ssid, password)?");
     return updateSuccess;
   }
+  
+  // Step 4: Begin the update process - display update URL
   Serial.print("Updating esp-hosted co-processor from ");
   Serial.println(hostedGetUpdateURL());
+  
+  // Step 5: Create a secure network client for HTTPS communication
   NetworkClientSecure *client = new NetworkClientSecure();
   if (!client) {
     Serial.println("ERROR: Could not allocate client!");
     return updateSuccess;
   }
+  
+  // Step 6: Configure client to skip certificate verification (insecure mode)
   client->setInsecure();
+  
+  // Step 7: Initialize HTTP client and attempt to connect to update server
   HTTPClient https;
   int httpCode = 0;
   if (!https.begin(*client, hostedGetUpdateURL())) {
     Serial.println("ERROR: HTTP begin failed!");
     goto finish_ota;
   }
+  
+  // Step 8: Send HTTP GET request to download the firmware
   httpCode = https.GET();
   if (httpCode == HTTP_CODE_OK) {
+    // Step 9: Get the size of the firmware file to download
     int len = https.getSize();
     if (len < 0) {
       Serial.println("ERROR: Update size not received!");
       https.end();
       goto finish_ota;
     }
+    
+    // Step 10: Get stream pointer for reading firmware data
     NetworkClient *stream = https.getStreamPtr();
+    
+    // Step 11: Initialize the ESP-Hosted update process
     if (!hostedBeginUpdate()) {
       Serial.println("ERROR: esp-hosted update start failed!");
       https.end();
       goto finish_ota;
     }
+    
+    // Step 12: Allocate buffer for firmware data transfer (2KB chunks)
     #define HOSTED_OTA_BUF_SIZE 2048
     uint8_t * buff = (uint8_t*)malloc(HOSTED_OTA_BUF_SIZE);
     if (!buff) {
       Serial.println("ERROR: Could not allocate OTA buffer!");
       https.end();
       goto finish_ota;
     }
+    
+    // Step 13: Download and write firmware data in chunks
     while (https.connected() && len > 0) {
       size_t size = stream->available();
       if (size > 0) {
+        // Show progress indicator
         Serial.print(".");
+        
+        // Limit chunk size to buffer capacity
         if (size > HOSTED_OTA_BUF_SIZE) {
           size = HOSTED_OTA_BUF_SIZE;
         }
+        
+        // Prevent reading more data than expected
         if (size > len) {
           Serial.printf("\nERROR: Update received extra bytes: %u!", size - len);
           break;
         }
+        
+        // Read firmware data chunk into buffer
         int readLen = stream->readBytes(buff, size);
         len -= readLen;
+        
+        // Write the chunk to ESP-Hosted co-processor
         if (!hostedWriteUpdate(buff, readLen)) {
           Serial.println("\nERROR: esp-hosted update write failed!");
           break;
         }
+        
+        // Step 14: Check if entire firmware has been downloaded
         if (len == 0) {
+          // Finalize the update process
           if (!hostedEndUpdate()) {
             Serial.println("\nERROR: esp-hosted update end failed!");
             break;
           }
+          
+          // Activate the new firmware
           if (!hostedActivateUpdate()) {
             Serial.println("\nERROR: esp-hosted update activate failed!");
             break;
           }
+          
+          // Update completed successfully
           updateSuccess = true;
           Serial.println("\nSUCCESS: esp-hosted co-processor updated!");
           break;
         }
       }
+      // Small delay to prevent overwhelming the system
       delay(1);
     }
+    
+    // Step 15: Clean up allocated buffer
     free(buff);
     Serial.println();
   }
 
+  // Step 16: Close HTTP connection
   https.end();
+  
 finish_ota:
+  // Step 17: Clean up network client
   delete client;
   return updateSuccess;
 #else
+  // ESP-Hosted functionality is not enabled in SDK configuration
   return false;
 #endif
 }

libraries/ESP_HostedOTA/src/ESP_HostedOTA.h

@@ -2,4 +2,9 @@
 
 #include <stdbool.h>
 
+/**
+ * Updates the ESP-Hosted co-processor firmware over-the-air (OTA)
+ * This function downloads and installs firmware updates for the ESP-Hosted slave device
+ * @return true if update was successful, false otherwise
+ */
 bool updateEspHostedSlave();