serLCD - Sparkfun serLCD Library

This is my attempt at porting LiquidCrystal library for use with serial displays. It implements most all functions from LiquidCrystal and added a few functions of my own. This library subclasses NewSoftSerial.

Since version 1.5 the library no longer subclasses NewSoftSerial as it is Arduino 1.0 compatible. Please download v1.5 from:

Download Here: https://github.com/nemith/serLCD

The up to date version (1.7) is below.

Functions

Examples

CODE

serLCD.h

  1. /*
  2.  serLCD.h - Library for controlling a SparkFun serLCD module
  3.             Code written for firmware version 2.5
  4.  
  5.  Created by Cody B. Null, September 9, 2011
  6.  Modified by Jordan Hochenbaum, Dec 5, 2011. (Version 1.5)
  7.  Modified by Johan Korten, March 23, 2013. (Version 1.6)
  8. Modified by Florentin Salomez, June 18, 2016 (Version 1.7)
  9.  
  10.  
  11.  Version 1.4 - This version wrote specifically for 16x2
  12.                Display.
  13.                More display support coming in later version.
  14.  
  15.  Version 1.5 - Since mid 2011 the Arduino IDE has implemented the NewSoftSerial
  16.                library updates in the standard SoftwareSerial library and so
  17.                using NewSoftSerial is no longer needed. serLCD has been updated
  18.                to use the Standard SoftwareSerial library. Also, Arduino 1.0
  19.                support has been added. Backwards compatible with previous versions.
  20.  
  21.  Version 1.6 - Added support for the setType special command.
  22.                                 This will help using different LCD's (2x16, 2x20, 4x16, 4x20).  
  23.                       Added support for scrollLeft and scrollRight commands.
  24.  
  25. Version 1.7 - Completed the setType special command.
  26.                         Now the setCursor function works correctly.
  27.                         Added keywords.txt and library.properties file.
  28.  
  29.  Note - This library requires NewSoftSerial library
  30.         The latest version of NewSoftSerial library can
  31.         always be found at http://arduiniana.org. -> NO LONGER NECESSARY. See 1.5 notes above.-Jordan Hochenbaum
  32. */
  33. #ifndef serLCD_h
  34. #define serLCD_h
  35.  
  36. #if ARDUINO >= 100
  37. #include "Arduino.h"       // for delayMicroseconds,digitalPinToBitMask, etc
  38. #else
  39. #include "WProgram.h"      // for delayMicroseconds
  40. #include "pins_arduino.h"  // for digitalPinToBitMask, etc
  41. #endif
  42. #include "SoftwareSerial.h"
  43.  
  44. // Commands
  45. #define LCD_BACKLIGHT           0x80
  46. #define LCD_CLEARDISPLAY        0x01
  47. #define LCD_CURSORSHIFT         0x10
  48. #define LCD_DISPLAYCONTROL      0x08
  49. #define LCD_ENTRYMODESET        0x04
  50. #define LCD_FUNCTIONSET         0x20
  51. #define LCD_SETCGRAMADDR        0x40
  52. #define LCD_SETDDRAMADDR        0x80
  53. #define LCD_SETSPLASHSCREEN     0x0A
  54. #define LCD_SPLASHTOGGLE        0x09
  55. #define LCD_RETURNHOME          0x02
  56.  
  57. // Flags for display entry mode
  58. #define LCD_ENTRYRIGHT          0x00
  59. #define LCD_ENTRYLEFT           0x02
  60.  
  61. // Flags for display on/off control
  62. #define LCD_BLINKON             0x01
  63. #define LCD_CURSORON            0x02
  64. #define LCD_DISPLAYON           0x04
  65.  
  66. // Flags for display size
  67. #define LCD_2LINE               0x02
  68. #define LCD_4LINE               0x04
  69. #define LCD_16CHAR              0x10
  70. #define LCD_20CHAR              0x14
  71.  
  72. //  Flags for setting display size
  73. #define LCD_SET2LINE            0x06
  74. #define LCD_SET4LINE            0x05
  75. #define LCD_SET16CHAR           0x04
  76. #define LCD_SET20CHAR           0x03
  77.  
  78. class serLCD : public SoftwareSerial {
  79. public:
  80.         serLCD (int pin);
  81.  
  82.         void clear();
  83.         void clearLine(int);
  84.         void home();
  85.         void setBrightness(int);
  86.  
  87.         void setSplash();
  88.         void setType(int);  // new in 1.6
  89.         void scrollLeft();  // new in 1.6
  90.         void scrollRight(); // new in 1.6
  91.         void toggleSplash();
  92.  
  93.         void blink();
  94.         void noBlink();
  95.         void cursor();
  96.         void noCursor();
  97.         void display();
  98.         void noDisplay();
  99.  
  100.         void setCursor(int, int);
  101.         void selectLine(int);
  102.  
  103.         void leftToRight();
  104.         void rightToLeft();
  105.         void autoscroll();
  106.         void noAutoscroll();
  107.  
  108.         void createChar(int, uint8_t[]);
  109.         void printCustomChar(int);
  110.  
  111. private:
  112.         void command(uint8_t);
  113.         void specialCommand(uint8_t);
  114.  
  115.         uint8_t _displayfunction;
  116.         uint8_t _displaycontrol;
  117.         uint8_t _displaymode;
  118.         uint8_t _numlines;
  119.         uint8_t _numchars;
  120.         uint8_t _rowoffset;
  121. };
  122.  
  123. #endif

serLCD.cpp

  1. /*
  2.  serLCD.cpp - Library for controlling a SparkFun serLCD
  3.               module.
  4.               Code written for firmware version 2.5
  5.  
  6.  Created by Cody B. Null, September 9, 2011
  7.  Modified by Jordan Hochenbaum, Dec 5, 2011. (Version 1.5)
  8.  Modified by Johan Korten, March 23, 2013. (Version 1.6)
  9.  Modified by Florentin Salomez, June 18, 2016 (Version 1.7)
  10.  
  11.  
  12.  Version 1.4 - This version wrote specifically for 16x2
  13.                Display.
  14.                More display support coming in later version.
  15.  
  16.  Version 1.5 - Since mid 2011 the Arduino IDE has implemented the NewSoftSerial
  17.                 library updates in the standard SoftwareSerial library and so
  18.                 using NewSoftSerial is no longer needed. serLCD has been updated
  19.                 to use the Standard SoftwareSerial library. Also, Arduino 1.0
  20.                 support has been added. Backwards compatible with previous versions.
  21.  
  22.  Version 1.6 - Added support for the setType special command.
  23.                                 This will help using different LCD's (2x16, 2x20, 4x16, 4x20).  
  24.                       Added support for scrollLeft and scrollRight commands.
  25.  
  26. Version 1.7 - Completed the setType special command.
  27.                                 Now the setCursor function works correctly.
  28.                                 Added keywords.txt and library.properties file.
  29.  
  30.  Note - This library requires NewSoftSerial library
  31.  The latest version of NewSoftSerial library can
  32.  always be found at http://arduiniana.org. -> NO LONGER NECESSARY. See V1.5 notes above
  33. */
  34.  
  35. //#include <../NewSoftSerial/NewSoftSerial.h>
  36.  
  37. #include <SoftwareSerial.h>
  38. #include "serLCD.h"
  39.  
  40. //      PUBLIC FUNCTIONS
  41.  
  42. // Contstructor
  43. // defaults to 16x2 display
  44. serLCD::serLCD(int pin) : SoftwareSerial(pin, pin){
  45.         pinMode(pin, OUTPUT);
  46.         begin(9600);
  47.         _numlines = LCD_2LINE;
  48.         _numchars = LCD_16CHAR;
  49.         _rowoffset = 0;
  50. }
  51.  
  52. /* Initialize.. not used trying to implement all display sizes
  53. void serLCD::init(int pin, int rows, int cols){
  54.         pinMode(pin, OUTPUT);
  55.         delay(4);
  56.         begin(9600);
  57.         if(cols == LCD_20CHAR){
  58.                 _numchars = LCD_20CHAR;
  59.                 specialCommand(LCD_SET20CHAR);
  60.         }else{ // default to 16 char display
  61.                 _numchars = LCD_16CHAR;
  62.                 specialCommand(LCD_SET16CHAR);
  63.         }      
  64.         if(rows == LCD_4LINE){
  65.                 _rowoffset = 1;
  66.                 _numlines = LCD_4LINE;
  67.                 specialCommand(LCD_SET4LINE);
  68.         }else{ // default to 2 line if input was invalid
  69.                 _rowoffset = 0;
  70.                 _numlines = LCD_2LINE;
  71.                 specialCommand(LCD_SET2LINE);
  72.         }
  73.         // clear the display
  74.         clear();
  75.         // set brightness to full
  76.         setBrightness(30);
  77. }
  78. */
  79.  
  80. // Set brightness value range 1-30 1=OFF 30=FULL
  81. void serLCD::setBrightness(int val){
  82.         if(val >= 1 && val <= 30){
  83.                 specialCommand(LCD_BACKLIGHT | (val - 1));
  84.         }
  85. }
  86.  
  87. // Clears screen and returns cursor to home position
  88. void serLCD::clear(){
  89.         command(LCD_CLEARDISPLAY);
  90. }
  91.  
  92. // Clears a single line by writing blank spaces then returning
  93. // cursor to beginning of line
  94. void serLCD::clearLine(int num){
  95.         if(num > 0 && num <= _numlines){
  96.                 setCursor(num, 1);
  97.                 print("                ");
  98.                 setCursor(num, 1);
  99.         }
  100. }
  101.  
  102. // Moves cursor to the beginning of selected line
  103. void serLCD::selectLine(int num){
  104.         if(num > 0 && num <= _numlines){
  105.                 setCursor(num, 1);
  106.         }
  107. }
  108.  
  109. // returns cursor to home position
  110. void serLCD::home(){
  111.         command(LCD_RETURNHOME);
  112. }
  113.  
  114. // Saves first 2 lines of txt to splash screen memory
  115. void serLCD::setSplash(){
  116.         specialCommand(LCD_SETSPLASHSCREEN);
  117. }
  118.  
  119. // Toggles splashscreen on and off
  120. void serLCD::toggleSplash(){
  121.         specialCommand(LCD_SPLASHTOGGLE);
  122. }
  123.  
  124. //  This is for text that flows Left to Right
  125. void serLCD::leftToRight(){
  126.         _displaymode |= LCD_ENTRYLEFT;
  127.         command(LCD_ENTRYMODESET | _displaymode);
  128. }
  129.  
  130. // This is for text that flows Right to Left
  131. void serLCD::rightToLeft() {
  132.         _displaymode &= ~LCD_ENTRYLEFT;
  133.         command(LCD_ENTRYMODESET | _displaymode);
  134. }
  135.  
  136. // Blinking cursor on/off
  137. void serLCD::blink(){
  138.         _displaycontrol |= LCD_BLINKON;
  139.         command(LCD_DISPLAYCONTROL | _displaycontrol);
  140. }
  141. void serLCD::noBlink(){
  142.         _displaycontrol &= ~LCD_BLINKON;
  143.         command(LCD_DISPLAYCONTROL | _displaycontrol);
  144. }
  145.  
  146. // Underline cursor on/off
  147. void serLCD::cursor(){
  148.         _displaycontrol |= LCD_CURSORON;
  149.         command(LCD_DISPLAYCONTROL | _displaycontrol);
  150. }
  151. void serLCD::noCursor(){
  152.         _displaycontrol &= ~LCD_CURSORON;
  153.         command(LCD_DISPLAYCONTROL | _displaycontrol);
  154. }
  155.  
  156. // Display on/off
  157. void serLCD::display(){
  158.         _displaycontrol |= LCD_DISPLAYON;
  159.         command(LCD_DISPLAYCONTROL | _displaycontrol);
  160. }
  161. void serLCD::noDisplay(){
  162.         _displaycontrol &= ~LCD_DISPLAYON;
  163.         command(LCD_DISPLAYCONTROL | _displaycontrol);
  164. }
  165.  
  166. // Set cursor to specific row and col values start at 1 not 0
  167. void serLCD::setCursor(int row, int col){
  168.         int row_offsets[2][4] = {
  169.                 { 0x00, 0x40, 0x10, 0x50 },
  170.                 { 0x00, 0x40, 0x14, 0x54 }
  171.         };
  172.         if((row > 0 && row < _numlines+1) && (col > 0 && col < _numchars+1)){
  173.            command(LCD_SETDDRAMADDR | ((col - 1) + row_offsets[_rowoffset][(row - 1)]));
  174.         }
  175. }
  176.  
  177. // Creates custom characters 8 char limit
  178. // Input values start with 1
  179. void serLCD::createChar(int location, uint8_t charmap[]){
  180.         location -= 1;
  181.         location &= 0x07;
  182.   for (int i=0; i<8; i++){
  183.     command(LCD_SETCGRAMADDR | (location << 3) | i);
  184.     write(charmap[i]);
  185.   }
  186. }
  187.  
  188. // Prints custom character
  189. // Input values start with 1
  190. void serLCD::printCustomChar(int num){
  191.         write((num - 1));
  192. }
  193.  
  194. // new in 1.6: sets the type of the LCD
  195. void serLCD::setType(int num){
  196. /*
  197.   3: 20 columns
  198.   4: 16 columns
  199.   5: 4 rows
  200.   6: 2 rows
  201. */     
  202.         if (num==3){
  203.                 _numchars = LCD_20CHAR;
  204.  
  205.         }
  206.         if(num == 4){
  207.                 _numchars = LCD_16CHAR;
  208.         }
  209.         if(num == 5){
  210.                 _numlines = LCD_4LINE;
  211.                 _rowoffset = 1;
  212.         }
  213.         if(num == 6){
  214.                 _numlines = LCD_4LINE;
  215.                 _rowoffset = 0;
  216.         }
  217.         specialCommand(num);
  218. }
  219.  
  220. // new in 1.6: scrolls text to left with one position
  221. void serLCD::scrollLeft(){
  222.   command(0x18);
  223. }
  224.  
  225. // new in 1.6: scrolls text to right with one position
  226. void serLCD::scrollRight(){
  227.         command(0x1C);
  228. }
  229.  
  230.  
  231. // PRIVATE FUNCTIONS
  232.  
  233. // Functions for sending the special command values
  234. void serLCD::command(uint8_t value){
  235.         write(0xFE);
  236.         write(value);
  237.         delay(5);
  238. }
  239. void serLCD::specialCommand(uint8_t value){
  240.         write(0x7C);
  241.         write(value);
  242.         delay(5);
  243. }

In order to have the keywords in color in the Arduino IDE add :

keywords.txt

# keywords for the serLCD v1.7 library
# created by Florentin SALOMEZ 18/06/2016

serLCD KEYWORD1

clear KEYWORD2
clearLine KEYWORD2
home KEYWORD2
setBrightness KEYWORD2

setSplash KEYWORD2
setType KEYWORD2
scrollLeft KEYWORD2
scrollRight KEYWORD2
toggleSplash KEYWORD2

blink KEYWORD2
noBlink KEYWORD2
cursor KEYWORD2
noCursor KEYWORD2
display KEYWORD2
noDisplay KEYWORD2

setCursor KEYWORD2
selectLine KEYWORD2

lefToRight KEYWORD2
rightToLeft KEYWORD2
autoscroll KEYWORD2
noAutoscroll KEYWORD2

createChar KEYWORD2
printCustomChar KEYWORD2

command KEYWORD2
specialCommand KEYWORD2

In order to have some info in the library manager in the Arduino IDE add :

library.properties

name=serLCD
version=1.7.0
author=Cody B. Null
maintainer=
sentence=Arduino driver for sparkfun serLCD v2.5
paragraph=Arduino driver for sparkfun serLCD v2.5
category=Display
url=http://playground.arduino.cc/Code/SerLCD
architectures=*

Share