E2271CS021 EInk Controller (display-eink-e2271cs021)
E-INK

General Description

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

Data Structures

struct  mtb_e2271cs021_font_t
 Structure that contains font information. More...
 
struct  mtb_e2271cs021_pins_t
 Configuration structure defining the necessary pins to communicate with the E-ink display. More...
 

Macros

#define MTB_E2271CS021_WHITE_BACKGROUND   (true)
 White background color for mtb_e2271cs021_clear()
 
#define MTB_E2271CS021_BLACK_BACKGROUND   (false)
 Black background color for mtb_e2271cs021_clear()
 
#define MTB_E2271CS021_FONT_X   (0x00)
 X font start coordinate for mtb_e2271cs021_text_to_frame_buffer()
 
#define MTB_E2271CS021_FONT_Y   (0x01)
 Y font start coordinate for mtb_e2271cs021_text_to_frame_buffer()
 
#define MTB_E2271CS021_IMG_X1   (0x00)
 X image start coordinate for mtb_e2271cs021_image_to_frame_buffer()
 
#define MTB_E2271CS021_IMG_X2   (0x01)
 X image end coordinate for mtb_e2271cs021_image_to_frame_buffer()
 
#define MTB_E2271CS021_IMG_Y1   (0x02)
 Y image start coordinate for mtb_e2271cs021_image_to_frame_buffer()
 
#define MTB_E2271CS021_IMG_Y2   (0x03)
 Y image end coordinate for mtb_e2271cs021_image_to_frame_buffer()
 
#define MTB_E2271CS021_CLEAR_TO_WHITE   (0xFF)
 Value to clear an 8 pixel section of the screen to white. More...
 
#define MTB_E2271CS021_CLEAR_TO_BLACK   (0x00)
 Value to clear an 8 pixel section of the screen to black. More...
 
#define MTB_E2271CS021_FRAME_SIZE
 Number of bytes needed for a full image (pixel count / 8). More...
 
#define MTB_E2271CS021_DEFAULT_TEMP_FACTOR   (20)
 Default temperature compensation factor used during initalization. More...
 
#define MTB_E2271CS021_RSLT_ERROR_POWER   (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_HARDWARE_E2271CS021, 0))
 Error changing power state for display. More...
 
#define MTB_E2271CS021_DISPLAY_SIZE_X   (264u)
 Number of horizontal pixels in the E-ink display.
 
#define MTB_E2271CS021_DISPLAY_SIZE_Y   (176u)
 Number of vertical pixels in the E-ink display.
 
#define MTB_E2271CS021_DISPLAY_COLOR_BITS   (1u)
 Number of bits consumed by each pixel for color information.
 

Enumerations

enum  mtb_e2271cs021_update_t {
  MTB_E2271CS021_PARTIAL,
  MTB_E2271CS021_FULL_4STAGE,
  MTB_E2271CS021_FULL_2STAGE
}
 Different ways the E-INK display can be updated. More...
 

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. More...
 
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. More...
 
cy_rslt_t mtb_e2271cs021_power (bool power)
 Turns on/off the E-INK display power. More...
 
cy_rslt_t mtb_e2271cs021_clear (bool background, bool power_cycle)
 Clears the display to all white or all black pixels. More...
 
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. More...
 
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. More...
 
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. More...
 

Data Structure Documentation

◆ mtb_e2271cs021_font_t

struct mtb_e2271cs021_font_t
Data Fields
uint8_t * fontData Pointer to the font pixel data array.
uint8_t xOffset X offset of the font in pixels.
uint8_t yOffset Y offset of the font in pixels.
uint8_t xSize X size of one font data in bytes.
uint8_t ySize Y size of one font data in bytes.
uint8_t xSpan Number of characters that fit the screen horizontally.
uint8_t ySpan Number of characters that fit the screen vertically.
bool color Color of the font : true = black characters in white background, false = white characters in black background.

◆ mtb_e2271cs021_pins_t

struct mtb_e2271cs021_pins_t
Data Fields
cyhal_gpio_t spi_mosi SPI MOSI pin.
cyhal_gpio_t spi_miso SPI MISO pin.
cyhal_gpio_t spi_sclk SPI SCLK pin.
cyhal_gpio_t spi_cs SPI CS pin.
cyhal_gpio_t reset GPIO Reset pin.
cyhal_gpio_t busy GPIO Busy pin.
cyhal_gpio_t discharge GPIO Discharge pin.
cyhal_gpio_t enable GPIO Enable pin.
cyhal_gpio_t border GPIO Border pin.
cyhal_gpio_t io_enable GPIO IO Enable pin.

Macro Definition Documentation

◆ MTB_E2271CS021_CLEAR_TO_WHITE

#define MTB_E2271CS021_CLEAR_TO_WHITE   (0xFF)

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

◆ MTB_E2271CS021_CLEAR_TO_BLACK

#define MTB_E2271CS021_CLEAR_TO_BLACK   (0x00)

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

◆ MTB_E2271CS021_FRAME_SIZE

#define MTB_E2271CS021_FRAME_SIZE
Value:
MTB_E2271CS021_DISPLAY_SIZE_Y) / 8)
#define MTB_E2271CS021_DISPLAY_SIZE_X
Number of horizontal pixels in the E-ink display.
Definition: mtb_e2271cs021_display.h:45

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

◆ MTB_E2271CS021_DEFAULT_TEMP_FACTOR

#define MTB_E2271CS021_DEFAULT_TEMP_FACTOR   (20)

Default temperature compensation factor used during initalization.

Call mtb_e2271cs021_set_temp_factor() if a different temp is needed.

◆ MTB_E2271CS021_RSLT_ERROR_POWER

#define MTB_E2271CS021_RSLT_ERROR_POWER   (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_HARDWARE_E2271CS021, 0))

Error changing power state for display.

Enumeration Type Documentation

◆ mtb_e2271cs021_update_t

Different ways the E-INK display can be updated.

Enumerator
MTB_E2271CS021_PARTIAL 

Update the display with only the changes from previous frame.

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.

MTB_E2271CS021_FULL_2STAGE 

Full update with only stages 1 and 4.

Stages 2 and 3 are skipped

Function Documentation

◆ mtb_e2271cs021_init()

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.

Parameters
[in]pinsPointer to the structure defining the pins used to communicate with the display
[in]spiPointer 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.
Returns
CY_RSLT_SUCCESS if properly initialized, else an error indicating what went wrong.

◆ mtb_e2271cs021_set_temp_factor()

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]temperatureThe ambient temperature, in degree C, the display is operating in

◆ mtb_e2271cs021_power()

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.

Parameters
[in]powerShould the power be turned on to the display
Returns
CY_RSLT_SUCCESS if properly initialized, else an error indicating what went wrong.

◆ mtb_e2271cs021_clear()

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.

Parameters
[in]backgroundMTB_E2271CS021_WHITE_BACKGROUND or MTB_E2271CS021_BLACK_BACKGROUND
[in]power_cycletrue for automatic power cycle. False otherwise
Returns
CY_RSLT_SUCCESS if properly initialized, else an error indicating what went wrong.

◆ mtb_e2271cs021_show_frame()

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.

Parameters
[in]prev_framePointer to the previous frame written on the display
[in]new_framePointer to the new frame that need to be written
[in]update_typeFull update (2/4 stages) or partial update
[in]power_cycle"true" for automatic power cycle, "false" for manual
Returns
CY_RSLT_SUCCESS if properly initialized, else an error indicating what went wrong.

◆ mtb_e2271cs021_image_to_frame_buffer()

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.

Parameters
[in,out]frame_bufferPointer to the frame buffer array in RAM
[in]imagePointer to the image array (typically in flash)
[in]img_coordinatesPointer to a 4-byte array of image coordinates
Returns
CY_RSLT_SUCCESS if properly initialized, else an error indicating what went wrong.

◆ mtb_e2271cs021_text_to_frame_buffer()

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.

Parameters
[in,out]frame_bufferPointer to the frame buffer array in RAM
[in]stringPointer to the string
[in]font_infoStructure that stores font information
[in]font_coordinatesPointer to the 2-byte array containing X and
Returns
CY_RSLT_SUCCESS if properly initialized, else an error indicating what went wrong.