MeshCore Firmware Guide

Keep your MeshCore device running the latest firmware for bug fixes, new features, and security improvements. Updating takes about 5 minutes.

This guide covers how to check your version, when to update, different update methods, firmware variants explained, and troubleshooting common flash failures.

Current Firmware

MeshCore firmware is actively developed with frequent releases. Check the official flasher or GitHub for the latest version:

MeshCore Flasher GitHub Releases

How to Check Your Current Version

Open the MeshCore companion app, connect to your device via Bluetooth, and look at the device info screen. Your firmware version is displayed there. You can also check via the CLI using the info command.

Should I Update?

Update When:

A security fix is released
A bug you've experienced is fixed
A feature you want is added
You're setting up a new device for the first time
Your version is more than 2-3 major releases behind

Wait When:

Your current setup is working perfectly and you don't need new features
The release is marked as beta or pre-release
You're running a remote repeater that's hard to access physically
You're about to leave for a trip and don't want to risk issues

Update Methods

Recommended

Method 1: Web Flasher

The easiest way to update. No software to install — works directly in your browser.

1 Open flasher.meshcore.co.uk in Chrome or Edge
2 Connect your device via USB (data cable, not charge-only)
3 Select your device type
4 Choose the same firmware variant you're currently running (Companion, Repeater, or Room Server)
5 Click "Flash" — takes 1-2 minutes

Settings preservation: Minor updates usually preserve your settings (node name, radio config, passwords). Major version jumps may require a full erase and reconfiguration. The flasher will indicate if a full erase is needed. Note your settings before updating, just in case.

Method 2: CLI Update

For users comfortable with the terminal. Useful for headless or remote devices where you can't use a browser.

pip install meshcore-cli
meshcore-cli flash --device <port> --firmware <variant>

The CLI downloads the latest firmware automatically. See the CLI Guide for full command reference.

Method 3: BLE OTA Update

Some devices support over-the-air updates via Bluetooth from the companion app. This is convenient for updating without a USB cable.

Limitations: OTA is slower than USB flashing and not supported on all device types. If the OTA update fails partway through, you may need to use the USB flasher to recover. Use USB when possible for the most reliable experience.

Firmware Variants Explained

MeshCore firmware comes in different variants for different device roles. Each variant is compiled specifically for the hardware it runs on.

Companion

For personal devices that pair with a phone. Includes Bluetooth support, message handling, and GPS reporting. This is what most users should flash.

Best for: Personal daily-use devices

Repeater

For infrastructure nodes that relay messages. Optimized for low power consumption and continuous operation. No personal messaging capability.

Best for: Fixed relay installations

Room Server

For store-and-forward message servers. Handles message storage, user authentication, and message delivery to offline clients.

Best for: Community message boards

Device-Specific Builds

Within each variant, there are device-specific builds compiled for different hardware:

ESP32-based devices

Heltec V3 / V4
LilyGo T-Beam
LilyGo T-Deck
Station G2

nRF52-based devices

RAK WisBlock (RAK4631)
LilyGo T-Echo
Seeed Wio Tracker

How to pick the right .bin file: The web flasher handles this automatically — just select your device from the dropdown. If downloading manually from GitHub, the filename includes both the variant and device type (e.g., companion-heltec-v3.bin).

Troubleshooting Failed Updates

Device not detected by the flasher

The #1 cause: you're using a charge-only USB cable. Try a different cable that you know carries data. Also try a different USB port. Some USB hubs don't provide enough power. On macOS, you may need to install a CH340/CP2102 serial driver for your device. On Windows, the driver usually installs automatically.

Flash appears to succeed but device won't boot

You may have flashed the wrong device-specific build (e.g., a T-Beam build on a Heltec V3). Re-flash with the correct build for your hardware. If the device is completely unresponsive, try holding the boot button while connecting USB, then flash again.

Wrong firmware variant flashed

No damage done — just re-flash with the correct variant. Flashing Companion when you wanted Repeater (or vice versa) is harmless. The device will work fine once you flash the right variant.

How to recover a bricked device

Most "bricked" devices aren't truly bricked. Hold the boot/reset button (varies by device) while connecting USB to force the device into bootloader mode. The web flasher should then detect it. For ESP32 devices, you can also try esptool.py erase_flash followed by a fresh firmware flash. For nRF52 devices, double-tap the reset button to enter DFU mode.

USB cable issues (data vs charge-only)

This is the most common problem and worth repeating: many USB cables only carry power, not data. The cable that came with your phone charger is often charge-only. Use a cable that came with a device that transfers data (camera, external drive), or buy a known data-capable USB cable. When in doubt, try 2-3 different cables.

Settings lost after update

If you updated across a major version, settings may have been reset. Reconfigure your node name, radio settings, and passwords using the companion app. This is why noting your settings before updating is good practice.

Firmware FAQ

How often should I update?

There's no fixed schedule. Check for updates every month or two, or when you see a release announcement on Discord or GitHub. Security fixes should be applied promptly. Feature updates can wait until convenient.

Can I downgrade to an older version?

Yes. Download the older firmware from GitHub releases and flash it using the same process. Note that downgrading across major versions may require a settings reset. Older firmware may not be compatible with newer companion apps.

Do all nodes on the network need the same firmware version?

Not necessarily. MeshCore is generally backward-compatible within the same major version. However, some features require matching versions on both ends. It's best practice to keep your network on similar versions, but a one-version-behind node won't break anything.

Can I switch between Meshtastic and MeshCore firmware?

Yes. The same hardware supports both protocols. Flash Meshtastic firmware using the Meshtastic flasher, or flash MeshCore firmware using the MeshCore flasher. You can switch back and forth as many times as you want — it doesn't damage anything.

Where can I see what changed in each release?

The MeshCore GitHub repository has release notes for each version. The NodakMesh Discord also discusses new releases and their impact on network operations.