329 lines
9.7 KiB
C
329 lines
9.7 KiB
C
/**
|
|
* (C) Copyright Collin J. Doering 2015
|
|
*
|
|
* This program is free software: you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation, either version 3 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
*/
|
|
|
|
/**
|
|
* @file lcdLib.h
|
|
* @author Collin J. Doering <collin.doering@rekahsoft.ca>
|
|
* @date Sep 29, 2015
|
|
* @brief Functions to initialize, and operate a character LCD.
|
|
*/
|
|
|
|
#ifndef LCD_LIB_H
|
|
#define LCD_LIB_H
|
|
|
|
// Includes -----------------------------------------------------------------------------------
|
|
#include "lcd_instr.h"
|
|
#include "lcdLibConfig.h"
|
|
|
|
//---------------------------------------------------------------------------------------------
|
|
// Library function declarations
|
|
|
|
/**
|
|
Initialize the LCD display via software initialization as specified by the datasheet.
|
|
*/
|
|
void initLCD(void);
|
|
|
|
/**
|
|
Writes a character to the LCD display at the current cursor position after the LCD display is
|
|
ready for new data. Allows the following ASCII escapes: '\n', '\r', '\f' and '\b'; ignores
|
|
ASCII escape '\a'.
|
|
*/
|
|
void writeCharToLCD(char);
|
|
|
|
/**
|
|
Writes a string to the LCD starting from the current cursor position.
|
|
*/
|
|
void writeStringToLCD(char*);
|
|
|
|
//---------------------------------------------------------------------------------------------
|
|
// LCD command functions (all have associated ANSI escape)
|
|
|
|
/**
|
|
Clears the display and positions the cursor in the top left of the LCD screen.
|
|
*/
|
|
void clearDisplay(void);
|
|
|
|
/**
|
|
Brings the cursor the the top left of the LCD screen.
|
|
*/
|
|
void returnHome(void);
|
|
|
|
/**
|
|
Gets the current row and column of the LCD cursor and sets given pointers row and column to
|
|
their respective values. Note indexes start at 1.
|
|
*/
|
|
void getCursorPosition(uint8_t* row, uint8_t* column);
|
|
|
|
/**
|
|
Using the given parameters row and column, sets the current row and column occupied by the LCD
|
|
cursor. Note indexes start at 1.
|
|
*/
|
|
void setCursorPosition(uint8_t row, uint8_t column);
|
|
|
|
/**
|
|
Moves the cursor n positions up. If the cursor is at the edge of the screen this has no effect.
|
|
*/
|
|
void moveCursorUp(uint8_t n);
|
|
|
|
/**
|
|
Moves the cursor n positions down. If the cursor is at the edge of the screen this has no effect.
|
|
*/
|
|
void moveCursorDown(uint8_t n);
|
|
|
|
/**
|
|
Moves the cursor n positions forward. If the cursor is at the edge of the screen this has no effect.
|
|
*/
|
|
void moveCursorForward(uint8_t n);
|
|
|
|
/**
|
|
Moves the cursor n positions backwards. If the cursor is at the edge of the screen this has no effect.
|
|
*/
|
|
void moveCursorBackward(uint8_t n);
|
|
|
|
/**
|
|
Moves the cursor to the beginning of the line n lines down.
|
|
*/
|
|
void moveCursorNextLine(uint8_t n);
|
|
|
|
/**
|
|
Moves the cursor to the beginning of the line n lines up.
|
|
*/
|
|
void moveCursorPreviousLine(uint8_t n);
|
|
|
|
/**
|
|
Moves the cursor to column n. If n is off screen go to the last line.
|
|
*/
|
|
void moveCursorToColumn(uint8_t n);
|
|
|
|
/**
|
|
Scroll whole page up by n lines. New lines are added at the bottom.
|
|
*/
|
|
void scrollUp(uint8_t n);
|
|
|
|
/**
|
|
Scroll whole page down by n lines. New lines are added at the top.
|
|
*/
|
|
void scrollDown(uint8_t n);
|
|
|
|
/**
|
|
Saves the cursors current position.
|
|
*/
|
|
void saveCursorPosition(void);
|
|
|
|
/**
|
|
Restores the last saved cursor position.
|
|
*/
|
|
void restoreCursorPosition(void);
|
|
|
|
/**
|
|
Clears part or all of screen dependent on the value of n:
|
|
0 or missing: clear from cursor to end of screen
|
|
1: clear from cursor to end of screen
|
|
2: clear entire screen
|
|
*/
|
|
void eraseDisplay(uint8_t n);
|
|
|
|
/**
|
|
Erases part of a line dependent on the value of n:
|
|
0 or missing: clear from cursor to end of the line
|
|
1: clear from cursor to beginning of the line
|
|
2: clear entire line
|
|
*/
|
|
void eraseInline(uint8_t n);
|
|
|
|
/**
|
|
Hides the cursor
|
|
*/
|
|
void hideCursor(void);
|
|
|
|
/**
|
|
Shows the cursor
|
|
*/
|
|
void showCursor(void);
|
|
|
|
//---------------------------------------------------------------------------------------------
|
|
// Utility functions (with no associated ASCII or ANSI escape)
|
|
|
|
/**
|
|
Turns the cursor blink off.
|
|
*/
|
|
void blinkCursorOff(void);
|
|
|
|
/**
|
|
Turns the cursor blink on.
|
|
*/
|
|
void blinkCursorOn(void);
|
|
|
|
/**
|
|
Turns the display off.
|
|
*/
|
|
void displayOff(void);
|
|
|
|
/**
|
|
Turns the display on.
|
|
*/
|
|
void displayOn(void);
|
|
|
|
//---------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
Read a single character from the row and column given (1 based) returning the cursor to
|
|
its previous original position.
|
|
*/
|
|
char readCharFromLCD(uint8_t row, uint8_t column);
|
|
|
|
/**
|
|
Read a line i (ones based) into str.
|
|
*/
|
|
void readLCDLine(uint8_t i, char* str);
|
|
|
|
//---------------------------------------------------------------------------------------------
|
|
// Advanced functions for special cases
|
|
|
|
/**
|
|
Read len characters from (from_row, from_column) to (to_row, to_column) returning the cursor
|
|
to its original position after the read. Upon success (not overflowing the screen), 0 is
|
|
returned; otherwise non zero will be returned. The str pointer will be updated with the
|
|
characters read from the screen. Even in the case of failure, str may be partially populated.
|
|
*/
|
|
void readCharsFromLCD(uint8_t from_row, uint8_t from_column, uint8_t to_row, uint8_t to_column, char* str, uint8_t len);
|
|
|
|
/**
|
|
Initialize the LCD display via its internal reset circuit.
|
|
|
|
Note: this is not the recommended way to initialize the LCD as it is unreliable and depends
|
|
on the power supply. Preferably the software initialization method should be used (via
|
|
the initLCD function).
|
|
*/
|
|
void initLCDByInternalReset(void);
|
|
|
|
|
|
//---------------------------------------------------------------------------------------------
|
|
// Mode and settings sanity check (preprocessor tests of lcdLibConfig.h)
|
|
//---------------------------------------------------------------------------------------------
|
|
|
|
#if !defined(LCD_CHARACTERS_PER_LINE)
|
|
#error "All modes require LCD_CHARACTERS_PER_LINE to be defined."
|
|
#elif !defined(LCD_NUMBER_OF_LINES)
|
|
#error "All modes require LCD_NUMBER_OF_LINES to be defined."
|
|
#elif !defined(LCD_LINE_BEGINNINGS)
|
|
#error "All modes require LCD_LINE_BEGINNINGS to be defined."
|
|
#else
|
|
|
|
#if LCD_NUMBER_OF_LINES == 1
|
|
#define LCD_LINES 0
|
|
#else
|
|
#define LCD_LINES (1 << INSTR_FUNC_SET_N)
|
|
#endif
|
|
|
|
#define LCD_CHARACTERS_PER_SCREEN (LCD_CHARACTERS_PER_LINE * LCD_NUMBER_OF_LINES)
|
|
#endif
|
|
|
|
#if !defined(LCD_FONT_5x8) &&\
|
|
!defined(LCD_FONT_5x10)
|
|
#error "All modes require LCD_FONT_5x8 or LCD_FONT_5x10 to be defined."
|
|
#elif defined(LCD_FONT_5x8) && \
|
|
defined(LCD_FONT_5x10)
|
|
#error "LCD_FONT_5x8 and LCD_FONT_5x10 are mutually exclusive. Choose one."
|
|
#elif defined(LCD_FONT_5x8)
|
|
#define LCD_FONT 0
|
|
#elif defined(LCD_FONT_5x10)
|
|
#define LCD_FONT (1 << INSTR_FUNC_SET_F)
|
|
#endif
|
|
|
|
#if !defined (LCD_RS) || \
|
|
!defined (LCD_RS_PORT) || \
|
|
!defined (LCD_RS_DDR) || \
|
|
!defined (LCD_RW) || \
|
|
!defined (LCD_RW_PORT) || \
|
|
!defined (LCD_RW_DDR) || \
|
|
!defined (LCD_ENABLE) || \
|
|
!defined (LCD_ENABLE_PORT) || \
|
|
!defined (LCD_ENABLE_DDR)
|
|
#error "All modes require LCD_RS[,_PORT,_DDR], LCD_RW[,_PORT,_DDR], and LCD_ENABLE[,_PORT,_DDR] be defined."
|
|
#endif
|
|
|
|
#if defined (EIGHT_BIT_ARBITRARY_PIN_MODE) && \
|
|
defined (FOUR_BIT_MODE)
|
|
#error "EIGHT_BIT_ARBITRARY_PIN_MODE and FOUR_BIT_MODE are mutually exclusive. Choose one."
|
|
#elif defined (EIGHT_BIT_ARBITRARY_PIN_MODE) || \
|
|
defined (FOUR_BIT_MODE)
|
|
|
|
// EIGHT_BIT_ARBITRARY_PIN_MODE specific requirements
|
|
#ifdef EIGHT_BIT_ARBITRARY_PIN_MODE
|
|
#if !defined (LCD_DBUS0) || \
|
|
!defined (LCD_DBUS0_PORT) || \
|
|
!defined (LCD_DBUS0_DDR) || \
|
|
!defined (LCD_DBUS0_PIN) || \
|
|
!defined (LCD_DBUS1) || \
|
|
!defined (LCD_DBUS1_PORT) || \
|
|
!defined (LCD_DBUS1_DDR) || \
|
|
!defined (LCD_DBUS1_PIN) || \
|
|
!defined (LCD_DBUS2) || \
|
|
!defined (LCD_DBUS2_PORT) || \
|
|
!defined (LCD_DBUS2_DDR) || \
|
|
!defined (LCD_DBUS2_PIN) || \
|
|
!defined (LCD_DBUS3) || \
|
|
!defined (LCD_DBUS3_PORT) || \
|
|
!defined (LCD_DBUS3_DDR) || \
|
|
!defined (LCD_DBUS3_PIN)
|
|
#error "EIGHT_BIT_ARBITRARY_PIN_MODE require that LCD_DBUS*[,_PORT,_DDR,_PIN] be defined."
|
|
#endif
|
|
#endif
|
|
|
|
// Requirements for EIGHT_BIT_ARBITRARY_PIN_MODE and FOUR_BIT_MODE
|
|
#if !defined (LCD_DBUS4) || \
|
|
!defined (LCD_DBUS4_PORT) || \
|
|
!defined (LCD_DBUS4_DDR) || \
|
|
!defined (LCD_DBUS4_PIN) || \
|
|
!defined (LCD_DBUS5) || \
|
|
!defined (LCD_DBUS5_PORT) || \
|
|
!defined (LCD_DBUS5_DDR) || \
|
|
!defined (LCD_DBUS5_PIN) || \
|
|
!defined (LCD_DBUS6) || \
|
|
!defined (LCD_DBUS6_PORT) || \
|
|
!defined (LCD_DBUS6_DDR) || \
|
|
!defined (LCD_DBUS6_PIN) || \
|
|
!defined (LCD_DBUS7) || \
|
|
!defined (LCD_DBUS7_PORT) || \
|
|
!defined (LCD_DBUS7_DDR) || \
|
|
!defined (LCD_DBUS7_PIN)
|
|
#error "Both EIGHT_BIT_ARBITRARY_PIN_MODE and FOUR_BIT_MODE require that LCD_DBUS*[,_PORT,_DDR,_PIN] be defined."
|
|
#endif
|
|
|
|
// Set LCD_BF automatically for both EIGHT_BIT_ARBITRARY_PIN_MODE and FOUR_BIT_MODE
|
|
#undef LCD_BF
|
|
#define LCD_BF LCD_DBUS7
|
|
|
|
#else
|
|
#if !defined (LCD_DBUS_PORT) || \
|
|
!defined (LCD_DBUS_DDR) || \
|
|
!defined (LCD_DBUS_PIN) || \
|
|
!defined (LCD_BF)
|
|
#error "Default mode requires that LCD_DBUS_[PORT,DDR,PIN] and LCD_BF be defined."
|
|
#endif
|
|
|
|
#undef LCD_DBUS7_PORT
|
|
#define LCD_DBUS7_PORT LCD_DBUS_PORT
|
|
#undef LCD_DBUS7_DDR
|
|
#define LCD_DBUS7_DDR LCD_DBUS_DDR
|
|
#undef LCD_DBUS7_PIN
|
|
#define LCD_DBUS7_PIN LCD_DBUS_PIN
|
|
#endif
|
|
|
|
#endif /* LCD_LIB_H */
|