I2C Library for Hobby Components SmartLCD (HCMODU0122)

Useful guides, libraries, and example sketches to support our Arduino based products.
admin
Site Admin
Posts: 865
Joined: Sun Aug 05, 2012 4:02 pm

I2C Library for Hobby Components SmartLCD (HCMODU0122)

Post by admin » Thu Jul 13, 2017 10:32 am

Image




Arduino I2C library for the Hobby Components Smart LCD.
Products currently supported by this library:

Hobby Components 1602 Smart LCD (HCMODU0122) available from hobbycomponents.com

Optional:

Hobby Components SmartLCD Keypad kit (HCKITS0058)


Installing the library

The library is available via several sources:

1) The latest version of the library can be found under the download section at the bottom of this post. Note that you must be logged in to download it.

2) Via our github page here: https://github.com/HobbyComponents/SmartLCD

3) For PlatformIO users you can add the library to your project by going to the library section of PlatformIO and searching either 'hobbycomponents' to view a list of our libraries or 'SmartLCD' to just list the SmartLCD.

For Arduino IDE users the library can be installed by downloading the library as a zip file via methods 1 or 2 above then in the Arduino IDE click on the Sketch menu and navigate to Sketch->Include Library->Add .Zip Library.

In the window that opens up navigate to wherever you downloaded the .Zip file and click open. The IDE should then automatically install the library.

Alternatively you can install the library manually by unzipping it to your Arduino library folder which can normally be found in one of the following places...


On Windows:
My Documents\Arduino\libraries\

On Mac:
Documents/Arduino/libraries/

Linux:
Usually found within the users home area under /Arduino/libraries/




Using the SMARTLCDI2C library


To use the library just include the SMARTLCDI2C .h header file and then create an instance of the library. E.g:

Code: Select all

#include <SMARTLCDI2C.h>
SmartLCD SmartLCD(I2C_Add);

Where I2C_Add is the I2C address of the SmartLCD (default is 0x27).


To initialise the library add the following line to the setup() section of your sketch:

Code: Select all

SmartLCD.init();



The following functions are available with this library:

void PrintChar(char Character);

Prints a single ASCII character to the screen starting at the current cursor position where:
Character is the ASCII encoded character to print

Example:

Code: Select all

SmartLCD.PrintChar('A');



void Print(char *String);

Prints a string of ASCII text to the screen starting at the current cursor position where:
String is an ASCII string with null terminator containing the text to print

Example:

Code: Select all

SmartLCD.Print("Hello World!");



void Print(const char *String, int16_t row, int16_t col);

Prints a string of ASCII text to the screen where:
String is an ASCII string with null terminator containing the text to print
Row is the text row number - valid values are -32767 to 32767
Col is the text column number - valid values are -32767 to 32767

Example:

Code: Select all

SmartLCD.Print("Hello!", 0, 5);



void Print(int Value);

Prints a signed integer number to the screen starting at the current cursor position where:
Value is the signed integer to print

Example:

Code: Select all

SmartLCD.Print(-1234);



void Print(float Value, byte DP);

Prints a floating point number to the screen starting at the current cursor position where:
Value is the floating point number to print
DP is the number of decimal places to print to. Omitting DP will print the number with no decimal places

Example:

Code: Select all

SmartLCD.Print(-1234.567, 2);



void ScrollText(const char *String, uint8_t row, int8_t startCol, int8_t endCol, uint16_t scrollDelay);

Scrolls some text where:
String is an ASCII string with null terminator containing the text to print
Row is the text row number - valid values are -32767 to 32767
startCol is the start column to scroll from - valid values are -32767 to 32767
endCol is the end column to scroll to - valid values are -32767 to 32767
scrollDelay is the delay in ms between each step

Notes:
If startCol < endCol text will scroll left to right, if startCol > endCol text will scroll right to left
This library function is blocking. Further code will not be executed until the scrolling has completed.


Example:

Code: Select all

SmartLCD.ScrollText("Hello!", 0, -6, 20, 100);



void Clear(void);

Clears the screen of any printed text and positions the cursor to row 0, column 0 (top left hand corner)

Example:

Code: Select all

SmartLCD.Clear();



void CurPos(byte Row, byte Col);

Positions the cursor on the screen where:
Row is the text row number - valid values are 0 to 4 (only 0 to 1 visible on 1602 version)

Col is the text column number - valid values are 0 to 79 (only 0 to 15 visible on 1602 version)

Example:

Code: Select all

SmartLCD.CurPos(0,0);



void DispState(byte State);

Turns the LCD on or off where:
State is required state to set the screen to. Valid values are
OFF (screen is turned off)
ON (screen is turned on)

Note that any text on the screen and the backlight state are not affected.

Example:

Code: Select all

SmartLCD.DispState(ON);



void DispCursor(byte State);

Turns the cursor on or off where:
State is required state to set the cursor to. Valid values are
OFF (cursor is turned off)
ON (cursor is turned on)

Example:

Code: Select all

SmartLCD.DispCursor(ON);



void CursorBlink(byte State);

Turns cursor blinking on or off where:
State is required state to set the cursor blink to. Valid values are
OFF (cursor blinking is turned off)
ON (cursor blinking is turned on)

Example:

Code: Select all

SmartLCD.CursorBlink(ON);





void Backlight(uint8_t Level);

Sets the brightness level for the back light where:
Level is the required brightness in 10% increments. Valid values are
0 (off) to 10 (100%)

Example:

Code: Select all

SmartLCD.Backlight(10);





void PrintCustChar(byte CharIndex);

Prints one of the 8 custom characters to the screen where:
CharIndex specifies which custom character (0 to 7) to print.

Example:

Code: Select all

SmartLCD.PrintCustChar(0);





void DefCustChar(uint8_t CharIndex, uint8_t *Data);

Defines one of the 8 custom characters by writing a 5x8 pixel bitmap to it where:
CharIndex specifies which custom character (0 to 7) to write the bitmap to.

Data is an 8 byte array containing the bitmap data.

See the Smart LCD manual for more information on bitmap format.

Note after issuing this function you must reposition the cursor before printing any text using the SmartLCD.CurPos(Row, Col) function.

Example:

Code: Select all

byte Bitmap[] = {0x0E,0x1F,0x11,0x11,0x11,0x11,0x11,0x1F};
SmartLCD.DefCustChar(0, Bitmap);
SmartLCD.PrintCustChar(0);





void CursorDir(uint8_t Dir);

Sets which direction the cursor will move when printing text where:
Dir is the direction the cursor will move. Valid values are
LTOR - cursor will move from left to right
RTOL - cursor will move from right to left

Example:

Code: Select all

SmartLCD.CursorDir(LTOR);





void I2CInit(void);

Initialises the LCD setting it to its default power on state. If the backlight was off it will also be set to the default on state.

Example:

Code: Select all

SmartLCD.I2CInit();





void ClearButton(void);

Clears the last button pressed state by reseting it to 0

Example:

Code: Select all

SmartLCD.ClearButton();



void PlayNote(byte Note, byte Time);

Plays one of 12 musical notes for a specified duration where:
Note is which of the 12 notes to play (0 to 11). Predefined values for note:
NOTE_C 0
NOTE_CS 1
NOTE_D 2
NOTE_DS 3
NOTE_E 4
NOTE_F 5
NOTE_FS 6
NOTE_G 7
NOTE_GS 8
NOTE_A 9
NOTE_A# 10
NOTE_B 11

Time is the duration of the note in 10ms increments (1 = 10ms to 255 = 2.55s)

Note: Requires the optional keypad and speaker accessory to be connected to the Smart LCD.

This command is none blocking - i.e. it will not wait for the note to finish playing.

Example:

Code: Select all

SmartLCD.PlayNote(NOTE_C, 100);



void Address(byte Address);

Changes the I2C slave address for the Smart LCD where:
Address is the new I2C address. Valid values are
0x08 to 0x77 (default =0x27)

Note: Once this command is issued the display will immediately respond to commands sent to the new slave address and will no longer respond to the original address. This command will also update the current I2C address stored within the library so you can continue to issue commands without needing to re-initialise the library.

Example:

Code: Select all

SmartLCD.Address(0x27);



void Contrast(byte Level);

Sets the contrast level of the screen where:
Level is the required contrast level. Valid values are
0 (maximum contrast) to 255 (minimum contrast).

Example:

Code: Select all

SmartLCD.Contrast(0);



void Version(void);

Shows the version of firmware flashed into the Smart LCD by displaying it to the LCD.

Example:

Code: Select all

SmartLCD.Version();



void ClearError(void);

Clears the error flag in the status register.

Example:

Code: Select all

SmartLCD.ClearError();



void WaitBar(byte Row, byte Col, byte Length, byte Percent);

Draws a horizontal wait bar to the screen where:
Row is the text row number to position the wait bar.

Col is the text col number to position the left side of the wait bar.

Length is the length in characters of the wait bar

Percent specifies what part of the wait bar to fill in percent (0 to 100)

Example:

Code: Select all

SmartLCD.WaitBar(0, 0, 16, 50)



boolean Busy(void);

Returns the busy status flag where
false = SmartLCD is not busy and can accept new commands
true = SmartLCD is busy and cannot accept new commands

Note that all the functions within this library use the busy command and will not finish executing until the SmartLCD has finished processing the current command. Therefore you do not need to use this function to check if it is ok to send another command when using the functions within this library.

Example:

Code: Select all

while(SmartLCD.Busy());



boolean Error(void);

Returns the command error flag where
false = Last command executed without error
true = There was an error with executing or receiving the last command.

Note that if the error flag is set it will not automatically clear. Therefore you must clear the flag using the SmartLCD.ClearError() function.

Example:

Code: Select all

if(SmartLCD.Error())
    Serial.print("Error!");
else
    Serial.print("OK");



boolean ButtonState(void);

Returns the keypad button pressed status where
false = No buttons are currently pressed on the external keypad.
true = A button on the external keypad is currently being pressed.

Note: Requires the optional keypad and speaker accessory to be connected to the Smart LCD.

Example:

Code: Select all

if(SmartLCD.ButtonState())
    Serial.print("Button pressed");



byte Button(void);

Returns the last button number to be pressed on the external keypad where
KEYPAD_NONE = No buttons have been pressed
KEYPAD_BACK = The back button has been pressed
KEYPAD_SELECT = The select button has been pressed
KEYPAD_DOWN = The down button has been pressed
KEYPAD_RIGHT = The right button has been pressed
KEYPAD_UP = The up button has been pressed
KEYPAD_LEFT = The left button has been pressed

After reading the button state the current status can been cleared by issuing the SmartLCD.ClearButton() function.

Note: Requires the optional keypad and speaker accessory to be connected to the Smart LCD

Example:

Code: Select all

if(SmartLCD.ButtonState() == true && SmartLCD.Button() != KEYPAD_NONE)
  {
    switch(SmartLCD.Button())   
    {
      case(KEYPAD_LEFT):
        SmartLCD.Print(" LEFT "); 
        break;

      case(KEYPAD_UP):
        SmartLCD.Print("  UP  "); 
        break;

      case(KEYPAD_RIGHT): 
        SmartLCD.Print("RIGHT "); 
        break;
        
      case(KEYPAD_BACK):
        SmartLCD.Print(" BACK ");
        break;

       case(KEYPAD_DOWN):
        SmartLCD.Print(" DOWN "); 
        break;
        
      case(KEYPAD_SELECT):
        SmartLCD.Print("SELECT"); 
        break;
    }

    SmartLCD.ClearButton(); 
  }



byte ReadADC(void);

Returns an 8 bit byte representing the state of the 8 bit ADC connected to the 'S' pin of the keypad header where:
0 = 0V (GND) and 255 = 5V (VCC)

Note this pin is used by the SmartLCD keypad for button sensing but if the SmartLCD keypad is not required this pin can be used as an 8 bit ADC input (5V max).

Example:

Code: Select all

byte Value = SmartLCD.ReadADC()
    Serial.println(Value);



byte Status(void);

Returns an 8 bit byte containing the current state from the I2C status register.

See SmartLCD manual for an explanation of the I2C status register

Example:

Code: Select all

byte Status = SmartLCD.Status()
    Serial.println(Status, BIN);




Image
  1. #include "SmartLCDI2C.h"      //Include the SmartLCD I2C Library
  2.  
  3. #define I2C_ADD 0x27          //I2C address of the Smart LCD
  4.  
  5. SmartLCD SmartLCD(I2C_ADD);   //Create an instance of the library
  6.  
  7.  
  8.  
  9. void setup()
  10. {
  11.   SmartLCD.init();            //Initiliases the library
  12. }
  13.  
  14.  
  15.  
  16. void loop()                
  17. {
  18.   SmartLCD.Clear();           //Clear the screen
  19.  
  20.   SmartLCD.CurPos(0, 5);      //Set the cursor to row 0 column 5
  21.   SmartLCD.Print("Hello");    //Print some text
  22.  
  23.   SmartLCD.CurPos(1, 4);      //Set the cursor to row 1 column 4
  24.   SmartLCD.Print("World !");  //Print some text
  25.  
  26.   while(1);                   //Do nothing
  27. }


Image

Latest version (0.4):
SmartLCD_V0_4.zip

Old version (0.3):
SmartLCD_V0_3.zip

Old version (0.2):
SmartLCD_V0_2.zip


Old 0.1 version:
SmartLCDI2C.zip

Diagrams, libraries, and example code are provided as an additional free service by Hobby Components and are not sold as part of this product. We do no provide any guarantees or warranties as to their accuracy or fitness for purpose.

Descriptions and diagrams on this page are copyright Hobby Components Ltd and may not be reproduced without permission.
You do not have the required permissions to view the files attached to this post.

malbro
Posts: 1
Joined: Thu May 24, 2018 6:16 pm

Re: I2C Library for Hobby Components SmartLCD (HCMODU0122)

Post by malbro » Wed May 30, 2018 6:07 pm

Hi

Trying to download the Smart LCD library but Avast is preventing access to the url /downloads/file.php indicating this file is a virus, can you confirm there is no problem before I disable Avast to allow the download?

andrew
Site Admin
Posts: 1374
Joined: Sun Aug 05, 2012 4:15 pm

Re: I2C Library for Hobby Components SmartLCD (HCMODU0122)

Post by andrew » Wed May 30, 2018 7:36 pm

The file is just a zip containing some none executable source (text) files so there shouldn't be anything for a virus to infect. I don't know why your antivirus program would be having an issue with it but I've just tried downloading the file myself and unzipped it and everything looks fine (using windows defender).
Comments made by this poster do not necessarily reflect the views of Hobby Components Ltd.

Gazz292
Posts: 8
Joined: Wed Jan 06, 2021 8:45 pm

Re: I2C Library for Hobby Components SmartLCD (HCMODU0122)

Post by Gazz292 » Fri Jan 29, 2021 8:05 pm

is it possible to use this with displays other than 16x2 and 20x4?

andrew
Site Admin
Posts: 1374
Joined: Sun Aug 05, 2012 4:15 pm

Re: I2C Library for Hobby Components SmartLCD (HCMODU0122)

Post by andrew » Sat Jan 30, 2021 8:58 am

is it possible to use this with displays other than 16x2 and 20x4?
Not sure if you're referring to the module or the library itself but the module can only be used with Hitachi (or Hitachi compatible) 16x2 and 20x4 character displays and the library can only be used with the SmartLCD module.
Comments made by this poster do not necessarily reflect the views of Hobby Components Ltd.

Gazz292
Posts: 8
Joined: Wed Jan 06, 2021 8:45 pm

Re: I2C Library for Hobby Components SmartLCD (HCMODU0122)

Post by Gazz292 » Tue Feb 02, 2021 11:59 pm

ahh gotya,
i was using the module with a 24 x 2 lcd.

RMurphy195
Posts: 8
Joined: Fri Oct 21, 2022 3:16 pm

Re: I2C Library for Hobby Components SmartLCD (HCMODU0122) Scrolling?

Post by RMurphy195 » Mon Jan 02, 2023 9:50 pm

Are there any plans to include scrolling commands to this library?

andrew
Site Admin
Posts: 1374
Joined: Sun Aug 05, 2012 4:15 pm

Re: I2C Library for Hobby Components SmartLCD (HCMODU0122)

Post by andrew » Wed Jan 04, 2023 9:19 am

Are there any plans to include scrolling commands to this library?

I've just added V0.4 of the library to the first post. This includes 2 new functions:


Print(const char *String, int16_t row, int16_t col) which allows for printing text to the display with a specified row and column. It also allows for printing of text outside, or partially outside the display area.


ScrollText(const char *String, uint8_t row, int8_t startCol, int8_t endCol, uint16_t scrollDelay) Which allows scrolling of text by specifying a start and end column. If startCol < endCol text will scroll left to right, if startCol > endCol text will scroll right to left.

For example to scroll some text on row 0 from column -10 to column 20 at 1 step every 100ms you can do this:


SmartLCD.ScrollText("Hello!", 0, -10, 20, 100);
Comments made by this poster do not necessarily reflect the views of Hobby Components Ltd.

RMurphy195
Posts: 8
Joined: Fri Oct 21, 2022 3:16 pm

Re: I2C Library for Hobby Components SmartLCD (HCMODU0122)

Post by RMurphy195 » Wed Jan 04, 2023 11:29 am

Thanks Andrew, these work rather well

andnum
Posts: 1
Joined: Tue Feb 07, 2023 1:07 pm

Re: I2C Library for Hobby Components SmartLCD (HCMODU0122)

Post by andnum » Fri Feb 10, 2023 10:03 am

Hi, is it possible to write to more displays in one code? I have two displays and changed the address on one of them, but I can't figure out how to "call" each of them inside the code.

Post Reply

Return to “Arduino”