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.
#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 NoneCreates 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
| Type | Name | Description |
|---|---|---|
uint8_t | mode | INKPLATE_1BIT or INKPLATE_3BIT. |
display.begin()returns voidInitializes the library and the display. Call it once, at the start of `setup()`.
ReturnsNothing.
display.clearDisplay()returns voidClears the frame buffer in memory. It does not change what the panel shows until you call `display()`.
ReturnsNothing.
display.display(bool _leaveOn = 0)returns voidDoes 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
| Type | Name | Description |
|---|---|---|
bool | _leaveOn | Keeps the panel supply on after the update when true. Defaults to 0. |
display.sdCardInit()returns int16_tPowers 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 boolPlays 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
| Type | Name | Description |
|---|---|---|
const char * | fileName | GIF file name on the card. |
int | x | Left position in pixels. |
int | y | Top position in pixels. |
bool | invert | Swaps black and white when true. Defaults to false. |
bool | loop | Replays the GIF forever when true. Defaults to true. |
uint16_t | fullRefreshEveryFrames | Forces a full refresh after this many partial updates to clear ghosting. 0 disables forced full refreshes. Defaults to 20. |
bool | leaveOn | Keeps the panel powered between frames when true. Defaults to true. |
display.setTextColor(uint16_t c)returns voidSets the text color.
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
uint16_t | c | Text color, for example BLACK. |
display.setTextSize(uint8_t s)returns voidScales text by an integer factor. The base font is 5 x 7 pixels.
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
uint8_t | s | Scale factor. |
display.println(value)returns size_tSame 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
| Type | Name | Description |
|---|---|---|
text or number | value | What to print. |
display.sdCardSleep()returns voidTurns 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.