Other Functions for Display Modules

Relatively Low-Level Functions

The CowPi_stdio library has several functions designed to control the display modules with greater flexibility than you can achieve with the stdio functions. If you want or need to use them, they are exposed to the application programmer, and you can review their Doxygen comments in the Functions for Direct Control of Display Modules Section. In general, we believe that most, application programmers do not need to use them if you are using the more-convenient stdio functions and the Special Functions described in the next section.

Warning

Using the lower-level functions to control display modules that you are also addressing with a file stream may result in undesirable behavior.

There are, however, one or two exceptions.

void cowpi_hd44780_create_character(const cowpi_display_module_protocol_t *configuration, uint8_t encoding, const uint8_t pixel_vector[8])

Creates a custom character for the HD44780 character display.

The encoding can be a value between 0 and 7, inclusive. Each element of the pixel vector corresponds to a row of the 5x8 character matrix (thus, only 5 bits of each element are used).

Parameters:

• configuration – the microcontroller pins, adapter mapping, and possibly i2c peripheral address

• encoding – the value used to represent the character

• pixel_vector – identifies which LCDs are “on” or “off” for the custom character.

uint8_t *cowpi_font_ascii_to_5wide_dotmatrix(uint8_t *destination, char c)

Provides the dot matrix representation of an ASCII character centered horizontally in the five columns used for a 5x8 dot matrix character (the five right-most columns of the 8x8 matrix).

Each byte of the destination array stores one row of the character’s dot matrix representation, with element 0 being the top of the character.

The destination array is assumed to point to a block of memory with 8 bytes allocated; that is, it must have enough space to hold the character’s dot matrix representation.

See also

cowpi_font_ascii_to_narrow_dotmatrix

See also

cowpi_font_ascii_to_8wide_dotmatrix

Parameters:

• destination – an empty 8-byte array

• c – the ASCII character whose dot matrix representation is to be provided

Returns:

destination, with the requested dot matrix character

Of these two, we believe that cowpi_hd44780_create_character() will be more commonly used. The HD44780 has eight custom-character locations for character values 0-7 and aliased to character values 8-15. When a character byte holds one of these values, the corresponding custom character will be displayed. Because the byte value 0x00 represents a terminal NUL for the stdio functions, and because the byte values 0x09-0x0D represent ASCII control characters (see Table 4), we recommend that you strictly use the character values 1-8 for the custom characters.

Tip

When printing using custom characters, you can do so using a %c conversion specifier:

fprintf(display, "Here's a custom character: %c\n", my_characters[i]);

or, if there is only one possible character for that string, then a literal byte for the character value can be placed in the format string:

fprintf(display, "Here's a custom character: \x1\n");

The hd44780_blinky and hd44780_lcd_character examples both demonstrate the use of custom characters.

The hd44780_lcd_character example also demonstrates the use of cowpi_font_ascii_to_5wide_dotmatrix(). As noted in HD44780-driven LCD Character Display, there are a few ASCII character values that the HD44780 uses for characters other than the corresponding ASCII characters, such as \. You can overcome this by using cowpi_font_ascii_to_5wide_dotmatrix() to obtain a sequence of bytes that correspond to the ASCII character, packaged in an array that cowpi_hd44780_create_character() can make use of.

Note

In the future we anticipate providing Special Functions to eliminate the need to most application programmers to use even these two lower-level functions.

Special Functions

The CowPi_stdio library provides three functions that take a FILE * argument and performs certain actions on the display. The cowpi_clear_display(), cowpi_sleep_display(), and cowpi_wake_display() functions perform actions that otherwise would require using lower-level cowpi_max7219_XXX or cowpi_hd44780_XXX functions but do so in a way that do not risk unpredictable behavior. We summarize them here.

void cowpi_clear_display(FILE *filestream)

Removes the contents of the display module and places the cursor in the home position.

Parameters:

filestream – a pointer to the FILE stream for the display module to be cleared

void cowpi_sleep_display(FILE *filestream)

Places a display module in a low-power state.

If the display module has a low-power mode that preserves the contents of the display, then this function will place the display module in that mode.

Parameters:

filestream – a pointer to the FILE stream for the display module to be placed in a low-power state

void cowpi_wake_display(FILE *filestream)

Takes a display module out of a low-power state.

If the display module has a low-power mode that preserves the contents of the display, then this function will take the display out of that mode, restoring the display’s contents.

Parameters:

filestream – a pointer to the FILE stream for the display module to be brought out of a low-power state

Table 5 Behavior of special functions

	cowpi_clear_display()	cowpi_sleep_display()	cowpi_wake_display()
USB connection to host computer	ignored	ignored	ignored
7-segment display	Removes all displayed characters and performs a form feed	Places MAX7219 in “shutdown” mode	Takes MAX7219 out of “shutdown” mode
LED matrix display	Prints remaining characters that are in the buffer and performs a form feed	Places MAX7219 in “shutdown” mode	Takes MAX7219 out of “shutdown” mode
LCD character display	Removes all displayed characters and performs a form feed	Disables backlight	Enables backlight
Morse Code	ignored	ignored	ignored