ESP-NOW on the ESP8266: espnow.h, roles and peers
Yes. You can use the ESP-NOW (ESP8266 core) library online in Mokxi with nothing to install, and the sketch runs in your browser. The example below, "ESP-NOW on two NodeMCUs", runs on the ESP8266 NodeMCU V1.0.
Built in on Mokxi: #include <espnow.h> and it builds, with nothing to install. Free, and no account needed.
What ESP-NOW (ESP8266 core) does
The ESP8266 speaks ESP-NOW too, but through its own header, espnow.h from the ESP8266 Arduino core, built on the older Non-OS SDK. The idea is the ESP32’s: a frame of up to 250 bytes goes straight to another board’s MAC address with no router in between. The calls look similar and are not the same, which is why code copied from an ESP32 tutorial fails to compile on a NodeMCU or Wemos D1 Mini.
Three things differ. Each board declares a role with esp_now_set_self_role(): ESP_NOW_ROLE_CONTROLLER to send, ESP_NOW_ROLE_SLAVE to receive, ESP_NOW_ROLE_COMBO for both. Peers are added with the MAC, role, channel, key and key length as separate arguments, not a struct. And the functions return 0 for success, where the ESP32 returns ESP_OK, while callbacks take a plain uint8_t pointer for the MAC.
The runnable project is two NodeMCUs: one sends a count, a short text and the reading of a knob on A0 every two seconds, the other prints each message and blinks its on-board LED. Mokxi puts both on the same simulated air as its ESP32s, so an ESP8266 here can talk to an ESP32 too. Roles and keys are stored, nothing is encrypted, and range is not modeled.
| Library Manager name | ESP-NOW (ESP8266 core) |
|---|---|
| Author | Espressif |
| Include | #include <espnow.h> |
| Boards | ESP8266 NodeMCU |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
Install it
It builds on ESP8266 NodeMCU.
In Mokxi it is built in: #include <espnow.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board it comes with the board package (Espressif), so the Arduino IDE has it as soon as the board is installed: there is nothing to add from the Library Manager.
The calls you will use
In the order a sketch meets them.
esp_now_init()
Starts ESP-NOW once WiFi.mode(WIFI_STA) is set. Returns 0 on success, any other value on failure.
esp_now_set_self_role(ESP_NOW_ROLE_CONTROLLER)
Declares what this board does. Senders use CONTROLLER, receivers SLAVE, and a board that does both COMBO.
esp_now_add_peer(receiverMac, ESP_NOW_ROLE_SLAVE, 1, NULL, 0)
Adds a peer by MAC with its role, its WiFi channel (1 here) and no key. Returns 0 when it was added.
esp_now_register_send_cb(onSent)
Registers void onSent(uint8_t *mac, uint8_t status). A status of 0 means the receiver acknowledged.
esp_now_send(receiverMac, (uint8_t *)&msg, sizeof(msg))
Sends up to 250 bytes to that peer. Passing NULL as the address sends to every peer in the list.
esp_now_register_recv_cb(onReceive)
Registers void onReceive(uint8_t *mac, uint8_t *data, uint8_t len), run as each frame arrives. Keep it short and set a flag for loop().
void onReceive(uint8_t *mac, uint8_t *data, uint8_t len) {
if (len == sizeof(msg)) memcpy(&msg, data, len);
got = true;
}Example: ESP-NOW on two NodeMCUs
On the ESP8266 NodeMCU V1.0. It runs in the browser exactly as printed.
// ESP-NOW on the ESP8266: a count and a knob reading every two seconds to the other board.
//
// The ESP8266 core's espnow.h, as the NodeMCU tutorials use it: a role, a
// peer added with its channel, and a send callback that gets 0 when the
// receiver's radio acknowledged the frame. The receiver's MAC is written
// below; in this project its wifiMac setting is that address.
#include <ESP8266WiFi.h>
#include <espnow.h>
uint8_t receiverMac[] = {0x02, 0x4D, 0x4F, 0x00, 0x82, 0x66};
typedef struct {
char text[32];
int count;
int dial; // the knob on A0, 0 to 1023
} Message;
Message msg;
unsigned long lastSend = 0;
void onSent(uint8_t *mac, uint8_t status)
{
(void)mac;
Serial.print("Last packet send status: ");
Serial.println(status == 0 ? "Delivery success" : "Delivery fail");
}
void setup()
{
Serial.begin(115200);
WiFi.mode(WIFI_STA);
Serial.print("Sender MAC: ");
Serial.println(WiFi.macAddress());
if (esp_now_init() != 0) {
Serial.println("Error initializing ESP-NOW");
return;
}
esp_now_set_self_role(ESP_NOW_ROLE_CONTROLLER);
esp_now_register_send_cb(onSent);
esp_now_add_peer(receiverMac, ESP_NOW_ROLE_SLAVE, 1, NULL, 0);
}
void loop()
{
if (millis() - lastSend > 2000) {
lastSend = millis();
strcpy(msg.text, "hello from the NodeMCU");
msg.count++;
msg.dial = analogRead(A0);
esp_now_send(receiverMac, (uint8_t *)&msg, sizeof(msg));
}
}Open it in the editor, wired and ready to run · ESP-NOW on two NodeMCUs: the project page
Common errors and how to fix them
esp_now.h: No such file or directory (on a NodeMCU)
That header is the ESP32’s. On the ESP8266 include <ESP8266WiFi.h> and <espnow.h>, then rewrite the setup with roles and the five-argument esp_now_add_peer(). The checks change from ESP_OK to 0 as well.
Last packet send status: Delivery fail
The MAC in receiverMac does not match the receiver, or the channel passed to esp_now_add_peer() differs from the one the receiver is on. Print WiFi.macAddress() on the receiver, copy it exactly and keep both boards on one channel.
The board resets with a watchdog message when a message arrives
The receive callback runs in the WiFi system context, where delay(), long Serial output and heavy work are unsafe on the ESP8266. Copy the data, set a volatile flag, and do the printing and blinking in loop(), as the example does.
Questions and answers
Does the role matter if both boards send and receive?
Set ESP_NOW_ROLE_COMBO on both and add each other as COMBO peers. The roles are mostly bookkeeping in the SDK, but tutorials and examples rely on them being consistent.
Why does my struct arrive wrong on an ESP32?
Fields of different sizes can be padded differently. Use fixed types such as int32_t and uint8_t in the same order on both, and compare len with sizeof() on the receiving side.
Keep going
Learn
Try ESP-NOW (ESP8266 core) without installing anything
Open the example, change the sketch, and keep your version in a free account.