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_X * \
                                              MTB_E2271CS021_DISPLAY_SIZE_Y) / 8)

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

enum 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]	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.

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]

temperature

The 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]

power

Should 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]	background	MTB_E2271CS021_WHITE_BACKGROUND or MTB_E2271CS021_BLACK_BACKGROUND
[in]	power_cycle	true 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_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

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_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

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_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

Returns

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