MeshCore firmware architecture
Beneath the surface of every mesh node runs carefully structured code. Understanding this architecture EMPowers you to troubleshoot, optimise, and contribute.
MeshCore firmware: how does it work?
The MeshCore firmware orchestrates everything happening inside your mesh device. Written primarily in C/C++, it transforms ESP32, nRF52, and STM32 microcontrollers into intelligent network nodes.
The architecture prioritises modularity and hardware abstraction. A developer working on routing algorithms need not understand GPIO pin assignments, whilst someone adding display support need not comprehend packet encryption.
This page dissects the firmware structure, explaining how components interconnect and communicate. Whether you are diagnosing a misbehaving repeater in Manchester or developing custom functionality for a Bristol community network, this knowledge proves invaluable.
Core firmware modules
Five primary modules form the MeshCore firmware foundation:
1. Radio module (LoRa driver)
Directly interfaces with Semtech LoRa silicon (SX1262, SX1276). Manages transmission timing, frequency selection within the 868 MHz band, and power amplifier control.
2. Mesh routing module
Implements the intelligence that allows messages to traverse multiple hops. Maintains neighbour tables, calculates routing costs, and decides when forwarding serves the network.
3. Protocol module
Handles the MeshCore protocol stack: packet framing, message type identification, and AES-256 encryption for private communications.
4. Application module
Provides user-facing functionality: text messaging, GPS position sharing, telemetry broadcasting, and node identification.
5. Interface module
Bridges the firmware to external systems: Bluetooth smartphone connections, serial debugging, OLED/TFT displays, and physical button inputs.
System architecture
These modules collaborate through an event-driven design:
Event loop
A central loop continuously polls for events: arriving radio packets, Bluetooth data, button presses, timer expirations. Each event triggers appropriate module handlers without blocking other operations.
Interrupt-driven radio
Hardware interrupts from the LoRa chip Signal incoming packets. The radio module captures data immediately into a queue, processed later by the event loop to avoid timing-critical code in interrupt context.
Non-blocking design
No operation monopolises the processor. Encryption calculations, GPS acquisition, and display updates all yield control regularly, ensuring the event loop remains responsive to time-sensitive radio events.
Hardware abstraction layer (hal)
The HAL allows identical firmware logic to run across diverse hardware platforms:
GPIO abstraction
Physical pins for LEDs, buttons, and sensors map through configuration files. Code references logical names whilst the HAL translates to actual hardware pins.
SPI/I2C abstraction
Serial communication with LoRa chips (SPI) and displays (I2C/SPI) flows through HAL functions, each implemented specifically for the target microcontroller family.
Power management
Deep sleep modes, CPU frequency scaling, and peripheral power gating vary dramatically between ESP32 and nRF52. The HAL presents a unified interface for power-conscious operations.
File system
Configuration persistence and message storage utilise flash memory. ESP32 EMPloys LittleFS whilst nRF52 uses different implementations, both accessible through identical HAL calls.
Benefits of this architecture
Modularity
Modules maintain clear boundaries. Improving the routing algorithm requires no changes to display code. Bug fixes in one area rarely break another.
Multi-platform
The HAL enables MeshCore to support ESP32, nRF52, and STM32 families from a single codebase. New hardware ports require only HAL implementation.
Extensibility
Adding capabilities follows established patterns. Community contributors have added sensor integrations, display drivers, and protocol extensions with minimal friction.
Testability
Module isolation enables targeted testing. Unit tests verify routing logic without requiring physical radios. Integration tests confirm inter-module communication.
Performance
Event-driven, non-blocking design ensures rapid response to incoming packets. Messages route through busy networks without perceptible delays.
Open source
Every line of firmware code is publicly accessible. Audit the security implementation, understand exactly what your device executes, contribute improvements back to the community.
Frequently asked questions
In which programming language is the firmware written?
MeshCore firmware uses C++ for application logic and module implementation, with C for low-level HAL operations. The ESP32 variant builds on the Arduino framework, whilst nRF52 uses the Nordic SDK.
How much memory does the firmware use?
Typical ESP32 deployments consume ~200-300 KB of flash and ~40-60 KB of RAM. This leaves ample space for message storage, configuration data, and future feature additions.
Can I add my own modules?
Absolutely. The modular architecture welcomes extensions. Community members have added environmental sensor support, custom telemetry types, and specialised routing behaviours.
How often does the firmware update?
Major releases arrive every 2-3 months bringing new features. Critical bug fixes deploy faster as patch releases. The open-source nature means active development never stalls.
Is the firmware backwards compatible?
Yes, within major version families. A V2.3 node communicates seamlessly with V2.1 peers. Major version increments (V2.x to V3.0) may introduce protocol changes requiring coordinated upgrades.
Dive into the MeshCore firmware
With this architectural understanding, you are equipped to explore the source code, diagnose problems, develop custom features, or contribute improvements that benefit the entire British mesh community.