This tutorial may be outdated. It is no longer recommended for beginners, and may need modifications to code or hardware that is not indicated in the tutorial.

MicroPython Usage

NOTE: This page describes using MicroPython firmware, not CircuitPython firmware. If you're using CircuitPython be sure to check out the CIrcuitPython guides: https://learn.adafruit.com/category/circuitpython and API docs: http://circuitpython.readthedocs.io/en/latest/? The MicroPython APIs described below won't work on CircuitPython firmware!

NOTE: The details below are a little out of date as the project has evolved significantly since the guide was written.  Check out the latest documentation on MicroPython ESP8266 here for the most up to date usage details: http://docs.micropython.org/en/latest/esp8266/index.html

To use MicroPython on the ESP8266 you'll need to connect to its serial port in a serial terminal at 115200 baud.  You can use any serial terminal, like PuTTY on Windows or screen on Linux & Mac OSX.

Once connected you can start entering MicroPython code in a read-eval-print loop (REPL).  For example here's the classic Hello World and counting to 10:

Download: file
>>> print("Hello world!")
Hello world!
>>> for i in range(1, 11):
...     print("Number {0}".format(i))
... 
Number 1
Number 2
Number 3
Number 4
Number 5
Number 6
Number 7
Number 8
Number 9
Number 10
>>>

Remember MicroPython isn't exactly the same as the Python you would use on the desktop.  In particular most of the python standard library isn't available.  Check out MicroPython's documentation for more information on what is supported by the language.

Also note the ESP8266 support for MicroPython is very beta and does not support all of MicroPython's libraries!  As of the time of this writing there's only enough support to access GPIO pins and connect to WiFi using a very low level socket-like interface.

Below are some tips on what you can do with MicroPython on the ESP8266 right now.

GPIO Access

Access to the GPIO pins on the ESP8266 is provided through an interface similar to the pyb.Pin class.  Here's a small example of blinking an LED connected to GPIO #14 ten times (make sure to connect a ~300+ ohm resistor in series with the LED):

Download: file
>>> import pyb
>>> pin = pyb.Pin(14, pyb.Pin.OUT)  # Set pin 14 as an output.
>>> for i in range(10):
...    pin.value(0)     # Set pin low (or use pin.low())
...    pyb.delay(1000)  # Delay for 1000ms (1 second)
...    pin.value(1)     # Set pin high (or use pin.high())
...    pyb.delay(1000)

One thing to be very careful about is putting your code in an infinite loop (like by replacing the for loop with a while True loop).  If you use an infinite loop then you won't be able to use the REPL to enter code anymore!  This might completely block you from using MicroPython and necessitate reflashing the firmware, so be careful using loops!

You can also use GPIO pins as inputs, for example here's reading pin 14 as an input:

Download: file
>>> import pyb
>>> pin = pyb.Pin(14, pyb.Pin.IN)
>>> pin.value()  # Read pin value, will show 0 when low (connected to ground).
0
>>> pin.value()  # Read pin value again, will show 1 when high (connected to 3.3V).
1

WiFi Access

Thanks to some excellent contributions the MicroPython ESP8266 firmware has basic support for using the ESP8266's WiFi radio.  Be aware the support is basic and only offers a low-level socket-like interface so you'll need to implement protocols yourself.  Here's a basic example to connect to a WiFi network and download a small test web page:

This Wifi example is obsolete and no longer works.
Download: file
>>> import esp
>>> 
>>> # Connect to a WiFi network.
>>> esp.connect('YOUR WIFI SSID NAME', 'YOUR WIFI SSID PASSWORD')
>>> 
>>> # Define function to print data received from socket.
>>> def socket_printer(socket, data):
>>>     print(data)
>>> 
>>> # Create a socket and setup the print function.
>>> soc = esp.socket()
>>> soc.onrecv(socket_printer)
>>> 
>>> # Connect to adafruit.com at port 80.
>>> soc.connect(('207.58.139.247', 80))
>>> 
>>> # Send a request for the wifi test page.
>>> soc.send('GET /testwifi/index.html HTTP/1.0\r\n\r\n')
37
>>> b'HTTP/1.1 200 OK\r\nDate: Tue, 12 May 2015 18:44:49 GMT\r\nServer: Apache\r\nAccess-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Accept-Encoding, Authorization, Referer, User-Agent\r\nAccess-Control-Allow-Methods: GET, POST, OPTIONS\r\nAccess-Control-Allow-Credentials: true\r\nAccess-Control-Max-Age: 1728000\r\nAccept-Ranges: bytes\r\nX-Mod-Pagespeed: 1.9.32.3-4448\r\nVary: Accept-Encoding\r\nCache-Control: max-age=0, no-cache\r\nContent-Length: 74\r\nConnection: close\r\nContent-Type: text/html\r\n\r\nThis is a test of the CC3000 module!\nIf you can read this, its working :)\n'

As you can see the esp module provides a simple socket-like interface to access internet services.  You'll need to implement protocols like HTTP yourself to access web pages, etc.

If you're curious what other functions exist on the esp.socket class (or any other object in MicroPython) you can see them by using the dir function:

Download: file
>>> dir(esp.socket)
['__del__', 'close', 'bind', 'listen', 'accept', 'connect', 'send', 'recv', 'sendto', 'recvfrom', 'onconnect', 'onrecv', 'onsent', 'ondisconnect']

Or check out the code for the module to see exactly how it works.  MicroPython code is similar to writing a C extension to Python so it will help to be familiar with the process of extending Python.  You'll also want to be aware of the key differences between MicroPython and normal desktop Python.

Running Code From A Script

You might have noticed all of the Python code so far has been entered by hand at the serial console.  Can you save a Python script and have it run with MicroPython on the ESP8266?  It turns out you can, but be aware support for saving code and running it is very limited and only allows for one file to be compiled in to the MicroPython firmware and run at boot.  MicroPython on the ESP8266 does not currently support running Python code off a SD card or other file system like other more mature MicroPython boards!

To make a script run at boot you'll need to compile a new slightly modified version of MicroPython's firmware.  Start up the VM for compiling MicroPython that you created in the previous steps (run the 'vagrant up' command and then 'vagrant ssh' command in the directory with the VM's Vagrantfile).  Once connected navigate to the MicroPython ESP8266 scripts directory and open the main.py script in a text editor like nano:

Download: file
cd ~/micropython/esp8266/scripts/
nano main.py

You should see a comment that says this script is run at boot:

Download: file
# This script is run on boot

Now you can enter any Python script you'd like to have run as soon as the board boots.  You can use the network, access GPIO, etc.  For example here's code to blink an LED connected to pin 14 forever:

Download: file
# This script is run on boot
import pyb
pin = pyb.Pin(14, pyb.Pin.OUT_PP)
while True:
    pin.value(1)
    pyb.delay(1000)
    pin.value(0)
    pyb.delay(1000)

Note if you use an infinite loop in the main script then the serial console REPL will not be accessible!  MicroPython doesn't have threading or multiprocessing support so it can only do one thing at a time.  If the main code never returns then the serial console REPL will never run!  You'll need to reflash the ESP8266 with firmware that has an empty main.py to bring back access to the serial console.

Save the modified main.py and exit nano by typing Ctrl-O and Ctrl-X.  Then rebuild the MicroPython ESP8266 firmware by executing:

Download: file
cd ~/micropython/esp8266
make

Again the output file is the ./build/firmware-combined.bin file.  You can copy this to the /vagrant folder and back to your main machine, then flash to an ESP8266 board just like in the previous steps.

That's all there is to running a script on boot with MicroPython on the ESP8266!

This guide was first published on May 12, 2015. It was last updated on May 12, 2015. This page (MicroPython Usage) was last updated on Jul 20, 2018.