Micropycelium - prototype routable mesh network for ESP32

## Introduction

Micropycelium is a prototype, routable mesh network. The purpose was to create a low-cost, autonomous networking system that could be deployed at scale in the wake of natural disasters or other catastrophes in which the standard telecommunications systems have been severely damaged. The ultimate goal of the project is an easy-to-deploy router (eventually with solar panel recharging capabilities) and easy-to-use hand-held devices or network adapters.

The code and documentation for the project can be found in the GitHub repo, and the build instructions are linked in the readme. Below is an overview of the system.

I presented this project at the HackNWA 2025 tech conference with a short live demo. The slides can be found here.

## Hardware Selection

The current form is an initial proof-of-concept. For this, I selected a handful of ESP-32 devices from M5stack for experimentation. I found that the M5Stamp Pico and S3 both worked well, while the C3 and C3U were not able to handle the asynchronous workload. The M5StickC-Plus-2 also worked well in my testing. Firmware build instructions for them all can be found in the GitHub repo.

For simplicity, I paired the M5stamp-S3 with a simple LiPo battery pack from Amazon. I attempted to connect the M5stamp-Pico with batteries, but I could not get it to work with the buck regulators I had on hand -- in principle, it should work with adequate voltage, but I could only get them to work with the ESP downloader tool connected to a computer or on a breadboard with an AC/DC power supply.

I currently recommend the Stamp S3 over the Stamp Pico because it is much easier to use: all you need is a USB-A to USB-C data cable.

## Algorithm Selection

To make an autonomous, routable network, a greedy algorithm was required. Greedy routing algorithms are able to route packets using only the data locally known to a router without any central collection of data or centralized assignment of numbers. There were several candidates to choose from, and I chose to adapt the Virtual Overlays Using Tree Embeddings system. In VOUTE, nodes create a spanning tree using just communications with their direct peers (network neighbors), and the protocol is designed to eventually settle with all nodes assigned a location within one logical tree that spans the whole network.

For this prototype, I chose an address space of 128 bits encoding up to 32 coordinates. After a root is elected by its node ID, it takes an empty set of coordinates as its address, then each of its neighbors become a child in the tree by taking a single coordinate such that each child of the root has a different coordinate. They then offer to accept their neighbors as children, and any children take their parent's coordinates plus an additional coordinate. This continues until all nodes in the network have an address, and the addresses describe a subset of the network connectivity. Routing is then done by comparing the destination address to the addresses of peers and forwarding to the peer with the shortest calculated distance to the destination; each hop then causes the packet to be forwarded closer to the destination until it arrives.

## Software Design

The software was written entirely by hand (no AI assistance) in micropython. It has a few main components:

1. The main `Packager` class, which handles all packet routing and event management logic.2. Serialization/encapsulation classes and helper functions3. Helper classes for managing peers, queued events, addresses, applications, etc4. Interface adapter for ESP-NOW.5. Applications for peer discovery, gossip, construction and maintenance of the spanning tree, and testing/debugging.6. A load of unit and e2e tests to ensure everything works correctly.7. Console code and miscellaneous firmware to make it useful in ESP32 hardware.

The `Packager` class is the most important and complex part of the project. It integrates all the logic from the rest of the system. I structured this to be very modular and extensible: network interface adapters and applications can be written in a plug-and-play way. The `Packager` uses an asynchronous control flow and contains an event scheduler to handle periodic synchronization tasks, etc. In total, the main code base is over 4400 lines of code; the console/machine-specific firmware code has another 1200+ lines; and the test suite is another 3000+ lines (without mocks). The total code base is close to 9000 lines long, and it is all released under the ISC License (equivalent to MIT).

## Video