Running MicroPython on ESP8266 NodeMCU

For some upcoming projects, I’m going to make some DIY sensors and switches using the ESP8266 NodeMCU. It’s a pretty cheap board that is based on the ESP8266 which has built-in WiFi. In this post today I’m going to be getting a brand new “ESP8266 NodeMCU” up and running with MicroPython. MicroPython allows you to write microcontroller code using Python instead of using C or the Arduino libraries.

To get started you’ll need:

There are lots of other ESP8266 boards floating around the internet so if you decide to go with a different board I would just ensure it comes with at least 1Mbyte of flash so you can run the full version of MicroPython.

Once the firmware is correctly flashed to the device we’ll be running Python code using the Read Eval Print Loop (or REPL for short) which allows us to type in Python code directly to execute. We’ll be able to access the REPL over a serial and Web interface. Once that’s working we can upload a new boot script so the device automatically connects to your WiFi.

Loading ESP8266 Firmware

You need a tool called esptool to download MicroPython to the board. There are some instructions on the GitHub page, most of the time you can just install it globally on your machine using:

Next, you need to determine the usb port that the ESP8266 is plugged into. A quick way on a Linux box is to run ls /dev/tty* to see available ports. You can run the command with it unplugged and plugged in to see what got added. In my case, the board is at /dev/ttyUSB0.

Now that the port is determined we can erase the flash on the board. We use esptool to do this. Make sure to change the port to match your setup.

You should get a confirmation saying that chip erase completed successfully. Now, we need to get the latest firmware image for MicroPython. Check out the download page for the latest firmware for the ESP8266. Download the .bin file. Then we can flash the firmware using esptool again. Update the port to match your setup and the put the path to your .bin file you just downloaded.

Now MicroPython is running on your device! We can connect to the Python REPL by opening up the com port with a baud rate of 115200. Windows users can use PuTTY or a similar tool to connect. Linux/Mac users can use screen to attach to the device using screen (make sure to use a baud rate of 115200):

After attaching to the REPL try typing some python code like you normally would.

If you see the message print out everything should be installed correctly. You can also type in the following code to let MicroPython check the firmware image. If you get a True as the last line of your response then everything is working correctly.

Setting up WebREPL and WiFi

Next, we’re going to look at setting up the WebREPL. The WebREPL provides a web interface to type code into the Python REPL as well as upload/download files. We can use this to upload a new version of boot.py and main.py so that the device can execute code automatically instead of us having to type it out every time.

So to get started make sure you are attached to the interface and type the following.

After typing it a prompt will start up asking if you want to enable or disable it running on boot. Type E to enable it on boot and then create a password. After setting the password allow the board to reboot.

Next, we’re going to connect to your local WiFi so you can connect to the WebREPL from any device on your network. Open up a serial connection to the ESP8266 again and type the following (put in the correct ESSID and password for your WiFi access point)

Now the device should be connected to your WiFi. All the code is doing is importing the network module from MicroPython, getting an object for the WiFi station interface, enabling it and then connecting to the WiFi.

Use the following to make sure your device is connected and get the IP address:

Take note of the IP address, we’ll use it in the next section when using the WebREPL.

Using WebREPL

You should now have WebREPL setup and the device connected to your local access point with a local IP address assigned. Next open the WebREPL website and change the IP address to match the local IP address for your device. You could self host this application yourself, but for the time being we’ll use the hosted version for starting development.

Click the Connect button after changing the IP address and type the password you set in the last section. You should get a “WebREPL connected” message. You now have access to the same REPL that you did when accessing the device over the serial connection. This web interface also exposes some nice features to send and receive files.

Automatic Connect to WiFi on Boot

We’re now going to modify the boot code to automatically connect to our our access point on bootup. This is done by modifying the boot.py file that is in the flash memory on the device. Using the WebREPL download the current boot.py file sitting on the device. Check the screenshot below, click the Get from device button after filling out the form.

So the boot.py is now downloaded to your machine. Open it up in your favorite text editor, mine looks like:

Now, we’re going to modify this so that it runs the correct python code to connect to the access point. Edit the file to look like this, change the ESSID and password again to match your setup.

Upload the new boot.py using the WebREPL.

Once it’s uploaded you can unplug your board to power reset the device. This time after resetting the device should automatically connect to your WiFi network. To test this you can try to connect again using the WebREPL, which should work if the IP address remained the same. You can also use the serial REPL and run the following again:

Next Steps

You should now have a WiFi MicroPython device that automatically connects to your network when it boots up. In future articles I’ll be using this as a basis for communicating with a MQTT broker to push and pull data. Subscribe to the blog if you want to learn more!