MeshCore Firmware Architecture

MeshCore firmware is written in C/C++ and is structured around five core modules plus a Hardware Abstraction Layer (HAL). Understanding the architecture helps when building custom integrations, contributing to the project, or diagnosing unusual behavior.

Canonical repository: github.com/meshcore-dev/MeshCore (core team). Andy Kirby's fork (MeshOS, optimized for T-Deck standalone devices) is at meshcore.co.uk. Both derive from the same original codebase but have diverged since the April 2026 governance split.

The five core modules

1. Radio Module

Interfaces directly with the LoRa transceiver (SX1262 / SX1276 / LR1110). Responsibilities:

• LoRa radio initialization with correct modem parameters (frequency, SF, BW, CR)
• Transmit queue management and airtime limiting
• Receive interrupt handling and packet CRC verification
• CAD (Channel Activity Detection) — listen-before-transmit to reduce collisions
• RSSI and SNR reporting per received packet

2. Routing Module

Manages path discovery and packet forwarding. MeshCore uses path-discovery routing rather than flooding:

• When a node wants to reach a destination, it broadcasts a route request (RREQ)
• Repeaters forward the RREQ, appending their node ID to build a path record
• The destination responds with a route reply (RREP) containing the full discovered path
• Subsequent packets follow the stored path rather than being flooded to all nodes
• Paths expire after a configurable timeout and are re-discovered on demand

This is fundamentally different from Meshtastic's flooding approach — path-discovery routing is more efficient in larger, stable networks but requires initial discovery overhead.

3. Protocol Module

Handles the MeshCore packet format, encryption, and message types:

• AES-256-CTR encryption for all message payloads
• Packet types: advertisement, route request/reply, direct message, channel message, ACK, telemetry
• Sequence number tracking for deduplication
• Fragmentation and reassembly for payloads exceeding MTU

4. Application Module

The user-facing layer. Handles:

• Contact management (storing known nodes and their path information)
• Channel management (public and named channels)
• Configuration persistence (settings stored to flash)
• Advertisement scheduling and hop count management
• Telemetry collection (battery, GPS, environmental sensors)

5. Interface Module

Provides access methods for interacting with the node:

• BLE GATT service (primary interface for companion apps)
• USB serial (CLI access; also used by the Python library)
• WiFi TCP server (ESP32 devices only)
• Display output (OLED, e-ink, TFT — device dependent)
• Button and input handling

Hardware Abstraction Layer (HAL)

The HAL abstracts platform-specific differences, allowing the same firmware core to run on multiple MCU families:

Platform	MCU	Key differences
ESP32-S3	Xtensa dual-core 240 MHz	WiFi + BLE, higher power draw, larger flash, TCP interface available
nRF52840	ARM Cortex-M4 64 MHz	BLE only, ultra-low power, SoftDevice BLE stack, USB CDC
STM32	ARM Cortex-M (varies)	Limited community support; used in some specialized boards

Build system

MeshCore uses PlatformIO (on top of Arduino framework) for building firmware. To build from source:

# Clone the repository
git clone https://github.com/meshcore-dev/MeshCore
cd MeshCore

# Install PlatformIO (if not already installed)
pip install platformio

# Build for a specific target (example: RAK4631 nRF52840)
pio run -e rak4631_repeater

# Flash
pio run -e rak4631_repeater --target upload

Contributing

The project uses a standard GitHub PR workflow. For significant changes, open an issue first to discuss approach. The core team reviews PRs regularly. Bug reports and hardware compatibility reports are particularly valuable — post to the issues tracker or the official Discord.