MeshCore Firmware

• MeshCore Firmware Variants Explained
• Flashing MeshCore Firmware
• Keeping MeshCore Firmware Updated

MeshCore Firmware Variants Explained

MeshCore is distributed as several distinct firmware variants, each designed for a specific role in the mesh. Choosing the correct variant is essential - running the wrong firmware type wastes resources and can degrade network performance.

The Firmware Variants

Companion (COMPANION)

The Companion firmware is for user-facing nodes. It is the firmware that end-users run on their personal devices to send and receive messages via the MeshCore mobile app.

• Primary function: Sends and receives direct messages and channel (group) messages. Maintains a contact list. Connects via BLE, USB serial, or WiFi to the MeshCore mobile app.
• Sub-variants: BLE (Bluetooth Low Energy), USB, and WiFi connection modes are available depending on hardware capability.
• When to use: Personal handheld nodes, base station nodes used for human communication, any node that a person interacts with via the MeshCore app.
• Firmware file example: rak4631_companion.uf2, tbeam_companion.bin

Repeater (REPEATER)

The Repeater firmware turns a node into a dedicated packet relay. It has no user interface and no messaging capability of its own.

• Primary function: Receives MeshCore packets and re-transmits them. Forwards packets to extend network reach.
• Resource profile: Minimal. No display driver, no BLE advertising for user connections (only for CLI access), no message store. Designed to run indefinitely on a small battery or solar.
• When to use: Any node whose sole purpose is extending mesh coverage - hilltop repeaters, building relay nodes, infrastructure backbone nodes.
• When NOT to use: Do not flash Repeater on a node you plan to use as a personal communicator. It has no user-facing messaging.
• Firmware file example: rak4631_repeater.uf2, tbeam_repeater.bin

Room Server (ROOM_SERVER)

The Room Server firmware creates a store-and-forward message hub. Room servers act as persistent group chat rooms accessible via LoRa.

• Primary function: Stores incoming messages and delivers them to nodes that connect later (offline delivery). Acts as a central hub for group communication.
• When to use: Fixed infrastructure nodes serving as community message hubs - in a building, on a hilltop tower, or at an event site where persistent message history is needed.
• Firmware file example: rak4631_roomserver.uf2, tbeam_roomserver.bin

Sensor (SENSOR)

The Sensor firmware is for nodes that collect and transmit environmental or telemetry data.

• Primary function: Reads sensor data (temperature, humidity, GPS, etc.) and transmits it to the mesh network.
• When to use: Unattended monitoring nodes - weather stations, asset trackers, environmental sensors.
• Hardware support: Primarily nRF52840-based boards (RAK4631, T114) due to their low power consumption and hardware sensor interfaces.
• Firmware file example: rak4631_sensor.uf2

Summary Table

Firmware	User Messaging	Packet Relay	Message Store	Sensor Data
Companion	Yes	No	Local only	No
Repeater	No	Yes	No	No
Room Server	No	Optional	Yes (network-wide)	No
Sensor	No	No	No	Yes

Source: MeshCore official documentation and firmware repository at github.com/meshcore-dev/MeshCore

Flashing MeshCore Firmware

MeshCore firmware can be installed on supported hardware using two primary methods: the MeshCore Web Flasher (browser-based) and UF2 drag-and-drop (for nRF52840 boards only).

Method 1: MeshCore Web Flasher

The MeshCore Web Flasher is the recommended method for most users. It runs entirely in a browser and uses the WebSerial API to communicate with the board over USB.

URL: https://flasher.meshcore.io

Browser Requirements

The WebSerial API is only available in Chromium-based browsers:

• Google Chrome (version 89 or later) - recommended
• Microsoft Edge (version 89 or later) - supported
• Firefox, Safari - NOT supported. WebSerial is not implemented in these browsers.

Step-by-Step: Initial Flash

1. Open flasher.meshcore.io in Chrome or Edge.
2. Connect your board to your computer via USB.
3. Select your board type from the dropdown (e.g., RAK4631, T-Beam v1.2, Heltec V3).
4. Select the firmware variant you want to flash:
   • Companion - for personal use nodes (connects to MeshCore app)
   • Repeater - for dedicated packet relay infrastructure nodes
   • Room Server - for store-and-forward message hub nodes
   • Sensor - for telemetry/environmental monitoring nodes (nRF52840 boards only)
5. Select the firmware version (latest stable is selected by default).
6. Click Connect. A browser dialog will appear listing available serial ports - select your device.
7. Click Flash. The flasher will download the firmware and write it to the device. This typically takes 30-90 seconds.
8. The board will reboot automatically after flashing.
9. First-boot setup: connect via BLE using the MeshCore app to configure the node name and preset (frequency/spreading factor profile).

Step-by-Step: OTA Update

For updating an existing MeshCore node, the process is the same as initial flash. The flasher will overwrite the existing firmware. Your saved configuration is generally preserved across firmware updates, but it is good practice to note your settings before updating.

Method 2: UF2 Drag-and-Drop (nRF52840 boards only)

Boards based on the nRF52840 MCU (RAK4631, T114, Heltec HT-n62) support UF2 flashing without needing a browser or WebSerial.

1. Download the correct .uf2 file for your board and firmware variant from the MeshCore firmware releases page on GitHub.
2. Put the board into bootloader mode: double-tap the reset button rapidly. The board will appear as a USB mass storage drive named something like RAK4631 or NICENANO.
3. Copy the .uf2 file onto the USB drive. The board will automatically flash and reboot.

Platform-Specific Setup Notes

Windows

Many LoRa development boards use USB-to-serial bridge chips (CP2102, CH340, FTDI). If the board is not recognized, you may need to install the driver for your specific USB chip. Check Device Manager for unknown devices. Common driver sources:

• CP2102/CP2104: Silicon Labs VCP driver
• CH340/CH341: WCH driver
• FTDI: FTDI Virtual COM Port driver

Linux

Most USB-serial chips work out of the box on modern Linux. If you get permission errors with WebSerial or serial tools, add your user to the dialout group: sudo usermod -a -G dialout $USER and log out/in.

macOS

macOS 11 and later include drivers for CP2102 and CH340. Older macOS versions may need manual driver installation. If the device doesn't appear, check System Information > USB.

Keeping MeshCore Firmware Updated

Keeping your MeshCore nodes on current firmware is important for stability, interoperability, and security. This page covers why updates matter, how to check your current version, update strategies for deployed infrastructure, and how to handle rollbacks.

Why Updates Matter

Bug Fixes

MeshCore is actively developed software. Each release typically resolves routing edge cases, BLE connectivity issues, memory leaks, and hardware-specific quirks. Running old firmware means running known bugs that may have already been fixed.

Performance Improvements

Routing algorithm refinements, radio parameter tuning, and message handling optimizations are regularly incorporated. A network of nodes all running the same recent firmware will generally route more efficiently than one running a mixture of old builds.

New Features

New capabilities - new sensor types, new room server features, new CLI commands, new position reporting formats - are only available in the firmware version that introduced them. Staying reasonably current ensures you can use new functionality as it becomes available.

Security Patches

While MeshCore is a mesh radio protocol rather than an internet-facing service, vulnerabilities can still exist. Malformed packet handling bugs, cryptographic implementation issues, and BLE pairing weaknesses are all possible attack surfaces. Security-relevant fixes are tagged in release notes; apply them promptly.

Version Compatibility

MeshCore nodes on significantly different firmware versions may have interoperability limitations, particularly across major version boundaries. Keeping your infrastructure nodes current minimizes the risk of incompatibility with nodes running newer client firmware.

Checking Your Current Firmware Version

There are two ways to check the firmware version on a node:

Via the MeshCore App

Connect to the node via the MeshCore app. Navigate to the node's detail or settings view. The firmware version is displayed in the device information section.

Via the MeshCore CLI

Connect to your node using a BLE serial terminal or the MeshCore CLI tool and run:

status

The output will include a line such as:

Firmware: MeshCore v2.4.1 (rak4631_repeater)
Built: 2026-03-15

The version number, board variant, and build date are all shown.

Update Strategy for Infrastructure Nodes

Repeaters and room servers are infrastructure - other users depend on them. Updating carelessly can cause network disruption. Follow this strategy:

1. Test on a Non-Critical Node First

If you operate multiple nodes, update one non-critical node (a spare, or the lowest-traffic repeater) to the new firmware first. Run it for 24 - 48 hours and verify:

• The node comes back online and connects to the mesh after the update.
• Routing works correctly through the node.
• No unexpected reboots or radio lockups occur.
• BLE connectivity from the app functions normally.

2. Preserve Configuration Before Updating

Before updating any node, record its current configuration:

• Node name
• Frequency preset and any custom radio parameters
• TX power setting
• Any custom channel configurations (for room servers: room name, password)

Use the CLI status command and screenshot or copy the output. While configuration is generally preserved across firmware updates (stored in non-volatile flash separate from the firmware), a failed or interrupted flash can result in settings being wiped.

3. Update During Low-Traffic Periods

Infrastructure nodes go offline during flashing (typically 30 - 90 seconds). Schedule updates during periods when the network is least used to minimize impact on other users.

4. Update Infrastructure Before Clients

When a new major or minor version is released, update repeaters and room servers before client nodes. Infrastructure nodes carry traffic for all clients; having them on newer firmware ensures they can handle any new packet formats clients may start using.

How to Update

The update process is identical to initial flashing - there is no separate "OTA update" mechanism that avoids physical access for most boards:

1. Connect the node to a computer via USB.
2. Open the MeshCore Web Flasher at flasher.meshcore.io in Chrome or Edge.
3. Select your board type and firmware variant.
4. Select the new firmware version.
5. Click Connect, select the serial port, then click Flash.
6. Wait for the flash to complete and the board to reboot.
7. Verify the node is operational using the status command.

For nRF52840 boards (RAK4631, T114, HT-n62): UF2 drag-and-drop is available as an alternative. Download the new .uf2 file, enter bootloader mode (double-tap reset), and copy the file to the USB drive.

Rollback: Returning to a Previous Version

If a firmware update causes problems, you can return to any previous version:

1. Open the MeshCore Web Flasher.
2. Select your board and variant.
3. Use the version selector to choose the previous known-good version (older versions are retained in the flasher's version history).
4. Flash as normal.

For UF2 boards: download the previous version's .uf2 file from the MeshCore GitHub releases page and flash it via drag-and-drop.

Note: Configuration is generally preserved across rollbacks. However, if a newer firmware version introduced a new configuration key that older firmware does not understand, the old firmware may ignore or reset that setting.

Coordinating Community Network Updates

If you operate nodes on a shared community network, coordinate updates with other network operators:

• Announce planned updates in your community's Discord, forum, or group chat before updating shared infrastructure.
• Share the release notes link so other operators can review what has changed.
• If a major version update is involved, agree on a migration window so all infrastructure nodes are updated together, minimizing the period of mixed-version operation.
• After updating, post a confirmation in the coordination channel so others know the node is back online and on the new version.

Same Version Compatibility Notes

Within the same major version, MeshCore nodes running different minor versions can generally communicate. However:

• Nodes running a minor version that introduced a new packet type will generate packets that older minor-version nodes may not fully process (they will forward them but may not display them correctly).
• Patch versions within the same minor version are always compatible - a 2.4.0 node and a 2.4.3 node will interoperate fully.
• When in doubt, check the release notes for any compatibility warnings. The MeshCore team typically calls out cross-version compatibility issues explicitly.