Flashing

MeshCore Guides

The web flasher

The supported path is the official web flasher. It needs a browser with WebSerial support, which means Chrome, Chromium, or Edge. Firefox does not implement WebSerial. Pick your board, pick the role firmware, pick the frequency band variant that matches your region and your board's radio, and flash over USB.

Pick the role now

MeshCore assigns a node's role at flash time. The main choices:

• Companion (BLE): your personal node, pairs with the phone app. First board: this one.
• Companion (USB serial): same role, wired to a computer instead of a phone. What meshcore-cli talks to.
• Repeater: a dedicated forwarder. No phone pairing; administered remotely over the mesh.
• Room server: a store-and-forward message board node.

Changing role means reflashing. Node identity is tied to the keys on the device, so plan names and placement around roles rather than reflashing casually.

ESP32 boards

ESP32 boards (Heltec V3/V4, LilyGo T-Beam and friends) flash over the USB serial port. Most enter the bootloader automatically when the flasher resets them. If the flasher cannot connect, put the board in bootloader mode manually: hold the BOOT button while plugging in USB (or while tapping reset), then retry.

nRF52 boards

nRF52840 boards (T114, RAK4631, T-Echo, Seeed trackers) use a UF2 bootloader. Double-tap the reset button and the board mounts as a USB mass-storage drive; copy the downloaded .uf2 firmware file onto it and the board reboots into MeshCore. No drivers, no flasher tool, works from any OS. The web flasher will hand you the UF2 file for these targets.

Linux gotchas

• Permissions: your user needs to be in the group that owns the serial device, typically dialout (uucp on Arch): sudo usermod -aG dialout $USER, then log out and back in.
• brltty steals the port: on Debian and Ubuntu the brltty screen-reader service claims some USB serial adapters the moment they enumerate, and the device vanishes. If dmesg shows the port appear and then disconnect, remove or disable brltty.
• Find the device: dmesg | tail right after plugging in. Boards show up as /dev/ttyACM0 or /dev/ttyUSB0.
• Close other users of the port: a running serial monitor (or a forgotten meshcore-cli session) blocks the flasher.

Building from source

The firmware is open source and builds with PlatformIO from the GitHub repository, one environment per board target. You only need this for development or customization; the web flasher covers normal use.

Verify

After flashing, the node boots and starts adverting. For a companion, connect with the app (or meshcore-cli) and confirm you can read the node's settings. Then set name and region before doing anything else, per Getting Started.