Flashing ESP32 Devices
Using the Meshtastic Web Flasher
Flash Device
-
Plug in your device
-
Visit flasher.meshtastic.org *requires Chrome or Edge browser
-
Follow the instructions

Connect and Set Up Device
Flashing Firmware via CLI
Connectivity Verification
-
Use firmware-tbeam0.7-X.X.X.xxxxxxx.bin for the T-Beam 0.7.
-
firmware-tbeam-X.X.X.xxxxxxx.bin is incompatible.
Command Line Interface Instructions
Install Prerequisite Software
Linux
python3 --version pip3 --version
|
sudo apt-get update sudo apt-get install python3
|
sudo apt-get install python3-pip
|
pip3 install --upgrade esptool
|
MacOS
brew -v
|
python3 --version pip3 --version
|
brew install python3
|
pip3 -v
|
pip3 install --upgrade esptool
|
Windows
-
Download and install Python. During the installation process, ensure you select the option to Add Python X.Y to PATH.
-
Download and install Git Bash (or another suitable shell), and execute all subsequent commands from that shell.
py --version pip --version
|
pip3 install --upgrade esptool
|
Check Connectivity with the Chip
-
On Linux and macOS, you may need to explicitly declare esptool as a .py script. Use the command esptool.py chip_id to do this, depending on your environment.
-
On Windows, you must explicitly declare esptool as a .py script by using the command esptool.py chip_id to ensure proper functionality.
Command
esptool chip_id
|
Expected Output
# You should see a result similar to this: mydir$ esptool chip_id esptool.py v2.6 Found 2 serial ports Serial port /dev/ttyUSB0 Connecting.... Detecting chip type... ESP32 Chip is ESP32D0WDQ6 (revision 1) Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None MAC: 24:6f:28:b5:36:71 Uploading stub... Running stub... Stub running... Warning: ESP32 has no Chip ID. Reading MAC instead. MAC: 24:6f:28:b5:36:71 Hard resetting via RTS pin...
|
Download Firmware
-
Navigate to the Meshtastic Downloads Page to obtain the latest firmware.
-
Scroll down to the Firmware section and choose one of the following options based on your preferences:
-
Download Stable: For stable, well-tested releases.
-
Download Alpha: For newer, experimental releases that include the latest features.
-
Once you are redirected to the GitHub release page, scroll down to the Assets section and expand it.
-
Identify the appropriate firmware for your device according to its architecture (e.g., firmware-esp32s3 for ESP32-S3-based devices like the Heltec V3).
-
Download the file and make a note of its location on your system, which is typically in your ~/Downloads folder.
Access the Firmware Directory
cd ~/Downloads/firmware-esp32s3-X.X.X.xxxxxxx/
|
Install or Update Firmware
Please note before you begin:
Linux & macOS
./device-install.sh -f firmware-BOARD-VERSION.bin
|
./device-update.sh -f firmware-BOARD-VERSION-update.bin
|
Windows
device-install.bat -f firmware-BOARD-VERSION.bin
|
device-update.bat -f firmware-BOARD-VERSION-update.bin
|
Connect and Set Up Device
Flashing with an External Serial Adapter
Flashing Process
-
Due to the ongoing chip shortage, recently acquired devices like the TTGO T-Beam may be equipped with legacy or non-standard USB to Serial adapter chips, which can be unreliable in certain situations.
-
Some devices may feature defective USB to Serial chips, leading to communication issues.
-
Specific devices, such as the Hydra (Meshtastic-DIY target)
USB Serial Adapters

Connecting Adapter to the Device
-
Connect the RX pin of the adapter to the TX pin of the device.
-
Connect the TX pin of the adapter to the RX pin of the device.
-
Connect a GND pin of the adapter to the GND pin of the device.
-
Connect either the 5V pin of the adapter to the 5V pin of the device (as illustrated) or the 3.3V pin of the adapter to the 3.3V pin of the device.
-
Bridge GPIO 0 to GND on the device with a jumper. (This will put the device into flash mode when powered up.) Example wiring featuring a T-Beam.

-
Connect the device to a USB port on the computer.
-
Remove the jumper bridging GPIO 0 to GND.

Flashing the Device

Troubleshooting the Flashing Process
Connect and Set Up Device
Flashing nRF52 & RP2040 Devices
-
Firmware Upgrade Process for nRF52 and RP2040 Devices: Devices based on nRF52 and RP2040 architectures offer a straightforward firmware upgrade process that does not require any driver or software installation on any platform.
-
Drag & Drop: These devices utilize the Drag & Drop installation method for installing firmware releases. Simply drag the firmware file onto the device in your file explorer.
-
Over-The-Air (OTA) Updates: nRF52 devices can receive OTA firmware updates from a mobile device via Bluetooth, allowing for seamless updates without the need for physical connections.
-
Factory Erase: Before installing new firmware, you may consider performing a Factory Erase to clear any existing data that may change format or location between releases.
-
Converting RAK4631-R to RAK4631: If your device does not come with the Arduino bootloader, you will need to perform a conversion to ensure compatibility.
-
Using Raspberry Pi as a SWDIO Flash Tool: If your device cannot be flashed via USB or Bluetooth, an alternative option is to use a direct SWDIO connection with a Raspberry Pi as a flashing tool.
Drag-and-Drop Firmware Updates for nRF52 & RP2040
Flash Device
-
You can now utilize the Meshtastic Web Flasher to download and transfer firmware to your nRF52 or RP2040-based devices. Alternatively, you can follow the instructions below to download and install the firmware.
-
If you have recently completed a Factory Erase, your device might automatically start up in bootloader mode. You can then proceed directly to "Copy the appropriate firmware..." for your specific device below:
nRF52
-
Download and unzip the latest firmware from the Meshtastic Downloads.
-
Connect your device to your computer using a USB data cable.
-
Press the reset button on your device twice (this will enter bootloader mode).
-
A new drive will be mounted on your computer (compatible with Windows, Mac, Linux, or Android).
-
Open this drive, where you should find three files: CURRENT.UF2, INDEX.HTM, and INFO_UF2.TXT.
-
Copy the appropriate firmware file (firmware-DEVICE_NAME-X.X.X-xxxxxxx.uf2) from the release folder to this drive.
-
After the file finishes copying, the device will reboot and install the Meshtastic firmware.
RP2040
-
Download and unzip the latest firmware from the Meshtastic Downloads.
-
Press and hold the BOOTSEL button, then connect the device to your computer using a USB cable.
-
A new drive will be mounted on your computer (compatible with Windows, Mac, Linux, or Android).
-
Open this drive, where you should find two files: INDEX.HTM and INFO_UF2.TXT.
-
Copy the appropriate firmware file (firmware-DEVICE_NAME-X.X.X-xxxxxxx.uf2) from the release folder to this drive.
-
After the file has finished copying, the device will reboot and install the Meshtastic firmware.
Possible Flashing Edge Cases
-
Older versions of the Meshtastic firmware may retain outdated data, which can lead to devices getting trapped in a crash loop during startup. If you encounter problems while upgrading your nRF52 device from a previous version of Meshtastic, you may need to perform a complete factory reset of the internal flash memory.Please follow the guide to factory erase your nRF52 device before proceeding to flash the firmware.
Connect and Set Up Device
Over-the-Air (OTA) Firmware Updates for nRF52
Android
-
Download the firmware release you wish to install from the Meshtastic Download Page or Meshtastic GitHub.
-
Unzip the firmware folder.
-
Open the nRF Connect App and select CONNECT on your device from the SCANNER tab.
-
If the interface displays DISCONNECT in the top right corner, proceed to step 5. If it says CONNECT, select CONNECT.
-
Tap the DFU icon in the top right corner of the screen.
-
Verify that "Distribution Packet (ZIP)" is selected, then select OK.
-
Choose the appropriate device firmware file (which will end with -ota.zip).
-
The update will start automatically (note that this process may be slow).
-
Once the update is complete, the device will reboot automatically.
Apple
-
Download the firmware release you wish to install from the Meshtastic Download Page, Meshtastic GitHub, or directly through the iOS/iPadOS app.
-
Unzip the firmware folder.
-
Open the nRF DFU App and select the correct device firmware file (ending with -ota.zip).
-
Connect to your device.
-
Upload the firmware.
-
Go to settings and enable "Packets Receipt Notification."
-
Change "Number of Packets" to a lower value; some users have found success with a setting of "5."
Factory Reset for nRF52/RP2040 Devices
-
Meshtastic utilizes the littlefs library to store configuration, logs, and other data in the internal flash memory of nRF52 and RP2040 devices. It's important to note that updating the firmware does not erase this additional data, which can lead to issues if the format and location of the data change between releases.
-
You can now use the Meshtastic Web Flasher to factory erase your nRF52 or RP2040-based devices. Visit the flasher, select your board, and click the trash can icon to the right of the Flash button. This will open a dialog to initiate the erase procedure.Alternatively, you can follow the instructions below.
nRF52
-
Download and unzip the latest firmware from the Meshtastic Downloads page.
-
Connect your device to your computer using a USB data cable.
-
Double-click the reset button on your device to enter bootloader mode.
-
A new drive will be mounted on your computer (this applies to Windows, Mac, or Linux).
-
Open this drive, and you should see three files: CURRENT.UF2, INDEX.HTM, and INFO_UF2.TXT.
-
Open the INFO_UF2.TXT file in a text editor and note the SoftDevice value.
-
Locate the file included in the downloaded firmware that matches your SoftDevice major version number (either 7.x.x or 6.x.x). Use either Meshtastic_nRF52_factory_erase_v3_S140_7.3.0.uf2 or Meshtastic_nRF52_factory_erase_v3_S140_6.1.0.uf2, and copy it onto the new drive. The device should then reboot.
-
With the Meshtastic CLI installed, open your Terminal or Console and enter the command: meshtastic --noproto.
-
You should see the message: Formatting... Done.
RP2040
-
Download the flash_nuke.uf2 file to your computer.
-
Press and hold the BOOTSEL button, then connect the board to your computer using a USB cable.
-
The board should now appear as a mass storage device on your computer, labeled as RPI-RP2.
-
Copy the flash_nuke.uf2 file to this device.
-
The board will automatically restart, and the flash memory will be erased.
Converting RAK4631-R to RAK4631
USB Device Firmware Update (DFU)
-
Install Python
-
Install adafruit-nrfutil
pip3 install adafruit-nrfutil
|
-
Download the necessary bootloader: WisCore_RAK4631_Board_Bootloader.zip.
-
Connect your RAK device to your computer via USB.
-
Flash the bootloader.
adafruit-nrfutil --verbose dfu serial --package ./WisCore_RAK4631_Board_Bootloader.zip -p /dev/ttyACM0 -b 115200 --singlebank --touch 1200
|
-
After that, continue with the regular flashing instructions.
Additional RUI3 Steps
Touched serial port COM11 Opened serial port COM11 Starting DFU upgrade of type 2, SoftDevice size: 0, bootloader size: 39000, application size: 0 Sending DFU start packet Timed out waiting for acknowledgement from device. Failed to upgrade target. Error is: No data received on serial port. Not able to proceed.
|
Debugger
pip3 install pyocd
|
-
Download the necessary bootloader: WisCore_RAK4631_Board_Bootloader.hex.
-
Connect the RAKDAP as instructed below:

-
Flash the bootloader
pyocd flash -t nrf52840 .\WisCore_RAK4631_Board_Bootloader.hex |
-
Proceed with the standard flashing instructions.
Updating or Recovering the Bootloader on nRF52 Devices
Method 1: Updating with the UF2 File (Recommended)
-
Download the correct UF2 Bootloader file.
-
Connect your device to your computer using a USB cable.
-
Activate bootloader mode by quickly double-pressing the RESET button on your device. For the Seeed Tracker 1000-E, press and hold the user button, then quickly connect the USB cable to the MagSafe port twice. The device should show up as a removable drive on your computer.
-
Drag and drop the UF2 file you downloaded into the removable drive. The device will automatically update the bootloader and reset.
-
Once the device resets, the update is complete. Your device is now operating on the latest bootloader version, and you can proceed with flashing the firmware.
Method 2: Using adafruit-nrfutil
-
Lilygo T-Echo SHA256: 85d8a334bbf82802d712e183f29ec5215f06786ca88914687c437aceab75d9cf
-
RAK4631 SHA256: 4a216ad2be8be23b80371a11753677c850c5711d3b85129390a416fc47ea0910
-
Seeed Tracker 1000-E SHA256: 8c69f0d43a7aac925055451d7262682d6926d4cfb7ea8240b466dc8f16a692ba
-
Generic Meshtastic 6.1.1 for DIY SHA256: ecebecea849ab79d09517dd4f6ff98de5647fe275b0b4d525501e6c29cb5a586
-
Generic Meshtastic 7.3.0 for DIY SHA256: 9a38edf4e974a6f705c41b296499a4fc57682ec9bb686eecd9f3d8d02fc6ffcf
-
Open a terminal or command prompt and install adafruit-nrfutil by running the following command:
pip install adafruit-nrfutil |
-
Obtain the correct ZIP package.
-
Connect your device to your computer using a USB cable.
-
In the terminal or command prompt, navigate to the directory where you downloaded the bootloader ZIP package, and execute the following command. Make sure to replace /dev/ttyACM0 with the correct port for your device (Windows users may use COMx):
adafruit-nrfutil --singlebank --touch 1200 --verbose dfu serial --package <downloaded file>.zip -p /dev/ttyACM0 -b 115200
|
-
Once the process is complete, the update is finished. Your device is now operating with the latest bootloader version, allowing you to proceed with flashing the firmware.
Method 3: Using a Debugger
Using SWDIO for Flashing with a Raspberry Pi
Wiring Setup
Install OpenOCD Software
$ sudo apt update $ sudo apt install libtool autoconf automake texinfo telnet gdb-multiarch git $ git clone git://repo.or.cz/openocd.git $ cd openocd/ $ ./bootstrap $ ./configure --enable-bcm2835gpio $ make -j4 $ sudo make install
|
Verify Connection
$ openocd -f ./openocd/tcl/interface/raspberrypi-native.cfg -c "transport select swd" -f openocd/tcl/target/nrf52.cfg -s tcl
|
Open On-Chip Debugger 0.12.0+dev-00633-gad87fbd1c Licensed under GNU GPL v2 For bug reports, read http://openocd.org/doc/doxygen/bugs.html srst_only separate srst_gates_jtag srst_push_pull connect_deassert_srst swd Info : Listening on port 6666 for tcl connections Info : Listening on port 4444 for telnet connections Info : BCM2835 GPIO JTAG/SWD bitbang driver Info : clock speed 100 kHz Info : SWD DPIDR 0x2ba01477 Info : [nrf52.cpu] Cortex-M4 r0p1 processor detected Info : [nrf52.cpu] target has 6 breakpoints, 4 watchpoints Info : [nrf52.cpu] Examination succeed Info : [nrf52.cpu] starting gdb server on 3333 Info : Listening on port 3333 for gdb connections Info : accepting 'telnet' connection on tcp/4444
|
Download Firmware
Flash Firmware
$ telnet 127.0.0.1 4444 Trying 127.0.0.1... Connected to 127.0.0.1. Escape character is '^]'. Open On-Chip Debugger > init > reset init > halt > nrf5 mass_erase > program firmware.hex verify > reset > exit 0
|
Establish Connection