/ 
Device-Arduino-LCD-1.01
River stage zero No dependents
/ Device::Arduino::LCD

NAME

Device::Arduino::LCD - Perl Interface to the PerLCD Arduino Sketch.

SYNOPSIS

use strict;
use Device::Arduino::LCD;

my $lcd = Device::Arduino::LCD->new;
$lcd->clear;
$lcd->first_line("Hello World");

See examples/demo.pl for a more comprehensive example.

DESCRIPTION

The Arduino is an open-source physical computing platform. Among the many things one might want to do with such a device is connect an LCD to it and print stuff (at least that's what I wanted to do with it).

There are a couple of excellent low-level libraries that can be linked into an Arduino sketch to provide this functionality. I've chosen the LCD4Bit library to link against. The PerLCD sketch provides a few higher level functions as well as a serial listener.

This Perl library provides a very high level interface for formatting and sending messages to the sketch's listener. Once the device is wired up to an LCD (a fairly trivial task), the USB serial drivers installed, and the sketch compiled and uploaded, getting text on the screen should be no more difficult than the example above: Zero knowledge of LCDs required.

The sketch provided can obviously be used with a client library written in any language, the choice of Perl was (almost) arbitrary.

VARIABLES

Package variables representing (supposedly) sensible default. May be changed as necessary before new() is called.

  • $Device::Arduino::LCD::Device -- default serial device to connect with. (/dev/tty.usbserial)

  • $Device::Arduino::LCD::Baud -- default baud rate (9600). Changing this requires recompiling and reloading the perlcd.cc code.

  • $Device::Arduino::LCD::READ_TIMEOUT -- default time in seconds for receive() to wait when called (10).

METHODS

new(class, [device, [baud]])

Returns a Device::Arduino::LCD object or dies if unable to open the serial device.

first_line(Device::Arduino::LCD, text)

Print text on the first line of the LCD. Characters exceeding the length of the display are truncated.

second_line(Device::Arduino::LCD, text)

As above, on the second line.

clear(Device::Arduino::LCD, [pre-delay, [post-delay]])

Clears the LCD. Waits pre-delay seconds before sending the command and post-delay seconds before returning.

scroll_left(Device::Arduino::LCD, [delay])

Scrolls both lines of the LCD to the left, at a rate of delay ms.

scroll_up(Device::Arduino::LCD, text, [pre-delay, [internal-delay, [post_delay]]]);

Scrolls the text up (i.e., line 2 becomes line 1; line 2 contains text). Waits pre-delay before sending the command; scrolls at a rate of internal-delay seconds; waits post_delay seconds before returning. Text is an array ref.

place_string(Device::Arduino::LCD, text, row, column)

Places character one of text at the row and column specified. Rows (on a two line display) range from 1 to 2; columns, however, are zero indexed. (Sorry about that.)

gauge_pct(Device::Arduino::LCD, gauge-number, x%)

Sends x% of 5V to the port specified by gauge-number. Gauges are numbered 1, 2, and 3 corresponding to PWM pins 3, 5, and 6 on the arduino. This has bugger all to do with LCDs, but since the pins are available it seems to make sense to provide a way of addressing them.

command(Device::Arduino::LCD, LCD-command)

Send (numeric) LCD-command directly to the LCD. Useful for sending the sorts of commands listed here: http://tinyurl.com/234d8z

Send the character directly to the LCD. The method will handle converting the character to an integer. With command(0 and print_char() one can achieve pretty much anything but initialization of the display.

make_char(Device::Arduino::LCD, ascii-num, data)

Installs data (an eight element array or array ref) as ascii character 0 - 7. (NB: the LCD allows eight characters, ASCII 0-7 to be defined by the user; that's what make_char and write_ascii as well as the bargraph functions are all about.)

write_ascii(Device::Arduino::LCD, ascii-num, row, col)

Prints the ascii character (0-7) at row, col. This is particularly useful for printing the custom characters created with make_char().

init_bargraph(Device::Arduino::LCD);

Defines eight custom characters (overwriting whatever's been defined before) as a series of bars for use in graphing.

graph(Device::Arduino::LCD, value, row, column);

With values ranging from 0 - 8 prints that many solid horizontal bars (starting at the bottom) in the position indicated. So

$lcd->graph(2, 1, 0); $lcd->graph(5, 1, 1);

prints this in the first and second blocks of the top row:

. . . . .  . . . . .
. . . . .  . . . . .
. . . . .  . . . . .
. . . . .  x x x x x
. . . . .  x x x x x
. . . . .  x x x x x
x x x x x  x x x x x
x x x x x  x x x x x

tallgraph(Device::Arduino::LCD, value, column);

Like graph() above but using a 16 x 5 font; the value can range from 0 to 16.

convert_to_char(Device::Arduino::LCD, ascii-num, @data)

Convert an array of arrayrefs of text to custom character ascii-num. A call to convert_to_char might look like.

my $ret = $lcd->convert_to_char(0,
				[ qw[ . x . x . ] ],
				[ qw[ x . x . x ] ],
				[ qw[ . x . x . ] ],
				[ qw[ x . x . x ] ],
				[ qw[ . x . x . ] ],
				[ qw[ x . x . x ] ],
				[ qw[ . x . x . ] ],
				[ qw[ x . x . x ] ]);

Any position indicated by an x (or X) will be lit, everything else will be off. The choice of period here is arbitrary. To print this character one could say $lcd->write_ascii(0, 1, 0).

PREREQUISITES

  • Device::SerialPort from CPAN (http://tinyurl.com/2tee6b)

  • GNU avr-gcc, uisp, and avrdude. Note: it's probably possible to use the Arduino development environment instead. I much prefer typing "make" and "make upload" (and editing in emacs).

  • An Arduino NG board and an LCD. In the US www.sparkfun.com distributes the board at a reasonable price. I also bought an LCD from them (the Xiamen GDM1602K).

  • Appropriate USB serial drivers. For OS X these are included with the Arduino development environment package.

  • The Arduino PerLCD sketch compiled and loaded onto the board. Edit arduino/Makefile (there are instructions at the top) and then run 'make'. If that goes well, frob the arduino reset switch and immediately execute 'make upload'.

SEE ALSO

The Arduino homepage: http://www.arduion.cc, particularly Heather Dewey-Hagborg's LCD tutorial (http://www.arduino.cc/en/Tutorial/LCDLibrary) and neillzero's LCD4BitLibrary page (http://www.arduino.cc/playground/Code/LCD4BitLibrary).

The Hitachi HD44780 Datasheet: http://www.electronic-engineering.ch/microchip/datasheets/lcd/hd44780.pdf

Dincer Aydin's LCD page on geocities was also a good resource, particularly the Custom-Character Calculator. http://www.geocities.com/dinceraydin/lcd/intro.htm

Erik Nordin's HD44780-Based LCD FAQ: http://www.repairfaq.org/filipg/LINK/F_LCD_HD44780.html

BUGS

Rows are are indexed from 0; columns from 1: The LCD4Bit library is shining through, it was kept this way for consistency but it's probably not very abstract or intuitive.

AUTHOR

Kevin Montuori, <montuori@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2007 by Kevin Montuori & mconsultancy

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of Perl 5 you may have available.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 283:

You forgot a '=back' before '=head1'