John Bailey / freetronicsLCDShield

A basic library for the Freetronics arduino LCD shield.

Fork of freetronicsLCDShield by Koen Kempeneers

freetronicsLCDShield.h@3:0e04b6c4abb8, 2013-10-31 (annotated)

Committer:
KKempeneers
Date:
Thu Oct 31 14:26:31 2013 +0000
Revision:
3:0e04b6c4abb8
Parent:
2:f40a5df43d09
Child:
5:fa933933ccd1
Added API documentation

Who changed what in which revision?

UserRevisionLine numberNew contents of line
KKempeneers 1:ddcefddda4a7 1 /* mbed freetronicsLCDShield Library, written by Koen J.F. Kempeneers
KKempeneers 1:ddcefddda4a7 2 * koen.kempeneers@damiaaninstituut.be
KKempeneers 1:ddcefddda4a7 3 *
KKempeneers 1:ddcefddda4a7 4 * Permission is hereby granted, free of charge, to any person obtaining a copy
KKempeneers 1:ddcefddda4a7 5 * of this software and associated documentation files (the "Software"), to deal
KKempeneers 1:ddcefddda4a7 6 * in the Software without restriction, including without limitation the rights
KKempeneers 1:ddcefddda4a7 7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
KKempeneers 1:ddcefddda4a7 8 * copies of the Software, and to permit persons to whom the Software is
KKempeneers 1:ddcefddda4a7 9 * furnished to do so, subject to the following conditions:
KKempeneers 1:ddcefddda4a7 10 *
KKempeneers 1:ddcefddda4a7 11 * The above copyright notice and this permission notice shall be included in
KKempeneers 1:ddcefddda4a7 12 * all copies or substantial portions of the Software.
KKempeneers 1:ddcefddda4a7 13 *
KKempeneers 1:ddcefddda4a7 14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
KKempeneers 1:ddcefddda4a7 15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
KKempeneers 1:ddcefddda4a7 16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
KKempeneers 1:ddcefddda4a7 17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
KKempeneers 1:ddcefddda4a7 18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
KKempeneers 1:ddcefddda4a7 19 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
KKempeneers 1:ddcefddda4a7 20 * THE SOFTWARE.
KKempeneers 1:ddcefddda4a7 21 */
KKempeneers 1:ddcefddda4a7 22
KKempeneers 1:ddcefddda4a7 23 #ifndef FREETRONICSLCDSHIELD_H
KKempeneers 1:ddcefddda4a7 24 #define FREETRONICSLCDSHIELD_H
KKempeneers 1:ddcefddda4a7 25
KKempeneers 0:01f3d38f8b6d 26 #define LEFT 0
KKempeneers 0:01f3d38f8b6d 27 #define RIGHT 1
KKempeneers 0:01f3d38f8b6d 28
KKempeneers 3:0e04b6c4abb8 29 /**
KKempeneers 3:0e04b6c4abb8 30 * Provides full LCD support for the HD44780 compatible LCD on the arduino shaped shield.
KKempeneers 3:0e04b6c4abb8 31 * http://www.freetronics.com/products/lcd-keypad-shield#.UnIr6_nkq0M
KKempeneers 3:0e04b6c4abb8 32 *
KKempeneers 3:0e04b6c4abb8 33 */
KKempeneers 0:01f3d38f8b6d 34 class freetronicsLCDShield : public Stream {
KKempeneers 0:01f3d38f8b6d 35 private:
KKempeneers 0:01f3d38f8b6d 36 // Functions
KKempeneers 0:01f3d38f8b6d 37 void writeByte (int byte);
KKempeneers 0:01f3d38f8b6d 38 void writeCommand (int command);
KKempeneers 0:01f3d38f8b6d 39 void writeData (int data);
KKempeneers 0:01f3d38f8b6d 40 void character(int line, int col, int value);
KKempeneers 0:01f3d38f8b6d 41
KKempeneers 0:01f3d38f8b6d 42 // Hardware
KKempeneers 0:01f3d38f8b6d 43 DigitalOut _rs, _e;
KKempeneers 0:01f3d38f8b6d 44 BusOut _d;
KKempeneers 0:01f3d38f8b6d 45 PwmOut _bl;
KKempeneers 0:01f3d38f8b6d 46 AnalogIn _a0;
KKempeneers 0:01f3d38f8b6d 47
KKempeneers 0:01f3d38f8b6d 48 public:
KKempeneers 3:0e04b6c4abb8 49 /**
KKempeneers 3:0e04b6c4abb8 50 * The constructor creates an freeTronics LCD Shield object, the pins are to be provided by the user. In sequence, RegisterSelect, Enable, Data0
KKempeneers 3:0e04b6c4abb8 51 * to Data3. Bl is the backlight and a0 is to be provided for button support.
KKempeneers 3:0e04b6c4abb8 52 * Bl should be a pin with PWM capabilities and a0 should be an analogue input.
KKempeneers 3:0e04b6c4abb8 53 *
KKempeneers 3:0e04b6c4abb8 54 * 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
KKempeneers 3:0e04b6c4abb8 55 *
KKempeneers 3:0e04b6c4abb8 56 * Example:
KKempeneers 3:0e04b6c4abb8 57 * @code
KKempeneers 3:0e04b6c4abb8 58 * <instanceName>.printf("Hello World");
KKempeneers 3:0e04b6c4abb8 59 * @endcode */
KKempeneers 2:f40a5df43d09 60 freetronicsLCDShield (PinName rs /*= PTA13*/,
KKempeneers 2:f40a5df43d09 61 PinName e /*= PTD5*/,
KKempeneers 2:f40a5df43d09 62 PinName d0 /*= PTA4*/,
KKempeneers 2:f40a5df43d09 63 PinName d1 /*= PTA5*/,
KKempeneers 2:f40a5df43d09 64 PinName d2 /*= PTC8*/,
KKempeneers 2:f40a5df43d09 65 PinName d3 /*= PTC9*/,
KKempeneers 2:f40a5df43d09 66 PinName bl /*= PTA12*/,
KKempeneers 2:f40a5df43d09 67 PinName a0 /*= PTB0*/);
KKempeneers 3:0e04b6c4abb8 68 /** Creates custom characters
KKempeneers 3:0e04b6c4abb8 69 *
KKempeneers 3:0e04b6c4abb8 70 * Characters that aren't included in the LCD controllers character map which includes typically all ASCII characters
KKempeneers 3:0e04b6c4abb8 71 * can be generated by writing bitmaps to the character generator ram memory space. For instance the degree sign '°' is an
KKempeneers 3:0e04b6c4abb8 72 * extended ASCII character not included in the character map.
KKempeneers 3:0e04b6c4abb8 73 * It can however be generated using the writeCGRAM member function. Each line of the 5x7 dot matrix is represented by a byte in which
KKempeneers 3:0e04b6c4abb8 74 * 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
KKempeneers 3:0e04b6c4abb8 75 * cursor space)
KKempeneers 3:0e04b6c4abb8 76 *
KKempeneers 3:0e04b6c4abb8 77 * Example:
KKempeneers 3:0e04b6c4abb8 78 * @code
KKempeneers 3:0e04b6c4abb8 79 * CGRAM_DATA[] = {0xC0, //0b00001100
KKempeneers 3:0e04b6c4abb8 80 * 0x12, //0b00010010
KKempeneers 3:0e04b6c4abb8 81 * 0x12, //0b00010010
KKempeneers 3:0e04b6c4abb8 82 * 0xC0, //0b00001100
KKempeneers 3:0e04b6c4abb8 83 * 0x00, //0b00000000
KKempeneers 3:0e04b6c4abb8 84 * 0x00, //0b00000000
KKempeneers 3:0e04b6c4abb8 85 * 0x00, //0b00000000
KKempeneers 3:0e04b6c4abb8 86 * 0x00}; //0b00000000
KKempeneers 3:0e04b6c4abb8 87 *
KKempeneers 3:0e04b6c4abb8 88 * <instanceName>.writeCGRAM (0x00, &CGRAM_DATA[0], 8);
KKempeneers 3:0e04b6c4abb8 89 * @endcode
KKempeneers 3:0e04b6c4abb8 90 *
KKempeneers 3:0e04b6c4abb8 91 * The '°' can hereafter be displayed by calling:
KKempeneers 3:0e04b6c4abb8 92 * @code
KKempeneers 3:0e04b6c4abb8 93 * <instanceName>.putc (0);
KKempeneers 3:0e04b6c4abb8 94 * @endcode
KKempeneers 3:0e04b6c4abb8 95 *
KKempeneers 3:0e04b6c4abb8 96 */
KKempeneers 1:ddcefddda4a7 97 void writeCGRAM (char address, const char *ptr, char nbytes);
KKempeneers 3:0e04b6c4abb8 98
KKempeneers 3:0e04b6c4abb8 99 /** Sets the current cursor position.
KKempeneers 3:0e04b6c4abb8 100 *
KKempeneers 3:0e04b6c4abb8 101 * To place the cursor at a specific location on the display call the setCursorPosition member function, the first argument is the line either 0
KKempeneers 3:0e04b6c4abb8 102 * or 1, the second argument is the column 0 .. 15.
KKempeneers 3:0e04b6c4abb8 103 *
KKempeneers 3:0e04b6c4abb8 104 */
KKempeneers 0:01f3d38f8b6d 105 void setCursorPosition (int line, int col);
KKempeneers 3:0e04b6c4abb8 106
KKempeneers 3:0e04b6c4abb8 107 /** Sets the backlight.
KKempeneers 3:0e04b6c4abb8 108 *
KKempeneers 3:0e04b6c4abb8 109 * The backlight is turned on (argument true) or off (false)
KKempeneers 3:0e04b6c4abb8 110 */
KKempeneers 0:01f3d38f8b6d 111 void setBackLight (bool blStatus);
KKempeneers 3:0e04b6c4abb8 112
KKempeneers 3:0e04b6c4abb8 113 /** Sets the backlight.
KKempeneers 3:0e04b6c4abb8 114 *
KKempeneers 3:0e04b6c4abb8 115 * The backlight intensity is specified by the normalized float argument 0 .. 1
KKempeneers 3:0e04b6c4abb8 116 */
KKempeneers 0:01f3d38f8b6d 117 void setBackLight (float blIntensity);
KKempeneers 3:0e04b6c4abb8 118
KKempeneers 3:0e04b6c4abb8 119 /** Sets cursor appearance.
KKempeneers 3:0e04b6c4abb8 120 *
KKempeneers 3:0e04b6c4abb8 121 * 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.
KKempeneers 3:0e04b6c4abb8 122 */
KKempeneers 1:ddcefddda4a7 123 void setCursor (bool cStatus = true, bool blink = false);
KKempeneers 3:0e04b6c4abb8 124
KKempeneers 3:0e04b6c4abb8 125 /** Shifts text.
KKempeneers 3:0e04b6c4abb8 126 *
KKempeneers 3:0e04b6c4abb8 127 * Text on the display is shifted left.
KKempeneers 3:0e04b6c4abb8 128 */
KKempeneers 1:ddcefddda4a7 129 void shiftLeft (void);
KKempeneers 3:0e04b6c4abb8 130
KKempeneers 3:0e04b6c4abb8 131 /** Shifts text.
KKempeneers 3:0e04b6c4abb8 132 *
KKempeneers 3:0e04b6c4abb8 133 * Text on the display is shifted right.
KKempeneers 3:0e04b6c4abb8 134 */
KKempeneers 1:ddcefddda4a7 135 void shiftRight (void);
KKempeneers 3:0e04b6c4abb8 136
KKempeneers 3:0e04b6c4abb8 137
KKempeneers 3:0e04b6c4abb8 138 /** Shifts text.
KKempeneers 3:0e04b6c4abb8 139 *
KKempeneers 3:0e04b6c4abb8 140 * Text on the display is shifted left if direction is set (true) or right is direction is reset (false)
KKempeneers 3:0e04b6c4abb8 141 */
KKempeneers 1:ddcefddda4a7 142 void shift (bool direction);
KKempeneers 3:0e04b6c4abb8 143
KKempeneers 3:0e04b6c4abb8 144 /** Clears the display, the cursor returns to its home position (0,0).
KKempeneers 3:0e04b6c4abb8 145 *
KKempeneers 3:0e04b6c4abb8 146 * 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
KKempeneers 3:0e04b6c4abb8 147 * overwrite the display.
KKempeneers 3:0e04b6c4abb8 148 */
KKempeneers 0:01f3d38f8b6d 149 void cls (void);
KKempeneers 3:0e04b6c4abb8 150
KKempeneers 3:0e04b6c4abb8 151 /** Returns the cursor to positition (0,0). The display is NOT cleared.
KKempeneers 3:0e04b6c4abb8 152 *
KKempeneers 3:0e04b6c4abb8 153 * This function differs from setCursorPosition(0,0) in the way that home() undoes all preceding shift operations. i.e. If the display is shifted
KKempeneers 3:0e04b6c4abb8 154 * one position right, the setCursorPosition(0,0) function call would place the cursor physically at the second character of the first row while
KKempeneers 3:0e04b6c4abb8 155 * home() places it at the first character of the first row.
KKempeneers 3:0e04b6c4abb8 156 */
KKempeneers 0:01f3d38f8b6d 157 void home(void);
KKempeneers 0:01f3d38f8b6d 158
KKempeneers 3:0e04b6c4abb8 159 /** Reads the status of the buttons
KKempeneers 3:0e04b6c4abb8 160 *
KKempeneers 3:0e04b6c4abb8 161 *
KKempeneers 3:0e04b6c4abb8 162 */
KKempeneers 0:01f3d38f8b6d 163 float readButton(void);
KKempeneers 0:01f3d38f8b6d 164
KKempeneers 0:01f3d38f8b6d 165 protected:
KKempeneers 0:01f3d38f8b6d 166 // Stream implementation functions
KKempeneers 0:01f3d38f8b6d 167 virtual int _putc(int value);
KKempeneers 0:01f3d38f8b6d 168 virtual int _getc();
KKempeneers 1:ddcefddda4a7 169 };
KKempeneers 1:ddcefddda4a7 170
KKempeneers 1:ddcefddda4a7 171 #endif