Skip to main content

Play a GIF from a microSD card

What this example shows​

Playing a GIF animation from a FAT, FAT32 or exFAT microSD card with partial updates. Playback only works in INKPLATE_1BIT mode, and every pixel is converted to black or white with a fixed threshold, with no dithering.

Example code​

Trimmed from the pinned example: only the file header comment is removed, the code is unchanged.

Select Board
Inkplate10_GIF_From_SD.ino
#if !defined(ARDUINO_INKPLATE10) && !defined(ARDUINO_INKPLATE10V2)
#error "Wrong board selection for this example, please select e-radionica Inkplate10 or Soldered Inkplate10 in the boards menu."
#endif

#include "Inkplate.h" // Include Inkplate library to the sketch
Inkplate display(INKPLATE_1BIT); // Create an object on Inkplate library, GIF playback requires 1-bit mode

void setup()
{
display.begin(); // Init Inkplate library (you should call this function ONLY ONCE)
display.clearDisplay(); // Clear frame buffer of display
display.display(); // Push the cleared frame buffer to the panel with a full refresh

// Init SD card. Display if SD card is init properly or not.
if (display.sdCardInit())
{
// Play "cat_gif.gif" from the SD card root, centered on the screen.
// loop = true: keep replaying the file forever (until reset/power-cycled).
if (!display.gif.playGifFromSd("cat_gif.gif", E_INK_WIDTH / 2 - 125, E_INK_HEIGHT / 2 - 125, false, true, 20, true))
{
// If something failed (missing file, unsupported/corrupt GIF), write an error message on the screen.
display.setTextColor(BLACK);
display.setTextSize(3);
display.println("GIF open error");
display.display();
}
}
else
{
// If SD card init was not successful, display error on screen.
display.setTextColor(BLACK);
display.setTextSize(3);
display.println("SD Card error!");
display.display();
}

// Turn off the MOSFET that powers the SD card
display.sdCardSleep();
}

void loop()
{
// Nothing...
}

Functions used​

Inkplate(uint8_t mode)returns None

Creates the display object. `INKPLATE_1BIT` is black and white and supports partial updates. `INKPLATE_3BIT` gives 8 levels of grey but only full updates.

ReturnsConstructor; no return value.

Parameters

TypeNameDescription
uint8_tmodeINKPLATE_1BIT or INKPLATE_3BIT.
display.begin()returns void

Initializes the library and the display. Call it once, at the start of `setup()`.

ReturnsNothing.

display.clearDisplay()returns void

Clears the frame buffer in memory. It does not change what the panel shows until you call `display()`.

ReturnsNothing.

display.display(bool _leaveOn = 0)returns void

Does a full refresh: sends the frame buffer to the panel. If `_leaveOn` is true, the panel supply stays on after the refresh, which saves time on the next update.

ReturnsNothing.

Parameters

TypeNameDescription
bool_leaveOnKeeps the panel supply on after the update when true. Defaults to 0.
display.sdCardInit()returns int16_t

Powers the microSD card and starts the SD interface.

Returns`1` if the card initialized, `0` if it failed.

display.gif.playGifFromSd(const char *fileName, int x, int y, bool invert = false, bool loop = true, uint16_t fullRefreshEveryFrames = 20, bool leaveOn = true)returns bool

Plays a GIF from the SD card using partial updates. It blocks until the GIF ends, or forever when `loop` is true. Each pixel is turned black or white with a fixed threshold.

Returns`true` on success, `false` if playback failed (for example a missing or unsupported file).

Parameters

TypeNameDescription
const char *fileNameGIF file name on the card.
intxLeft position in pixels.
intyTop position in pixels.
boolinvertSwaps black and white when true. Defaults to false.
boolloopReplays the GIF forever when true. Defaults to true.
uint16_tfullRefreshEveryFramesForces a full refresh after this many partial updates to clear ghosting. 0 disables forced full refreshes. Defaults to 20.
boolleaveOnKeeps the panel powered between frames when true. Defaults to true.
display.setTextColor(uint16_t c)returns void

Sets the text color.

ReturnsNothing.

Parameters

TypeNameDescription
uint16_tcText color, for example BLACK.
display.setTextSize(uint8_t s)returns void

Scales text by an integer factor. The base font is 5 x 7 pixels.

ReturnsNothing.

Parameters

TypeNameDescription
uint8_tsScale factor.
display.println(value)returns size_t

Same as `print()`, then moves the cursor to the start of the next line. It comes from the Arduino `Print` class that `Adafruit_GFX` builds on.

ReturnsNumber of bytes printed.

Parameters

TypeNameDescription
text or numbervalueWhat to print.
display.sdCardSleep()returns void

Turns off the power to the microSD card and sets the SD interface pins to inputs to save energy.

ReturnsNothing.

What to expect​

Put a GIF named cat_gif.gif in the root of the card. The sketch plays it in a loop until you reset or power-cycle the board. The example header says playback speed is limited by the e-paper partial refresh, not by the GIF frame delay. A full refresh happens every 20 partial updates to clear ghosting. If playback fails, for example because the file is missing or unsupported, the display shows GIF open error. If the card does not start, it shows SD Card error!.

The GIF is placed with E_INK_WIDTH / 2 - 125 and E_INK_HEIGHT / 2 - 125 as the top left corner, so change those two offsets to suit the size of your own GIF.