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.txtrm -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')
