E2271CS021 EInk Controller API Reference

group group_board_libs

APIs for controlling the E-INK display on the board.

Defines

MTB_E2271CS021_WHITE_BACKGROUND

White background color for mtb_e2271cs021_clear()

MTB_E2271CS021_BLACK_BACKGROUND

Black background color for mtb_e2271cs021_clear()

MTB_E2271CS021_FONT_X

X font start coordinate for mtb_e2271cs021_text_to_frame_buffer()

MTB_E2271CS021_FONT_Y

Y font start coordinate for mtb_e2271cs021_text_to_frame_buffer()

MTB_E2271CS021_IMG_X1

X image start coordinate for mtb_e2271cs021_image_to_frame_buffer()

MTB_E2271CS021_IMG_X2

X image end coordinate for mtb_e2271cs021_image_to_frame_buffer()

MTB_E2271CS021_IMG_Y1

Y image start coordinate for mtb_e2271cs021_image_to_frame_buffer()

MTB_E2271CS021_IMG_Y2

Y image end coordinate for mtb_e2271cs021_image_to_frame_buffer()

MTB_E2271CS021_CLEAR_TO_WHITE

Value to clear an 8 pixel section of the screen to white.

MTB_E2271CS021_CLEAR_TO_BLACK

Value to clear an 8 pixel section of the screen to black.

MTB_E2271CS021_FRAME_SIZE

Number of bytes needed for a full image (pixel count / 8).

MTB_E2271CS021_DEFAULT_TEMP_FACTOR

Default temperature compensation factor used during initalization.

Call mtb_e2271cs021_set_temp_factor() if a different temp is needed.

MTB_E2271CS021_RSLT_ERROR_POWER

Error changing power state for display.

MTB_E2271CS021_DISPLAY_SIZE_X

Number of horizontal pixels in the E-ink display.

MTB_E2271CS021_DISPLAY_SIZE_Y

Number of vertical pixels in the E-ink display.

MTB_E2271CS021_DISPLAY_COLOR_BITS

Number of bits consumed by each pixel for color information.

Enums

enum mtb_e2271cs021_update_t

mtb_e2271cs021_update_t: Different ways the E-INK display can be updated.

Values:

enumerator MTB_E2271CS021_PARTIAL

Update the display with only the changes from previous frame.

enumerator MTB_E2271CS021_FULL_4STAGE

Full update with four stages: Stage 1: update the display with the inverted version of the previous frame.

Stage 2: update the display with an all white frame. Stage 3: update the display with the inverted version of the new frame. Stage 4: update the display with the new frame.

enumerator MTB_E2271CS021_FULL_2STAGE

Full update with only stages 1 and 4.

Stages 2 and 3 are skipped

Functions

cy_rslt_t mtb_e2271cs021_init(const mtb_e2271cs021_pins_t *pins, cyhal_spi_t *spi)

Initialize the E-INK display hardware, starts the required hardware components, and sets a default temperature compensation factor.

Note: This function does not turn on the E-INK display.

Return

CY_RSLT_SUCCESS if properly initialized, else an error indicating what went wrong.

Parameters

  • [in] pins: Pointer to the structure defining the pins used to communicate with the display

  • [in] spi: Pointer to an already intialized SPI block to use for communication. Note: The cable select pin should NOT be initialized as part of the SPI interface. It is toggled manually.

void mtb_e2271cs021_free()

Frees any hardware resources reserved for the E-INK display.

void mtb_e2271cs021_set_temp_factor(int8_t temperature)

Set temperature in order to perform temperature compensation of E-INK parameters.

Note: This function does not turn on the E-INK display.

Parameters

  • [in] temperature: The ambient temperature, in degree C, the display is operating in

cy_rslt_t mtb_e2271cs021_power(bool power)

Turns on/off the E-INK display power.

Note: This function can not be used to clear the E-INK display. The display will retain the previously written frame even when it’s turned off.

Return

CY_RSLT_SUCCESS if properly initialized, else an error indicating what went wrong.

Parameters

  • [in] power: Should the power be turned on to the display

cy_rslt_t mtb_e2271cs021_clear(bool background, bool power_cycle)

Clears the display to all white or all black pixels.

Note1: The E-INK display should be powered on (using mtb_e2271cs021_power()) before calling this function if “power_cycle” is false. Otherwise the display won’t be cleared.

Note2: This function is intended to be called only after a reset/power up. Use mtb_e2271cs021_show_frame() to clear the display if you know the frame that has been written to the display.

Return

CY_RSLT_SUCCESS if properly initialized, else an error indicating what went wrong.

Parameters

cy_rslt_t mtb_e2271cs021_show_frame(uint8_t *prev_frame, uint8_t *new_frame, mtb_e2271cs021_update_t update_type, bool power_cycle)

Updates the E-INK display with the provided frame stored in the flash or RAM.

Afterward the new frame data is copied to the previous frame buffer.

Note: If the previous frame data changes from the actual frame previously written to the display, considerable ghosting may occur.

If the “power_cycle” parameter is false, the E-INK display should be powered on (using mtb_e2271cs021_power()) before calling this function. Otherwise the display won’t be updated.

Return

CY_RSLT_SUCCESS if properly initialized, else an error indicating what went wrong.

Parameters

  • [in] prev_frame: Pointer to the previous frame written on the display

  • [in] new_frame: Pointer to the new frame that need to be written

  • [in] update_type: Full update (2/4 stages) or partial update

  • [in] power_cycle: “true” for automatic power cycle, “false” for manual

void mtb_e2271cs021_image_to_frame_buffer(uint8_t *frame_buffer, uint8_t *image, uint8_t *img_coordinates)

Copies pixel block data between the specified x and y coordinates from an image (typically stored in the flash) to a frame buffer in RAM.

Copying is done at byte level. Pixel level operations are not supported.

This function does not update the E-INK display. After frame buffer update, use mtb_e2271cs021_show_frame() to update the display if required.

NOTE: This is a blocking function that can take as many as MTB_E2271CS021_FRAME_SIZE RAM write cycles to complete.

Return

CY_RSLT_SUCCESS if properly initialized, else an error indicating what went wrong.

Parameters

  • [inout] frame_buffer: Pointer to the frame buffer array in RAM

  • [in] image: Pointer to the image array (typically in flash)

  • [in] img_coordinates: Pointer to a 4-byte array of image coordinates

void mtb_e2271cs021_text_to_frame_buffer(uint8_t *frame_buffer, char *string, mtb_e2271cs021_font_t *font_info, uint8_t *font_coordinates)

Converts a text input (string) to pixel data and stores it at the specified coordinates of a frame buffer.

Notes: This function only supports printable ASCII characters from “!” to “~”

X and Y locations used in this function are font coordinates, rather than the pixel coordinates used in mtb_e2271cs021_image_to_frame_buffer(). See the mtb_e2271cs021_fonts.h for details.

This function does not update the E-INK display. After frame buffer update, use mtb_e2271cs021_show_frame() to update the display if required.

NOTE: This is a blocking function that can take as many as MTB_E2271CS021_FRAME_SIZE RAM write cycles to complete.

Return

CY_RSLT_SUCCESS if properly initialized, else an error indicating what went wrong.

Parameters

  • [inout] frame_buffer: Pointer to the frame buffer array in RAM

  • [in] string: Pointer to the string

  • [in] font_info: Structure that stores font information

  • [in] font_coordinates: Pointer to the 2-byte array containing X and

struct mtb_e2271cs021_font_t
#include <mtb_e2271cs021.h>

Structure that contains font information.

struct mtb_e2271cs021_pins_t
#include <mtb_e2271cs021_display.h>

Configuration structure defining the necessary pins to communicate with the E-ink display.