Merge branch 'arduino:main' into useSymlink

Author: todateman

.gitignore

@@ -9,3 +9,4 @@ cores/arduino/mydebug.cpp.donotuse
 .DS_Store?
 /.vs
 /.gitignore
+.vscode/settings.json

libraries/WiFiS3/docs/api.md

@@ -15,31 +15,106 @@
 
 #define DO_NOT_CHECK_CMD "NO_CMD_CHECK"
 
+/**
+ * @brief A class that provides methods to interact with a modem.
+ * 
+ * This class is responsible for providing an interface to communicate with
+ * a modem through serial communication. It includes methods for initialization, 
+ * sending and receiving data, and handling modem configurations.
+ */
 class ModemClass {
 
 public:
+  /** 
+   * @brief Constructor for the ModemClass, which initializes the modem with the specified transmit (TX) and receive (RX) pins.
+   * 
+   * @param Initializes an instance of the ModemClass class with
+   * specific transmit `tx` and receive `rx` pins for communication.
+   */
   ModemClass(int tx, int rx);
+
+  /**
+   * @brief Constructor for the ModemClass, which initializes the modem with the specified UART interface.
+   *
+   * @param `_serial` is a pointer to the UART object that will be used for communication with the modem.
+   */
   ModemClass(UART * _serial);
+
+  /**
+   * @brief Destructor for ModemClass.
+   */
   ~ModemClass();
 
+
+  /**
+   * @brief Initializes the modem communication with a specified baud rate.
+   * 
+   * @param[in] `badurate` sets the baud rate for the serial connection.
+   */
   void begin(int badurate = 115200, int retry = 3);
+
+  /** 
+   * @brief Ends the modem communication.
+   */
   void end();
+
+
+  /**
+   * @brief Sends a formatted command string to a device and stores the response.
+   *
+   * This function formats a command string using the provided format and arguments, 
+   * sends it to a device, and waits for a response, which is stored in the `str` string.
+   *
+   * @param `cmd` A string representing the command to be sent to the device.
+   * @param `str` A reference to a string that will hold the device's response.
+   * @param `fmt` A format string for constructing the command.
+   * 
+   * @return `true` if the command was successfully sent and a response was received, 
+   * `false` otherwise.
+   */
   bool write(const std::string &cmd, std::string &str, const char * fmt, ...);
+
+  /**
+   * @brief Used to send a command to the modem without waiting for a response.
+   * 
+   * @param It takes a command string `cmd`, a string `str` where the response will be stored,
+   * and a format string `fmt` along with additional arguments.
+   */
   void write_nowait(const std::string &cmd, std::string &str, const char * fmt, ...);
 
+  /**
+   * @brief Sends binary data directly to the modem without any processing or interpretation.
+   * 
+   * @param It takes a pointer to the binary `data` and the `size` of the data as arguments.
+   * Used for sending raw binary commands or data to the modem for operations that 
+   * require direct communication without any additional formatting or parsing.
+   */
   bool passthrough(const uint8_t *data, size_t size);
+
+  /**
+   * @brief Disables automatic trimming of results for one operation.
+   * 
+   * This function disables the automatic trimming of results for one operation. 
+   * After it is called, the results will not be trimmed automatically until 
+   * the function is called again.
+   */
   void avoid_trim_results() {
     /* one shot - it works only 1 time the it is necessary to call again this
        funtion */
     trim_results = false;
   }
 
+  /**
+   * @brief Enables a specific mode of reading where the size of the data
+   * to be read is considered for processing.
+   */
   void read_using_size() {
     // read_by_size = true; // deprecated
   }
+  
   bool beginned;
 
-  /* calling this function with no argument will enable debug message to be printed
+  /* Calling this function with no argument will enable debug message to be printed
      on Serial
      use first parameter UART *u to redirect debug output to a different serial
 
@@ -54,6 +129,9 @@ class ModemClass {
     _debug_level = level;
   }
 
+  /**
+   * @brief Used to disable debugging output for the modem communication.
+   */
   void noDebug() {
     _serial_debug = nullptr;
   }
@@ -63,6 +141,11 @@ class ModemClass {
   void debug(bool e) {enable_dbg = e;}
   #endif
 
+  /**
+   * @brief Sets the timeout value for communication operations.
+   * 
+   * @param Can be called with a specified timeout value in milliseconds.
+   */
   void timeout(size_t timeout_ms) {_timeout = timeout_ms;}
 
 private:

libraries/WiFiS3/src/Modem.h

@@ -5,16 +5,69 @@
 #include <vector>
 #include <algorithm>
 
+/**
+ * @brief Trims whitespace characters from the beginning of a string. 
+ * 
+ * @param `s` is the string from which leading whitespace characters will be removed. 
+ * The function modifies this string directly.
+ */
 void ltrim(std::string &s);
 
-// trim from end (in place)
+/**
+ * @brief Trims trailing whitespace characters from a string.
+ *
+ * @param `s` the string from which trailing whitespace characters will be removed. 
+ * The function modifies this string directly.
+ */
 void rtrim(std::string &s);
 
-// trim from both ends (in place)
+
+/**
+ * @brief Trims whitespace characters from both ends of a string.
+ *
+ * This function removes any leading and trailing whitespace characters (spaces, 
+ * tabs, etc.) from the given string. It modifies the string in place, erasing 
+ * whitespace from both the beginning and the end of the string.
+ *
+ * @param `s` is the string from which both leading and trailing whitespace characters 
+ * will be removed. The function modifies this string directly.
+ */
 void trim(std::string &s);
 
+/**
+ * @brief Takes a string and splits it into substrings.
+ * 
+ * This function splits a string into multiple substrings, storing each substring 
+ * as an element in the `res` vector. The string is split at each occurrence of 
+ * the specified delimiter. Optionally, the function can trim whitespace from 
+ * each token before storing it in the result vector.
+ * 
+ * @param `res` is a reference to a vector of strings where the resulting tokens 
+ * will be stored.
+ * @param `str` is the string to be split. This string will be modified as it is 
+ * split.
+ * @param `delimiter` is the delimiter string that separates the tokens in `str`.
+ * @param `_trim` is a boolean flag indicating whether to trim whitespace from each 
+ * token. If true, leading and trailing whitespace will be removed from each token. Defaults to true.
+ */
 void split(std::vector<std::string> &res, std::string &str, const std::string &delimiter, bool _trim = true);
 
+/** 
+ * @brief Removes a specified substring from the beginning of a string.
+ *
+ * This function attempts to remove the first occurrence of the specified substring 
+ * (`what`) from the beginning of the string (`str`). Before performing the removal, 
+ * it trims leading whitespace from the string. If the substring is found at the 
+ * beginning of the string, it is removed, and the function returns `true`. Otherwise the 
+ * function returns `false`.
+ *
+ * @param `str` is a reference to the string from which the substring will be removed. 
+ * The string is modified if the substring is removed.
+ * @param `what` is the substring to be removed from the beginning of `str`.
+ * 
+ * @return `true` if the substring was found and removed from the beginning of 
+ * the string, `false` otherwise.
+ */
 bool removeAtBegin(std::string &str, const std::string &what);
 
 #endif

libraries/WiFiS3/src/StringHelpers.h

@@ -397,7 +397,6 @@ IPAddress CWifi::localIP() {
 /* -------------------------------------------------------------------------- */
    modem.begin();
    string res = "";
-   int attempts = 0;
    IPAddress local_IP(0,0,0,0);
 
    if(modem.write(string(PROMPT(_MODE)),res, "%s" , CMD_READ(_MODE)))  {

libraries/WiFiS3/src/WiFi.cpp

@@ -30,42 +30,220 @@
 #include "FifoBuffer.h"
 #include <memory>
 
+
+/**
+ * @brief Represents a Wi-Fi client that connects to a remote server over a Wi-Fi network.
+ * 
+ * The WiFiClient class allows for network communication over Wi-Fi, providing methods 
+ * for establishing connections, sending and receiving data, and managing the client’s 
+ * socket state. This class is used to manage client connections in a Wi-Fi network, 
+ * either for communication or for network data transfer.
+ * 
+ * It inherits from the Client class, providing basic socket communication functionality.
+ */
 class WiFiClient : public Client {
 
 public:
+  /**
+   * @brief Default constructor for the WiFiClient class.
+   */
   WiFiClient();
+
   /* this constructor is not intended to be called outside of the Server class */
+  /**
+   * @brief Constructor to initialize a WiFiClient object with a specific socket.
+   *
+   * @param `s` is the socket descriptor to associate with this client.
+   */
   WiFiClient(int s);
+
+  /**
+   * @brief Copy constructor for the WiFiClient class.
+   *
+   * @param `c` is the `WiFiClient` object to copy.
+   */
   WiFiClient(const WiFiClient& c);
+
+  /**
+   * @brief Destructor for the WiFiClient class.
+   */
   ~WiFiClient();
+
+  /**
+   * @brief Establishes a connection to a server using an IP address and port.
+   *
+   * @param `ip` as the IP address of the server to connect to.
+   * @param `port` as the port number on the server to connect to.
+   * 
+   * @return `1` on a successful connection, `0` on failure.
+   */
   virtual int connect(IPAddress ip, uint16_t port);
+
+  /**
+   * @brief Establishes a connection to a server using a hostname and port.
+   * 
+   * @param `host` is a pointer to a null-terminated string containing the hostname of the server.
+   * @param `port` is the port number on the server to connect to.
+   * 
+   * @return `1` if the connection was successful, `0` otherwise.
+   */
   virtual int connect(const char *host, uint16_t port);
+
+  /** 
+   * @brief Sends a single byte of data to the connected server.
+   *
+   * @param `b` being the byte of data to send.
+   * 
+   * @return The number of bytes successfully written, which is `1` on success or `0` on failure.
+   */
   virtual size_t write(uint8_t);
+
+  /** 
+   * @brief Writes a buffer of data to the connected server.
+   * 
+   * @param Takes a pointer to a buffer `buf` containing the data to be written
+   * and the size of the buffer `size` as parameters.
+   * 
+   * @return The number of bytes successfully written, or `0` if the write operation fails.
+   */
   virtual size_t write(const uint8_t *buf, size_t size);
+
+  /**
+   * @brief Checks the number of bytes available for reading from the server.
+   *
+   * @return The number of bytes available to read. Returns `0` if no data is 
+   * available, or if the socket is invalid.
+   */
   virtual int available();
+
+  /**
+   * @brief Reads a single byte of data from the server.
+   *
+   * @return The byte read as an `int` (0–255). Returns `-1` if no data is available 
+   * or if an error occurs.
+   */
   virtual int read();
+
+  /**
+   * @brief Reads multiple bytes of data from the server into a buffer.
+   *
+   * This function retrieves data from the server's receive buffer and stores it 
+   * into the provided array. It attempts to read up to the specified number of 
+   * bytes (`size`).
+   *
+   * @param[out] `buf` is a pointer to the buffer where the data will be stored.
+   * @param[in] `size` is the maximum number of bytes to read.
+   *
+   * @return The number of bytes successfully read into the buffer. 
+   * Returns `0` if no data is available or if the socket is invalid.
+   */
   virtual int read(uint8_t *buf, size_t size);
+
+  /**
+   * @brief Peeks at the next byte of incoming data without removing it from the internal buffer.
+   * 
+   * @return The next byte as an `int` (0–255). Returns `-1` if no data is available 
+   * or if the socket is invalid.
+   */
   virtual int peek();
+
+  /**
+   * @brief Flushes the write buffer of the client.
+   * 
+   * This function ensures that any data buffered for transmission is sent to the
+   * connected server. If there is any pending data in the send buffer, it is 
+   * transmitted over the network.
+   */
   virtual void flush();
+
+  /**
+   * @brief Closes the connection to the server and clears the receive buffer.
+   */
   virtual void stop();
+
+  /**
+   * @brief Checks if the client is connected to a server.
+   * 
+   * @return Returns 1 if the client is connected, 0 otherwise.
+   */
   virtual uint8_t connected();
+
+  /**
+   * @brief Implicit conversion operator to `bool`.
+   * 
+   * Converts the `WiFiClient` object to a `bool` value indicating whether the client 
+   * is connected or not.
+   * 
+   * @return `true` if the client socket is open and valid, `false` otherwise.
+   */
   virtual operator bool() {
     return _sock != -1;
   }
+
+  /**
+   * @brief Equality operator for comparing two `WiFiClient` objects.
+   * 
+   * Compares the current `WiFiClient` object with another `WiFiClient` object
+   * to determine if they represent the same socket connection.
+   * 
+   * @param The `WiFiClient` object to compare with.
+   * @return `true` if both `WiFiClient` objects represent the same socket, 
+   * `false` otherwise.
+   */
   virtual bool operator==(const WiFiClient&);
+
+  /**
+   * @brief Inequality operator for comparing two `WiFiClient` objects.
+   * 
+   * Compares the current `WiFiClient` object with another `WiFiClient` object
+   * to determine if they represent different socket connections.
+   * 
+   * @param `whs` is the `WiFiClient` object to compare with.
+   * @return `true` if both WiFiClient objects represent different sockets, 
+   * `false` if they represent the same socket.
+   */
   virtual bool operator!=(const WiFiClient& whs)
   {
       return !this->operator==(whs);
   };
+
+  /**
+   * @brief Retrieves the remote IP address of the server the client is connected to.
+   * 
+   * @return The IP address of the remote server. If not connected, returns IPAddress(0, 0, 0, 0).
+   */
   virtual IPAddress remoteIP();
+
+  /**
+   * @brief Retrieves the remote port number of the server the client is connected to.
+   * 
+   * @return Returns the port number of the remote server. If not connected, returns 0.
+   */
   virtual uint16_t remotePort();
 
+  /**
+   * @brief Sets the connection timeout for the client.
+   * 
+   * @param `timeout` is the timeout value in milliseconds.
+   */
   void setConnectionTimeout(int timeout) {
     _connectionTimeout = timeout;
   }
 
+  /**
+   * @brief Declares WiFiServer as a friend class.
+   * 
+   * This allows the WiFiServer class to access private and protected members 
+   * of the WiFiClient class.
+   */
   friend class WiFiServer;
 
+  /**
+   * @brief Inherits the `write` method from the `Print` class.
+   * 
+   * This allows the WiFiSSLClient class to use the `write` method defined in the 
+   * `Print` class.
+   */
   using Print::write;
 
 protected:

libraries/WiFiS3/src/WiFi.h

@@ -24,12 +24,49 @@
 #include "WiFiCommands.h"
 #include "Modem.h"
 
+/**
+ * @brief Class that handles the WiFi file system operations.
+ * 
+ * This class provides functionality for managing files on a WiFi-connected 
+ * device, including mounting, reading, writing, and configuring the file system. 
+ */
 class WiFiFileSystem {
 
 public:
+   /**
+    * @brief Initializes objects of the WiFiFileSystem class.
+    */
    WiFiFileSystem();
+
+   /**
+    * @brief Mounts the file system and optionally formats it on failure.
+    *
+    * @param If `format_on_fault` is set to `true`,
+    * the file system will be formatted if a fault occurs during mounting.
+    */
    void mount(bool format_on_fault = false);
+
+   /**
+    * @brief Writes data to a file in the file system.
+    *
+    * @param `name` is the name of the file to which the data will be written.
+    * A pointer `data` to the data that will be written to the file.
+    * `size` is the number of bytes to write from the provided data buffer.
+    * `operation` determines the type of file operation to perform (e.g., create, overwrite).
+    * 
+    * @return Returns the number of bytes successfully written. Returns 0 if the operation fails.
+    */
    size_t writefile(const char* name, const char* data, size_t size, int operation = WIFI_FILE_WRITE);
+
+   /**
+    * @brief Reads a file from the file system and prints its content.
+    * 
+    * It sends the read request to the modem, which fetches the data. The content 
+    * is printed to the serial output in chunks, with each chunk being processed 
+    * until the entire file is read. 
+    * 
+    * @param `name` is the name of the file to be read from the file system.
+    */
    void readfile(const char* name);
 
 };

libraries/WiFiS3/src/WiFiClient.h

@@ -25,38 +25,215 @@
 #include "Modem.h"
 #include "WiFiFileSystem.h"
 
-
+/**
+ * @brief A specialized client class for secure SSL/TLS connections.
+ * 
+ * The WiFiSSLClient class extends the functionality of the WiFiClient class to provide secure
+ * communication over SSL/TLS protocols. It ensures encrypted and authenticated communication
+ * between the client and a remote server.
+ */
 class WiFiSSLClient : public WiFiClient {
 
 public:
+   /**
+    * @brief Initializes objects of the WiFiSSLClient class.
+    */
    WiFiSSLClient();
    ~WiFiSSLClient();
+
+   /**
+    * @brief Establishes a secure SSL connection to a specified IP address and port.
+    * 
+    * @param It takes an `IPAddress` object representing the IP address of the server
+    * and a `uint16_t` port number as parameters.
+    *
+    * @return Returns a status code indicating the success or failure of the 
+    * connection.
+    */
    virtual int connect(IPAddress ip, uint16_t port);
+
+   /**
+    * @brief Establishes a secure SSL connection to a specified host and port.
+    * 
+    * @param `host` is the hostname or IP address of the server to connect to.
+    * `port` is the port number to connect to.
+    * 
+    * @return Returns `1` if the connection is successfully established, `0` otherwise.
+    */
    virtual int connect(const char* host, uint16_t port);
+
+   /**
+    * @brief Sets the Certificate Authority (CA) for SSL/TLS verification.
+    *
+    * @param `root_ca` is a pointer to a null-terminated string containing the root 
+    * CA certificate in PEM format. If set to `nullptr`, the default root 
+    * CA bundle will be used.
+    */
    void setCACert(const char* root_ca);
+
+   /**
+    * @brief Sets the ECC (Elliptic Curve Cryptography) key slot and 
+    * certificate for establishing secure SSL connections.
+    * 
+    * @param `int ecc508KeySlot` specifies the ECC key slot to be used for the SSL connection.
+    * @param `const byte cert[]` is a pointer to the certificate data in the form of an array of bytes.
+    * @param `int certLength` specifies the length of the certificate data array.
+    */
    void setEccSlot(int ecc508KeySlot, const byte cert[], int certLength);
+   
+   /**
+    * @brief Writes a single byte of data to the SSL connection.
+    * 
+    * @param `b` is the byte to be sent.
+    * 
+    * @return The number of bytes successfully written. Returns `1` if the byte 
+    * was sent successfully, or `0` if an error occurred.
+    */
    virtual size_t write(uint8_t);
+
+   /**
+    * @brief Writes a buffer of data to the SSL connection.
+    *
+    * @param `buf` is a pointer to the buffer containing the data to be sent.
+    * @param `size` is the number of bytes to send from the buffer.
+    *
+    * @return Returns `size` if the data is successfully sent, 
+    * or `0` if the transmission fails or the socket is invalid.
+    */
    virtual size_t write(const uint8_t *buf, size_t size);
+   
+   /**
+    * @brief Checks the number of bytes available for reading from the SSL connection.
+    * 
+    * @return Returns the number of bytes available to read from the SSL connection without blocking.
+    */
    virtual int available();
+
+   /**
+    * @brief Reads data from the SSL connection into the receive buffer.
+    *
+    * @return Returns the number of bytes successfully read into the buffer. Returns 
+    * `0` if no data is received, or `-1` if the socket is invalid or an error occurs.
+    */
    virtual int read();
+
+   /**
+    * @brief Reads a specified number of bytes from the SSL connection into a buffer.
+    *
+    * @param `buf` is a pointer to the buffer where the read data will be stored.
+    * `size` is the maximum number of bytes to read into the buffer.
+    *
+    * @return The number of bytes successfully read. Returns `0` if no data is 
+    * available or an error occurs.
+    */
    virtual int read(uint8_t *buf, size_t size);
+
+   /**
+    * @brief Peeks at the next byte available from the SSL connection without removing it.
+    *
+    * This function queries the modem to retrieve the next byte available in the 
+    * SSL/TLS connection, allowing the byte to remain in the buffer for future reads.
+    *
+    * @return The next byte available as an integer value (0–255), or `-1` if 
+    * the socket is invalid or no data is available.
+    */
    virtual int peek();
+
+   /**
+    * @brief Flushes the write buffer of the SSL connection.
+    * 
+    * This function clears the write buffer, ensuring that any pending data is sent 
+    * over the SSL/TLS connection. It uses the modem to handle the flush operation.
+    */
    virtual void flush();
+
+   /**
+    * @brief Terminates the SSL/TLS connection and clears the receive buffer.
+    */
    virtual void stop();
+
+   /**
+    * @brief Checks if the SSL/TLS connection is active.
+    *
+    * This function determines if the SSL/TLS client is still connected by querying 
+    * the modem for the connection status. It checks the validity of the socket 
+    * before proceeding with the query.
+    *
+    * @return Returns `1` if the client is connected, `0` otherwise.
+    */
    virtual uint8_t connected();
+
+   /**
+    * @brief Implicit conversion operator to check if the SSL client is connected.
+    * 
+    * @return `true` if the socket is valid (i.e., connected), `false` otherwise.
+    */
    virtual operator bool() {
       return _sock != -1;
    }
+
+   /**
+    * @brief Comparison operator to check equality between two `WiFiSSLClient` objects.
+    * 
+    * @param `WiFiSSLClient` object to compare.
+    * 
+    * @return `true` if both WiFiSSLClient objects are equivalent (i.e., they have the same socket),
+    * `false` otherwise.
+    */
    virtual bool operator==(const WiFiSSLClient&);
+
+   /**
+    * @brief Inequality operator to compare two `WiFiSSLClient` objects.
+    * 
+    * This operator compares the current `WiFiSSLClient` object with another `WiFiSSLClient` object
+    * to determine if they are not equal, based on their underlying socket or connection.
+    * 
+    * @param `whs` The WiFiSSLClient object to compare with.
+    * @return `true` if the two WiFiSSLClient objects do not represent the same connection (i.e., have different sockets),
+    * `false` otherwise.
+    */
    virtual bool operator!=(const WiFiSSLClient& whs)
    {
       return !this->operator==(whs);
    };
+
+   /**
+    * @brief Retrieves the remote IP address of the WiFi SSL client.
+    *
+    * This function queries the modem for the remote IP address associated with 
+    * the current connection.
+    *
+    * @return The remote IP address of the client. Returns `0.0.0.0` if the 
+    * socket is not valid or the query fails.
+    */
    virtual IPAddress remoteIP();
+
+   /**
+    * @brief Retrieves the remote port number of the WiFi SSL client.
+    *
+    * This function queries the modem to obtain the remote port number associated 
+    * with the current connection.
+    *
+    * @return Returns the remote port number of the client. Returns `0` if the socket 
+    * is not valid or the query fails.
+    */
    virtual uint16_t remotePort();
 
+
+   /**
+    * @brief Declares WiFiServer as a friend class.
+    * 
+    * This allows the WiFiServer class to access private and protected members 
+    * of the WiFiSSLClient class.
+    */
    friend class WiFiServer;
 
+   /**
+    * @brief Inherits the `write` method from the Print class.
+    * 
+    * This allows the WiFiSSLClient class to use the `write` method defined in the 
+    * Print class.
+    */
    using Print::write;
 
 private:

libraries/WiFiS3/src/WiFiFileSystem.h

@@ -26,32 +26,148 @@
 #include "WiFiClient.h"
 
 
-
+/**
+ * @brief A class that provides server functionality for WiFi-based communication.
+ * 
+ * The WiFiServer class inherits from the Server class and extends its functionality 
+ * to create and manage a server over a WiFi connection. This class allows for accepting 
+ * incoming client connections, handling data communication, and closing connections 
+ * in a networked environment.
+ */
 class WiFiServer : public Server {
 private:
   int _sock;
   int _port;
   WiFiClient client;
 
 public:
+  /**
+   * @brief Initializes objects of the WiFiServer class.
+   */
   WiFiServer();
+
+  /**
+   * @brief Constructs a WiFiServer object with the specified port.
+   * 
+   * @param `p` The port number on which the server will listen for incoming connections.
+   */
   WiFiServer(int p);
+
+  /**
+   * @brief Checks if there are any incoming client connections waiting to be accepted.
+   * 
+   * This function queries the server to check if there is a client waiting to be 
+   * accepted. If a client is available, it returns a `WiFiClient` object representing 
+   * the client. It uses the modem to query the server for an available client 
+   * socket and accepts the connection if a valid client is found.
+   *
+   * @return Returns a WiFiClient object representing the next client connection that is available
+   * for processing.
+   */
   WiFiClient available();
+
+  /**
+   * @brief Accepts an incoming client connection on the server.
+   * 
+   * @return Returns a WiFiClient object representing the accepted client.
+   */
   WiFiClient accept();
+
+  /**
+   * @brief Starts the Wi-Fi server and binds it to the specified port.
+   * 
+   * @param `port` is the port number which the server will listen to for incoming connections.
+   */
   void begin(int port);
+  
+  /**
+   * @brief Starts the Wi-Fi server and binds it to the default port.
+   *
+   * This function initializes the server and binds it to a default port.
+   */
   void begin();
+
+  /**
+  * @brief Writes a single byte to all connected clients.
+  *
+  * @param `b` is the byte to be sent to the clients.
+  */
   virtual size_t write(uint8_t);
+
+  /**
+   * @brief Writes data to all connected clients.
+   *
+   * This function sends a buffer of data to all clients connected to the server. 
+   * It writes the specified number of bytes to the server 
+   * socket and returns the count of successfully written bytes.
+   *
+   * @param `buf` is a pointer to the buffer containing the data to be sent.
+   * `size` is the number of bytes to write from the buffer.
+   * 
+   * @return The number of bytes successfully written. Returns 0 if the 
+   * data could not be sent.
+   */
   virtual size_t write(const uint8_t *buf, size_t size);
+
+  /**
+   * @brief Ends the Wi-Fi server and closes the server socket.
+   *
+   * This function terminates the server by sending a command to the modem to 
+   * close the server socket. It sets the server socket variable to an invalid 
+   * state (`-1`) to indicate that the server is no longer active.
+   *
+   */
   void end();
+
+  /**
+   * @brief Converts the WiFiSSLClient object to a boolean value.
+   * 
+   * This operator allows a WiFiSSLClient object to be implicitly or explicitly
+   * converted to a boolean. It checks whether the client socket is valid (i.e., 
+   * `_sock != -1`).
+   * 
+   * @return `true` if the server socket is valid (server is running), `false` otherwise.
+   */
   explicit operator bool();
+
+  /**
+   * @brief Compares two WiFiServer objects for equality.
+   * 
+   * This virtual operator compares the underlying socket (`_sock`) of two `WiFiServer` 
+   * objects to determine if they refer to the same server connection.
+   * 
+   * @param WiFiServer object to compare against.
+   * 
+   * @return `true` if both WiFiServer objects have the same socket; `false` otherwise.
+   */
   virtual bool operator==(const WiFiServer&);
+
+  /**
+   * @brief Compares two WiFiServer objects for inequality.
+   * 
+   * This virtual operator compares the underlying socket (`_sock`) of two WiFiServer
+   * objects. It returns `true` if the objects do not refer to the same server connection 
+   * (i.e., they have different socket values), and `false` otherwise.
+   * 
+   * @param `whs` The WiFiServer object to compare against.
+   * @return `true` if the WiFiServer objects have different sockets; `false` otherwise.
+   */
   virtual bool operator!=(const WiFiServer& whs)
   {
     return !this->operator==(whs);
   };
 
+  /**
+   * @brief Inherits the `write` method from the `Print` class.
+   * 
+   * This allows the WiFiSSLClient class to use the `write` method defined in the 
+   * `Print` class.
+   */
   using Print::write;
 
+  /**
+   * @brief Grants WiFiClient class access to private and protected members of WiFiServer.
+   */
   friend class WiFiClient;
 };
 

libraries/WiFiS3/src/WiFiSSLClient.h

@@ -30,6 +30,13 @@
 #include "Modem.h"
 #include "FifoBuffer.h"
 
+/**
+ * @brief A class for handling UDP communication over a Wi-Fi network.
+ * 
+ * The WiFiUDP class is an extension of the UDP class that enables sending and receiving UDP packets
+ * over a Wi-Fi network. It provides functions for initialization, packet transmission, and reception
+ * tailored for Wi-Fi connectivity.
+ */
 class WiFiUDP : public UDP {
 private:
   int _sock; 
@@ -41,57 +48,212 @@ class WiFiUDP : public UDP {
   virtual void read_if_needed(size_t s);
 
 public:
-  WiFiUDP();  // Constructor
-  virtual uint8_t begin(uint16_t);	// initialize, start listening on specified port. Returns 1 if successful, 0 if there are no sockets available to use
+  /**
+   * @brief Default constructor for the WiFiUDP class.
+   */
+  WiFiUDP();
+
+  /**
+   * @brief Starts a UDP socket on the specified local port.
+   * 
+   * @param `uint16_t` The local port number to bind the UDP socket to.
+   * 
+   * @return Returns `1` if the socket is successfully opened, or 
+   * `0` if the socket is already in use or could not be opened.
+   */
+  virtual uint8_t begin(uint16_t);
+  
+  /**
+   * @brief Starts a UDP socket bound to a specific IP address and port.
+   * 
+   * @param `a` The local IP address to bind the UDP socket to.
+   * @param `p` The local port number to bind the UDP socket to.
+   * 
+   * @return Returns `1` if the socket is successfully opened, or 
+   * `0` if the socket is already in use or could not be opened.
+   */
   virtual uint8_t begin(IPAddress a, uint16_t p);
-  virtual uint8_t beginMulticast(IPAddress, uint16_t);  // initialize, start listening on specified multicast IP address and port. Returns 1 if successful, 0 if there are no sockets available to use
-  virtual void stop();  // Finish with the UDP socket
+  
+  /**
+   * @brief Starts a UDP multicast socket bound to a specific IP address and port.
+   * 
+   * @param `IPAddress` The multicast IP address to bind the UDP socket to.
+   * @param `uint16_t` The port number to bind the UDP socket to.
+   * 
+   * @return Returns `1` if the socket is successfully opened, or 
+   * `0` if the socket is already in use or could not be opened.
+   */
+  virtual uint8_t beginMulticast(IPAddress, uint16_t);
+  
+  /**
+   * @brief Stops the UDP socket and releases its resources.
+   */
+  virtual void stop();
 
-  // Sending UDP packets
+  /**
+   * @brief Begins constructing a multicast UDP packet for sending.
+   * 
+   * @return Returns `1` if the packet preparation is successful.
+   * Or `0` if there is an error or the socket is not initialized.
+   */
   virtual int beginMulticastPacket();
-  // Start building up a packet to send to the remote host specific in ip and port
-  // Returns 1 if successful, 0 if there was a problem with the supplied IP address or port
+  
+  /**
+   * @brief Begins constructing a UDP packet for sending to a specific IP address and port.
+   * 
+   * @param `ip` The destination IP address as an `IPAddress` object.
+   * @param `port` The destination port number.
+   * 
+   * @return Returns `1` if the packet preparation is successful. 
+   * Or `0` if there is an error or the socket is not initialized.
+   */
   virtual int beginPacket(IPAddress ip, uint16_t port);
-  // Start building up a packet to send to the remote host specific in host and port
-  // Returns 1 if successful, 0 if there was a problem resolving the hostname or port
+
+  /**
+   * @brief Begins constructing a UDP packet for sending to a specific hostname and port.
+   * 
+   * @param `host` The destination hostname as a null-terminated string.
+   * @param `port` The destination port number.
+   * 
+   * @return Returns `1` if the packet preparation is successful.
+   * Or `0` if there is an error or the socket is not initialized.
+   */
   virtual int beginPacket(const char *host, uint16_t port);
-  // Finish off this packet and send it
-  // Returns 1 if the packet was sent successfully, 0 if there was an error
+
+  /**
+   * @brief Completes the construction of a UDP packet and sends it to the specified destination.
+   * 
+   * @return Returns `1` if the packet is successfully transmitted.
+   * Or `0` if there is an error or the socket is not initialized.
+   */
   virtual int endPacket();
-  // Write a single byte into the packet
+
+  /**
+   * @brief Sends a single byte of data to the currently opened UDP packet.
+   * 
+   * @param `b` The byte of data to send.
+   * 
+   * @return Returns `1` if the byte was successfully written.
+   * Or `0` if there was an error or the packet was not properly initialized.
+   */
   virtual size_t write(uint8_t);
-  // Write size bytes from buffer into the packet
+
+  /**
+   * @brief Sends a buffer of data to the currently opened UDP packet.
+   * 
+   * @param `buffer` A pointer to the buffer containing the data to send.
+   * @param `size` The number of bytes from the buffer to write.
+   * 
+   * @return Returns the number of bytes successfully written if the operation is successful.
+   * Or `0` if the data was not successfully written, or if the packet was not properly initialized.
+   */
   virtual size_t write(const uint8_t *buffer, size_t size);
 
+  /**
+   * @brief Inherits the `write` method from the Print class.
+   * 
+   * This allows the WiFiSSLClient class to use the `write` method defined in the 
+   * `Print` class.
+   */
   using Print::write;
 
-  // Start processing the next available incoming packet
-  // Returns the size of the packet in bytes, or 0 if no packets are available
+  /** 
+   * @brief Start processing the next available incoming packet
+   * 
+   * @return Returns the size of the incoming packet, or `0` if no packet is available.
+   */
   virtual int parsePacket();
-  // Number of bytes remaining in the current packet
+
+  /** 
+   * @brief Checks if there are any available UDP packets to read.
+   * 
+   * @return Returns the number of available bytes if packets are available, or `0` if no packets are available.
+   */
   virtual int available();
-  // Read a single byte from the current packet
+
+  /** 
+   * @brief Read a single byte from the current packet
+   * 
+   * @return Returns the number of bytes read into the buffer, or `-1` if an error occurs.
+   */
   virtual int read();
-  // Read up to len bytes from the current packet and place them into buffer
-  // Returns the number of bytes read, or 0 if none are available
+
+  /** 
+   * @brief Reads data from the UDP receive buffer into a provided buffer.
+   * 
+   * @param `buffer` A pointer to the buffer where the received data will be stored.
+   * @param `size` The number of bytes to read from the UDP buffer.
+   * 
+   * @return The number of bytes successfully read into the buffer.
+   * If less than `size` bytes are read, it indicates that the buffer was exhausted early.
+   */
   virtual int read(unsigned char* buffer, size_t len);
-  // Read up to len characters from the current packet and place them into buffer
-  // Returns the number of characters read, or 0 if none are available
+
+
+  /** 
+   * @brief Reads data from the UDP receive buffer into a character buffer.
+   * 
+   * @param `buffer` A pointer to the character buffer where the received data will be stored.
+   * @param `len` The number of bytes to read from the UDP buffer.
+   * 
+   * @return The number of bytes successfully read into the buffer.
+   * If less than `len` bytes are read, it indicates that the buffer was exhausted early.
+   */
   virtual int read(char* buffer, size_t len) { return read((unsigned char*)buffer, len); };
-  // Return the next byte from the current packet without moving on to the next byte
+
+  /** 
+   * @brief Peeks at the next byte available in the UDP buffer without moving on to the next byte.
+   * 
+   * @return The value of the next byte in the UDP buffer, or `-1` if no data is available.
+   */
   virtual int peek();
+
+  /** 
+   * @brief Finish reading the current packet
+   */
   virtual void flush();	// Finish reading the current packet
+
+  /** 
+   * @brief Compares two WiFiUDP objects for equality.
+   * 
+   * This function compares two `WiFiUDP` objects by checking if their associated 
+   * socket values (`_sock`) are the same.
+   * 
+   * @param `WiFiUDP&` The WiFiUDP object to compare with the current object.
+   * 
+   * @return `true` if the socket values are equal, `false` otherwise.
+   */
   virtual bool operator==(const WiFiUDP&);
+  
+  /** 
+   * @brief Compares two WiFiUDP objects for inequality.
+   * 
+   * This function compares two `WiFiUDP` objects by checking if their associated 
+   * socket values (`_sock`) are different.
+   * 
+   * @param `whs` The WiFiUDP object to compare with the current object.
+   * @return `true` if the socket values are different, `false` otherwise.
+   */
   virtual bool operator!=(const WiFiUDP& whs)
   {
     return !this->operator==(whs);
   };
 
-  // Return the IP address of the host who sent the current incoming packet
+  /** 
+   * @brief Retrieves the remote IP address of the host who sent the current incoming packet.
+   * 
+   * @return An `IPAddress` object representing the remote IP address. If the socket
+   * is not valid or the address cannot be retrieved, it returns `IPAddress(0, 0, 0, 0)`.
+   */
   virtual IPAddress remoteIP();
-  // Return the port of the host who sent the current incoming packet
+  
+  /** 
+   * @brief Return the port of the host who sent the current incoming packet.
+   * 
+   * @return The remote port number as a `uint16_t`. If the socket is not valid or
+   * the port cannot be retrieved, it returns `0`.
+   */
   virtual uint16_t remotePort();
-
 
 };
 

libraries/WiFiS3/src/WiFiServer.h

@@ -3,7 +3,7 @@
 # https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5---3rd-party-Hardware-specification
 
 name=Arduino Renesas fsp Boards
-version=1.4.0
+version=1.4.1
 
 # Compile variables
 # ------------------------