freetronicsLCDShield.h

00001 /* mbed freetronicsLCDShield Library, written by Koen J.F. Kempeneers
00002  * kkempeneers@skynet.be
00003  * Improved button support added by John Bailey 
00004  * jdb__mbed(at)anotherdimension.net
00005  *
00006  * Permission is hereby granted, free of charge, to any person obtaining a copy
00007  * of this software and associated documentation files (the "Software"), to deal
00008  * in the Software without restriction, including without limitation the rights
00009  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00010  * copies of the Software, and to permit persons to whom the Software is
00011  * furnished to do so, subject to the following conditions:
00012  *
00013  * The above copyright notice and this permission notice shall be included in
00014  * all copies or substantial portions of the Software.
00015  *
00016  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00017  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00018  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00019  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00020  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00021  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00022  * THE SOFTWARE.
00023  */
00024 
00025 #ifndef FREETRONICSLCDSHIELD_H
00026 #define FREETRONICSLCDSHIELD_H
00027 
00028 #define LEFT  0
00029 #define RIGHT 1
00030 
00031 /** Number of detectable buttons on the shield, Left, Right, Up, Down, plus one for "No button" */
00032 #define FREETRONICSLCDSHIELD_BUTTON_COUNT 5
00033 
00034 /** 
00035   * Provides full LCD support for the HD44780 compatible LCD on the arduino shaped shield.
00036   * http://www.freetronics.com/products/lcd-keypad-shield#.UnIr6_nkq0M
00037   *
00038   */
00039 class freetronicsLCDShield : public Stream {
00040     private:
00041         // Functions
00042         void writeByte (int byte);
00043         void writeCommand (int command);
00044         void writeData (int data);
00045         void character(int line, int col, int value);
00046         
00047         // Hardware         
00048         DigitalOut _rs, _e;
00049         BusOut _d;
00050         PwmOut _bl;
00051         AnalogIn _a0;
00052         
00053     public:
00054         /** 
00055          * The constructor creates an freeTronics LCD Shield object, the pins are to be provided by the user. In sequence, RegisterSelect, Enable, Data0 
00056          * to Data3. Bl is the backlight and a0 is to be provided for button support. 
00057          * Bl should be a pin with PWM capabilities and a0 should be an analogue input.
00058          * 
00059          * 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  
00060          * 
00061          * Example:
00062          * @code
00063          * <instanceName>.printf("Hello World");
00064          * @endcode         */ 
00065         freetronicsLCDShield (PinName rs /*= PTA13*/, 
00066                               PinName e  /*= PTD5*/, 
00067                               PinName d0 /*= PTA4*/, 
00068                               PinName d1 /*= PTA5*/, 
00069                               PinName d2 /*= PTC8*/, 
00070                               PinName d3 /*= PTC9*/,
00071                               PinName bl /*= PTA12*/,
00072                               PinName a0 /*= PTB0*/);                               
00073         /** Creates custom characters 
00074          *
00075          * Characters that aren't included in the LCD controllers character map which includes typically all ASCII characters 
00076          * can be generated by writing bitmaps to the character generator ram memory space. For instance the degree sign '°' is an 
00077          * extended ASCII character not included in the character map.
00078          * It can however be generated using the writeCGRAM member function. Each line of the 5x7 dot matrix is represented by a byte in which
00079          * 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
00080          * cursor space)
00081          *
00082          * Example:
00083          * @code
00084          * CGRAM_DATA[] = {0xC0,    //0b00001100
00085          *                 0x12,    //0b00010010 
00086          *                 0x12,    //0b00010010 
00087          *                 0xC0,    //0b00001100
00088          *                 0x00,    //0b00000000 
00089          *                 0x00,    //0b00000000 
00090          *                 0x00,    //0b00000000 
00091          *                 0x00};   //0b00000000
00092          * 
00093          * <instanceName>.writeCGRAM (0x00, &CGRAM_DATA[0], 8);
00094          * @endcode
00095          *
00096          * The '°' can hereafter be displayed by calling:
00097          * @code
00098          * <instanceName>.putc (0);
00099          * @endcode
00100          *
00101          */                        
00102         void writeCGRAM (char address, const char *ptr, char nbytes);
00103         
00104         /** Sets the current cursor position.
00105          *
00106          * To place the cursor at a specific location on the display call the setCursorPosition member function, the first argument is the line either 0 
00107          * or 1, the second argument is the column 0 .. 15.
00108          *
00109          */
00110         void setCursorPosition (int line, int col);
00111         
00112         /** Sets the backlight.
00113          * 
00114          * The backlight is turned on (argument true) or off (false) 
00115          */  
00116         void setBackLight (bool blStatus);
00117 
00118         /** Sets the backlight.
00119          * 
00120          * The backlight intensity is specified by the normalized float argument 0 .. 1 
00121          */  
00122         void setBackLight (float blIntensity);
00123         
00124         /** Sets cursor appearance.
00125          * 
00126          * 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. 
00127          */  
00128         void setCursor (bool cStatus = true, bool blink = false);
00129         
00130         /** Shifts text.
00131          * 
00132          * Text on the display is shifted left.
00133          */  
00134         void shiftLeft (void);
00135         
00136         /** Shifts text.
00137          * 
00138          * Text on the display is shifted right.
00139          */  
00140         void shiftRight (void);
00141         
00142  
00143         /** Shifts text.
00144          * 
00145          * Text on the display is shifted left if direction is set (true) or right is direction is reset (false)
00146          */  
00147         void shift (bool direction);
00148 
00149         /** Clears the display, the cursor returns to its home position (0,0).
00150          * 
00151          * 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
00152          * overwrite the display. 
00153          */  
00154         void cls (void);
00155 
00156         /** Returns the cursor to positition (0,0). The display is NOT cleared. 
00157          * 
00158          * This function differs from setCursorPosition(0,0) in the way that home() undoes all preceding shift operations. i.e. If the display is shifted
00159          * one position right, the setCursorPosition(0,0) function call would place the cursor physically at the second character of the first row while
00160          * home() places it at the first character of the first row. 
00161          */  
00162         void home(void);
00163         
00164         typedef enum
00165         {
00166             None,
00167             Left,
00168             Down,
00169             Up,
00170             Right
00171         } ShieldButton; 
00172         
00173         /** Reads the status of the buttons
00174          * 
00175          * This function returns the ADC value of the input connected to the buttons.  When no button is pressed, this input is pulled high.
00176          * If any button is pressed, the input is connected to ground via a resistor & the function will return a value less than 1.0, 
00177          * depending on the button.  Approximate values (sourced from the schematic) are:
00178          *  Left:  2.47V -> ADC 0.748
00179          *  Down:  1.61V -> ADC 0.488
00180          *  Up:    0.71V -> ADC 0.215
00181          *  Right: 0.00V -> ADC 0.000
00182          * Note that as ADC inputs are referenced to 3.3V, the select button cannot be read (as the voltage when this buttong is pressed is 3.62V,
00183          * saturating the input and indistinguishable from no button being pressed.
00184          */  
00185         float readButton(void);
00186              
00187         /** Determines which of the buttons is currently pressed
00188          *
00189          * Note that the shield design means that multi-button detection is not practical 
00190          */
00191         ShieldButton pressedButton(void);     
00192              
00193     protected:
00194         // Stream implementation functions
00195         virtual int _putc(int value);
00196         virtual int _getc();
00197                 
00198         /** Lower thresholds for the ADC value for each push button on the shield */
00199         static const float buttonThresholds[FREETRONICSLCDSHIELD_BUTTON_COUNT];
00200 };
00201 
00202 #endif