How to Set Up PainlessMesh With a NodeMCUv2 (ESP8266) Board?

Sat, 04 Apr 2026 08:38:27 +0000

Hello, I'm Ganesh. I'm building git-lrc, an AI code reviewer that runs on every commit. It is free, unlimited, and source-available on Github. Star Us to help devs discover the project. Do give it a try and share your feedback for improving the product.

In this article, I will be demonstrating how to use PainlessMesh with a NodeMCUv2 (ESP8266) board.

What Problem we are solving?

ESP8266 is a low-cost Wi-Fi microcontroller. It is a popular choice for IoT projects.

Main advantage is it can connect to Wi-Fi network.

If it connect to network and it can transmit data wirelessly.

This make it suitable for IoT projects. Where we need to collect data from sensor and transmit to cloud or any other device.

But this also comes with a limitation. If we need to connect each ESP8266 board to router, then we need to have router in range of each ESP8266 board.

For Example I will name ESP8266 boards as Node A, Node B, Node C.

If Node A and B are within range of and connected to the gateway
If Node C is OUT of the range of the gateway and node B, but Node C is IN of the range of Node A

Node C cannot transmit data to cloud directly.

To Solve this problem we need a mesh or ad-hoc network. Where Node C can transmit data to Node A, and Node A can transmit data to router and then to cloud.

So, There are many ways to solve this problem. Multi Gateway, Repeater, Star Network, Mesh Network.

As, I did few experiments with ESP8266. I found PainlessMesh is a good solution for this problem.

What is PainlessMesh?

PainlessMesh creates a self organizing and repairing network where all nodes are connected.

All nodes in the mesh are equal. The network uses a star topology, avoiding any circular paths.

Messages between different nodes are sent in JSON format, making them easy to understand and produce.

So, Basicaly it is very easy to use and understand library for connecting multiple ESP8266 boards in a mesh network.

Key Features of PainlessMesh

We can see how network are connected in the image below.

It is True ad-hoc networking: Which means all nodes are equal and can communicate with each other. These self organizing and repairing network.

The number of nodes is limited only by the memory of the ESP8266 board.

JSON based: Messages between different nodes are sent in JSON format, making them easy to understand and produce.

Wifi & Networking: It uses ESP8266's wifi radio to create a mesh network.

painlessMesh is not IP networking: It does not use IP networking. It use esp8266's node id for communication for identifying nodes.

What are limitations of PainlessMesh?

If you know little bit about IOT you would have already identified limitations of PainlessMesh.

As it uses json based communication. More data will be consumed for just sending data.

As painlessmesh uses json to keep network alive. It will consume more power. That means instead of sending data esp8266 will be consuming lot of power to keep network alive.

There are many other limitations too. Also I found 2 articles which they had made performance check of painlessmesh. Here is one of the article Performance Assessment of ESP8266 Wireless Mesh Networks

But despite all these limitations, painlessmesh is a good library for small scale projects. which is compatible with ESP8266 boards.

Let's start with setting up painlessmesh with ESP8266.

How to use PainlessMesh With a NodeMCUv2 (ESP8266) Board?

In Previous article we saw how to use DHT22 sensor with ESP8266 in platformio.

Do refer if don't know how to setup platformio.

Now let's focus on setting up painlessmesh with ESP8266.

In the examples folder of painlessmesh library we can find many examples.

Let's start with the basic example.

Add this in platformio.ini file.

[env:nodemcuv2]
platform = espressif8266
board = nodemcuv2
framework = arduino
upload_speed = 115200
monitor_speed = 115200
upload_port = /dev/ttyUSB0
monitor_port = /dev/ttyUSB0
lib_deps = 
    painlessmesh/painlessMesh @ ^1.5.0
    bblanchon/ArduinoJson @ ^7.0.0

And upload the same code to 2 ESP8266 boards.

Add this in main.cpp file.

#include <Arduino.h>
#include <painlessMesh.h>
#include <ArduinoJson.h>

#define   MESH_PREFIX     "MyMeshNetwork"
#define   MESH_PASSWORD   "SecretPassword"
#define   MESH_PORT       5555

Scheduler     userScheduler; // to control your personal task
painlessMesh  mesh;

// Prototype
void receivedCallback( uint32_t from, String &msg );

// Send my ID every 10 seconds to inform others that I am the Server
Task logServerTask(10000, TASK_FOREVER, []() {
    JsonDocument jsonBuffer;
    JsonObject msg = jsonBuffer.to<JsonObject>();

    msg["topic"] = "logServer";
    msg["nodeId"] = mesh.getNodeId();

    String str;
    serializeJson(msg, str);
    mesh.sendBroadcast(str);

    // log to serial
    serializeJson(msg, Serial);
    Serial.printf("\n");
});

void setup() {
  Serial.begin(115200);

  // Keep debug messages clean: only show errors and connections
  mesh.setDebugMsgTypes( ERROR | CONNECTION );  

  mesh.init( MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, WIFI_AP_STA, 6 );
  mesh.onReceive(&receivedCallback);

  mesh.onNewConnection([](size_t nodeId) {
    Serial.printf("New Connection %u\n", nodeId);
  });

  mesh.onDroppedConnection([](size_t nodeId) {
    Serial.printf("Dropped Connection %u\n", nodeId);
  });

  // Add the task to your scheduler
  userScheduler.addTask(logServerTask);
  logServerTask.enable();
}

void loop() {
  mesh.update();
}

void receivedCallback( uint32_t from, String &msg ) {
  Serial.printf("logServer: Received from %u msg=%s\n", from, msg.c_str());
}

Initialize the mesh network.

Add debug messages.

Add new connection callback.

Add dropped connection callback.

Add the task to your scheduler. To make the wifi keep alive.

Compile and upload the code to 2 ESP8266 boards.

Output:

New Connection 1
New Connection 2
logServer: Received from 1 msg={"topic":"logServer","nodeId":1}
logServer: Received from 2 msg={"topic":"logServer","nodeId":2}

Conclusion

Will be shareing detailed example on how to connect painlessmesh with DHT22 sensor in next article.

Any feedback or contributors are welcome! It’s online, source-available, and ready for anyone to use.
⭐ Star it on GitHub: https://github.com/HexmosTech/git-lrc