Getting MicroPython

1. Get the latest version of Python 2 or 3 (we recommend 2)

• For Mac/Linux: https://www.python.org/downloads/mac-osx/ Python comes installed and can be accessed in Terminal by running the command python.
• For Windows: https://www.python.org/downloads/windows/ Python installation is required. Make sure to opt-in when the installer asks about adding Python to your system path! This is extremely easy to miss but extra important. Once installed, the Python interpreter can be accessed using the command python in Command Prompt. If that doesn't work, you can also try the command py.

• * Your Python version can be checked using the command python --version in the command line interface (i.e. Command Prompt for Windows, Terminal for Mac/Linux). *
  • If you're in the Python interpreter, the line will begin with >>> or ..., and you can return to the command line interface by using exit(). This distinction will be important later.
  • For Windows: the prompt should look something like C:\Users\yourname>.

• For Mac: it'll say roughly SoAndSo's Macbook:~ yourname$.
• ** Having Python locally on your computer is not technically a required step for configuring MicroPython to run on your board, but is extremely helpful when it comes to editing scripts and learning Python/MicroPython. **

2. As the regular download of Python contains only an interpreter and a single-line command prompt (known as a REPL, or read-eval-print-loop), it is recommended that you also download a text editor. We recommend the Anaconda package, which contains the Spyder IDE application and can be downloaded here (link). Spyder creates an environment similar to MATLAB, as opposed to using just what comes with Python--which would be like coding using only MATLAB's Command Window. It's like using a typewriter instead of Microsoft Word.

• Be sure to download the correct version of Anaconda to work with your version of Python.
• For Windows: Do NOT add Anaconda to your system path!
• If you choose not to use Anaconda/Spyder, you can still edit scripts as text files in Notepad with limited functionality.
• This is what Spyder looks like:

3. "pip" is a command line program used to install packages. Insure that you have pip installed by running the command pip --help in the command line directly into Terminal or Command Prompt (read: not the Python interpreter).

• You can also upgrade pip once you have it installed by running pip install -U pip on Mac or python -m pip install -U pip on PC.
• More information regarding pip can be found in the official pip documentation (link).

4. Use pip to install esptool.py (a python script which allows us to flash firmware to all ESP8266 boards):

• Run the command pip install esptool in Terminal or Command Prompt
• For Mac/Linux: you may need to type "sudo pip install esptool" and enter your password to your computer
  • It will not show the characters of the password as you type them, so don't worry when nothing shows up as you type, just type your password and hit enter
• You may need to use pip2 install esptool or pip3 install esptool depending on your version of Python.

5. Download Micropython Firmware from MicroPython.org (link).

• It is recommended to download the latest stable release of the firmware at the top of the list (avoid daily builds).
• The .bin file (binary) is the only one you need.

6. Put board in firmware flashing mode. This is automatic for the Adafruit Feather HUZZAH when you connect to the serial port of a computer (i.e. USB). For other boards within the ESP8266 class, refer to the manual for instructions on putting the board in firmware flashing mode.

7. Install the driver to make the board's serial port visible, courtesy of Silicon Labs (link).

• For Mac: Confirm the driver installed correctly by running the command " ls /dev/cu.* " in Terminal, you should see something like "/dev/cu.SLAB_USBtoUART " listed as one of the devices, if it is, move on to step number 8
  • If not, go in "System Preferences" and click "Security and Privacy". In the "General" tab, towards the bottom of the page, there may be an option to allow the driver to be installed, click "allow"
    • Also, go into "System Information" and under the "hardware" tab, click "USB", "CP2104 USB to UART Bridge Controller" should be listed there
    • If this doesn't work, uninstall and reinstall the driver
      • Do this by opening up the Silicon Labs VCP Driver Install disk, and drag the uninstaller.sh file into a Terminal Window
      • Then reinstall the Silicon Labs Driver
• For Windows: Avoid downloading versions of the driver with "Serial Enumeration" included. To confirm that the driver downloaded, open "Device Manager" and search for "Ports (COM and LPT)". You should find "Silicon Labs CP210x USB to UART Bridge (COM9)" or something similar. Remember the COM# part, that's how you'll access the Serial Monitor to receive messages from MicroPython and the board.

• For Linux: ??? good luck

8. Look below for the command to run for Mac/Windows to erase the existing flash on the board.

• Run the command esptool.py --port (port) erase_flash, replacing "(port)" with the path or name of the serial port that is connected to the ESP8266 without the parentheses.
  • For Mac: "/dev/cu.USBtoUART" is the name of your port
    • Your command should look like esptool.py --port /dev/cu.SLAB_USBtoUART erase_flash
  • For Windows: The device's COM# (COM11 or COM6, for examplke) that you found in the previous step is the name of your port.
    • Your command should look like esptool.py --port COM# erase_flash
  • For Linux: Please find a friend that has a Mac or Windows computer because Linux is dumb.
• TIP: Be very careful with spacing and spelling. If you make a mistake and receive an error, use the up arrow key to bring back your last command. You can also use the left and right arrow keys to edit mid-line, but clicking on a space between letters won't work.

9. Write the Micropython firmware onto to the ESP8266

• Repeat step 6 to put the board into firmware flashing mode. If you are using the HUZZAH, this is automatic and you can move on.
• In Terminal or Command Prompt, run the below command directly into the command line interface.

esptool.py --port (port) --baud (baud) write_flash --flash_size=detect 0 (firmware)

• Where it says (port), Insert the path or name of the serial port that is connected to the ESP8266 (without the parenthesis)
  • For Mac: It is /dev/cu.SLAB_USBtoUART
  • For Windows: It is COM# as before.
  • For Linux: yikes
• Where it says (baud), Insert the baud rate (without parenthesis). 115200 is a good baud rate, but if it does not work, try 9600
• The 0 (that's a zero, not an uppercase o) after --flash_size=detect is crucial.
• Where it says (firmware), insert the full, absolute file location and name for the firmware you just downloaded (esp8266...bin) do not include parenthesis
  • For Mac: This can be achieved by finding the file in Finder or searching for the file using Spotlight Search. From there, right click on the file name, then hold down the "option" key. Click "copy (filename) as pathname". You can then paste it directly in Terminal where it says (firmware).
    • If you hold the "option key", and you don't see the option "copy (filename) as pathname" then you must find where the firmware has been downloaded. It will most likely be in your downloads folder, but you can search "esp8266"
      • Once you find where the firmware is located in your computer run the command "cd downloads" or "cd documents" or "cd ...." wherever the firmware is. Then once you're there, go back up a
  • For Windows: This can be achieved by finding the file in File Explorer, right-clicking, and selecting properties. From there, copy the file location and name in the place of (firmware) like so: location\filename. Be sure to include the file extension.
• * If this still does not work, try using the command with fewer arguments. The bare minimum is:

esptool.py --port (port) write_flash 0 (firmware)

10. Reset the device (there's a button labeled RST on the HUZZAH). You are now running MicroPython on your board (hopefully).

Advance to the next tutorial to learn how to interact with MicroPython on your board!