NAME

	RPi::I2C::LCD - Interface vi I2C to the LCD1602 multi-line LCD display module

SYNOPSIS

	use RPi::I2C::LCD

	# all option values have defaults
	my $device = RPi::I2C::LCD->new(
		'devaddr'	=> <I2C address>,
		'busno'		=> <RPi bus number for I2C interface: 0 or 1>,
		'width'		=> <display width character count>,
		'rows'		=> <number of lines in display>,
		'backlight'	=> <backlight on=1, backlight off=0>,
		'defwait'	=> <inter-command delay in seconds>,
		'justify'	=> <justification for all lines, right, left, or center>,
		'version'	=> <module version>
		);

	$device->writeByte($byte)

	$device->sendByte($data,$mode)

	$device->prntStr($message,$lineno)
	
	$device->display('OFF')
	$device->display('ON')
	$device->display('CLEAR')

	return $device->lookup(<option>)

DESCRIPTION

	Interface to write to a LCD1602 multi-line display with an I2C adapter
	in front of it.

YOU SHOULD KNOW

	RPi::I2C is prerequisite and its documentation specifies requirements
	for enabling the I2C bus and determining the bus address to use.

	There is a Perl module for the LCD1602 display in I2C::LCD, but without
	the I2C adapter, the display requires 16 connections to the Raspberry Pi.
	With the I2C adapter, only 4 connections are required.  The LCD with the
	adapter soldered to it is available as a unit.

ACKNOWLEDGEMENTS

	Adapted from a Perl script posted by anita2R
	on PerlMonks May 24, 2016 at 16:28 UTC

METHODS

	new([options])
		
		Instantiates an object representing the attached display.

		Parameters

			Every option has a default value, and the defaults may be sufficient 
			for most applications.

			my $device = RPi::I2C::LCD->new(
				'devaddr'	=> <I2C address>,
					default 0x27
				'busno'		=> <RPi bus number for I2C interface: 0 or 1>,
					default 1, for /dev/i2c-1
				'width'		=> <display width character count>,
					default 16
				'rows'		=> <number of lines in display>,
					default 2, there are both 2 and 4-line display modules
				'backlight'	=> <backlight state>,
					default 1, ON=1, OFF=0
				'defwait'	=> <inter-command delay in seconds>,
					default 0.0001 seconds
				'justify'	=> <justification for all lines, 'right', 'left', or 'center'>,
					default 'center'
				'version'	=> <module version>
				);

	writeByte($byte)

		write a single byte to the display, used internally

	sendByte($data,$mode)

		send a byte to the display, used internally

	prntStr($message,$lineno)

		print a string on the specified line, using justification

		Parameters
		
			$message is a string, truncated to fit on a single line.
			$lineno is one's-based
	
	display('OFF')
	display('ON')
	display('CLEAR')

		turn display OFF, ON, or CLEAR
		CLEAR may be necessary if a new line written to the display does not
		overwrite all character positions on the line

		display('ON') is called during initialisation.

	lookup(<option>)

		lookup up an option value and return the string value

EXAMPLE

	#!/usr/bin/perl
	use RPi::I2C;
	use RPi::I2C::LCD;

	my $Disp = RPi::I2C::LCD->new;
	$Disp->prntStr(scalar localtime,2);
	$Disp->prntStr($Disp->lookup("version"),1);

AUTHOR

	Todd Merriman, <todd at toolz dot com>, 
	d.b.a. Software Toolz, Atlanta, Georgia

LICENSE AND COPYRIGHT

	Copyright (C) 2023 by Todd Merriman d.b.a. Software Toolz

	This library is free software; you can redistribute it and/or modify it
	under the same terms as Perl itself.

