• Python 3: Install from the python website for your platform. Make sure to add it to your PATH on Windows.

Install the following programs using a terminal (MacOSX and Linux) or with command prompt (Windows).

  • esptool: Install with the command: pip3 install esptool
  • ampy: Install with the command: pip3 install adafruit-ampy

If you are getting a permission error, add “sudo” before the command (MacOSX and Linux) e.g. sudo pip3 install esptool, or launch a command prompt as administrator (Windows) and run the command in the new terminal.

  • putty: (Windows only) Install from their website.


Download the latest firmware from here.

Erase Firmware


Use the command below to erase the existing flash from the ESP8266. On Windows you can check the port for the microcontroller by going to Device Manager and selecting “Ports (COM and LPT)”. If you plug in the microcontroller while viewing this menu you should see a new device appear. That device is the ESP8266. Replace the “X” in the command below with the COM number from the device manager.

esptool --port COMX --baud 115200 erase_flash

MacOSX and Linux

In a terminal enter the command ls /dev. Check for a new device by plugging in the microcontroller and entering the command again. On Linux you should see a new item appear that starts with “ttyUSB” followed by a number and on MacOSX you should see an item appear that starts with “cu”. Replace the “X” in the command below with this new item. --port /dev/X --baud 115200 erase_flash

Write Firmware

In your terminal, navigate to the same directory as .bin file you dowloaded at the beginning of this guide and enter the following command to install the firmware on your ESP8266. Replace “X” with the same value as you did above and replace “FIRMWARE_FILE” with the exact name of the file as it appears your directory.


esptool --port COMX --baud 115200 write_flash --flash_size=detect -fm dio 0 FIRMWARE_FILE.bin

MacOSX and Linux --port /dev/X --baud 115200 write_flash --flash_size=detect -fm dio 0 FIRMWARE_FILE.bin

Test Firmware Installation

Hard reset the microcontroller by pressing the reset button next to the micro USB port.

Open a REPL


Open putty which you should have installed in the requirements section. Select the “Serial” radio button. For “Serial line” enter the port starting with “COM” which you found in the section above. For speed enter the value “115200”. Lastly click on the “Open” button on the bottom of the dialog.

MacOSX and Linux

Start a REPL over the serial by port using the following command. Replace X with the port that you found in the section above.

sudo screen /dev/X 115200

Test Firmware

Press enter until you see >>>. This means that a REPL has been successfully created.

To check that state of the firmware, enter the following lines into the REPL:

import esp

If you see output containing “True” you have successfully installed the firmware.


To start programming check out the wifi clock Github repo for starter code and examples.

More guides and videos will be posted soon. Stay tuned!