Skip to main content

Draw from two tasks with the display mutex

What this example shows​

Running two FreeRTOS tasks that each draw and partially update their own half of the screen. Each task takes the display mutex with displayLock() before it touches the frame buffer or calls partialUpdate(), so their writes do not interleave and corrupt the picture.

Example code​

Trimmed from the pinned example: the file header comment is removed and the board check message is shortened to plain ASCII. The rest of the code is unchanged.

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

#include "Inkplate.h"

Inkplate display(INKPLATE_1BIT);

static const int SQ = 140;
static const int DY = 6;

void taskLeft(void *pvParameters)
{
int y = 60, dy = DY;
while (true)
{
display.displayLock();
display.fillRect(0, 0, 600, display.height(), WHITE);
display.fillRect(230, y, SQ, SQ, BLACK);
display.partialUpdate(false, true);
display.displayUnlock();

y += dy;
if (y < 0 || y + SQ > display.height())
dy = -dy;
vTaskDelay(pdMS_TO_TICKS(150));
}
}

void taskRight(void *pvParameters)
{
int y = display.height() / 2, dy = -DY;
while (true)
{
display.displayLock();
display.fillRect(600, 0, 600, display.height(), WHITE);
display.fillRect(830, y, SQ, SQ, BLACK);
display.partialUpdate(false, true);
display.displayUnlock();

y += dy;
if (y < 0 || y + SQ > display.height())
dy = -dy;
vTaskDelay(pdMS_TO_TICKS(150));
}
}

void setup()
{
Serial.begin(115200);
display.begin();
display.clearDisplay();
display.drawFastVLine(600, 0, display.height(), BLACK);
display.display();

xTaskCreatePinnedToCore(taskLeft, "TaskLeft", 4096, NULL, 1, NULL, 0);
xTaskCreatePinnedToCore(taskRight, "TaskRight", 4096, NULL, 1, NULL, 1);
}

void loop()
{
vTaskDelay(pdMS_TO_TICKS(1000));
}

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.displayLock()returns void

Takes the display mutex. Call it before a task touches the frame buffer or refreshes the panel, and always call the matching `displayUnlock()` afterwards.

ReturnsNothing.

display.fillRect(int16_t x, int16_t y, int16_t w, int16_t h, uint16_t color)returns void

Draws a filled rectangle into the frame buffer.

ReturnsNothing.

Parameters

TypeNameDescription
int16_txLeft edge in pixels.
int16_tyTop edge in pixels.
int16_twWidth in pixels.
int16_thHeight in pixels.
uint16_tcolorFill color, for example BLACK.
display.height()returns int16_t

Returns the height of the display in pixels.

ReturnsDisplay height in pixels.

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.
display.displayUnlock()returns void

Releases the display mutex taken with `displayLock()`.

ReturnsNothing.

vTaskDelay(TickType_t ticks)returns void

FreeRTOS function that puts the calling task to sleep so other tasks can run. The example converts milliseconds to ticks with `pdMS_TO_TICKS()`.

ReturnsNothing.

Parameters

TypeNameDescription
TickType_tticksDelay in FreeRTOS ticks.
Serial.begin(unsigned long baud)returns void

Arduino function that starts the serial port.

ReturnsNothing.

Parameters

TypeNameDescription
unsigned longbaudBaud rate. The example uses 115200.
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.drawFastVLine(int16_t x, int16_t y, int16_t h, uint16_t color)returns void

Draws a vertical line into the frame buffer.

ReturnsNothing.

Parameters

TypeNameDescription
int16_txHorizontal position in pixels.
int16_tyStart position in pixels.
int16_thLine length in pixels.
uint16_tcolorLine color, for example BLACK.
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.
xTaskCreatePinnedToCore(TaskFunction_t task, const char *name, uint32_t stackDepth, void *params, UBaseType_t priority, TaskHandle_t *handle, BaseType_t coreId)returns BaseType_t

FreeRTOS function from the ESP32 Arduino core that starts a task on a chosen CPU core. The example starts one task on core 0 and one on core 1, each with a 4096 byte stack and priority 1.

ReturnsThe example does not use the return value.

Parameters

TypeNameDescription
TaskFunction_ttaskFunction the task runs.
const char *nameTask name.
uint32_tstackDepthStack size in bytes.
void *paramsValue passed to the task. The example passes NULL.
UBaseType_tpriorityTask priority.
TaskHandle_t *handleReceives the task handle. The example passes NULL.
BaseType_tcoreIdCPU core to run on, 0 or 1.

What to expect​

A vertical line splits the screen at x = 600. A black square bounces up and down in the left half, and another bounces in the right half, each moving on its own. Neither square disturbs the other half.

To see what happens without the mutex, comment out the displayLock() and displayUnlock() calls, as the example header suggests.