Last Updated: 

Getting Code onto ESP8266 with MicroPython

The ESP8266 is a low-cost Wi-Fi microchip with full TCP/IP stack and microcontroller capability. MicroPython is a lean and efficient implementation of the Python 3 programming language that includes a small subset of the Python standard library and is optimised to run on microcontrollers. Combining the ESP8266 with MicroPython allows developers to quickly prototype and develop IoT applications using the familiar Python syntax. In this blog post, we will explore the fundamental concepts, usage methods, common practices, and best practices for getting code onto an ESP8266 using MicroPython.

Table of Contents#

  1. Fundamental Concepts
  2. Prerequisites
  3. Flashing MicroPython Firmware
  4. Connecting to the ESP8266
  5. Uploading Code to the ESP8266
  6. Common Practices
  7. Best Practices
  8. Conclusion
  9. References

Fundamental Concepts#

MicroPython Firmware#

MicroPython firmware is a pre-compiled binary file that contains the MicroPython interpreter and a set of libraries tailored for the ESP8266. Before you can run Python code on the ESP8266, you need to flash this firmware onto the device.

REPL (Read - Evaluate - Print - Loop)#

The REPL is an interactive shell that allows you to enter Python commands one by one and see the results immediately. It is a powerful tool for testing code snippets, debugging, and interacting with the hardware.

File System#

The ESP8266 running MicroPython has a simple file system. You can store Python scripts on the device and run them later. The main script that runs on boot is called main.py.

Prerequisites#

  • ESP8266 Board: Any ESP8266-based development board, such as the NodeMCU.
  • USB Cable: To connect the ESP8266 to your computer.
  • Computer: Running Windows, macOS, or Linux.
  • Python 3: Installed on your computer. You will need it to run the firmware flashing tool and other utilities.
  • Firmware File: Download the latest MicroPython firmware for the ESP8266 from the official MicroPython website.
  • Esptool: A Python utility used to flash the firmware onto the ESP8266. You can install it using pip install esptool.

Flashing MicroPython Firmware#

Step 1: Erase the Existing Flash#

First, you need to erase the existing content on the ESP8266 flash memory. Open a terminal and run the following command:

esptool.py --port /dev/ttyUSB0 erase_flash

Replace /dev/ttyUSB0 with the actual serial port of your ESP8266 on your computer. On Windows, it might be something like COM3.

Step 2: Flash the MicroPython Firmware#

After erasing the flash, you can flash the MicroPython firmware. Run the following command:

esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect 0 esp8266-20230426-v1.20.0.bin

Replace /dev/ttyUSB0 with your serial port and esp8266-20230426-v1.20.0.bin with the actual name of the firmware file you downloaded.

Connecting to the ESP8266#

Using PuTTY (Windows) or Minicom (Linux)#

  • Windows: Download and open PuTTY. Select the serial connection type, enter the serial port (e.g., COM3) and the baud rate (usually 115200), and click Open.
  • Linux: Open a terminal and run minicom -D /dev/ttyUSB0 -b 115200 (replace /dev/ttyUSB0 with your serial port).

Once connected, you should see the MicroPython REPL prompt (>>>).

Uploading Code to the ESP8266#

Using Ampy (Adafruit MicroPython Tool)#

Ampy is a command-line tool for interacting with MicroPython boards over a serial connection. Install it using pip install adafruit-ampy.

Uploading a Single File#

To upload a Python script, say test.py, to the ESP8266, run the following command:

ampy --port /dev/ttyUSB0 put test.py

Running a Script#

You can run the uploaded script from the REPL. First, import the script:

import test

Setting the Boot Script#

To make a script run on boot, rename it to main.py and upload it:

ampy --port /dev/ttyUSB0 put main.py

Common Practices#

Error Handling#

When writing code for the ESP8266, it's important to include error handling. For example, when connecting to a Wi-Fi network:

import network
import time
 
sta_if = network.WLAN(network.STA_IF)
if not sta_if.isconnected():
    print('Connecting to network...')
    sta_if.active(True)
    sta_if.connect('your_SSID', 'your_PASSWORD')
    for _ in range(10):
        if sta_if.isconnected():
            break
        time.sleep(1)
    if not sta_if.isconnected():
        print('Network connection failed')
    else:
        print('Network config:', sta_if.ifconfig())

Memory Management#

The ESP8266 has limited memory. Avoid creating large lists or objects that can exhaust the memory. You can use generators and iterators instead.

Best Practices#

Modular Code#

Write modular code by splitting your program into smaller functions and classes. This makes the code easier to understand, test, and maintain.

Version Control#

Use a version control system like Git to manage your code. This allows you to track changes, collaborate with others, and roll back to previous versions if needed.

Conclusion#

Getting code onto an ESP8266 using MicroPython is a straightforward process that involves flashing the firmware, connecting to the device, and uploading your Python scripts. By understanding the fundamental concepts, following common practices, and adopting best practices, you can efficiently develop IoT applications using the ESP8266 and MicroPython. With the power of Python, you can quickly prototype and deploy projects with less code and faster development cycles.

References#

2025-10