PainlessMesh Technical Documentation
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. Information on the JSON schema used for the various messages can be found here.
List of features
- Fairly easy setup.
- Usable on Arduino environment.
- Implemented as a layer-3 protocol. Connectionless and without confirmation.
- Totally asynchronous. No need to poll for new messages.
- Accurate time synchronization. All nodes share same clock with a precision better than 10 ms.
- All nodes know the complete topology instantly. Updated every 3 seconds.
- Mesh autoconfigure itself. Any node can be disconnected in any moment. Any new node is integrated automatically.
- All nodes continuously monitor its directly connected peers to check if they are active.
- Single addressed and broadcast messages are possible.
- Network loops are actively avoided.
Every node acts as an accesspoint (AP) for other nodes to connect to and as a client to connect to one AP of another node. There is a limit of 4 station nodes per AP for ESP8266 and 10 for ESP32.
Each node which is not already/anymore connected to an AP, scans for AP's from other nodes periodically. It will connect to the AP with the strongest signal, which is not already present in the list of connections or sub-connections, i.e. which is not known yet to the node. By only connecting to unknown APs the mesh avoids the creation of network loops, such that there is a single route between each pair of nodes in the mesh.
The direction of the arrow represents the direction in which connections are made.
A list of connections of the node is stored and for each connection a list of sub-connections is also stored. (Note: the list of connections contains the connections which are received by the node and the connection (max 1) that are initiated by the node.). Every node knows the complete network topology.
The list of sub-connections per node is obtained by a request/response message. The request contains the sub-connections of the requesting node, and the response contains the sub-connections of the responding node. The collection of sub-connections returned, always excludes the requesting connection and its sub-connections. For more information see the protocol information
Cases in which a new node sync is done
- Request for sub-connections is done periodically
- When any update in the network is detected, i.e. any sub-connection of a node has changed
- When a new node connects to a new AP
With the star network topology without any loops. routing becomes very easy. There is a single route for each node pair.
For single messages, a destination and origin node is specified. First the connection to use is looked up. Either the direct connection, or the connection which has a sub-connection to the destination node. The message is send to that node. When that node is not the destination node, the exact message is relayed to the next connection, which is looked up in the same way. This repeats until the message arrives at the destination node.
Messages are not acknowledged. This should be implemented at application level.
For broadcast messages, all connections are iterated and the message is sent to each connection. Upon receiving the broadcast message, the message is relayed to all connections of the receiving node, except for the connection by which the message is received.