Welcome to CircuitPython! (original) (raw)

1004

Beginner

Skill guide

CircuitPython for ESP8266

We are no longer supporting CircuitPython on ESP8266. This page is for historical purposes only. There is no guarantee that the instructions will continue to work.

Why are we dropping support for ESP8266?

CircuitPython on ESP8266 has not been a great experience for users. It's hard to send files to the device because it has no native USB, and you can quickly run out of RAM (there's less than you think once the networking stack is added). We've decided to only use ESP as a co-processor. Specifically, the ESP32 because it has good TLS/SSL support which is now essential for even the most basic interactions.

If you'd like to use ESP8266, please keep to version 3.x with the knowledge that it isn't supported. You can also check out MicroPython for ESP8266 which is still supported!

If you'd like to add WiFi support, check out our guide on ESP32/ESP8266 as a co-processor.

About ESP8266 for CircuitPython (3.x)

We have two 'strains' of CircuitPython, the primary one is the ATSAMD21/51-based boards that have native USB connectivity. Native USB means that the board can show up as a disk drive called CIRCUITPY and hold all your files on it.

There's also CircuitPython for boards like the ESP8266 and nRF52832, these are really nice chips with WiFi and Bluetooth, respectively, built in. But they do not have native USB! That means there is no way for the chip to appear as a disk drive. You can still use them with CircuitPython but its a lot tougher, so we don't recommend them for beginners. Here's what you have to know about using non-native chips for CircuitPython:

You only get a REPL connection! No HID keyboard/mouse or other USB interface
No disk drive for drag-n-drop file moving, files must be moved via a special tool such as ampy that 'types' the file in for you via the REPL
Loading CircuitPython requires command line tools

Installing CircuitPython on the ESP8266

To use CircuitPython with the ESP8266 you'll need to first flash it with the latest firmware.

Download esptool

First install the esptool.py software which enables firmware flashing on the ESP8266. The easiest way to install this tool is from Python's pip package manager. If you don't have it already you'll need to install Python 2.7 (make sure you check the box to put Python in your system path when installing on Windows) and then run the following command in a terminal: pip install esptool

Note on Mac OSX and Linux you might need to run the command as root with sudo, like: sudo pip install esptool

If you receive an error that esptool.py only supports Python 2.x try running again with the pip2 command instead of pip (likely your system is using Python 3 and the pip command is getting confused which version to use).

Download Latest CircuitPython Firmware

Next download the latest CircuitPython ESP8266 firmware file:

Get ESP8266 Ready For Bootloading

Now you'll need to put the ESP8266 into its firmware flashing mode. Each ESP8266 board is slightly different:

For a raw ESP8266 module you'll need to wire up buttons to ground for the GPIO0 and RESET pins. Hold the GPIO0 button down (or connect the line to ground) and while still holding GPIO0 to ground press and release the RESET button (or connect and release the line from ground), then release GPIO0.
For the HUZZAH ESP8266 breakout buttons for GPIO0 and RESET are built in to the board. Hold GPIO0 down, then press and release RESET (while still holding GPIO0), and finally release GPIO0.
For the Feather HUZZAH ESP8266 you don't need to do anything special to go into firmware flashing mode. This board is built to detect when the serial port is opened for flashing and automatically configure the ESP8266 module to receive firmware. Be sure to first install the SiLabs CP210x driver on Windows and Mac OSX to make the board's serial port visible! On Windows you want the normal VCP driver, not the 'with Serial Enumeration' driver.

Erase ESP8266

It's recommended to erase the entire flash memory of the ESP8266 board before uploading firmware. Run the following command in a terminal to perform this erase:

esptool.py --port ESP8266_PORTNAME erase_flash

Where ESP8266_PORTNAME is the path or name of the serial port that is connected to the ESP8266. The exact name of the device varies depending on the type of serial to USB converter chip so you might need to look at the serial ports with and without the device connected to find its name.

Program ESP8266

Now put the ESP8266 back into firmware flashing mode and run the following command to load the downloaded firmware file:

esptool.py --port ESP8266_PORTNAME --baud 115200 write_flash --flash_size=detect 0 firmware.bin

Again set ESP8266_PORTNAME to the path or name of the serial port that is connected to the ESP8266. In addition set firmware.bin to the name or path to the firmware file you would like to load.

Once the tool finishes flashing the firmware (you'll usually see a blue light on the ESP8266 module flashing during this process) press the RESET button on the ESP8266 board or disconnect and reconnect it to your computer. You should be all set to start using the latest CircuitPython firmware on the board!

Note that if you see an error that "detect is not a valid flash_size parameter" you might be using an older version of esptool.py. To upgrade to the latest version run the following command pip install --upgrade esptool

Upload Libraries & Files Using Ampy!

The biggest difference you'll find with ESP8266 is that you need to use a special tool to move files around. Check out ampy by reading this guide. It's about MicroPython but CircuitPython is nearly identical so the the overall installation and usage is identical!

Other Stuff To Know!

The REPL works as you'd expect, so check out that introductory page.
File storage is in the same chip as CircuitPython so if you update, you may lose your files! Keep backups.
Libraries and API are also the same as for other CircuitPython boards.
Note that the ESP8266 does not have a ton of pins available, and only one analog input with 0-1.0V range. There is no UART port available (it's the one used for the REPL!)
There are no analog outputs.
For SPI and I2C, you can use them! But you will need to use bitbangio to create the bus objects

Page last edited August 20, 2025