Installing CircuitPython on an ESP32 Reverse Feather TFT

(On Linux, natch.)

I’ve been wanting to play around with CircuitPython for ages. I like Python, I like microcontrollers, what’s not to like? Quite a while back, I even ordered a Feather M0 for that — but I didn’t do my research, ordered the wi-fi version and it turned out that’s the one Feather M0 that can’t run CircuitPython.

This time I checked more carefully before ordering, and got a processor that for sure claimed to run CircuitPython.

I had a specific project in mind: a CO2 meter that I can take to meetings and public spaces as a proxy for a COVID virus detector. After a lot of research on the Adafruit website, I decided the ESP32-S3 Reverse TFT Feather looked perfect. It’s small, has a built-in display, definitely claims to run CircuitPython, and has built-in buttons and what Adafruit calls a Stemma QT connector (technically a 4 Pin JST SH) so I could connect to the CO2 sensor without even needing solder or test clips. (I’ll write about the CO2 sensor project separately.) It also has a battery connector and built-in logic to charge a li-ion battery and report on voltage.

So far, it’s a terrific board. But I had some teething pains getting it to run CircuitPython, and the documentation is very incomplete, so that’s what this article is for.

Before I ordered, I read all the way through the installation instructions for CircuitPython on the Reverse Feather TFT. Everything looked very straightforward.

Once the Feather arrived, following the instructions, I plugged it in to USB. It showed up as a serial device, ready to be used from the Arduino toolset. Just to make sure, I fired up the Arduino IDE (normally I use the arduino-mk command-line tools for development, but the IDE is an easy way to check that things are working) and verified everything was fine by loading a blink sketch.

Enough of that; onward to CircuitPython. I followed the slightly confusing instructions (are you supposed to double-click once first, and then click twice again? The first double-click didn’t seem to make any difference, but I did it just to make sure). After a tap on the reset button (LED turned purple) then a second tap (red, then green), the FTHRS3BOOT drive appeared as it was supposed to. I mounted the drive, then copyied the CP install to it:

ls -l /dev/disk/by-label
sudo mount LABEL=FTHRS3BOOT /mnt
sudo cp adafruit-circuitpython-adafruit_feather_esp32s3_reverse_tft-en_US-10.0.3.uf2 /mnt
sync

Then I waited, periodically re-running that ls -l /dev/disk/by-label to see when the FTHRS3BOOT drive disappeared and the CIRCUITPY drive appeared.

Except that it never did. I waited fifteen minutes, running sync a few more times just in case, and verified with diff that the UF2 file on the FTHRS3BOOT was the same as the one I copied. But no CIRCUITPY label.

I tried unplugging and starting over several times, with the same result each time.

Trying Open Installer

I searched the Adafruit forums, and found several other people who’d had problems getting CP onto their Reverse TFT Feathers. One person recommended going to the CircuitPython download page for the ESP32-S3 Reverse TFT Feather and using the OPEN INSTALLER button — from chrome because Firefox doesn’t support serial ports.

So I tried that, though I used chromium, not chrome. Open Installer gives you several choices; I told it to erase everything, overwrite the bootloader, then install CP. It looked like the re-flash of the bootloader went okay. Then it got to the CP install step and reported

Flashing ...

There was a progress bar but it was empty and never filled in. I waited ten minutes, but nothing happened and nothing changed on the mounted FTHRS3BOOT.

What finally worked

I tried the Open Installer again, but this time, I told it to only flash the bootloader. Once that was done, I unplugged the Feather, plugged it back in, and ran the manual install again, mounting FTHRS3BOOT and copying the UF2 file to it, then running sync right away.

And wonder of wonders, a light on the Feather started flashing (which it hadn’t done before) and in just a few seconds, the CIRCUITPY drive appeared!

So I’m not sure what to make of all this, except that following the instructions definitely isn’t enough. Evidently it needs a new bootloader. This may be related to the note on that circuitpython.org download page:

Note: CircuitPython 10 and later, on Espressif boards with 4MB flash, requires TinyUF2 0.33.0 or later. The flash partition layout has changed (details).

Is the ESP32 Reverse Feather TFT an "Espressif board"? That word isn’t mentioned on its page, but apparently Espressif is a Chinese company that makes ESP32 chips, so, maybe.

Or maybe there’s just a timing issue, and trying it over and over eventually accidentally got it right.

Anyway, if you have trouble installing CircuitPython on your Feather, try installing a new bootloader first. And if that doesn’t work, I guess, keep trying it over and over.

Once that pain was over, the board worked beautifully. I plugged in the CO2 sensor and got it working in just a few minutes, and the rest of the work was user interface and building a case. I love the display and the other features. I’ll probably buy a few more of these boards and I’m looking forward to working more with them. But I wish it wasn’t so hard to get CircuitPython installed.

Tags: hardware, python, circuitpython [ *13:58 Dec 04, 2025 More hardware | permalink to this entry | * ]