Read a text file from a microSD card

What this example shows

Open the file text.txt on a microSD card and print its content on the screen. If the card cannot be initialized, the screen shows SD Card error!, and if the file cannot be opened, it shows File open error.

Put a file named text.txt in the root folder of the card before you insert it. The sketch's own comments ask for a file of at most 200 characters, but the code reads up to 3000 bytes.

Example code

Select Board

Inkplate7SPECTRA_SD_TXT_Read.ino

#include "Inkplate.h" //Include Inkplate library to the sketch
Inkplate display;     // Create an object on Inkplate library
SdFile file;          // Create SdFile object used for accessing files on SD card

void setup()
{
    display.begin();        // Init Inkplate library (you should call this function ONLY ONCE)
    display.clearDisplay(); // Clear frame buffer of display
    display.setCursor(0, 0);
    display.setTextColor(INKPLATE_BLACK);
    display.setTextSize(1);
    // Init SD card. Display if SD card is init propery or not.
    if (display.sdCardInit())
    {
        // Try to load text with max lenght of 200 chars.
        if (!file.open("/text.txt", O_RDONLY))
        { // If it fails to open, send error message to display, otherwise read the file.
            display.println("File open error");
            display.display();
        }
        else
        {
            display.clearDisplay();    // Clear everything that is stored in frame buffer of epaper
            display.setCursor(0, 0);   // Set print position at the begining of the screen
            char text[3001];           // Array where data from SD card is stored (max 200 chars here)
            int len = file.fileSize(); // Read how big is file that we are opening
            if (len > 3000)
                len = 3000;        // If it's more than 200 bytes (200 chars), limit to max 200 bytes
            file.read(text, len);  // Read data from file and save it in text array
            text[len] = 0;         // Put null terminating char at the and of data
            display.print(text);   // Print data/text
            display.sdCardSleep(); // Put sd card in sleep mode
            display.display();     // Do a full refresh of display
        }
    }
    else
    { // If card init was not successful, display error on screen, put sd card in sleep mode, and stop the program
      // (using infinite loop)
        display.println("SD Card error!");
        display.display();
        display.sdCardSleep();
        while (true)
            ;
    }
}

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

This example also uses SdFile, a file class from the SdFat code bundled with the Inkplate library (it is in the library's src/features/SdFat folder). Its functions below are described as the sketch uses them.

Functions used

Inkplate()returns None

Creates the Inkplate object. Inkplate 7SPECTRA has a single six-color mode, so the constructor takes no mode argument.

ReturnsConstructor; no return value.

SdFilereturns None

File class from the SdFat code bundled with the Inkplate library. The sketch creates one object, file, to open and read the file on the card.

ReturnsType; no return value.

display.begin()returns void

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

ReturnsNothing.

display.clearDisplay()returns void

Fills the frame buffer with white. It does not change the panel.

ReturnsNothing.

display.setCursor(int16_t x, int16_t y)returns void

Sets where the next printed text starts, here the top left corner.

ReturnsNothing.

display.setTextColor(uint16_t c)returns void

Sets the text color, here black.

ReturnsNothing.

display.setTextSize(uint8_t s)returns void

Sets the text magnification, here 1.

ReturnsNothing.

display.sdCardInit()returns int16_t

Initializes the microSD card so files on it can be opened.

ReturnsNon-zero when the card was initialized; the sketch treats 0 as an error.

file.open(const char *path, oflag_t oflag)returns bool

Opens a file on the card. The sketch opens /text.txt with O_RDONLY, read only.

Returnstrue if the file was opened.

file.fileSize()returns uint32_t

Returns the size of the open file in bytes. The sketch limits what it reads to 3000 bytes.

ReturnsSize of the file in bytes.

file.read(void *buf, size_t count)returns int

Reads up to count bytes from the open file into buf.

ReturnsNumber of bytes read.

display.print(value)returns size_t

Prints text into the frame buffer, like Serial.print().

ReturnsNumber of bytes printed.

display.println(value)returns size_t

Prints text into the frame buffer and moves to the next line, like Serial.println().

ReturnsNumber of bytes printed.

display.sdCardSleep()returns void

Puts the microSD card in sleep mode.

ReturnsNothing.

display.display(bool _leaveOn = 0)returns void

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

ReturnsNothing.

What to expect

The content of text.txt appears on the screen in black, starting at the top left corner. With no card or a card that cannot be read, the screen shows SD Card error!; with a card but no text.txt, it shows File open error. The sketch prints nothing to the Serial Monitor.

🔗Open the complete example

examples/Inkplate7SPECTRA/Advanced/SD/Inkplate7SPECTRA_SD_TXT_Read

→