Detailed Description

LCD driver implementation for a DOGM128W-6 LCD display.

============================================================================

Driver include

The LCD header file should be included in an application as follows:

Overview

This LCD driver implementation is designed to operate on a DOGM128W-6 LCD display. This display is the one used on the SmartRF06 EB (Evaluation Board). The LCD display can be written to by first writing the data to display to an internal buffer, and then sending the buffer content to the LCD display. The LCD driver will make use of the SPI driver for updating the display. The driver contains different functions for both modifying the internal buffer and for updating the display with the buffer content.

The DOGM128W-6 LCD display contains 128 pixel columns and 64 pixel rows. The (x,y) coordinate system is as described below:

*
*       X ----->
*   Y   +---------------------------------------------+
*   |   |(0,0)              PAGE 0             (127,0)|
*   |   |                   PAGE 1                    |
*   v   |                   PAGE 2                    |
*       |                   PAGE 3                    |
*       |                   PAGE 4                    |
*       |                   PAGE 5                    |
*       |                   PAGE 6                    |
*       |(0,63)             PAGE 7            (127,63)|
*       +---------------------------------------------+
*

This LCD driver uses a 5x7 font, thus each character takes up 5 pixels width and 7 pixels height. Each line of text will take up one page of the display. The difference between the defined variables LCD_CHAR_WIDTH and LCD_FONT_WIDTH equals the character spacing on the LCD display.

General Behavior

Before using LCD:

In order to use the DOGM128W-6 LCD display on the SmartRF06 EB, the application needs to first drive the Board_3V3_EN pin high to enable the 3.3V domain on the board.
The LCD display is configured by calling LCD_open(). This function will in turn open the SPI driver and allocate the 2 additional control signals (through the PIN driver) required to operate the LCD.

In total the following pins are required to operate the LCD on the SmartRF06EB:

*  Board_SPI0_MOSI     (Serial peripheral interface, Master-Out-Slave-In, controlled by LCD driver)
*  Board_SPI0_MISO     (Serial peripheral interface, Master-In-Slave-Out, controlled by LCD driver)
*  Board_SPI0_CLK      (Serial peripheral interface, Clock, controlled by LCD driver)
*  Board_LCD_CSN       (Serial peripheral interface, Chip select, controlled by LCD driver)
*  Board_LCD_RST       (LCD reset signal, active low, controlled by LCD driver)
*  Board_LCD_MODE      (LCD mode signal, controlled by LCD driver)
*  Board_3V3_EN        (Enable the 3.3V domain. NOTE: Must be set by application, NOT controlled by LCD driver)
*

The following SPI parameters will be fixed by the LCD driver:

transferMode = SPI_MODE_BLOCKING
transferTimeout = BIOS_WAIT_FOREVER
mode = SPI_MASTER
dataSize = 8

The APIs in this driver serve as an interface to a typical TI-RTOS application. The specific peripheral implementations are responsible to create all the SYS/BIOS specific primitives to allow for thread-safe operation.

After LCD operation has ended:

Release system dependencies for LCD by calling LCD_close().

Error handling

Please refer to the SPI driver documentation for information about error handling during a SPI transaction.

If an error occurs when modifying the internal buffers, the functions are return without completing the buffer modification.

Power Management

The TI-RTOS power management framework will try to put the device into the most power efficient mode whenever possible. Please see the technical reference manual for further details on each power mode.

The LCD driver makes use of the SPICC26XXDMA driver, which is setting a power constraint during transfers to keep the device out of standby. I.e. device will enter idle mode when no tasks are active. When the transfer has finished, the power constraint is released.

LCD Details

Allocating space to internal buffers

The LCD driver joined (at link time) to an array of LCD_Buffer structures named lcdBuffers. lcdBuffers is implemented in the application with each entry being an instance of a LCD_Buffer. The number of buffers availible must be passed as an argument to LCD_open(). Each entry in lcdBuffers contains a:

(Char *) which points to a buffer with data to be printed on the LCD
(unsigned int) which is the size of the buffer
(Semaphore_Struct) which is a semaphore to be associated with the buffer. The Semaphores will be constructed by the LCD driver when it is being opened, and is being used to block task execution while the associated buffer is in use.

Modifying internal buffers and updating LCD display

Before the LCD screen can be filled, the data to display must be written to the internal buffers. All functions called LCD_bufferxxxx are only modifying the internal buffers. To send the buffer content to the LCD display, one must use the functions LCD_update() or LCD_updatePart(). The only exception from this is the function LCD_writeLine(), which both modifies a buffer and send the content to the LCD display.

Supported Functions

API function	Description
LCD_open()	Initialize LCD display and configure SPI driver
LCD_close()	Disable LCD operation
LCD_writeLine()	Write a string and a number to a page on the LCD display
LCD_update()	Write the content of a LCD buffer to the display
LCD_updatePart()	Write part of a LCD buffer to the display
LCD_bufferClear()	Empty an entire LCD buffer
LCD_bufferClearPage()	Empty an entire page in a LCD buffer
LCD_bufferClearPart()	Empty part of a LCD buffer
LCD_bufferInvert()	Invert the pixels of a part of a LCD buffer
LCD_bufferInvertPage()	Invert the pixels of a page in a LCD buffer
LCD_bufferPrintString()	Write a string to a LCD buffer
LCD_bufferPrintStringAligned()	Write an aligned string to a LCD buffer
LCD_bufferPrintInt()	Write an integer to a LCD buffer
LCD_bufferPrintIntAligned()	Write an aligned integer to a LCD buffer
LCD_bufferPrintFloat()	Write a floating point number to a LCD buffer
LCD_bufferPrintFloatAligned()	Write an aligned floating point number to a LCD buffer
LCD_bufferSetLine()	Draw a line to a LCD buffer
LCD_bufferClearLine()	Clear a line from a LCD buffer
LCD_bufferSetHLine()	Draw a horizontal line to a LCD buffer
LCD_bufferClearHLine()	Clear a horizontal line from a LCD buffer
LCD_bufferSetVLine()	Draw a vertical line to a LCD buffer
LCD_bufferClearVLine()	Clear a vertical line from a LCD buffer
LCD_bufferHArrow()	Draw a horizontal arrow to a LCD buffer
LCD_bufferVArrow()	Draw a vertical arrow to a LCD buffer
LCD_bufferSetPx()	Set a pixel in a LCD buffer
LCD_bufferClearPx()	Clear a pixel in a LCD buffer
LCD_bufferCopy()	Copy content of one LCD buffer into another
LCD_setContrast()	Set the contrast of the LCD display

Use Cases

The most basic use cases discribed are described below. A complete LCD example can also be found in the TI-RTOS simplelink distribution.

Configuring the LCD display

LCD_Handle lcdHandle;
LCD_Params lcdParams;
PIN_State  pinState;
PIN_Handle hPins;
// This application supports two LCD buffers
Char lcdBuffer0[LCD_BYTES] = {0};
Char lcdBuffer1[LCD_BYTES] = {0};
// Populate LCD_Buffer structure with buffer pointers and buffer sizes.
// The Semaphore structure will be constructed when opening the LCD.
LCD_Buffer lcdBuffers[] = {
    {lcdBuffer0, LCD_BYTES, NULL},
    {lcdBuffer1, LCD_BYTES, NULL},
};
// Application pin table.
// Drive Board_3V3_EN high to enble 3.3V domain on SRF06EB
PIN_Config pinList[] = {
     Board_3V3_EN     | PIN_GPIO_OUTPUT_EN | PIN_GPIO_HIGH  | PIN_PUSHPULL,
     PIN_TERMINATE
};
// Open PIN driver
hPins = PIN_open(&pinState, pinList);
// Initialize LCD parameters
LCD_Params_init(&lcdParams);
// Optionally override default bit rate
lcdParams.spiBitRate = someNewSpiBitRate;
// Open LCD driver, using 2 buffers
lcdHandle = LCD_open(&lcdBuffers[0], 2, &lcdParams);
// Make sure it was successful
if (!lcdHandle)
{
    System_abort("Error initializing LCD\n");
}

Writing to the internal buffer

// Clear and write to buffer 0
LCD_bufferClear(lcdHandle, 0);
LCD_bufferPrintString(lcdHandle, 0, "Writing to Buffer 0", 24, LCD_PAGE0);
LCD_bufferSetHLine(lcdHandle, 0, LCD_X_FIRST, LCD_X_LAST, 20);

Updating LCD display with buffer content

// Update display with content of buffer 0

LCD_update(lcdHandle, 0);

Instrumentation

The LCD driver interface produces log statements if instrumentation is enabled.

Diagnostics Mask	Log details
Diags_USER1	basic operations performed

#include <xdc/std.h>
#include <ti/drivers/SPI.h>
#include <ti/sysbios/family/arm/m3/Hwi.h>
#include <ti/sysbios/knl/Semaphore.h>

Include dependency graph for LCDDogm1286.h:

Go to the source code of this file.

Data Structures
struct	LCD_Params
	LCD Parameters are used to with the LCD_open() call. Default values for these parameters are set using LCD_Params_init(). More...

struct	LCD_Command
	Format of LCD commands used by the LCD controller. More...

struct	LCD_Buffer
	LCD_Buffer used to store data to be printed on the LCD display. More...

struct	LCD_Object
	LCD Object. More...

struct	LCD_HWAttrs
	LCD Hardware attributes. More...

struct	LCD_Config
	The LCD_Config structure contains a set of pointers used to characterize the LCD driver implementation. More...

Macros
#define	ti_sysbios_family_arm_m3_Hwi__nolocalnames

#define	LCD_PIXELS 8192

#define	LCD_BYTES 1024

#define	LCD_COLS 128

#define	LCD_X_MIN 0

#define	LCD_X_MAX (LCD_COLS-1)

#define	LCD_ROWS 64

#define	LCD_Y_MIN 0

#define	LCD_Y_MAX (LCD_ROWS-1)

#define	LCD_PAGES 8

#define	LCD_PAGE_ROWS 8

#define	LCD_CHAR_WIDTH 6

#define	LCD_FONT_WIDTH 5

Typedefs
typedef struct LCD_Config *	LCD_Handle
	A handle that is returned from a LCD_open() call. More...

typedef enum LCD_Align	LCD_Align
	LCD alignment enum. More...

typedef enum LCD_Page	LCD_Page
	LCD page enum. More...

typedef enum LCD_X_Limit	LCD_X_Limit
	LCD x-axis enum. More...

typedef enum LCD_Y_Limit	LCD_Y_Limit
	LCD y-axis enum. More...

typedef struct LCD_Params	LCD_Params
	LCD Parameters are used to with the LCD_open() call. Default values for these parameters are set using LCD_Params_init(). More...

typedef struct LCD_Command	LCD_Command
	Format of LCD commands used by the LCD controller. More...

typedef struct LCD_Buffer	LCD_Buffer
	LCD_Buffer used to store data to be printed on the LCD display. More...

typedef struct LCD_Object	LCD_Object
	LCD Object. More...

typedef struct LCD_HWAttrs	LCD_HWAttrs
	LCD Hardware attributes. More...

typedef struct LCD_Config	LCD_Config
	The LCD_Config structure contains a set of pointers used to characterize the LCD driver implementation. More...

Enumerations
enum	LCD_Align { LCD_ALIGN_LEFT, LCD_ALIGN_CENTER, LCD_ALIGN_RIGHT }
	LCD alignment enum. More...

enum	LCD_Page { LCD_PAGE0 = 0, LCD_PAGE1, LCD_PAGE2, LCD_PAGE3, LCD_PAGE4, LCD_PAGE5, LCD_PAGE6, LCD_PAGE7, LCD_PAGE_COUNT }
	LCD page enum. More...

enum	LCD_X_Limit { LCD_X_FIRST = 0, LCD_X_LAST = (LCD_COLS-1) }
	LCD x-axis enum. More...

enum	LCD_Y_Limit { LCD_Y_FIRST = 0, LCD_Y_LAST = (LCD_ROWS-1) }
	LCD y-axis enum. More...

Functions
void	LCD_close (LCD_Handle handle)
	Function to close the LCD instance specified by the LCD handle. More...

void	LCD_init (void)
	This function initializes the LCD driver module. More...

LCD_Handle	LCD_open (LCD_Buffer buffers, uint8_t nBuffers, LCD_Params params)
	Function to set up the DOGM128W-6 LCD display. More...

void	LCD_Params_init (LCD_Params *params)
	Function to initialize the LCD_Params struct to its defaults. More...

void	LCD_writeLine (LCD_Handle handle, unsigned int bufIndex, char *str, unsigned int uiValue, unsigned char ucFormat, unsigned char ucLine)
	Function that writes a string and value to a buffer and sends it to the LCD display. The written page is being cleared before it is written to. More...

void	LCD_update (LCD_Handle handle, unsigned int bufIndex)
	Function that writes the specified buffer to the LCD display. More...

void	LCD_updatePart (LCD_Handle handle, unsigned int bufIndex, unsigned char ucXFrom, unsigned char ucXTo, LCD_Page iPageFrom, LCD_Page iPageTo)
	Function that sends the specified part of the given buffer to the corresponding part on the LCD. This function assumes ucXFrom <= ucXTo and iPageFrom <= iPageTo. The resolution is given in columns [0–127] and pages [0–7]. More...

void	LCD_bufferClear (LCD_Handle handle, unsigned int bufIndex)
	Function that empties the specified LCD buffer. More...

void	LCD_bufferClearPage (LCD_Handle handle, unsigned int bufIndex, LCD_Page iPage)
	This function clears the page specified by iPage in the given buffer. More...

void	LCD_bufferClearPart (LCD_Handle handle, unsigned int bufIndex, unsigned char ucXFrom, unsigned char ucXTo, LCD_Page iPageFrom, LCD_Page iPageTo)
	This function clears the pixels in a given piece of a page. Resolution is given in coulmns [0–127] and pages [0–7]. The function assumes ucXFrom <= ucXTo and iPageFrom <= iPageTo. More...

void	LCD_bufferInvert (LCD_Handle handle, unsigned int bufIndex, unsigned char ucXFrom, unsigned char ucYFrom, unsigned char ucXTo, unsigned char ucYTo)
	This function inverts the pixels (bits) in a given region of the specified buffer. More...

void	LCD_bufferInvertPage (LCD_Handle handle, unsigned int bufIndex, unsigned char ucXFrom, unsigned char ucXTo, LCD_Page iPage)
	This function inverts a range of columns in the display buffer on a specified page (for example, LCD_PAGE0). This function assumes ucXFrom <= ucXTo. More...

void	LCD_bufferPrintString (LCD_Handle handle, unsigned int bufIndex, const char *pcStr, unsigned char ucX, LCD_Page iPage)
	Function that writes a string to the specified buffer. More...

void	LCD_bufferPrintStringAligned (LCD_Handle handle, unsigned int bufIndex, const char *pcStr, LCD_Align iAlignment, LCD_Page iPage)
	This function writes a string to the given buffer specified by the iAlignment argument. More...

void	LCD_bufferPrintInt (LCD_Handle handle, unsigned int bufIndex, int i32Number, unsigned char ucX, LCD_Page iPage)
	Function that writes an integer to the specified buffer. More...

void	LCD_bufferPrintIntAligned (LCD_Handle handle, unsigned int bufIndex, int i32Number, LCD_Align iAlignment, LCD_Page iPage)
	This function writes an integer to the given buffer as specified by the iAlignment argument. More...

void	LCD_bufferPrintFloat (LCD_Handle handle, unsigned int bufIndex, float fNumber, unsigned char ucDecimals, unsigned char ucX, LCD_Page iPage)
	This function writes a number of data type float to the given buffer at a specified column and page. Use this function instead of performing a float to c-string conversion and then using LCD_bufferPrintString(). More...

void	LCD_bufferPrintFloatAligned (LCD_Handle handle, unsigned int bufIndex, float fNumber, unsigned char ucDecimals, LCD_Align iAlignment, LCD_Page iPage)
	This function writes a float number to the given buffer as specified by the iAlignment argument. More...

void	LCD_bufferSetLine (LCD_Handle handle, unsigned int bufIndex, unsigned char ucXFrom, unsigned char ucYFrom, unsigned char ucXTo, unsigned char ucYTo)
	This function draws a line in the specified buffer from (ucXFrom,ucYFrom) to (ucXTo,ucYTo). The function uses Bresenham's line algorithm. More...

void	LCD_bufferClearLine (LCD_Handle handle, unsigned int bufIndex, unsigned char ucXFrom, unsigned char ucYFrom, unsigned char ucXTo, unsigned char ucYTo)
	This function clears a line in the specified buffer from (ucXFrom,ucYFrom) to (ucXTo,ucYTo). The function uses Bresenham's line algorithm. More...

void	LCD_bufferSetHLine (LCD_Handle handle, unsigned int bufIndex, unsigned char ucXFrom, unsigned char ucXTo, unsigned char ucY)
	This function draws a horizontal line from (ucXFrom,ucY) to (ucXTo,ucY) into the specified buffer. More...

void	LCD_bufferClearHLine (LCD_Handle handle, unsigned int bufIndex, unsigned char ucXFrom, unsigned char ucXTo, unsigned char ucY)
	This function clears a horizontal line from (ucXFrom,ucY) to (ucXTo,ucY) from the specified buffer. More...

void	LCD_bufferSetVLine (LCD_Handle handle, unsigned int bufIndex, unsigned char ucX, unsigned char ucYFrom, unsigned char ucYTo)
	This function draws a vertical line from (ucX,ucYFrom) to (ucX,ucYTo) into the specified buffer. More...

void	LCD_bufferClearVLine (LCD_Handle handle, unsigned int bufIndex, unsigned char ucX, unsigned char ucYFrom, unsigned char ucYTo)
	This function clears a vertical line from (ucX,ucYFrom) to (ucX,ucYTo) from the buffer specified. More...

void	LCD_bufferHArrow (LCD_Handle handle, unsigned int bufIndex, unsigned char ucXFrom, unsigned char ucXTo, unsigned char ucY)
	This function draws a horizontal arrow from (ucXFrom,ucY) to (ucXTo,ucY) to buffer specified. The function assumes ucY to be in the range [2–61] in order for arrowhead to fit on the LCD. More...

void	LCD_bufferVArrow (LCD_Handle handle, unsigned int bufIndex, unsigned char ucX, unsigned char ucYFrom, unsigned char ucYTo)
	This function draws a vertical arrow from (ucX,ucYFrom) to (ucX,ucYTo) to the buffer specified. The function assumes that ucX is in the range [2–125] for the arrowhead to fit on the LCD. More...

void	LCD_bufferSetPx (LCD_Handle handle, unsigned int bufIndex, unsigned char ucX, unsigned char ucY)
	This function sets a pixel on (ucX,ucY). More...

void	LCD_bufferClearPx (LCD_Handle handle, unsigned int bufIndex, unsigned char ucX, unsigned char ucY)
	This function clears the pixel at (ucX,ucY). More...

void	LCD_bufferCopy (LCD_Handle handle, unsigned int fromBufIndex, unsigned int toBufIndex)
	This function copies the content of fromBufIndex to toBufIndex. More...

void	LCD_setContrast (LCD_Handle handle, unsigned char ucContrast)
	This Function sets the LCD contrast. More...

Macro Definition Documentation

#define ti_sysbios_family_arm_m3_Hwi__nolocalnames

#define LCD_PIXELS 8192

#define LCD_BYTES 1024

Number of bytes needed in LCD buffer

#define LCD_COLS 128

Number of pixel columns

#define LCD_X_MIN 0

First pixel on LCD x-axis

#define LCD_X_MAX (LCD_COLS-1)

Last pixel on LCD x-axis

#define LCD_ROWS 64

Number of pixel rows

#define LCD_Y_MIN 0

First pixel on LCD y-axis

#define LCD_Y_MAX (LCD_ROWS-1)

Last pixel on LCD y-axis

#define LCD_PAGES 8

#define LCD_PAGE_ROWS 8

Number of pixel rows per LCD page

#define LCD_CHAR_WIDTH 6

Space used for each character

#define LCD_FONT_WIDTH 5

Actual font character width

Typedef Documentation

typedef struct LCD_Config* LCD_Handle

A handle that is returned from a LCD_open() call.

typedef enum LCD_Align LCD_Align

LCD alignment enum.

This enumeration defines the text alignment. It is used by LCD_bufferPrintxxxAligned functions.

typedef enum LCD_Page LCD_Page

LCD page enum.

This enumeration defines the LCD pages. It is used by LCD_bufferxxx functions

typedef enum LCD_X_Limit LCD_X_Limit

LCD x-axis enum.

This enumeration defines x axis limit It is used for x argument in LCD_bufferxxx functions

typedef enum LCD_Y_Limit LCD_Y_Limit

LCD y-axis enum.

This enumeration defines y axis limit It is used for y argument in LCD_bufferxxx functions

typedef struct LCD_Params LCD_Params

LCD Parameters are used to with the LCD_open() call. Default values for these parameters are set using LCD_Params_init().

See also: SPI_Params_init

typedef struct LCD_Command LCD_Command

Format of LCD commands used by the LCD controller.

typedef struct LCD_Buffer LCD_Buffer

LCD_Buffer used to store data to be printed on the LCD display.

A sample structure is shown below:

 LCD_Buffer lcdBuffers[] = {
     {lcdBuffer0, LCD_BYTES, NULL},
     {lcdBuffer1, LCD_BYTES, NULL},
 };

typedef struct LCD_Object LCD_Object

LCD Object.

The application must not access any member variables of this structure!

typedef struct LCD_HWAttrs LCD_HWAttrs

LCD Hardware attributes.

A sample structure is shown below:

 const LCD_HWAttrs lcdHWAttrs = {
     .LCD_initCmd = &LCD_initCmd,
     .lcdResetPin = Board_LCD_RST,
     .lcdModePin = Board_LCD_MODE,
     .lcdCsnPin = Board_LCD_CSN,
     .spiIndex = Board_SPI0
 };

typedef struct LCD_Config LCD_Config

The LCD_Config structure contains a set of pointers used to characterize the LCD driver implementation.

Enumeration Type Documentation

enum LCD_Align

LCD alignment enum.

This enumeration defines the text alignment. It is used by LCD_bufferPrintxxxAligned functions.

Enumerator
LCD_ALIGN_LEFT	Text is aligned to the left
LCD_ALIGN_CENTER	Text is aligned in the center
LCD_ALIGN_RIGHT	Text is aligned to the right

enum LCD_Page

LCD page enum.

This enumeration defines the LCD pages. It is used by LCD_bufferxxx functions

Enumerator
LCD_PAGE0
LCD_PAGE1
LCD_PAGE2
LCD_PAGE3
LCD_PAGE4
LCD_PAGE5
LCD_PAGE6
LCD_PAGE7
LCD_PAGE_COUNT

enum LCD_X_Limit

LCD x-axis enum.

This enumeration defines x axis limit It is used for x argument in LCD_bufferxxx functions

Enumerator
LCD_X_FIRST
LCD_X_LAST

enum LCD_Y_Limit

LCD y-axis enum.

This enumeration defines y axis limit It is used for y argument in LCD_bufferxxx functions

Enumerator
LCD_Y_FIRST
LCD_Y_LAST

Function Documentation

void LCD_close ( LCD_Handle handle )

Function to close the LCD instance specified by the LCD handle.

Precondition: LCD_open() has to be called first. Function assumes that the handle is not NULL. Calling context: Task.

Parameters

handle A LCD handle returned from LCD_open()

See also: LCD_open()

void LCD_init ( void )

This function initializes the LCD driver module.

Precondition: The LCD_config structure must exist and be persistent before this function can be called. This function must be called before any other LCD driver APIs. Calling context: Hwi, Swi, Task, Main.

LCD_Handle LCD_open	(	LCD_Buffer *	buffers,
		uint8_t	nBuffers,
		LCD_Params *	params
	)

Function to set up the DOGM128W-6 LCD display.

Precondition: LCD controller has been initialized using LCD_init(). Calling context: Task.

Parameters

buffers	Pointer to a buffer block.
nBuffers	Number of buffers in the buffer block.
params	Pointer to a parameter block, if NULL it will use default values

Returns: A pointer to a LCD_Handle on success or a NULL it was already opened

See also: LCD_close(); LCD_init()

void LCD_Params_init ( LCD_Params * params )

Function to initialize the LCD_Params struct to its defaults.

Defaults values are:

 lcdWriteTimeout = BIOS_WAIT_FOREVER;
 spiBitRate      = 1000000;
 spiFrameFormat  = SPI_POL0_PHA0;

Precondition: Calling context: Task.

Parameters

params Parameter structure to initialize

void LCD_writeLine	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		char *	str,
		unsigned int	uiValue,
		unsigned char	ucFormat,
		unsigned char	ucLine
	)

Function that writes a string and value to a buffer and sends it to the LCD display. The written page is being cleared before it is written to.

LCD_write will block task execution until all the data in buffer has been written to the LCD.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
str	A pointer to the string to print.
uiValue	Value to print
ucFormat	Base of the value to print � 2,8,16 etc. ucFormat must be between 2 and 36, where 10 means decimal base, 16 hexadecimal, 8 octal, and 2 binary. If ucFormat is zero, only the string will get printed.
ucLine	The page to write. Must be a value from 0-7.

void LCD_update	(	LCD_Handle	handle,
		unsigned int	bufIndex
	)

Function that writes the specified buffer to the LCD display.

LCD_update will block task execution until all the data in buffer has been written to the LCD.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.

void LCD_updatePart	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		unsigned char	ucXFrom,
		unsigned char	ucXTo,
		LCD_Page	iPageFrom,
		LCD_Page	iPageTo
	)

Function that sends the specified part of the given buffer to the corresponding part on the LCD. This function assumes ucXFrom <= ucXTo and iPageFrom <= iPageTo. The resolution is given in columns [0–127] and pages [0–7].

LCD_updatePart will block task execution until all the data has been written to the LCD.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
ucXFrom	The lowest x-position (column) to write [0–127].
ucXTo	The highest x-position to write [ucXFrom–127].
iPageFrom	The first page to write. Must be one of the following enumerated values: LCD_PAGE0 LCD_PAGE1 LCD_PAGE2 LCD_PAGE3 LCD_PAGE4 LCD_PAGE5 LCD_PAGE6 LCD_PAGE7
iPageTo	The last page to write [iPageFrom–LCD_PAGE7].

Returns: None

void LCD_bufferClear	(	LCD_Handle	handle,
		unsigned int	bufIndex
	)

Function that empties the specified LCD buffer.

LCD_bufferClear will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.

void LCD_bufferClearPage	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		LCD_Page	iPage
	)

This function clears the page specified by iPage in the given buffer.

LCD_bufferClearPage will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
iPage	The page to clear. Must be one of the following enumerated values: LCD_PAGE0 LCD_PAGE1 LCD_PAGE2 LCD_PAGE3 LCD_PAGE4 LCD_PAGE5 LCD_PAGE6 LCD_PAGE7

Returns: None

void LCD_bufferClearPart	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		unsigned char	ucXFrom,
		unsigned char	ucXTo,
		LCD_Page	iPageFrom,
		LCD_Page	iPageTo
	)

This function clears the pixels in a given piece of a page. Resolution is given in coulmns [0–127] and pages [0–7]. The function assumes ucXFrom <= ucXTo and iPageFrom <= iPageTo.

LCD_bufferClearPart will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
ucXFrom	The lowest x-position (column) to be cleared [0–127].
ucXTo	The highest x-position to be cleared [ucXFrom–127].
iPageFrom	The first page cleared. Must be one of the following enumerated values: LCD_PAGE0 LCD_PAGE1 LCD_PAGE2 LCD_PAGE3 LCD_PAGE4 LCD_PAGE5 LCD_PAGE6 LCD_PAGE7
iPageTo	The last page cleared [iPageFrom–LCD_PAGE7].

Returns: None

void LCD_bufferInvert	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		unsigned char	ucXFrom,
		unsigned char	ucYFrom,
		unsigned char	ucXTo,
		unsigned char	ucYTo
	)

This function inverts the pixels (bits) in a given region of the specified buffer.

LCD_bufferInvert will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
ucXFrom	The first x-position (column) to invert [0–127].
ucYFrom	is the first y-position (row) to invert [0–63].
ucXTo	The last x-position (column) to invert [0–127].
ucYTo	The last y-position (row) to invert [0–63].

Returns: None

void LCD_bufferInvertPage	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		unsigned char	ucXFrom,
		unsigned char	ucXTo,
		LCD_Page	iPage
	)

This function inverts a range of columns in the display buffer on a specified page (for example, LCD_PAGE0). This function assumes ucXFrom <= ucXTo.

LCD_bufferInvertPage will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
ucXFrom	The first x-position (column) to invert [0–127].
ucXTo	The last x-position (column) to invert [ucXFrom–127].
iPage	The page on which to invert. Must be one of the following enumerated values: LCD_PAGE0 LCD_PAGE1 LCD_PAGE2 LCD_PAGE3 LCD_PAGE4 LCD_PAGE5 LCD_PAGE6 LCD_PAGE7

Returns: None

void LCD_bufferPrintString	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		const char *	pcStr,
		unsigned char	ucX,
		LCD_Page	iPage
	)

Function that writes a string to the specified buffer.

LCD_bufferPrintString will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
pcStr	A pointer to the string to print.
ucX	The x-position (column) to begin printing [0–127].
iPage	The page on which to print. Must be one of the following enumerated values: LCD_PAGE0 LCD_PAGE1 LCD_PAGE2 LCD_PAGE3 LCD_PAGE4 LCD_PAGE5 LCD_PAGE6 LCD_PAGE7

void LCD_bufferPrintStringAligned	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		const char *	pcStr,
		LCD_Align	iAlignment,
		LCD_Page	iPage
	)

This function writes a string to the given buffer specified by the iAlignment argument.

LCD_bufferPrintStringAligned will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
pcStr	A pointer to the string to print.
iAlignment	The text alignment. Must be one of the following enumerated values: LCD_ALIGN_LEFT LCD_ALIGN_CENTER LCD_ALIGN_RIGHT
iPage	The page on which to print. Must be one of the following enumerated values: LCD_PAGE0 LCD_PAGE1 LCD_PAGE2 LCD_PAGE3 LCD_PAGE4 LCD_PAGE5 LCD_PAGE6 LCD_PAGE7

Returns: None

void LCD_bufferPrintInt	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		int	i32Number,
		unsigned char	ucX,
		LCD_Page	iPage
	)

Function that writes an integer to the specified buffer.

LCD_bufferPrintInt will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
i32Number	The number to print.
ucX	The x-position (column) to begin printing [0–127].
iPage	The page on which to print. Must be one of the following enumerated values: LCD_PAGE0 LCD_PAGE1 LCD_PAGE2 LCD_PAGE3 LCD_PAGE4 LCD_PAGE5 LCD_PAGE6 LCD_PAGE7

void LCD_bufferPrintIntAligned	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		int	i32Number,
		LCD_Align	iAlignment,
		LCD_Page	iPage
	)

This function writes an integer to the given buffer as specified by the iAlignment argument.

LCD_bufferPrintIntAligned will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
i32Number	The number to be printed.
iAlignment	The text alignment. Must be one of the following enumerated values: LCD_ALIGN_LEFT LCD_ALIGN_CENTER LCD_ALIGN_RIGHT
iPage	The page on which to print. Must be one of the following enumerated values: LCD_PAGE0 LCD_PAGE1 LCD_PAGE2 LCD_PAGE3 LCD_PAGE4 LCD_PAGE5 LCD_PAGE6 LCD_PAGE7

Returns: None

void LCD_bufferPrintFloat	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		float	fNumber,
		unsigned char	ucDecimals,
		unsigned char	ucX,
		LCD_Page	iPage
	)

This function writes a number of data type float to the given buffer at a specified column and page. Use this function instead of performing a float to c-string conversion and then using LCD_bufferPrintString().

LCD_bufferPrintFloat will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
fNumber	The number to print.
ucDecimals	The number of decimals to print, MAX = 10.
ucX	The x-position (column) to begin printing [0–127].
iPage	The page on which to print. Must be one of the following enumerated values: LCD_PAGE0 LCD_PAGE1 LCD_PAGE2 LCD_PAGE3 LCD_PAGE4 LCD_PAGE5 LCD_PAGE6 LCD_PAGE7

Returns: None

void LCD_bufferPrintFloatAligned	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		float	fNumber,
		unsigned char	ucDecimals,
		LCD_Align	iAlignment,
		LCD_Page	iPage
	)

This function writes a float number to the given buffer as specified by the iAlignment argument.

LCD_bufferPrintFloatAligned will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
fNumber	The number to be printed.
ucDecimals	The number of decimals to be printed, MAX = 10.
iAlignment	The text alignment. Can be one of the following enumerated values: LCD_ALIGN_LEFT LCD_ALIGN_CENTER LCD_ALIGN_RIGHT
iPage	The page on which to print. Must be one of the following enumerated values: LCD_PAGE0 LCD_PAGE1 LCD_PAGE2 LCD_PAGE3 LCD_PAGE4 LCD_PAGE5 LCD_PAGE6 LCD_PAGE7

Returns: None

void LCD_bufferSetLine	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		unsigned char	ucXFrom,
		unsigned char	ucYFrom,
		unsigned char	ucXTo,
		unsigned char	ucYTo
	)

This function draws a line in the specified buffer from (ucXFrom,ucYFrom) to (ucXTo,ucYTo). The function uses Bresenham's line algorithm.

This function will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
ucXFrom	The start column [0–127].
ucXTo	The end column [0–127].
ucYFrom	The start row [0–63].
ucYTo	The end row [0–63].

Returns: None

void LCD_bufferClearLine	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		unsigned char	ucXFrom,
		unsigned char	ucYFrom,
		unsigned char	ucXTo,
		unsigned char	ucYTo
	)

This function clears a line in the specified buffer from (ucXFrom,ucYFrom) to (ucXTo,ucYTo). The function uses Bresenham's line algorithm.

This function will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
ucXFrom	The start column [0–127].
ucXTo	The end column [0–127].
ucYFrom	The start row [0–63].
ucYTo	The end row [0–63].

Returns: None

void LCD_bufferSetHLine	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		unsigned char	ucXFrom,
		unsigned char	ucXTo,
		unsigned char	ucY
	)

This function draws a horizontal line from (ucXFrom,ucY) to (ucXTo,ucY) into the specified buffer.

This function will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
ucXFrom	The start column [0–127].
ucXTo	The end column [0–127].
ucY	The row [0–63].

Returns: None

void LCD_bufferClearHLine	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		unsigned char	ucXFrom,
		unsigned char	ucXTo,
		unsigned char	ucY
	)

This function clears a horizontal line from (ucXFrom,ucY) to (ucXTo,ucY) from the specified buffer.

This function will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
ucXFrom	The start column [0–127].
ucXTo	The end column [0–127].
ucY	The row [0–63].

Returns: None

void LCD_bufferSetVLine	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		unsigned char	ucX,
		unsigned char	ucYFrom,
		unsigned char	ucYTo
	)

This function draws a vertical line from (ucX,ucYFrom) to (ucX,ucYTo) into the specified buffer.

This function will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
ucX	The x-position (column) of the line [0–127].
ucYFrom	The start row [0–63].
ucYTo	The end row [0–63].

Returns: None

void LCD_bufferClearVLine	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		unsigned char	ucX,
		unsigned char	ucYFrom,
		unsigned char	ucYTo
	)

This function clears a vertical line from (ucX,ucYFrom) to (ucX,ucYTo) from the buffer specified.

This function will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
ucX	The x-position (column) of the line [0–127].
ucYFrom	The start row [0–63].
ucYTo	The end row [0–63].

Returns: None

void LCD_bufferHArrow	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		unsigned char	ucXFrom,
		unsigned char	ucXTo,
		unsigned char	ucY
	)

This function draws a horizontal arrow from (ucXFrom,ucY) to (ucXTo,ucY) to buffer specified. The function assumes ucY to be in the range [2–61] in order for arrowhead to fit on the LCD.

This function will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
ucXFrom	The start column [0–127].
ucXTo	The end column [0–127].
ucY	The the y-position (row) of the arrow [2–61].

Returns: None

void LCD_bufferVArrow	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		unsigned char	ucX,
		unsigned char	ucYFrom,
		unsigned char	ucYTo
	)

This function draws a vertical arrow from (ucX,ucYFrom) to (ucX,ucYTo) to the buffer specified. The function assumes that ucX is in the range [2–125] for the arrowhead to fit on the LCD.

This function will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
ucX	The the x-position (column) of the arrow [2–125].
ucYFrom	The start row [0–63].
ucYTo	The end row [0–63].

Returns: None

void LCD_bufferSetPx	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		unsigned char	ucX,
		unsigned char	ucY
	)

This function sets a pixel on (ucX,ucY).

This function will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
ucX	The pixel x-position (column) [0–127].
ucY	The pixel y-position (row) [0–63].

Returns: None

void LCD_bufferClearPx	(	LCD_Handle	handle,
		unsigned int	bufIndex,
		unsigned char	ucX,
		unsigned char	ucY
	)

This function clears the pixel at (ucX,ucY).

This function will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffer is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
bufIndex	The buffer to use, specified by its index in the LCD_Buffer structure.
ucX	The pixel x-position (column) [0–127].
ucY	The pixel y-position (row) [0–63].

Returns: None

void LCD_bufferCopy	(	LCD_Handle	handle,
		unsigned int	fromBufIndex,
		unsigned int	toBufIndex
	)

This function copies the content of fromBufIndex to toBufIndex.

This function will block task execution until all the buffer modification has finished.

Precondition: Function assumes that the handle and buffers are not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
fromBufIndex	A pointer to the destination buffer.
toBufIndex	A pointer to the target buffer.

Returns: None

void LCD_setContrast	(	LCD_Handle	handle,
		unsigned char	ucContrast
	)

This Function sets the LCD contrast.

Precondition: Function assumes that the handle is not NULL. Calling context: Task.

Parameters

handle	A LCD_Handle
ucContrast	The contrast value [0–63].

Returns: None

Detailed Description

Driver include

Overview

General Behavior

Error handling

Power Management

LCD Details

Allocating space to internal buffers

Modifying internal buffers and updating LCD display

Supported Functions

Use Cases

Configuring the LCD display

Writing to the internal buffer

Updating LCD display with buffer content

Instrumentation

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation