All Embedded

EE Compendium

Arm

Atmel

Microchip

Electronic Engineer

Embedded Programmer

Electronic Consultant

Original release

V1.01

Added processing of font bitmap files

Added flags field to bitmap header

V1.02

Some graphics programs sometimes use an opposite colouring of the pixels (an opposite palette). We now read the palette of each image and invert pixels if the opposite pallet colouring is used.

V1.03

LCD_C define changed to DISPLAY_C to match new define used by the V1.03 driver

Message box confirmation of conversion complete added.

Original release

V1.01

Minor changes to remove long variable names not liked by some compilers

V1.02

No significant changes

V1.03

Changed sample screen modes to be cycled through from a single switch input, instead of the previous switch input per sample screen.

Added CONSTANT define to main.h and replaced all ‘const rom’ to CONSTANT in the code, to allow easy dealing with compilers that require an additional qualifier such as ‘rom’ and those that don’t.

Added Microchip C30 and C32 compiler compatible projects for 16 and 32 bit Microchip devices.

Original release

V1.01

Changes to deal with long variable names that are cropped by some compilers.

lcd_delay_ms changed from a define to a function to simplify for compilers that don’t provide standard delay library functions or macros)

V1.02

Implemented centre and right align options for displaying strings

Changed the example lcd_display_bitmap call to use DISPLAY_BITMAP_INVERT_PIXELS_OFF to avoid confusion for new users (was previously DISPLAY_BITMAP_INVERT_PIXELS_ON).

V1.03

Significant changes to the overall driver code.

Added scrolling text functionality.

Moved many of the defines to the lcd-model.h file to make using the driver with new screens more straightforward.

Added USE_LOCAL_RAM_BUFFER define for a local ram buffer of display data to optionally be used to increase speed where microcontroller / processor ram is available, or when required for displays that do not provide the capability to read display data back from the screen.

Added CONSTANT define to main.h and replaced all ‘const rom’ to CONSTANT in the code, to allow easy dealing with compilers require an additional qualifier such as ‘rom’ and those that don’t.

Added Microchip C30 and C32 compiler compatibility for 16 and 32 bit Microchip devices.

Added new screen model sample files for Batron BTHQ240064AVB-EMN-06-LED with SPI interface.

If you do encounter issues using the driver with other compilers or devices and are able to give us details of the issue you encountered we will try and include changes or notes across our range of drivers to help other programmers avoid similar issues in the future. Please use the contact us page of our web site to report any such issues discovered.

Double check IO pin definitions in the driver header file.

Verify with a scope that all of the control and data pins to the screen are working correctly.

Add additional null execution steps to the DISPLAY_BUS_ACCESS_DELAY define in the display.h file in case more time is required for signals to stabilise on your PCB. This is more likely to be an issue for 2 layer PCB’s (no ground plane) with long tack lengths or screens with long ribbon / FFC cable connections.

Check that no other device on the data bus is outputting while the driver is trying to communicate with the screen.

If your screen controller IC includes a status register try reading the status from the screen and confirm that you get the expected response.

If you’re using output latches for some of the screen control pins, instead of pins connected directly to your processor, check your output latch function restores the previous output on the data bus when it exits, to avoid destroying the data the driver function is writing to the screen.

Check that your microcontroller is not resetting due to a watchdog timer timeout.

Check that you have enough stack space allocated. This driver does not use an excessive amount of ram from the stack, but if your application is already using large amounts of the stack before calling driver functions this may be causing a stack overrun?

Re-read the datasheet to find out what you’re doing wrong!

Generic Driver and Screen Specific Files

The ‘display.c’ and ‘display.h’ files contain all of the driver generic functions and defines.

The ‘display-model.c’ and display-model.h’ files contain functions and defines that are particular to a specific screen and controller IC.

Delay Function

display_delay_ms(delay_ms)

Provides a simple means for the drive to delay while initialising the screen. Accuracy is not important as long as a value of 1 = a delay of at least 1mS (i.e. longer delays don’t matter).

Initialise The Screen

void display_initialise (void)

This function calls a screen specific function in the ‘display-model.c’ file. The function contains the screen initialisation sequence.

If configuring the driver for a new screen then copy sample ‘display-model.c’ and ‘display-model.h’ files for a screen that is most similar and then modify this function to suit the screen in use.

Set the Contrast

void display_set_contrast (BYTE contrast_value)

This function is only used for screens that have built in digital contrast adjustment. It calls a screen specific function in the ‘display-model.c’ file. The function contains the screen initialisation sequence.

If configuring the driver for a new screen then copy sample ‘display-model.c’ and display-model.h’ files for a screen that is most similar and then modify this function to suit the screen in use.

Clear Screen

void display_clear_screen (BYTE invert_pixels)

This function writes 0×00 or 0xFF to every screen output byte location to clear it.

Usage examples:-

display_clear_screen(0); //Normal clear screen

display_clear_screen(1); //Set all screen pixels on

This is a universal function – modification is not normally required.

Display Bitmap

void display_bitmap (DWORD image_flash_address, const rom BYTE *p_image_memory_address, WORD image_options, WORD x_start_coord, WORD y_start_coord)

image_flash_address

Start address of bitmap in flash memory (set to 0 if bitmap is in program memory))

*p_image_memory_address

Pointer to bitmap in program memory (set to 0 if bitmap is in flash memory)

image_options

Bit 15:13 Unused

Bit 12 Font table image: 1 = Scroll text, 0 = static text

Bit 11:10 If either is high then do not output to the screen (used for centre and right aligned text)

Bit 9 Font table image: 1 = using proportionally spaced characters

Bit 8 Font table image: 0 = displayed along X axis, 1 = display along Y axis

Bit 7 1 = Invert pixels (i.e. a pixel on becomes off and vice versa)

Bit 6:0

0 = image is a normal bitmap.

>0 = Image is from a font table. The address given is the start of the font table. The value of bits 6:0 is the ASCII character required (0×01 – 0x7F)

x_start_coord

0 to DISPLAY_WIDTH_PIXELS. (If = 0xFFFF then the ‘ display_auto_x_coordinate’ variable is used for the bitmap x coordiante. This variable is updated with the next x coordinate each time this function is called to allow successive display across a screen).

ui_y_start_coord

0 to DISPLAY_HEIGHT_PIXELS. (If = 0xFFFF then the ‘display_auto_y_coordinate’ variable is used for the bitmap y coordiante. This variable is updated with the next y coordinate each time this function is called to allow successive display across a screen).

image_options standard defines:

DISPLAY_BITMAP_INVERT_PIXELS_OFF

DISPLAY_BITMAP_INVERT_PIXELS_ON

This is a large complex function that carries out all of the bitmap display functions. At a basic level it is simply reading bitmap data from memory and displaying each column in order. It is complex because it is dealing with all the problems having to read bitmaps in bytes of 8 pixels each and then write to the screen in bytes of 8 pixels but without there necessarily being any alignment between the two, and in as efficient a manor as possible. This function is also used to display each character of a string and when displaying text in proportional mode it deals with calculating how each character bitmap should be shifted and masked for any of the 4 possible screen orientations that may be used.

Usage example:-

display_bitmap(0, ec_logo_128x64, //Bitmap

DISPLAY_BITMAP_INVERT_PIXELS_ON, //Options

0, 0); //X, Y

This is a universal function – modification is not normally required.

Special Note

The X and Y start coordinates are screen based, not screen orientation based. Depending on how your particular screen is addressed and orientated in your application the X and Y values may relate to either actual real world axis and their values may run in either direction. An easy way of determining this for a new application is to display a bitmap or an ASCII text string in the centre of the screen and then alter the X and Y values to see how they affect the position of the bitmap or string.

Display String

Version for displaying constant strings:-

void display_const_string (DWORD image_flash_address, const rom BYTE *p_image_memory_address, WORD image_options, WORD x_start_coord, WORD y_start_coord, const rom BYTE *p_ascii_string)

Version for displaying variable strings:-

void display_variable_string (DWORD image_flash_address, const rom BYTE *p_image_memory_address, WORD image_options, WORD x_start_coord, WORD y_start_coord, BYTE *p_ascii_string)

image_flash_address

Start address of font table bitmap in flash memory (set to 0 if bitmap is in program memory))

*p_image_memory_address

Pointer to font table bitmap in program memory (set to 0 if bitmap is in flash memory)

image_options

Bits15:10 Unused

Bit9 0 = Monospace / fixed pitch characters, 1 = proportionally spaced characters

Bit8 0 = Display string along X axis, 1 = Display string along Y axis

Bit7 1 = Invert pixels (i.e. a pixel on becomes off and vice versa)

Bits6:0 Not available (used by display bitmap function)

x_start_coord

0 to DISPLAY_WIDTH_PIXELS. (If = 0xFFFF then the ‘ display_auto_x_coordinate’ variable is used for the bitmap x coordiante. This variable is updated with the next x coordinate each time this function is called to allow successive display across a screen).

y_start_coord

0 to DISPLAY_HEIGHT_PIXELS. (If = 0xFFFF then the ‘ display_auto_y_coordinate’ variable is used for the bitmap y coordinate. This variable is updated with the next y coordiante each time this function is called to allow successive display across a screen).

*p_ascii_string

Pointer to the string to be displayed (must be null terminated)

image_options standard defines:

DISPLAY_STRING_INVERT_PIXELS_OFF

DISPLAY_STRING_INVERT_PIXELS_ON

DISPLAY_STRING_ON_X_AXIS

DISPLAY_STRING_ON_Y_AXIS

DISPLAY_STRING_MONOSPACE

DISPLAY_STRING_PROPORTIONAL

DISPLAY_STRING_LEFT_ALIGN

DISPLAY_STRING_CENTER_ALIGN

DISPLAY_STRING_CENTRE_ALIGN

DISPLAY_STRING_RIGHT_ALIGN

These functions are relatively straightforward and they simply read the string one character at a time calling the display_display_bitmap function to display each character and to display the space between each character. A bitmap is displayed for the space between each character so that any underlying display pixels are overwritten as a string is displayed and so that the number of pixels required between each character can be effectively set by the special gap character in each font table bitmap (character 0x7f).

Constant string usage example:-

const rom BYTE sample_const_string[] = {“Hello World”};

display_const_string(0, font_05x07, //Bitmap

(DISPLAY_STRING_ON_X_AXIS | DISPLAY_STRING_INVERT_PIXELS_OFF |

DISPLAY_STRING_MONOSPACE |

DISPLAY_STRING_LEFT_ALIGN), //Options

0, 0, //X, Y

sample_const_string); //String

Variable string usage example:-

BYTE sample_variable_string[15] = {“Hello World”};

display_variable_string (0, font_05x07, //Bitmap

(DISPLAY_STRING_ON_X_AXIS | DISPLAY_STRING_INVERT_PIXELS_OFF |

DISPLAY_STRING_MONOSPACE |

DISPLAY_STRING_LEFT_ALIGN), //Options

0, 0, //X, Y

sample_variable_string); //String

This is a universal function – modification is not normally required.

Special Note

The X and Y start coordinates are screen based, not screen orientation based. Depending on how your particular screen is addressed and orientated in your application the X and Y values may relate to either actual real world axis and their values may run in either direction. An easy way of determining this for a new application is to display a bitmap or an ASCII text string in the centre of the screen and then alter the X and Y values to see how they affect the position of the bitmap or string.

Text Alignment

Left aligned text is the default way that strings are displayed. If you select centre or right aligned text the driver has automatically to calculate the required string start position as if the string was left aligned. It does this by simply displaying the string once, but with the data not actually being output to the screen, and then using the completed string end position to calculate the required left aligned string start position. The string is then displayed again, this time being outputted to the display. You don’t need to worry about the complexities of how the driver does this, but bear in mind that there is additional time required for this double processing of the string to take place. The double display approach is required because when centre or right aligning proportional text (which centre and right aligning is so useful for from a programmers point of view) each character has to be completely read and analysed to determine its width.

Byte Ordering Test Sequence

void display_byte_ordering_test_sequence (BYTE flags)

uc_flags

bit 0 set = reset to byte 0

bit 1 clear = move forwards 1 byte, set = move back 1 byte

This function may be used when configuring a new screen, to test how each sequential byte gets displayed on the screen. Call the function the first time with bit 0 set. The function will send a byte to the display at address 0×00, 0×00. Using push buttons or a timer, repeat calling the function with bit 0 and 1 clear and the function will write to the next byte, then the next, then the next…

The test byte sent is formatted as follows:-

This is a really useful way to discover how the screen is mapped and if there are bytes at the beginning of the address space that are unused (i.e. you have to call the function several times before you see the first byte). In this instance update the DISPLAY_WIDTH_START_OFFSET constant with the required offset to correct this.

This is a universal function – modification is not normally required.

Write Bitmap Byte

void display_write_bitmap_byte (BYTE bitmap_mask, BYTE bitmap_data, WORD x_byte_coord, WORD y_byte_coord);

bitmap_mask

bit high = use the bitmap_data value, bit low = use the existing screen value

bitmap_data

The data to write, controlled by the bitmap_mask bits

x_byte_coord

The X coordinate to write to

y_byte_coord

The Y coordinate to write to

This function first reads the current display value for the byte being addressed, then applies the bitmap data AND’d with the mask, before writing the byte back to the display.

If configuring the driver for a new screen then copy sample ‘display-model.c’ and display-model.h’ files for a screen that is most similar and then modify this function to suit the screen in use.

Set Byte Address

void display_set_address (WORD x_coord, WORD y_coord_page)

This functions deals with the complexities of how a screen is mapped and sends the address to be accessed to the screen. Displays with non logical or reverse orientation addressing are corrected using this function.

If configuring the driver for a new screen then copy sample ‘display-model.c’ and display-model.h’ files for a screen that is most similar and then modify this function to suit the screen in use.

Write Command

void display_write_command (BYTE data)

This function is usually that same as the instructions in the write part of display_write_bitmap_byte. The only difference may be setting the DC data / command line. However to allow for screens that aren’t so normal this separate write command function is used.

If configuring the driver for a new screen then copy sample ‘display-model.c’ and ‘display-model.h’ files for a screen that is most similar and then modify this function to suit the screen in use.

The following tests we’re carried out using a 128 x 64 pixel 8 bit parallel interface screen without using faster internal memory (DISPLAY_USE_LOCAL_RAM_BUFFER define disabled) and with all compiler optimisations turned off.

PIC18 Sample Project:

Approximately 7440 program memory bytes (3720 x 16 bit instructions) compiling just the driver functions with the Microchip C18 MPLAB C Compiler for PIC18 family of 8 bit microcontrollers.

PIC24 Sample Project:

Approximately 3334 program memory words (1677 x 24 bit instructions) compiling just the driver functions with the Microchip C30 MPLAB C Compiler for PIC24 family of 16 bit microcontrollers and dsPIC digital signal controllers.

PIC32 Sample Project:

Approximately 7540 program memory bytes (1855 x 32 bit instructions) compiling just the driver functions with the Microchip C32 MPLAB C Compiler for PIC32 family of 32 bit microcontrollers.

Variables Memory Space

Approximately 16 bytes of static RAM (DISPLAY_USE_LOCAL_RAM_BUFFER define disabled)

The driver does not require a great deal of temporary variable storage space from the stack as bitmap data is read and displayed one byte at a time.

Speed

This will depend on your screen and processor / microcontroller. As a basic guide, using the driver with the BATRON BTHQ128064 AVD COG 128 x 64 pixel sample screen and a PIC18 microcontroller running with a 6 MIPS instruction clock (3V3 powered) , internal program memory used to store bitmaps and DISPLAY_USE_LOCAL_RAM_BUFFER define disabled:-

Displaying a single 128 x 64 pixel bitmap takes approximately 85mS.

Displaying a 20 character left aligned ASCII text string, 5×7 pixel font, monospaced characters takes approximately 25ms.

Displaying a 20 character left aligned ASCII text string, 5×7 pixel font, proportional characters takes approximately 29ms.

With a 10 MIPS instruction clock (5V powered)

Displaying a single 128 x 64 pixel bitmap takes approximately 51mS.

Displaying a 20 character left aligned ASCII text string, 5×7 pixel font, monospaced characters takes approximately 15ms.

Displaying a 20 character left aligned ASCII text string, 5×7 pixel font, proportional characters takes approximately 17ms.

5000 x 5000 pixels

Using The Driver With a RTOS or Kernel

The stack / driver is implemented as a single thread so you just need to make sure it is always called from a single thread (it is not designed to be thread safe).