Public interface for the ST7789V3 display driver. More...

Data Structures
struct	ST7789V3_Config
	Runtime configuration and hardware binding for one display instance. More...

Enums and Types
Public state, mode, and callback types used by the driver.
enum	GPIO_Pinstate { HIGH = 1 , LOW = 0 }
	Logical output level used by GPIO control callbacks. More...

enum	Trans_State { DATA = 1 , CMD = 0 }
	Select whether the current SPI byte stream is command or pixel/data content. More...

enum	Color_Mode { bit_12 = 0x03U , bit_16 = 0x05U , bit_18 = 0x06U }
	Pixel format written to the display controller. More...

enum	Inversion_Mode { INVON = 1 , INVOFF = 0 }
	Display inversion mode selection. More...

enum	Sleep_State { Asleep = 0 , Awake = 1 }
	Sleep state selection for the display. More...

enum	Orientation { Portrait = 0 , Landscape = 1 , Portrait_Inverted = 2 , Landscape_Inverted = 3 }
	Logical display orientation used by SetRotation. More...

enum	ST7789V3_State { ST7789_STATE_READY = 0 , ST7789_STATE_BUSY = 1 , ST7789_STATE_ERROR = 2 }
	Driver transfer state used for DMA operations. More...

typedef struct ST7789V3_Config	ST7789V3_Config
	Forward declaration of the driver configuration structure.

typedef void(*	ST7789V3_Callback) (ST7789V3_Config config, void user_data)
	Callback signature used for DMA completion and error notifications.

Core Control API
Functions for initialization and controller-level display control.
void	ST7789V3_init (ST7789V3_Config *config)
	Initialize the display and apply the default startup sequence.

int8_t	SetWindow (ST7789V3_Config *config, uint16_t X_Start, uint16_t X_End, uint16_t Y_Start, uint16_t Y_End)
	Set the active drawing window on the display.

int8_t	SetColorMode (ST7789V3_Config *config, Color_Mode bitdepth)
	Set the controller pixel format.

void	DISPLAYON (ST7789V3_Config *config)
	Enable display output.

void	DISPLAYOFF (ST7789V3_Config *config)
	Disable display output.

void	HardReset (ST7789V3_Config *config)
	Toggle the hardware reset line using the driver's reset sequence.

void	InvertDisplay (ST7789V3_Config *config, Inversion_Mode Inversion)
	Enable or disable display inversion.

void	SleepMode (ST7789V3_Config *config, Sleep_State sleepstate)
	Put the display into sleep mode or wake it up.

Drawing API
Functions for rendering pixels, text, and basic shapes.
int8_t	DrawPixel (ST7789V3_Config *config, uint16_t x, uint16_t y, uint32_t hexcolor)
	Draw a single pixel using a 24-bit RGB888 input color.

void	DrawChar (ST7789V3_Config config, uint16_t x, uint16_t y, char user_char, uint32_t hexcolor, const FontDef font)
	Draw a single printable ASCII character.

void	FillScreen (ST7789V3_Config *config, uint32_t hexcolor)
	Fill the entire display with a single color.

void	SetRotation (ST7789V3_Config *config, Orientation orientation)
	Change the logical display rotation.

void	DrawString (ST7789V3_Config config, uint16_t x, uint16_t y, const char str, uint32_t hexcolor, const FontDef *font)
	Draw a null-terminated string.

void	DrawLine (ST7789V3_Config *config, uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1, uint32_t hexcolor)
	Draw a line between two points using Bresenham's algorithm.

void	DrawRectangle (ST7789V3_Config *config, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint32_t hexcolor)
	Draw an unfilled rectangle outline.

void	DrawFilledRectangle (ST7789V3_Config *config, uint16_t x, uint16_t y, uint16_t width, uint16_t height, uint32_t hexcolor)
	Draw a filled rectangle.

void	DrawCircle (ST7789V3_Config *config, uint16_t x_center, uint16_t y_center, uint16_t radius, uint32_t hexcolor)
	Draw a circle outline using the midpoint circle algorithm.

void	DrawFilledCircle (ST7789V3_Config *config, uint16_t x_center, uint16_t y_center, uint16_t radius, uint32_t hexcolor)
	Draw a filled circle using the midpoint circle algorithm.

DMA API
Optional non-blocking transfer helpers.
int8_t	ST7789V3_WriteBuffer_DMA (ST7789V3_Config config, const uint8_t buf, uint16_t len)
	Start a non-blocking DMA write of pixel data to the display.

void	ST7789V3_DMA_Complete (ST7789V3_Config *config)
	Finish a successful DMA transfer and run the completion callback.

void	ST7789V3_DMA_Error (ST7789V3_Config *config)
	Finish a failed DMA transfer and run the error callback.

Controller Command Macros
Controller command values used by the ST7789V3 display.
#define	ST7789V3_rst

#define	ST7789V3_backlight

#define	Sleep_Out 0x11U

#define	Sleep_In 0x10U

#define	Display_On_Register 0x29U

#define	Display_Off_Register 0x28U

#define	CASET 0x2AU

#define	RASET 0x2BU

#define	RAMWR 0x2CU

#define	COLMODE 0x3AU

#define	MADCTL 0x36U

#define	INVOFF_REG 0x20U

#define	INVON_REG 0x21U

Color Constants
Predefined 24-bit RGB888 colors in 0xRRGGBB format.
#define	BLACK 0x000000U

#define	WHITE 0xFFFFFFU

#define	RED 0xFF0000U

#define	GREEN 0x00FF00U

#define	BLUE 0x0000FFU

#define	YELLOW 0xFFFF00U

#define	CYAN 0x00FFFFU

#define	MAGENTA 0xFF00FFU

#define	ORANGE 0xFF6A00U

#define	PINK 0xFF69B4U

#define	PURPLE 0x800080U

#define	LIME 0x32FF00U

#define	NAVY 0x000080U

#define	DARK_GREEN 0x006400U

#define	MAROON 0x800000U

#define	OLIVE 0x808000U

#define	TEAL 0x008080U

#define	SILVER 0xC0C0C0U

#define	GRAY 0x808080U

#define	DARK_GRAY 0x404040U

#define	LIGHT_GRAY 0xD3D3D3U

#define	GOLD 0xFFD700U

#define	SKY_BLUE 0x87CEEBU

Detailed Description

Public interface for the ST7789V3 display driver.

Macro Definition Documentation

◆ BLACK

#define BLACK 0x000000U

Black in RGB888 format.

◆ BLUE

#define BLUE 0x0000FFU

Blue in RGB888 format.

◆ CASET

#define CASET 0x2AU

Column address set command.

◆ COLMODE

#define COLMODE 0x3AU

Interface pixel format command.

◆ CYAN

#define CYAN 0x00FFFFU

Cyan in RGB888 format.

◆ DARK_GRAY

#define DARK_GRAY 0x404040U

Dark gray in RGB888 format.

◆ DARK_GREEN

#define DARK_GREEN 0x006400U

Dark green in RGB888 format.

◆ Display_Off_Register

#define Display_Off_Register 0x28U

Turn the display output off.

◆ Display_On_Register

#define Display_On_Register 0x29U

Turn the display output on.

◆ GOLD

#define GOLD 0xFFD700U

Gold in RGB888 format.

◆ GRAY

#define GRAY 0x808080U

Gray in RGB888 format.

◆ GREEN

#define GREEN 0x00FF00U

Green in RGB888 format.

◆ INVOFF_REG

#define INVOFF_REG 0x20U

Disable display color inversion.

◆ INVON_REG

#define INVON_REG 0x21U

Enable display color inversion.

◆ LIGHT_GRAY

#define LIGHT_GRAY 0xD3D3D3U

Light gray in RGB888 format.

◆ LIME

#define LIME 0x32FF00U

Lime in RGB888 format.

◆ MADCTL

#define MADCTL 0x36U

Memory data access control command.

◆ MAGENTA

#define MAGENTA 0xFF00FFU

Magenta in RGB888 format.

◆ MAROON

#define MAROON 0x800000U

Maroon in RGB888 format.

◆ NAVY

#define NAVY 0x000080U

Navy in RGB888 format.

◆ OLIVE

#define OLIVE 0x808000U

Olive in RGB888 format.

◆ ORANGE

#define ORANGE 0xFF6A00U

Orange in RGB888 format.

◆ PINK

#define PINK 0xFF69B4U

Pink in RGB888 format.

◆ PURPLE

#define PURPLE 0x800080U

Purple in RGB888 format.

◆ RAMWR

#define RAMWR 0x2CU

Memory write command.

◆ RASET

#define RASET 0x2BU

Row address set command.

◆ RED

#define RED 0xFF0000U

Red in RGB888 format.

◆ SILVER

#define SILVER 0xC0C0C0U

Silver in RGB888 format.

◆ SKY_BLUE

#define SKY_BLUE 0x87CEEBU

Sky blue in RGB888 format.

◆ Sleep_In

#define Sleep_In 0x10U

Enter sleep mode command.

◆ Sleep_Out

#define Sleep_Out 0x11U

Exit sleep mode command.

◆ ST7789V3_backlight

#define ST7789V3_backlight

Reserved placeholder for board-specific backlight mapping.

◆ ST7789V3_rst

#define ST7789V3_rst

Reserved placeholder for board-specific reset mapping.

◆ TEAL

#define TEAL 0x008080U

Teal in RGB888 format.

◆ WHITE

#define WHITE 0xFFFFFFU

White in RGB888 format.

◆ YELLOW

#define YELLOW 0xFFFF00U

Yellow in RGB888 format.

Typedef Documentation

◆ ST7789V3_Callback

typedef void(* ST7789V3_Callback) (ST7789V3_Config *config, void *user_data)

Callback signature used for DMA completion and error notifications.

Parameters

config	Pointer to the active driver configuration.
user_data	Application-defined context pointer from ST7789V3_Config::callback_user_data.

Enumeration Type Documentation

◆ Color_Mode

enum Color_Mode

Pixel format written to the display controller.

Enumerator
bit_12	12-bit color mode.
bit_16	16-bit color mode.
bit_18	18-bit color mode.

◆ GPIO_Pinstate

enum GPIO_Pinstate

Logical output level used by GPIO control callbacks.

Enumerator
HIGH	Drive the output high.
LOW	Drive the output low.

◆ Inversion_Mode

enum Inversion_Mode

Display inversion mode selection.

Enumerator
INVON	Enable inversion.
INVOFF	Disable inversion.

◆ Orientation

enum Orientation

Logical display orientation used by SetRotation.

Enumerator
Portrait	Upright portrait orientation.
Landscape	90-degree landscape orientation.
Portrait_Inverted	180-degree portrait orientation.
Landscape_Inverted	270-degree landscape orientation.

◆ Sleep_State

enum Sleep_State

Sleep state selection for the display.

Enumerator
Asleep	Request sleep mode.
Awake	Request normal awake mode.

◆ ST7789V3_State

enum ST7789V3_State

Driver transfer state used for DMA operations.

Enumerator
ST7789_STATE_READY	Ready to start a new transfer.
ST7789_STATE_BUSY	A transfer is currently in progress.
ST7789_STATE_ERROR	The last DMA transfer ended in an error state.

◆ Trans_State

enum Trans_State

Select whether the current SPI byte stream is command or pixel/data content.

Enumerator
DATA	Treat the transfer as display data.
CMD	Treat the transfer as a controller command.

Function Documentation

◆ DISPLAYOFF()

void DISPLAYOFF ( ST7789V3_Config * config )

Disable display output.

Parameters

config Pointer to the active driver configuration.

References Display_Off_Register.

◆ DISPLAYON()

void DISPLAYON ( ST7789V3_Config * config )

Enable display output.

Parameters

config Pointer to the active driver configuration.

References Display_On_Register.

Referenced by ST7789V3_init().

◆ DrawChar()

void DrawChar	(	ST7789V3_Config *	config,
		uint16_t	x,
		uint16_t	y,
		char	user_char,
		uint32_t	hexcolor,
		const FontDef *	font
	)

Draw a single printable ASCII character.

Parameters

config	Pointer to the active driver configuration.
x	Leftmost X position of the character.
y	Topmost Y position of the character.
user_char	Printable ASCII character to draw.
hexcolor	Foreground color in `0xRRGGBB` RGB888 format.
font	Pointer to the font definition used for rendering.

Note: Characters outside the printable ASCII range are ignored.

References FontDef::bytes_per_row, FontDef::data, DrawPixel(), FontDef::height, and FontDef::width.

Referenced by DrawString().

◆ DrawCircle()

void DrawCircle	(	ST7789V3_Config *	config,
		uint16_t	x_center,
		uint16_t	y_center,
		uint16_t	radius,
		uint32_t	hexcolor
	)

Draw a circle outline using the midpoint circle algorithm.

Parameters

config	Pointer to the active driver configuration.
x_center	Center X coordinate.
y_center	Center Y coordinate.
radius	Circle radius in pixels.
hexcolor	Outline color in `0xRRGGBB` RGB888 format.

References DrawPixel().

◆ DrawFilledCircle()

void DrawFilledCircle	(	ST7789V3_Config *	config,
		uint16_t	x_center,
		uint16_t	y_center,
		uint16_t	radius,
		uint32_t	hexcolor
	)

Draw a filled circle using the midpoint circle algorithm.

Parameters

config	Pointer to the active driver configuration.
x_center	Center X coordinate.
y_center	Center Y coordinate.
radius	Circle radius in pixels.
hexcolor	Fill color in `0xRRGGBB` RGB888 format.

◆ DrawFilledRectangle()

void DrawFilledRectangle	(	ST7789V3_Config *	config,
		uint16_t	x,
		uint16_t	y,
		uint16_t	width,
		uint16_t	height,
		uint32_t	hexcolor
	)

Draw a filled rectangle.

Parameters

config	Pointer to the active driver configuration.
x	Top-left X coordinate.
y	Top-left Y coordinate.
width	Rectangle width in pixels.
height	Rectangle height in pixels.
hexcolor	Fill color in `0xRRGGBB` RGB888 format.

References ST7789V3_Config::LCD_Height, and ST7789V3_Config::LCD_Width.

◆ DrawLine()

void DrawLine	(	ST7789V3_Config *	config,
		uint16_t	x0,
		uint16_t	y0,
		uint16_t	x1,
		uint16_t	y1,
		uint32_t	hexcolor
	)

Draw a line between two points using Bresenham's algorithm.

Parameters

config	Pointer to the active driver configuration.
x0	Starting X coordinate.
y0	Starting Y coordinate.
x1	Ending X coordinate.
y1	Ending Y coordinate.
hexcolor	Line color in `0xRRGGBB` RGB888 format.

References DrawPixel().

Referenced by DrawRectangle().

◆ DrawPixel()

int8_t DrawPixel	(	ST7789V3_Config *	config,
		uint16_t	x,
		uint16_t	y,
		uint32_t	hexcolor
	)

Draw a single pixel using a 24-bit RGB888 input color.

Parameters

config	Pointer to the active driver configuration.
x	Pixel X coordinate.
y	Pixel Y coordinate.
hexcolor	Color in `0xRRGGBB` RGB888 format.

Returns: 0 on success, or -1 if the coordinates are outside the current logical display bounds.

References DATA, HIGH, ST7789V3_Config::LCD_Height, ST7789V3_Config::LCD_Width, LOW, ST7789V3_Config::set_cs, ST7789V3_Config::set_dc, SetWindow(), and ST7789V3_Config::spi_write.

Referenced by DrawChar(), DrawCircle(), and DrawLine().

◆ DrawRectangle()

void DrawRectangle	(	ST7789V3_Config *	config,
		uint16_t	x,
		uint16_t	y,
		uint16_t	width,
		uint16_t	height,
		uint32_t	hexcolor
	)

Draw an unfilled rectangle outline.

Parameters

config	Pointer to the active driver configuration.
x	Top-left X coordinate.
y	Top-left Y coordinate.
width	Rectangle width in pixels.
height	Rectangle height in pixels.
hexcolor	Outline color in `0xRRGGBB` RGB888 format.

References DrawLine(), ST7789V3_Config::LCD_Height, and ST7789V3_Config::LCD_Width.

◆ DrawString()

void DrawString	(	ST7789V3_Config *	config,
		uint16_t	x,
		uint16_t	y,
		const char *	str,
		uint32_t	hexcolor,
		const FontDef *	font
	)

Draw a null-terminated string.

Parameters

config	Pointer to the active driver configuration.
x	Starting X position of the first character.
y	Starting Y position of the first character.
str	Null-terminated string to draw.
hexcolor	Text color in `0xRRGGBB` RGB888 format.
font	Pointer to the font definition used for rendering.

Note: Supports \n for newline, \r for carriage return, and simple line wrapping when the next character would exceed the display width.

References DrawChar(), FontDef::height, ST7789V3_Config::LCD_Width, and FontDef::width.

◆ FillScreen()

void FillScreen	(	ST7789V3_Config *	config,
		uint32_t	hexcolor
	)

Fill the entire display with a single color.

Parameters

config	Pointer to the active driver configuration.
hexcolor	Fill color in `0xRRGGBB` RGB888 format.

Fill the entire display with a single color.

References ST7789V3_Config::LCD_Height, ST7789V3_Config::LCD_Width, and SetWindow().

◆ HardReset()

void HardReset ( ST7789V3_Config * config )

Toggle the hardware reset line using the driver's reset sequence.

Parameters

config Pointer to the active driver configuration.

Toggle the hardware reset line using the driver's reset sequence.

References ST7789V3_Config::delay_ms, HIGH, LOW, and ST7789V3_Config::set_rst.

◆ InvertDisplay()

void InvertDisplay	(	ST7789V3_Config *	config,
		Inversion_Mode	Inversion
	)

Enable or disable display inversion.

Parameters

config	Pointer to the active driver configuration.
Inversion	Requested inversion mode.

References ST7789V3_Config::Inversion_Mode, INVOFF_REG, INVON, and INVON_REG.

Referenced by ST7789V3_init().

◆ SetColorMode()

int8_t SetColorMode	(	ST7789V3_Config *	config,
		Color_Mode	bitdepth
	)

Set the controller pixel format.

Parameters

config	Pointer to the active driver configuration.
bitdepth	Requested color mode.

Returns: 0 on success.

Note: The selected mode is also cached in ST7789V3_Config::Bit_Depth.

References ST7789V3_Config::Bit_Depth, and COLMODE.

Referenced by ST7789V3_init().

◆ SetRotation()

void SetRotation	(	ST7789V3_Config *	config,
		Orientation	orientation
	)

Change the logical display rotation.

Parameters

config	Pointer to the active driver configuration.
orientation	Requested orientation.

Note: This function updates the cached width, height, and controller offsets to match the selected orientation.

References ST7789V3_Config::Col_Offset, Landscape, Landscape_Inverted, ST7789V3_Config::LCD_Height, ST7789V3_Config::LCD_Width, MADCTL, Portrait, Portrait_Inverted, and ST7789V3_Config::Row_Offset.

◆ SetWindow()

int8_t SetWindow	(	ST7789V3_Config *	config,
		uint16_t	X_Start,
		uint16_t	X_End,
		uint16_t	Y_Start,
		uint16_t	Y_End
	)

Set the active drawing window on the display.

Parameters

config	Pointer to the active driver configuration.
X_Start	Inclusive starting column in logical display coordinates.
X_End	Inclusive ending column in logical display coordinates.
Y_Start	Inclusive starting row in logical display coordinates.
Y_End	Inclusive ending row in logical display coordinates.

Returns: 0 on success.

Note: This function applies the configured row and column offsets before the address values are written to the controller.

References CASET, CMD, ST7789V3_Config::Col_Offset, DATA, HIGH, LOW, RAMWR, RASET, ST7789V3_Config::Row_Offset, ST7789V3_Config::set_cs, ST7789V3_Config::set_dc, and ST7789V3_Config::spi_write.

Referenced by DrawPixel(), and FillScreen().

◆ SleepMode()

void SleepMode	(	ST7789V3_Config *	config,
		Sleep_State	sleepstate
	)

Put the display into sleep mode or wake it up.

Parameters

config	Pointer to the active driver configuration.
sleepstate	Requested sleep state.

References Sleep_In, and Sleep_Out.

◆ ST7789V3_DMA_Complete()

void ST7789V3_DMA_Complete ( ST7789V3_Config * config )

Finish a successful DMA transfer and run the completion callback.

Parameters

config Pointer to the active driver configuration.

Note: Call this from the application's SPI or DMA transfer-complete ISR bridge.

References ST7789V3_Config::callback_user_data, HIGH, ST7789V3_Config::set_cs, ST7789_STATE_READY, ST7789V3_Config::State, and ST7789V3_Config::tx_complete_callback.

◆ ST7789V3_DMA_Error()

void ST7789V3_DMA_Error ( ST7789V3_Config * config )

Finish a failed DMA transfer and run the error callback.

Parameters

config Pointer to the active driver configuration.

Note: Call this from the application's SPI or DMA error ISR bridge.

References ST7789V3_Config::callback_user_data, HIGH, ST7789V3_Config::set_cs, ST7789_STATE_ERROR, ST7789V3_Config::State, and ST7789V3_Config::tx_error_callback.

◆ ST7789V3_init()

void ST7789V3_init ( ST7789V3_Config * config )

Initialize the display and apply the default startup sequence.

Parameters

config Pointer to a configured driver instance.

Note: Before calling this function, populate the required GPIO, SPI, and delay callbacks and set the initial display width and height fields.

References bit_16, ST7789V3_Config::Col_Offset, ST7789V3_Config::delay_ms, DISPLAYON(), HIGH, ST7789V3_Config::Inversion_Mode, InvertDisplay(), INVON, ST7789V3_Config::LCD_Height, ST7789V3_Config::LCD_Width, LOW, ST7789V3_Config::Row_Offset, ST7789V3_Config::set_rst, SetColorMode(), and Sleep_Out.

◆ ST7789V3_WriteBuffer_DMA()

int8_t ST7789V3_WriteBuffer_DMA	(	ST7789V3_Config *	config,
		const uint8_t *	buf,
		uint16_t	len
	)

Start a non-blocking DMA write of pixel data to the display.

Parameters

config	Pointer to the active driver configuration.
buf	Pointer to the pixel data buffer.
len	Number of bytes to transfer.

Returns: 0 on success, -1 if DMA support is unavailable or the driver is not ready, or another negative value from the platform DMA callback.

Note: Call SetWindow before starting the transfer.; Chip select remains asserted until ST7789V3_DMA_Complete or ST7789V3_DMA_Error is called from the matching ISR path.

References DATA, HIGH, LOW, ST7789V3_Config::set_cs, ST7789V3_Config::set_dc, ST7789V3_Config::spi_write_dma, ST7789_STATE_BUSY, ST7789_STATE_ERROR, ST7789_STATE_READY, and ST7789V3_Config::State.

Data Structures

Enums and Types

Core Control API

Drawing API

DMA API

Controller Command Macros

Color Constants

Detailed Description

Macro Definition Documentation

◆ BLACK

◆ BLUE

◆ CASET

◆ COLMODE

◆ CYAN

◆ DARK_GRAY

◆ DARK_GREEN

◆ Display_Off_Register

◆ Display_On_Register

◆ GOLD

◆ GRAY

◆ GREEN

◆ INVOFF_REG

◆ INVON_REG

◆ LIGHT_GRAY

◆ LIME

◆ MADCTL

◆ MAGENTA

◆ MAROON

◆ NAVY

◆ OLIVE

◆ ORANGE

◆ PINK

◆ PURPLE

◆ RAMWR

◆ RASET

◆ RED

◆ SILVER

◆ SKY_BLUE

◆ Sleep_In

◆ Sleep_Out

◆ ST7789V3_backlight

◆ ST7789V3_rst

◆ TEAL

◆ WHITE

◆ YELLOW

Typedef Documentation

◆ ST7789V3_Callback

Enumeration Type Documentation

◆ Color_Mode

◆ GPIO_Pinstate

◆ Inversion_Mode

◆ Orientation

◆ Sleep_State

◆ ST7789V3_State

◆ Trans_State

Function Documentation

◆ DISPLAYOFF()

◆ DISPLAYON()

◆ DrawChar()

◆ DrawCircle()

◆ DrawFilledCircle()

◆ DrawFilledRectangle()

◆ DrawLine()

◆ DrawPixel()

◆ DrawRectangle()

◆ DrawString()

◆ FillScreen()

◆ HardReset()

◆ InvertDisplay()

◆ SetColorMode()

◆ SetRotation()

◆ SetWindow()

◆ SleepMode()

◆ ST7789V3_DMA_Complete()

◆ ST7789V3_DMA_Error()

◆ ST7789V3_init()

◆ ST7789V3_WriteBuffer_DMA()