From f84eb1ddda358fa2e28a8781736921df0b8d2dc6 Mon Sep 17 00:00:00 2001 From: "Collin J. Doering" Date: Thu, 15 Oct 2015 00:26:46 -0400 Subject: [PATCH] Comment and clean-up lcdLib.c and lcdLib.h Signed-off-by: Collin J. Doering --- lcdLib.c | 53 +++++++++++++++++++++++++++++++++++++++++++---------- lcdLib.h | 10 +++++++--- 2 files changed, 50 insertions(+), 13 deletions(-) diff --git a/lcdLib.c b/lcdLib.c index 41b30ff..4456cb7 100644 --- a/lcdLib.c +++ b/lcdLib.c @@ -33,8 +33,8 @@ volatile uint8_t currentLineChars = 0; const uint8_t lineBeginnings[LCD_NUMBER_OF_LINES] = { LCD_LINE_BEGINNINGS }; //------------------------------------------------------------------------------------------ - // Function definitions + void flashLED(uint8_t times) { while (times > 0) { STATUS_LED_PORT |= 1 << STATUS_LED; // turn on status LED @@ -100,10 +100,6 @@ void loop_until_LCD_BF_clear(void) { } #ifdef FOUR_BIT_MODE -/* - Writes one nibble to the LCD data bus. Does not touch the RS or RW control lines. - Note: the bits that are sent are the four MSBs of the given argument - */ void writeLCDNibble_(uint8_t b) { // Reset data lines to zeros LCD_DBUS7_PORT &= ~(1 << LCD_DBUS7); @@ -122,9 +118,6 @@ void writeLCDNibble_(uint8_t b) { } #endif -/* - Write a byte to the LCD data bus. Does not touch the RS or RW control lines. -*/ void writeLCDByte_(uint8_t b) { #ifdef FOUR_BIT_MODE writeLCDNibble_(b); @@ -157,9 +150,15 @@ void writeLCDByte_(uint8_t b) { #endif } +/* + Sets RS=RW=0 and writes the given 8 bit integer to the LCD databus. In the default 8-bit mode + and EIGHT_BIT_ARBITRARY_PIN_MODE, the given data is written in one cycle using the + writeLCDByte_ function. In FOUR_BIT_MODE however, the given data is written in two cycles + using two successive calls to the writeLCDNibble_ function. + */ void writeLCDInstr_(uint8_t instr) { -LCD_RS_PORT &= ~(1 << LCD_RS); // RS=0 -LCD_RW_PORT &= ~(1 << LCD_RW); // RW=0 + LCD_RS_PORT &= ~(1 << LCD_RS); // RS=0 + LCD_RW_PORT &= ~(1 << LCD_RW); // RW=0 #ifdef FOUR_BIT_MODE writeLCDNibble_(instr); @@ -174,6 +173,12 @@ void writeLCDInstr(uint8_t instr) { writeLCDInstr_(instr); } +/* + Sets RS=1, RW=0 and accepts a char (8 bit) and outputs it to the current cursor position of + the LCD. In the default 8-bit mode and EIGHT_BIT_ARBITRARY_PIN_MODE, the given data is + written in one cycle using the writeLCDByte_ function. In FOUR_BIT_MODE however, the given + data is written in two cycles using two successive calls to the writeLCDNibble_ function. + */ void writeCharToLCD_(char c) { LCD_RS_PORT |= (1 << LCD_RS); // RS=1 LCD_RW_PORT &= ~(1 << LCD_RW); // RW=0 @@ -186,6 +191,22 @@ void writeCharToLCD_(char c) { #endif } +/* + Given a single character, checks whether its a ASCII escape and does the following: + + - Newline '\n': moves the cursor to the next physical line of the LCD display; if the cursor is on + the last line of the display, clears the display and positions the cursor at the top left + of the LCD + - Carriage return '\r': moves the cursor to the beginning of the current line + - Backspace '\b': moves the cursor one position backwards, wrapping to the end of the + previous line when at the beginning of a line (other then the first one). A space is then + inserted to replace the character at point, without moving the cursor. When the cursor is + at the beginning of the first line, does nothing. + - Form feed '\f': clears the LCD display and places the cursor at the beginning of the first line. + - Alarm '\a': ignored + + Any other character is sent to the LCD display using writeCharToLCD_. + */ void writeCharToLCD(char c) { switch (c) { case '\n': // Line feed @@ -249,6 +270,10 @@ void writeStringToLCD(const char* str) { } } +/* + Writes the CMD_CLEAR_DISPLAY command to the LCD using writeLCDINSTR, and clears the local + char and line counters. + */ void clearDisplay(void) { writeLCDInstr(CMD_CLEAR_DISPLAY); @@ -257,6 +282,10 @@ void clearDisplay(void) { currentLineChars = 0; } +/* + Writes the CMD_RETURN_HOME command to the LCD using writeLCDInstr, and clears the local char + and line counters. + */ void returnHome(void) { writeLCDInstr(CMD_RETURN_HOME); @@ -325,6 +354,10 @@ static inline void disableLCDOutput(void) { #endif } +/* + Set RS=RW=0 and write the CMD_INIT command to the LCD data bus. Note that an appropriate + pause must follow before sending new commands to the LCD using writeLCD*_ functions. + */ static inline void softwareLCDInitPulse(void) { enableLCDOutput(); LCD_RS_PORT &= ~(1 << LCD_RS); // RS=0 diff --git a/lcdLib.h b/lcdLib.h index 6e33837..01819f5 100644 --- a/lcdLib.h +++ b/lcdLib.h @@ -84,21 +84,24 @@ void flashLED(uint8_t times); */ void clkLCD(void); +/* + Wait until LCD_BF (busy flag) is cleared (low). + */ void loop_until_LCD_BF_clear(void); -#ifdef FOUR_BIT_MODE /* Given a 8 bit integer, writes the four MSB's (one nibble) to the LCD data bus. Note: this is only defined in FOUR_BIT_MODE */ +#ifdef FOUR_BIT_MODE void writeLCDNibble_(uint8_t); #endif /* Given an 8 bit integer, writes it to the LCD data bus. - Note that this function does not ensure the LCD is ready to accept new data and thus needs to + This function does not ensure the LCD is ready to accept new data and thus needs to be handled by the caller. */ void writeLCDByte_(uint8_t); @@ -127,7 +130,8 @@ void writeCharToLCD_(char); /* Writes a character to the LCD display at the current cursor position after the LCD display is - ready for new data. + ready for new data. Allows the following ASCII escapes: '\n', '\r', '\f' and '\b'; ignores + ASCII escape '\a'. */ void writeCharToLCD(char);