docs/en/api/espnow.rst
####### ESP-NOW #######
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.
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.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).
.. literalinclude:: ../../../libraries/ESP_NOW/examples/ESP_NOW_Broadcast_Master/ESP_NOW_Broadcast_Master.ino :language: cpp
.. 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