You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Kurt Wilson 07342e7a46
Merge pull request #1 from Kurtoid/patch-1
update markdown for GitHub
4 years ago
examples Fixed printf statement in startHere receivedCallback() 8 years ago
src Fixed printf statement in startHere receivedCallback() 8 years ago
.DS_Store Fixed printf statement in startHere receivedCallback() 8 years ago Created LICENCE 8 years ago update markdown for GitHub 4 years ago
library.json Modifications & additions for publishing as library 8 years ago Modifications & additions for publishing as library 8 years ago

Intro to easyMesh

easyMesh is a library that takes care of the particulars for creating a simple mesh network using Arduino and esp8266. The goal is to allow the programmer to work with a mesh network without having to worry about how the network is structured or managed.

True ad-hoc netoworking

easyMesh is a true ad-hoc network, meaning that no-planning, central controller, or router is required. Any system of 1 or more nodes will self-organize into fully functional mesh. The maximum size of the mesh is limited (i think) by the amount of memory in the heap that can be allocated to the sub-connections buffer… and so should be really quite high.

JSON based

easyMesh uses JSON objects for all its messaging. There a couple of reasons for this. First, it makes the code and the messages human readable and easy to understand and second, it makes it easy to integrate easyMesh with javascript front-ends, web applications, and other apps. Some performance is lost, but I havent been running into performance issues yet. Converting to binary messaging would be fairly straight forward if someone wants to contribute.

Wifi & Networking

easyMesh is designed to be used with Arduino, but it does not use the Arduino WiFi libraries, as I was running into performance issues (primarily latency) with them. Rather the networking is all done using the native esp8266 SDK libraries, which are available through the Arduino IDE. Hopefully though, which networking libraries are used wont matter to most users much as you can just include the .h, run the init() and then work the library through the API.

easyMesh is not IP networking

easyMesh does not create a TCP/IP network of nodes. Rather each of the nodes is uniquely identified by its 32bit chipId which is retrieved from the esp8266 using the system_get_chip_id() call in the SDK. Every esp8266 will have a unique number. Messages can either be broadcast to all of the nodes on the mesh, or sent specifically to an individual node which is identified by its chipId.


demoToy is currently the only example. It is kind of complex, uses a web server, web sockets, and neopixel animations, so it is not really a great entry level example. That said, it does some pretty cools stuff… here is a video of the demo.


easyMesh makes use of the following libraries. They can both be installed through Arduino Library Manager

easyMesh API

Using easyMesh is easy!

First include the library and create an easyMesh object like this…

#include <easyMesh.h>
easyMesh  mesh;

Member Functions

void easyMesh::init( String prefix, String password, uint16_t port )

Add this to your setup() function. Initialize the mesh network. This routine does the following things…

  • Starts a wifi network
  • Begins searching for other wifi networks that are part of the mesh
  • Logs on to the best mesh network node it finds… if it doesnt find anything, it starts a new search in 5 seconds.

prefix = the name of your mesh. The wifi ssid of this node will be prefix + chipId password = wifi password to your mesh port = the TCP port that you want the mesh server to run on

void easyMesh::update( void )

Add this to your loop() function This routine runs various maintainance tasks... Not super interesting, but things don't work without it.

void easyMesh::setReceiveCallback( &receivedCallback )

Set a callback routine for any messages that are addressed to this node. The callback routine has the following structure…

void receivedCallback( uint32_t from, String &msg )

Every time this node receives a message, this callback routine will the called. “from” is the id of the original sender of the message, and “msg” is a string that contains the message. The message can be anything. A JSON, some other text string, or binary data.

void easyMesh::setNewConnectionCallback( &newConnectionCallback )

This fires every time the local node makes a new connection. The callback has the following structure…

void newConnectionCallback( bool adopt )

adopt is a boolean value that indicates whether the mesh has determined to adopt the remote nodes timebase or not. If adopt == true, then this node has adopted the remote nodes timebase.

The mesh does a simple calculation to determine which nodes adopt and which nodes dont. When a connection is made, the node with the smaller number of connections to other nodes adopts the timebase of the node with the larger number of connections to other nodes. If there is a tie, then the AP (access point) node wins.

Example 1:

There are two separate meshes (Mesh A and Mesh B) that have discovered each other and are connecting. Mesh A has 7 nodes and Mesh B has 8 nodes. When the connection is made, Mesh B has more nodes in it, so Mesh A adopts the timebase of Mesh B.

Example 2:

A brand new mesh is starting. There are only 2 nodes (Node X and Node Y) and they both just got turned on. They find each other, and as luck would have it, Node X connects as a Station to the wifi network established by Node Ys AP (access point)… which means that Node X is the wifi client and Node Y is the wifi server in the particular relationship. In this case, since both nodes have zero (0) other connections, Node X adopts Node Ys timebase because the tie (0 vs 0) goes to the AP.

bool easyMesh::sendBroadcast( String &msg)

Sends msg to every node on the entire mesh network.

returns true if everything works, false if not. Prints an error message to Serial.print, if there is a failure.

bool easyMesh::sendSingle(uint32_t dest, String &msg)

Sends msg to the node with Id == dest.

returns true if everything works, false if not. Prints an error message to Serial.print, if there is a failure.

uint16_t easyMesh::connectionCount()

Returns the total number of nodes connected to this mesh.

uint32_t easyMesh::getChipId( void )

Return the chipId of the node that we are running on.

uint32_t easyMesh::getNodeTime( void )

Returns the mesh timebase microsecond counter. Rolls over 71 minutes from startup of the first node.