3.d. Orangutan LCD Control Functions

Overview

This section of the library gives you the ability to control the 8×2 character LCD on the 3pi Robot, Orangutan SV, Orangutan SVP, and Orangutan LV-168. It implements the standard 4-bit HD44780 protocol, and it uses the busy-wait-flag feature to avoid the unnecessarily long delays present in other 4-bit LCD control libraries. This comprehensive library is meant to offer as much LCD control as possible, so it most likely gives you more methods than you need. Make sure to use the linker option -Wl,-gc-sections when compiling your code, so that these extra functions will not be included in your hex file. See Section 4 for more information.

This library is designed to gracefully handle alternate use of the four LCD data lines. It will change their data direction registers and output states only when needed for an LCD command, after which it will immediately restore the registers to their previous states. This allows the LCD data lines to additionally function as pushbutton inputs and an LED driver.

C++ users: See Section 5.c of Programming Orangutans and the 3pi Robot from the Arduino Environment for examples of this class in the Arduino environment, which is almost identical to C++.

Complete documentation of this library’s methods can be found in Section 5 of the Pololu AVR Library Command Reference.

Usage Examples

This library comes with two examples in libpololu-avr\examples.

1. lcd1

Demonstrates shifting the contents of the display by moving the word “Hello” around the two lines of the LCD.

#include <pololu/orangutan.h>

/*
 * lcd1: for the Orangutan controllers and 3pi robot
 *
 * This example uses the OrangutanLCD library to display things on the LCD.
 *
 * http://www.pololu.com/docs/0J20
 * http://www.pololu.com
 * http://forum.pololu.com
 */

int main()
{
  while(1)
  {
    print("Hello");           // display "Hello" at (0, 0), a.k.a. upper-left
    delay_ms(200);
    lcd_scroll(LCD_RIGHT, 3, 200);// shift the display right every 200ms three times
    clear();                  // clear the LCD
    lcd_goto_xy(3, 1);             // go to the fourth character of the second LCD line
    print("Hello");           // display "Hello" at (3, 1), a.k.a. lower-right
    delay_ms(200);
    lcd_scroll(LCD_LEFT, 3, 200); // shift the display left every 200ms three times
    clear();                  // clear the LCD
  }

  return 0;
}

1. lcd2

Demonstrates creating and displaying custom characters on the LCD. The following picture shows an example of custom characters, using them to display a bar graph of sensor readings and a smiley face:

#include <pololu/orangutan.h>

// get random functions
#include <stdlib.h>

/*
 * lcd2: for the Orangutan controllers and 3pi robot
 *
 * This example uses the OrangutanLCD functions to display custom 
 * characters on the LCD.  Simply push a any user pushbutton to
 * display a new, randomly chosen, custom mood character.
 *
 * http://www.pololu.com/docs/0J20
 * http://www.pololu.com
 * http://forum.pololu.com
 */

// define some custom "mood" characters
#include <avr/pgmspace.h>  // this lets us refer to data in program space (i.e. flash)
const char happy[] PROGMEM = {
  0b00000,                 // the five bits that make up the top row of the 5x8 character
  0b01010,
  0b01010,
  0b01010,
  0b00000,
  0b10001,
  0b01110,
  0b00000
};

const char sad[] PROGMEM = {
  0b00000, 
  0b01010,
  0b01010,
  0b01010,
  0b00000,
  0b01110,
  0b10001,
  0b00000
};

const char indifferent[] PROGMEM = {
  0b00000, 
  0b01010,
  0b01010,
  0b01010,
  0b00000,
  0b00000,
  0b01110,
  0b00000
};

const char surprised[] PROGMEM = {
  0b00000, 
  0b01010,
  0b01010,
  0b00000,
  0b01110,
  0b10001,
  0b10001,
  0b01110
};

const char mocking[] PROGMEM = {
  0b00000, 
  0b01010,
  0b01010,
  0b01010,
  0b00000,
  0b11111,
  0b00101,
  0b00010
};

char prevMood = 5;


int main()
{
  lcd_load_custom_character(happy, 0);
  lcd_load_custom_character(sad, 1);
  lcd_load_custom_character(indifferent, 2);
  lcd_load_custom_character(surprised, 3);
  lcd_load_custom_character(mocking, 4);
  clear();                  // this must be called before we can use the custom characters
  print("mood: ?");

  // initialize the random number generator based on how long
  // they hold the button the first time
  wait_for_button_press(ALL_BUTTONS);
  long seed = 0;
  while(button_is_pressed(ALL_BUTTONS))
    seed++;
  srandom(seed);

  while(1)
  {
  
    lcd_goto_xy(6, 0);             // move cursor to the correct position
  
    char mood;
    do
    {
      mood = random()%5;
    } while (mood == prevMood);   // ensure we get a new mood that differs from the previous
    prevMood = mood;
  
    print_character(mood);   // print a random mood character
    wait_for_button(ALL_BUTTONS);   // wait for any button to be pressed
  }

  return 0;
}