UTFT Arduino and chipKit Universal TFT display library
Manual
UTFT l i br ar y Page 1 PREFACE: Thi s l i br ar y i s t he cont i nuat i on of my I TDB02_Gr aph, I TDB02_Gr aph16 and RGB_GLCD l i br ar i es f or Ar dui no and chi pKi t . As t he number of suppor t ed di spl ay modul es and cont r ol l er s st ar t ed t o i ncr ease I f el t i t was t i me t o make a si ngl e, uni ver sal l i br ar y as i t wi l l be much easi er t o mai nt ai n i n t he f ut ur e.
Basi c f unct i onal i t y of t hi s l i br ar y was or i gi anl l y based on t he demo- code pr ovi ded by I Tead st udi o ( f or t he I TDB02 modul es) and NKC El ect r oni cs ( f or t he RGB GLCD modul e/ shi el d) .
Thi s l i br ar y suppor t s a number of 8bi t , 16bi t and ser i al gr aphi c di spl ays, and wi l l wor k wi t h bot h Ar dui no and chi pKi t boar ds. For a f ul l l i st of t est ed di spl ay modul es and cont r ol l er s, see t he document UTFT_Supported_display_modules_&_controllers.pdf.
You can al ways f i nd t he l at est ver si on of t he l i br ar y at http://electronics.henningkarlsen.com/
I f you make any modi f i cat i ons or i mpr ovement s t o t he code, I woul d appr eci at e t hat you shar e t he code wi t h me so t hat I mi ght i ncl ude i t i n t he next r el ease. I can be cont act ed t hr ough http://electronics.henningkarlsen.com/contact.php.
For ver si on i nf or mat i on, pl ease r ef er t o version.txt.
IMPORTANT: When usi ng 8bi t and 16bi t di spl ay modul es t her e ar e some r equi r ement s you must adher e t o. These r equi r ement s can be f ound i n t he document UTFT_Requirements.pdf. Ther e ar e no speci al r equi r ement s when usi ng ser i al di spl ays.
Si nce most peopl e have onl y one or possi bl y t wo di f f er ent di spl ay modul es a l ot of memor y has been wast ed t o keep suppor t f or many unneeded cont r ol l er chi ps. As of v1. 1 you now have t he opt i on t o easi l y r emove t hi s unneeded code f r omt he l i br ar y. By di sabl i ng t he cont r ol l er s you don' t need you can r educe t he memor y f oot pr i nt of t he l i br ar y by sever al Kb. For mor e i nf or mat i on, pl ease r ef er t o memorysaver.h.
I f you ar e usi ng t he AquaLEDSource All in One Super Screw Shield on a chi pKi t Max32, pl ease r ead t he comment i n hardware/pic32/HW_PIC32_defines.h
I f you ar e usi ng t he CTE TFT LCD/SD Shield for Arduino Due or t he ElecHouse TFT LCD Screen Shield for Arduino DUE /Taijiuino, pl ease r ead t he comment i n hardware/arm/HW_ARM_defines.h
8 bi t di spl ay shi el ds desi gned f or use on Ar dui no Uno ( and si mi l ar l y si zed boar ds) can now be used on Ar dui no Megas. Pl ease r ead t he comment i n hardware/avr/HW_AVR_defines.h
The 7 di spl ay modul es have not been t est ed on t he chi pKi t boar ds due t o t he hi gh cur r ent r equi r ement f or t he LED backl i ght .
Thi s l i br ar y i s l i censed under a CC BY-NC-SA 3.0 ( Cr eat i ve Commons At t r i but i on- NonCommer ci al - Shar eAl i ke 3. 0 Unpor t ed) Li cense.
For mor e i nf or mat i on see: http://creativecommons.org/licenses/by-nc-sa/3.0/
UTFT l i br ar y Page 2
DEFINED LITERALS:
Alignment For use with print(), printNumI() and printNumF()
LEFT: RI GHT: CENTER: 0 9999 9998
Orientation For use with InitLCD()
PORTRAI T: LANDSCAPE: 0 1
VGA Colors Predefined colors for use with setColor() and setBackColor()
VGA_BLACK VGA_SI LVER VGA_GRAY VGA_WHI TE VGA_MAROON VGA_RED VGA_PURPLE VGA_FUCHSI A VGA_GREEN VGA_LI ME VGA_OLI VE VGA_YELLOW VGA_NAVY VGA_BLUE VGA_TEAL VGA_AQUA VGA_TRANSPARENT ( onl y val i d f or set BackCol or ( ) )
Display model For use with UTFT()
Pl ease see UTFT_Supported_display_modules_&_controllers.pdf
INCLUDED FONTS:
SmallFont
Char act er si ze: Number of char act er s: 8x12 pi xel s 95
BigFont
Char act er si ze: Number of char act er s: 16x16 pi xel s 95
SevenSegNumFont
Char act er si ze: Number of char act er s: 32x50 pi xel s 10
UTFT l i br ar y Page 3 FUNCTIONS:
UTFT(Model, RS, WR, CS, RST[, ALE]); The main class constructor when using 8bit or 16bit display modules.
Parameters: Model : See t he separ at e document f or t he suppor t ed di spl ay modul es RS: Pi n f or Regi st er Sel ect WR: Pi n f or Wr i t e CS: Pi n f or Chi p Sel ect RST: Pi n f or Reset ALE: <optional> Onl y used f or l at ched 16bi t shi el ds Pi n f or Lat ch si gnal
Usage: UTFT myGLCD( I TDB32S, 19, 18, 17, 16) ; / / St ar t an i nst ance of t he UTFT cl ass
UTFT(Model, SDA, SCL, CS, RST[, RS]); The main class constructor when using serial display modules.
Parameters: Model : See t he separ at e document f or t he suppor t ed di spl ay modul es SDA: Pi n f or Ser i al Dat a SCL: Pi n f or Ser i al Cl ock CS: Pi n f or Chi p Sel ect RST: Pi n f or Reset RS: <optional> Onl y used f or 5pi n ser i al modul es Pi n f or Regi st er Sel ect
Usage: UTFT myGLCD( I TDB18SP, 11, 10, 9, 12, 8) ; / / St ar t an i nst ance of t he UTFT cl ass
InitLCD([orientation]); Initialize the LCD and set display orientation.
Parameters: Or i ent at i on: <optional> PORTRAI T LANDSCAPE (default) Usage: myGLCD. i ni t LCD( ) ; / / I ni t i al i ze t he di spl ay Notes: Thi s wi l l r eset col or t o whi t e wi t h bl ack backgr ound. Sel ect ed f ont wi l l be r eset t o none.
getDisplayXSize(); Get the width of the screen in the current orientation.
Parameters: None Returns: Wi dt h of t he scr een i n t he cur r ent or i ent at i on i n pi xel s Usage: Xsi ze = myGLCD. get Di spl ayXSi ze( ) ; / / Get t he wi dt h
getDisplayYSize(); Get the height of the screen in the current orientation.
Parameters: None Returns: Hei ght of t he scr een i n t he cur r ent or i ent at i on i n pi xel s Usage: Ysi ze = myGLCD. get Di spl ayYSi ze( ) ; / / Get t he hei ght
UTFT l i br ar y Page 4 lcdOff(); Turn off the LCD. No commands will be executed until a lcdOn(); is sent.
Parameters: None Usage: myGLCD. l cdOf f ( ) ; / / Tur n of f t he l cd Notes: Thi s f unct i on i s cur r ent l y onl y suppor t ed on PCF8833 and CPLD- based di spl ays. CPLD- based di spl ays wi l l onl y t ur n of f t he backl i ght . I t wi l l accept f ur t her commands/ wr i t es.
lcdOn(); Turn on the LCD after issuing a lcdOff()-command.
Parameters: None Usage: myGLCD. l cdOn( ) ; / / Tur n on t he l cd Notes: Thi s f unct i on i s cur r ent l y onl y suppor t ed on PCF8833 and CPLD- based di spl ays. CPLD- based di spl ays wi l l onl y t ur n on t he backl i ght .
setContrast(c); Set the contrast of the display.
Parameters: c: Cont r ast - l evel ( 0- 64) Usage: myGLCD. set Cont r ast ( 64) ; / / Set cont r ast t o f ul l ( def aul t ) Notes: Thi s f unct i on i s cur r ent l y onl y suppor t ed on PCF8833- based di spl ays
setBrightness(br); Set the brightness of the display backlight.
Parameters: br : Br i ght ness- l evel ( 0- 16) Usage: myGLCD. set Br i ght ness( 16) ; / / Set br i ght ness t o maxi mum( def aul t ) Notes: Thi s f unct i on i s cur r ent l y onl y suppor t ed on CPLD- based di spl ays
setDisplayPage(pg); Set which memory page to display.
Parameters: pg: Page ( 0- 7) ( 0 i s def aul t ) Usage: myGLCD. set Di spl ayPage( 4) ; / / Di spl ay page 4 Notes: Thi s f unct i on i s cur r ent l y onl y suppor t ed on CPLD- based di spl ays
setWritePage(pg); Set which memory page to use for subsequent display writes.
Parameters: pg: Page ( 0- 7) ( 0 i s def aul t ) Usage: myGLCD. set Wr i t ePage( 2) ; / / Use page 2 f or subsequent wr i t es Notes: Thi s f unct i on i s cur r ent l y onl y suppor t ed on CPLD- based di spl ays
UTFT l i br ar y Page 5 clrScr(); Clear the screen. The background-color will be set to black.
Parameters: None Usage: myGLCD. cl r Scr ( ) ; / / Cl ear t he scr een
fillScr(r, g, b); Fill the screen with a specified color.
Parameters: r : Red component of an RGB val ue ( 0- 255) g: Gr een component of an RGB val ue ( 0- 255) b: Bl ue component of an RGB val ue ( 0- 255) Usage: myGLCD. f i l l Scr ( 255, 127, 0) ; / / Fi l l t he scr een wi t h or ange
fillScr(color); Fill the screen with a specified pre-calculated RGB565 color.
Parameters: col or : RGB565 col or val ue Usage: myGLCD. f i l l Scr ( VGA_RED) ; / / Fi l l t he scr een wi t h r ed
setColor(r, g, b); Set the color to use for all draw*, fill* and print commands.
Parameters: r : Red component of an RGB val ue ( 0- 255) g: Gr een component of an RGB val ue ( 0- 255) b: Bl ue component of an RGB val ue ( 0- 255) Usage: myGLCD. set Col or ( 0, 255, 255) ; / / Set t he col or t o cyan
setColor(color); Set the specified pre-calculated RGB565 color to use for all draw*, fill* and print commands.
Parameters: col or : RGB565 col or val ue Usage: myGLCD. set Col or ( VGA_AQUA) ; / / Set t he col or t o aqua
getColor(); Get the currently selected color.
Parameters: None Returns: Cur r ent l y sel ect ed col or as a RGB565 val ue ( wor d) Usage: Col or = myGLCD. get Col or ( ) ; / / Get t he cur r ent col or
setBackColor(r, g, b); Set the background color to use for all print commands.
Parameters: r : Red component of an RGB val ue ( 0- 255) g: Gr een component of an RGB val ue ( 0- 255) b: Bl ue component of an RGB val ue ( 0- 255) Usage: myGLCD. set BackCol or ( 255, 255, 255) ; / / Set t he backgr ound col or t o whi t e
setBackColor(color); Set the specified pre-calculated RGB565 background color to use for all print commands.
Parameters: col or : RGB565 col or val ue Usage: myGLCD. set BackCol or ( VGA_LI ME) ; / / Set t he backgr ound col or t o l i me
getBackColor(); Get the currently selected background color.
Parameters: None Returns: Cur r ent l y sel ect ed backgr ound col or as a RGB565 val ue ( wor d) Usage: BackCol or = myGLCD. get BackCol or ( ) ; / / Get t he cur r ent backgr ound col or
UTFT l i br ar y Page 6 drawPixel(x, y); Draw a single pixel.
Parameters: x: x- coor di nat e of t he pi xel y: y- coor di nat e of t he pi xel Usage: myGLCD. dr awPi xel ( 119, 159) ; / / Dr aw a si ngl e pi xel
drawLine(x1, y1, x2, y2); Draw a line between two points.
Parameters: x1: x- coor di nat e of t he st ar t - poi nt y1: y- coor di nat e of t he st ar t - poi nt x2: x- coor di nat e of t he end- poi nt y2: y- coor di nat e of t he end- poi nt Usage: myGLCD. dr awLi ne( 0, 0, 239, 319) ; / / Dr aw a di agonal l i ne
drawRect(x1, y1, x2, y2); Draw a rectangle between two points.
Parameters: x1: x- coor di nat e of t he st ar t - cor ner y1: y- coor di nat e of t he st ar t - cor ner x2: x- coor di nat e of t he end- cor ner y2: y- coor di nat e of t he end- cor ner Usage: myGLCD. dr awRect ( 119, 159, 239, 319) ; / / Dr aw a r ect angl e
drawRoundRect(x1, y1, x2, y2); Draw a rectangle with slightly rounded corners between two points. The minimum size is 5 pixels in both directions. If a smaller size is requested the rectangle will not be drawn.
Parameters: x1: x- coor di nat e of t he st ar t - cor ner y1: y- coor di nat e of t he st ar t - cor ner x2: x- coor di nat e of t he end- cor ner y2: y- coor di nat e of t he end- cor ner Usage: myGLCD. dr awRoundRect ( 0, 0, 119, 159) ; / / Dr aw a r ounded r ect angl e
fillRect(x1, y1, x2, y2); Draw a filled rectangle between two points.
Parameters: x1: x- coor di nat e of t he st ar t - cor ner y1: y- coor di nat e of t he st ar t - cor ner x2: x- coor di nat e of t he end- cor ner y2: y- coor di nat e of t he end- cor ner Usage: myGLCD. f i l l Rect ( 119, 0, 239, 159) ; / / Dr aw a f i l l ed r ect angl e
fillRoundRect(x1, y1, x2, y2); Draw a filled rectangle with slightly rounded corners between two points. The minimum size is 5 pixels in both directions. If a smaller size is requested the rectangle will not be drawn.
Parameters: x1: x- coor di nat e of t he st ar t - cor ner y1: y- coor di nat e of t he st ar t - cor ner x2: x- coor di nat e of t he end- cor ner y2: y- coor di nat e of t he end- cor ner Usage: myGLCD. f i l l RoundRect ( 0, 159, 119, 319) ; / / Dr aw a f i l l ed, r ounded r ect angl e
drawCircle(x, y, radius); Draw a circle with a specified radius.
Parameters: x: x- coor di nat e of t he cent er of t he ci r cl e y: y- coor di nat e of t he cent er of t he ci r cl e r adi us: r adi us of t he ci r cl e i n pi xel s Usage: myGLCD. dr awCi r cl e( 119, 159, 20) ; / / Dr aw a ci r cl e wi t h a r adi us of 20 pi xel s
fillCircle(x, y, radius); Draw a filled circle with a specified radius.
Parameters: x: x- coor di nat e of t he cent er of t he ci r cl e y: y- coor di nat e of t he cent er of t he ci r cl e r adi us: r adi us of t he ci r cl e i n pi xel s Usage: myGLCD. f i l l Ci r cl e( 119, 159, 10) ; / / Dr aw a f i l l ed ci r cl e wi t h a r adi us of 10 pi xel s
UTFT l i br ar y Page 7 print(st, x, y[, deg]); Print a string at the specified coordinates. You can use the literals LEFT, CENTER and RIGHT as the x-coordinate to align the string on the screen.
Parameters: st : t he st r i ng t o pr i nt x: x- coor di nat e of t he upper , l ef t cor ner of t he f i r st char act er y: y- coor di nat e of t he upper , l ef t cor ner of t he f i r st char act er deg: <optional> Degr ees t o r ot at e t ext ( 0- 359) . Text wi l l be r ot at ed ar ound t he upper l ef t cor ner . Usage: myGLCD. pr i nt ( Hel l o, Wor l d! , CENTER, 0) ; / / Pr i nt Hel l o, Wor l d! Notes: CENTER and RI GHT wi l l not cal cul at e t he coor di nat es cor r ect l y when r ot at i ng t ext . The st r i ng can be ei t her a char ar r ay or a St r i ng obj ect
printNumI(num, x, y[, length[, filler]]); Print an integer number at the specified coordinates. You can use the literals LEFT, CENTER and RIGHT as the x-coordinate to align the string on the screen.
Parameters: num: t he val ue t o pr i nt ( - 2, 147, 483, 648 t o 2, 147, 483, 647) INTEGERS ONLY x: x- coor di nat e of t he upper , l ef t cor ner of t he f i r st di gi t / si gn y: y- coor di nat e of t he upper , l ef t cor ner of t he f i r st di gi t / si gn l engt h: <optional> mi ni mumnumber of di gi t s/ char act er s ( i ncl udi ng si gn) t o di spl ay f i l l er : <optional> f i l l er char act er t o use t o get t he mi ni muml engt h. The char act er wi l l be i nser t ed i n f r ont of t he number , but af t er t he si gn. Def aul t i s ' ' ( space) . Usage: myGLCD. pr i nt NumI ( num, CENTER, 0) ; / / Pr i nt t he val ue of num
printNumF(num, dec, x, y[, divider[, length[, filler]]]); Print a floating-point number at the specified coordinates. You can use the literals LEFT, CENTER and RIGHT as the x-coordinate to align the string on the screen. WARNING: Floating point numbers are not exact, and may yield strange results when compared. Use at your own discretion.
Parameters: num: t he val ue t o pr i nt ( See note) dec: di gi t s i n t he f r act i onal par t ( 1- 5) 0 is not supported. Use printNumI() instead. x: x- coor di nat e of t he upper , l ef t cor ner of t he f i r st di gi t / si gn y: y- coor di nat e of t he upper , l ef t cor ner of t he f i r st di gi t / si gn di vi der : <Optional> Si ngl e char act er t o use as deci mal poi nt . Def aul t i s ' . ' l engt h: <optional> mi ni mumnumber of di gi t s/ char act er s ( i ncl udi ng si gn) t o di spl ay f i l l er : <optional> f i l l er char act er t o use t o get t he mi ni muml engt h. The char act er wi l l be i nser t ed i n f r ont of t he number , but af t er t he si gn. Def aul t i s ' ' ( space) . Usage: myGLCD. pr i nt NumF( num, 3, CENTER, 0) ; / / Pr i nt t he val ue of num wi t h 3 f r act i onal di gi t s Notes: Suppor t ed r ange depends on t he number of f r act i onal di gi t s used. Appr ox r ange i s +/ - 2*( 10^( 9- dec) )
setFont(fontname); Select font to use with print(), printNumI() and printNumF().
Parameters: f ont name: Name of t he ar r ay cont ai ni ng t he f ont you wi sh t o use Usage: myGLCD. set Font ( Bi gFont ) ; / / Sel ect t he f ont cal l ed Bi gFont Notes: You must decl ar e t he f ont - ar r ay as an ext er nal or i ncl ude i t i n your sket ch.
getFont(); Get the currently selected font.
Parameters: None Returns: Cur r ent l y sel ect ed f ont Usage: Cur r ent Font = myGLCD. get Font ( ) ; / / Get t he cur r ent f ont
getFontXsize(); Get the width of the currently selected font.
Parameters: None Returns: Wi dt h of t he cur r ent l y sel ect ed f ont i n pi xel s Usage: Xsi ze = myGLCD. get Font Xsi ze ( ) ; / / Get f ont wi dt h
getFontYsize(); Get the height of the currently selected font.
Parameters: None Returns: Hei ght of t he cur r ent l y sel ect ed f ont i n pi xel s Usage: Ysi ze = myGLCD. get Font Ysi ze ( ) ; / / Get f ont hei ght
UTFT l i br ar y Page 8 drawBitmap (x, y, sx, sy, data[, scale]); Draw a bitmap on the screen.
Parameters: x: x- coor di nat e of t he upper , l ef t cor ner of t he bi t map y: y- coor di nat e of t he upper , l ef t cor ner of t he bi t map sx: wi dt h of t he bi t map i n pi xel s sy: hei ght of t he bi t map i n pi xel s dat a: ar r ay cont ai ni ng t he bi t map- dat a scal e: <optional> Scal i ng f act or . Each pi xel i n t he bi t map wi l l be dr awn as <scal e>x<scal e> pi xel s on scr een. Usage: myGLCD. dr awBi t map( 0, 0, 32, 32, bi t map) ; / / Dr aw a 32x32 pi xel bi t map Notes: You can use t he onl i ne- t ool ImageConverter 565 or ImageConverter565.exe i n t he Tool s- f ol der t o conver t pi ct ur es i nt o compat i bl e ar r ays. The onl i ne- t ool can be f ound on my websi t e. Requi r es t hat you #include <avr/pgmspace.h> when usi ng an Ar dui no ot her t han Ar dui no Due.
drawBitmap (x, y, sx, sy, data, deg, rox, roy); Draw a bitmap on the screen with rotation.
Parameters: x: x- coor di nat e of t he upper , l ef t cor ner of t he bi t map y: y- coor di nat e of t he upper , l ef t cor ner of t he bi t map sx: wi dt h of t he bi t map i n pi xel s sy: hei ght of t he bi t map i n pi xel s dat a: ar r ay cont ai ni ng t he bi t map- dat a deg: Degr ees t o r ot at e bi t map ( 0- 359) r ox: x- coor di nat e of t he pi xel t o use as r ot at i onal cent er r el at i ve t o bi t maps upper l ef t cor ner r oy: y- coor di nat e of t he pi xel t o use as r ot at i onal cent er r el at i ve t o bi t maps upper l ef t cor ner Usage: myGLCD. dr awBi t map( 50, 50, 32, 32, bi t map, 45, 16, 16) ; / / Dr aw a bi t map r ot at ed 45 degr ees ar ound i t s cent er Notes: You can use t he onl i ne- t ool ImageConverter 565 or ImageConverter565.exe i n t he Tool s- f ol der t o conver t pi ct ur es i nt o compat i bl e ar r ays. The onl i ne- t ool can be f ound on my websi t e. Requi r es t hat you #include <avr/pgmspace.h> when usi ng an Ar dui no ot her t han Ar dui no Due.