hd44780.cpp

//  vi:ts=4
// -----------------------------------------------------------------------
//  hd44780.cpp - hd44780 base class
//  Copyright (c) 2014-2020  Bill Perry
//  (Derivative work of arduino.cc IDE LiquidCrystal library)
//  Note:
//    Original Copyrights for LiquidCrystal are a mess as originally none were
//    specified, but in Nov 2015 these have appeared so they are included:
//
//  Copyright (C) 2006-2008 Hans-Christoph Steiner. All rights reserved.
//  Copyright (c) 2010 Arduino LLC. All right reserved.
//
//  See licenseInfo.txt for a history of the copyrights of LiquidCrystal
// ------------------------------------------------------------------------
//
//  This file is part of the hd44780 library
//
//  hd44780 is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation version 3 of the License.
//
//  hd44780 is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with hd44780.  If not, see <http://www.gnu.org/licenses/>.
//
// See the license.txt file for further licensing & copyright details.
// -----------------------------------------------------------------------
//
// hd44780 is an extensible LCD library for hd44780 based LCD displays.
// The library consists of a hd44780 base class combined with one or more
// i/o subclasses to perform the i/o communication between the host and the
// hd44780 display interface.
//
// The API functionality provided by the hd44780 base class, when combined
// with an hd44780 library i/o subclass, is compatible with the API
// functionality of the Arduino LiquidCrystal library as well as compatibilty
// with most of the LCD API 1.0 Specification (nearly obsolete).
//
// The hd44780 API also provides some addtional extensions and all the API
// functions provided by hd44780 are common across all i/o subclasses.
//
// -----------------------------------------------------------------------
// History
//
// 2020-11-14  bperrybap - fixed timing issue in begin() on VERY fast processors like ESP using pinIO
// 2019.08.11  bperrybap - updates for reinitalization using begin() & init() and use of "new" 
// 2019.05.30  bperrybap - updates to support use of "new" for lcd objects
// 2019.02.03  bperrybap - fatalError(errcode), accept negative errcode values
// 2017.12.23  bperrybap - added LCD API 1.0 init() function
// 2017.05.11  bperrybap - setCursor() wraps when auto linewrap enabled
//                         and col beyond end of line
// 2017.05.11  bperrybap - linewrap tweak for better visual cursor position
// 2017.05.11  bperrybap - added auto linewrap functionality
// 2017.01.07  bperrybap - added blinkLED() and fatalError() 
// 2016.12.26  bperrybap - new constructors
// 2016.10.17  bperrybap - corrected DDRAM address mask in createChar()
// 2016.10.15  bperrybap - createChar() restores DDRAM location when possible
// 2016.09.08  bperrybap - changed param order of iowrite() to match ioread()
// 2016.08.06  bperrybap - changed iosend() to iowrite()
// 2016.08.06  bperrybap - added status() and read()
// 2016.07.27  bperrybap - added return status for command() and iosend()
// 2016.07.20  bperrybap - merged hd44780 base class and i/o classes into a
//                         single library.
// 2016.06.08  bperrybap - removed pre IDE 1.0 support
// 2016.06.03  bperrybap - added smart execution delays
// 2016.05.14  bperrybap - added LCD 1.0 API functions
// 2016.05.05  bperrybap - added support for 8 bit mode
// 2014.02.15  bperrybap - initial creation
//
// @author Bill Perry - bperrybap@opensource.billsworld.billandterrie.com
//
// ------------------------------------------------------------------------

#include "hd44780.h"


// Unfortunately, it cannot be assumed that the hd44780 object is zereod out since
// users can create the lcd object using "new".
// Because of this, the constructor code must initalize certain variables 
//
// One oddity is that constructors zero out the row/line offset/address table
// of addresses for each row/line
// This is intentional to allow these capabilities:
//  - user can call setRowOffsets() *before* begin()
//  - user can call init() at any time to reinitialize and
//    and the row offsets will be preserved.
// To support this, begin() will look at the row offsets and assign defaults if
// they have not been assigned. (still zero)
//

hd44780::hd44780() : _cols(0), _rows(0)
{
	/*
 	 * Set up default execution times for clear/home and
	 * all other instructions and data writes.
	 * Setting exec times here
	 * allows application to call setExecTimes() before begin()
	 * should it be necessary to override defaults.
	 */

	setExecTimes(HD44780_CHEXECTIME, HD44780_INSEXECTIME);

	// clear row offset addresses, will be set in begin()
	setRowOffsets(0,0,0,0);

	noLineWrap(); // no linewrap as default

	markStart(0); // initialize last start time to 'now'
}

hd44780::hd44780(uint8_t cols, uint8_t rows) : _cols(cols), _rows(rows)
{
	// clear row offset addresses, will be set in begin()
	setRowOffsets(0,0,0,0);

	noLineWrap(); // no linewrap as default

	setExecTimes(HD44780_CHEXECTIME, HD44780_INSEXECTIME);
	markStart(0); // initialize last start time to 'now'
}

hd44780::hd44780(uint8_t cols, uint8_t rows, uint32_t chExecTimeUs, uint32_t insExecTimeus) :
		 _cols(cols), _rows(rows), _chExecTime(chExecTimeUs), _insExecTime(insExecTimeus)
{
	// clear row offset addresses, will be set in begin()
	setRowOffsets(0,0,0,0);

	noLineWrap(); // no linewrap as default

	markStart(0); // initialize last start time to 'now'
}

// undocumented init() function to allow compatibilty with certain
// other "liquidcrystal" libraries like LiquidCrystal_I2C
//
// It is different than the IDE bundled LiquidCrystal library in that 
// it takes no parameters to be consistent across all i/o classes.
//
// This function can be called at any time to re-initialize the LCD
// LCD rowoffset table values and the execution timings are preserved
//
// Note: default rows and cols is 16x2
// which is different than LiquidCryal which is 16x1

int hd44780::init()
{
	if(!_cols)
		_cols = 16;
	if(!_rows)
		_rows = 2;
	return(begin(_cols, _rows));
}

//
// initialize the LCD
// Note: The hd44780 spec uses the term "line" whereas the
//  IDE LiquidCrystal library uses the term "row" so this
//  library (hd44780) will continue using the term "row"
//  rather than "line".
//  Other than name, they are the same.
//
// Returns 0 on success, non zero on initialization failure
//
int hd44780::begin(uint8_t cols, uint8_t rows, uint8_t dotsize)
{
int rval = 0;


	/*
	 * Limit lines/rows to max in the row offset table
	 */
	if(rows > sizeof(_rowOffsets) / sizeof(_rowOffsets[0]))
		rows = sizeof(_rowOffsets) / sizeof(_rowOffsets[0]);

	/*
	 * create default row/line offset table of addresses for each row/line
	 * if not already set by user using setRowOffsets() before begin() is called.
	 *	OR
	 * if the user is changing the number of columns on the display since a previous
	 * initialization
	 * 
	 * See here for further explanation of lcd memory addressing:
	 * http://web.alfredstate.edu/weimandn/lcd/lcd_addressing/lcd_addressing_index.html
	 * This default will handle:
	 * 40x2, 20x4, 20x2, 16x2, 16x1 (type 2), 16x4
	 * displays not supported by this:
	 * - 16x1 (type 1), This uses a discontigous memory for the single line
	 *   (This requires ugly mods to the library to make work)
	 * - 40x4 is dual 40x2 displays using dual E signals which is not suppo
	 *
	 * users can override this at any time by calling setRowOffsets(r0,r1,r2,r3)
	 */

	if((!_rowOffsets[0] && !_rowOffsets[1] && !_rowOffsets[2] && !_rowOffsets[3])
	 || (_cols && (_cols != cols)))
	{
		setRowOffsets(0x00, 0x40, 0x00 + cols, 0x40 + cols);
	}


	/*
	 * Save rows/cols
	 */
	_rows = rows;
	_cols = cols;

	/*
	 * SEE PAGE 45/46 of Hitachi HD44780 spec FOR INITIALIZATION SPECIFICATION.
	 * according to datasheet,we need at least 40ms after power rises above 2.7V
	 * before sending commands.The Arduino AVR can turn on and start running way
	 * before 4.5V so we'll wait 100ms to add some additional margin
	 */

	delay(100); 
  
	// default to 4 bit mode (can be overridded by i/o class library)
	_displayfunction = HD44780_4BITMODE;

	// call h/w i/o class init function
	if((rval = ioinit())) // intentional assignment
	{
		return(rval);
	}

	if (_rows > 1)
	{
		_displayfunction |= HD44780_2LINE;
	}

	// for some 1 line displays you can select a 10 pixel high font
	if ((dotsize != HD44780_5x8DOTS) && (rows == 1))
	{
		_displayfunction |= HD44780_5x10DOTS;
	}

	/*
	 * ========================================================================
	 * The init sequence below is shown in the hitachi HD44780 datasheet
	 * figures 23 & 24, pages 45 & 46
	 *
	 * NOTE:
	 * IMO, most explanations and comments about this sequence are wrong as the
	 * code authors don't really understand what it is actually doing.
	 * Adding to the confusion is that the hitachi HD44780 datasheet does
	 * a very poor job explaining this sequence. 
	 * Also, adding to the confusion is the note about FunctionSet on page 27:
	 *  ----------------------------------------------------------------------
	 *	Note: Perform the function at the head of the program before executing
	 *	any instructions (except for the read busy flag and address instruction)
	 *	From this point, the function set instruction cannot be executed unless
	 *	the interface data length is changed.
	 *  ----------------------------------------------------------------------
	 *
	 * It isn't clear what information this note is trying to convey.
	 *
	 * It appears to be implying that FunctionSet must be done first and that it
	 * cannot be executed later unless the data length is changed.
	 * If that is what it saying...
	 * This is in direct conflict with the comand sequence in the
	 * Initialize by Instruction in figures 23 & 24, particulary in
	 * figure 23 as the 4th command sent will be a FunctionSet command
	 * setting data length to 8 bits as well as the prefered the N and F bits
	 * when the data length is guaranteed to already be 8 bits. 
	 *
	 * But since sending a FunctionSet command with DL=1 along with setting N
	 * and F bits works when the display is already in 8 bit mode, my conclusion
	 * is that the note on page 27 is obviously incorrect and can be ignored.
	 *
	 * --
	 *
	 * When using 4 bit length mode, the LCD expects the nibbles on d4-d7 and
	 * expects the upper nibble of the 8 bits first.
	 * Therefore, when using 4 bit mode, it is critical that the host and
	 * the LCD are in sync on the nibbles.
	 *
	 * The command sequences in figures 23 and 24 are not simple retries and
	 * there is nothing magical about the timing.
	 * They are specifically chosen to ensure that after completion,
	 * the LCD is in the desired interface mode (8 bit or 4 bit).
	 * The two sequences start off with an identical 3 command sequence of
	 * FunctionSet commands which are used to reliably put the LCD into
	 * 8 bit length mode regardless of what mode or state the LCD happends
	 * to be in and regardless of whether the host is controlling all 8 data
	 * pin signals or just d4-d7.
	 * The only difference between the two sequences is that the 4 bit
	 * initializaion (figure 24) puts the LCD interface into 4 bit mode
	 * after the LCD is assured to be in 8 bit mode.
	 *
	 * 
	 * Below is a detailed explanation of the hd44780 initalization sequence
	 *
	 * --- bperrybap
	 *
	 * The overall methodology is to carefully use a command sequence that can
	 * first reliably put the LCD back into 8 bit mode and then if using 4 bit
	 * mode, a command can be issued to put the LCD into 4 bit mode.
	 * This sequence is not reseting the display but rather re-initalizing the
	 * host interface mode (8 bit or 4 bit)
	 * It also ensures that a host that can only control data lines D4-D7 is
	 * able to reliably get into nibble sync with the LCD and put the LCD into
	 * 4 bit mode regardless of the what state the LCD is currently in.
	 *
	 * This special initailization command sequence is required beause there is
	 * no way to actully reset the LCD to its power up default state and
	 * there is no way of knowing if the LCD is currently in 4bit or 8bit mode.
	 * Even if the h/w inteface is 8 bits, the LCD could potentially be in
	 * 4 bit mode.
	 * Also, if the LCD is in 4 bit mode, the LCD could be in the middle of
	 * receiving nibbles. i.e. the system was reset after only a single
	 * nibble was sent to the LCD.
	 * When the LCD is in 4 bit mode and out of nibble sync with the host:
	 * 	the LCD has received the upper/1st nibble of a command/data byte and
	 *	is waiting for the lower/2nd nibble.
	 *	After the 2nd nibble is recieved, the LCD will go off and execute an
	 *	unknown command. This is why the firt delay is so long. The host has to
	 *  accomodate the longest possible command execution time.
	 *	The next two FunctionSet commands will be interpreted
	 *	as a single FunctionSet command by the LCD to put the display back into 
	 *	8 bit mode.
	 *
	 * It appears that all delays specified in figures 23 & 24 are 2.7x the
	 * execution times in table 6. It appears that these values were chosen to
	 * accomodate LCDs that are running chips clocked slower than the 270kHz
	 * reference used in table 6
	 * A 2.7x factor would allow the Initialize by Instruction sequence to work
	 * with chips clocked down to 100Khz.
	 *
	 * In each of the 3 steps, EN is strobed once as the host will be
	 * treating the LCD h/w interface as if it is 8 bits wide regardless of
	 * whether the actual h/w interface to the LCD may only be 4 bits.
	 * d4-d7 signals on the hd44780 interface are set for 
	 * a function set "goto 8bit mode" command.
	 * Also, d0-d3 signals on the physical hd44780 interface are either set to
	 * low, or not driven in the case of 4 bit only h/w host interfaces.
	 *
	 * Here is the command sequence shown seperately for each of 3 states the
	 * LCD can be in. 
	 * This will demonstrate why there must be a command sequence
	 * of three "goto 8 bit mode" followed by one "goto to 4 bit mode" if
	 * using 4 bit mode.
	 *
	 * ========================================================================
	 * LCD in 8 BIT mode:
	 * =================
	 * 1) Set the upper 4 bits (d4-d7) of Functionset: FUNCTION_SET|8BIT = 0x3
	 *		8bit host: LCD interprets command 0x30
	 *			since lower 4 bits will be low and read as zeros.
	 *		4bit host: LCD interprets command 0x3X
	 *			since lower 4 bits will be unpredictable
	 *			FUNCTION_SET & 8BIT are set, so it gets interpreted as a
	 *			"goto 8bit mode" and so this is essentially a NOP as the
 	 *			display is already 8 bit mode
	 *
	 * 2) Set the upper 4 bits (d4-d7) of Functionset: FUNCTION_SET|8BIT = 0x3
	 *		8bit host: LCD interprets command 0x30
	 *			since lower 4 bits will be low and read as zeros.
	 *		4bit host: LCD interprets command 0x3X
	 *			since lower 4 bits will be unpredictable
	 *			FUNCTION_SET & 8BIT are set, so it gets interpreted as a
	 *			"goto 8bit mode" and so this is essentially a NOP as the
 	 *			display is already 8 bit mode
	 *
	 * 3) Set the upper 4 bits (d4-d7) of Functionset: FUNCTION_SET|8BIT = 0x3
	 *		8bit host: LCD interprets command 0x30
	 *			since lower 4 bits will be low and read as zeros.
	 *		4bit host: LCD interprets command 0x3X
	 *			since lower 4 bits will be unpredictable
	 *			FUNCTION_SET & 8BIT are set, so it gets interpreted as a
	 *			"goto 8bit mode" and so this is essentially a NOP as the
 	 *			display is already 8 bit mode
	 *
	 * LCD in 4 bit mode and expecting upper/1st nibble:
	 * =================================================
	 * 1) Set the upper 4 bits (d4-d7) of Functionset: FUNCTION_SET|8BIT = 0x3
	 *		LCD pulls in nibble as upper 4 bits of 8 bit command
	 *
	 * 2) Set the upper 4 bits (d4-d7) of Functionset: FUNCTION_SET|8BIT = 0x3
	 *		LCD pulls in nibble as lower 4 bits to complete 8 bits of command
	 *		LCD interprets command 0x33.
	 *			the LCD sees a Goto 8bit mode command and changes to 8 bit mode.
	 *
	 * 3) Set the upper 4 bits (d4-d7) of Functionset: FUNCTION_SET|8BIT = 0x3
	 *		LCD interprets command 0x30 on 8bit hosts since
	 *			 lower 4 bits will be low and read as zeros.
	 *		LCD interprets command 0x3X on 4 bit hosts since
	 *			 lower 4 bits will be unpredictable
	 *		since FUNCTION_SET & 8BIT are set, it gets interpreted as
	 *			 a "goto 8bit mode" and so
	 * 		this is essentially a NOP as the display is already 8 bit mode
	 *
	 * LCD in 4 bit mode and expecting lower/2nd nibble:
	 * (out of nibble sync with host)
	 * ========================================================================
	 * 1) Set the upper 4 bits (d4-d7) of Functionset: FUNCTION_SET|8BIT = 0x3
	 *		LCD pulls in nibble as lower 4 bits to complete 8 bits of command
	 *		LCD interprets command with upper nibble (unknown) and lower
	 *		nibble 0x3
	 *		There is no telling what this command does as the upper nibble is
	 *		unknown. And THAT is why the first delay in the sequence must be so
	 *		long. It isn't that the the first "function set" takes that long it
	 *		is because there is no telling what command might now be executing
	 *		and BUSY cannot be used yet.
	 *		Therefore, the host must blind wait the worst case amount of time.
	 *		A 4.1ms delay appears to be 2.7x the worst case instruction
	 *		execution time (clear & home are 1.52ms) at a 270kHz LCD clock rate.
	 *		(4.1ms would accomodate a chip clocked at 100kHz instead of 270 kHz)
	 *
	 * 2) Set the upper 4 bits (d4-d7) of Functionset: FUNCTION_SET|8BIT = 0x3
	 *		If LCD happened to go into 8BIT mode in step 1
	 *			LCD interprets this command as 0x30
	 *				since d0-d3 lower 4 bits will be read as zeros in 8 bit mode
	 *				This is essentially a NOP as the display is already in
	 *				8 bit mode
	 *
	 *		If LCD still in 4 bit mode,
	 *			then this is upper nibble of next command.
	 *
	 * 3) Set the upper 4 bits (d4-d7) of Functionset: FUNCTION_SET|8BIT = 0x3
	 *		If LCD happened to go into 8BIT mode in step 1
	 *			LCD interprets this command as 0x30
	 *				since d0-d3 lower 4 bits will be read as zeros in 8 bit mode
	 *				This is essentially a NOP as the display is already in
	 *				8 bit mode
	 *
	 *		If LCD still in 4 bit mode
	 *			LCD pulls in nibble as lower 4 bits to complete 8 bits of cmd
	 *			LCD interprets command 0x33.
	 *			the LCD sees a Goto 8bit mode command and changes to 8 bit mode.
	 *
	 *
	 * =======================================================================
	 * Once the display in 8 bit mode, if the interface is to be in 4 bit mode:
	 * =======================================================================
 	 * - Set the upper 4 bits of Functionset: with 8BIT clear
	 *	this puts the LCD in 4 bit and it now expects upper nibble
	 */

    
	/*
	 * Note:
	 * The initialization sequence below uses special hd44780 internal API
	 * for 4 bit commands.
	 * Internal 4 bit commands are commands that are sent to the LCD using
	 * only a single strobe of EN even if the host h/w interface is 4 bit only.
	 * In other words it is indicating that only the upper 4 bits need to be
	 * sent to the display - so effectively the host must ensure that the
	 * upper four bits are placed on D4-d7 and that EN is stobed only once
	 * including if the host h/w interface is only 4 bits wide.
	 *
	 * 8bit only i/o interface libraries can ignore this as the bits for these
	 * special commands are in the proper d4-d7 bit locations so the full
	 * 8 bit byte can be presented to the LCD.
	 * i.e.
	 *  - 8 bit interfaces can treat 4bit commands the same as regular commands
	 *  - 4 bit only interfaces will send just the upper 4 bits (d4-d7)
	 *
	 * Additional Note:
	 *	The Initiatlization by Instruction figures 23 & 24 of the hitachi spec
	 *	seems to use delays that are 2.7x the specified instruction times based
	 *	on a 270khz clock from table 6
	 *  i.e. 4.1ms is 2.7x 1.52ms of clear/home commands
	 *	and 100us is 2.7x 37us for all the other instructions (cmd & data)
	 *  The delay values appear to be accomodating LCDs clocked down to 100kHz
	 *	rather than at the 270Khz reference.
	 *	This library will wait a little bit longer given the delay functions
	 *	used. However, since iowrite() honors execution times, 
	 *  the delays here are in addition to the configured execution times
	 *	and technically should not be needed.
	 *  So if the application called setExecTimes() with excution
	 *  values prior to begin() those will be in addition to these
	 *  delays so everthing should work no matter how slow the LCD is.
	 *
	 * Note that delay() is used here vs delayMicroSeconds() as delay()
	 * on later versions of Arduino core code calls some scheduling functions
	 * like yield() to potentially allow other code to execute during this time period.
	 *
	 * delay() can be used because this code is never called from a constructor
	 *
	 */
	command4bit(HD44780_FUNCTIONSET|HD44780_8BITMODE);
	delay(5); // wait 5ms vs 4.1ms, some are slower than spec

	command4bit(HD44780_FUNCTIONSET|HD44780_8BITMODE);
	delay(1); // wait 1ms vs 100us
    
	command4bit(HD44780_FUNCTIONSET|HD44780_8BITMODE);
	delay(1); // wait 1ms vs 100us

	/*
	 * At this point the LCD is guaranteed to be in 8 bit mode
	 *
	 * If the interface needs to be put into 4 bit mode, the
	 * goto 4bit mode command is sent as another special internal
	 * "4bit" command because the 4bit only host talks 4 bits and the LCD
	 * isn't in 4 bit mode yet.
	 * Note: there is no need for a delay *after* command4bit() since
	 * it uses markStart(_insExecTime) to indicate the instruction time
	 * and will be honored by waitReady() used in the i/o class.
	 */
	if(!(_displayfunction & HD44780_8BITMODE))
		command4bit(HD44780_FUNCTIONSET|HD44780_4BITMODE);

	/*
	 * At this point the LCD is in 8 bit mode for 8 bit host interfaces,
	 * and in 4 bit mode for 4bit only host interfaces so we can 
	 * now use the "normal" library command() & API interface functions
	 */

	// set # lines, font size, etc.
	command(HD44780_FUNCTIONSET | _displayfunction);  


	// turn the display on with no cursor or blinking default
	_displaycontrol = HD44780_DISPLAYON | HD44780_CURSOROFF | HD44780_BLINKOFF;  
	display();

	clear(); // clear display

	// Initialize to default text direction (for romance languages)
	_displaymode = HD44780_ENTRYLEFT2RIGHT;
	// set the entry mode
	rval = command(HD44780_ENTRYMODESET | _displaymode);

// FIXME
#ifdef LATER
	// quick check to see if BUSY is working on devices that support reads
	{
	int lcdstatus = status();
		if(lcdstatus >= 0)
		{
			// if BUSY bit is set then there is a problem
			if(lcdstatus &  0x80)
				return(RV_EBUSY);
		}
	}
#endif
	backlight(); // turn on the backlight, if supported

	return(rval);
}

int hd44780::clear()
{
	return(command(HD44780_CLEARDISPLAY));  // clear display, set cursor to 0,0
}

int hd44780::home()
{
	return(command(HD44780_RETURNHOME));  // set cursor position to 0,0
}

// setRowOffsets:
//
// Create a row/line offset table of addresses for each row/line
// See here for further explanation of lcd memory addressing:
// http://web.alfredstate.edu/weimandn/lcd/lcd_addressing/lcd_addressing_index.html

int hd44780::setRowOffsets(int row0, int row1, int row2, int row3)
{
	_rowOffsets[0] = row0;
	_rowOffsets[1] = row1;
	_rowOffsets[2] = row2;
	_rowOffsets[3] = row3;
	return(RV_ENOERR);
}


int hd44780::setCursor(uint8_t col, uint8_t row)
{
	// while this could return RV_EINVAL for invalid parameters
	// it is going to adjust them to maintain compability with existing LiquidCrystal
	// library and to allow a back door way to set the ddram address - see below

	if ( row >= _rows ) 
	{
		// set to max line (rows/lines start at 0, _rows is 1 based)
		row = _rows-1;
	}
	/*
	 * if col is too large, it can't corrupt the command since
	 * SETDDRRAMADDR is bit 7 of the byte
	 * It is intionally not checked to allow allow:
	 * - positioning off the end of the visable line
	 * - if line 0 is used, it is a backdoor to do SETDDRAMADDR to any address
	 *
	 * NOTE:
	 * Things are handled differently if auto linewrap is enabled:
	 * position takes into consideration line wrapping.
	 * i.e. positioning to col 16, row 0  on a 16x2 display
	 * will position the cursor to col 0 row 1.
	 */

	if(_wraplines)
	{
		// wrap while requested col > toal cols
		while(col >= _cols)
		{
			col -= _cols;
			if(++row >= _rows)
				row = 0; // wrap back to top line
		}

		// save position
		_curcol = col;
		_currow = row;
	}

#ifdef later
	// in right to left mode the cursor position wil be incorrect.
	// however, things like home() and clear() will not work as expected either.
	// home() positions back to DDRAMADDR 0 
	// clear() positions back to DDRAMADDR 0 and removes the right to left mode
	// It isn't clear how home() and clear() should be handled.
	// if they position to (0,0) then they have to expcility do it as well as
	// restore rightToLeft() mode when being used.
	//
	if(!(_displaymode & HD44780_ENTRYLEFT2RIGHT))
		return(command(HD44780_SETDDRAMADDR | (_cols - col -1 + _rowOffsets[row])));
	else
#endif
		return(command(HD44780_SETDDRAMADDR | (col + _rowOffsets[row])));
}

// turn off display pixels
int hd44780::noDisplay()
{
	_displaycontrol &= ~HD44780_DISPLAYON;
	return(command(HD44780_DISPLAYCONTROL | _displaycontrol));
}

// turn on display pixels
int hd44780::display()
{
	_displaycontrol |= HD44780_DISPLAYON;
	return(command(HD44780_DISPLAYCONTROL | _displaycontrol));
}

// Turns off underline cursor
int hd44780::noCursor()
{
	_displaycontrol &= ~HD44780_CURSORON;
	return(command(HD44780_DISPLAYCONTROL | _displaycontrol));
}
// Turn on underline cursor
int hd44780::cursor()
{
	_displaycontrol |= HD44780_CURSORON;
	return(command(HD44780_DISPLAYCONTROL | _displaycontrol));
}

// Turn on off the blinking cursor
int hd44780::noBlink()
{
	_displaycontrol &= ~HD44780_BLINKON;
	return(command(HD44780_DISPLAYCONTROL | _displaycontrol));
}

// Turn on the blinking cursor
int hd44780::blink()
{
	_displaycontrol |= HD44780_BLINKON;
	return(command(HD44780_DISPLAYCONTROL | _displaycontrol));
}

// These API functions scroll/shift the display contents without changing the RAM
int hd44780::scrollDisplayLeft(void)
{
	return(command(HD44780_CURDISPSHIFT | HD44780_DISPLAYMOVE | HD44780_MOVELEFT));
}
int hd44780::scrollDisplayRight(void)
{
	return(command(HD44780_CURDISPSHIFT | HD44780_DISPLAYMOVE | HD44780_MOVERIGHT));
}

// This is for text that flows Left to Right
int hd44780::leftToRight(void)
{
	_displaymode |= HD44780_ENTRYLEFT2RIGHT;
	return(command(HD44780_ENTRYMODESET | _displaymode));
}

// This is for text that flows Right to Left
int hd44780::rightToLeft(void)
{
	_displaymode &= ~HD44780_ENTRYLEFT2RIGHT;
	return(command(HD44780_ENTRYMODESET | _displaymode));
}

// This moves the cursor one space to the right
int hd44780::moveCursorRight(void)
{
	return(command(HD44780_CURDISPSHIFT | HD44780_CURSORMOVE | HD44780_MOVERIGHT));
}

// This moves the cursor one space to the left
int hd44780::moveCursorLeft(void)
{
	return(command(HD44780_CURDISPSHIFT | HD44780_CURSORMOVE | HD44780_MOVELEFT));
}

// This will enable autoshifting display as new characters are written.
// If mode is left to right, shift is left
// if mode is right to left, shift is right
int hd44780::autoscroll(void)
{
	_displaymode |= HD44780_ENTRYAUTOSHIFT;
	return(command(HD44780_ENTRYMODESET | _displaymode));
}

// This will disable autoshifting when new characters are written
int hd44780::noAutoscroll(void)
{
	_displaymode &= ~HD44780_ENTRYAUTOSHIFT;
	return(command(HD44780_ENTRYMODESET | _displaymode));
}

// Allows filling in the first 8 CGRAM locations
// with custom characters
// note that it is not possible to support more than 8 locations
// since SETCGRAMADDR instruction is bit 6 and there no room
// for any more address bits.
// (location is bits 3-5 and data row is bits 0-2 of the instruction)
int hd44780::createChar(uint8_t location, uint8_t charmap[])
{
int rval;
int ddramaddr;

	location &= 0x7; // we only have 8 locations 0-7

	ddramaddr = status(); // fetch status which includes ddram address

	if(ddramaddr < 0) // status() failed, so just set address to 0
		ddramaddr = 0;
	else
		ddramaddr &= 0x7f; // strip off BUSY bit

	rval = command(HD44780_SETCGRAMADDR | (location << 3));
	if(rval)
		return(rval);
	for (int i=0; i<8; i++)
	{
		if(_write(charmap[i]) != 1) // use raw write to avoid line processing
			return(RV_EIO);
	}

	// put LCD back into DDRAM mode so write() works
	return(setCursor(ddramaddr , 0));
}

// special version of code to support wimpy AVR parts that can't directly access
// const data in flash like all the other processors
// Note that most other Arduino cores have adopted to support the
// AVR proprietary PROGMEM macros to be compatible with AVR specific code.
// Since the macro PROGMEM is defined when proprietary AVR progmem support is
// implememented (even on non AVR cores),
// this code will look for that macro to enable special code to deal with it.
// While at this time, this is only needed for AVR parts, it will work on
// non AVR parts that have implemented support for the proprietary
// AVR progmem crap.
//
#if defined (PROGMEM)
int hd44780::createChar(uint8_t location, const uint8_t *charmap)
{
uint8_t buf[8];
	// fetch/read the full 8 byte glyph data into RAM
	for(int i= 0; i< 8; i++)
	{
		buf[i] = pgm_read_byte(charmap++);
	}
	// call the RAM based function to actually send it to the LCD
	return(createChar(location, buf));
}
#else
int hd44780::createChar(uint8_t location, const uint8_t *charmap)
{
	return(createChar(location, (uint8_t *)charmap));
}

#endif

// turn on backlight at full intensity
int hd44780::backlight(void)
{
	return(iosetBacklight(-1)); // max brightness
}

// turn off backlight
int hd44780::noBacklight(void)
{
	return(iosetBacklight(0));
}

// turn on pixels and backlight
int hd44780::on ( void )
{
int rval;

	rval = display();
	backlight(); // ignore any issues for backlight control
	return(rval);
}

// turn off pixels and backlight
int hd44780::off ( void )
{
   noBacklight(); // ignore any issues for backlight control
   return(noDisplay());
}

// command() - send hd44780 command byte to lcd
//
// Returns 0 on success, non zero if command failed
//
inline int hd44780::command(uint8_t value)
{
int status;

	status = iowrite(HD44780_IOcmd, value);

	// executime time depends on command
	if((value == HD44780_CLEARDISPLAY) || (value == HD44780_RETURNHOME))
	{
		_curcol = 0;
		_currow = 0;
		markStart(_chExecTime);
	}
	else
	{
		markStart(_insExecTime);
	}

	return(status);
}

// status() - read status byte from LCD
// returns:
// 	success: 8 bit hd44780 status byte (busy flag & address)
//	failure: neagative value (error or read/status not supported by i/o subclass
int hd44780::status()
{
int rvalue = ioread(HD44780_IOcmd);
	// markStart() is not called here as status reads do not
	// require any execution time.
	// setting the start time to now, which is 0, can potentially erase
	// the execution time of a previous command if status reads
	// are not supported therefore, just leave the previous start time.
	return(rvalue);
}

// read() - read a data byte from LCD
// returns:
// 	success: 8 bit value read
//	failure: neagative value (error or read not supported by i/o subclass
int hd44780::read()
{
int rvalue = ioread(HD44780_IOdata);
	// it apears that even though the read operation actually completed
	// when the data has been read, i.e. ioread() returns,
	// that the chip cannot take another instruction
	// until after the normal instruction execution time.
	// See Table 6 page 25 of Hitachi hd44780 datasheet
	markStart(_insExecTime);
	return(rvalue);
}

// write() - process data character byte to lcd
// returns number of bytes successfully written to device
// i.e. 1 if success or 0 if no character was processed (error)
size_t hd44780::write(uint8_t value)
{
size_t rval;

	rval = _write(value);
	if(_wraplines)
	{
		// currently only works for left to right mode
		if(++_curcol >= _cols)
		{
			_curcol = 0;
			_currow++;
			if(_currow >= _rows)
				_currow = 0;
			setCursor(_curcol, _currow);
		}
	}
	return (rval);
}


// _write() - send raw data byte to lcd
// returns 1 if success or 0 if no byte was processed (error)
size_t hd44780::_write(uint8_t value)
{
int status = 1; //assume success

	if(iowrite(HD44780_IOdata, value))
		status = 0; // write was unsuccessful
	markStart(_insExecTime);
	
	return status;
}

//============================================================================
// A couple of functions that really shouldn't be here.
// blinkLED() and fatalError()
//
// NOTE: I REALLY do not like having these functions here and they definitely
// do not belong in this class; HOWEVER.... blinking a built in LED in arduino
// is not as easy as it should be to ensure that works across many different
// cores and boards.
// Some cores didn't correclty define their LED_BUILTIN define, and some boards
// use use an active LOW LED.
// To make things simpler for the hd44780 examples and ensure consistency as
// well as making maintenance much easier,
// I held my nose and moved those two functions to here.
// -- bperrybap

// blinkLED() - blink builtin LED
// blinks a built in LED if there is one.
// returns zero if successful
//

// helper macros to turn on built in LED as some boards like the ESP8266 use
// active low LEDs

#if defined(ARDUINO_ARCH_ESP8266)
#define ledBuiltinOn() digitalWrite(LED_BUILTIN, LOW)
#define ledBuiltinOff() digitalWrite(LED_BUILTIN, HIGH)
#else
#define ledBuiltinOn() digitalWrite(LED_BUILTIN, HIGH)
#define ledBuiltinOff() digitalWrite(LED_BUILTIN, LOW)
#endif

int hd44780::blinkLED(int blinks)
{
#ifdef LED_BUILTIN
	pinMode(LED_BUILTIN, OUTPUT);
	// blink out error code
	for(int i = 0; i< blinks; i++)
	{
		ledBuiltinOn();
		delay(100);
		ledBuiltinOff();
		delay(250);
	}
	return(0);
#else
	// No built in LED, so do "nothing"
	if(blinks){} // "nop" if to eliminate warning, will be optimized out

	return(RV_ENOTSUP);
#endif
}

// fatalError() - loop & blink an error code
void hd44780::fatalError(int errcode)
{
	if(errcode < 0)
		errcode = -errcode;
	while(1)
	{
		blinkLED(errcode);	// blink LED if possible
		delay(1500);		// using delay() ensures watchdogs don't trip
	}
}
//============================================================================