1.1.Requirements

The first thing you need is a board with an ESP8266 chip. The MicroPythonsoftware supports the ESP8266 chip itself and any board should work. The maincharacteristic of a board is how much flash it has, how the GPIO pins areconnected to the outside world, and whether it includes a built-in USB-serialconverter to make the UART available to your PC.

The minimum requirement for flash size is 1Mbyte. There is also a specialbuild for boards with 512KB, but it is highly limited comparing to thenormal build: there is no support for filesystem, and thus features whichdepend on it won’t work (WebREPL, mip, etc.). As such, 512KB build willbe more interesting for users who build from source and fine-tune parametersfor their particular application.

Names of pins will be given in this tutorial using the chip names (eg GPIO0)and it should be straightforward to find which pin this corresponds to on yourparticular board.

1.2.Powering the board

If your board has a USB connector on it then most likely it is powered throughthis when connected to your PC. Otherwise you will need to power it directly.Please refer to the documentation for your board for further details.

1.3.Getting the firmware

The first thing you need to do is download the most recent MicroPython firmware.bin file to load onto your ESP8266 device. You can download it from theMicroPython downloads page.From here, you have 3 main choices

• Stable firmware builds for 1024kb modules and above.

• Daily firmware builds for 1024kb modules and above.

• Daily firmware builds for 512kb modules.

If you are just starting with MicroPython, the best bet is to go for the Stablefirmware builds. If you are an advanced, experienced MicroPython ESP8266 userwho would like to follow development closely and help with testing newfeatures, there are daily builds (note: you actually may need somedevelopment experience, e.g. being ready to follow git history to knowwhat new changes and features were introduced).

Support for 512kb modules is provided on a feature preview basis. For endusers, it’s recommended to use modules with flash of 1024kb or more. Assuch, only daily builds for 512kb modules are provided.

1.4.Deploying the firmware

Once you have the MicroPython firmware (compiled code), you need to load it ontoyour ESP8266 device. There are two main steps to do this: first youneed to put your device in boot-loader mode, and second you need to copy acrossthe firmware. The exact procedure for these steps is highly dependent on theparticular board and you will need to refer to its documentation for details.

If you have a board that has a USB connector, a USB-serial converter, and hasthe DTR and RTS pins wired in a special way then deploying the firmware shouldbe easy as all steps can be done automatically. Boards that have such featuresinclude the Adafruit Feather HUZZAH and NodeMCU boards.

If you do not have such a board, you need keep GPIO0 pulled to ground and resetthe device by pulling the reset pin to ground and releasing it again to enterprogramming mode.

For best results it is recommended to first erase the entire flash of yourdevice before putting on new MicroPython firmware.

Currently we only support esptool.py to copy across the firmware. You can findthis tool here:https://github.com/espressif/esptool/, or install itusing pip:

pipinstallesptool

Versions starting with 1.3 support both Python 2.7 and Python 3.4 (or newer).An older version (at least 1.2.1 is needed) works fine but will require Python2.7.

Any other flashing program should work, so feel free to try them out or referto the documentation for your board to see its recommendations.

Using esptool.py you can erase the flash with the command:

esptool.py--port/dev/ttyUSB0erase_flash

And then deploy the new firmware using:

esptool.py--port/dev/ttyUSB0--baud460800write_flash--flash_size=detect0esp8266-20170108-v1.8.7.bin

You might need to change the “port” setting to something else relevant for yourPC. You may also need to reduce the baudrate if you get errors when flashing(eg down to 115200). The filename of the firmware should also match the filethat you have.

For some boards with a particular FlashROM configuration (e.g. some variants ofa NodeMCU board) you may need to manually set a compatibleSPI Flash Mode.You’d usually pick the fastest option that is compatible with your device, butthe-fmdout option (the slowest option) should have the best compatibility:

esptool.py--port/dev/ttyUSB0--baud460800write_flash--flash_size=detect-fmdout0esp8266-20170108-v1.8.7.bin

If the above commands run without error then MicroPython should be installed onyour board!

If you pulled GPIO0 manually to ground to enter programming mode, release itnow and reset the device by again pulling the reset pin to ground for a shortduration.

1.5.Serial prompt

Once you have the firmware on the device you can access the REPL (Python prompt)over UART0 (GPIO1=TX, GPIO3=RX), which might be connected to a USB-serialconverter, depending on your board. The baudrate is 115200. The next part ofthe tutorial will discuss the prompt in more detail.

1.6.WiFi

After a fresh install and boot the device configures itself as a WiFi accesspoint (AP) that you can connect to. The ESSID is of the form MicroPython-xxxxxxwhere the x’s are replaced with part of the MAC address of your device (so willbe the same every time, and most likely different for all ESP8266 chips). Thepassword for the WiFi is micropythoN (note the upper-case N). Its IP addresswill be 192.168.4.1 once you connect to its network. WiFi configuration willbe discussed in more detail later in the tutorial.

1.7.Troubleshooting installation problems

If you experience problems during flashing or with running firmware immediatelyafter it, here are troubleshooting recommendations:

• Be aware of and try to exclude hardware problems. There are 2 common problems:bad power source quality and worn-out/defective FlashROM. Speaking of powersource, not just raw amperage is important, but also low ripple and noise/EMIin general. If you experience issues with self-made or wall-wart style powersupply, try USB power from a computer. Unearthed power supplies are also knownto cause problems as they source of increased EMI (electromagnetic interference)- at the very least, and may lead to electrical devices breakdown. So, you areadvised to avoid using unearthed power connections when working with ESP8266and other boards. In regard to FlashROM hardware problems, there are independent(not related to MicroPython in any way) reports(e.g.)that on some ESP8266 modules, FlashROM can be programmed as little as 20 timesbefore programming errors occur. This ismuch less than 100,000 programmingcycles cited for FlashROM chips of a type used with ESP8266 by reputablevendors, which points to either production rejects, or second-hand worn-outflash chips to be used on some (apparently cheap) modules/boards. You may wantto use your best judgement about source, price, documentation, warranty,post-sales support for the modules/boards you purchase.

• The flashing instructions above use flashing speed of 460800 baud, which isgood compromise between speed and stability. However, depending on yourmodule/board, USB-UART converter, cables, host OS, etc., the above baudrate may be too high and lead to errors. Try a more common 115200 baudrate instead in such cases.

• If lower baud rate didn’t help, you may want to try older version ofesptool.py, which had a different programming algorithm:

  pipinstallesptool==1.0.1

  This version doesn’t support--flash_size=detect option, so you willneed to specify FlashROM size explicitly (in megabits). It also requiresPython 2.7, so you may need to usepip2 instead ofpip in thecommand above.

• The--flash_size option in the commands above is mandatory. Omittingit will lead to a corrupted firmware.

• To catch incorrect flash content (e.g. from a defective sector on a chip),add--verify switch to the commands above.

• Additionally, you can check the firmware integrity from a MicroPython REPLprompt (assuming you were able to flash it and--verify option doesn’treport errors):

  importespesp.check_fw()

  If the last output value is True, the firmware is OK. Otherwise, it’scorrupted and need to be reflashed correctly.

• If you experience any issues with another flashing application (notesptool.py), try esptool.py, it is a generally accepted flashingapplication in the ESP8266 community.

• If you still experience problems with even flashing the firmware, pleaserefer to esptool.py project page,https://github.com/espressif/esptoolfor additional documentation and bug tracker where you can report problems.

• If you are able to flash firmware, but--verify option oresp.check_fw() return errors even after multiple retries, youmay have a defective FlashROM chip, as explained above.