To use MicroPython on the ESP8266 you'll need a firmware file to load on the ESP8266.  The best way to get the firmware is to build it yourself from its source code.  This way you can get the latest version of MicroPython and even make changes to add features or extend MicroPython on the ESP8266.  This page will show you how to setup a toolchain in a virtual machine that can compile MicroPython firmware.

However if you just want to try out MicroPython on the ESP8266 check out the easy install option below to download a pre-made firmware image.

Easy Install

Since his guide was originally published the MicroPython team has now started to provide pre-built firmware images of MicroPython for the ESP8266.  Check out this brand new guide that explains how to download and flash the official MicroPython firmware images to an ESP8266.  If you're a beginner or new to MicroPython you probably want to start there first!

Toolchain Setup

To build MicroPython firmware for the ESP8266 you'll need to first build the ESP open SDK toolchain that can compile code for the ESP8266's processor.  You could manually compile and install this SDK on your computer, however it's much easier to use a small virtual machine running Linux to compile and use the toolchain.  This way you can use the ESP open SDK from any computer regardless of it running Windows, Mac OSX, or even Linux, and you can keep the SDK's tools in an environment that's isolated and won't conflict with any other development tools on your machine.

Dependencies

To setup the virtual machine you'll need to install a few pieces of software:

• VirtualBox - This is open source virtualization software that is a free download.
• Vagrant - This is an open source wrapper around VirtualBox which makes it easy to create and run a virtual machine from the command line.  Vagrant is also free to download.
• Git - Source control system used to download the configuration for this project.  Git is also free and open source.

Once you have VirtualBox, Vagrant, and Git installed on your system then you can move on to provisioning the virtual machine.

Provision Virtual Machine

To create and provision the virtual machine you'll need to download a Vagrant configuration file.  This file defines what operating system to install (Ubuntu 14.04) and some commands to prepare the operating system for building the ESP SDK.

Start by opening a command line terminal (in Windows make sure to open a 'Git Bash' command window as you'll need to use Git commands) and run the following command to clone the repository for this project and navigate inside it:

Now 'turn on' the virtual machine by running this command:

The first time the 'vagrant up' command runs it will take a bit of time as it downloads the operating system image, but later 'vagrant up' commands will be faster as the OS image is cached internally.

Once the virtual machine is running you should see the command finish with text like:

If you see an error go back and make sure you've installed both VirtualBox and Vagrant.  Also make sure you're executing the command from inside the cloned repository's directory, there should be a file named Vagrantfile inside the directory you're running these commands from.

Once the virtual machine is running you can enter a Linux command terminal on it by executing the command:

After a moment you should be at an Ubuntu Linux command prompt that looks something like:

Woo hoo!  Your virtual machine is now running and ready to compile the ESP open SDK and MicroPython firmware.

Compile ESP Open SDK

Once inside the virtual machine you'll first need to compile the ESP open SDK.  The SDK source code has already been downloaded in the esp-open-sdk subdirectory during the virtual machine provisioning.  You just need to change to the directory and execute a command to make the project.  Run the following commands:

Note that the compilation will take a bit of time.  On my machine compilation took about 30 minutes, but on an older or slower machine it might take an hour or more.  Luckily you only need to compile the ESP open SDK once and then can quickly build MicroPython using the compiled SDK tools.

If during the compilation you see it fail with an error like:

This means the virtual machine ran out of memory as it compiled the SDK tools.  You can resolve this by increasing the amount of memory available to the SDK.  Shut down the VM and edit the Vagrantfile to change this line:

Try increasing it to 1.5 or even 2 gigabytes and 'vagrant up' the machine again to try the compilation again.  I found only about 1 gigabyte of memory was needed to compile the toolchain (and this is the default value in the Vagrantfile configuration).

If you see the compilation fail with a different error then there might be a problem with the ESP open SDK.  Try checking the github issues for it to see if there is a known issue with the error you received.

Once the compilation has finished you should see it end with text like:

Now the ESP open SDK is compiled and you're almost ready to build MicroPython (or any other ESP8266 code you'd ever like to compile).  First though you need to add the ESP open SDK tools to the virtual machine's path so MicroPython can find them.  Run this command to update the .profile file that runs whenever you log into the virtual machine:

To make this updated path available log out and back in to the virtual machine by running:

Once logged in again you should see your path environment variable has the ESP open SDK tools in it.  You can check this by running the command:

You should see a path value that looks something like this (notice the esp-open-sdk tools in the path):

Excellent!  Now you're all set to compile MicroPython in the next section.  Remember you only need to perform the ESP open SDK compilation steps above once in the virtual machine.

Compile MicroPython Firmware

Next you can build the MicroPython firmware for the ESP8266.  Make sure you've followed all the steps above and have a virtual machine running and the ESP open SDK compiled.

The MicroPython source code has already been downloaded to the micropython folder during the virtual machine provisioning.  However you need to run a small git command to pull in external dependencies before you can build it.  To install this dependency and then start the compilation execute the following commands inside the virtual machine:

The MicroPython library compilation should be quick and only take a few minutes at most.  Once it completes you should see text like the following:

If you see an error, try searching the MicroPython issues to see if the error is a known issue.

Once finished the output will be the file ./build/firmware-combined.bin.  In the next section you'll walk through how to load the firmware on an ESP8266 board, however first you'll need to copy the firmware bin file out of the virtual machine.  Luckily Vagrant has a special directory inside the virtual machine which can be used to copy files between the virtual machine and the host computer running Vagrant.  Execute the following command to copy out the firmware bin file to this shared folder:

Now exit the virtual machine by running the following command:

Then check that the firmware-combined.bin file is on your computer in the same directory that you ran 'vagrant up' to start the VM.  If you don't see the file then log back in to the virtual machine (using 'vagrant ssh') and make sure the command to copy the firmware-combined.bin file to the /vagrant folder inside the VM succeeded.

Once you have successfully compiled the firmware-combined.bin file and retrieved it from inside the VM you're done using the virtual machine.  Run the following command to 'turn off' the virtual machine:

If you'd like to start the VM again in the future just navigate to the same directory as the Vagrantfile and run the 'vagrant up' command again.  After a few moments the VM will be running and you can run 'vagrant ssh' to enter a terminal on the virtual machine.  All of the files and SDK tools that were compiled previously should be available again in the VM.

Continue on to learn how to flash the compiled ESP8266 MicroPython firmware to the hardware.