5. Orangutan LCD

Reference

static void OrangutanLCD::clear()

void clear()

Clears the display and returns the cursor to the upper-left corner (0, 0).

static void OrangutanLCD::initPrintf()

void lcd_init_printf()

Initializes the display for use with the standard C function printf(). This is not available in the Arduino environment. See the avr-libc manual for more information on how to use printf() with an AVR, and please note that using printf() will consume a significant amount of your Orangutan’s program and data memory. This function is intended to work with the LCD that came with your Orangutan; if you are using a different LCD, you can use lcd_init_printf_with_dimensions() to initialize printf() for the width and height of your LCD. This function only needs to be called once in your program, prior to any printf() calls.

Example

#include <stdio.h>
void someFunction(int x)
{
  lcd_init_printf();
  // in C++: OrangutanLCD::initPrintf();
  printf("x=%5d", x);
}

static void OrangutanLCD::initPrintf(unsigned char lcd_width, unsigned char lcd_height)

void lcd_init_printf_with_dimensions(unsigned char lcd_width, unsigned char lcd_height)

Initializes the display for use with the standard C function printf() and lets you specify the width and height of your LCD using the lcd_width and lcd_height arguments. This is not available in the Arduino environment. See the avr-libc manual for more information on how to use printf() with an AVR, and please note that using printf() will consume a significant amount of your Orangutan’s program and data memory. If you are using the LCD that came with your Orangutan, you can use the argument-free lcd_init_printf(), which automatically initializes printf() for the width and height of your Orangutan’s (or 3pi’s) LCD. This version of the function is useful if you are using a different LCD or for some reason only want to use a portion of your LCD. This function only needs to be called oncce in your program, prior to any printf() calls.

Example

#include <stdio.h>
void someFunction(int x)
{
  // initialize printf() for a 20x4 character LCD
  lcd_init_printf_with_dimensions(20, 4);
  // in C++: OrangutanLCD::initPrintf(20, 4);
  printf("x=%5d", x);
}

static void OrangutanLCD::print(unsigned char character)

Prints a single ASCII character to the display at the current cursor position.

static void OrangutanLCD::print(char character)

void print_character(char character)

Prints a single ASCII character to the display at the current cursor position. This is the same as the unsigned char version above.

Example:

print_character('A');
// in C++: OrangutanLCD::print('A');

static void OrangutanLCD::print(const char *str)

void print(const char *str)

Prints a zero-terminated string of ASCII characters to the display starting at the current cursor position. The string will not wrap or otherwise span lines.

Example:

print("Hello!");
// in C++: OrangutanLCD::print("Hello!");

static void OrangutanLCD::printFromProgramSpace(const char *str)

void print_from_program_space(const char *str)

Prints a string stored in program memory. This can help save a few bytes of RAM for each message that your program prints. Even if you use the normal print() function, the strings will be initially stored in program space anyway, so it should never hurt you to use this function.

Example:

#include <avr/pgmspace.h>
const char hello[] PROGMEM = "Hello ";

void someFunction()
{
  print_from_program_space(hello);
  // in C++: OrangutanLCD::printFromProgramSpace(hello);
  print_from_program_space(PSTR("there!"));
  // in C++: OrangutanLCD::printFromProgramSpace(PSTR("there!"));
}

static void OrangutanLCD::print(int value)

Prints the specified signed integer (2-byte) value to the display at the current cursor position. It will not wrap or otherwise span lines. There is no C version of this method, but print_long(value) should be sufficient.

Example:

OrangutanLCD::print(-25);
// in C: print_long(-25);

static void OrangutanLCD::print(long value)

void print_long(long value)

Prints the specified signed long (4-byte) value to the display at the current cursor position. It will not wrap or otherwise span lines.

static void OrangutanLCD::print(unsigned int value)

Prints the specified unsigned integer (2-byte) value to the display at the current cursor position. The value will not wrap or otherwise span lines and will always be positive.

static void OrangutanLCD::print(unsigned long value)

void print_unsigned_long(unsigned long value)

Prints the specified unsigned long (4-byte) value to the display at the current cursor position. The value will not wrap or otherwise span lines and will always be positive.

static void OrangutanLCD::printHex(unsigned int value)

void print_hex(unsigned int value)

Prints the specified two-byte value in hex to the display at the current cursor position. The value will not wrap or otherwise span lines.

static void OrangutanLCD::printHex(unsigned char value)

void print_hex_byte(unsigned char value)

Prints the specified byte value in hex to the display at the current cursor position. The value will not wrap or otherwise span lines.

static void OrangutanLCD::printBinary(unsigned char value)

void print_binary(unsigned char value)

Prints the specified byte in binary to the display at the current cursor position. The value will not wrap or otherwise span lines.

static void OrangutanLCD::gotoXY(unsigned char x, unsigned char y)

void lcd_goto_xy(int col, int row)

Moves the cursor to the specified (x, y) location on the LCD. The top line is y = 0 and the leftmost character column is x = 0, so you can return to the upper-left home position by calling lcd.gotoXY(0, 0), and you can go to the start of the second LCD line by calling lcd.gotoXY(0, 1);

static void OrangutanLCD::showCursor(unsigned char cursorType)

void lcd_show_cursor(unsigned char cursorType)

Displays the cursor as either a blinking or solid block. This library defines literals CURSOR_BLINKING and CURSOR_SOLID for use as an argument to this method.

static void OrangutanLCD::hideCursor()

void lcd_hide_cursor()

Hides the cursor.

static void OrangutanLCD::moveCursor(unsigned char direction, unsigned char distance)

void lcd_move_cursor(unsigned char direction, unsigned char num)

Moves the cursor left or right by distance spaces. This library defines literals LCD_LEFT and LCD_RIGHT for use as a direction argument to this method.

static void OrangutanLCD::scroll(unsigned char direction, unsigned char distance, unsigned int delay_time)

void lcd_scroll(unsigned char direction, unsigned char num, unsigned int delay_time)

Shifts the display left or right by distance spaces, delaying for delay_time milliseconds between each shift. This library defines literals LCD_LEFT and LCD_RIGHT for use as a direction argument to this method. Execution does not return from this method until the shift is complete.

static void OrangutanLCD::loadCustomCharacter(const char *picture_ptr, unsigned char number)

void lcd_load_custom_character(const char *picture_ptr, unsigned char number)

Loads a custom character drawing into the memory of the LCD. The parameter ‘number’ is a character value between 0 and 7, which represents the character that will be customized. That is, lcd.print((char)number) or print_character(number) will display this drawing in the future.

Note: the clear() method must be called before these characters are used.

The pointer picture_ptr must be a pointer to an 8 byte array in program space containing the picture data. Bit 0 of byte 0 is the upper-right pixel of the 5×8 character, and bit 4 of byte 7 is the lower-left pixel. The example below demonstrates how to construct this kind of array.

Example:

#include <avr/pgmspace.h>
// the PROGMEM macro comes from the pgmspace.h header file
// and causes the smile pointer to point to program memory instead
// of RAM
const char smile[] PROGMEM = {
  0b00000,
  0b01010,
  0b01010,
  0b01010,
  0b00000,
  0b10001,
  0b01110,
  0b00000
};

void setup()
{
  // set character 3 to a smiley face
  lcd_load_custom_character(smile, 3);
  // in C++: OrangutanLCD::loadCustomCharacter(smile, 3);

  // clear the lcd (this must be done before we can use the above character)
  clear();
  // in C++: OrangutanLCD::clear();

  // display the character
  print_character(3);
  // in C++: OrangutanLCD::print((char)3);
}