Initial steps: MicroPython on ESP8266

Adafruit Huzzah ESP8266 breakout board

Some time ago I witnessed people getting all kinds of excited about ESP8266 devices. Worth checking out, I thought, and promptly ordered about five boards – specifically the ESP8266 Huzzah boards from Adafruit. They’re not the cheapest, but with Adafruit you always know you’re getting quality and it has features like level-shifted (ie, 5V safe) RX pin and 3V3 output.

But when they arrived I was a tad busy and I thought to myself, “I’m already messing about with the Raspberry Pi, BeagleBone, Arduino and AVRs; do I really need another platform?”

Apparently I do.

Just lately I’ve been thinking a lot about home automation and ESP devices are just the thing. I mean, you can buy ready-made home automation devices, but if a smart lamp or quite-bright kettle is going to leak my personal details to Russian hackers or set my house on fire, I at least want to have had the pleasure of designing and building it myself.

And so I dug the boards out of the drawer, blew off the dust and started Googling. And what I found pleased me.

With these ESP boards, you get a tiny but capable microcontroller fitted with GPIO pins, a wifi module and a full TCP stack, all for … well, it depends which board you go for, but they’re all pretty cheap.

Quick overview

So, a quick overview. The ESP chips are produced by Shanghai manufacturer Espressif. By themselves they’re difficult to use, but an outfit called Ai-Thinker started building them into modules providing the microcontroller capabilities. And still these aren’t easy to use for us tinkerers. Luckily, just about everyone and his dog is producing development boards making the GPIO and other pins easily accessible. This made the ESP8266 wildly popular. More recently we’ve the addition of its bigger brother, the ESP32 which adds Bluetooth Classic/LT capabilities as well as a faster, two-core processor and more GPIO. Support for that wasn’t as good as the ESP8266 at first; it’s improving now but if you want a relatively painless introduction to the ESP world then the ESP8266 is still the better bet.

The ESP8266s I’m using are NodeMCU boards and come flashed with a version of the Lua programming language. You can connect to the board and start programming immediately using the built-in Lua interpreter. But I thought, “Do I really need to learn another language?”

This time the answer was no. And that’s when I found you can use Python instead.

I like Python.

(You can also erase the flash memory and code using the Arduino IDE, just as you would with any Arduino board. And I’m sure I will do that. Plus there’s a rather more complex and capable development environment you can run in your browser – check out Mongoose OS. But for now my focus is on Python.)

Getting going

Getting MicroPython onto the ESP8266 board and then using it aren’t difficult, but there are a few things that can trip you up.

So here’s my setup: I’m working on macOS using the CoolTerm terminal program to connect to the ESP8266 board via serial thanks to an FTDI cable. (Some boards have a built-in USB connection which provides a serial connection, but the standard Huzzah board doesn’t.) You can also use simpler USB-serial cables. On my Mac, the FTDI shows up as /dev/cu.usbserial-FTFXZ7LX, but precisely which port is in use will depend on your OS and cable.

The first thing you do is head over to the MicroPython site’s tutorial. It’s pointless to repeat everything that’s on that well-written site, so I’ll just summarise. You’ll need Python installed on your PC, and here I’m assuming Python 3 – if you’re masochistic enough to stick with 2.7 then you’re on your own as far as I’m concerned. For the avoidance of doubt, by ‘PC’ I mean your main machine, regardless of whether it’s running macOS, Linux or … what’s that other thing?

You then:

  • Install esptool on your PC.
  • Download new firmware for the ESP8266 from the MicroPython site.
  • Erase the ESP board’s firmware using esptool.
  • Flash the board with the new firmware.
  • Connect to the board over serial or a browser (but see below).

And it is all quite easy. But here’s a couple of things that caught me out, or at least took a moment’s thought.

Make sure you’re using the right serial port – it needs to be specified in the esptool commands.

I’d start with a baud rate of 115,200 for the serial connection. It’s slower than the maximum but safer.

When erasing and flashing the ESP8266, it needs to be in the right mode. How to achieve this is likely to vary from board to board, depending on how they are configured. On the Huzzah there are two buttons – a button connected to GPIO0 which, when pressed, takes that pin low (and also lights an LED); and a reset button. To get the Huzzah into flashing mode you need to press and hold down the GPIO0 button, press and release Reset and then release GPIO0. Because the board I’m using has been fitted with female headers it’s impossible to do all that with my fingers, so I’ve fashioned a tool from an extra-large paperclip to do the job.

Once I’d discovered that the board needs to be in this mode, I managed to erase the flash okay (bye-bye Lua). But I struggled to load the new firmware. With my early attempts having failed, it didn’t work until I erased the flash again. It took a long time for the firmware to download at 115,200 baud, but this only needs to be done once (or each time you update it).

A lot of work is done on the PC’s command line. And you often have to specify the port and the baud rate. So I save myself a bit of typing by starting with:



Then, instead of having to type /dev/cu.usbserial-FTFXZ7LX or 115200 all the time, I just type $PT and $BD.

Once the firmware has been flash, you connect to the ESP8266 using serial terminal software (CoolTerm in my case, although the Arduino IDE’s serial terminal could be pressed into service) and you’re presented with the classic triple angle-bracket of the Python REPL.


The ESP8266’s wifi has the ability to act as an access point (AP) or as a normal wifi client (or ‘station’) – or both. With the default install of MicroPython, the device is set as an AP. You can connect to it by selecting the AP in your PC’s wifi settings. The Python REPL then becomes available via a web browser using software called WebREPL running on the ESP. There are full details of this on the MicroPython site – but I haven’t yet got it to work. My Mac simply won’t connect. And I don’t care much, frankly – I’d rather use serial anyway, so I haven’t put any effort into solving the issue. In fact, I’ve turned off WebREPL by connecting to the ESP over serial and, at the Python REPL prompt, typing:

>> import webrepl_setup

That gives you the option of disabling WebREPL or, if you want it, setting the password.


Like I said, once you’ve connected, you’re in the REPL. You can type in Python code and watch it run. There’s also a special paste mode that allows you to paste in whole chunks of code. But that gets tiresome pretty quick.

There’s no operating system on the ESP8266, but there is a file system that stores files in the flash memory. So, if you want to do stuff like file management, you’ll need to use Python’s file handling functions. Towards the bottom of the screengrab of a CoolTerm session below you can see how I’ve imported the os module and used its methods os.listdir() and os.remove() to show the current directory’s files and delete one of them.

File transfer

Clearly a better method of writing software for the device is to code on your PC and then transfer the Python files over to the ESP8266. There exist several ways of doing this, but my current choice is Adafruit’s ampy. This is a command-line tool written in Python that you run on your PC. It’s a very simply way of transferring files to and from the ESP board, listing the files that are on it, deleting them and a couple of other functions.

So that’s me set up – in future posts I’ll look at MicroPython in a bit more depth. In the meantime, I’ll leave you with this tip: if you’re trying to use a command-line tool like esptool or ampy, make sure you don’t have a serial terminal talking to the board at the same time. I issued more than a few curses before I remembered to head over to CoolTerm and click ‘Disconnect’.


Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.