LCD Version 0.95 Date: 01/09/2002 Copyright (c) 1999, 2000, 2001, 2002 Devon Jones (soulcatcher@evilsoft.org). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ############################################################################### Description: LCD is a class designed to allow a programmer access the display based functions of a Serial LCD. LCD::MatrixOrbital is a driver for LCD. It should work with a Matrix Orbital VFD as well (although not supporting one or two functions that are VFD specific - this is because I do not yet own a VFD.). LCD::CrystalFontz is a future driver for LCD. It whould work with CrystalFontz displays. It is suggested the to use this module, you use the wrapper module LCD. ############################################################################### Using this module: In order to use this module, you must do the following: use LCD $LCD = new LCD('MatrixOrbital', '/dev/ttyS0', 20, 4, 0); Strictly speaking the only parameters you need to send to new is the name of the driver (MatrixOrbital only for the time being) and the name of the device file for the serial port you are using, but I find it's better to be explicit. Following that, you can use any of the methods for the device but only certain ones are recommended: Core Functions: new (when creating) Character Initialization Functions: CreateCharacter InitGraphHoriz InitGraphVert InitLargeDigit Display Initialization Functions: SetBacklight SetContrast SetCursorBlink SetCursorDisplay SetLineWrap SetScroll Printing Functions: ClearAll ClearLine PrintGraphHoriz PrintGraphVert PrintLargeDigit PrintText PrintTextXY PrintRight PrintTextFrame Cursor Movement Functions: SetCursorLeft SetCursorRight SetPosition SetPositionTop State Functions: ResetState StateBacklight StateContrast StateCursorBlink StateCursorDisplay StateLineWrap StatePosition StateScroll Keypad Functions: ReadKey SetKPAutoTransmit PollKeyPad SetKPRepeatMode ClearKeyPadBuffer StateKPAutoTransmit StateKPRepeatMode StateKPUpDownMode All others should be considered 'Private' methods. ############################################################################### ############################################################################### # Name: LCD->new (Public) # Parameters: Driver - Should be "MatrixOrbital" or "CrystalFontz" # or whatever driver you add. # Device - Should be the device file of your serial port that # the LCD is attached to. Typically /dev/cua0 or # /dev/cua1. Required # X - Integer of the width (in characters) of the LCD # defaults to 20 (typically 20 or 40) # Y - Integer of the height (in characters) of the LCD # defaults to 4 (typically 2 or 4) # Debug - If debug is turned to on, the system will print # everything it sends to the lcd to STDOUT. Could # also be useful if you want to redirect the output # to another place. can be 0 (off) or 1 (on) defaults # to 0 # Returns: An LCD object. # Precondition: Need to create a new LCD object # Postcondition: The object is created, and is initialized to default values. # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Character Initialization Functions # ############################################################################### ############################################################################### # Name: LCD->CreateCharacter (Public) # Note: A character is a 5 x 8 grid, with a 1 standing for on, and a 0 # standing for off. Another note - all lines are required, and # all require the programmer to give five ones or zeros # Parameters: Position - can be 0-7. this stands for the hexidecimal position # of the character. In order to print this character # in the future, you must print the ascii # representation of 0x00 - 0x07 (depending on where # you place the character.) Required # Line 1 - string of five ones and zeros (such as 01100 or # 00010) standing for whether the pixel is on or off # for positions 1-5 of line 1. Required # Line 2 ... 7 - Same as above but appropriate for each line. # Line 8 - Same as above, but the whole line will be on or off # based on the first number. So 01111 and 00000 would # both print an empty line vs. 10010 and 11101 would # print the full line. Required # Returns: Nothing # Precondition: Programmer wishes to create a special character # Postcondition: The special character exists in one of 0x00 - 0x07 # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->InitGraphHoriz (Public) # Parameters: None # Returns: Nothing # Precondition: Programmer wishes to use a horizontal graph # Postcondition: All custom character slots are filled with horizontal graph # Characters. # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->InitGraphVert (Public) # Parameters: Width - 'thick' or 'thin'. Defaults to thick # Returns: Nothing # Precondition: Programmer wishes to use a vertical graph # Postcondition: All custom character slots are filled with vertical graph # Characters. # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->InitLargeDigit (Public) # Parameters: None # Returns: Nothing # Precondition: Programmer wishes to use large digits # Postcondition: All custom character slots are filled with large digit # Characters. # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Display Initialization Functions # ############################################################################### ############################################################################### # Name: LCD->SetBacklight (Public) # Parameters: cmd - 'on'/1 or 'off'/0 defaults to on # min - 0 - 180. This is the number of min that backlight will # remain on. 0 stands for forever. # Returns: Nothing # Precondition: Programmer wishes to change the state of the Backlight # Postcondition: Backlight is now on or off as wished. # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->SetContrast (public) # Parameters: Contrast - 0 - 256. Required # Returns: Nothing # Precondition: Programmer wishes to change the screen contrast. # Postcondition: Contrast is set # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->SetCursorBlink (public) # Parameters: cmd - 'on'/1 or 'off'/0 Defaults to on # Returns: Nothing # Precondition: Programmer wishes to turn cursor blinking on/off # Postcondition: cursor is now blinking/not blinking # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->SetCursorDisplay (public) # Parameters: cmd - 'on'/1 or 'off'/0 Defaults to on # Returns: nothing # Precondition: Programmer wishes to turn cursor display on/off # Postcondition: cursor is now displayed/not displayed # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->SetLineWrap (public) # Parameters: cmd - 'on'/1 or 'off'/0 Defaults to on # Returns: nothing # Precondition: Programmer wants to turn line wrapping on/off # Postcondition: Line Wrapping is on/off # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->SetScroll (public) # Parameters: cmd - 'on'/1 or 'off'/0 Defaults to on # Returns: Nothing # Precondition: Programmer wants to turn scrolling on/off # Postcondition: scrolling is on/off # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Printing Functions # ############################################################################### ############################################################################### # Name: LCD->ClearAll (Public) # Parameters: None # Returns: Nothing # Precondition: Programmer wants to clear screen # Postcondition: LCD Screen is cleared, and cursor is at position 0,0 # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->ClearLine (Public) # Parameters: Line number to erase # Returns: 0 on error, line number otherwise # Precondition: Programmer wants to clear a line # Postcondition: Line is cleared, and cursor is at position 0,$line # Author: Etienne Goyer (etienne.goyer@linuxquebec.com # Date: 11/08/2001 ############################################################################### ############################################################################### # Name: LCD->ClearLine (Public) # Parameters: Line number, position where to start erasing # Returns: 0 on error, line number otherwise # Precondition: Programmer wants to clear a line from a specific point # Postcondition: Line is cleared, and cursor is at position $x,$line # Author: Etienne Goyer (etienne.goyer@linuxquebec.com # Date: 11/12/2001 ############################################################################### ############################################################################### # Name: LCD->PrintGraphHoriz (Public) # Parameters: Cnumber - Column number the graph line will be printed in. # Required. Must be 1 through LCD max X # Rnumber - Row number the graph line will be printed in. # Required. Must be 1 through LCD max Y # direction - 1 (Left to Right) or 0 (Right to Left) Required # length - Length of the graph. From 1 to 5 * LCD max X # Required # Returns: Nothing # Precondition: Programmer wants to print a graph line, and InitGraphVert has been run # Postcondition: A line will be printed on the LCD # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->PrintGraphVert (Public) # Parameters: Cnumber - Column number the graph line will be printed in. # Required. Must be 1 through LCD max X # length - Length of the graph. From 1 to 8 * LCD max Y # Required # Returns: Nothing # Precondition: Programmer wants to print a graph line, and InitGraphVert has been run # Postcondition: A line will be printed on the LCD # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->PrintLargeDigit (Public) # Parameters: Cnumber - Column number the graph line will be printed in. # Required. Must be 1 through LCD max X - 2 # Digit - 0 - 9. Required # Returns: Nothing # Precondition: User wantes to print a large digit, and has run InitLargeDigit # Postcondition: A large digit has been printed # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->PrintText (Public) # Parameters: Text - The text you want to print. It will start from the # current location, and print from there. If LineWrap is # on, it will wrap. # Returns: Nothing # Precondition: Programmer wants to print some text # Postcondition: Text is printed # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->PrintTextXY (Public) # Parameters: Text - The text you want to print. It will start from the # specified location, and print from there. If LineWrap is # on, it will wrap. # Returns: Nothing # Precondition: Programmer wants to print some text # Postcondition: Text is printed # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->PrintRight (Public) # Parameters: Text - The text you want to print, Line - the line on wich to # print # Returns: Text printed or 0 on error # Precondition: Programmer wants to print some text right-justified # Postcondition: Text is printed, right-justified # Author: Etienne Goyer (etienne.goyer@linuxquebec.com) # Date: 11/12/2001 ############################################################################### ############################################################################### # Name: LCD->PrintTextFrame (Public) # Parameters: Text[] - The text to be printed as a frame. For example: # Send @text with rows 0-3 with up to 20 characters of text if # using a 20 X 4 LCD # Returns: Nothing # Precondition: Programmer wants to print some text # Postcondition: Text is printed # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Cursor Movement Functions # ############################################################################### ############################################################################### # Name: LCD->SetCursorLeft (public) # Parameters: None # Returns: Nothing # Precondition: Programmer wishes to move the cursor one spot to the left # Postcondition: cursor has moved on spot to the left # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->SetCursorRight (public) # Parameters: None # Returns: Nothing # Precondition: Programmer wishes to move the cursor one spot to the right # Postcondition: cursor has moved on spot to the right # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->SetPosition (public) # Parameters: x - Required. The x position of the cursor # y - Required. The y position of the cursor # Returns: Nothing # Precondition: Programmer wants to change the X,Y postion of the cursor # Postcondition: the X,Y position has changed # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->SetPositionTop (public) # Parameters: None # Returns: Nothing # Precondition: Programmer wants the cursor to return to 0,0 # Postcondition: The cursor is at 0,0 # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # State Functions # ############################################################################### ############################################################################### # Name: LCD->ResetState (Public) # Parameters: None # Returns: Nothing # Precondition: Programmer wants to reset the state to as it was at instantiation # Postcondition: Backlight is off, blink is off, Cursor is off, Line Wrap is off # Position is 0,0 and Scroll is off # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->StateBacklight (public) # Parameters: None # Returns: Backlight State - 1 or 0 # Precondition: Programmer wants to know the state of the backlight # Postcondition: The backlight state is returned # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->Statecontrast (public) # Parameters: None # Returns: contrast State - 0 - 256 # Precondition: Programmer wants to know the state of LCD contrast # Postcondition: The contrast state is returned # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->StateCursorBlink (public) # Parameters: None # Returns: cursor blinking State - 1 or 0 # Precondition: Programmer wants to know the state of the corsor's blinking # Postcondition: The cursor blinking state is returned # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->StateCursorDisplay (public) # Parameters: None # Returns: Cursor Display State - 1 or 0 # Precondition: Programmer wants to know the state of the cursor display # Postcondition: The cursor display state is returned # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->StateLineWrap (public) # Parameters: None # Returns: Line Wrap State - 1 or 0 # Precondition: Programmer wants to know the state of Line Wrapping # Postcondition: The line wrapping state is returned # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->StatePosition (public) # Parameters: None # Returns: x - x position of the cursor # y - y position of the cursor # Precondition: Programmer wants to know the position of the cursor # Postcondition: The cursor position is returned # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Name: LCD->StateScroll (public) # Parameters: None # Returns: Scroll State - 1 or 0 # Precondition: Programmer wants to know the state of scrolling # Postcondition: The scolling state is returned # Author: Vincent Thinselin (vthinsel@capgemini.fr) # Date: 2/2/2000 ############################################################################### ############################################################################### # Keypad Functions # ############################################################################### ############################################################################### # Name: LCD->ReadKey (public) # Parameters: None # Returns: a char or undef on error # Precondition: Programmer wants to get the last keypress # Postcondition: Character returned from the keypad returned # Author: Etienne Goyer (etienne.goyer@linuxquebec.com) # Date: 11/07/2001 ############################################################################### ############################################################################### # Name: LCD->SetKPAutoTransmit (public) # Parameters: The string 'on' or 'off', case-insensitive # Returns: True (1) on success # Precondition: Programmer wants to set Auto transmit propertie of the keypad # on or off. # Postcondition: none # Author: Etienne Goyer (etienne.goyer@linuxquebec.com) # Date: 11/07/2001 ############################################################################### ############################################################################### # Name: LCD->PollKeyPad (public) # Parameters: The string 'on' or 'off', case-insensitive # Returns: Caracter corresponding to keypress # Precondition: Keypad must be in poll mode (KPAutoTransmit == 0) # Postcondition: None # Comment: WARNING : this method use alarm. Don't call it inside of an # alarm or other timer, otherwise strange thing will happen. # Author: Etienne Goyer (etienne.goyer@linuxquebec.com) # Date: 11/07/2001 ############################################################################### ############################################################################### # Name: LCD->SetKPRepeatMode (public) # Parameters: The string 'on' or 'off', case-insensitive, to set Repeat mode # plus 0 or 1 for Resend or Key Up/Down (default Resend) # Returns: Nothing # Precondition: Programmer wants to set Repeat mode and propertie of the # keypad and, optionnally, the Resend or Key Up/Down behavior. # Postcondition: Repeat mode is set. # Author: Etienne Goyer (etienne.goyer@linuxquebec.com) # Date: 11/07/2001 ############################################################################### ############################################################################### # Name: LCD->ClearKeyPadBuffer (public) # Parameters: None # Returns: Nothing # Precondition: Programmer wants to clear the keypad buffer # Postcondition: Keypad buffer is cleared # Author: Etienne Goyer (etienne.goyer@linuxquebec.com) # Date: 11/07/2001 ############################################################################### ############################################################################### # Name: LCD->StateKPAutoTransmit (public) # Parameters: None # Returns: Keypad Autotransmit status (1 if on, 0 if off) # Precondition: Programmer wants to get Auto transmit propertie of the keypad # Postcondition: none # Author: Etienne Goyer (etienne.goyer@linuxquebec.com) # Date: 11/07/2001 ############################################################################### ############################################################################### # Name: LCD->StateKPRepeatMode (public) # Parameters: None # Returns: Keypad Repeat mode (1 if on, 0 if off) # Precondition: Programmer wants to get Repeat Mode propertie of the keypad # Postcondition: none # Author: Etienne Goyer (etienne.goyer@linuxquebec.com) # Date: 11/07/2001 ############################################################################### ############################################################################### # Name: LCD->StateKPUpDownMode (public) # Parameters: None # Returns: 0 in Resend mode, 1 in Key Up/Down mode # Precondition: Programmer wants to Auto-Repeat behavior of the keypad. # NB : This make no sens if the KP is not in Auto-Repeat mode # Postcondition: none # Author: Etienne Goyer (etienne.goyer@linuxquebec.com) # Date: 11/07/2001 ###############################################################################