Skip to main content

Read a text file from a microSD card

What this example shows​

Opening text.txt on a FAT, FAT32 or exFAT microSD card, reading up to 200 characters and printing them on the display.

Example code​

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

Select Board
Inkplate10_microSD_TXT_Read.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 and also set library into 1 Bit mode (BW)
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.display(); // Put clear image on display
display.setTextSize(5);

// Init SD card. Display if SD card is init propery or not.
if (display.sdCardInit())
{
display.println("SD Card ok! Reading data...");
display.partialUpdate();

// 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();
display.sdCardSleep();
}
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[201]; // 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 > 200)
len = 200; // 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.display(); // Do a full refresh of display
display.sdCardSleep(); // Put sd card in sleep mode
}
}
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.partialUpdate();
display.sdCardSleep();
while (true)
;
}
}

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.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.sdCardInit()returns int16_t

Powers the microSD card and starts the SD interface.

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

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.partialUpdate(bool _forced = false, bool leaveOn = false)returns uint32_t

Refreshes only the parts of the screen that changed, without a full refresh. It works only in `INKPLATE_1BIT` mode.

ReturnsNumber of pixels that changed from black to white, which can leave blur.

Parameters

TypeNameDescription
bool_forcedForces a partial update in cases the library would otherwise do a full one (advanced use with deep sleep). Defaults to false.
boolleaveOnKeeps the panel supply on after the update when true. Defaults to false.
SdFile()returns None

Creates a file object for reading and writing files on the card. `SdFile` is part of the SdFat library bundled with the Inkplate library.

ReturnsConstructor; no return value.

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

Opens a file on the card.

Returns`true` if the file opened.

Parameters

TypeNameDescription
const char *pathFile name or path on the card.
oflag_toflagHow to open the file, for example O_RDONLY. Defaults to O_RDONLY.
display.setCursor(int16_t x, int16_t y)returns void

Sets where the next `print()` starts, in pixels from the top left corner.

ReturnsNothing.

Parameters

TypeNameDescription
int16_txHorizontal position in pixels.
int16_tyVertical position in pixels.
file.fileSize()returns uint64_t

Returns the size of the open file in bytes.

ReturnsFile size in bytes.

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

Reads bytes from the open file into a buffer.

ReturnsNumber of bytes read, or a negative value on error.

Parameters

TypeNameDescription
void *bufBuffer that receives the data.
size_tcountNumber of bytes to read.
display.print(value)returns size_t

Prints text or a number at the cursor. The `print` functions come from the Arduino `Print` class that `Adafruit_GFX` builds on. For a number, an optional second argument sets the decimal places of a float or the number base of an integer.

ReturnsNumber of bytes printed.

Parameters

TypeNameDescription
text, number or charvalueWhat to print.
intsecond argument (optional)Decimal places for a float, or the base for an integer, for example DEC.
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​

The display first shows SD Card ok! Reading data.... Then it clears and prints the first 200 characters of text.txt at text size 5, followed by a full refresh. The file must be named exactly text.txt and sit in the root of the card. If the file does not open, the display shows File open error. If the card does not start, it shows SD Card error! and the sketch stops.

The pinned example folder also contains a sample text.txt, which you can copy to the card.