Firmware development

MeshCore firmware architecture

Technical explanation of the MeshCore firmware: modules, components and internal architecture for developers

Discover MeshCore → Read more ↓

MeshCore firmware: how does it work?

The MeshCore firmware is the software that runs on ESP32, nRF52 and STM32 chipsets. It is written in C/C++ and consists of multiple modular components that work together to make the mesh network function.

The firmware architecture is designed with modularity and hardware abstraction in mind. This makes it possible to use the same codebase for different hardware platforms without major modifications.

This page explains how the firmware is internally structured, which modules exist, and how they work together.

Core firmware modules

The MeshCore firmware consists of 5 main modules:

1. Radio module (LoRa driver)

Manages the LoRa radio chip (SX1262, SX1276, etc). Handles transmission, reception, frequency hopping and power management.

radio.init(868MHz, SF9, BW125, CR4_5); radio.send(packet, size); radio.receive(callback);

2. Mesh routing module

Implements the mesh routing algorithm. Determines which messages should be forwarded, maintains a neighbor list, and manages the routing table.

routing.handlePacket(packet); routing.addNeighbor(nodeId, rssi, snr); routing.findRoute(destination);

3. Protocol module

Implements the MeshCore protocol: packet encoding/decoding, message types, encryption/decryption with AES-256.

protocol.encodePacket(message, dest); protocol.decodePacket(rawData); protocol.encrypt(payload, key);

4. Application module

Contains the application logic: text messages, GPS, telemetry, node info. This is what the user sees and uses.

app.sendMessage("Hello", userId); app.updatePosition(lat, lon, alt); app.getTelemetry();

5. Interface module

Manages communication with external interfaces: Bluetooth (smartphone), Serial (CLI), Screen (OLED/TFT), Buttons.

bluetooth.init(); bluetooth.sendToApp(message); screen.display(text);

System architecture

The modules work together in an event-driven architecture:

Event loop

The firmware runs a main event loop that continuously checks for events: incoming radio packet, Bluetooth message, button press, timer expired. Each event triggers the appropriate module.

Interrupt-driven radio

The LoRa chip triggers a hardware interrupt when a packet is received. The radio module places the packet in a queue, which is processed in the event loop.

Non-blocking design

All operations are non-blocking. Long tasks (like encryption or GPS fix) use background tasks or are split into smaller steps to keep the event loop responsive.

Start with MeshCore →

Hardware Abstraction Layer (HAL)

The HAL makes it possible to run the same firmware on different hardware:

GPIO abstraction

Buttons, LEDs and other GPIO pins are controlled via a HAL interface. Each hardware variant has a config file with pin mappings.

hal_gpio_write(LED_PIN, HIGH);

SPI/I2C abstraction

Communication with LoRa chip (SPI) and displays (I2C/SPI) goes via HAL functions that are implemented differently per platform.

hal_spi_transfer(data, size);

Power management

Deep sleep, CPU frequency scaling and peripheral power control are platform-specific and abstracted via HAL.

hal_enter_deep_sleep(seconds);

File system

Configuration and messages are stored in flash. ESP32 uses LittleFS, nRF52 uses a different implementation, but the same HAL API.

hal_fs_write("config.json", data);

Benefits of this architecture

🔧

Modularity

Modules are loosely coupled. You can update the routing module without touching the radio module.

📱

Multi-platform

Thanks to HAL the same codebase works on ESP32, nRF52 and STM32.

🔄

Extensibility

New features are easy to add as extra modules.

🐛

Testability

Modules can be tested individually. Unit tests per module.

⚡

Performance

Event-driven and non-blocking design ensures low latency and good responsiveness.

🔓

Open source

The entire firmware is open source. You can read, modify and contribute to the code.

Frequently asked questions

In which programming language is the firmware written?

The MeshCore firmware is written in C++ (for most modules) and C (for low-level HAL). It uses the Arduino framework for ESP32 and Nordic SDK for nRF52.

How much memory does the firmware use?

On ESP32 the firmware uses ~200-300 KB flash and ~40-60 KB RAM. This leaves enough room for message storage and future features.

Can I add my own modules?

Yes, the modular architecture makes it easy to add your own modules. For example: an extra sensor module, custom routing logic, or a new interface.

How often does the firmware update?

MeshCore has active development with releases every 2-3 months. Bugfixes come faster, new features in major releases.

Is the firmware backwards compatible?

Yes, the protocol is backwards compatible within major versions. A v2.3 node can communicate with v2.1 nodes. With a major update (v3.0) this may change.

Dive into the MeshCore firmware

Now that you understand the firmware architecture, you can explore the source code, contribute to development, or make your own modifications.

View devices → Learn more about MeshCore →