AIP31068 I2C LCD controller

Device driver for AIP31068. More...

Detailed Description

Device driver for AIP31068.

Author
Hendrik van Essen hendr.nosp@m.ik.v.nosp@m.e@fu-.nosp@m.berl.nosp@m.in.de

Files

file  aip31068_internal.h
 Internal definitions for the AIP31068 I2C LCD controller.
 
file  aip31068_params.h
 Default configuration for the AIP31068 I2C LCD controller.
 
file  aip31068_regs.h
 Register definitions for the AIP31068 I2C LCD controller.
 
file  aip31068.h
 

Data Structures

struct  aip31068_params_t
 AIP31068 device initialization parameters. More...
 
struct  aip31068_t
 AIP31068 PWM device data structure type. More...
 

Enumerations

enum  aip31068_custom_symbol_t {
  CUSTOM_SYMBOL_1 = 0, CUSTOM_SYMBOL_2 = 1, CUSTOM_SYMBOL_3 = 2, CUSTOM_SYMBOL_4 = 3,
  CUSTOM_SYMBOL_5 = 4, CUSTOM_SYMBOL_6 = 5, CUSTOM_SYMBOL_7 = 6, CUSTOM_SYMBOL_8 = 7
}
 Keys for custom symbols. More...
 
enum  aip31068_text_insertion_mode_t { LEFT_TO_RIGHT, RIGHT_TO_LEFT }
 Defines the direction of the text insertion. More...
 
enum  aip31068_font_size_t { FONT_SIZE_5x8, FONT_SIZE_5x10 }
 Size of a character of the display in dots/pixels. More...
 
enum  aip31068_bit_mode_t { BITMODE_4_BIT, BITMODE_8_BIT }
 Bit mode for the display. More...
 

Functions

int aip31068_init (aip31068_t *dev, const aip31068_params_t *params)
 Initialization. More...
 
int aip31068_turn_on (aip31068_t *dev)
 Turn on the display. More...
 
int aip31068_turn_off (aip31068_t *dev)
 Turn off the display. More...
 
int aip31068_clear (aip31068_t *dev)
 Clear the display and set the cursor to position (0, 0). More...
 
int aip31068_return_home (aip31068_t *dev)
 Reset cursor position to (0, 0) and scroll display to original position. More...
 
int aip31068_set_auto_scroll_enabled (aip31068_t *dev, bool enabled)
 Enable or disable automated scrolling. More...
 
int aip31068_set_cursor_blinking_enabled (aip31068_t *dev, bool enabled)
 Enable or disable cursor blinking. More...
 
int aip31068_set_cursor_visible (aip31068_t *dev, bool visible)
 Show or hide the cursor. More...
 
int aip31068_set_cursor_position (aip31068_t *dev, uint8_t row, uint8_t col)
 Move the cursor to a given position. More...
 
int aip31068_set_text_insertion_mode (aip31068_t *dev, aip31068_text_insertion_mode_t mode)
 Set the direction from which the text is inserted, starting from the cursor. More...
 
int aip31068_move_cursor_left (aip31068_t *dev)
 Move the cursor one unit to the left. More...
 
int aip31068_move_cursor_right (aip31068_t *dev)
 Move the cursor one unit to the right. More...
 
int aip31068_scroll_display_left (aip31068_t *dev)
 Scroll the entire display content (all lines) one unit to the left. More...
 
int aip31068_scroll_display_right (aip31068_t *dev)
 Scroll the entire display content (all lines) one unit to the right. More...
 
int aip31068_set_custom_symbol (aip31068_t *dev, aip31068_custom_symbol_t customSymbol, const uint8_t charmap[])
 Create a custom symbol. More...
 
int aip31068_print_custom_symbol (aip31068_t *dev, aip31068_custom_symbol_t customSymbol)
 Print a custom symbol by key reference. More...
 
int aip31068_print (aip31068_t *dev, const char *data)
 Print a string. More...
 
int aip31068_print_char (aip31068_t *dev, char c)
 Print a single character. More...
 

Enumeration Type Documentation

◆ aip31068_bit_mode_t

Bit mode for the display.

Enumerator
BITMODE_4_BIT 

Use 4 bit mode.

BITMODE_8_BIT 

Use 8 bit mode.

Definition at line 69 of file aip31068.h.

◆ aip31068_custom_symbol_t

Keys for custom symbols.

Enumerator
CUSTOM_SYMBOL_1 

1st custom symbol

CUSTOM_SYMBOL_2 

2nd custom symbol

CUSTOM_SYMBOL_3 

3rd custom symbol

CUSTOM_SYMBOL_4 

4th custom symbol

CUSTOM_SYMBOL_5 

5th custom symbol

CUSTOM_SYMBOL_6 

6th custom symbol

CUSTOM_SYMBOL_7 

7th custom symbol

CUSTOM_SYMBOL_8 

8th custom symbol

Definition at line 36 of file aip31068.h.

◆ aip31068_font_size_t

Size of a character of the display in dots/pixels.

Enumerator
FONT_SIZE_5x8 

Single character has 5x8 pixels.

FONT_SIZE_5x10 

Single character has 5x10 pixels.

Definition at line 61 of file aip31068.h.

◆ aip31068_text_insertion_mode_t

Defines the direction of the text insertion.

Starting from the cursor, either increment the column of the cursor position after insertion (LEFT_TO_RIGHT), or decrement the current column of the cursor position after insertion (RIGHT_TO_LEFT).

Enumerator
LEFT_TO_RIGHT 

Insert text from left to right.

RIGHT_TO_LEFT 

Insert text from right to left.

Definition at line 53 of file aip31068.h.

Function Documentation

◆ aip31068_clear()

int aip31068_clear ( aip31068_t dev)

Clear the display and set the cursor to position (0, 0).

Note
: Also changes to setTextInsertionMode(LEFT_TO_RIGHT)
Parameters
[in]devDevice descriptor of the AIP31068
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_init()

int aip31068_init ( aip31068_t dev,
const aip31068_params_t params 
)

Initialization.

Parameters
[in]devDevice descriptor of the AIP31068
[in]paramsParameters for device initialization
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_move_cursor_left()

int aip31068_move_cursor_left ( aip31068_t dev)

Move the cursor one unit to the left.

When the cursor passes the 40th character of the first line and a second line is available, the cursor will move to the second line.

Parameters
[in]devDevice descriptor of the AIP31068
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_move_cursor_right()

int aip31068_move_cursor_right ( aip31068_t dev)

Move the cursor one unit to the right.

When the cursor passes the 40th character of the first line and a second line is available, the cursor will move to the second line.

Note
: The cursor respects the setting for the insertion mode and is set to (1, 0) for LEFT_TO_RIGHT and to (1, COL_MAX) for RIGHT_TO_LEFT.
Parameters
[in]devDevice descriptor of the AIP31068
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_print()

int aip31068_print ( aip31068_t dev,
const char *  data 
)

Print a string.

Parameters
[in]devDevice descriptor of the AIP31068
[in]dataString to be printed (null-terminated)
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_print_char()

int aip31068_print_char ( aip31068_t dev,
char  c 
)

Print a single character.

Parameters
[in]devDevice descriptor of the AIP31068
[in]cCharacter to be printed
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_print_custom_symbol()

int aip31068_print_custom_symbol ( aip31068_t dev,
aip31068_custom_symbol_t  customSymbol 
)

Print a custom symbol by key reference.

Parameters
[in]devDevice descriptor of the AIP31068
[in]customSymbolKey of the custom symbol to be printed
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_return_home()

int aip31068_return_home ( aip31068_t dev)

Reset cursor position to (0, 0) and scroll display to original position.

Parameters
[in]devDevice descriptor of the AIP31068
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_scroll_display_left()

int aip31068_scroll_display_left ( aip31068_t dev)

Scroll the entire display content (all lines) one unit to the left.

Note
: The cursor respects the setting for the insertion mode and is set to (1, 0) for LEFT_TO_RIGHT and to (1, COL_MAX) for RIGHT_TO_LEFT.
Parameters
[in]devDevice descriptor of the AIP31068
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_scroll_display_right()

int aip31068_scroll_display_right ( aip31068_t dev)

Scroll the entire display content (all lines) one unit to the right.

Parameters
[in]devDevice descriptor of the AIP31068
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_set_auto_scroll_enabled()

int aip31068_set_auto_scroll_enabled ( aip31068_t dev,
bool  enabled 
)

Enable or disable automated scrolling.

Parameters
[in]devDevice descriptor of the AIP31068
[in]enabledEnable or disable
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_set_cursor_blinking_enabled()

int aip31068_set_cursor_blinking_enabled ( aip31068_t dev,
bool  enabled 
)

Enable or disable cursor blinking.

Parameters
[in]devDevice descriptor of the AIP31068
[in]enabledEnable or disable
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_set_cursor_position()

int aip31068_set_cursor_position ( aip31068_t dev,
uint8_t  row,
uint8_t  col 
)

Move the cursor to a given position.

Parameters
[in]devDevice descriptor of the AIP31068
[in]rowRow of the new cursor position (starting at 0)
[in]colColumn of the new cursor position (starting at 0)
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_set_cursor_visible()

int aip31068_set_cursor_visible ( aip31068_t dev,
bool  visible 
)

Show or hide the cursor.

Parameters
[in]devDevice descriptor of the AIP31068
[in]visibleShow or hide
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_set_custom_symbol()

int aip31068_set_custom_symbol ( aip31068_t dev,
aip31068_custom_symbol_t  customSymbol,
const uint8_t  charmap[] 
)

Create a custom symbol.

Useful link: https://maxpromer.github.io/LCD-Character-Creator/

Parameters
[in]devDevice descriptor of the AIP31068
[in]customSymbolKey to which a custom symbol should be assigned
[in]charmapBitmap definition of the custom symbol
Note
: The size of charmap depends on how the AIP31068 was initialized. 8 bytes for FONT_SIZE_5x8 and 10 bytes for FONT_SIZE_5x10.

This function resets the cursor position. Therefore this function should be called before printing any characters to the display.

Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_set_text_insertion_mode()

int aip31068_set_text_insertion_mode ( aip31068_t dev,
aip31068_text_insertion_mode_t  mode 
)

Set the direction from which the text is inserted, starting from the cursor.

Parameters
[in]devDevice descriptor of the AIP31068
[in]modeInsertion mode
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_turn_off()

int aip31068_turn_off ( aip31068_t dev)

Turn off the display.

Parameters
[in]devDevice descriptor of the AIP31068
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs

◆ aip31068_turn_on()

int aip31068_turn_on ( aip31068_t dev)

Turn on the display.

Parameters
[in]devDevice descriptor of the AIP31068
Return values
0on success
-1if acquiring of I2C bus fails
-EIOWhen slave device doesn't ACK the byte
-ENXIOWhen no devices respond on the address sent on the bus
-ETIMEDOUTWhen timeout occurs before device's response
-EINVALWhen an invalid argument is given
-EOPNOTSUPPWhen MCU driver doesn't support the flag operation
-EAGAINWhen a lost bus arbitration occurs