espnow – ESP-NOW Module

The espnow module provides an interface to the ESP-NOW protocol provided by Espressif on its SoCs.

Sender

import espnow

e = espnow.ESPNow()
peer = espnow.Peer(mac=b'ªªªªªª')
e.peers.append(peer)

e.send("Starting...")
for i in range(10):
    e.send(str(i)*20)
e.send(b'end')

Receiver

import espnow

e = espnow.ESPNow()
packets = []

while True:
    if e:
        packet = e.read()
        packets.append(packet)
        if packet.msg == b'end':
            break

print("packets:", f"length={len(packets)}")
for packet in packets:
    print(packet)

Available on these boards
  • 01Space 0.42 OLED ESP32C3
  • AITHinker ESP32-C3S_Kit
  • AITHinker ESP32-C3S_Kit_2M
  • ATMegaZero ESP32-S2
  • Adafruit Camera
  • Adafruit Feather ESP32 V2
  • Adafruit Feather ESP32-C6 4MB Flash No PSRAM
  • Adafruit Feather ESP32-S2 Reverse TFT
  • Adafruit Feather ESP32-S2 TFT
  • Adafruit Feather ESP32-S3 Reverse TFT
  • Adafruit Feather ESP32-S3 TFT
  • Adafruit Feather ESP32S2
  • Adafruit Feather ESP32S3 4MB Flash 2MB PSRAM
  • Adafruit Feather ESP32S3 No PSRAM
  • Adafruit Feather HUZZAH32
  • Adafruit FunHouse
  • Adafruit HUZZAH32 Breakout
  • Adafruit ItsyBitsy ESP32
  • Adafruit MagTag
  • Adafruit MatrixPortal S3
  • Adafruit Metro ESP32S2
  • Adafruit Metro ESP32S3
  • Adafruit QT Py ESP32 PICO
  • Adafruit QT Py ESP32-S3 4MB Flash 2MB PSRAM
  • Adafruit QT Py ESP32-S3 no psram
  • Adafruit QT Py ESP32C3
  • Adafruit QT Py ESP32S2
  • Adafruit Vindie S2
  • Adafruit-Qualia-S3-RGB666
  • Ai Thinker ESP32-CAM
  • Arduino Nano ESP32
  • Artisense Reference Design RD00
  • AutosportLabs-ESP32-CAN-X2
  • BARDUINO 4.0.2
  • BLING!
  • BPI-Bit-S2
  • BPI-Leaf-S3
  • BPI-PicoW-S3
  • BastWiFi
  • Bee-Data-Logger
  • Bee-Motion-S3
  • Bee-S3
  • BlizzardS3
  • CRCibernetica IdeaBoard
  • CircuitART Zero S3
  • ColumbiaDSL-Sensor-Board-V1
  • CrumpS2
  • Cytron Maker Feather AIoT S3
  • DFRobot Beetle ESP32-C3
  • DFRobot FireBeetle 2 ESP32-S3
  • Deneyap Kart
  • Deneyap Kart 1A
  • Deneyap Kart 1A v2
  • Deneyap Kart G
  • Deneyap Mini
  • Deneyap Mini v2
  • ES3ink
  • ESP 12k NodeMCU
  • ESP32 Devkit V1
  • ESP32-C3-DevKitM-1
  • ESP32-C6-DevKitC-1-N8
  • ESP32-C6-DevKitM-1
  • ESP32-S2-DevKitC-1-N4
  • ESP32-S2-DevKitC-1-N4R2
  • ESP32-S2-DevKitC-1-N8R2
  • ESP32-S3-Box-2.5
  • ESP32-S3-Box-Lite
  • ESP32-S3-DevKitC-1-N16
  • ESP32-S3-DevKitC-1-N32R8
  • ESP32-S3-DevKitC-1-N8
  • ESP32-S3-DevKitC-1-N8R2
  • ESP32-S3-DevKitC-1-N8R8
  • ESP32-S3-DevKitC-1-N8R8-with-HACKTABLET
  • ESP32-S3-DevKitM-1-N8
  • ESP32-S3-EYE
  • ESP32-S3-USB-OTG-N8
  • ESP8684-DevKitC-02-N4
  • Espressif ESP32 DevKitc V4 WROOM-32E
  • Espressif ESP32 DevKitc V4 WROVER
  • Espressif ESP32 TTGO T8 v1.7
  • Espressif ESP32-EYE
  • Espressif ESP32-LyraT
  • Espressif-ESP32-S3-LCD-EV-Board
  • Espressif-ESP32-S3-LCD-EV-Board_v1.5
  • FeatherS2
  • FeatherS2 Neo
  • FeatherS2 PreRelease
  • FeatherS3
  • FeatherS3 Neo
  • Flipper Zero Wi-Fi Dev
  • Franzininho WIFI w/Wroom
  • Franzininho WIFI w/Wrover
  • Freenove ESP32-WROVER-DEV-CAM
  • Gravitech Cucumber M
  • Gravitech Cucumber MS
  • Gravitech Cucumber R
  • Gravitech Cucumber RS
  • HMI-DevKit-1.1
  • Hardkernel Odroid Go
  • Heltec ESP32-S3-WIFI-LoRa-V3
  • HexKyS2
  • IoTs2
  • Kaluga 1
  • LILYGO T-DECK
  • LILYGO T-DISPLAY S3 v1.2
  • LILYGO T-Display S3 Pro
  • LILYGO T-Watch-S3
  • LILYGO TEMBED ESP32S3
  • LILYGO TTGO T-01C3
  • LILYGO TTGO T-DISPLAY v1.1
  • LILYGO TTGO T-DISPLAY v1.1 4M
  • LILYGO TTGO T-OI PLUS
  • LILYGO TTGO T8 ESP32-S2
  • LILYGO TTGO T8 ESP32-S2 w/Display
  • LOLIN S3 16MB Flash 8MB PSRAM
  • LOLIN S3 MINI 4MB Flash 2MB PSRAM
  • LOLIN S3 PRO 16MB Flash 8MB PSRAM
  • Lilygo T-watch 2020 V3
  • Luatos Core-ESP32C3
  • M5STACK STAMP-C3
  • M5Stack Atom Echo
  • M5Stack Atom Lite
  • M5Stack Atom Matrix
  • M5Stack Atom U
  • M5Stack AtomS3
  • M5Stack AtomS3 Lite
  • M5Stack AtomS3U
  • M5Stack Cardputer
  • M5Stack Core Basic
  • M5Stack Core Fire
  • M5Stack Core2
  • M5Stack CoreS3
  • M5Stack Dial
  • M5Stack M5Paper
  • M5Stack Stick C
  • M5Stack Stick C Plus
  • M5Stack Timer Camera X
  • MORPHEANS MorphESP-240
  • MagiClick S3 N4R2
  • Maker Go ESP32C3 Supermini
  • Maker Go ESP32C6 Supermini
  • Maker badge by Czech maker
  • MakerFabs-ESP32-S3-Parallel-TFT-With-Touch-7inch
  • MicroDev microC3
  • MicroDev microS2
  • MixGo CE
  • NanoS3
  • Neuron
  • NodeMcu-ESP32-C2
  • OMGS3
  • Oak Dev Tech PixelWing ESP32S2
  • Oxocard Artwork
  • Oxocard Connect
  • Oxocard Galaxy
  • Oxocard Science
  • ProS3
  • RGBTouch Mini
  • S2Mini
  • S2Pico
  • SQFMI Watchy
  • Saola 1 w/Wroom
  • Saola 1 w/Wrover
  • Seeed Studio XIAO ESP32C3
  • Seeed Xiao ESP32-C6 4MB Flash 512KB SRAM
  • Seeed Xiao ESP32-S3 Sense
  • Spotpear ESP32C3 LCD 1.44
  • Sunton ESP32-2424S012
  • Sunton-ESP32-8048S050
  • Sunton-ESP32-8048S070
  • TTGO T8 ESP32-S2-WROOM
  • Targett Module Clip w/Wroom
  • Targett Module Clip w/Wrover
  • ThingPulse Pendrive S3
  • TinyC6
  • TinyPICO
  • TinyPICO Nano
  • TinyS2
  • TinyS3
  • TinyWATCH S3
  • VCC-GND YD-ESP32-S3 (N16R8)
  • VCC-GND YD-ESP32-S3 (N8R8)
  • VIDI X V1.1
  • Waveshare ESP32-S2-Pico
  • Waveshare ESP32-S2-Pico-LCD
  • Waveshare ESP32-S3-GEEK
  • Waveshare ESP32-S3-Pico
  • Waveshare ESP32-S3-Tiny
  • Waveshare ESP32-S3-Zero
  • Waveshare ESP32S3 LCD 1.28
  • WeAct ESP32-C6 (4MB)
  • WeAct ESP32-C6 (8MB)
  • WeMos LOLIN32 Lite
  • Wemos Lolin C3 Mini
  • Wemos Lolin C3 Pico
  • nanoESP32-S2 w/Wrover
  • nanoESP32-S2 w/Wroom
  • senseBox MCU-S2 ESP32S2
  • sunton_esp32_2432S028
  • sunton_esp32_2432S032C

class espnow.ESPNow(buffer_size: int = 526, phy_rate: int = 0)

Provides access to the ESP-NOW protocol.

Allocate and initialize ESPNow instance as a singleton.

Parameters:
  • buffer_size (int) – The size of the internal ring buffer. Default: 526 bytes.

  • phy_rate (int) – The ESP-NOW physical layer rate. Default: 1 Mbps. wifi_phy_rate_t

deinit() None

Deinitializes ESP-NOW and releases it for another program.

__enter__() ESPNow

No-op used by Context Managers.

__exit__() None

Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.

send(message: circuitpython_typing.ReadableBuffer, peer: Peer | None = None) None

Send a message to the peer’s mac address.

This blocks until a timeout of 2 seconds if the ESP-NOW internal buffers are full.

Parameters:
  • message (ReadableBuffer) – The message to send (length <= 250 bytes).

  • peer (Peer) – Send message to this peer. If None, send to all registered peers.

read() ESPNowPacket | None

Read a packet from the receive buffer.

This is non-blocking, the packet is received asynchronously from the peer(s).

Returns:

An ESPNowPacket if available in the buffer, otherwise None.

send_success: int

The number of tx packets received by the peer(s) ESP_NOW_SEND_SUCCESS. (read-only)

send_failure: int

The number of failed tx packets ESP_NOW_SEND_FAIL. (read-only)

read_success: int

The number of rx packets captured in the buffer. (read-only)

read_failure: int

The number of dropped rx packets due to buffer overflow. (read-only)

set_pmk(pmk: circuitpython_typing.ReadableBuffer) None

Set the ESP-NOW Primary Master Key (pmk) for encrypted communications.

Parameters:

pmk (ReadableBuffer) – The ESP-NOW Primary Master Key (length = 16 bytes).

buffer_size: int

The size of the internal ring buffer. (read-only)

phy_rate: int

The ESP-NOW physical layer rate. wifi_phy_rate_t

peers: Peers

The peer info records for all registered ESPNow peers. (read-only)

__bool__() bool

True if len() is greater than zero. This is an easy way to check if the buffer is empty.

__len__() int

Return the number of bytes available to read. Used to implement len().

class espnow.ESPNowPacket

A packet retrieved from ESP-NOW communication protocol. A namedtuple.

mac: circuitpython_typing.ReadableBuffer

The sender’s mac address (length = 6 bytes).

msg: circuitpython_typing.ReadableBuffer

The message sent by the peer (length <= 250 bytes).

rssi: int

The received signal strength indication (in dBm from -127 to 0).

time: int

The time in milliseconds since the device last booted when the packet was received.

class espnow.Peer(mac: bytes, *, lmk: bytes | None, channel: int = 0, interface: int = 0, encrypted: bool = False)

A data class to store parameters specific to a peer.

Construct a new peer object.

Parameters:
  • mac (bytes) – The mac address of the peer.

  • lmk (bytes) – The Local Master Key (lmk) of the peer.

  • channel (int) – The peer’s channel. Default: 0 ie. use the current channel.

  • interface (int) – The WiFi interface to use. Default: 0 ie. STA.

  • encrypted (bool) – Whether or not to use encryption.

mac: circuitpython_typing.ReadableBuffer

The WiFi mac to use.

lmk: circuitpython_typing.ReadableBuffer

The WiFi lmk to use.

channel: int

The WiFi channel to use.

interface: int

The WiFi interface to use.

encrypted: bool

Whether or not to use encryption.

class espnow.Peers

Maintains a list of Peer internally and only exposes a subset of list methods.

You cannot create an instance of Peers.

append(peer: Peer) None

Append peer.

Parameters:

peer (Peer) – The peer object to append.

remove(peer: Peer) None

Remove peer.

Parameters:

peer (Peer) – The peer object to remove.