# Part 1: Firmware Update & Running Code (Heltec Boards)
###### tags: `TA Stuff ESP32` `Heltec` `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 **Heltec 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 Heltec 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 Heltec 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**
#### **After (Port number for CP210x may be different in your Windows)**
:::
+ **Step 3:** Download [**this file**](https://github.com/H-Ryan/Heltec/blob/main/PyCom%20MicroPython/Heltec%20PyCom%20MicroPython.zip?raw=true) and extract them on 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**.
:::
+ - 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):
<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:
<br><br>
<br>
+ - 3. Enter **Offset** `00`, and in **Choose a File** select your download `heltec.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)
:::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`.
+ **Step 2:** Enter the device com port into the `Device address (list)` field and remove the check box selection from `Safe-boot before upload`.
:::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.
+ **Step 4:** Confirm the success by entering `print("Hello from Heltec")` and the board shows it in REPL.
:::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.
:::
+ **Step 5:** We are ready to make our first project now. Create a folder on your computer like; ( `First Project` ).
+ **Step 6:** In Atom click on `Add Folder` from the left panel then open created folder.
+ **Step 7:** Right-click on your project folder from the left panel and choose `New File` to create a new file, in the opened box enter `main.py` and press enter.
:::info
All projects must have `main.py` which is the start point for code execution.
:::
+ **Step 8:** Copy the following lines in `main.py` and save it.
```python=
from machine import Pin # Used for LED pin addressing
import time # Used for the delay between blinking
led = Pin('P22', mode=Pin.OUT) # Used LED pin as output
# Loop for blinking
while True:
led.value(1)
time.sleep(1)
led.value(0)
time.sleep(1)
```
+ **Step 8:** Now upload the file to your board from the upload project button:
<br>
+ **Step 9:** The LED on your board starts to blink and the REPL is not accessible anymore because of your loop. To stop blinking press Ctrl+c in the REPL section.
:::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 [**Pycom (here)**](https://docs.pycom.io/tutorials/) and try different code to learn more.
Good Luck!
:::
<br><br>
## Mac OS
Follow these steps:
+ **Step 1:** Connect your Heltec 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 Heltec 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.
:::
+ **Step 3:** Download [**this file**](https://github.com/H-Ryan/Heltec/blob/main/PyCom%20MicroPython/Heltec%20PyCom%20MicroPython.zip?raw=true) and extract them on your Mac.
+ **Step 4:** Open [**this website**](https://nabucasa.github.io/esp-web-flasher/) and do:
+ - 1. Follow the numbered steps to connect to your development board:
+ - 2. Press on **Erase** then **Ok** to delete files from your board:
+ - 3. Choose **Offset**, **Downloaded Files**, and 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)
:::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`.
+ **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/
```
:::info
It would be good to restart Atom.
:::
+ **Step 3:** Open Atom, click on `Connect device` in Pymakr and choose your device port.
+ **Step 4:** Confirm the success by entering `print("Hello from Heltec")` and the board shows it in REPL.
:::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.
:::
+ **Step 5:** We are ready to make our first project now. Create a folder on your computer like; ( `First Project` ).
+ **Step 6:** In Atom click on `Add Folder` from the left panel then open created folder.
+ **Step 7:** Right-click on your project folder from the left panel and choose `New File` to create a new file, in the opened box enter `main.py` and press enter.
:::info
All projects must have `main.py` which is the start point for code execution.
:::
+ **Step 8:** Copy the following lines in `main.py` and save it.
```python=
from machine import Pin # Used for LED pin addressing
import time # Used for the delay between blinking
led = Pin('P22', mode=Pin.OUT) # Used LED pin as output
# Loop for blinking
while True:
led.value(1)
time.sleep(1)
led.value(0)
time.sleep(1)
```
+ **Step 9:** Now upload the file to your board from the upload project button:
+ **Step 10:** The LED on your board starts to blink and the REPL is not accessible anymore because of your loop. To stop blinking press Ctrl+c in the REPL section.
:::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 [**Pycom (here)**](https://docs.pycom.io/tutorials/) 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 Heltec 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
```
+ **Step 4:** Download [**this file**](https://github.com/H-Ryan/Heltec/blob/main/PyCom%20MicroPython/Heltec%20PyCom%20MicroPython.zip?raw=true) and extract them on 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
```
+ **Step 6:** Open [**this website**](https://nabucasa.github.io/esp-web-flasher/) and do:
+ - 1. Connect your device.
+ - 2. Press on **Erase** then **Ok** to delete files from your board:
+ - 3. Choose **Offset**, upload **Downloaded Files**, and 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)
:::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`.
+ **Step 2:** Enter the device com port into the `Device address (list)` field.
:::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**).
+ **Step 4:** Confirm the success by entering `print("Hello from Heltec")` and the board shows it in REPL.
:::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.
:::
+ **Step 5:** We are ready to make our first project now. Create a folder on your computer like; ( `First Project` ).
+ **Step 6:** In Atom click on `Add Folder` from the left panel then open created folder.
+ **Step 7:** Right-click on your project folder from the left panel and choose `New File` to create a new file, in the opened box enter `main.py` and press enter.
:::info
All projects must have `main.py` which is the start point for code execution.
:::
+ **Step 8:** Copy the following lines in `main.py` and save it.
```python=
from machine import Pin # Used for LED pin addressing
import time # Used for the delay between blinking
led = Pin('P22', mode=Pin.OUT) # Used LED pin as output
# Loop for blinking
while True:
led.value(1)
time.sleep(1)
led.value(0)
time.sleep(1)
```
+ **Step 9:** Now upload the file to your board from the upload project button:
+ **Step 10:** The LED on your board starts to blink and the REPL is not accessible anymore because of your loop. To stop blinking press Ctrl+c in the REPL section.
:::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 [**Pycom (here)**](https://docs.pycom.io/tutorials/) 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>
Sign in with Wallet
Connect another wallet