John Bailey / freetronicsLCDShield

A basic library for the Freetronics arduino LCD shield.

Fork of freetronicsLCDShield by Koen Kempeneers

freetronicsLCDShield.h@7:56d8df0eb209, 2017-07-02 (annotated)

Committer:
johnb
Date:
Sun Jul 02 15:26:57 2017 +0000
Revision:
7:56d8df0eb209
Parent:
6:ac481535732f 
Updated threshold value & added comments

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 5:fa933933ccd1 2 * kkempeneers@skynet.be
johnb 7:56d8df0eb209 3 * Improved button support added by John Bailey
johnb 7:56d8df0eb209 4 * jdb__mbed(at)anotherdimension.net
KKempeneers 1:ddcefddda4a7 5 *
KKempeneers 1:ddcefddda4a7 6 * Permission is hereby granted, free of charge, to any person obtaining a copy
KKempeneers 1:ddcefddda4a7 7 * of this software and associated documentation files (the "Software"), to deal
KKempeneers 1:ddcefddda4a7 8 * in the Software without restriction, including without limitation the rights
KKempeneers 1:ddcefddda4a7 9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
KKempeneers 1:ddcefddda4a7 10 * copies of the Software, and to permit persons to whom the Software is
KKempeneers 1:ddcefddda4a7 11 * furnished to do so, subject to the following conditions:
KKempeneers 1:ddcefddda4a7 12 *
KKempeneers 1:ddcefddda4a7 13 * The above copyright notice and this permission notice shall be included in
KKempeneers 1:ddcefddda4a7 14 * all copies or substantial portions of the Software.
KKempeneers 1:ddcefddda4a7 15 *
KKempeneers 1:ddcefddda4a7 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
KKempeneers 1:ddcefddda4a7 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
KKempeneers 1:ddcefddda4a7 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
KKempeneers 1:ddcefddda4a7 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
KKempeneers 1:ddcefddda4a7 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
KKempeneers 1:ddcefddda4a7 21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
KKempeneers 1:ddcefddda4a7 22 * THE SOFTWARE.
KKempeneers 1:ddcefddda4a7 23 */
KKempeneers 1:ddcefddda4a7 24
KKempeneers 1:ddcefddda4a7 25 #ifndef FREETRONICSLCDSHIELD_H
KKempeneers 1:ddcefddda4a7 26 #define FREETRONICSLCDSHIELD_H
KKempeneers 1:ddcefddda4a7 27
KKempeneers 0:01f3d38f8b6d 28 #define LEFT 0
KKempeneers 0:01f3d38f8b6d 29 #define RIGHT 1
KKempeneers 0:01f3d38f8b6d 30
johnb 7:56d8df0eb209 31 /** Number of detectable buttons on the shield, Left, Right, Up, Down, plus one for "No button" */
johnb 6:ac481535732f 32 #define FREETRONICSLCDSHIELD_BUTTON_COUNT 5
johnb 6:ac481535732f 33
KKempeneers 3:0e04b6c4abb8 34 /**
KKempeneers 3:0e04b6c4abb8 35 * Provides full LCD support for the HD44780 compatible LCD on the arduino shaped shield.
KKempeneers 3:0e04b6c4abb8 36 * http://www.freetronics.com/products/lcd-keypad-shield#.UnIr6_nkq0M
KKempeneers 3:0e04b6c4abb8 37 *
KKempeneers 3:0e04b6c4abb8 38 */
KKempeneers 0:01f3d38f8b6d 39 class freetronicsLCDShield : public Stream {
KKempeneers 0:01f3d38f8b6d 40 private:
KKempeneers 0:01f3d38f8b6d 41 // Functions
KKempeneers 0:01f3d38f8b6d 42 void writeByte (int byte);
KKempeneers 0:01f3d38f8b6d 43 void writeCommand (int command);
KKempeneers 0:01f3d38f8b6d 44 void writeData (int data);
KKempeneers 0:01f3d38f8b6d 45 void character(int line, int col, int value);
KKempeneers 0:01f3d38f8b6d 46
KKempeneers 0:01f3d38f8b6d 47 // Hardware
KKempeneers 0:01f3d38f8b6d 48 DigitalOut _rs, _e;
KKempeneers 0:01f3d38f8b6d 49 BusOut _d;
KKempeneers 0:01f3d38f8b6d 50 PwmOut _bl;
KKempeneers 0:01f3d38f8b6d 51 AnalogIn _a0;
KKempeneers 0:01f3d38f8b6d 52
KKempeneers 0:01f3d38f8b6d 53 public:
KKempeneers 3:0e04b6c4abb8 54 /**
KKempeneers 3:0e04b6c4abb8 55 * 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 56 * to Data3. Bl is the backlight and a0 is to be provided for button support.
KKempeneers 3:0e04b6c4abb8 57 * Bl should be a pin with PWM capabilities and a0 should be an analogue input.
KKempeneers 3:0e04b6c4abb8 58 *
KKempeneers 3:0e04b6c4abb8 59 * 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 60 *
KKempeneers 3:0e04b6c4abb8 61 * Example:
KKempeneers 3:0e04b6c4abb8 62 * @code
KKempeneers 3:0e04b6c4abb8 63 * <instanceName>.printf("Hello World");
KKempeneers 3:0e04b6c4abb8 64 * @endcode */
KKempeneers 2:f40a5df43d09 65 freetronicsLCDShield (PinName rs /*= PTA13*/,
KKempeneers 2:f40a5df43d09 66 PinName e /*= PTD5*/,
KKempeneers 2:f40a5df43d09 67 PinName d0 /*= PTA4*/,
KKempeneers 2:f40a5df43d09 68 PinName d1 /*= PTA5*/,
KKempeneers 2:f40a5df43d09 69 PinName d2 /*= PTC8*/,
KKempeneers 2:f40a5df43d09 70 PinName d3 /*= PTC9*/,
KKempeneers 2:f40a5df43d09 71 PinName bl /*= PTA12*/,
KKempeneers 2:f40a5df43d09 72 PinName a0 /*= PTB0*/);
KKempeneers 3:0e04b6c4abb8 73 /** Creates custom characters
KKempeneers 3:0e04b6c4abb8 74 *
KKempeneers 3:0e04b6c4abb8 75 * Characters that aren't included in the LCD controllers character map which includes typically all ASCII characters
KKempeneers 3:0e04b6c4abb8 76 * can be generated by writing bitmaps to the character generator ram memory space. For instance the degree sign '°' is an
KKempeneers 3:0e04b6c4abb8 77 * extended ASCII character not included in the character map.
KKempeneers 3:0e04b6c4abb8 78 * 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 79 * 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 80 * cursor space)
KKempeneers 3:0e04b6c4abb8 81 *
KKempeneers 3:0e04b6c4abb8 82 * Example:
KKempeneers 3:0e04b6c4abb8 83 * @code
KKempeneers 3:0e04b6c4abb8 84 * CGRAM_DATA[] = {0xC0, //0b00001100
KKempeneers 3:0e04b6c4abb8 85 * 0x12, //0b00010010
KKempeneers 3:0e04b6c4abb8 86 * 0x12, //0b00010010
KKempeneers 3:0e04b6c4abb8 87 * 0xC0, //0b00001100
KKempeneers 3:0e04b6c4abb8 88 * 0x00, //0b00000000
KKempeneers 3:0e04b6c4abb8 89 * 0x00, //0b00000000
KKempeneers 3:0e04b6c4abb8 90 * 0x00, //0b00000000
KKempeneers 3:0e04b6c4abb8 91 * 0x00}; //0b00000000
KKempeneers 3:0e04b6c4abb8 92 *
KKempeneers 3:0e04b6c4abb8 93 * <instanceName>.writeCGRAM (0x00, &CGRAM_DATA[0], 8);
KKempeneers 3:0e04b6c4abb8 94 * @endcode
KKempeneers 3:0e04b6c4abb8 95 *
KKempeneers 3:0e04b6c4abb8 96 * The '°' can hereafter be displayed by calling:
KKempeneers 3:0e04b6c4abb8 97 * @code
KKempeneers 3:0e04b6c4abb8 98 * <instanceName>.putc (0);
KKempeneers 3:0e04b6c4abb8 99 * @endcode
KKempeneers 3:0e04b6c4abb8 100 *
KKempeneers 3:0e04b6c4abb8 101 */
KKempeneers 1:ddcefddda4a7 102 void writeCGRAM (char address, const char *ptr, char nbytes);
KKempeneers 3:0e04b6c4abb8 103
KKempeneers 3:0e04b6c4abb8 104 /** Sets the current cursor position.
KKempeneers 3:0e04b6c4abb8 105 *
KKempeneers 3:0e04b6c4abb8 106 * 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 107 * or 1, the second argument is the column 0 .. 15.
KKempeneers 3:0e04b6c4abb8 108 *
KKempeneers 3:0e04b6c4abb8 109 */
KKempeneers 0:01f3d38f8b6d 110 void setCursorPosition (int line, int col);
KKempeneers 3:0e04b6c4abb8 111
KKempeneers 3:0e04b6c4abb8 112 /** Sets the backlight.
KKempeneers 3:0e04b6c4abb8 113 *
KKempeneers 3:0e04b6c4abb8 114 * The backlight is turned on (argument true) or off (false)
KKempeneers 3:0e04b6c4abb8 115 */
KKempeneers 0:01f3d38f8b6d 116 void setBackLight (bool blStatus);
KKempeneers 3:0e04b6c4abb8 117
KKempeneers 3:0e04b6c4abb8 118 /** Sets the backlight.
KKempeneers 3:0e04b6c4abb8 119 *
KKempeneers 3:0e04b6c4abb8 120 * The backlight intensity is specified by the normalized float argument 0 .. 1
KKempeneers 3:0e04b6c4abb8 121 */
KKempeneers 0:01f3d38f8b6d 122 void setBackLight (float blIntensity);
KKempeneers 3:0e04b6c4abb8 123
KKempeneers 3:0e04b6c4abb8 124 /** Sets cursor appearance.
KKempeneers 3:0e04b6c4abb8 125 *
KKempeneers 3:0e04b6c4abb8 126 * 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 127 */
KKempeneers 1:ddcefddda4a7 128 void setCursor (bool cStatus = true, bool blink = false);
KKempeneers 3:0e04b6c4abb8 129
KKempeneers 3:0e04b6c4abb8 130 /** Shifts text.
KKempeneers 3:0e04b6c4abb8 131 *
KKempeneers 3:0e04b6c4abb8 132 * Text on the display is shifted left.
KKempeneers 3:0e04b6c4abb8 133 */
KKempeneers 1:ddcefddda4a7 134 void shiftLeft (void);
KKempeneers 3:0e04b6c4abb8 135
KKempeneers 3:0e04b6c4abb8 136 /** Shifts text.
KKempeneers 3:0e04b6c4abb8 137 *
KKempeneers 3:0e04b6c4abb8 138 * Text on the display is shifted right.
KKempeneers 3:0e04b6c4abb8 139 */
KKempeneers 1:ddcefddda4a7 140 void shiftRight (void);
KKempeneers 3:0e04b6c4abb8 141
KKempeneers 3:0e04b6c4abb8 142
KKempeneers 3:0e04b6c4abb8 143 /** Shifts text.
KKempeneers 3:0e04b6c4abb8 144 *
KKempeneers 3:0e04b6c4abb8 145 * Text on the display is shifted left if direction is set (true) or right is direction is reset (false)
KKempeneers 3:0e04b6c4abb8 146 */
KKempeneers 1:ddcefddda4a7 147 void shift (bool direction);
KKempeneers 3:0e04b6c4abb8 148
KKempeneers 3:0e04b6c4abb8 149 /** Clears the display, the cursor returns to its home position (0,0).
KKempeneers 3:0e04b6c4abb8 150 *
KKempeneers 3:0e04b6c4abb8 151 * 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 152 * overwrite the display.
KKempeneers 3:0e04b6c4abb8 153 */
KKempeneers 0:01f3d38f8b6d 154 void cls (void);
KKempeneers 3:0e04b6c4abb8 155
KKempeneers 3:0e04b6c4abb8 156 /** Returns the cursor to positition (0,0). The display is NOT cleared.
KKempeneers 3:0e04b6c4abb8 157 *
KKempeneers 3:0e04b6c4abb8 158 * 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 159 * 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 160 * home() places it at the first character of the first row.
KKempeneers 3:0e04b6c4abb8 161 */
KKempeneers 0:01f3d38f8b6d 162 void home(void);
KKempeneers 0:01f3d38f8b6d 163
johnb 6:ac481535732f 164 typedef enum
johnb 6:ac481535732f 165 {
johnb 6:ac481535732f 166 None,
johnb 6:ac481535732f 167 Left,
johnb 6:ac481535732f 168 Down,
johnb 6:ac481535732f 169 Up,
johnb 6:ac481535732f 170 Right
johnb 6:ac481535732f 171 } ShieldButton;
johnb 6:ac481535732f 172
KKempeneers 3:0e04b6c4abb8 173 /** Reads the status of the buttons
KKempeneers 3:0e04b6c4abb8 174 *
johnb 7:56d8df0eb209 175 * This function returns the ADC value of the input connected to the buttons. When no button is pressed, this input is pulled high.
johnb 7:56d8df0eb209 176 * If any button is pressed, the input is connected to ground via a resistor & the function will return a value less than 1.0,
johnb 7:56d8df0eb209 177 * depending on the button. Approximate values (sourced from the schematic) are:
johnb 7:56d8df0eb209 178 * Left: 2.47V -> ADC 0.748
johnb 7:56d8df0eb209 179 * Down: 1.61V -> ADC 0.488
johnb 7:56d8df0eb209 180 * Up: 0.71V -> ADC 0.215
johnb 7:56d8df0eb209 181 * Right: 0.00V -> ADC 0.000
johnb 7:56d8df0eb209 182 * 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,
johnb 7:56d8df0eb209 183 * saturating the input and indistinguishable from no button being pressed.
KKempeneers 3:0e04b6c4abb8 184 */
KKempeneers 0:01f3d38f8b6d 185 float readButton(void);
KKempeneers 0:01f3d38f8b6d 186
johnb 7:56d8df0eb209 187 /** Determines which of the buttons is currently pressed
johnb 7:56d8df0eb209 188 *
johnb 7:56d8df0eb209 189 * Note that the shield design means that multi-button detection is not practical
johnb 7:56d8df0eb209 190 */
johnb 6:ac481535732f 191 ShieldButton pressedButton(void);
johnb 6:ac481535732f 192
KKempeneers 0:01f3d38f8b6d 193 protected:
KKempeneers 0:01f3d38f8b6d 194 // Stream implementation functions
KKempeneers 0:01f3d38f8b6d 195 virtual int _putc(int value);
KKempeneers 0:01f3d38f8b6d 196 virtual int _getc();
johnb 6:ac481535732f 197
johnb 7:56d8df0eb209 198 /** Lower thresholds for the ADC value for each push button on the shield */
johnb 6:ac481535732f 199 static const float buttonThresholds[FREETRONICSLCDSHIELD_BUTTON_COUNT];
KKempeneers 1:ddcefddda4a7 200 };
KKempeneers 1:ddcefddda4a7 201
KKempeneers 1:ddcefddda4a7 202 #endif