Functions for Direct Control of Display Modules 

Functions for Direct Control of Communication Protocols 

communication.h 

Public-facing type definitions and function pointers for SPI & I2C.

Enums

enum bit_order_t

Indicates whether a byte’s bits should be transmitted least- or most-significant bit first.

Values:

enumerator COWPI_LSB_FIRST

enumerator COWPI_MSB_FIRST

Functions

bool cowpi_use_spi_hardware()

Assigns to cowpi_spi_initialize, cowpi_spi_transmit, and cowpi_spi_finalize implementations that use the microcontroller’s built-in SPI hardware.

Using the SPI hardware may limit the choice of data and clock pins. Attempting to use the SPI hardware while specifying pins that cannot be used by the SPI hardware may result in unexpected behavior.

The CowPi_stdio library does not have SPI hardware implementations for all microcontrollers. If a hardware implementation is unavailable, this function will return false and will assign a bit-banged implementation instead.

Returns:: true if hardware implementations have been assigned to the CowPi’s SPI function pointers
Returns:: false if hardware implementations have not been assigned to the CowPi’s SPI function pointers

void cowpi_use_spi_bitbang()

Assigns to cowpi_spi_initialize, cowpi_spi_transmit, and cowpi_spi_finalize pure software (“bit-banged”) implementations that do not use the microcontroller’s built-in SPI hardware.

Bit-banged implementations have no restrictions on the choice of data and clock pins.

int8_t cowpi_discover_i2c_address(uint8_t i2c_data_pin, uint8_t i2c_clock_pin)

Reports the address of the I2C peripheral if there is exactly one I2C peripheral attached to the designated pins.

Parameters:

i2c_data_pin – the I2C serial data pin
i2c_clock_pin – the I2C serial clock pin

Returns:

0 if no I2C peripherals are detected
-1 if multiple I2C peripherals are detected
the peripheral’s I2C address otherwise

bool cowpi_use_i2c_hardware()

Assigns to cowpi_i2c_initialize, cowpi_i2c_transmit, and cowpi_i2c_finalize implementations that use the microcontroller’s built-in I2C (aka IIC, aka TWI) hardware.

Using the I2C hardware may limit the choice of data and clock pins. Attempting to use the I2C hardware while specifying pins that cannot be used by the I2C hardware may result in unexpected behavior.

The CowPi_stdio library does not have I2C hardware implementations for all microcontrollers. If a hardware implementation is unavailable, this function will return false and will assign a bit-banged implementation instead.

Returns:: true if hardware implementations have been assigned to the CowPi’s I2C function pointers
Returns:: false if hardware implementations have not been assigned to the CowPi’s I2C function pointers

void cowpi_use_i2c_bitbang()

Assigns to cowpi_i2c_initialize, cowpi_i2c_transmit, and cowpi_i2c_finalize pure software (“bit-banged”) implementations that do not use the microcontroller’s built-in I2C hardware.

Bit-banged implementations have no restrictions on the choice of data and clock pins.

Variables

void (*cowpi_spi_initialize)(const cowpi_display_module_protocol_t *configuration, bit_order_t bit_order)

Function pointer for function that takes care of any setup needed before using SPI to send data to a display module.

The particulars of what this setup is depends on the particular SPI implementation.

See also

cowpi_spi_transmit

See also

cowpi_spi_finalize

Param configuration:: the pins used for SPI
Param bit_order:: indicates whether the peripheral expects the byte to arrive LSB first or MSB first

void (*cowpi_spi_transmit)(uint8_t byte)

Function pointer for function that uses SPI to send data to a display module.

This might be a pre-defined implementation that uses the microcontroller’s SPI hardware, or it might be a pre-defined bit-bang implementation.

See also

cowpi_spi_initialize

See also

cowpi_spi_finalize

Param byte:: the byte to be transmitted to the peripheral

void (*cowpi_spi_finalize)(void)

Function pointer for function that takes care of any teardown needed after using SPI to send data to a display module.

The particulars of what this teardown is depends on the particular SPI implementation.

See also

cowpi_spi_initialize

See also

cowpi_spi_transmit

bool (*cowpi_i2c_initialize)(const cowpi_display_module_protocol_t *configuration)

Function pointer for function that takes care of any setup needed before using I2C to send data to a display module.

This includes, but might not be limited to, transmitting the start bit and the peripheral’s address.

See also

cowpi_i2c_transmit

See also

cowpi_i2c_finalize

Param configuration:: the microcontroller pins, adapter mapping, and possibly i2c peripheral address
Return:: true if ACK received; false otherwise

bool (*cowpi_i2c_transmit)(uint8_t byte)

Function pointer for function that uses SPI to send data to a display module.

This might be a pre-defined implementation that uses the microcontroller’s SPI hardware, or it might be a pre-defined bit-bang implementation.

See also

cowpi_i2c_initialize

See also

cowpi_i2c_finalize

Param byte:: the byte to be transmitted to the peripheral
Return:: true if ACK received; false otherwise

void (*cowpi_i2c_finalize)(void)

Function pointer for function that takes care of any teardown needed after using SPI to send data to a display module.

This includes, but might not be limited to, transmitting the stop bit.

See also

cowpi_i2c_initialize

See also

cowpi_i2c_transmit

Functions for Direct Control of MAX7219-Controlled Display Modules 

max7219.h 

Utility functions for peripherals driven by MAX7219 such as 8-digit/7-segment display modules and 8x8 LED matrices.

The MAX7219 will initially be configured to use all eight digits (or all 8 rows in the case of an 8x8 LED matrix), intensity level 3 (7/32 of full brightness), no-decode, not shut-down, and not in test mode.

Author: Christopher A. Bohn

The MAX7219 is simple enough that firmware programs can send data (or commands) to it directly through cowpi_max7219_send(); however, convenient abstractions can also be built on top of cowpi_max7219_send().

Functions

void cowpi_setup_max7219(const cowpi_display_module_protocol_t *configuration)

Configures the MAX7219 to nominal settings.

Parameters:: configuration – the pins used for SPI

void cowpi_max7219_send(const cowpi_display_module_protocol_t *configuration, uint8_t address, uint8_t data)

Sends a byte of data to be placed in the specified MAX7219 register.

The firmware program should only need to send data to addresses 1-8, the digit registers. Most other registers are handled by specific cowpi_max7219 functions.

This is a portable software-only implementation; it does not use SPI hardware, nor does it use memory-mapped I/O of any form. Re-implementing this function (using a different function name) to use SPI hardware is a possible part of a memory-mapped I/O lab assignment.

Parameters:

configuration – the pins used for SPI
address – the register to be updated
data – the byte to place in that register

void cowpi_max7219_shutdown(const cowpi_display_module_protocol_t *configuration)

Shuts-down the MAX7219 display module.

This function places a 0 in the MAX7219’s Shutdown register, causing the display to blank. Data in the digit and control registers remain unchanged.

See also

cowpi_max7219_startup

Parameters:: configuration – the pins used for SPI

void cowpi_max7219_startup(const cowpi_display_module_protocol_t *configuration)

Takes the MAX7219 display module out of shutdown mode.

This function places a 1 in the MAX7219’s Shutdown register, causing the display to resume.

See also

cowpi_max7219_shutdown

Parameters:: configuration – the pins used for SPI

void cowpi_max7219_no_decode(const cowpi_display_module_protocol_t *configuration)

Takes the MAX7219 out of decode mode.

This function places 0 in the MAX7219’s Decode-Mode register, causing the display to map the data register bits directly to the digits’ segments.

See also

cowpi_max_bcd_decode

Parameters:: configuration – the pins used for SPI

void cowpi_max7219_bcd_decode(const cowpi_display_module_protocol_t *configuration)

Places the MAX7219 in decode mode.

This function places 0xFF in the MAX7219’s Decode-Mode register, causing the display to interpret the data register bits as BCD values and place the corresponding decimal numeral on the digits.

This function should not be called when using an 8x8 LED matrix — there’s no harm in doing so, but decode mode really is meant for 7-segment displays.

See also

cowpi_max_bcd_decode

Parameters:: configuration – the pins used for SPI

void cowpi_max7219_set_intensity(const cowpi_display_module_protocol_t *configuration, uint8_t intensity)

Sets the MAX7219 display module’s brightness level.

This function places the argument in the MAX7219’s Intensity register. The MAX7219 ignores the upper four bits, so there are 16 levels of brightness.

Parameters:

configuration – the pins used for SPI
intensity – the desired brightness level

Functions for Direct Control of HD44780-Controlled Display Modules 

hd44780.h 

Utility functions for peripherals driven by HD44780 such as 16x2 and 20x4 LCD character display modules.

The HD44780 will initially be placed in 4-bit mode, and:

With each character, increment the cursor’s location but do not shift the display
Turn the display on, the cursor off, and no blinking
Clear the display

Author: Christopher A. Bohn

The HD44780 is complex enough that the firmware program should call cowpi_hd44780_send_command(), cowpi_hd44780_send_character(), or another more-specific function. These functions will take care of dividing the data into halfbytes, managing timing, and other complexities, and will call cowpi_hd44780_send_halfbyte().

Unlike the MAX7219 and the SSD1306, the HD44780 does not handle serial communication on its own and requires a serial adapter. The mapping between the byte sent from the program and the lines on the display module is specified by the adapter_mapping field in the functions’ cowpi_display_module_protocol_t argument

Defines

LCDENTRY_CURSORMOVESRIGHT: Instructs the display module to shift the cursor right after a character is displayed.

LCDENTRY_CURSORMOVESLEFT: Instructs the display module to shift the cursor left after a character is displayed.

LCDENTRY_TEXTSHIFTS: Instructs the display module to shift the entire display after a character is displayed.

LCDENTRY_TEXTNOSHIFT: Instructs the display module not to shift the display after a character is displayed.

LCDONOFF_DISPLAYON: Instructs the display module to turn on the display.

LCDONOFF_DISPLAYOFF: Instructs the display module to turn off the display.

LCDONOFF_CURSORON: Instructs the display module to turn on the underscore cursor.

LCDONOFF_CURSOROFF: Instructs the display module to turn off the underscore cursor.

LCDONOFF_BLINKON: Instructs the display module to blink the cursor’s position.

LCDONOFF_BLINKOFF: Instructs the display module not to blink the cursor’s position.

LCDSHIFT_DISPLAYLEFT: Shifts the entire display to the left.

LCDSHIFT_DISPLAYRIGHT: Shifts the entire display to the right.

LCDSHIFT_CURSORLEFT: Shifts the cursor to the left.

LCDSHIFT_CURSORRIGHT: Shifts the cursor to the right.

Typedefs

typedef void (*cowpi_hd44780_send_halfbyte_t)(const cowpi_display_module_protocol_t *configuration, uint8_t halfbyte, bool is_command)

Pointer to function that sends a halfbyte to the HD44780 character display.

The cowpi_hd44780 utility functions all make use of the cowpi_hd44780_send_halfbyte() function pointer.

Initially, cowpi_hd44780_send_halfbyte() is one of two default implementations, depending on whether the communication protocol is SPI or I2C.

Re-implementing this function to use SPI or I2C hardware is a possible part of a memory-mapped I/O lab assignment.

SPI: Assumes the display module’s data-in line is connected to the microcontroller’s COPI pin (D11 on most Arduino boards), the display module’s serial-clock line is connected to the microcontroller’s SCK pin (D13 on most Arduino boards), and the display module’s chip-select line is connected to Arduino pin D10.

I2C: Assumes the display module’s data line is connected to the microcontroller’s SDA pin (D18 on most Arduino boards) and the display module’s serial-clock line is connected to the microcontroller’s SCL pin (D19 on most Arduino boards).

See also

cowpi_hd44780_send_halfbyte

Param configuration:: the microcontroller pins, adapter mapping, and possibly i2c peripheral address
Param halfbyte:: the data to be sent to the display module
Param is_command:: indicates whether the data is part of a command (true) or part of a character (false)

Functions

void cowpi_setup_hd44780(const cowpi_display_module_protocol_t *configuration)

Configures the HD44780 to nominal settings.

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

void cowpi_hd44780_set_send_halfbyte_function(cowpi_hd44780_send_halfbyte_t send_halfbyte_function)

Reassigns the cowpi_hd44780_send_halfbyte function pointer to point to the specified function.

During setup, this function is used to assign one of the two default cowpi_hd44780_send_halfbyte_t implementations to cowpi_hd44780_send_halfbyte, unless it was previously used to assign a re-implementation. It can also later be used to assign a re-implementation.

Deprecated:: Make assignments directly to cowpi_hd44780_send_halfbyte

Parameters:: send_halfbyte_function – the function to be used to send halfbytes to the HD44780 character display

void cowpi_hd44780_place_character(const cowpi_display_module_protocol_t *configuration, uint8_t address, uint8_t character)

Places the specified character on the display at the specified location.

The character is an ASCII or “extended-ASCII” character, or a custom character created by using cowpi_hd44780_create_character().

Note that the base address of the top row is 0x00, and the base address of the bottom row is 0x40.

Parameters:

configuration – the microcontroller pins, adapter mapping, and possibly i2c peripheral address
address – the address of the desired location
character – the character to be displayed

void cowpi_hd44780_place_cursor(const cowpi_display_module_protocol_t *configuration, uint8_t address)

Places the cursor at the specified location without updating the display.

While the cursor will move to the specified location, it will only be visibly there if the cursor is on.

Note that the base address of the top row is 0x00, and the base address of the bottom row is 0x40.

Parameters:

configuration – the microcontroller pins, adapter mapping, and possibly i2c peripheral address
address – the address of the desired location

void cowpi_hd44780_send_command(const cowpi_display_module_protocol_t *configuration, uint8_t command)

Sends a command to the HD44780 character display.

The command is a bitwise disjunction of named constants to specify the entry mode (cursor and text movement to occur after characters are sent), a disjunction of named constants to specify the display mode (whether the display is on, whether the underscore cursor is displayed, and whether the cursor’s location blinks), or one shift command (shift display left/right or shift cursor left/right).

Parameters:

configuration – the microcontroller pins, adapter mapping, and possibly i2c peripheral address
command – constant(s) that specify the entry mode, display mode, or shift command

void cowpi_hd44780_send_character(const cowpi_display_module_protocol_t *configuration, uint8_t character)

Displays a character at the cursor’s location on the HD44780 character display.

The character is an ASCII or “extended-ASCII” character, or one of the eight custom characters created by using cowpi_hd44780_create_character().

Parameters:

configuration – the microcontroller pins, adapter mapping, and possibly i2c peripheral address
character – the character to be displayed

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.

void cowpi_hd44780_clear_display(const cowpi_display_module_protocol_t *configuration)

Clears the display and places the cursor in row 0, column 0.

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

void cowpi_hd44780_return_home(const cowpi_display_module_protocol_t *configuration)

Places the cursor in row 0, column 0.

If the display was shifted, the display is shifted back to its original position. The contents of each character position remain unchanged.

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

void cowpi_hd44780_set_backlight(const cowpi_display_module_protocol_t *configuration, bool backlight_on)

Turns the display module’s backlight on or off.

Parameters:

configuration – the microcontroller pins, adapter mapping, and possibly i2c peripheral address
backlight_on – indicates whether the backlight should be on (true) or off (false)

Functions for Working with the CowPi_stdio Font Glyphs 

font_7segment.h 

Provides a font to display approximations of printable ASCII characters on 7-segment displays.

The mapping of bits to segment lines is:

 --A--
|     |
F     B
|     |              bit      7 6 5 4 3 2 1 0
 --G--           segment     DP A B C D E F G
|     |
E     C
|     |
 --D--   (DP)

If your display follows the same mapping, you can use the functions’ outputs directly. If the endianness of segments A-G are the same but your decimal point is bit 0, then you can left-shift the functions’ outputs by 1 and only certain punctuation characters will be improperly displayed. If the mapping is any further off, then you will likely not be able to use these functions.

Author: Christopher A. Bohn

Functions

uint8_t cowpi_font_ascii_to_7segment(char c)

Provides the 7-segment bit vector for an ASCII character or for a hexadecimal numeral.

For hexadecimal numerals 0x0-0xF, returns a bit vector to display that numeral on a 7-segment display. For the printable ASCII characters 0x20-0x7E, returns a bit vector to display an approximation of that character on a 7-segment display. Values in the range 0x10-0x1F, and 0x7F (DEL) return 0xFF, which will illuminate all segments.

The bit vector is guaranteed to work for a 7-segment display whose segments are mapped to bits in the manner specified in the MAX7219/MAX7221 datasheet (MSB DP-A-B-C-D-E-F-G LSB).

Parameters:: c – the ASCII character whose 7-segment bit vector is to be provided
Returns:: a 7-segment bit vector

uint8_t *cowpi_font_string_to_7segment(uint8_t *destination, const char *s)

Provides an array of 7-segment bit vectors for an ASCII character string.

The source string, s, is assumed to be NUL-terminated.

The destination array is assumed to point to a block of memory with strlen(s) bytes allocated; that is, it must have enough space to hold the array of bit vectors.

Note

The array of bit vectors will not be NUL-terminated.

Parameters:

destination – an empty array of sufficient size to hold the bit vectors
s – the string to be converted into 7-segment bit vectors

Returns:

destination, with the requested bit vectors

font_dotmatrix.h 

Provides a font to display printable ASCII characters on dot-matrix displays.

All characters are guaranteed to occupy a rectangle no greater than 8 rows by 5 columns.

Author: Christopher A. Bohn

Functions

int8_t cowpi_font_get_dotmatrix_width(char c)

Provides the minimum number of columns needed to represent a character in the dot matrix font.

Parameters:: c – the character whose width is to be determined
Returns:: the dot matrix width of the character

uint8_t *cowpi_font_ascii_to_narrow_dotmatrix(uint8_t *destination, char c)

Provides the dot matrix representation of an ASCII character with no blank columns to the right of the character.

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. Each bit position in an array element represents a column.

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

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

uint8_t *cowpi_font_ascii_to_8wide_dotmatrix(uint8_t *destination, char c)

Provides the dot matrix representation of an ASCII character centered horizontally in the eight 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_5wide_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

uint8_t *cowpi_font_transpose_dotmatrix(uint8_t *matrix)

Transposes an 8x8 dot matrix representation.

After the transposition, each element of the matrix array represents a column, and each bit position of an array element represents a row.

This is an in-place transposition; that is, the original matrix is overwritten.

Parameters:: matrix – the dot matrix to be transposed
Returns:: matrix after the transposition

int cowpi_font_string_to_horizontal_dotmatrix(uint8_t *destination, const char *s, bool kerned)

Provides a single dot matrix representation of an ASCII character string suitable for scrolling horizontally.

Each byte of the destination array stores one column of the string’s dot matrix representation, with element 0 being the leftmost column of the first character.

The destination array is assumed to point to a block of memory with sufficient space allocated to hold the full string’s dot matrix representation; 6 * strlen(s) is guaranteed to be sufficient.

Parameters:

destination – an empty array to hold the dot matrix representation
s – the ASCII string whose dot matrix representation is to be provided
kerned – indicates whether to use minimal space between characters or to use a fixed 5 columns per character

Returns:

the number of columns in the string’s dot matrix representation

int cowpi_font_string_to_vertical_dotmatrix(uint8_t *destination, const char *s, bool kerned)

Provides a single dot matrix representation of an ASCII character string suitable for scrolling vertically.

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

The destination array is assumed to point to a block of memory with sufficient space allocated to hold the full string’s dot matrix representation; 9 * strlen(s) is guaranteed to be sufficient.

Parameters:

destination – an empty array to hold the dot matrix representation
s – the ASCII string whose dot matrix representation is to be provided
kerned – indicates whether to use minimal space between characters or to use a fixed 8 rows per character

Returns:

the number of rows in the string’s dot matrix representation

font_morse_code.h 

Provides a “font” to drive the dits and dahs of a Morse Code illuminator or sounder.

Author: Christopher A. Bohn

Enums

enum [anonymous]

Symbols used in Morse Code.

Values:

enumerator END_OF_CHARACTER

enumerator SYMBOL_SPACE

enumerator CHARACTER_SPACE

enumerator WORD_SPACE

enumerator DIT

enumerator DAH

Functions

uint8_t *cowpi_font_ascii_to_morse_code(uint8_t *destination, char c)

Provides the series of DITs and DAHs to represent an ASCII character in Morse Code.

Each byte of the destination array stores a DIT, a DAH, a SYMBOL_SPACE (the pause between dits/dahs), a CHARACTER_SPACE (the pause between letters), a WORD_SPACE (the pause between words), or an END_OF_CHARACTER (a terminating NUL).

In most cases, a 9-byte destination array will be sufficient; however, if c is a percent sign (%’) then 18 bytes will be required for the destination` array.

Parameters:

destination – an empty 8-byte array
c – the ASCII character whose Morse Code representation is to be provided

Returns:

destination, with the requested series of Morse symbols