The ESP8266 is a great little WIFI module that can run micropython.

From the homepage of the vendor:

ESP8266 is a highly integrated chip designed for the needs of a new connected world. It offers a complete and self-contained WiFi networking solution, allowing it to either host the application or to offload all WiFi networking functions from another application processor.

Condensed specs:

  • WiFi (802.11 b/g/n, direct connect and AP mode, WEP, WPA/WPA2)
  • integrated TCP/IP protocol stack
  • uProcessor (Xtensa LX106) @ 80Mhz, 96kB data RAM, 64kB instruction RAM
  • SDIO 1.1/2.0, SPI, UART, GPIO
  • Vcc 3.3V, I = 0.5uA..215mA
  • application interface uses AT commands

Getting Started

Docker is a tool that provides a container that houses all the tools necessary to build micropython. It automates setting up the build environment and isolates it from your main system.

  1. Install Docker and git 
    sudo apt-get install docker git
  2. Build ESP docker image 
    docker build https://github.com/nevers/esp-open-sdk-docker.git

Building micropython

There are pre-built micropython binaries for a variety of microprocessors available online. These next steps are if you want to make modifications to the micropython codebase.

  1. Clone the micropython repo and make any modifications 
    git clone --recurse-submodules -j8 [email protected]:micropython/micropython.git
  2. Build micropython 
    docker run --rm -ti -v `pwd`:`pwd` -w `pwd`/micropython/ports/esp8266/ esp-open-sdk:2.0.0 make axtls
docker run --rm -ti -v `pwd`:`pwd` -w `pwd`/micropython/ports/esp8266/ esp-open-sdk:2.0.0 make

Checking connectivity

  1. Plug in your programmer/serial device to your computer and ESP and find the tty name: 
      dmesg | tail

    The output should look something like this:

      usb 5-2: New USB device found, idVendor=0403, idProduct=6010
  usb 5-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
  usb 5-2: Product: DLP2232M
  usb 5-2: Manufacturer: FTDI
  usb 5-2: SerialNumber: FTYRWJML
  usbcore: registered new interface driver usbserial_generic
  usbserial: USB Serial support registered for generic
  usbcore: registered new interface driver ftdi_sio
  usbserial: USB Serial support registered for FTDI USB Serial Device
  ftdi_sio 5-2:1.0: FTDI USB Serial Device converter detected
  usb 5-2: Detected FT2232C
  usb 5-2: FTDI USB Serial Device converter now attached to ttyUSB0
  ftdi_sio 5-2:1.1: FTDI USB Serial Device converter detected
  2. Check for connectivity by changing /dev/ttyUSB0 to the correct tty device and run the command 
    docker run --rm -ti --device=/dev/ttyUSB0 -v `pwd`:`pwd` -w `pwd`/micropython/ports/esp8266/ -e PYTHONIOENCODING=utf-8 esp-open-sdk:2.0.0 python -m serial.tools.miniterm /dev/ttyUSB0 115200

  3. Reset the ESP and you should see the bootloader output to your terminal, otherwise see esptool troubleshooting tips for more information.

  4. Press CTRL+] to exit.

Flashing the compiled binary

  1. Reset the ESP while holding GPIO0 low, this will put it into flash mode.

  2. Change /dev/ttyUSB0 in the command below with the correct tty device and run to flash to that device 
    docker run --rm -ti --device=/dev/ttyUSB0 -v `pwd`:`pwd` -w `pwd`/micropython/ports/esp8266/ esp-open-sdk:2.0.0 make PORT=/dev/ttyUSB0 deploy
  3. Reset the ESP

Initial setup

  1. Micropython has the WebREPL disabled by default so you will need to configure it. Connect to the serial REPL using the following command 
    docker run --rm -ti --device=/dev/ttyUSB0 -v `pwd`:`pwd` -w `pwd`/micropython/ports/esp8266/ -e PYTHONIOENCODING=utf-8 esp-open-sdk:2.0.0 python -m serial.tools.miniterm /dev/ttyUSB0 115200

  2. Press CTRL-B to get the prompt, it should appear as >>>. Test the prompt by typing print('hello esp8266!').

  3. Connect the ESP to your wifi by running the following commands (See here for details) 
    import network
sta_if = network.WLAN(network.STA_IF)
sta_if.active(True)
sta_if.connect('<your ESSID>', '<your password>')
sta_if.ifconfig()

Upload your code

The micropython boot process is detailed here but basically runs boot.py and then main.py. boot.py loads any daemons or services and main.py is where your custom code should be placed.

To upload main.py you can use the upload utility of WebREPL, install a ftp server, or compile (freeze) your code.

WebREPL

WebREPL provides a convienient means of accessing the ESPs python interpreter, allowing you to upload files or control the device manualy. This is useful when developing software but it is not recommended to enable this on production devices.

  1. Configure WebREPL by typing import webrepl_setup at the serial REPL prompt >>> and follow the instructions.

  2. Press CTRL-D to restart the ESP. Browse to MicroPython browser WebREPL client and connect to the ESPs IP address to access the WebREPL. If you are not able to connect, check for a shield in your browsers address bar, the browser may be blocking the connection.

Install a FTP server

You may want to install a convenient FTP server for managing the files on the ESP.

  1. Begin by cloning the uftp library from its repo 
    git clone --recurse-submodules -j8 [email protected]:robert-hh/FTP-Server-for-ESP8266-and-ESP32.git
  2. Link the module into the micropython folder so that the compiler will include it 
    ln -s ../../../../FTP-Server-for-ESP8266-and-ESP32/uftpd.py micropython/ports/esp8266/modules/uftpd.py
  3. Ensure you are working with a clean build 
    docker run --rm -ti -v `pwd`:`pwd` -w `pwd`/micropython/ports/esp8266/ esp-open-sdk:2.0.0 make clean

  4. Build and flash micropython exactly as before

  5. Restart the ESP and, as before, connect to the serial REPL

  6. At the >>> prompt type import uftpd

  7. Connect to the ESPs IP address using your favorite FTP client and upload your code

Freezing your code

Updated: