# Flashing MicroPython Onto ESP32-S2
## 1. Introduction
MicroPython is a subsidiary language of the Python programming language, inheriting most of Python 3 properties and syntax. It is known as simple and easy to learn compared to other mainstream programming languages. Making it a popular choice amongst beginner programmers, and brings a breath of fresh air into the world of IoT development.

The MicroPython development team is actively maintaining the source code on GitHub. Dedicated to bringing support to ICs, and bug fixes. So compiling on the latest MicroPython firmware is necessary.

This is a summary on building MicroPython developing environment. Including the process compiling ESP32-S2 firmware, and flashing onto the board.

## 2. Linux
Building the MicroPython environment requires a Linux-based system.

For Windows users it is recommended to install a VMware running Ubuntu, as it is the most convenient route.

There are tons of Linux varients available, however, in terms of simplicity, Ubuntu offers a mature platform to operate on. Search "VMware Ubuntu" on a search engine to learn more.

It is recommended to download related software and system image file/iso on the official websites respectively to ensure the reliablility.

## 3. Building the ESP-IDF(Iot Development Framework) Environment

ESP32 Series chips' development mostly relies on the SDK(Software Development Kit) provided by Espressif. MicroPython also requires this SDK in order to work.

You can also refer to the esp-idf guide for the details of building the environment.

Here's a simple summary:

First, create a folder under the home directory

Open the Terminal and enter the command:
`mkdir -p ~/esp`

Access the folder you just created:
`cd ~/esp`

Enter the following code to clone esp-idf version 4.4 from GitHub, this is a stable version for building the MicroPython environment on the S2 chip:

`git clone -b release/v4.4 --recursive git://github.com/espressif/esp-idf.git
`

Navigate to the esp-idf folder:
`cd ~/esp/esp-idf`

Enter the following command line to install required tools for ESP-IDF, such as, compiler, debugger, and Python packages. You can also download a specific configuration for a specific chip. For example, `./install.fish esp32s2.` But it is recommended to use the install all command to save a lot of trouble:
`./install.sh all`

If you are experiencing network errors, you could try downloading from the Espressif server directly:

`cd ~/esp/esp-idfexport IDF_GITHUB_ASSETS="dl.espressif.com/github_assets"./install.sh all
`

After cloning the repository and installing the required tools, execute the following line to initiate ESP-IDF before compiling MicroPython:
`. $HOME/esp/esp-idf/export.sh
`

After exporting, here are some command lines you can use: `idf.py --help` for further information, `idf.py --version` to check current version, `idf.py --list-targets` to check current supported chip model.

## 4. Create an esp-idf Command Shortcut on Ubuntu

Using command lines to open and edit files are a nightmare for ones that are unfamiliar with Linux. Luckily, we can make use of Ubuntu's GUI to edit Linux files, just as one would using Windows. Here's how to create esp-idf command shortcut:

Open the home folder(it's same as your user name) on the Ubuntu desktop
, click the pulldown menu on the top right corner, and check the box "show hidden files":

Double click the .bashrc file to edit it.

On the last line, enter the following command then save the file.

# get run esp-idf
alias get_idf='. /home/user/esp/esp-idf/export.sh'


Open a terminal tab, enter the following command for the change to take effect:
`source ~/.bashrc`

Any time in the future, just type this command line to launch ESP-IDF:
`get_idf`

This shortcut can save a lot of time in future developments, you can also use alternative command lines as long as they don't conflict.

## 5. MicroPython Environment Building

Clone the MicroPython depository onto the local computer. I'm going to create a subfolder "mpy" in the "esp" folder as its location.
`mkdir ~/esp/mpy`

Navigate to the folder you wish to store MicroPython with:
`cd ~/esp/mpy
`

Enter the following command to clone repository:
`git clone git://github.com/micropython/micropython
`

Navigate to the MicroPython folder:
`cd micropython/
`

Next step is to compile mpy-coress in order to build MicroPython cross compiler, this process only needs to be done once:
`make -C mpy-cross
`

Then navigate to the ESP32 folder:
`cd ports/esp32
`

Enter the following command to initialize the submodules, this is a one-time process:
`make submodules
`

## 6. Compile Firmware

After making sure the ESP-IDF is running, we can enter the following command under ports/esp32 directory to compile a default ESP32 MicroPython firmware:
`make
`

If the process is sucessful, then the directory should appear a "build-GENERIC" folder. Inside the folder contains "firmware.bin" file, this is the MicroPython firmware file that can be used with ESP32 chip.

If unsuccessful, try the following: check and make sure ESP-IDF is initiated, ESP-IDF is on the latest version, required tools for ESP-IDF are installed. In most situations, it is ESP-IDF not initiated or its related tools that's causing the problem.

Setting up ESP-IDF is recommended for this reason, as it offers the most stable environment, and most likely wouldn't cause many problems during installation.

Once everything is ready, it is time to start compiling the ESP32-S2 firmware.

Under ports/esp32 directory contains "Makefile" file, the previous `make` command is to execute the program inside this file. Open the file to edit its contents:


In the 6th line, one can set the chip model to compile on, change ESP32_S2_WROVER to ESP32S2. Save the file then use the `make` command to start compiling.



Here we can learn more details about "Makefile" file so it's easier to edit and tweak in the future.

In the 6th line, `BOARD ?=` stands for the folder name under ports/esp32/boards. Upon opening we can see there are various officialy supported boards listed inside. Fill out the respective board folder name behind `BOARD ?=` then we can use `make` command to compile the firmware according to the board.


Line 12, `PORT ?=` is for setting up the port for flashing the firmware.

Line 13, `BAUD ?=` is for setting baud rate, this impacts the flashing speed and the stability during the flashing process.

I recommend adding the following code under line 33, this command automatically helps us open the project configuration utility every time while we use the `make` command. We can easily configure the chip functions. If configuration is not needed, then simply press esc key to skip this process, it will automatically finish the rest of the compiling process.

`idf.py $(IDFPY_FLAGS) menuconfig`

The code behind line 44 is pretty straight forward, such as, using `make clean` command is equivalent to `idf.py fullclean`. This erases the project files within the folder completely.

## 7. Flashing Firmware

The ESP32-S2 chip supports both USB serial flashing and uart serial flashing.

For Windows users, one can use the official Espressif flash download tool, to directly flash firmware onto the ESP32-S2 chip via USB.

Whether what methods you are using to flash the firmware, make sure the chip is in "bootloader mode", the process to enter that mode is as follows:

Hold the BOOT button, press RESET button once, then release BOOT button.

If you encounter problems or using device other than described, you would need to refer to ESP-IDF compile guide or the chip datasheet to resolve the issue.

Here are 2 methods to flashing firmware:

### 7.1. Flashing with `make` command in Ubuntu Terminal

Check if the device is detected before flashing, usually need to set up USB configuration if using VMware.

Type in the following command while the device awaiting flashing firmware is unplugged:
`ls /dev/tty*
`

Plug in the device, re-enter the previous command. Usually, a new USB device will appear. In my case it's ttyACM0, update this information in "Makefile" then save it.

Next step, make sure ESP-IDF is initiated in the terminal, firmware compile process is complete, and ESP32-S2 chip is in "bootloader mode".

Use the erase command to erase the flash to ensure a clean install, followed by the deploy command to flash firmware onto the chip:
`make erase`
`make deploy`

If encountered authorization problem, use the following line to override. Make sure to double check if the USB serial port given is correct:
`sudo chmod 777 /dev/ttyACM0`

### 7.2. Windows Flash Download Tool
Copy firmware.bin file from the corresponding project files. Rename the file to the chip model for easy reference. For VMware + Ubuntu users, simply copy the file on Ubuntu, and then paste it within folders in Windows systems.


Open Flash Download Tool from Espressif, select chip model, loadMode select USB.

Final check on ESP32-S2 chip is on "bootloader mode", and the chip has successfully been detected by Windows, and the corresponding serial port number. If the chip is not detected on Windows, it could be connected to the Ubuntu virtual system, disconnect or shut down the virtual machine and replug the model.

Fill in the COM port to the corresponding chip port, add firmware file, and set the starting flash address to 0x1000.


One can also edit baud rate to maximize deployment speed, however, doing so might impact the stability.

Once finishing setup, click ERASE button to erase chip's flash, then click START to flash the new firmware into the chip's flash.

Check if firmware was flashed successfully by using a port debugging tool named "PuTTY" is recommented, as it is compatible on Windows and Linux systems.

Use the command line below to install PuTTY:
`sudo apt-get install putty
`

Launch PuTTY with Terminal or open it in the application row.

`putty`

For Windows users, simply [download](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) the 64bit putty.exe file and open it, no installation required.

PuTTY configuration are as follows:

Notice the debug message from MicroPython firmware previously compiled are set to transmit through USB port by default and not UART serial port. Connect to the board via USB port.

For Linux users, the device port should be ttyACM0, and in Windows it's a COM port. Double check the specific port name before filling port information.

Speed must be set to 115200, this is default by the chip design.

Hit Open, a new window will pop up, usually without any message. Press ctrl + D to restart MicroPython, and you will see the message:


This is the MicroPython REPL interpreter.

We can type in a simple MicroPython code to test:

`print("Hello User~")`

If you got a different result as the picture shown, such as, garbled text or not responding, then reflashing the firmware is required, or check if the above mentioned process is correct.

Please leave a comment if you have any questions, thank you.