freetronicsLCDShield.h

00001 /* mbed freetronicsLCDShield Library, written by Koen J.F. Kempeneers
00002  * koen.kempeneers@damiaaninstituut.be
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy
00005  * of this software and associated documentation files (the "Software"), to deal
00006  * in the Software without restriction, including without limitation the rights
00007  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00008  * copies of the Software, and to permit persons to whom the Software is
00009  * furnished to do so, subject to the following conditions:
00010  *
00011  * The above copyright notice and this permission notice shall be included in
00012  * all copies or substantial portions of the Software.
00013  *
00014  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00015  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00016  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00017  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00018  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00019  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00020  * THE SOFTWARE.
00021  */
00022 
00023 #ifndef FREETRONICSLCDSHIELD_H
00024 #define FREETRONICSLCDSHIELD_H
00025 
00026 #define LEFT  0
00027 #define RIGHT 1
00028 
00029 /** 
00030   * Provides full LCD support for the HD44780 compatible LCD on the arduino shaped shield.
00031   * http://www.freetronics.com/products/lcd-keypad-shield#.UnIr6_nkq0M
00032   *
00033   */
00034 class freetronicsLCDShield : public Stream {
00035     private:
00036         // Functions
00037         void writeByte (int byte);
00038         void writeCommand (int command);
00039         void writeData (int data);
00040         void character(int line, int col, int value);
00041         
00042         // Hardware         
00043         DigitalOut _rs, _e;
00044         BusOut _d;
00045         PwmOut _bl;
00046         AnalogIn _a0;
00047         
00048     public:
00049         /** 
00050          * The constructor creates an freeTronics LCD Shield object, the pins are to be provided by the user. In sequence, RegisterSelect, Enable, Data0 
00051          * to Data3. Bl is the backlight and a0 is to be provided for button support. 
00052          * Bl should be a pin with PWM capabilities and a0 should be an analogue input.
00053          * 
00054          * The class inherits from stream, therfore writing to the display is as easy as calling printf() to display text or putc() to display a custom character  
00055          * 
00056          * Example:
00057          * @code
00058          * <instanceName>.printf("Hello World");
00059          * @endcode         */ 
00060         freetronicsLCDShield (PinName rs /*= PTA13*/, 
00061                               PinName e  /*= PTD5*/, 
00062                               PinName d0 /*= PTA4*/, 
00063                               PinName d1 /*= PTA5*/, 
00064                               PinName d2 /*= PTC8*/, 
00065                               PinName d3 /*= PTC9*/,
00066                               PinName bl /*= PTA12*/,
00067                               PinName a0 /*= PTB0*/);                               
00068         /** Creates custom characters 
00069          *
00070          * Characters that aren't included in the LCD controllers character map which includes typically all ASCII characters 
00071          * can be generated by writing bitmaps to the character generator ram memory space. For instance the degree sign '°' is an 
00072          * extended ASCII character not included in the character map.
00073          * It can however be generated using the writeCGRAM member function. Each line of the 5x7 dot matrix is represented by a byte in which
00074          * the lower 5 bits correspond to the pixel on the display. In total 8 bytes make up one custom character (the 8th byte represents the
00075          * cursor space)
00076          *
00077          * Example:
00078          * @code
00079          * CGRAM_DATA[] = {0xC0,    //0b00001100
00080          *                 0x12,    //0b00010010 
00081          *                 0x12,    //0b00010010 
00082          *                 0xC0,    //0b00001100
00083          *                 0x00,    //0b00000000 
00084          *                 0x00,    //0b00000000 
00085          *                 0x00,    //0b00000000 
00086          *                 0x00};   //0b00000000
00087          * 
00088          * <instanceName>.writeCGRAM (0x00, &CGRAM_DATA[0], 8);
00089          * @endcode
00090          *
00091          * The '°' can hereafter be displayed by calling:
00092          * @code
00093          * <instanceName>.putc (0);
00094          * @endcode
00095          *
00096          */                        
00097         void writeCGRAM (char address, const char *ptr, char nbytes);
00098         
00099         /** Sets the current cursor position.
00100          *
00101          * To place the cursor at a specific location on the display call the setCursorPosition member function, the first argument is the line either 0 
00102          * or 1, the second argument is the column 0 .. 15.
00103          *
00104          */
00105         void setCursorPosition (int line, int col);
00106         
00107         /** Sets the backlight.
00108          * 
00109          * The backlight is turned on (argument true) or off (false) 
00110          */  
00111         void setBackLight (bool blStatus);
00112 
00113         /** Sets the backlight.
00114          * 
00115          * The backlight intensity is specified by the normalized float argument 0 .. 1 
00116          */  
00117         void setBackLight (float blIntensity);
00118         
00119         /** Sets cursor appearance.
00120          * 
00121          * The cursor is set visible (1st argument true) or invisible (false). When the second argument is set when the cStatus is set the cursor blinks. 
00122          */  
00123         void setCursor (bool cStatus = true, bool blink = false);
00124         
00125         /** Shifts text.
00126          * 
00127          * Text on the display is shifted left.
00128          */  
00129         void shiftLeft (void);
00130         
00131         /** Shifts text.
00132          * 
00133          * Text on the display is shifted right.
00134          */  
00135         void shiftRight (void);
00136         
00137  
00138         /** Shifts text.
00139          * 
00140          * Text on the display is shifted left if direction is set (true) or right is direction is reset (false)
00141          */  
00142         void shift (bool direction);
00143 
00144         /** Clears the display, the cursor returns to its home position (0,0).
00145          * 
00146          * The user should preserve caution when clearing the display in the main program loop, this very quickly results in flickering. A better approach is to
00147          * overwrite the display. 
00148          */  
00149         void cls (void);
00150 
00151         /** Returns the cursor to positition (0,0). The display is NOT cleared. 
00152          * 
00153          * This function differs from setCursorPosition(0,0) in the way that home() undoes all preceding shift operations. i.e. If the display is shifted
00154          * one position right, the setCursorPosition(0,0) function call would place the cursor physically at the second character of the first row while
00155          * home() places it at the first character of the first row. 
00156          */  
00157         void home(void);
00158         
00159         /** Reads the status of the buttons
00160          * 
00161          * 
00162          */  
00163         float readButton(void);
00164              
00165     protected:
00166         // Stream implementation functions
00167         virtual int _putc(int value);
00168         virtual int _getc();
00169 };
00170 
00171 #endif