1. F Malpartida
  2. New LiquidCrystal

Commits

F Malpartida  committed 98dda3b

First version with comments.

  • Participants
  • Parent commits cbe36ae
  • Branches default

Comments (0)

Files changed (6)

File LiquidCrystal.cpp

View file
  • Ignore whitespace
+// ---------------------------------------------------------------------------
+// Created by Francisco Malpartida on 20/08/11.
+// Copyright 2011 - Under creative commons license 3.0:
+//        Attribution-ShareAlike CC BY-SA
+//
+// This software is furnished "as is", without technical support, and with no 
+// warranty, express or implied, as to its usefulness for any purpose.
+//
+// Thread Safe: No
+// Extendable: Yes
+//
+// @file LiquidCrystal.h
+// This file implements a basic liquid crystal library that comes as standard
+// in the Arduino SDK.
+// 
+// @brief 
+// This is a basic implementation of the LiquidCrystal library of the
+// Arduino SDK. This library is a refactored version of the one supplied
+// in the Arduino SDK in such a way that it simplifies its extension
+// to support other mechanism to communicate to LCDs such as I2C, Serial.
+// The original library has been reworked in such a way that this will be
+// the base class implementing all generic methods to command an LCD based
+// on the Hitachi HD44780 and compatible chipsets.
+//
+// This base class is a pure abstract class and needs to be extended. As reference,
+// it has been extended to drive 4 and 8 bit mode control, LCDs and I2C extension
+// backpacks such as the I2CLCDextraIO using the PCF8574* I2C IO Expander ASIC.
+//
+//
+// This library is only compatible with Arduino's SDK version 1.0
+//
+//
+// @author F. Malpartida - fmalpartida@gmail.com
+// ---------------------------------------------------------------------------
 #include <stdio.h>
 #include <string.h>
 #include <inttypes.h>
 
 }
 
-/********** high level commands, for the user! */
+// Common LCD Commands
+// ---------------------------------------------------------------------------
 void LiquidCrystal::clear()
 {
    command(LCD_CLEARDISPLAY);  // clear display, set cursor position to zero
-   delayMicroseconds(2000);  // this command takes a long time!
+   delayMicroseconds(2000);    // this command is time consuming
 }
 
 void LiquidCrystal::home()
 {
    command(LCD_RETURNHOME);  // set cursor position to zero
-   delayMicroseconds(2000);  // this command takes a long time!
+   delayMicroseconds(2000);  // This command is time consuming
 }
 
 void LiquidCrystal::setCursor(uint8_t col, uint8_t row)
 {
    int row_offsets[] = { 0x00, 0x40, 0x14, 0x54 };
+   
    if ( row > _numlines ) 
    {
-      row = _numlines-1;    // we count rows starting w/0
+      row = _numlines-1;    // rows start at 0
    }
    
    command(LCD_SETDDRAMADDR | (col + row_offsets[row]));
 }
 
-// Turn the display on/off (quickly)
+// Turn the display on/off
 void LiquidCrystal::noDisplay() 
 {
    _displaycontrol &= ~LCD_DISPLAYON;
    _displaycontrol &= ~LCD_CURSORON;
    command(LCD_DISPLAYCONTROL | _displaycontrol);
 }
-void LiquidCrystal::cursor() {
+void LiquidCrystal::cursor() 
+{
    _displaycontrol |= LCD_CURSORON;
    command(LCD_DISPLAYCONTROL | _displaycontrol);
 }
 
-// Turn on and off the blinking cursor
-void LiquidCrystal::noBlink() {
+// Turns on/off the blinking cursor
+void LiquidCrystal::noBlink() 
+{
    _displaycontrol &= ~LCD_BLINKON;
    command(LCD_DISPLAYCONTROL | _displaycontrol);
 }
-void LiquidCrystal::blink() {
+
+void LiquidCrystal::blink() 
+{
    _displaycontrol |= LCD_BLINKON;
    command(LCD_DISPLAYCONTROL | _displaycontrol);
 }
 
 // These commands scroll the display without changing the RAM
-void LiquidCrystal::scrollDisplayLeft(void) {
+void LiquidCrystal::scrollDisplayLeft(void) 
+{
    command(LCD_CURSORSHIFT | LCD_DISPLAYMOVE | LCD_MOVELEFT);
 }
+
 void LiquidCrystal::scrollDisplayRight(void) {
    command(LCD_CURSORSHIFT | LCD_DISPLAYMOVE | LCD_MOVERIGHT);
 }
 }
 
 // This is for text that flows Right to Left
-void LiquidCrystal::rightToLeft(void) {
+void LiquidCrystal::rightToLeft(void) 
+{
    _displaymode &= ~LCD_ENTRYLEFT;
    command(LCD_ENTRYMODESET | _displaymode);
 }
 
 // This will 'right justify' text from the cursor
-void LiquidCrystal::autoscroll(void) {
+void LiquidCrystal::autoscroll(void) 
+{
    _displaymode |= LCD_ENTRYSHIFTINCREMENT;
    command(LCD_ENTRYMODESET | _displaymode);
 }
 
 // This will 'left justify' text from the cursor
-void LiquidCrystal::noAutoscroll(void) {
+void LiquidCrystal::noAutoscroll(void) 
+{
    _displaymode &= ~LCD_ENTRYSHIFTINCREMENT;
    command(LCD_ENTRYMODESET | _displaymode);
 }
 
-// Allows us to fill the first 8 CGRAM locations
-// with custom characters
-void LiquidCrystal::createChar(uint8_t location, uint8_t charmap[]) {
-   location &= 0x7; // we only have 8 locations 0-7
+// Write to CGRAM of new characters
+void LiquidCrystal::createChar(uint8_t location, uint8_t charmap[]) 
+{
+   location &= 0x7;                // we only have 8 locations 0-7
+
    command(LCD_SETCGRAMADDR | (location << 3));
-   for (int i=0; i<8; i++) {
-      write(charmap[i]);
+   for (int i=0; i<8; i++) 
+   {
+      write(charmap[i]);           // call the virtual write method
    }
 }
 
-/*********** mid level commands, for sending data/cmds */
-
+// General LCD commands - generic methods used by the rest of the commands
+// ---------------------------------------------------------------------------
 void LiquidCrystal::command(uint8_t value) 
 {
    send(value, LOW);
 size_t LiquidCrystal::write(uint8_t value) 
 {
    send(value, HIGH);
-   return 1; // assume sucess
+   
+   return 1;           // assume OK
 }

File LiquidCrystal.h

View file
  • Ignore whitespace
+// ---------------------------------------------------------------------------
+// Created by Francisco Malpartida on 20/08/11.
+// Copyright 2011 - Under creative commons license 3.0:
+//        Attribution-ShareAlike CC BY-SA
+//
+// This software is furnished "as is", without technical support, and with no 
+// warranty, express or implied, as to its usefulness for any purpose.
+//
+// Thread Safe: No
+// Extendable: Yes
+//
+// @file LiquidCrystal.h
+// This file implements a basic liquid crystal library that comes as standard
+// in the Arduino SDK.
+// 
+// @brief 
+// This is a basic implementation of the LiquidCrystal library of the
+// Arduino SDK. This library is a refactored version of the one supplied
+// in the Arduino SDK in such a way that it simplifies its extension
+// to support other mechanism to communicate to LCDs such as I2C, Serial.
+// The original library has been reworked in such a way that this will be
+// the base class implementing all generic methods to command an LCD based
+// on the Hitachi HD44780 and compatible chipsets.
+//
+// This base class is a pure abstract class and needs to be extended. As reference,
+// it has been extended to drive 4 and 8 bit mode control, LCDs and I2C extension
+// backpacks such as the I2CLCDextraIO using the PCF8574* I2C IO Expander ASIC.
+//
+//
+// This library is only compatible with Arduino's SDK version 1.0
+//
+//
+// @author F. Malpartida - fmalpartida@gmail.com
+// ---------------------------------------------------------------------------
 #ifndef LiquidCrystal_h
 #define LiquidCrystal_h
 
 #include <inttypes.h>
 #include "Print.h"
 
-// commands
-#define LCD_CLEARDISPLAY 0x01
-#define LCD_RETURNHOME 0x02
-#define LCD_ENTRYMODESET 0x04
-#define LCD_DISPLAYCONTROL 0x08
-#define LCD_CURSORSHIFT 0x10
-#define LCD_FUNCTIONSET 0x20
-#define LCD_SETCGRAMADDR 0x40
-#define LCD_SETDDRAMADDR 0x80
+
+/*!
+    @defined 
+    @abstract   All these definitions shouldn't be used unless you are writing a driver.
+    @discussion All these definitions are for driver implementation only and
+    shouldn't be used by applications.
+*/
+// LCD Commands
+// ---------------------------------------------------------------------------
+#define LCD_CLEARDISPLAY        0x01
+#define LCD_RETURNHOME          0x02
+#define LCD_ENTRYMODESET        0x04
+#define LCD_DISPLAYCONTROL      0x08
+#define LCD_CURSORSHIFT         0x10
+#define LCD_FUNCTIONSET         0x20
+#define LCD_SETCGRAMADDR        0x40
+#define LCD_SETDDRAMADDR        0x80
 
 // flags for display entry mode
-#define LCD_ENTRYRIGHT 0x00
-#define LCD_ENTRYLEFT 0x02
+// ---------------------------------------------------------------------------
+#define LCD_ENTRYRIGHT          0x00
+#define LCD_ENTRYLEFT           0x02
 #define LCD_ENTRYSHIFTINCREMENT 0x01
 #define LCD_ENTRYSHIFTDECREMENT 0x00
 
-// flags for display on/off control
-#define LCD_DISPLAYON 0x04
-#define LCD_DISPLAYOFF 0x00
-#define LCD_CURSORON 0x02
-#define LCD_CURSOROFF 0x00
-#define LCD_BLINKON 0x01
-#define LCD_BLINKOFF 0x00
+// flags for display on/off and cursor control
+// ---------------------------------------------------------------------------
+#define LCD_DISPLAYON           0x04
+#define LCD_DISPLAYOFF          0x00
+#define LCD_CURSORON            0x02
+#define LCD_CURSOROFF           0x00
+#define LCD_BLINKON             0x01
+#define LCD_BLINKOFF            0x00
 
 // flags for display/cursor shift
-#define LCD_DISPLAYMOVE 0x08
-#define LCD_CURSORMOVE 0x00
-#define LCD_MOVERIGHT 0x04
-#define LCD_MOVELEFT 0x00
+// ---------------------------------------------------------------------------
+#define LCD_DISPLAYMOVE         0x08
+#define LCD_CURSORMOVE          0x00
+#define LCD_MOVERIGHT           0x04
+#define LCD_MOVELEFT            0x00
 
 // flags for function set
-#define LCD_8BITMODE 0x10
-#define LCD_4BITMODE 0x00
-#define LCD_2LINE 0x08
-#define LCD_1LINE 0x00
-#define LCD_5x10DOTS 0x04
-#define LCD_5x8DOTS 0x00
+// ---------------------------------------------------------------------------
+#define LCD_8BITMODE            0x10
+#define LCD_4BITMODE            0x00
+#define LCD_2LINE               0x08
+#define LCD_1LINE               0x00
+#define LCD_5x10DOTS            0x04
+#define LCD_5x8DOTS             0x00
 
-class LiquidCrystal : public Print {
+class LiquidCrystal : public Print 
+{
 public:
-   
+
+   /*!
+    @method
+    @abstract   LiquidCrystal abstract constructor.
+    @discussion LiquidCrystal class abstract constructor needed to create
+    the base abstract class.
+    */
    LiquidCrystal ( );
    
+   /*!
+    @function
+    @abstract   LCD initialization.
+    @discussion Initializes the LCD to a given size (col, row). This methods
+    initializes the LCD, therefore, it MUST be called prior to using any other
+    method from this class.
+    
+    This method is pure abstract, it is dependent on each derived class from
+    this base class to implement the internals of how the LCD is initialized
+    and configured.
+    
+    @param      cols: the number of columns that the display has
+    @param      rows: the number of rows that the display has
+    */
    virtual void begin(uint8_t cols, uint8_t rows, uint8_t charsize = LCD_5x8DOTS) = 0;
    
+   /*!
+    @function
+    @abstract   Clears the LCD.
+    @discussion Clears the LCD screen and positions the cursor in the upper-left 
+    corner. 
+    
+    This operation is time consuming for the LCD.
+    
+    @param      none
+    */
    void clear();
+   
+   /*!
+    @function
+    @abstract   Sets the cursor to the upper-left corner.
+    @discussion Positions the cursor in the upper-left of the LCD. 
+    That is, use that location in outputting subsequent text to the display. 
+    To also clear the display, use the clear() function instead.
+    
+    This operation is time consuming for the LCD.
+    
+    @param      none
+   */
    void home();
+   
+   /*!
+    @function
+    @abstract   Turns off the LCD display.
+    @discussion Turns off the LCD display, without losing the text currently 
+    being displayed on it.
+    
+    @param      none
+    */
    void noDisplay();
+   
+   /*!
+    @function
+    @abstract   Turns on the LCD display.
+    @discussion Turns on the LCD display, after it's been turned off with 
+    noDisplay(). This will restore the text (and cursor location) that was on 
+    the display prior to calling noDisplay().
+
+    @param      none
+    */
    void display();
+   
+   /*!
+    @function
+    @abstract   Turns off the blinking of the LCD cursor.
+    
+    @param      none
+    */
    void noBlink();
+
+   /*!
+    @function
+    @abstract   Display the cursor of the LCD.
+    @discussion Display the blinking LCD cursor. If used in combination with 
+    the cursor() function, the result will depend on the particular display.
+
+    @param      none
+    */
    void blink();
+   
+   /*!
+    @function
+    @abstract   Hides the LCD cursor.
+
+    @param      none
+    */
    void noCursor();
+   
+   /*!
+    @function
+    @abstract   Display the LCD cursor.
+    @discussion Display the LCD cursor: an underscore (line) at the location 
+    where the next character will be written.
+    
+    @param      none
+    */
    void cursor();
+   
+   /*!
+    @function
+    @abstract   Scrolls the contents of the display (text and cursor) one space 
+    to the left.
+
+    @param      none
+    */
    void scrollDisplayLeft();
+   
+   /*!
+    @function
+    @abstract   Scrolls the contents of the display (text and cursor) one space 
+    to the right.
+
+    @param      none
+    */
    void scrollDisplayRight();
+   
+   /*!
+    @function
+    @abstract   Set the direction for text written to the LCD to left-to-right.
+    @discussion Set the direction for text written to the LCD to left-to-right. 
+    All subsequent characters written to the display will go from left to right, 
+    but does not affect previously-output text.
+    
+    This is the default configuration.
+    
+    @param      none
+    */
    void leftToRight();
+   
+   /*!
+    @function
+    @abstract   Set the direction for text written to the LCD to right-to-left.
+    @discussion Set the direction for text written to the LCD to right-to-left. 
+    All subsequent characters written to the display will go from right to left, 
+    but does not affect previously-output text.
+    
+    left-to-right is the default configuration.
+    
+    @param      none
+    */
    void rightToLeft();
+   
+   /*!
+    @function
+    @abstract   Turns on automatic scrolling of the LCD.
+    @discussion Turns on automatic scrolling of the LCD. This causes each 
+    character output to the display to push previous characters over by one 
+    space. If the current text direction is left-to-right (the default), 
+    the display scrolls to the left; if the current direction is right-to-left, 
+    the display scrolls to the right. 
+    This has the effect of outputting each new character to the same location on the LCD.
+    
+    @param      none
+    */
    void autoscroll();
+   
+   /*!
+    @function
+    @abstract   Turns off automatic scrolling of the LCD.
+    @discussion Turns off automatic scrolling of the LCD, this is the default
+    configuration of the LCD.
+
+    @param      none
+    */
    void noAutoscroll();
    
-   void createChar(uint8_t, uint8_t[]);
-   void setCursor(uint8_t, uint8_t);
+   /*!
+    @function
+    @abstract   Creates a custom character for use on the LCD.
+    @discussion Create a custom character (glyph) for use on the LCD. 
+    Most chipsets only support up to eight characters of 5x8 pixels. Therefore,
+    this methods has been limited to locations (numbered 0 to 7). 
+    
+    The appearance of each custom character is specified by an array of eight 
+    bytes, one for each row. The five least significant bits of each byte 
+    determine the pixels in that row. To display a custom character on screen, 
+    write()/print() its number, i.e. lcd.print (char(x)); // Where x is 0..7.
+    
+    @param      location: LCD memory location of the character to create
+                (0 to 7)
+    @param      charmap: the bitmap array representing each row of the character.
+    */
+   void createChar(uint8_t location, uint8_t charmap[]);
    
-   void command(uint8_t);
-   size_t write(uint8_t);
+   /*!
+    @function
+    @abstract   Position the LCD cursor.
+    @discussion Sets the position of the LCD cursor. Set the location at which 
+    subsequent text written to the LCD will be displayed.
+
+    @param      col: LCD column
+    @param      row: LCD row - line.
+    */
+   void setCursor(uint8_t col, uint8_t row);
+
    
-   virtual void send(uint8_t, uint8_t) = 0;
-   virtual void write4bits(uint8_t) = 0;
-   //virtual void pulseEnable() = 0;
+   /*!
+    @function
+    @abstract   Send a command to the LCD.
+    @discussion This method sends a command to the LCD by setting the Register
+    select line of the LCD.
+    
+    This command shouldn't be used to drive the LCD, only to implement any other
+    feature that is not available on this library.
+    
+    @param      value: Command value to send to the LCD.
+    */
+   void command(uint8_t value);
+
+   /*!
+    @function
+    @abstract   Writes to the LCD.
+    @discussion This method writes character to the LCD in the current cursor
+    position.
+    
+    This is the virtual write method, implemented in the Print class, therefore
+    all Print class methods will end up calling this method.
+
+    @param      value: Value to write to the LCD.
+    */
+   size_t write(uint8_t value);
    
+   /*!
+    @function
+    @abstract   Send a particular value to the LCD.
+    @discussion Sends a particular value to the LCD. This is a pure abstract
+    method, therefore, it is implementation dependent of each derived class how
+    to physically write to the LCD.
+    
+    Users should never call this method.
+    
+    @param      value: Value to send to the LCD.
+    @result     mode: LOW - write to the LCD CGRAM, HIGH - write a command to
+    the LCD.
+    */
+   virtual void send(uint8_t value, uint8_t mode) = 0;
+      
    using Print::write;
    
-protected: 
-   uint8_t _displayfunction;
-   uint8_t _displaycontrol;
-   uint8_t _displaymode;
-   uint8_t _numlines;
+protected:
+   // Internal LCD variables to control the LCD shared between all derived
+   // classes.
+   uint8_t _displayfunction;  // LCD_5x10DOTS or LCD_5x8DOTS, LCD_4BITMODE or 
+                              // LCD_8BITMODE, LCD_1LINE or LCD_2LINE
+   uint8_t _displaycontrol;   // LCD base control command LCD on/off, blink, cursor
+                              // all commands are "ored" to its contents.
+   uint8_t _displaymode;      // Text entry mode to the LCD
+   uint8_t _numlines;         // Number of lines of the LCD, initialized with begin()
    
 private:
    

File LiquidCrystal_4bit.cpp

View file
  • Ignore whitespace
+// ---------------------------------------------------------------------------
+// Created by Francisco Malpartida on 20/08/11.
+// Copyright 2011 - Under creative commons license 3.0:
+//        Attribution-ShareAlike CC BY-SA
+//
+// This software is furnished "as is", without technical support, and with no 
+// warranty, express or implied, as to its usefulness for any purpose.
+//
+// Thread Safe: No
+// Extendable: Yes
+//
+// @file LiquidCrystal_4bit.cpp
+// This file implements a basic liquid crystal library that comes as standard
+// in the Arduino SDK.
+// 
+// @brief 
+// This is a basic implementation of the LiquidCrystal library of the
+// Arduino SDK. The original library has been reworked in such a way that 
+// this class implements the all methods to command an LCD based
+// on the Hitachi HD44780 and compatible chipsets using the parallel port of
+// the LCD (4 bit and 8 bit).
+//
+// The functionality provided by this class and its base class is identical
+// to the original functionality of the Arduino LiquidCrystal library.
+//
+//
+// This library is only compatible with Arduino's SDK version 1.0
+//
+//
+// @author F. Malpartida - fmalpartida@gmail.com
+// ---------------------------------------------------------------------------
 #include <stdio.h>
 #include <string.h>
 #include <inttypes.h>
 // Note, however, that resetting the Arduino doesn't reset the LCD, so we
 // can't assume that its in that state when a sketch starts (and the
 // LiquidCrystal_4bit constructor is called).
+// A call to begin() will reinitialize the LCD.
 
+
+// CONSTRUCTORS
+// ---------------------------------------------------------------------------
 LiquidCrystal_4bit::LiquidCrystal_4bit(uint8_t rs, uint8_t rw, uint8_t enable,
-                                        uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3,
-                                        uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7)
+                                       uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3,
+                                       uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7)
 {
    init(0, rs, rw, enable, d0, d1, d2, d3, d4, d5, d6, d7);
 }
 }
 
 LiquidCrystal_4bit::LiquidCrystal_4bit(uint8_t rs, uint8_t rw, uint8_t enable,
-                             uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3)
+                                       uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3)
 {
    init(1, rs, rw, enable, d0, d1, d2, d3, 0, 0, 0, 0);
 }
    init(1, rs, 255, enable, d0, d1, d2, d3, 0, 0, 0, 0);
 }
 
+// PRIVATE METHODS
+// ---------------------------------------------------------------------------
+
+//
+// init
 void LiquidCrystal_4bit::init(uint8_t fourbitmode, uint8_t rs, uint8_t rw, uint8_t enable,
                               uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3,
                               uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7)
 {
+   uint8_t i;
+   
+   // Initialize the IO pins
+   // -------------------------------------------------------------------------
    _rs_pin = rs;
    _rw_pin = rw;
    _enable_pin = enable;
    _data_pins[4] = d4;
    _data_pins[5] = d5;
    _data_pins[6] = d6;
-   _data_pins[7] = d7; 
+   _data_pins[7] = d7;
    
+   // Initialize the IO port direction to OUTPUT
+   // -------------------------------------------------------------------------
+   for ( uint8_t i = 0; i < 4; i++ )
+   {
+      pinMode ( _data_pins[i], OUTPUT );
+   }
+   
+   // Initialize the rest of the ports if it is an 8bit controlled LCD
+   // -------------------------------------------------------------------------
+   if ( !fourbitmode )
+   {
+      for ( uint8_t i = 4; i < 7; i++ )
+      {
+         pinMode ( _data_pins[i], OUTPUT );
+      }
+   }
    pinMode(_rs_pin, OUTPUT);
+   
    // we can save 1 pin by not using RW. Indicate by passing 255 instead of pin#
-   if (_rw_pin != 255) { 
+   if (_rw_pin != 255) 
+   { 
       pinMode(_rw_pin, OUTPUT);
    }
+   
    pinMode(_enable_pin, OUTPUT);
    
+   // Initialise displaymode functions to defaults: LCD_1LINE and LCD_5x8DOTS
+   // -------------------------------------------------------------------------
    if (fourbitmode)
       _displayfunction = LCD_4BITMODE | LCD_1LINE | LCD_5x8DOTS;
    else 
       _displayfunction = LCD_8BITMODE | LCD_1LINE | LCD_5x8DOTS;
-   
-   //begin(16, 1);
 }
 
+// PUBLIC METHODS
+// ---------------------------------------------------------------------------
+
+//
+// begin
 void LiquidCrystal_4bit::begin(uint8_t cols, uint8_t lines, uint8_t dotsize) 
 {
    if (lines > 1) 
    _numlines = lines;
    
    // for some 1 line displays you can select a 10 pixel high font
+   // ---------------------------------------------------------------------------
    if ((dotsize != 0) && (lines == 1)) 
    {
       _displayfunction |= LCD_5x10DOTS;
    
    // SEE PAGE 45/46 FOR INITIALIZATION SPECIFICATION!
    // according to datasheet, we need at least 40ms after power rises above 2.7V
-   // before sending commands. Arduino can turn on way befer 4.5V so we'll wait 50
+   // before sending commands. Arduino can turn on way before 4.5V so we'll wait 50
+   // ---------------------------------------------------------------------------
    delayMicroseconds(50000); 
    
    // Now we pull both RS and R/W low to begin commands
    digitalWrite(_rs_pin, LOW);
    digitalWrite(_enable_pin, LOW);
-   if (_rw_pin != 255) { 
+   
+   if (_rw_pin != 255) 
+   { 
       digitalWrite(_rw_pin, LOW);
    }
    
    //put the LCD into 4 bit or 8 bit mode
+   // ---------------------------------------------------------------------------
    if (! (_displayfunction & LCD_8BITMODE)) 
    {
       // this is according to the hitachi HD44780 datasheet
    _displaycontrol = LCD_DISPLAYON | LCD_CURSOROFF | LCD_BLINKOFF;  
    display();
    
-   // clear it off
+   // clear the LCD
    clear();
    
    // Initialize to default text direction (for romance languages)
 /************ low level data pushing commands **********/
 
 // write either command or data, with automatic 4/8-bit selection
-void LiquidCrystal_4bit::send(uint8_t value, uint8_t mode) {
+// send
+void LiquidCrystal_4bit::send(uint8_t value, uint8_t mode) 
+{
    digitalWrite(_rs_pin, mode);
    
    // if there is a RW pin indicated, set it low to Write
-   if (_rw_pin != 255) { 
+   // ---------------------------------------------------
+   if (_rw_pin != 255) 
+   { 
       digitalWrite(_rw_pin, LOW);
    }
    
-   if (_displayfunction & LCD_8BITMODE) {
+   if (_displayfunction & LCD_8BITMODE)
+   {
       write8bits(value); 
-   } else {
+   } 
+   else 
+   {
       write4bits(value>>4);
       write4bits(value);
    }
 }
 
-void LiquidCrystal_4bit::pulseEnable(void) {
+//
+// pulseEnable
+void LiquidCrystal_4bit::pulseEnable(void) 
+{
    digitalWrite(_enable_pin, LOW);
-   delayMicroseconds(1);    
+   delayMicroseconds(1);
+   
    digitalWrite(_enable_pin, HIGH);
-   delayMicroseconds(1);    // enable pulse must be >450ns
+   delayMicroseconds(1);           // enable pulse must be > 450ns
+   
    digitalWrite(_enable_pin, LOW);
-   delayMicroseconds(100);   // commands need > 37us to settle
+   delayMicroseconds(100);         // commands need > 37us to settle
 }
 
-void LiquidCrystal_4bit::write4bits(uint8_t value) {
-   for (int i = 0; i < 4; i++) {
-      pinMode(_data_pins[i], OUTPUT);
+//
+// write4bits
+void LiquidCrystal_4bit::write4bits(uint8_t value) 
+{
+   for (uint8_t i = 0; i < 4; i++) 
+   {
       digitalWrite(_data_pins[i], (value >> i) & 0x01);
    }
    
    pulseEnable();
 }
 
-void LiquidCrystal_4bit::write8bits(uint8_t value) {
-   for (int i = 0; i < 8; i++) {
-      pinMode(_data_pins[i], OUTPUT);
+//
+// write8bits
+void LiquidCrystal_4bit::write8bits(uint8_t value) 
+{
+   for (uint8_t i = 0; i < 8; i++) 
+   {
       digitalWrite(_data_pins[i], (value >> i) & 0x01);
    }
    

File LiquidCrystal_4bit.h

View file
  • Ignore whitespace
+// ---------------------------------------------------------------------------
+// Created by Francisco Malpartida on 20/08/11.
+// Copyright 2011 - Under creative commons license 3.0:
+//        Attribution-ShareAlike CC BY-SA
+//
+// This software is furnished "as is", without technical support, and with no 
+// warranty, express or implied, as to its usefulness for any purpose.
+//
+// Thread Safe: No
+// Extendable: Yes
+//
+// @file LiquidCrystal_4bit.h
+// This file implements a basic liquid crystal library that comes as standard
+// in the Arduino SDK.
+// 
+// @brief 
+// This is a basic implementation of the LiquidCrystal library of the
+// Arduino SDK. The original library has been reworked in such a way that 
+// this class implements the all methods to command an LCD based
+// on the Hitachi HD44780 and compatible chipsets using the parallel port of
+// the LCD (4 bit and 8 bit).
+//
+// The functionality provided by this class and its base class is identical
+// to the original functionality of the Arduino LiquidCrystal library.
+//
+//
+// This library is only compatible with Arduino's SDK version 1.0
+//
+//
+// @author F. Malpartida - fmalpartida@gmail.com
+// ---------------------------------------------------------------------------
 #ifndef LiquidCrystal_4bit_h
 #define LiquidCrystal_4bit_h
 
 class LiquidCrystal_4bit : public LiquidCrystal
 {
 public:
+   /*!
+    @method     
+    @abstract   8 bit LCD constructors.
+    @discussion Defines the pin assignment that the LCD will have.
+    The constructor does not initialize the LCD.
+    */
    LiquidCrystal_4bit(uint8_t rs, uint8_t enable,
                       uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3,
                       uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7);
    LiquidCrystal_4bit(uint8_t rs, uint8_t rw, uint8_t enable,
                       uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3,
                       uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7);
+
+   /*!
+    @method     
+    @abstract   4 bit LCD constructors.
+    @discussion Defines the pin assignment that the LCD will have.
+    The constructor does not initialize the LCD.
+    */
    LiquidCrystal_4bit(uint8_t rs, uint8_t rw, uint8_t enable,
                       uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3);
    LiquidCrystal_4bit(uint8_t rs, uint8_t enable,
                       uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3);
       
 
+   /*!
+    @function
+    @abstract   LCD initialization.
+    @discussion Initializes the LCD to a given size (col, row). This methods
+    initializes the LCD, therefore, it MUST be called prior to using any other
+    method from this class.
+        
+    @param      cols: the number of columns that the display has
+    @param      rows: the number of rows that the display has
+    @param      charsize: size of the characters of the LCD: LCD_5x8DOTS or
+    LCD_5x10DOTS.
+     */
+   virtual void begin(uint8_t cols, uint8_t rows, uint8_t charsize = LCD_5x8DOTS);   
    
-   virtual void begin(uint8_t cols, uint8_t rows, uint8_t charsize = LCD_5x8DOTS);   
-   virtual void send(uint8_t, uint8_t);
-   virtual void write4bits(uint8_t);
-   virtual void pulseEnable();
+   /*!
+    @function
+    @abstract   Send a particular value to the LCD.
+    @discussion Sends a particular value to the LCD for writing to the LCD or
+    as an LCD command.
+    
+    Users should never call this method.
+    
+    @param      value: Value to send to the LCD.
+    @result     mode: LOW - write to the LCD CGRAM, HIGH - write a command to
+    the LCD.
+    */
+   virtual void send(uint8_t value, uint8_t mode);
+
    
 private:
+
+   /*!
+    @method     
+    @abstract   Initializes the LCD pin allocation
+    @discussion Initializes the LCD pin allocation and configuration.
+   */
    void init(uint8_t fourbitmode, uint8_t rs, uint8_t rw, uint8_t enable,
              uint8_t d0, uint8_t d1, uint8_t d2, uint8_t d3,
              uint8_t d4, uint8_t d5, uint8_t d6, uint8_t d7);
    
-   void write8bits(uint8_t);
+   /*!
+    @method     
+    @abstract   Writes an 8 bit value to the LCD.
+    @discussion Writes 8 bits to the LCD control data lines.
+    */
+   void write8bits(uint8_t value);
    
-   uint8_t _rs_pin; // LOW: command.  HIGH: character.
-   uint8_t _rw_pin; // LOW: write to LCD.  HIGH: read from LCD.
-   uint8_t _enable_pin; // activated by a HIGH pulse.
-   uint8_t _data_pins[8];
+   /*!
+    @method     
+    @abstract   Writes an 4 bit value to the LCD.
+    @discussion Writes 4 bits (the least significant) to the LCD control data lines.
+    */   
+   void write4bits(uint8_t value);
+   
+   /*!
+    @method     
+    @abstract   Pulse the LCD enable line (En).
+    @discussion Sends a pulse of 1 uS to the Enable pin to execute an command
+    or write operation.
+    */ 
+   void pulseEnable();
+   
+   uint8_t _rs_pin;       // LOW: command.  HIGH: character.
+   uint8_t _rw_pin;       // LOW: write to LCD.  HIGH: read from LCD.
+   uint8_t _enable_pin;   // activated by a HIGH pulse.
+   uint8_t _data_pins[8]; // Data pins.
 };
 
 #endif

File LiquidCrystal_I2C.cpp

View file
  • Ignore whitespace
+// ---------------------------------------------------------------------------
+// Created by Francisco Malpartida on 20/08/11.
+// Copyright 2011 - Under creative commons license 3.0:
+//        Attribution-ShareAlike CC BY-SA
+//
+// This software is furnished "as is", without technical support, and with no 
+// warranty, express or implied, as to its usefulness for any purpose.
+//
+// Thread Safe: No
+// Extendable: Yes
+//
+// @file LiquidCrystal_I2C.c
+// This file implements a basic liquid crystal library that comes as standard
+// in the Arduino SDK but using an I2C IO extension board.
+// 
+// @brief 
+// This is a basic implementation of the LiquidCrystal library of the
+// Arduino SDK. The original library has been reworked in such a way that 
+// this class implements the all methods to command an LCD based
+// on the Hitachi HD44780 and compatible chipsets using I2C extension
+// backpacks such as the I2CLCDextraIO with the PCF8574* I2C IO Expander ASIC.
+//
+// The functionality provided by this class and its base class is identical
+// to the original functionality of the Arduino LiquidCrystal library.
+//
+//
+// This library is only compatible with Arduino's SDK version 1.0
+//
+//
+// @author F. Malpartida - fmalpartida@gmail.com
+// ---------------------------------------------------------------------------
 #include "Arduino.h" 
-
 #include <inttypes.h>
 #include "I2CIO.h"
 #include "LiquidCrystal.h"
 //
 // Note, however, that resetting the Arduino doesn't reset the LCD, so we
 // can't assume that its in that state when a sketch starts (and the
-// LiquidCrystal constructor is called).
+// LiquidCrystal_I2C constructor is called).
+// A call to begin() will reinitialize the LCD.
 
+// CONSTRUCTORS
+// ---------------------------------------------------------------------------
 LiquidCrystal_I2C::LiquidCrystal_I2C( uint8_t lcd_Addr )
 {
   _Addr = lcd_Addr;
   _backlightval = LCD_NOBACKLIGHT;
 }
 
+
+// PRIVATE METHODS
+// ---------------------------------------------------------------------------
+
+//
+// init
 int LiquidCrystal_I2C::init()
 {
-	return ( init_priv( ) );
-}
-
-int LiquidCrystal_I2C::init_priv()
-{
    int status = 0;
    
-   // initialise the backpack IO expander
+   // initialize the backpack IO expander
+   // and display functions.
+   // ------------------------------------------------------------------------
 	if ( _i2cio.begin ( _Addr ) == 1 )
    {
-      _i2cio.portMode ( OUTPUT );
+      _i2cio.portMode ( OUTPUT );  // Set the entire IO extender to OUTPUT
       _displayfunction = LCD_4BITMODE | LCD_1LINE | LCD_5x8DOTS;
-      //begin(_cols, _rows);
       status = 1;
    }
    return ( status );
 }
 
+
+// PUBLIC METHODS
+// ---------------------------------------------------------------------------
+
+//
+// begin
 void LiquidCrystal_I2C::begin(uint8_t cols, uint8_t lines, uint8_t dotsize) 
 {
    _cols = cols;
 
 	// SEE PAGE 45/46 FOR INITIALIZATION SPECIFICATION!
 	// according to datasheet, we need at least 40ms after power rises above 2.7V
-	// before sending commands. Arduino can turn on way befer 4.5V so we'll wait 50
+	// before sending commands. Arduino can turn on way before 4.5V so we'll wait 50
 	delayMicroseconds(50000); 
   
 	// Now we pull both RS and R/W low to begin commands
-	expanderWrite(_backlightval);	// reset expanderand turn backlight off (Bit 8 =1)
+	expanderWrite(_backlightval);	// reset expander and turn backlight off (Bit 8 =1)
 	delay(1000);
 
   	//put the LCD into 4 bit mode
   
 }
 
-/*********** mid level commands, for sending data/cmds */
 
+// low level data pushing commands
+//----------------------------------------------------------------------------
 
-/************ low level data pushing commands **********/
-
-// write either command or data
+//
+// send - write either command or data
 void LiquidCrystal_I2C::send(uint8_t value, uint8_t mode) 
 {
+   // Is it a command or data
+   // ------------------------------------------------------------------------
    if ( mode == HIGH )
    {
       mode = Rs;
 	write4bits((lownib)|mode);
 }
 
+//
+// write4bits
 void LiquidCrystal_I2C::write4bits(uint8_t value) 
 {
 	expanderWrite(value);
 	pulseEnable(value);
 }
 
-void LiquidCrystal_I2C::pulseEnable(uint8_t _data)
+//
+// write4bits
+void LiquidCrystal_I2C::pulseEnable (uint8_t _data)
 {
-	expanderWrite(_data | En);	// En high
-	delayMicroseconds(1);		// enable pulse must be >450ns
+	expanderWrite (_data | En);	// En HIGH
+	delayMicroseconds(1);		   // enable pulse must be >450ns
 	
 	expanderWrite(_data & ~En);  // En low
 	delayMicroseconds(50);		  // commands need > 37us to settle
 } 
 
-/********** high level commands, for the user! */
+//
+// expanderWrite
+void LiquidCrystal_I2C::expanderWrite(uint8_t _data)
+{                                        
+   _i2cio.write ( _data );
+}
 
+// User commands - users can expand this section
+//----------------------------------------------------------------------------
 
 // Turn the (optional) backlight off/on
 void LiquidCrystal_I2C::noBacklight(void) 
 }
 
 
-/************ low level data pushing commands **********/
-
-void LiquidCrystal_I2C::expanderWrite(uint8_t _data)
-{                                        
-   _i2cio.write ( _data );
-}
 
 	

File LiquidCrystal_I2C.h

View file
  • Ignore whitespace
+// ---------------------------------------------------------------------------
+// Created by Francisco Malpartida on 20/08/11.
+// Copyright 2011 - Under creative commons license 3.0:
+//        Attribution-ShareAlike CC BY-SA
+//
+// This software is furnished "as is", without technical support, and with no 
+// warranty, express or implied, as to its usefulness for any purpose.
+//
+// Thread Safe: No
+// Extendable: Yes
+//
+// @file LiquidCrystal_I2C.h
+// This file implements a basic liquid crystal library that comes as standard
+// in the Arduino SDK but using an I2C IO extension board.
+// 
+// @brief 
+// This is a basic implementation of the LiquidCrystal library of the
+// Arduino SDK. The original library has been reworked in such a way that 
+// this class implements the all methods to command an LCD based
+// on the Hitachi HD44780 and compatible chipsets using I2C extension
+// backpacks such as the I2CLCDextraIO with the PCF8574* I2C IO Expander ASIC.
+//
+// The functionality provided by this class and its base class is identical
+// to the original functionality of the Arduino LiquidCrystal library.
+//
+//
+// This library is only compatible with Arduino's SDK version 1.0
+//
+//
+// @author F. Malpartida - fmalpartida@gmail.com
+// ---------------------------------------------------------------------------
 #ifndef LiquidCrystal_I2C_h
 #define LiquidCrystal_I2C_h
 
 #define LCD_BACKLIGHT   0x00
 #define LCD_NOBACKLIGHT 0x80
 
+/*!
+   @note These definitions will have to be changed should the IOExpander be 
+   connected differently to this default.
+*/
+
+/*!
+    @defined 
+    @abstract   Enable bit of the LCD
+    @discussion Defines the IO of the expander connected to the LCD Enable
+*/
 #define En B01000000  // Enable bit
+
+/*!
+ @defined 
+ @abstract   Read/Write bit of the LCD
+ @discussion Defines the IO of the expander connected to the LCD Rw pin
+ */
 #define Rw B00100000  // Read/Write bit
+
+/*!
+ @defined 
+ @abstract   Register bit of the LCD
+ @discussion Defines the IO of the expander connected to the LCD Register select pin
+ */
 #define Rs B00010000  // Register select bit
 
+
 class LiquidCrystal_I2C : public LiquidCrystal 
 {
 public:
+   
+   /*!
+    @method     
+    @abstract   Class constructor. 
+    @discussion Initializes class variables and defines the I2C address of the
+    LCD. The constructor does not initialize the LCD.
+    
+    @param      lcd_Addr: I2C address of the IO expansion module. For I2CLCDextraIO,
+    the address can be configured using the on board jumpers.
+    */
    LiquidCrystal_I2C (uint8_t lcd_Addr);
    
+   /*!
+    @function
+    @abstract   LCD initialization.
+    @discussion Initializes the LCD to a given size (col, row). This methods
+    initializes the LCD, therefore, it MUST be called prior to using any other
+    method from this class.
+    
+    @param      cols: the number of columns that the display has
+    @param      rows: the number of rows that the display has
+    @param      charsize: size of the characters of the LCD: LCD_5x8DOTS or
+    LCD_5x10DOTS.
+    */
+   virtual void begin(uint8_t cols, uint8_t rows, uint8_t charsize = LCD_5x8DOTS);   
+   
+   /*!
+    @function
+    @abstract   Send a particular value to the LCD.
+    @discussion Sends a particular value to the LCD for writing to the LCD or
+    as an LCD command.
+    
+    Users should never call this method.
+    
+    @param      value: Value to send to the LCD.
+    @result     mode: LOW - write to the LCD CGRAM, HIGH - write a command to
+    the LCD.
+    */
+   virtual void send(uint8_t value, uint8_t mode);
+   
+   /*!
+    @function
+    @abstract   Switch-off the LCD backlight.
+    @discussion Switch-off the LCD backlight, this method is not supported by
+    the I2CLCDextraIO, it needs an extra IO pin to drive the LCD backlight
+    
+    @param      none
+    */
+   void noBacklight();
 
+   /*!
+    @function
+    @abstract   Switch-on the LCD backlight.
+    @discussion Switch-on the LCD backlight, this method is not supported by
+    the I2CLCDextraIO, it needs an extra IO pin to drive the LCD backlight
+    
+    @param      none
+    */
+   void backlight();
 
-   void printLeft();
-   void printRight();
-   void shiftIncrement();
-   void shiftDecrement();
-   void noBacklight();
-   void backlight();
-   
-   // Virtual methods
-   virtual void begin(uint8_t cols, uint8_t rows, uint8_t charsize = LCD_5x8DOTS );
-   virtual void send(uint8_t, uint8_t);
-   virtual void write4bits(uint8_t);
-   virtual void pulseEnable(uint8_t);
 
 private:
-   int  init_priv();
-   int init();
+   
+   /*!
+    @method     
+    @abstract   Initializes the LCD class
+    @discussion Initializes the LCD class and IO expansion module.
+    */
+   int  init();
+   
+   /*!
+    @method     
+    @abstract   Writes an 4 bit value to the LCD.
+    @discussion Writes 4 bits (the least significant) to the LCD control data lines.
+    */
+   void write4bits(uint8_t);
+   
+   /*!
+    @method     
+    @abstract   Pulse the LCD enable line (En).
+    @discussion Sends a pulse of 1 uS to the Enable pin to execute an command
+    or write operation.
+    */
+   void pulseEnable(uint8_t);
+   
+   /*!
+    @method     
+    @abstract   Writes to the expansion module.
+    @discussion Writes a byte to the IO expansion module. This will be applied
+    to all its outputs.
+    */ 
    void expanderWrite(uint8_t);
-
-   uint8_t _Addr;
-   uint8_t _cols;
-   uint8_t _rows;
-   uint8_t _backlightval;
-   I2CIO   _i2cio;
    
+   uint8_t _Addr;           // I2C Address of the IO expander
+   uint8_t _cols;           // Number of columns of the LCD
+   uint8_t _rows;           // Number of rows of the LCD
+   uint8_t _backlightval;   // Backlight shadow value
+   I2CIO   _i2cio;          // I2CIO PCF8574* expansion module driver I2CLCDextraIO
 };
 
 #endif