In this guide, we’ll introduce you to Thonny IDE. After completing this guide, you’ll have your first LED blinking using MicroPython and Thonny IDE. It allows you to program your ESP32 and ESP8266 boards with MicroPython, and it is compatible with Windows, Mac OS X, and Linux. It even comes installed by default with Raspbian OS for Raspberry Pi.
A) Installing Thonny IDE – Windows PC
To install Thonny on your Windows PC, follow the next instructions:
1. Go to https://thonny.org
2. Download the version for Windows and wait a few seconds while it downloads.
3. Run the .exe file.
4. Follow the installation wizard to complete the installation process. You just need to click “Next”.
5. After completing the installation, open Thonny IDE. A window as shown in the following figure should open.
B) Installing Thonny IDE – Mac OS X
Since Thonny IDE is open source and downloaded from the Internet, it’s not a verified app in the App Store. For security reasons, Mac OS X blocks unknown apps to run on your computer. Follow these next instructions to enable any downloaded software to run in your Mac.
1. Open the “System Preferences...” menu.
2. Open the “Security & Privacy” menu.
3. At the bottom left corner, click the lock icon to modify your “Security & Privacy” settings:
4. Type your username/password and click the “Unlock” button.
5. Finally, select the option “Allow apps downloaded from: Anywhere“.
That’s it, you can close that window.
To install Thonny on Mac OS X, follow the next instructions:
1. Go to https://thonny.org
2. Download the version for Mac OS X and wait a few seconds while it downloads.
3. Open the .dmg file.
4. Drag the “Thonny” application to your Desktop:
5. Thonny IDE is now installed and you can double-click to open it:
6. After the installation is completed, open Thonny IDE. A window as shown in the following figure should open.
C) Installing Thonny IDE – Linux
To install Thonny on your Linux computer, it depends on your Linux distribution and version, follow the next instructions for your system. First, we recommend installing these dependencies: python3, python3-pip, and python3-tk
If you’re in Ubuntu, you can install the Python dependencies like this:
sudo apt install python3 python3-pip python3-tk
After having Python3, pip3, and Python3 Tkinter, you can install Thonny IDE.
- Ubuntu (after running that command, you’ll need to press Enter again to install the software):
bash <(wget -O – https://thonny.org/in
- Or you can install Thonny IDE with pip3:
sudo pip3 install thonny
- Fedora since 27:
sudo dnf install thonny
- Raspbian since Stretch (installed by default):
sudo apt install python3-thonny
After installing Thonny IDE and depending on your installation method, to open Thonny IDE:
- You either need go to the search bar and type “Thonny” to find it
- Or if you installed Thonny IDE using pip3, you can type in your terminal window:
thonny
Then, it should open Thonny IDE:
Testing the Installation
Connect the board to your computer using an USB cable. To test the installation, you need to tell Thonny that you want to run MicroPython Interpreter and select the board you are using.
1. Go to Tools > Options and select the Interpreter tab.
2. Choose MicroPython on a generic device.
3. Then, select your device serial port (recommended).
You can also select the “Try to detect automatically” option, but only if you just have one board connected to your computer at a time. Otherwise, select the specific port for the board you’re using.
4. Thonny IDE should now be connected to your board and you should see the prompt on the Shell.
5. Type the command help() in the Shell and see if it responds back.
If it responded back, everything is working fine. Now, you can send a few more commands to test.
Send the following commands to light up the on-board LED
>>> from machine import Pin
>>> Pin(2, Pin.OUT).value(1)
If you’re using an ESP8266, the logic to turn on the LED works the other way around, so you should send the following command instead:
>>> Pin(2, Pin.OUT).value(0)
The on-board LED should light up.
Then, turn off the led:
>>> Pin(2, Pin.OUT).value(0)
Thonny IDE Overview
At this point, you should have:
- Thonny IDE installed on your computer
- ESP32/ESP8266 flashed with MicroPython firmware
Open Thonny IDE. There are two different sections: the Editor and the MicroPython Shell/Terminal:
- The Editor section is where you write your code and edit your .py files. You can open more than one file, and the Editor will open a new tab for each file.
- On the MicroPython Shell you can type commands to be executed immediately by your ESP board without the need to upload new files. The terminal also provides information about the state of an executing program, shows errors related with upload, syntax errors, prints messages, etc…
You can also customize Thonny IDE to show other useful tabs. Go to View and you can select several tabs that provide more information.
Something that could be very useful is the Variables tab. It lists all available variables in your program and their corresponding values.
Running Your First Script
To get you familiar with the process of writing a file and executing code on your ESP32/ESP8266 boards, we’ll upload a new script that simply blinks the on-board LED of your ESP32 or ESP8266.
Creating the main.py file on your board
1. When you open Thonny IDE for the first time, the Editor shows an untitled file. Save that file as main.py. Simply, click the save icon and name the file main.py.
2. The Editor should now have a tab called main.py.
3. Copy the following code to the main.py file:
from machine import Pin
from time import sleep
led = Pin(2, Pin.OUT)
while True:
led.value(not led.value())
sleep(0.5)
Uploading the Script
Go to Device and select Upload current script as main script.
It should write the following on the Shell.
Note: uploading the code as main script will save the current file with the name main.py on the ESP, even if you have saved it in your computer with a different name. The same happens for the boot.py file.
Important: when the ESP restarts, first it runs the boot.py file and afterwards the main.py.
After uploading the script, press the ESP EN/RESET button
The ESP on-board LED should be blinking.
Congratulations, you’ve successfully uploaded a new script to your ESP32/ESP8266 using Thonny IDE.
List Files Saved on ESP32/ESP8266
To list all files saved on the ESP board, type in the Shell:
%lsdevice
Show File Content
To show the file content, use %cat / followed by the file path. For example:
%cat /main.py
Alternatively, to show the boot.py and main.py scripts, you can also go to Device and select one of the options: Show device’s main script or Show device’s boot script.
Uploading Files/Libraries
To upload a file with a unique name to your ESP using Thonny IDE, follow these next steps:
- Create a new file
- Save it in your computer with the exact name that you want, for example “umqttsimple.py”
- Go to Device > Upload current script with current name
- The file should be saved on the ESP with the name “umqttsimple.py”
- You can list the files stored in your ESP board with the command %lsdevice:
That’s it! The umqttsimple.py file was uploaded to your board. You can see the file content using the %cat /umqttsimple.py command:
Removing/Deleting File from ESP
At the moment, Thonny IDE doesn’t have a command to remove a file from the ESP. So, in order to remove/delete all files completely from your ESP, you need to re-flash it with MicroPython firmware.
Note: you can upload a blank script to the ESP board to remove/delete code.
Conclusion
Thonny IDE is a great IDE to program the ESP32 and ESP8266 boards using MicroPython. It is compatible with Windows, Mac OS X, and Linux and it easy to install.
