f8544lcd Files

/*****************************************************************
	███████╗ █████╗ ███████╗██╗  ██╗██╗  ██╗██╗      ██████╗██████╗  *
	██╔════╝██╔══██╗██╔════╝██║  ██║██║  ██║██║     ██╔════╝██╔══██╗ *
	█████╗  ╚█████╔╝███████╗███████║███████║██║     ██║     ██║  ██║ *
	██╔══╝  ██╔══██╗╚════██║╚════██║╚════██║██║     ██║     ██║  ██║ *
	██║     ╚█████╔╝███████║     ██║     ██║███████╗╚██████╗██████╔╝ *
	╚═╝      ╚════╝ ╚══════╝     ╚═╝     ╚═╝╚══════╝ ╚═════╝╚═════   *
-------------------------------------------------------Alpha version *
 ******************************************************************
         f8544lcd : C PCD8544 & GFX libs For Monochrome Nokia LCD (Model PCD8544) for pinguino boards

	->File :README.TXT
    ->Revision : 0.01 Alpha
	->Last update : March 2014
	-> Description : Documentation of F8544LCD library for Pinguino boards
	
 This port is non affiliated, non licensed , non endorsed, and non supported in any way by Adafruit or Microchip.
 
This lib is a free and individual Pinguino/ PIC18F C port/rewriting of a mix of Two C++ libs From Adafruit :
 
 - Adafruit PCD8544 

  and 

- AdaFruit GFX                                

Known limitation : Can drive only 1 display at time (as original library).


Ported to Pinguino/Pic by Thomas Missonier (sourcezax@users.sourceforge.net). 


Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice,
  this list of conditions, the others licences below, and the following disclaimer.
- Redistributions in binary form must reproduce the above notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

---------------------------------------------------------------------------------
Adafruit PCD8544
*//*********************************************************************
This is a library for our Monochrome Nokia 5110 LCD Displays

  Pick one up today in the adafruit shop!
  ------> http://www.adafruit.com/products/338

These displays use SPI to communicate, 4 or 5 pins are required to  
interface

Adafruit invests time and resources providing this open source code, 
please support Adafruit and open-source hardware by purchasing 
products from Adafruit!

Written by Limor Fried/Ladyada  for Adafruit Industries.  
BSD license, check license.txt for more information
All text above, and the splash screen below must be included in any redistribution
*********************************************************************
AdaFruit GFX
---------------------------------------------------------------------------------
This is the core graphics library for all our displays, providing a common
set of graphics primitives (points, lines, circles, etc.).  It needs to be
paired with a hardware-specific library for each display device we carry
(to handle the lower-level functions).

Adafruit invests time and resources providing this open source code, please
support Adafruit & open-source hardware by purchasing products from Adafruit!
 
Copyright (c) 2013 Adafruit Industries.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
---------------------------------------------------------------------------
*********************************************************************/

--------------------------------------------------------------
1. What is F8544lcd library?
--------------------------------------------------------------

	FB544lcd library is a fusion of two Arduino's open source's libraries (PCD8544 drivers and adafruit graphic library)developped by Adafruit (all rights reserved).
	It provides driver and Graphic functions to drive a 3310/5510 nokia monochrome LCD (pcd8544 model) screen on pinguino boards based on PIC.
	
	It has been arranged/optimised and ported from C++ TO C by Thomas Missonier.

--------------------------------------------------------------
2. How to Install it?
--------------------------------------------------------------
	Download and Extract the files from Archive.

	On 8 bits pinguino boards :

	-Copy the glcdfont.c, fr8544lcd.c and fr8544lcd.h files to your pinguino_ide_directory/p8/pinguino/libraries folder
	-Copy the f8544lcd.pdl file to your pinguino_ide_directory/p8/pdl folder

	On 32 bits pinguino boards (Not tested yet):

	-Copy the glcdfont.c, fr8544lcd.c and fr8544lcd.h files to your pinguino_ide_directory/p32/pinguino/libraries folder
	-Copy the f8544lcd.pdl file to your pinguino_ide_directory/p32/pdl folder

	Copy the examples/f85lcd folder to 
	Restart your Pinguino's IDE if started, it's done!

--------------------------------------------------------------
3. Wiring the screen To your Pinguino board
--------------------------------------------------------------

	!!Important, you need to read your lcd's datasheet and Pinguino Specifications before wiring. There are Many models, and some connections and voltages requirements may differ.
	You can damage Your screen or your Board if you use wrong wiring or voltages!

	Here is an wiring example on 5V pinguino (PIC18F4550) with A particular screen :

	pin 17	---> LCD CS/CE  
	pin 	--->LCD RST 
	pin 	--->LCD Dat/Com
	pin 	--->LCD SPIDat/DIN/SDIN
	pin 	---> LCD SPIClk/CLK 
	GROUND or VCC 3.3V (depending of models) ---> LCD LED/LIGHT                                      
	//Ground --->Ground
	3,3V	--->Vcc  

	Note : a 2.8-3.3V input is required(Extra components is needed to convert 5V to 3.3V). I've made a diviser divider with two 1,8 kohms resistors to obtain a voltage near of 3V.
	Use limiting resistors between Pinguino pin, and lcd pins (I use 10kohm)
--------------------------------------------------------------
4. How to use it?
--------------------------------------------------------------

On Pinguino IDE, you don't need to include any file. FD8544lcd comes with pdl, so pinguino includes all necessary files and code protion if needed.

In order to use it and activate the screen, you need to use the functions :
 
 f8544lcd.initCS(F8544LCD_SCLK,F8544LCD_SDIN, F8544LCD_DC,F8544LCD_SCE, F8544LCD_RESET);
 
 And
    f8544lcd.begin(40);
	
 Note : since the C port, contrast is mandatory in function begin, I suggest 40, but i can be changed later.
 For other functions, see "Available user functions" section (6) below to see the list of available functions and their descriptions.

--------------------------------------------------------------
 5. Note, Todo, and Troubleshouting
--------------------------------------------------------------
	 
	 5.1 Note and Todo 
		 --------------
		-This library needs more optimisations to reduce the generated hex size.
		-It uses an SPI software, no spi hardware yet.
		-this library has not been tested on pic32 boards.
		
	 5.2 Troubleshooting
		 --------------
		If you have this error on pic18F4500 boards:
		"linker script has no definition that matches the type of section ".idata"
		Open the file boot4.18f4550.lkr (Thanks to André from Pinguino forum for his help :))
		change :
		DATABANK NAME=gpr1 START=0x100 END=0x1FF
		DATABANK NAME=gpr2 START=0x200 END=0x2FF
		DATABANK NAME=gpr3 START=0x300 END=0x3FF
		to :
		//DATABANK NAME=gpr1 START=0x100 END=0x1FF
		//DATABANK NAME=gpr2 START=0x200 END=0x2FF
		DATABANK NAME=gpr3 START=0x100 END=0x3FF

		and :
		DATABANK NAME=gpr6 START=0x600 END=0x6FF
		DATABANK NAME=gpr7 START=0x700 END=0x7FF
		to
		//DATABANK NAME=gpr6 START=0x600 END=0x6FF
		DATABANK NAME=gpr7 START=0x600 END=0x7FF

		
	3.3 Contact
		 --------------
		Any question, bug report, suggestion, contact or review, please feel free to contact me at :
		sourcezax@users.sourceforge.net
		

 
 

--------------------------------------------------------------
 6 . Available user functions
--------------------------------------------------------------

	***************************
	*f8544lcd.PartialUpdate() *
	***************************
		This is a dummy function (put a #define in the code)to enable Partial update of The screen. It will accelerate Your display. It will only redraw what has been modified on your screen.
		I suggest to place it into your code.

	************************************
	*f8544lcd.height() (*#define alias)*
	************************************

		Return the height of the screen

	**********************************
	*f8544lcd.width()(*#define alias)*
	**********************************

		Return the width of the screen 

	**************************************************************
	*void f8544lcd.initCS(s8 SCLK, s8 DIN, s8 DC, s8 CS, s8 RST);*
	**************************************************************

		Init the screen with Cable select. I suggest to use this function to init the screen.

	******************************************************	
	* void f8544lcd.init(s8 SCLK, s8 DIN, s8 DC, s8 RST);*
	******************************************************

		The same function withous C/S support. Not recommended

	************************************
	*void f8544lcd.begin(u8 contrast); *
	************************************

		This function starts the screen. the contrast value is mandatory. 40 is a standard value.

	***********************************
	*void f8544lcd.setContrast(u8 val)*
	***********************************
		
		Set the contrast value of the screen.

	*************************	
	*void f8544lcd.display()*
	*************************
		
		Send buffer values to the screen. Used to refresh to refresh the screen. Usefull when drawing, they will not appear, until you run this command ;)

	******************************	
	*void f8544lcd.clearDisplay()*
	******************************
		Clear the buffer screen, set the cursor to 0,0. 

	**************************************************
	*void f8544lcd.drawPixel(s16 x, s16 y, u16 color)*
	**************************************************

		Draw a pixel with the <color> color into the buffer at x,y.

	**********************************
	*u8 f8544lcd.getPixel(s8 x, s8 y)*
	**********************************

		Get the the value of pixel at x,y

	*************************************************************
	* void f8544lcd.drawCircle(s16 x0, s16 y0, s16 r, u16 color)*
	*************************************************************

		Draw a circle into buffer at X,Y with radius r and color <color>

	************************************************************
	*void f8544lcd.fillCircle(s16 x0, s16 y0, s16 r, u16 color)*
	************************************************************

		Fill a circle into buffer at X,Y with radius r and color <color>

	**************************************************************************************
	*void f8544lcd.drawTriangle(s16 x0, s16 y0, s16 x1, s16 y1,s16 x2, s16 y2, u16 color)*
	**************************************************************************************

		Draw a triangle with color <color> between 3 points : (x0,y0), (x1,y1) and (x2,y2)
	 
	**************************************************************************************
	*void f8544lcd.fillTriangle(s16 x0, s16 y0, s16 x1, s16 y1,s16 x2, s16 y2, u16 color)*
	**************************************************************************************

		Fill a triangle with color <color> between 3 points : (x0,y0), (x1,y1) and (x2,y2)

	**************************************************************************
	*void f8544lcd.drawRoundRect(s16 x, s16 y, s16 w,s16 h, s16 r, u16 color)*
	**************************************************************************

		Draw a rounded rectangle of <w> width and <h> height at x,y with color <color>.

	**************************************************************************
	*void f8544lcd.fillRoundRect(s16 x, s16 y, s16 w,s16 h, s16 r, u16 color)*
	**************************************************************************

		Fill a rounded rectangle of <w> width and <h> height at x,y with color <color>.

	**********************************************************************************
	*void f8544lcd.drawBitmap(s16 x, s16 y, const u8 *bitmap,s16 w, s16 h, u16 color)*
	**********************************************************************************

		Draw a Bitmap with color <color> at <x>,<y> with <w>width and <h>height
		
	***************************************
	*void f8544lcd.setCursor(s16 x, s16 y)*
	**************************************
		
		Set text cursor postion to <x>,<y>

	***********************************
	*void f8544lcd.setTextColor(u16 c)*
	***********************************

		Set Text color width <c>color

	********************************************
	*void f8544lcd.setTextColor2(u16 c, u16 bg)*
	********************************************

		Set Text color width <c>color, and backgrounf with <bg>color

	*********************************
	*void f8544lcd.setTextSize(u8 s)*
	*********************************
		Set the size <s> of the text

	********************************************************
	* void f8544lcd.setTextWrap(boolean w) (*#define alias)*
	********************************************************
		Enable or disable Text wrapping

	*********************************
	*void f8544lcd.setRotation(u8 x)*
	*********************************
		Set the rotation to <x>

	********************************************
	*u8 f8544lcd.getRotation() (*#define alias)*
	********************************************

		return the rotation

	*******************************************************************
	*void f8544lcd.drawLine(s16 x0, s16 y0, s16 x1, s16 y1, u16 color)*
	*******************************************************************
		
		Draw a line between (<x0,y0>) and <x1,Y1> with color <color>

	*************************************************************
	*void f8544lcd.drawFastVLine(s16 x, s16 y, s16 h, u16 color)*
	*************************************************************
		Draw a vertical line who starts at(<x0,y0>),<h> height, with color <color>

	*************************************************************
	*void f8544lcd.drawFastHLine(s16 x, s16 y, s16 w, u16 color)*
	*************************************************************
		
		Draw a horizontal line who starts at(<x0,y0>), <h> with, with color <color>

	***************************************************************
	*void f8544lcd.drawRect(s16 x, s16 y, s16 w, s16 h, u16 color)*
	***************************************************************
		
		Draw a  rectangle of <w> width and <h> height at x,y with color <color>.

	**************************************************************
	*void f8544lcd.fillRect(s16 x, s16 y, s16 w, s16 h, u16 color)*
	**************************************************************
		
		Fill a  rectangle of <w> width and <h> height at x,y with color <color>.

	*****************************************************
	*void f8544lcd.fillScreen(u16 color) (*#define alias)*
	*****************************************************
		
		Fill the screen with <color> color

	**************************************
	*void f8544lcd__invertDisplay(bool i)*
	**************************************

		Not implemented, maintened for future release.

	****************************
	*void f8544lcd__write(u8 c)*
	****************************

		Write the <c> char to the screen

	***********************************
	*void f8544lcd.print(char *chaine)*
	***********************************

	Print a string to the screen

	********************************************
	*void f8544lcd__printNumber(u16 n, u8 base)*
	********************************************

	Print a numbre <n> with base <base> to the screen.