DOCSEARCHbyAlgolia
Submit Docs

ESP-NOW Documentation

repository·master·Indexed 20 days ago

https://github.com/espressif/esp-now

ESP-NOW is a connectionless wireless communication protocol supporting one-to-many and many-to-many device connections for efficient mass data transmission, including network configuration, firmware upgrades, and debugging. The documentation covers implementation on ESP32 series boards, including examples for OTA upgrades, WiFi provisioning, and device control using initiator and responder roles.

Tokens
18K
Snippets
45
Records
93
Agent score
71%

What's inside ESP-NOW

  1. Overview of the ESP-NOW Programming Guide

    master
    ESP-NOW is the official development framework for Espressif's ESP32 series SoCs. It provides high-level functionalities designed to simplify the implementation of the ESP-NOW protocol, reducing the complexity of developing wireless communication products using the ESP32.

  2. What is the ESP-NOW component

    master

    The ESP-NOW component is a high-level abstraction layer built on top of the standard ESP-IDF ESP-NOW protocol. It simplifies the implementation of the protocol by providing enhanced application-level features such as pairing, control, provisioning, debugging, Over-the-Air (OTA) updates, and security.

    Key characteristics include:

    • Resource Efficient: Occupies less CPU and flash memory compared to standard implementations.
    • Coexistence: Can work alongside Wi-Fi and Bluetooth LE.
    • Hardware Support: Supports ESP8266, ESP32, ESP32-S, and ESP32-C series.
    • Flexible Transmission: Supports unicast and broadcast modes, enabling one-to-many and many-to-many device connections.

  3. Understand ESP-NOW Debug Demo functionality

    master

    The debug demo provides a command-line interface (via UART or ESP-NOW) and a web interface to manage and monitor devices.

    Debug Receiver Board Features

    • Wi-Fi Management: Configuration, scanning, and pinging.
    • ESP-NOW Management: Control, provisioning, OTA, configuration, and iperf.
    • System Management: Heap status, version info, restart, power save, reset, rollback, and coredump.
    • Peripheral Management: GPIO and UART control.
    • Remote Execution: Ability to run commands on specific remote devices.
    • Log Reception: Receives wireless logs from monitored devices via ESP-NOW.
    • Web Server: Hosts an HTTP server for browser-based log and status viewing.

    Monitored Device Features

    • Log Storage: Stores log data in flash.
    • Wireless Transmission: Sends log data to the receiver via ESP-NOW.
    • Network Forwarding: Can transfer log data to a TCP server over an HTTP network.

    Critical Requirement: The debug receiver board must be on the same Wi-Fi channel as the monitored devices to receive data. If they are on the same channel, the receiver board does not need to be connected to a router.

  4. ESP-NOW Enhanced Features: Provisioning, Upgrade, and Debug

    master

    This component provides high-level application-level functionalities on top of the standard ESP-NOW protocol:

    Provisioning

    Provides a method to share network credentials (SSID/password) across devices. One device is configured via Bluetooth, and it can then transmit these credentials to other devices directly via ESP-NOW, eliminating the need for manual configuration on every node.

    Firmware Upgrade (OTA)

    • Breakpoint Resume: Supports resuming firmware updates from the last successfully written package if interrupted.
    • Mass Upgrade: Can upgrade multiple devices simultaneously (e.g., 50 devices in 3 minutes).
    • Rollback: Automatically rolls back to the previous firmware version if an upgrade error occurs.

    Debugging and Production Testing

    • Remote Logging: Receive running logs from multiple responders to a single initiator, useful for high-voltage or high-temperature environments where direct contact is impossible.
    • Debug Commands: Control peripherals (GPIO, UART, LED), adjust Wi-Fi settings (country code, power), and check system status (memory, tasks).
    • Production Tests: Supports aging tests, interference tests, wireless RF performance monitoring, and version verification.

  5. How ESP-NOW provisioning works (Initiator vs Responder)

    master

    The provisioning process follows a specific communication pattern between the two roles:

    Initiator Behavior

    1. Scanning: Scans for provision beacons continuously until one is received.
    2. Request: Sends a device type provision frame to request WiFi credentials from the responder.
    3. Connection: Upon receiving a WiFi type provision frame, the initiator extracts the credentials and connects to the configured Router.

    Responder Behavior

    1. Beaconing: Broadcasts provision beacons every 100 ms for a duration of 30 seconds.
    2. Response: If a device type provision frame is received, it responds with a WiFi type provision frame containing the WiFi credentials.

    Note: This example does not implement device authentication via the initiator.

  6. ESP-NOW Data Security with ECDH and AES

    master

    ESP-NOW supports secure communication using the following mechanisms:

    • Key Exchange: Uses ECDH (Elliptic Curve Diffie-Hellman) and a Proof of Possession (PoP) string to authorize sessions and derive shared keys.
    • Configuration Security: Uses AES256-CTR mode for encrypting configuration data.
    • Data Security: Uses AES128-CCM mode for encrypting standard ESP-NOW data packets.
    • Efficiency: Supports multiple device handshakes simultaneously, allowing up to 16 devices to be configured in approximately 5 seconds.

  7. How ESP-NOW device roles work

    master

    In an ESP-NOW network, devices are categorized into two roles based on data flow:

    1. Initiator: Typically used by devices that trigger actions or send data, such as switches, sensors, or LCD screens.
    2. Responder: Typically used by devices that receive commands to perform actions, such as lights, sockets, or other smart appliances.

    A single device can act as both an initiator and a responder simultaneously.

  8. Performance considerations for ESP-NOW Debug Demo

    master

    When using the ESP-NOW Debug Demo, be aware of the following performance impacts:

    • Network Congestion: Since ESP-NOW utilizes the Wi-Fi interface, high data volumes can cause delays in command reception or data transmission. To minimize delay, it is recommended to keep the device count around 50 or fewer and set the logging level to info or higher.
    • Logging Levels: Lower logging levels (more verbose) increase network load and may degrade performance.
    • Data Format: The data header includes a timestamp used for experimental purposes; it is not real-time calibrated and can be customized.
    • Log Mode Status: You can check the current log mode (uart, flash, or espnow) using the console command log -i.

  9. How ESP-NOW Internal Time Synchronization works

    master

    The ESP-NOW Internal Time Synchronization module enables time synchronization between nodes without internet connectivity. It is specifically designed to prevent nodes waking from deep sleep from incorrectly resetting the controller node's time.

    The system operates using two distinct roles:

    1. Initiator (Controller): Acts as the authoritative time source. It broadcasts the current time to the network but never adjusts its own internal clock based on other nodes.
    2. Responder (Data Node): Receives time broadcasts and adjusts its local clock to match the Initiator.

    This architecture ensures that the central controller remains the stable reference for the entire network.

  10. Understand ESP-NOW roles and features

    master

    ESP-NOW is a connectionless Wi-Fi communication protocol that simplifies the OSI model to a single layer, reducing latency and congestion. This component provides an application-level abstraction of ESP-NOW with enhanced features.

    Device Roles

    ESP-NOW defines two roles based on data flow:

    • Initiator (发起者): Typically sensors, switches, or LCD screens that trigger actions.
    • Responder (响应者): Typically smart appliances like lights or sockets that react to commands. Note: A single device can act as both an Initiator and a Responder simultaneously.

    Core Capabilities

    • Fast Response: Millisecond-level response times without needing a full Wi-Fi connection.
    • High Compatibility: Works alongside Wi-Fi (Station/AP mode) and BLE.
    • Long Range & Multi-hop: Supports long-distance communication and multi-hop control for hundreds of devices.
    • Advanced Provisioning: Allows devices to share network credentials (SSID/Password) via ESP-NOW after the first device is provisioned via Bluetooth.
    • Secure Data: Supports ECDH and AES128-CCM for secure handshakes and data encryption.

  11. Enable ESP-NOW Auto Channel Switching

    master

    If the responder device is connected to an Access Point (AP), its channel is fixed. A coin cell button device, which is powered off most of the time, may not know which channel the responder is on.

    To support this, enable CONFIG_ESPNOW_CONTROL_AUTO_CHANNEL_SENDING=y.

    How it works:

    1. The initiator sends a command on a saved or default channel.
    2. If no acknowledgement is received within CONFIG_ESPNOW_CONTROL_WAIT_ACK_DURATION, the initiator retransmits the command CONFIG_ESPNOW_CONTROL_RETRANSMISSION_TIMES times.
    3. If still no acknowledgement is received, the initiator switches to other channels in the allowed list (defined by the Wi-Fi country code) and repeats the process.
    4. Once an acknowledgement is received, the initiator stops and saves that channel for the next transmission.

    Note on Country Regulations: Channel switching must comply with local regulations. Use esp_wifi_set_country to set the country code. The default is "01" (world safe mode), which allows channels 1 through 11 on the 2.4GHz band.

  12. Use ESP-NOW for firmware updates (OTA)

    master

    ESP-NOW can be used for mass firmware updates with the following features:

    • Resume from Breakpoint: Firmware is sent in fixed-size packets. If an update is interrupted, the device requests only the remaining packets to continue from where it left off.
    • Mass Deployment: Supports updating multiple devices simultaneously (e.g., up to 50 devices within 3 minutes).
    • Rollback Support: If an update fails, the device can roll back to the previous working firmware version.