How to wirelessly program the Espressif ESP8266 WiFi Module with MicroPython and Thonny (for Mac OS)
[The Espressif ESP8266]
The ESP8266, like the Raspberry Pi 3 Model B or the Arduino Uno, can function as a microcontroller. While only slightly larger than an SD card, the ESP8266 can extremely effectively power small to mid-size electronics projects. The ESP8266 is special because it is *also* designed to be a WiFi module. It can be used in tandem with another microcontroller, but its own microcontroller capabilities make it a useful and inexpensive two-for-one device.
With Python continuing to grow in popularity, and with more and more projects becoming WiFi capable, it’s handy to be able to wirelessly program the ESP8266 using Python. Here’s how to do it with Mac!
[Installing Micropython]
Micropython is exactly what it sounds like–it’s Python, but smaller. It uses less memory, so it’s useful for smaller boards. Functionally, it’s the same as Python, especially for smaller projects. To begin, we will need to upload Micropython firmware onto the ESP8266 flash memory.
Download the latest stable build here: https://micropython.org/download/esp8266/
[Installing ESPTool]
ESPTool is what we’ll use to upload Micropython onto our boards. ESPTool is an open-source utility that is used to communicate with the ROM bootloader.
First, we need to find the location of our board. If you haven’t already connected it to your computer via a micro-USB cable, do that now. Type the following into your terminal to find the connected USB:
Ls /dev/tty.usb*My port happened to be the following:/dev/tty.usbserial-14120
If you don’t already have Python installed on your computer, you’ll need that too. Use the following command line to see if it’s already installed:
python3 — versionIf it’s not, use the following command line to install it:
install python3We can now install ESPTool. Use the following command to do that (The second command allows us to verify installation):
pip install esptoolesptool.py -h
[Flash Micropython Firmware]
Alright! Time to get Micropython onto the board! First, erase any old firmware using the following command:
esptool.py — port <serial_port> erase_flashReplace ‘<serial_port>’ with the port we found above using the ls terminal command (e.g., /dev/tty.usbserial-14120).
Upload the Micropython firmware to the ESP8266 flash using the following command:
esptool.py — port <serial_port> write_flash — flash_size=detect -fm dio 0x00000 <micropython-firmware>.binReplace ‘<serial_port>’ with the port we found above using the ls terminal command (e.g., /dev/tty.usbserial-14120). Replace <micropython-firmware> with the name of the .bin file downloaded from the Micropython website (e.g., esp8266–20220618-v1.19.1.bin). If you get a file not found error, use the following command to change directories to the folder the .bin file is located in:
cd Downloads[The Thonny IDE]
The Thonny IDE is an IDE we can use to program the ESP8266 using Python. WebREPL (The thing that lets us program wirelessly, or “over the air”) is a convenient add-on in Thonny, making it an especially beginner-friendly IDE. Download the latest version of Thonny here: https://thonny.org/.
Open Thonny via terminal using the following command line (the -a tells terminal to open thonny wherever it may be located):
open -a thonnyNow that Thonny is open, we need to configure the interpreter to be able to communicate with the board. Do that in Run > Select Interpreter.
From the dropdown menu, select Micropython (ESP8266) and select the serial port we found earlier (e.g., /dev/tty.usbserial-14120). You can also ask Thonny to detect the serial port for you. Click OK. You should see the following message confirming connection:
[Finding the ESP8266 IP Address]
Now that we have established physical connection with our board, we want to set up a WebREPL that will facilitate OTA programming. We will do this by connecting both our computer and the board to the same external WiFi network. If you are logged in to a WiFi network that requires a splash page sign-in, follow these instructions using a mobile hotspot.
In the Thonny shell, copy and paste the following code to begin WebREPL setup. Enable running on boot, and create a password if you are prompted to do so. The password I chose was rpass.
import webrepl_setupNow, in a new Thonny file, copy and paste the following code. Replace the values of “wifi_name”, “replpassword”, and “wifi_password” with the data from the actual WiFi you will be connecting (both your board and your computer!) to.
wifi_name = ‘put_wifi_name_here’wifi_password = ‘put_wifi_password_here’replpassword = ‘put_repl_password_here’
Save this file under the name ‘secrets.py’. You can use it to store all your secure information, like passwords and login info.
Open the boot.py file, and copy and paste the following code into it:
import webreplimport timefrom secrets import wifi_name, wifi_passworddef connect(): #function to connect to the network import network Wlan = network.WLAN(network.STA_IF) if not wlan.isconnected(): wlan.active(True) wlan.connect(wifi_name, wifi_password)def showip(): #function to retrieve IP address once connected import network Wlan = network.WLAN(network.STA_IF) print(‘connecting to network’, wifi_name, ‘…’) time.sleep(2) print(‘network config: ‘, wlan.ifconfig())connect()showip()webrepl.start()import main #this allows our main code to run on boot
Now, in the Thonny shell, enter the following command:
from boot import showipThis will show you the network config, where the first number is your IP address, and will tell you which daemon has been started. In some cases, you may see two daemons have been started, when you can just take the second IP address shown and use that.
[Configuring the WebREPL]
We have now set up a repl password and found our board’s IP address! Using the Thonny interpreter setup, we can switch the serial port to WebREPL and connect the board to WiFi.
In Thonny, go to Run>Select Interpreter, and change the serial port to WebREPL. Update the default IP address to your board’s IP address, and update the password to the repl password you set during setup.
Press OK. After a few seconds, you should see a message in the Thonny shell saying that WebREPL has been connected.
Disconnect your board from your laptop and connect it to an external power source (a phone charger is fine). Now, reboot Thonny. You should see the same WebREPL connect message! Your board is now headless and ready for OTA programming.
[Testing the WebREPL Connection]
We can test the WebREPL connection with the LED on the board.
In the Thonny shell, copy and paste the following code line by line. The LED should turn on and off based on the value you assign. Notice, unconventionally, that a 0 value turns the LED on and that a 1 value turns the LED off.
from machine import PinLed = Pin(2, Pin.OUT)led.value(0)led.value(1)
If the above code works, we are now ready to send Python code to the ESP8266 wirelessly!
