Add documentation

Author: P-R-O-C-H-Y

docs/en/api/espnow.rst

@@ -2,29 +2,275 @@
 ESP-NOW
 #######
 
-ESP-NOW is a fast, connectionless communication technology featuring a short packet transmission.
+About
+-----
+
+ESP-NOW is a communication protocol designed for low-power, low-latency, and high-throughput communication between ESP32 devices without the need for an access point (AP). 
+It is ideal for scenarios where devices need to communicate directly with each other in a local network.
 ESP-NOW is ideal for smart lights, remote control devices, sensors and other applications. 
 
-.. note:: This is a work in progress project and this section is still missing. If you want to contribute, please see the `Contributions Guide <../contributing.html>`_.
+This library provides an easy-to-use interface for setting up ESP-NOW communication, adding and removing peers, and sending and receiving data packets.
+
+Arduino-ESP32 ESP-NOW API
+-------------------------
+
+ESP-NOW Class
+*************
+
+The `ESP_NOW_Class` is the main class used for managing ESP-NOW communication.
+
+begin
+^^^^^
+
+Initialize the ESP-NOW communication. This function must be called before using any other ESP-NOW functionalities.
+
+.. code-block:: cpp
+
+    bool begin(const uint8_t *pmk = NULL);
+
+* ``pmk``: Optional. Pass the pairwise master key (PMK) if encryption is enabled.
+
+Returns ``true`` if initialization is successful, ``false`` otherwise.
+
+end
+^^^
+
+End the ESP-NOW communication. This function releases all resources used by the ESP-NOW library.
+
+.. code-block:: cpp
+
+    bool end();
+
+Returns ``true`` if the operation is successful, ``false`` otherwise.
+
+getTotalPeerCount
+^^^^^^^^^^^^^^^^^
+
+Get the total number of peers currently added.
+
+.. code-block:: cpp
+
+    int getTotalPeerCount();
+
+Returns the total number of peers, or ``-1`` if an error occurs.
+
+getEncryptedPeerCount
+^^^^^^^^^^^^^^^^^^^^^
+
+Get the number of peers using encryption.
+
+.. code-block:: cpp
+
+    int getEncryptedPeerCount();
+
+Returns the number of peers using encryption, or ``-1`` if an error occurs.
+
+onNewPeer
+^^^^^^^^^
+
+You can register a callback function to handle incoming data from new peers using the `onNewPeer` function.
+
+.. code-block:: cpp
+
+    void onNewPeer(void (*cb)(const esp_now_recv_info_t *info, const uint8_t *data, int len, void *arg), void *arg);
+
+* ``cb``: Pointer to the callback function.
+* ``arg``: Optional. Pointer to user-defined argument to be passed to the callback function.
+
+``cb`` function signature:
+
+.. code-block:: cpp
+
+    void cb(const esp_now_recv_info_t *info, const uint8_t *data, int len, void *arg);
+
+``info``: Information about the received packet.
+``data``: Pointer to the received data.
+``len``: Length of the received data.
+``arg``: User-defined argument passed to the callback function.
+
+ESP-NOW Peer Class
+******************
+
+The `ESP_NOW_Peer` class represents a peer device in the ESP-NOW network.
+
+Constructor
+^^^^^^^^^^^
+
+Create an instance of the `ESP_NOW_Peer` class.
+
+.. code-block:: cpp
+
+    ESP_NOW_Peer(const uint8_t *mac_addr, uint8_t channel, wifi_interface_t iface, const uint8_t *lmk);
+
+* ``mac_addr``: MAC address of the peer device.
+* ``channel``: Communication channel.
+* ``iface``: WiFi interface.
+* ``lmk``: Optional. Pass the local master key (LMK) if encryption is enabled.
+
+add
+^^^
+
+Add the peer to the ESP-NOW network.
+
+.. code-block:: cpp
+
+    bool add();
+
+Returns ``true`` if the peer is added successfully, ``false`` otherwise.
+
+remove
+^^^^^^
+
+Remove the peer from the ESP-NOW network.
+
+.. code-block:: cpp
+
+    bool remove();
+
+Returns ``true`` if the peer is removed successfully, ``false`` otherwise.
+
+send
+^^^^
+
+Send data to the peer.
+
+.. code-block:: cpp
+
+    size_t send(const uint8_t *data, int len);
+
+* ``data``: Pointer to the data to be sent.
+* ``len``: Length of the data in bytes.
+
+Returns the number of bytes sent, or ``0`` if an error occurs.
+
+addr
+^^^^
+
+Get the MAC address of the peer.
+
+.. code-block:: cpp
+
+    const uint8_t * addr() const;
+
+Returns a pointer to the MAC address.
+
+addr
+^^^^
+
+Set the MAC address of the peer.
+
+.. code-block:: cpp
+
+    void addr(const uint8_t *mac_addr);
+
+* ``mac_addr``: MAC address of the peer.
+
+getChannel
+^^^^^^^^^^
+
+Get the communication channel of the peer.
+
+.. code-block:: cpp
+
+    uint8_t getChannel() const;
+
+Returns the communication channel.
+
+setChannel
+^^^^^^^^^^
+
+Set the communication channel of the peer.
+
+.. code-block:: cpp
+
+    void setChannel(uint8_t channel);
+
+* ``channel``: Communication channel.
+
+getInterface
+^^^^^^^^^^^^
+
+Get the WiFi interface of the peer.
+
+.. code-block:: cpp
+
+    wifi_interface_t getInterface() const;
+
+Returns the WiFi interface.
+
+setInterface
+^^^^^^^^^^^^
+
+Set the WiFi interface of the peer.
+
+.. code-block:: cpp
+
+    void setInterface(wifi_interface_t iface);
+
+* ``iface``: WiFi interface.
+
+isEncrypted
+^^^^^^^^^^^
+
+Check if the peer is using encryption.
+
+.. code-block:: cpp
+
+    bool isEncrypted() const;
+
+Returns ``true`` if the peer is using encryption, ``false`` otherwise.
+
+setKey
+^^^^^^
+
+Set the local master key (LMK) for the peer.
+
+.. code-block:: cpp
+
+    void setKey(const uint8_t *lmk);
+
+* ``lmk``: Local master key.
+
+_onReceive
+^^^^^^^^^^
+
+Callback function to handle incoming data from the peer, must be implemented by the upper class.
+
+.. code-block:: cpp
+
+    void _onReceive(const uint8_t *data, int len, bool broadcast);
+
+* ``data``: Pointer to the received data.
+* ``len``: Length of the received data.
+* ``broadcast``: ``true`` if the data is broadcasted, ``false`` otherwise.
+
+_onSent
+^^^^^^^
+
+Callback function to handle the completion of sending data to the peer, must be implemented by the upper class.
+
+.. code-block:: cpp
+
+    void _onSent(bool success);
+
+* ``success``: ``true`` if the data is sent successfully, ``false`` otherwise.
 
 Examples
 --------
 
-ESP-NOW Master
-**************
+Set of 2 examples of the ESP-NOW library to send and receive data between multiple ESP32 devices (1 master, multiple slaves).
 
-.. literalinclude:: ../../../libraries/ESP32/examples/ESPNow/ESPNow_Basic_Master/ESPNow_Basic_Master.ino
-    :language: arduino
+1. ESP-NOW Broadcast Master Example:
 
-ESP-NOW Slave
-*************
+.. literalinclude:: libraries/ESP_NOW/examples/ESP_NOW_Broadcast_Master/ESP_NOW_Broadcast_Master.ino
+    :language: cpp
 
-.. literalinclude:: ../../../libraries/ESP32/examples/ESPNow/ESPNow_Basic_Slave/ESPNow_Basic_Slave.ino
-    :language: arduino
+2. ESP-NOW Broadcast Slave Example:
 
-Resources
----------
+.. literalinclude:: libraries/ESP_NOW/examples/ESP_NOW_Broadcast_Slave/ESP_NOW_Broadcast_Slave.ino
+    :language: cpp
 
-* `ESP-NOW`_ (User Guide)
+Example of the ESP-NOW Serial library to send and receive data between 2 ESP32 devices using the serial port:
 
-.. _ESP-NOW: https://www.espressif.com/sites/default/files/documentation/esp-now_user_guide_en.pdf
+.. literalinclude:: libraries/ESP_NOW/examples/ESP_NOW_Serial/ESP_NOW_Serial.ino
+    :language: cpp

libraries/ESP_NOW/src/ESP32_NOW.h

@@ -60,7 +60,6 @@ class ESP_NOW_Class : public Print {
 
   void onNewPeer(void (*cb)(const esp_now_recv_info_t *info, const uint8_t * data, int len, void * arg), void * arg);
 
-  //TODO: Add function to set peer rate - esp_now_set_peer_rate_config()
 };
 
 extern ESP_NOW_Class ESP_NOW;