---
# System prepended metadata

title: 'Part 1: Firmware Update & Running Code (Generic ESP32 Boards)'
tags: [ESP32, TA Stuff ESP32]

---

# Part 1: Firmware Update & Running Code (Generic ESP32 Boards)
###### tags: `TA Stuff ESP32` `ESP32` 

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 have watched this brief walkthrough, at least to the firmware update part: <span style="color:red">[**Session 2 Setup Atom Pymakr**](Link To YouTube Tutorial for Heltec basic installation if we have one.) and:</span> --> 
* 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)  

:::info
**Depending on your operating system follow one of the following sections:**
:::  

### [Windows](#Windows-OS)
### [Mac](#Mac-OS)
### [Linux](#Linux-OS-(Ubuntu-22.04))

## 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**](https://www.silabs.com/documents/public/software/CP210x_Windows_Drivers.zip) 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)
:::info
Your Windows **Device Manager** should look like these; before and after driver installation:  
#### **Before**  
![](https://i.imgur.com/MCi89FM.png) 
#### **After (Port number for CP210x may be different in your Windows)**
![](https://i.imgur.com/2S3gbNH.png) 
:::  
+ **Step 3:** Download [**this file**](https://micropython.org/resources/firmware/esp32-20220117-v1.18.bin) in your computer.
+ **Step 4:** Open [**this website**](https://nabucasa.github.io/esp-web-flasher/) and do:
:::info
The page must be opened in the latest version of **Google Chrome** or **Microsoft Edge**.
:::
+  - 0. **On most (Not All) of *ESP32 Generic* boards You need to keep the `Boot` button on your board down both during $Erase$ and $Programming$ (Flashing) otherwise it does not work.**  
+  - 1. Follow the numbered steps to connect to your development board (Choose CP210x and COM port number shoul be the same as your device manager):
![](https://i.imgur.com/V5pdmqC.png)
<br> 
:::danger  
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.
:::   
+  - 2. Press on **Erase** then **Ok** to delete files from your board:
![](https://i.imgur.com/3aBIyBc.png) 
<br><br>
![](https://i.imgur.com/QinuPaP.png) 
<br>   

+  - 3. 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)  
![](https://i.imgur.com/FU2zRNh.png)
![](https://i.imgur.com/nL33DiM.png)


:::success
**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)**](#After). Then open `Settings` on Pymakr and choose `Global settings`. 
![](https://i.imgur.com/xTCseEy.png) 
+ **Step 2:** Enter the device com port into the `Device address (list)` field and remove the check box selection from `Safe-boot before upload`.
![](https://i.imgur.com/kaIYdhO.png) 
:::info
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.
![](https://i.imgur.com/7vDoAgP.png) 
+ **Step 4:** Confirm the success by entering `print("Hello from Heltec")` and the board shows it in REPL.
![](https://i.imgur.com/iFzqwWf.png)     

:::warning
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.
![](https://i.imgur.com/TlHSmce.png)  
:::


:::success
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)**](https://docs.micropython.org/en/latest/esp32/quickref.html) and try different code to learn more. 
Good Luck!
:::

<br><br>

## 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`.
:::info
Your **USB Device Tree** should look like this; and you can find the **CP2102 USB to UART Bridge Controller** in the USB Device Tree.  

![](https://i.imgur.com/Y22CxqN.png)

![](https://i.imgur.com/Y8R0yf7.png)

:::  
+ **Step 3:** Download [**this file**](https://micropython.org/resources/firmware/esp32-20220117-v1.18.bin) to your Mac.
+ **Step 4:** Open [**this website**](https://nabucasa.github.io/esp-web-flasher/) and do:
+  - 0. **On most (Not All) of *ESP32 Generic* boards You need to keep the `Boot` button on your board down both during $Erase$ and $Programming$ (Flashing) otherwise it does not work.**  
  
+ - 1. Follow the numbered steps to connect to your development board:

![](https://i.imgur.com/XJMJpk1.png)

:::danger  
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.
:::   

+ - 2. Press on **Erase** then **Ok** to delete files from your board:

![](https://i.imgur.com/hsRkIHU.png)

![](https://i.imgur.com/deCzddi.png)

![](https://i.imgur.com/JlqQuRy.png)


+ - 3. 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)

![](https://i.imgur.com/m6LseEM.png)

![](https://i.imgur.com/cfi8PIm.png)

    
:::success
**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`.
![](https://i.imgur.com/iMEA3P2.png)

+ **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.

```shell=
    ls /dev/
```
![](https://i.imgur.com/bFdk5DZ.png)

![](https://i.imgur.com/OzdbLPG.png)


:::info
It would be good to restart Atom.
:::  
+ **Step 3:** Open Atom, click on `Connect device` in Pymakr and choose your device port.

![](https://i.imgur.com/fgjSNtN.png)

![](https://i.imgur.com/wo1Q4Eo.png)

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

![](https://i.imgur.com/2OQESad.png)

![](https://i.imgur.com/oUNR8PH.png)
     

:::warning
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.
![](https://i.imgur.com/t9aoZST.png)
  
:::

:::success
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)**](https://docs.micropython.org/en/latest/esp32/quickref.html) and try different code to learn more. 
Good Luck!
:::
<br><br>
## Linux OS (Ubuntu 22.04)
Follow these steps:

+ **Step 1:** Run the following commands to remove access conflict in your Ubuntu:
```shell=
sudo systemctl stop brltty-udev.service
sudo systemctl mask brltty-udev.service
sudo systemctl stop brltty.service
sudo systemctl disable brltty.service
```
+ **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_**).

```shell=
  sudo dmesg | grep ttyUSB0
```
![](https://i.imgur.com/eDtA0Gs.png)


+ **Step 4:** Download [**this file**](https://micropython.org/resources/firmware/esp32-20220117-v1.18.bin) 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
```shell=
  ls -l /dev/ttyUSB0
  sudo usermod -a -G dialout [Your username]
  sudo chmod a+rw /dev/ttyUSB0
  ls -l /dev/ttyUSB0
```
![](https://i.imgur.com/yTCyS7y.png)



+ **Step 6:** Open [**this website**](https://nabucasa.github.io/esp-web-flasher/) and do:
+  - 0. **On most (Not All) *ESP32 Generic* boards You need to keep the `Boot` button on your board down both during $Erase$ and $Programming$ (Flashing) otherwise it does not work.**  
 + - 1. Connect your device.
  
![](https://i.imgur.com/w4MIl80.png)

:::danger  
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.
:::   
 
 + - 2. Press on **Erase** then **Ok** to delete files from your board:

![](https://i.imgur.com/5mnu2ib.png)

![](https://i.imgur.com/LVTisTs.png)

![](https://i.imgur.com/VCSjiX7.png)


+ - 3. 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)  

![](https://i.imgur.com/e668Ra9.png)

![](https://i.imgur.com/rxYmPdM.png)


:::success
**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`.
![](https://i.imgur.com/xTCseEy.png) 
+ **Step 2:** Enter the device com port into the `Device address (list)` field.

![](https://i.imgur.com/4ol2E5P.png)
 
:::info
It would be good to disconnect your device and restart Atom. Remeber to enter commands in your Terminal again.

```shell=
  ls -l /dev/ttyUSB0
  sudo usermod -a -G dialout [Your username]
  sudo chmod a+rw /dev/ttyUSB0
  ls -l /dev/ttyUSB0
```

:::  
+ **Step 3:** Open Atom, click on `Connect device` in Pymakr and choose your Device Address (**/dev/ttyUSB0**).
![](https://i.imgur.com/ifY23PU.png)

+ **Step 4:** Confirm the success by entering `print("Hello from Heltec")` and the board shows it in REPL.
![](https://i.imgur.com/P2GQPVM.png)

:::warning
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.
![](https://i.imgur.com/Y3fnHib.png)
  
:::


:::info
Everytime you disconnect/connect your Heltec board in Ubuntu you must give access to it by following commands:
```shell=
sudo usermod -a -G dialout [Your username]
sudo chmod a+rw /dev/ttyUSB0
```
:::
:::success
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)**](https://docs.micropython.org/en/latest/esp32/quickref.html) and try different code to learn more. 
Good Luck!
:::

 

*[REPL]: Read-Evaluate-Print Loop


<style>

.markdown-body code{
    font-size: 1em !important;
}
.markdown-body .a{
    font-size: 5em !important;
}
.markdown-body pre {
    background-color: #333;
    border: 1px solid #333 !important;
    color: #dfdfdf;
    font-weight: 600;
}
.token.operator, .token.entity,
.token.url, .language-css .token.string,
.style .token.string {
    background: #000;
}
.markdown-body table {
    display: table;
    padding: 1em;
    width: 100%;
}
.markdown-body table th,
.markdown-body table td,
.markdown-body table tr {
    border: none !important;
}
.markdown-body table tr {
    background-color: transparent !important;
    border-bottom: 1px solid rgba(0, 0, 0, 0.2) !important;
}
</style>


