espnow_component.h

Go to the documentation of this file.

#pragma once
 
#include "esphome/core/automation.h"
#include "esphome/core/component.h"
#include "esphome/core/defines.h"
 
#ifdef USE_ESP32
 
#include "esphome/core/event_pool.h"
#include "esphome/core/lock_free_queue.h"
#include "espnow_packet.h"
 
#if defined(USE_WIFI) && defined(USE_WIFI_CONNECT_STATE_LISTENERS)
#include "esphome/components/wifi/wifi_component.h"
#endif
 
#include <esp_idf_version.h>
 
#include <esp_mac.h>
#include <esp_now.h>
 
#include <array>
#include <map>
#include <memory>
#include <string>
#include <vector>
 
namespace esphome::espnow {
 
// Maximum size of the ESPNow event queue - must be power of 2 for lock-free queue
static constexpr size_t MAX_ESP_NOW_SEND_QUEUE_SIZE = 16;
static constexpr size_t MAX_ESP_NOW_RECEIVE_QUEUE_SIZE = 16;
 
using peer_address_t = std::array<uint8_t, ESP_NOW_ETH_ALEN>;
 
enum class ESPNowTriggers : uint8_t {
  TRIGGER_NONE = 0,
  ON_NEW_PEER = 1,
  ON_RECEIVE = 2,
  ON_BROADCAST = 3,
  ON_SUCCEED = 10,
  ON_FAILED = 11,
};
 
enum ESPNowState : uint8_t {
  ESPNOW_STATE_OFF = 0,
  ESPNOW_STATE_DISABLED,
  ESPNOW_STATE_ENABLED,
};
 
struct ESPNowPeer {
  uint8_t address[ESP_NOW_ETH_ALEN];  // MAC address of the peer
 
  bool operator==(const ESPNowPeer &other) const { return memcmp(this->address, other.address, ESP_NOW_ETH_ALEN) == 0; }
  bool operator==(const uint8_t *other) const { return memcmp(this->address, other, ESP_NOW_ETH_ALEN) == 0; }
};
 
class ESPNowUnknownPeerHandler {
 public:
  virtual bool on_unknown_peer(const ESPNowRecvInfo &info, const uint8_t *data, uint16_t size) = 0;
};
 
class ESPNowReceivedPacketHandler {
 public:
  virtual bool on_receive(const ESPNowRecvInfo &info, const uint8_t *data, uint16_t size) = 0;
};
class ESPNowBroadcastHandler {
 public:
  virtual bool on_broadcast(const ESPNowRecvInfo &info, const uint8_t *data, uint16_t size) = 0;
};
 
#if defined(USE_WIFI) && defined(USE_WIFI_CONNECT_STATE_LISTENERS)
class ESPNowComponent final : public Component, public wifi::WiFiConnectStateListener {
#else
class ESPNowComponent final : public Component {
#endif
 public:
  ESPNowComponent();
  void setup() override;
  void loop() override;
  void dump_config() override;
 
  float get_setup_priority() const override { return setup_priority::LATE; }
 
  // Add a peer to the internal list of peers
  void add_peer(peer_address_t address) {
    ESPNowPeer peer;
    memcpy(peer.address, address.data(), ESP_NOW_ETH_ALEN);
    this->peers_.push_back(peer);
  }
  // Add a peer with the esp_now api and add to the internal list if doesnt exist already
  esp_err_t add_peer(const uint8_t *peer);
  // Remove a peer with the esp_now api and remove from the internal list if exists
  esp_err_t del_peer(const uint8_t *peer);
  // Action entry points; distinct names because add_peer(peer_address_t) only fills the boot-time list
  esp_err_t add_peer_from_action(const peer_address_t &address) { return this->add_peer(address.data()); }
  esp_err_t del_peer_from_action(const peer_address_t &address) { return this->del_peer(address.data()); }
 
  void set_wifi_channel(uint8_t channel) { this->wifi_channel_ = channel; }
  void apply_wifi_channel();
  void set_channel_from_action(uint8_t channel) {
    if (this->is_wifi_enabled())
      return;
    this->set_wifi_channel(channel);
    this->apply_wifi_channel();
  }
  uint8_t get_wifi_channel();
 
  void set_auto_add_peer(bool value) { this->auto_add_peer_ = value; }
 
#if defined(USE_WIFI) && defined(USE_WIFI_CONNECT_STATE_LISTENERS)
  // WiFiConnectStateListener interface: refresh the cached channel after each (re)connect
  void on_wifi_connect_state(StringRef ssid, std::span<const uint8_t, 6> bssid) override;
#endif
 
  void enable();
  void disable();
  bool is_disabled() const { return this->state_ == ESPNOW_STATE_DISABLED; };
  void set_enable_on_boot(bool enable_on_boot) { this->enable_on_boot_ = enable_on_boot; }
  bool is_wifi_enabled();
 
  esp_err_t send(const uint8_t *peer_address, const std::vector<uint8_t> &payload,
                 const send_callback_t &callback = nullptr) {
    return this->send(peer_address, payload.data(), payload.size(), callback);
  }
  esp_err_t send(const uint8_t *peer_address, const uint8_t *payload, size_t size,
                 const send_callback_t &callback = nullptr);
 
  void register_receive_handler(ESPNowReceivedPacketHandler *handler) { this->receive_handlers_.push_back(handler); }
  void register_unknown_peer_handler(ESPNowUnknownPeerHandler *handler) {
    this->unknown_peer_handlers_.push_back(handler);
  }
  void register_broadcast_handler(ESPNowBroadcastHandler *handler) { this->broadcast_handlers_.push_back(handler); }
 
 protected:
  friend void on_data_received(const esp_now_recv_info_t *info, const uint8_t *data, int size);
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 5, 0)
  friend void on_send_report(const esp_now_send_info_t *info, esp_now_send_status_t status);
#else
  friend void on_send_report(const uint8_t *mac_addr, esp_now_send_status_t status);
#endif
 
  void enable_();
  void send_();
 
  std::vector<ESPNowUnknownPeerHandler *> unknown_peer_handlers_;
  std::vector<ESPNowReceivedPacketHandler *> receive_handlers_;
  std::vector<ESPNowBroadcastHandler *> broadcast_handlers_;
 
  std::vector<ESPNowPeer> peers_{};
 
  uint8_t own_address_[ESP_NOW_ETH_ALEN]{0};
  LockFreeQueue<ESPNowPacket, MAX_ESP_NOW_RECEIVE_QUEUE_SIZE> receive_packet_queue_{};
  // Pool sized to queue capacity (SIZE-1) because LockFreeQueue<T,N> is a ring
  // buffer that holds N-1 elements. This guarantees allocate() returns nullptr
  // before push() can fail, preventing a pool slot leak.
  EventPool<ESPNowPacket, MAX_ESP_NOW_RECEIVE_QUEUE_SIZE - 1> receive_packet_pool_{};
 
  LockFreeQueue<ESPNowSendPacket, MAX_ESP_NOW_SEND_QUEUE_SIZE> send_packet_queue_{};
  // Pool sized to queue capacity (SIZE-1) — see receive_packet_pool_ comment.
  EventPool<ESPNowSendPacket, MAX_ESP_NOW_SEND_QUEUE_SIZE - 1> send_packet_pool_{};
  ESPNowSendPacket *current_send_packet_{nullptr};  // Currently sending packet, nullptr if none
 
  uint8_t wifi_channel_{0};
  ESPNowState state_{ESPNOW_STATE_OFF};
 
  bool auto_add_peer_{false};
  bool enable_on_boot_{true};
};
 
extern ESPNowComponent *global_esp_now;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
 
}  // namespace esphome::espnow
 
#endif  // USE_ESP32