microSD gallery

What this example shows

Pick a random picture from the root folder of the microSD card, draw it, and go to deep sleep for 5 minutes. When the board wakes, the sketch runs again from the start and picks another one. Put some .bmp, .jpg or .png files in the card's root folder before you start.

This example also uses the ESP32 deep sleep functions (arduino-esp32), which are not part of the Inkplate library and come with the ESP32 board package. SdFile and FsFile come from the SdFat library that the Inkplate library includes.

Example code

Select Board

Inkplate7SPECTRA_Gallery.ino

#include "Inkplate.h" // Include Inkplate library to the sketch
Inkplate inkplate;     // Create an object on Inkplate library and also set library into 1 Bit mode (BW)
SdFile file;          // Create SdFile object used for accessing files on SD card

#define DELAY_MS 5 * 60 * 1000

// Here we store possible image paths
String files[100];
int fileCount = 0;

// Generic helper function to see if null terminated c string ends with other string
// https://stackoverflow.com/questions/744766/how-to-compare-ends-of-strings-in-c
int endsWith(const char *str, const char *suffix)
{
    if (!str || !suffix)
        return 0;
    size_t lenstr = strlen(str);
    size_t lensuffix = strlen(suffix);
    if (lensuffix > lenstr)
        return 0;
    return strncmp(str + lenstr - lensuffix, suffix, lensuffix) == 0;
}

void setup()
{
    // Initialize serial
    Serial.begin(115200);

    inkplate.begin(); // Init Inkplate library (you should call this function ONLY ONCE)

    // Init SD card. Display if SD card is init propery or not.
    if (inkplate.sdCardInit())
    {
        // Temporary buffer for file name
        char a[50];
        FsFile f, root = inkplate.getSdFat().open("/");         // Currently open file and the directory we want images from e.g. root /
        while (f.openNext(&root, O_RDONLY) && f.getName(a, 40)) // Iterate over all files in directory
        {
            if (f.isFile() && !f.isHidden() && a[0] != '.' &&                        // Check if current file isn't a directory
                (endsWith(a, ".bmp") || endsWith(a, ".jpg") || endsWith(a, ".png"))) // Check if the file is an image
                Serial.println(files[fileCount++] = String(a));                      // Print the file name and add it to all files
            f.close();                                                               // Close the file
        }

        Serial.println(); // Blank print to separate all files from the chosen one

        if (fileCount != 0) // If there we're any files choose one and draw it
        {
            String s = files[random(0, fileCount)];
            inkplate.image.draw(s, 0, 0);
            Serial.println("Drawn image: ");
            Serial.println(s);
            inkplate.display();
        }
    }
    else
    {
      Serial.println("failed opening sd");
    }

    // Go to sleep for DELAY_MS
    esp_sleep_enable_timer_wakeup(1000L * DELAY_MS);

    // Put SD card into deep sleep
    inkplate.sdCardSleep();

    // Start deep sleep (this function does not return). Program stops here.
    esp_deep_sleep_start();
}

void loop()
{
    // Never here! If you are using deep sleep, the whole program should be in setup() because the board restarts each
    // time. loop() must be empty!
}

Functions used

Inkplate()returns None

Creates the Inkplate object. Inkplate 7SPECTRA has a single six-color mode, so the constructor takes no mode argument (the comment about 1-bit mode comes from other Inkplates).

ReturnsConstructor; no return value.

SdFile()returns None

SdFat: a file object. The sketch creates one as `file` but does not use it; it reads the card with FsFile objects instead.

ReturnsConstructor; no return value.

inkplate.begin()returns void

Initializes the library, the peripherals and the frame buffer. Call it once in setup().

ReturnsNothing.

inkplate.sdCardInit()returns int16_t

Switches on the microSD card's supply, starts its SPI bus and mounts the card.

Returns1 if the card was mounted, 0 if it was not.

inkplate.getSdFat()returns SdFat &

Gives access to the SdFat object the library uses for the card. The sketch opens the root folder of the card with it.

ReturnsA reference to the SdFat object.

f.openNext(&root, O_RDONLY)returns bool

SdFat (FsFile): opens the next entry of the folder. The sketch loops over every entry of the root folder, opened read-only.

Returnstrue if an entry was opened.

f.getName(char *name, size_t size)returns size_t

SdFat (FsFile): copies the name of the open entry into the buffer.

ReturnsThe length of the name, 0 on failure.

f.isFile()returns bool

SdFat (FsFile): whether the entry is a file and not a folder.

Returnstrue for a file.

f.isHidden()returns bool

SdFat (FsFile): whether the entry is hidden. The sketch skips hidden files and names that start with a dot.

Returnstrue for a hidden entry.

f.close()returns bool

SdFat (FsFile): closes the entry.

Returnstrue on success.

random(long min, long max)returns long

Arduino core: a pseudo-random number from min up to, but not including, max. The sketch uses it to choose one of the file names it collected.

ReturnsThe random number.

inkplate.image.draw(const String path, int x, int y, bool dither = 1, bool invert = 0)returns bool

Draws the image file with that name from the microSD card, with its top-left corner at (x, y); the library picks the decoder from the file extension (bmp, jpg or png). The sketch draws the chosen file at (0, 0) with the default dithering on and invert off.

Returnstrue if the image was drawn.

inkplate.display(bool _leaveOn = 0)returns void

Sends the whole frame buffer to the panel and refreshes it.

ReturnsNothing.

esp_sleep_enable_timer_wakeup(uint64_t time_in_us)returns esp_err_t

ESP32 board package: wakes the chip from deep sleep after the given time in microseconds. The sketch passes 1000 × DELAY_MS, which is 5 minutes.

ReturnsESP_OK on success.

inkplate.sdCardSleep()returns void

Sets the card's SPI pins to inputs and switches off the card's supply, to save power in deep sleep.

ReturnsNothing.

esp_deep_sleep_start()returns void

ESP32 board package: enters deep sleep. It does not return; the next wake-up starts the sketch from the beginning, which is why loop() stays empty.

ReturnsDoes not return.

What to expect

The screen shows one of the pictures from the root folder of the card, drawn at the top-left corner. The Serial Monitor at 115200 baud lists the names of all the .bmp, .jpg and .png files it found, one per line, then an empty line, then Drawn image: and the name of the one it drew. The sketch keeps up to 100 names. If the card cannot be mounted, it prints failed opening sd; if the card has no pictures, nothing is drawn. After 5 minutes the board wakes and picks again.

🔗Open the complete example

examples/Inkplate7SPECTRA/Diagnostics/Inkplate7SPECTRA_Gallery

→