####### ESP-NOW ####### 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 can be used for smart lights, remote control devices, sensors and many other applications. 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. It is an abstract class that must be inherited by a child class that properly handles the peer connections and implements the `_onReceive` and `_onSent` methods. 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``: Wi-Fi 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 Wi-Fi interface of the peer. .. code-block:: cpp wifi_interface_t getInterface() const; Returns the Wi-Fi interface. setInterface ^^^^^^^^^^^^ Set the Wi-Fi interface of the peer. .. code-block:: cpp void setInterface(wifi_interface_t iface); * ``iface``: Wi-Fi 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. This is a virtual method can be implemented by the upper class for custom handling. .. 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. This is a virtual method can be implemented by the upper class for custom handling. .. code-block:: cpp void onSent(bool success); * ``success``: ``true`` if the data is sent successfully, ``false`` otherwise. Examples -------- Set of 2 examples of the ESP-NOW library to send and receive data using broadcast messages between multiple ESP32 devices (multiple masters, multiple slaves). 1. ESP-NOW Broadcast Master Example: .. literalinclude:: ../../../libraries/ESP_NOW/examples/ESP_NOW_Broadcast_Master/ESP_NOW_Broadcast_Master.ino :language: cpp 2. ESP-NOW Broadcast Slave Example: .. literalinclude:: ../../../libraries/ESP_NOW/examples/ESP_NOW_Broadcast_Slave/ESP_NOW_Broadcast_Slave.ino :language: cpp Example of the ESP-NOW Serial library to send and receive data as a stream between 2 ESP32 devices using the serial monitor: .. literalinclude:: ../../../libraries/ESP_NOW/examples/ESP_NOW_Serial/ESP_NOW_Serial.ino :language: cpp