Skip to content

Latest commit

 

History

History
276 lines (159 loc) · 6.3 KB

espnow.rst

File metadata and controls

276 lines (159 loc) · 6.3 KB

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.

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.

bool end();

Returns true if the operation is successful, false otherwise.

getTotalPeerCount

Get the total number of peers currently added.

int getTotalPeerCount();

Returns the total number of peers, or -1 if an error occurs.

getEncryptedPeerCount

Get the number of peers using encryption.

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.

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:

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.

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.

bool add();

Returns true if the peer is added successfully, false otherwise.

remove

Remove the peer from the ESP-NOW network.

bool remove();

Returns true if the peer is removed successfully, false otherwise.

send

Send data to the peer.

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.

const uint8_t * addr() const;

Returns a pointer to the MAC address.

addr

Set the MAC address of the peer.

void addr(const uint8_t *mac_addr);
  • mac_addr: MAC address of the peer.

getChannel

Get the communication channel of the peer.

uint8_t getChannel() const;

Returns the communication channel.

setChannel

Set the communication channel of the peer.

void setChannel(uint8_t channel);
  • channel: Communication channel.

getInterface

Get the Wi-Fi interface of the peer.

wifi_interface_t getInterface() const;

Returns the Wi-Fi interface.

setInterface

Set the Wi-Fi interface of the peer.

void setInterface(wifi_interface_t iface);
  • iface: Wi-Fi interface.

isEncrypted

Check if the peer is using encryption.

bool isEncrypted() const;

Returns true if the peer is using encryption, false otherwise.

setKey

Set the local master key (LMK) for the peer.

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.

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.

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
  1. 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