Todbot's Host-side tasks tricks

Things you might need to do on your computer when using CircuitPython.

Installing CircuitPython libraries

The below examples are for MacOS / Linux. Similar commands are used for Windows

Installing libraries with circup

circup can be used to easily install and update modules

$ pip3 install --user circup
$ circup install adafruit_midi
$ circup update   # updates all modules

Freshly update all modules to latest version (e.g. when going from CP 6 -> CP 7) (This is needed because circup update doesn't actually seem to work reliably)

circup freeze > mymodules.txt
rm -rf /Volumes/CIRCUITPY/lib/*
circup install -r mymodules.txt

And updating circup when a new version of CircuitPython comes out:

$ pip3 install --upgrade circup

Copying libraries by hand with cp

To install libraries by hand from the CircuitPython Library Bundle or from the CircuitPython Community Bundle (which circup doesn't support), get the bundle, unzip it and then use cp -rX.

cp -rX bundle_folder/lib/adafruit_midi /Volumes/CIRCUITPY/lib

Note: on limited-memory boards like Trinkey, Trinket, QTPy, you must use the -X option on MacOS to save space. You may also need to omit unused parts of some libraries (e.g. adafruit_midi/system_exclusive is not needed if just sending MIDI notes)

Preparing images for CircuitPython

CircuitPython requires "indexed" (aka "palette") BMP3 images. If using adafruit_imageload the images can have RLE compression, but if using displayio.OnDiskBitmap(), then make sure no compression is used.

To make images load faster, you can reduce the number of colors in the image. The maximum number of colors is 256, but try reducing colors to 64 or even 2 if it's a black-n-white image.

Some existing Learn Guides:

And here's some ways to do the conversions.

Command-line: using ImageMagick

ImageMagick is a command-line image manipulation tool. With it, you can convert any image format to BMP3 format. The main ImageMagick CLI command is convert.

convert myimage.jpg -resize 240x240 -colors 64 -type palette -compress None BMP3:myimage_for_cirpy.bmp

Command-line: using GraphicsMagick

GraphicsMagick is a slimmer, lower-requirement clone of ImageMagick. All GraphicsMagick commands are accessed via the gm CLI command.

gm convert myimage.jpg -resize 240x240 -colors 64 -type palette -compress None BMP3:myimage_for_cirpy.bmp

Making images smaller or for E-Ink displays

To make images smaller (and load faster), reduce number of colors from 256. If your image is a monochrome (or for use with E-Ink displays like MagTag), use 2 colors. The "-dither" options are really helpful for monochrome:

convert cat.jpg -dither FloydSteinberg -colors 2 -type palette BMP3:cat.bmp

NodeJs: using gm

There is a nice wrapper around GraphicsMagick / Imagemagick with the gm library. A small NodeJs program to convert images could look like this:

var gm = require('gm');
gm('myimage.jpg')
    .resize(240, 240)
    .colors(64)
    .type("palette")
    .compress("None")
    .write('myimage_for_cirpy.bmp', function (err) {
        if (!err) console.log('done1');
    });

Python: using PIL / pillow

The Python Image Library (PIL) fork pillow seems to work the best. It's unclear how to toggle compression.

from PIL import Image
size = (240, 240)
num_colors = 64
img = Image.open('myimage.jpg')
img = img.resize(size)
newimg = img.convert(mode='P', colors=num_colors)
newimg.save('myimage_for_cirpy.bmp')

This guide was first published on Apr 02, 2022. It was last updated on Apr 02, 2022.

This page (Host-side tasks) was last updated on May 19, 2022.

Text editor powered by tinymce.