Part 1: Firmware Update & Running Code (Generic ESP32 Boards)
In this tutorial, we walk you through the hardware configuration, so you are up and running for your journey in IoT. If you own a Generic ESP32 Development Board you should follow this tutorial.
You will:
- Download and Install the board driver on your computer
- Download and update the board firmware
- Try a small code to confirm if everything is set properly
We'll continuously update this walkthrough. Is there anything missing or unclear, or have you experienced some issue? Please add a comment. You do this by highlighting the text and then you can write a comment on the highlighted part. You need to log in/create an account on HackMD first.
0. Prerequisites
- You should be finished with the IDE installation tutorial before continuing this :)
- Have your ESP32 development board
- USB Cable (Make sure the USB cable is capable of data transferring. If you get the bundle with cable it will support)
Depending on your operating system follow one of the following sections:
Windows OS
Follow these steps:
- Step 1: Connect your board to your computer with a USB cable.
- Step 2: Download the hardware driver from this link. You will get a zip file extract the file and depending on your Windows version either execute the file end with _x64 or with _x86. (Almost all new computers are x64)
Your Windows Device Manager should look like these; before and after driver installation:
Before
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
After (Port number for CP210x may be different in your Windows)
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
The page must be opened in the latest version of Google Chrome or Microsoft Edge.
-
-
- On most (Not All) of ESP32 Generic boards You need to keep the
Boot
button on your board down both during and (Flashing) otherwise it does not work.
-
-
- Follow the numbered steps to connect to your development board (Choose CP210x and COM port number shoul be the same as your device manager):
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
During the next two steps, you should not interrupt any execution, meaning you should keep your browser open and not remove the USB cable from your board or computer.
-
-
- Press on Erase then Ok to delete files from your board:
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
-
-
- Enter Offset
1000
, and in Choose a File select your download esp32-20220117-v1.18.bin
, then press program to write firmware to your board. (It takes a while and during this time don’t disconnect your board from the USB cable)
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
You are now ready for the next step to run code on your development IDE. Follow the steps below:
- Step 1: Open your Atom IDE and at the bottom, you see the Pymakr plugin. You need to find the COM port number of your device, which is visible in Device Manager (here). Then open
Settings
on Pymakr and choose Global settings
.
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
- Step 2: Enter the device com port into the
Device address (list)
field and remove the check box selection from Safe-boot before upload
.
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
It would be good to disconnect your device and restart your Windows before starting REPL in Atom.
- Step 3: Open Atom, click on
Connect device
in Pymakr and choose your COM port.
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
- Step 4: Confirm the success by entering
print("Hello from Heltec")
and the board shows it in REPL.
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
If you press the “RST” button your board goes into the following state, and it is because this firmware is a PyCom MicroPython and the reset button is not defined.
You should: 1. Close REPL tab on Atom. 2. Disconnect the board from USB and connect it again 3. Open REPL again like “Step 7” above.
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
You are now successfully finished Part 1 of four parts tutorial, It is a good idea to read more about MicroPython Tutorials and Examples from MicroPython Site (here) and try different code to learn more.
Good Luck!
Mac OS
Follow these steps:
- Step 1: Connect your development board to your Mac with a USB cable.
- Step 2: The driver has already integrated into the macOS. Check if your Mac have detected your development Board by clicking
Apple icons >> About This Mac >> Overview >> System Report... >> Hardware >> USB
.
Your USB Device Tree should look like this; and you can find the CP2102 USB to UART Bridge Controller in the USB Device Tree.
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
During the next two steps, you should not interrupt any execution, meaning you should keep your browser open and not remove the USB cable from your board or computer.
-
-
- Press on Erase then Ok to delete files from your board:
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
-
-
- Enter Offset
1000
, and in Choose a File select your download esp32-20220117-v1.18.bin
, then press program to write firmware to your board. (It takes a while and during this time don’t disconnect your board from the USB cable)
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
You are now ready for the next step to run code on your development IDE. Follow the steps below:
-
Step 1: Open your Atom IDE and at the bottom, you see the Pymakr plugin. Then open Settings
on Pymakr and choose Global settings
. Remove the check box selection from Auto connect
and Safe-boot before upload
.
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
-
Step 2: Enter the device port into the Device address (list)
field. The device addree can be found using the following command in the Terminal.
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
It would be good to restart Atom.
- Step 3: Open Atom, click on
Connect device
in Pymakr and choose your device port.
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
- Step 4: Confirm the success by entering
print("Hello from Heltec")
and the board shows it in REPL.


If you press the “RST” button your board goes into the following state, and it is because this firmware is a PyCom MicroPython and the reset button is not defined.
You should: 1. Close REPL tab on Atom. 2. Disconnect the board from USB and connect it again 3. Open REPL again like “Step 7” above.

You are now successfully finished Part 1 of four parts tutorial, It is a good idea to read more about MicroPython Tutorials and Examples from MicroPython Site (here) and try different code to learn more.
Good Luck!
Linux OS (Ubuntu 22.04)
Follow these steps:
- Step 1: Run the following commands to remove access conflict in your Ubuntu:
- Step 2: Connect your development board to your computer with a USB cable.
- Step 3: The driver has already integrated into the Linux kernel. Open the Terminal, and type following command to check the connecting information (usb 1-1.1: cp210x converter now attached to ttyUSB0).

- Step 4: Download this file to your computer.
- Step 5: Modify the port permission using the following 3 commands one by one in the Terminal, and the port permission will change from crw-rw–– to crw-rw-rw-. (You may need enter your password when you use sudo command, and you need to repeat these commands when you reconnect your Heltec board or connect from ESP Web Flasher to IDE). Remember your device addree (/dev/ttyUSB0).1

- Step 6: Open this website and do:
-
-
- On most (Not All) ESP32 Generic boards You need to keep the
Boot
button on your board down both during and (Flashing) otherwise it does not work.
-

During the next two steps, you should not interrupt any execution, meaning you should keep your browser open and not remove the USB cable from your board or computer.
-
-
- Press on Erase then Ok to delete files from your board:



-
-
- Enter Offset
1000
, and in Choose a File select your download esp32-20220117-v1.18.bin
, then press program to write firmware to your board. (It takes a while and during this time don’t disconnect your board from the USB cable)


You are now ready for the next step to run code on your development IDE. Follow the steps below:
- Step 1: Open your Atom IDE and at the bottom, you see the Pymakr plugin. Then open
Settings
on Pymakr and choose Global settings
. Remove the check box selection from Safe-boot before upload
.
Image Not Showing
Possible Reasons
- The image file may be corrupted
- The server hosting the image is unavailable
- The image path is incorrect
- The image format is not supported
Learn More →
- Step 2: Enter the device com port into the
Device address (list)
field.

It would be good to disconnect your device and restart Atom. Remeber to enter commands in your Terminal again.
-
Step 3: Open Atom, click on Connect device
in Pymakr and choose your Device Address (/dev/ttyUSB0).

-
Step 4: Confirm the success by entering print("Hello from Heltec")
and the board shows it in REPL.

If you press the “RST” button your board goes into the following state, and it is because this firmware is a PyCom MicroPython and the reset button is not defined.
You should: 1. Close REPL tab on Atom. 2. Disconnect the board from USB and connect it again 3. Open REPL again like “Step 7” above.

Everytime you disconnect/connect your Heltec board in Ubuntu you must give access to it by following commands:
You are now successfully finished Part 1 of four parts tutorial, It is a good idea to read more about MicroPython Tutorials and Examples from MicroPython Site (here) and try different code to learn more.
Good Luck!