Flashing MicroPython onto a generic ESP8266 IoT controller

You can program the ESP8266 and ESP32 with a variety of tools and platforms including raw C, NodeMCU, Arduino IDE, LUA, and MicroPython. If you are here then you want to try MicroPython. Let's get MicroPython on our test board so that we start development.

Test mule with an ESP8266EX with a 24Mhz crystal and relay

Required Components

  • ESP8266 compatible board or module
  • A USB to 3.3V adapter and cable
  • A PC with a USB port and Internet Access

Installation and Verification Steps

We're going to erase the program memory and then load MicroPython into the program memory just erased. Finally, we will test with a small bit of Python code.

These are the steps I took to flash my ESP8266 board using my Windows 11 PC.

Development MachineESP8266 Target DeviceComments
Install Python3
Install esptoolPython 3 tools are required to flash the ESP8266 over serial. Future updates can be OTA.

python3 -m pip install esptool
Unplug the board
Set the jumper to programGPIO tied to ground
Connect USB-to-serial adapter to Dev MachineConnect the USB adapter to board
Connect power to the board
Verify the USB serial adapter COM/tty portIdentify the serial device on Dev Machine. We need it later for the esptool and the terminal connection
Download the MicroPython binary (.bin)
https://micropython.org/download/esp8266/
Erase the ESP8266 flash PC port style
python3 -m esptool --port COM6 erase_flash
Mac port style
python3 -m esptool --chip esp8266 erase_flash
Flash MicroPython onto ESP8266 PC port style
python3 -m esptool --port COM6 --baud 460800 write_flash \
--flash_size=detect 0 esp8266-20220618-v1.19.1.bin
Mac port style
python3 -m esptool --chip esp8266 write_flash \
--flash_size detect 0 esp8266-20220618-v1.19.1.bin
Unplug power from the board
Set the jumper to runGPIO0 tied to 3.3v
Connect power to the board
Verify the USB serial adapter COM/tty port 
Connect to the board over the serial connection The serial port speed is 115200.
Putty on PC or alternative.
Terminal with screen on Mac
Verify Python prompt in terminalShould see something like ">>>"

I have an old, possibly counterfeit, Prolific adapter.  It doesn't work with a "driver obsolete since 2012" style message but appears to work fine on a Mac with device /dev/cu.usbserial-1140 /dev/tty.usbserial-1140.  

Video Walkthrough

Identifying the ESP 8266 COM Port

You can find the Windows COM port by looking in the Windows Device Manager

Example Board Program/Run Jumper

The jumper in the middle of the upper edge ties GPIO0 to 3.3v or Gnd putting the board in run or program mode.

Connecting an ESP8266 to a Computer via USB/serial adapter

The adapter at the bottom bridges the 3.3v TX/RX serial port and the computer's USB port.


Installing esptool

joefreeman@Joes-MacBook-Pro ~ % python3 -m pip install esptool
Collecting esptool
Downloading esptool-4.3.tar.gz (222 kB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 222.5/222.5 kB 1.9 MB/s eta 0:00:00
Preparing metadata (setup.py) ... done
Collecting bitstring>=3.1.6
Downloading bitstring-4.0.1-py3-none-any.whl (45 kB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 45.6/45.6 kB 5.5 MB/s eta 0:00:00
Requirement already satisfied: cryptography>=2.1.4 in /Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages (from esptool) (38.0.3)
Collecting ecdsa>=0.16.0
Downloading ecdsa-0.18.0-py2.py3-none-any.whl (142 kB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 142.9/142.9 kB 5.7 MB/s eta 0:00:00
Requirement already satisfied: pyserial>=3.0 in /Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages (from esptool) (3.5)
Collecting reedsolo<=1.5.4,>=1.5.3
Downloading reedsolo-1.5.4.tar.gz (271 kB)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 271.3/271.3 kB 9.8 MB/s eta 0:00:00
Preparing metadata (setup.py) ... done
Requirement already satisfied: cffi>=1.12 in /Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages (from cryptography>=2.1.4->esptool) (1.15.1)
Requirement already satisfied: six>=1.9.0 in /Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages (from ecdsa>=0.16.0->esptool) (1.16.0)
Requirement already satisfied: pycparser in /Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages (from cffi>=1.12->cryptography>=2.1.4->esptool) (2.21)
Installing collected packages: reedsolo, ecdsa, bitstring, esptool
DEPRECATION: reedsolo is being installed using the legacy 'setup.py install' method, because it does not have a 'pyproject.toml' and the 'wheel' package is not installed. pip 23.1 will enforce this behaviour change. A possible replacement is to enable the '--use-pep517' option. Discussion can be found at https://github.com/pypa/pip/issues/8559
Running setup.py install for reedsolo ... done
DEPRECATION: esptool is being installed using the legacy 'setup.py install' method, because it does not have a 'pyproject.toml' and the 'wheel' package is not installed. pip 23.1 will enforce this behaviour change. A possible replacement is to enable the '--use-pep517' option. Discussion can be found at https://github.com/pypa/pip/issues/8559
Running setup.py install for esptool ... done
Successfully installed bitstring-4.0.1 ecdsa-0.18.0 esptool-4.3 reedsolo-1.5.4

Erase Flash - Example Output

    C:\Users\joe>python3 -m esptool --port COM6 erase_flash
    esptool.py v4.3
    Serial port COM6
    Connecting....
    Detecting chip type... Unsupported detection protocol, switching and trying again...
    Connecting...
    Detecting chip type... ESP8266
    Chip is ESP8266EX
    Features: WiFi
    Crystal is 26MHz
    MAC: 5c:cf:7f:19:7b:3a
    Uploading stub...
    Running stub...
    Stub running...
    Erasing flash (this may take a while)...
    Chip erase completed successfully in 9.4s
    Hard resetting via RTS pin...

Flash MicroPython - Example Output

    C:\Users\joe\Downloads>python3 -m esptool --port COM6 --baud 460800 write_flash --flash_size=detect 0 esp8266-20220618-v1.19.1.bin
    esptool.py v4.3
    Serial port COM6
    Connecting...
    Detecting chip type... Unsupported detection protocol, switching and trying again...
    Connecting...
    Detecting chip type... ESP8266
    Chip is ESP8266EX
    Features: WiFi
    Crystal is 26MHz
    MAC: 5c:cf:7f:19:7b:3a
    Stub is already running. No upload is necessary.
    Changing baud rate to 460800
    Changed.
    Configuring flash size...
    Auto-detected Flash size: 4MB
    Flash will be erased from 0x00000000 to 0x0009afff...
    Flash params set to 0x0040
    Compressed 634844 bytes to 419808...
    Wrote 634844 bytes (419808 compressed) at 0x00000000 in 10.0 seconds (effective 509.6 kbit/s)...
    Hash of data verified.

    Leaving...
    Hard resetting via RTS pin...

Example Python-ing

Toggle the ESP8266 Module LED

This code will toggle flash the CPU LED one time. You can paste it into the REPL from a terminal.  This assumes GPIO2 is the LED

import machine
pin=machine.Pin(2,machine.Pin.OUT)
pin.on()
pin.off()

My board has the same pinout as the WeMos D1 - see the table near the bottom.

Flash the ESP8266 Module LED

This code will flash the LED on the ESP8266

import machine
pin = machine.Pin(2, machine.Pin.OUT)
def toggle(p):
   p.value(not p.value())

import time
while True:
    toggle(pin)
    time.sleep_ms(500)


You can just paste it into a terminal window relying on the REPL

Python code entered via REPl is erased upon restart or even a ctrl-c.  You must put Python code into boot.py or main.py to get it to persist across resets.

Terminal on Windows

You'll need a terminal program that can hook to the serial port.  Linux and Mac have this built in.  On Microsoft Windows you can use something like PuTTY. This shows a sample PuTTy session configuration used in the samples above.


References

  • https://docs.micropython.org/en/latest/esp8266/tutorial/intro.html
  • http://micropython.org/download/#esp8266
  • https://docs.micropython.org/en/latest/esp8266/quickref.html
  • https://github.com/micropython/micropython/releases
  • https://www.mfitzp.com/wemos-d1-pins-micropython/

  • https://cyberblogspot.com/how-to-install-esptool-on-windows-10/
  • https://docs.espressif.com/projects/esptool/en/latest/esp32/installation.html
  • https://docs.espressif.com/projects/esptool/en/latest/esp8266/esptool/advanced-commands.html

My Wemos-compatible board

I'm using the LinkSprint R1 board which is pin aligned with the Wemos D1 board. https://www.mfitzp.com/wemos-d1-pins-micropython/
I2C may be implemented in software for MicroPython and thus may run on any pin.
LinkNode BreakoutESP8266 PinFunctions
Board LED/Relay16GPIO 
header5GPIO, I2C SCL 
header4GPIO, I2C SDA 
programming pin0GPIO 
CPU Module LED2GPIO 
header servo14GPIO, SPI SCK
header servo12GPIO, SPI MISO
header servo13GPIO, SPI MOSI
header servo15GPIO, SPI SS
headerA0Analog in, via ADC

3Receive

1Transmit

Revision

Created 2022 11

Comments

Popular posts from this blog

Understanding your WSL2 RAM and swap - Changing the default 50%-25%

Accelerate Storage Spaces with SSDs in Windows 10 Storage Pool tiers

Java 8 development on Linux/WSL with Visual Studio Code on Windows 10