Installing CircuitPython on a Gemma M0 (Shallow Thoughts)

Installing CircuitPython on a Gemma M0

(On Linux.)

I wrote previously about my difficulties installing CircuitPython on an ESP32 Feather.

When I ordered the Feather, I ordered a bunch of other stuff too, including a tiny wearable microcontroller that's sold specifically for MicroPython: a Gemma M0.

Again, I had trouble getting MicroPython working, but the Gemma's problem was quite different.

Unlike the ESP32 Reverse TFT Feather, the Gemma M0 came with MicroPython installed. But it was MicroPython 5 — far too old to be supported by any current libraries. Obviously I had to update it.

I downloaded the appropriate UF2 installer from the Gemma M0 CircuitPython page and proceeded according to the basic CP on Gemma M0 tutorial. Unlike the Feather, with the Gemma, mounting the GEMMABOOT disk and copying the UF2 to it correctly removed GEMMABOOT and created a CIRCUITPY disk, which I mounted.

But then nothing worked! There was both a code.py and a main.py on /CIRCUITPY, but nothing was running and no LEDs were blinking.

Connecting to the serial console with

screen /dev/ttyACM0 115200

revealed that both scripts were failing with:

ValueError: MicroPython .mpy file; use CircuitPython mpy-cross

In fact, just entering the CircuitPython REPL in the console and typing

import adafruit_dotstar

(the dotstar library is preinstalled) failed with the same message.

I couldn't get past this, so I ended up asking on the Adafruit forums, and got several quick and helpful responses, which got me going.

I think the problem is that copying the UF2 to /GEMMABOOT installs the files in the UF2, but does not remove any existing files. The original CircuitPython 5 that's shipped on the Gemma encodes its libraries in a compressed format with the .mpy extension, e.g. lib/adafruit_dotstar.mpy. This apparently worked in CircuitPython 5 but is no longer supported in CP10 (though I haven't found any source actually saying so). So all those old .mpy files sitting around in lib make it seem like you have those libraries installed, but you don't.

The easiest cure: use a program called circup, specifically

circup update

It will print a bunch of warnings where you have to confirm you want to update:

WARNING: 'adafruit_dotstar': module corrupted or in an unknown mpy format. Updating is required.
Do you want to update? [y/N]: y
Updated adafruit_dotstar

which of course you do, since the old libraries don't work at all.

If you can't or don't want to use circup, you could also

rm -rf /CIRCUP/lib/*

and then manually install any libraries you need.

I wish copying the UF2 to install CircuitPython removed files that were there previously. That would solve a lot of confusion. (Of course, mentioning this problem in the documentation would also help.)

Once CP is installed, the Gemma M0 is a wonderful little device. I had it driving a string of neopixels in no time flat, and now I have a fun battery powered blinky hat to wear to the holiday light parade. I can't wait to see what other fun wearables I can make.

Tags: hardware, python, circuitpython
[ 18:13 Dec 09, 2025    More hardware | permalink to this entry | ]