First, make sure you've installed the fundamental MagTag libraries as shown on the previous page.

Text Editor

Adafruit recommends using the Mu editor for editing your CircuitPython code. You can get more info in this guide.

Alternatively, you can use any text editor that saves simple text files.

Code

Click the Download: Project Zip File link below in the code window to get a zip file with all the files needed for the project. Copy magtag_slidshow.py from the zip file and place on the CIRCUITPY drive, then rename it to code.py.

Also copy the whole /slides directory from the zip file and place and its contents it on the CIRCUITYPY drive. These are some sample images you can start with.

Image Prep

You can use the images included with the .zip download as a guide for making new images -- and we've got a whole guide on preparing graphics for e-ink displays called, wait for it... Preparing Graphics for E-Ink Displays!

The recommended specifications for the MagTag Slideshow* images are as follows:

  • .bmp file format
  • 4-bit indexed (these are nice and small, and it's a four-shades-of-grey display, so these look just as good as any higher bit depth)
  • 296 x 128 pixels

*note, there are different methods in CircuitPython for displaying images on e-ink displays, so for other projects you may need to use different bit-depths.

# Magtag Slideshow
# auto plays .bmp images in /slides folder
# press left and right buttons to go back or forward one slide
# press down button to toggle autoplay mode
# press up button to toggle sound

import time
import terminalio
from adafruit_magtag.magtag import MagTag
from adafruit_slideshow import PlayBackOrder, SlideShow, PlayBackDirection

magtag = MagTag()


def blink(color, duration):
    magtag.peripherals.neopixel_disable = False
    magtag.peripherals.neopixels.fill(color)
    time.sleep(duration)
    magtag.peripherals.neopixel_disable = True


RED = 0x880000
GREEN = 0x008800
BLUE = 0x000088
YELLOW = 0x884400
CYAN = 0x0088BB
MAGENTA = 0x9900BB
WHITE = 0x888888

blink(WHITE, 0.3)

# pylint: disable=no-member
magtag.add_text(
    text_font=terminalio.FONT,
    text_position=(
        5,
        (magtag.graphics.display.height // 2) - 1,
    ),
    text_scale=3,
)
magtag.set_text("MagTag Slideshow")
time.sleep(5)
magtag.add_text(
    text_font=terminalio.FONT,
    text_position=(3, 120),
    text_scale=1,
)
magtag.set_text("  back        mute      pause/play     fwd", 1)
time.sleep(8)

timestamp = time.monotonic()
sound_toggle = True  # state of sound feedback
autoplay_toggle = True  # state of autoplay
auto_pause = 60  # time between slides in auto mode

# Create the slideshow object that plays through alphabetically.
slideshow = SlideShow(
    magtag.graphics.display,
    None,
    auto_advance=autoplay_toggle,
    folder="/slides",
    loop=True,
    order=PlayBackOrder.ALPHABETICAL,
    dwell=auto_pause,
)

while True:
    slideshow.update()
    if magtag.peripherals.button_a_pressed:
        if sound_toggle:
            magtag.peripherals.play_tone(220, 0.15)
        blink(YELLOW, 0.4)
        slideshow.direction = PlayBackDirection.BACKWARD
        time.sleep(5)
        slideshow.advance()

    if magtag.peripherals.button_b_pressed:
        if not sound_toggle:
            magtag.peripherals.play_tone(660, 0.15)
            blink(CYAN, 0.4)
        else:
            blink(MAGENTA, 0.4)
        sound_toggle = not sound_toggle

    if magtag.peripherals.button_c_pressed:
        if not autoplay_toggle:
            if sound_toggle:
                magtag.peripherals.play_tone(440, 0.15)
            blink(GREEN, 0.4)
            autoplay_toggle = True
            slideshow.direction = PlayBackDirection.FORWARD
            slideshow.auto_advance = True
        else:
            if sound_toggle:
                magtag.peripherals.play_tone(110, 0.15)
            blink(RED, 0.4)
            autoplay_toggle = False
            slideshow.auto_advance = False

    if magtag.peripherals.button_d_pressed:
        if sound_toggle:
            magtag.peripherals.play_tone(880, 0.15)
        blink(BLUE, 0.4)
        slideshow.direction = PlayBackDirection.FORWARD
        time.sleep(5)
        slideshow.advance()

    time.sleep(0.01)

How It Works

Libraries

We import a libraries to take care of the heavy lifting, in this case:

Download: file
import time
import terminalio
from adafruit_magtag.magtag import MagTag
from adafruit_slideshow import PlayBackOrder, SlideShow, PlayBackDirection

The time library allows us to do some pausing between steps.

In order to easily display a title and some labels, the terminalio library gives us a typeface to use.

The adafruit_magtag library makes it very simple to set up the MagTag's display, use the buttons, NeoPixels, and speaker.

The adafruit_slideshow library similarly is a convenience library that makes it a snap to run a slideshow on the device!

Setup

There are a number of setup steps we'll take next. First, we create the MagTag() object named magtag (all lower-case is easier to type anyway!).

Next, we'll create a function called blink() in order to solve the Riemann Hypothesis. OK, OK, just kidding; it'll be used to blink the NeoPixels.

Download: file
def blink(color, duration):
    magtag.peripherals.neopixel_disable = False
    magtag.peripherals.neopixels.fill(color)
    time.sleep(duration)
    magtag.peripherals.neopixel_disable = True

Notice how there's no need for a separate NeoPixel setup, we can simply call them with the magtag.peripherals.neopixels commands.

The function has two arguments -- color and duration -- which make it simple to blink a particular color for a particular time period.

Next, we'll define some color variable names.

Download: file
RED = 0x880000
GREEN = 0x008800
BLUE = 0x000088
YELLOW = 0x884400
CYAN = 0x0088BB
MAGENTA = 0x9900BB
WHITE = 0x888888

And then we will flash the lights white upon startup:

blink(WHITE, 0.3)

Text

Next up, we'll use the magtag library's text commands to put a title and some instructional labels on screen.

Download: file
magtag.add_text(
    text_font=terminalio.FONT,
    text_position=(
        5,
        (magtag.graphics.display.height // 2) - 1,
    ),
    text_scale=3,
)
magtag.set_text("MagTag Slideshow")
time.sleep(5)
magtag.add_text(
    text_font=terminalio.FONT,
    text_position=(3, 120),
    text_scale=1,
)
magtag.set_text("  back        mute      pause/play     fwd", 1)

Note that each instance of text can be referred to by index number, so the first one is index 0, and the second is index 1, which appears as the second argument in this line:

magtag.set_text(" back mute pause/play fwd", 1)

Variables

We set a few variables that will used to track states and timing.

Download: file
sound_toggle = True  # state of sound feedback
autoplay_toggle = True  # state of autoplay
auto_pause = 60  # time between slides in auto mode

Slideshow Setup

The final bit of setup is to create the slideshow object:

Download: file
slideshow = SlideShow(
    magtag.graphics.display,
    backlight_pwm=None,
    auto_advance=autoplay_toggle,
    folder="/slides",
    loop=True,
    order=PlayBackOrder.ALPHABETICAL,
    dwell=auto_pause,
)

This sets up the slideshow to:

  • use the MagTag display
  • there is no backlight! so don't try
  • sets the auto advance on (initially)
  • specifies the folder for bitmaps
  • sets looping on, the playback order is alphabetical (RANDOM is the other option)
  • the dwell time between slides is set to 60 seconds

Main Loop

In the main loop of the program, the slideshow.update() line is all that's needed to run the slideshow with the initial settings! Everything else in the code here is for using the buttons.

Download: file
if magtag.peripherals.button_a_pressed:
        if sound_toggle:
            magtag.peripherals.play_tone(220, 0.15)
        blink(YELLOW, 0.4)
        slideshow.direction = PlayBackDirection.BACKWARD
        time.sleep(5)
        slideshow.advance()

    if magtag.peripherals.button_b_pressed:
        if not sound_toggle:
            magtag.peripherals.play_tone(660, 0.15)
            blink(CYAN, 0.4)
        else:
            blink(MAGENTA, 0.4)
        sound_toggle = not sound_toggle

    if magtag.peripherals.button_c_pressed:
        if not autoplay_toggle:
            if sound_toggle:
                magtag.peripherals.play_tone(440, 0.15)
            blink(GREEN, 0.4)
            autoplay_toggle = True
            slideshow.direction = PlayBackDirection.FORWARD
            slideshow.auto_advance = True
        else:
            if sound_toggle:
                magtag.peripherals.play_tone(110, 0.15)
            blink(RED, 0.4)
            autoplay_toggle = False
            slideshow.auto_advance = False

    if magtag.peripherals.button_d_pressed:
        if sound_toggle:
            magtag.peripherals.play_tone(880, 0.15)
        blink(BLUE, 0.4)
        slideshow.direction = PlayBackDirection.FORWARD
        time.sleep(5)
        slideshow.advance()

The A button and D button are used for reversing and advancing the slideshow by one slide, respectively. You can see the we play a quick beep sound if sound is enabled. The NeoPixels are also blinked a unique color depending on the direction.

The B button toggles the sound on or off each time it is pressed.

And, finally, the C button will toggle the auto advance state on and off.

Load up some images and give it all a try! When the player starts it will automatically advance and loop the slides. 

Press the C button to pause playback, press it again to resume. You'll see the NeoPixels blink red for "pause" and "green" for resume. 

Want to advance to the next slide, just press the D button. You can go back one slide by pressing the A button.

Oh, and lastly, if you don't want to hear beeps when you press the buttons, you can toggle sound by pressing the B button.

This guide was first published on Dec 22, 2020. It was last updated on Dec 22, 2020.

This page (Code the MagTag Slideshow Viewer) was last updated on Apr 10, 2021.

Text editor powered by tinymce.