CircuitPython Setup

Your Adafruit PyPortal should already come with CircuitPython but maybe there's a new version, or you overwrote your board with Arduino code! In that case, see the below for how to reinstall or update CircuitPython. Otherwise you can skip this and proceed with the build.

Install Libraries for CircuitPython

Use the link below to download the Adafruit CircuitPython Library Bundle. Download the adafruit-circuitpython-bundle-4.x-mpy-*.py bundle zip file, and unzip a folder of the same name. Inside you'll find a lib folder. You have two options:

  • You can add the lib folder to your CIRCUITPY drive. This will ensure you have all the drivers. But it will take a bunch of space on the 8 MB disk
  • Add each library as you need it, this will reduce the space usage but you'll need to put in a little more effort.

At a minimum we recommend the following libraries, in fact we more than recommend. They're basically required. So grab them and install them into CIRCUITPY/lib now!

  • adafruit_pyportal
  • adafruit_imageload
  • adafruit_slideshow
  • adafruit_sdcard
  • adafruit_bus_device
  • neopixel.mpy

Images on internal flash

The code looks for an "images" folder on the CIRCUITPY drive by default. If it can't find any there, it'll search for images on the SD card.

Images on SD Card

If no images are on the internal storage, the code will search on the microSD card. The microSD card must be FAT32 and contain a folder named "images".

Image file names can be titled arbitrarily but avoid using special characters, hyphens and the sort. Your images must be in the following format and resolution.

  • Images must be 320 x 240 pixel 16-bit color .bmp files
Download our sample image pack to get you started!

Upload code

Copy the python code below and paste it into a text document, then save it to the CIRCUITPY drive.

import os
import board
import busio
import digitalio
import storage
import adafruit_sdcard
from adafruit_slideshow import PlayBackOrder, SlideShow, PlayBackDirection

# Default location to look is in internal memory

switch = digitalio.DigitalInOut(board.D3)
switch.direction = digitalio.Direction.INPUT
switch.pull = digitalio.Pull.UP

spi = busio.SPI(board.SCK, MOSI=board.MOSI, MISO=board.MISO)
cs = digitalio.DigitalInOut(board.SD_CS)
    sdcard = adafruit_sdcard.SDCard(spi, cs)
    vfs = storage.VfsFat(sdcard)
    storage.mount(vfs, "/sd")
    IMAGE_DIRECTORY = "/sd/images"
except OSError as error:
    print("No SD card, will only look on internal memory")

def print_directory(path, tabs=0):
    for file in os.listdir(path):
        stats = os.stat(path + "/" + file)
        filesize = stats[6]
        isdir = stats[0] & 0x4000

        if filesize < 1000:
            sizestr = str(filesize) + " by"
        elif filesize < 1000000:
            sizestr = "%0.1f KB" % (filesize / 1000)
            sizestr = "%0.1f MB" % (filesize / 1000000)

        prettyprintname = ""
        for _ in range(tabs):
            prettyprintname += "   "
        prettyprintname += file
        if isdir:
            prettyprintname += "/"
        print('{0:<20} Size: {1:>6}'.format(prettyprintname, sizestr))

        # recursively print directory contents
        if isdir:
            print_directory(path + "/" + file, tabs + 1)

except OSError as error:
    raise Exception("No images found on flash or SD Card")

# Create the slideshow object that plays through once alphabetically.
slideshow = SlideShow(board.DISPLAY, None, folder=IMAGE_DIRECTORY, loop=True,
                      order=PlayBackOrder.ALPHABETICAL, dwell=0)
while True:
    if not switch.value:
        slideshow.direction = PlayBackDirection.FORWARD
        while not switch.value:

This guide was first published on Mar 12, 2019. It was last updated on Mar 12, 2019.

This page (Code) was last updated on May 17, 2021.

Text editor powered by tinymce.