Adafruit ILI9341 TFT Library
Graphics Test
by lady ada
We have a library with example code ready to go for use with these TFTs. The library is not incredibly fast and optimized but its a good start and can easily be ported to other micrcontrollers. However, we'll assume you're using an Arduino.
Our github repository contains all the code and examples you'll need for driving the TFT.
Our github repository contains all the code and examples you'll need for driving the TFT.
Install Libraries
You'll need a few libraries to use this display
From within the Arduino IDE, open up the Library Manager...
Install Adafruit ILI9341 TFT Library
We have example code ready to go for use with these TFTs.
Two libraries need to be downloaded and installed: first is the Adafruit ILI9341 library (this contains the low-level code specific to this device), and second is the Adafruit GFX Library (which handles graphics operations common to many displays we carry). If you have Adafruit_GFXalready, make sure its the most recent version since we've made updates for better performance
Two libraries need to be downloaded and installed: first is the Adafruit ILI9341 library (this contains the low-level code specific to this device), and second is the Adafruit GFX Library (which handles graphics operations common to many displays we carry). If you have Adafruit_GFXalready, make sure its the most recent version since we've made updates for better performance
Search for ILI9341 and install the Adafruit ILI9341 library that pops up!
For more details, especially for first-time library installers, check out our great tutorial at http://learn.adafruit.com/adafruit-all-about-arduino-libraries-install-use
Next up, search for Adafruit GFX and locate the core library. A lot of libraries may pop up because we reference it in the description so just make sure you see Adafruit GFX Library in bold at the top.
Install it!
Repeat this process one more time, looking for the Adafruit_ZeroDMA library. Install that one too.
Restart the Arduino software. You should see a new example folder called Adafruit_ILI9341 and inside, an example called graphicstest. Upload that sketch to your Arduino! You should see a collection of graphical tests draw out on the TFT.
Resistive Touchscreen Paint Demo
This page is for the Resistive Touch Screen version of the Shield!
The LCD has a 2.8" 4-wire resistive touch screen glued onto it. You can use this for detecting finger-presses, stylus', etc. Normally, you'll need 4 pins to talk to the touch panel but we decided to go all snazzy and put a dedicated touch screen driver onto the shield. The driver shares the SPI pins with the TFT and SD card, so only one extra pin is needed (digital #8) This allows you to query the controller when you're ready to read touchscreen data, and saves 3 pins.
To control the touchscreen you'll need one more library - the STMPE610 controller library which does all the low level chatting with the STMPE610 driver chip.
To control the touchscreen you'll need one more library - the STMPE610 controller library which does all the low level chatting with the STMPE610 driver chip.
Once you have the library installed, restart the IDE. Now from the examples->Adafruit_ILI9341menu select touchpaint and upload it to your Arduino.
The touch screen is made of a thin glass sheet, and its very fragile - a small crack or break will make the entire touch screen unusable. Don't drop or roughly handle the TFT and be especially careful of the corners and edges. When pressing on the touchscreen, sometimes people can use the tip of their fingers, or a fingernail. If you don't find the touchscreen responds well to your fingers, you can use a rounded stylus which will certainly work. Do not press harder and harder until the screen cracks!
Getting data from the touchscreen is fairly straight forward. Start by creating the touchscreen object with
Then you can start the touchscreen with
Now you can call
Since data from the STMPE610 comes in 0-4095 but our screen is 320 pixels by 240 pixels, we can use map to convert 0-4095 to 0-320 or 0-240. Something like
One last point (pun intended!) since the touchscreen driver stores points in a buffer, you may want to ask the driver "is the touchscreen being pressed RIGHT NOW?" You can do that with
To get the touch point from the controller. TS_Point has .x and .y data points. The x and y points range from 0 to 240 and 0 to 320 respectively. This corresponds to each pixel on the display. The FT6206 does not need to be 'calibrated' but it also doesn't know about rotation. So if you want to rotate the
screen you'll need to manually rotate the x/y points!
On the resistive TFT touch shield
Solder the jumper labeled Pin 3. Then you can use Digital 3 to control the backlight.
On the capacitive TFT touch shield
Solder the jumper labeled Pin 5. Then you can use Digital 5 to control the backlight.
Advanced users may want to get an interrupt on a pin (or even, just test a pin rather than do a full SPI query) when the touchscreen is pressed. You can do that by jumpering the #7 solder jumper labeled TS int. We didn't want it to connect to #2 or #3 since those are the Leonardo I2C pins.You can use pin change interrupts to get an interrupt callback on #7. Or, with a little blue wire, advanced users can connect a wire from the TS interrupt pad to any pin they choose. We find that querying/polling the chip is fast enough for most beginner Arduino projects!
Adafruit_STMPE610 ts = Adafruit_STMPE610(STMPE_CS);We're using hardware SPI so the clock, mosi and miso pins are not defined here. For the shield, CS is #8 always.
Then you can start the touchscreen with
ts.begin()Check to make sure this returns a True value, which means the driver was found. If it wasn't, make sure you have the hardware SPI jumpers set up right: for Leonardo/Mega the ICSP jumpers get closed.
Now you can call
if (! ts.bufferEmpty())to check if there's any data in the buffer. The touchscreen driver will store touchpoints at all times. When you're ready to get the data, just check if there's any data in the buffer. If there is, you can call
TS_Point p = ts.getPoint();To get the oldest point from the buffer. TS_Point has .x .y and .z data points. The x and y points range from 0 to 4095. The STMPE610 does not store any calibration data in it and it doesn't know about rotation. So if you want to rotate the screen you'll need to manually rotate the x/y points!The z point is 'pressure' and ranges from 0 to 255, we don't use it here but you can experiment with it on your own, the harder you press, the lower the number.
Since data from the STMPE610 comes in 0-4095 but our screen is 320 pixels by 240 pixels, we can use map to convert 0-4095 to 0-320 or 0-240. Something like
p.x = map(p.x, 0, 4095, 0, tft.width());However, the touchscreen is a bit bigger than the screen, so we actually need to ignore presses beyond the touchscreen itself. We found that these numbers reflected the true range that overlaps the screen
p.y = map(p.y, 0, 4095, 0, tft.height());
#define TS_MINX 150So we use
#define TS_MINY 130
#define TS_MAXX 3800
#define TS_MAXY 4000
p.x = map(p.x, TS_MINX, TS_MAXX, 0, tft.width());instead.
p.y = map(p.y, TS_MINY, TS_MAXY, 0, tft.height());
One last point (pun intended!) since the touchscreen driver stores points in a buffer, you may want to ask the driver "is the touchscreen being pressed RIGHT NOW?" You can do that with
if (ts.touched())
Capacitive Touchscreen Paint Demo
This page is for the Capacitive Touch Screen version of the Shield!
We now have a super-fancy capacitive touch screen version of this shield. Instead of a resistive controller that needs calibration and pressing down, the capacitive has a hard glass cover and can be used with a gentle fingertip. It is a single-touch capacitive screen only!
The capacitive touch screen controller communicates over I2C, which uses two hardwire pins. However, you can share these pins with other sensors and displays as long as they don't conflict with I2C address 0x38.
The capacitive touch screen controller communicates over I2C, which uses two hardwire pins. However, you can share these pins with other sensors and displays as long as they don't conflict with I2C address 0x38.
Download the FT6206 Library
To control the touchscreen you'll need one more library - the FT6206 controller library which does all the low level chatting with the FT6206 driver chip. Use the library manager and search for FT6206 and select the Adafruit FT6206 library:
Once you have the library installed, restart the IDE. Now from the examples->Adafruit_FT6206menu select CapTouchPaint and upload it to your Arduino.
The touch screen is made of a thin glass sheet, and its very fragile - a small crack or break will make the entire touch screen unusable. Don't drop or roughly handle the TFT and be especially careful of the corners and edges. When pressing on the touchscreen, remember you cannot use a fingernail, it must be a fingerpad. Do not press harder and harder until the screen cracks!
Getting data from the touchscreen is fairly straight forward. Start by creating the touchscreen object with
Then you can start the touchscreen with
Now you can call
Adafruit_FT6206 ts = Adafruit_FT6206();We're using hardware I2C which is fixed in hardware so no pins are defined.
Then you can start the touchscreen with
ts.begin()Check to make sure this returns a True value, which means the driver was found. You can also call begin(threshvalue) wish a number from 0-255 to set the touch threshhold. The default works pretty well but if you're having too much sensitivity (or not enought) you can try tweaking it
Now you can call
if (ts.touched())to check if the display is being touched, if so call:
TS_Point p = ts.getPoint();
Using Fonts
More recent versions of the Adafruit GFX library offer the ability to use alternate fonts besides the one standard fixed-size and -spaced face that’s built in. Several alternate fonts are included, plus there’s the ability to add new ones.
|
|
The included fonts are derived from the GNU FreeFont project. There are three faces: “Serif” (reminiscent of Times New Roman), “Sans” (reminiscent of Helvetica or Arial) and “Mono” (reminiscent of Courier). Each is available in a few styles (bold, italic, etc.) and sizes. The included fonts are in a bitmap format, not scalable vectors, as it needs to work within the limitations of a small microcontroller.
|
Located inside the “Fonts” folder inside Adafruit_GFX, the included files (as of this writing) are:
Download: file
- FreeMono12pt7b.h FreeSansBoldOblique12pt7b.h
- FreeMono18pt7b.h FreeSansBoldOblique18pt7b.h
- FreeMono24pt7b.h FreeSansBoldOblique24pt7b.h
- FreeMono9pt7b.h FreeSansBoldOblique9pt7b.h
- FreeMonoBold12pt7b.h FreeSansOblique12pt7b.h
- FreeMonoBold18pt7b.h FreeSansOblique18pt7b.h
- FreeMonoBold24pt7b.h FreeSansOblique24pt7b.h
- FreeMonoBold9pt7b.h FreeSansOblique9pt7b.h
- FreeMonoBoldOblique12pt7b.h FreeSerif12pt7b.h
- FreeMonoBoldOblique18pt7b.h FreeSerif18pt7b.h
- FreeMonoBoldOblique24pt7b.h FreeSerif24pt7b.h
- FreeMonoBoldOblique9pt7b.h FreeSerif9pt7b.h
- FreeMonoOblique12pt7b.h FreeSerifBold12pt7b.h
- FreeMonoOblique18pt7b.h FreeSerifBold18pt7b.h
- FreeMonoOblique24pt7b.h FreeSerifBold24pt7b.h
- FreeMonoOblique9pt7b.h FreeSerifBold9pt7b.h
- FreeSans12pt7b.h FreeSerifBoldItalic12pt7b.h
- FreeSans18pt7b.h FreeSerifBoldItalic18pt7b.h
- FreeSans24pt7b.h FreeSerifBoldItalic24pt7b.h
- FreeSans9pt7b.h FreeSerifBoldItalic9pt7b.h
- FreeSansBold12pt7b.h FreeSerifItalic12pt7b.h
- FreeSansBold18pt7b.h FreeSerifItalic18pt7b.h
- FreeSansBold24pt7b.h FreeSerifItalic24pt7b.h
- FreeSansBold9pt7b.h FreeSerifItalic9pt7b.h
Each filename starts with the face name (“FreeMono”, “FreeSerif”, etc.) followed by the style (“Bold”, “Oblique”, none, etc.), font size in points (currently 9, 12, 18 and 24 point sizes are provided) and “7b” to indicate that these contain 7-bit characters (ASCII codes “ ” through “~”); 8-bit fonts (supporting symbols and/or international characters) are not yet provided but may come later.
Using GFX Fonts in Arduino Sketches
After #including the Adafruit_GFX and display-specific libraries, include the font file(s) you plan to use in your sketch. For example:
Download: file
- #include <Adafruit_GFX.h> // Core graphics library
- #include <Adafruit_TFTLCD.h> // Hardware-specific library
- #include <Fonts/FreeMonoBoldOblique12pt7b.h>
- #include <Fonts/FreeSerif9pt7b.h>
Each font takes up a bit of program space; larger fonts typically require more room. This is a finite resource (about 32K max on an Arduino Uno for font data and all of your sketch code), so choose carefully. Too big and the code will refuse to compile (or in some edge cases, may compile but then won’t upload to the board). If this happens, use fewer or smaller fonts, or use the standard built-in font.
Inside these .h files are several data structures, including one main font structure which will usually have the same name as the font file (minus the .h). To select a font for subsequent graphics operations, use the setFont() function, passing the address of this structure, such as:
Download: file
- tft.setFont(&FreeMonoBoldOblique12pt7b);
Subsequent calls to tft.print() will now use this font. Most other attributes that previously worked with the built-in font (color, size, etc.) work similarly here.
To return to the standard fixed-size font, call setFont(), passing either NULL or no arguments:
Download: file
- tft.setFont();
Some text attributes behave a little differently with these new fonts. Not wanting to break compatibility with existing code, the “classic” font continues to behave as before.
For example, whereas the cursor position when printing with the classic font identified the top-left corner of the character cell, with new fonts the cursor position indicates the baseline — the bottom-most row — of subsequent text. Characters may vary in size and width, and don’t necessarily begin at the exact cursor column (as in below, this character starts one pixel left of the cursor, but others may be on or to the right of it).
When switching between built-in and custom fonts, the library will automatically shift the cursor position up or down 6 pixels as needed to continue along the same baseline.
One “gotcha” to be aware of with new fonts: there is no “background” color option…you can set this value but it will be ignored. This is on purpose and by design.
The background color feature has typically been used with the “classic” font to overwrite old screen contents with new data. This only works because those characters are a uniform size; it’s not a sensible thing to do with proportionally-spaced fonts with characters of varying sizes (and which may overlap).
To replace previously-drawn test when using a custom font, use the getTextBounds() function to determine the smallest rectangle encompassing a string, erase the area using fillRect(), then draw new text.
Download: file
- int16_t x1, y1;
- uint16_t w, h;
- tft.getTextBounds(string, x, y, &x1, &y1, &w, &h);
getTextBounds expects a string, a starting cursor X&Y position (the current cursor position will not be altered), and addresses of two signed and two unsigned 16-bit integers. These last four values will then contain the upper-left corner and the width & height of the area covered by this text — these can then be passed directly as arguments to fillRect().
This will unfortunately “blink” the text when erasing and redrawing, but is unavoidable. The old scheme of drawing background pixels in the same pass only creates a new set of problems.
Adding New Fonts
If you want to create new font sizes not included with the library, or adapt entirely new fonts, we have a command-line tool (in the “fontconvert” folder) for this. It should work on many Linux- or UNIX-like systems (Raspberry Pi, Mac OS X, maybe Cygwin for Windows, among others).
Building this tool requires the gcc compiler and FreeType library. Most Linux distributions include both by default. For others, you may need to install developer tools and download and build FreeType from the source. Then edit the Makefile to match your setup before invoking “make”.
fontconvert expects at least two arguments: a font filename (such as a scalable TrueType vector font) and a size, in points (72 points = 1 inch; the code presumes a screen resolution similar to the Adafruit 2.8" TFT displays). The output should be redirected to a .h file…you can call this whatever you like but I try to be somewhat descriptive:
Download: file
- ./fontconvert myfont.ttf 12 > myfont12pt7b.h
The GNU FreeFont files are not included in the library repository but are easily downloaded. Or you can convert most any font you like.
The name assigned to the font structure within this file is based on the input filename and font size, not the output. This is why I recommend using descriptive filenames incorporating the font base name, size, and "7p". Then the .h filename and font structure name can match.
The resulting .h file can be copied to the Adafruit_GFX/Fonts folder, or you can import the file as a new tab in your Arduino sketch using the Sketch→Add File… command.
If in the Fonts folder, use this syntax when #including the file:
Download: file
- #include <Fonts/myfont12pt7b.h>
If a tab within your sketch, use this syntax:
Download: file
- #include "myfont12pt7b.h"
Drawing Bitmaps
There is a built in microSD card slot into the shield, and we can use that to load bitmap images! You will need a microSD card formatted FAT16 or FAT32 (they almost always are by default).
Its really easy to draw bitmaps. We have a library for it, Adafruit_ImageReader, which can be installed through the Arduino Library Manager (Sketch→Include Library→Manage Libraries…). Enter “imageread” in the search field and the library is easy to spot:
Its really easy to draw bitmaps. We have a library for it, Adafruit_ImageReader, which can be installed through the Arduino Library Manager (Sketch→Include Library→Manage Libraries…). Enter “imageread” in the search field and the library is easy to spot:
With the library installed, let’s proceed by downloading this image of pretty flowers (pix by johngineer):
Copy purple.bmp into the base directory of a microSD card and insert it into the microSD socket in the shield. Now upload the File→Examples→Adafruit_ImageReader→ShieldILI9341 example sketch to your Arduino + shield. You will see the flowers appear!
To make new bitmaps, make sure they are less than 240 by 320 pixels and save them in 24-bit BMP format! They must be in 24-bit format, even if they are not 24-bit color as that is the easiest format for the Arduino to decode. You can rotate images using the setRotation() procedure.
The ShieldILI9341 example sketch shows everything you need to work with BMP images. Here’s just the vital bits broken out…
Several header files are included at the top of the sketch. All of these are required…they let us access the SD card and the display, and provide the image-reading functions:
- #include <SPI.h>
- #include <SD.h>
- #include <Adafruit_GFX.h> // Core graphics library
- #include <Adafruit_ILI9341.h> // Hardware-specific library
- #include <Adafruit_ImageReader.h> // Image-reading functions
Several #defines relate to hardware pin numbers, all fixed values when using the shield.
Then we declare the tft screen object, and the image-reader object like so:
- #define SD_CS 4 // SD card select pin
- #define TFT_CS 10 // TFT select pin
- #define TFT_DC 9 // TFT display/command pin
- Adafruit_ILI9341 tft = Adafruit_ILI9341(TFT_CS, TFT_DC);
- Adafruit_ImageReader reader; // Class w/image-reading functions
After the SD and TFT’s
begin() functions have been called (see the example sketch again, in the setup() function), you can then call reader.drawBMP() to load an image from the card to the screen:
- ImageReturnCode stat;
- stat = reader.drawBMP("/purple.bmp", tft, 0, 0);
You can draw as many images as you want — though remember the names must be less than 8 characters long. Call like so:
- reader.drawBMP(filename, tft, x, y);
'x' and 'y' are pixel coordinates where top-left corner of the image will be placed. Images can be placed anywhere on screen…even partially off screen, the library will clip the section to load.
Image loading is explained in greater depth in the Adafruit_GFX library guide.
Backlight & Touch IRQ
Both the resistive and capacitive versions of this shield have the ability to dim the backlight and get an interrupt from the resistive or capacitive touch controller chip on-board.
Controlling the Backlight
By default, we assume you'll want the backlight on all the time. However, you may want to PWM control or otherwise turn off the LED backlight to save power. You can do this with a simple hack. On the back, look for the backlight jumper.On the resistive TFT touch shield
Solder the jumper labeled Pin 3. Then you can use Digital 3 to control the backlight.
On the capacitive TFT touch shield
Solder the jumper labeled Pin 5. Then you can use Digital 5 to control the backlight.
Touchscreen Interrupt pin
Advanced users may want to get an interrupt on a pin (or even, just test a pin rather than do a full SPI query) when the touchscreen is pressed. You can do that by jumpering the #7 solder jumper labeled TS int. We didn't want it to connect to #2 or #3 since those are the Leonardo I2C pins.You can use pin change interrupts to get an interrupt callback on #7. Or, with a little blue wire, advanced users can connect a wire from the TS interrupt pad to any pin they choose. We find that querying/polling the chip is fast enough for most beginner Arduino projects!
Downloads
Datasheets & Files
Diagram showing the TFT (yellow outline) underlying Arduino mounting holes (thin white line), PCP outline (rectangular thin white line) and 'visible portion' of the TFT (dashed inner line)
Schematic of the v2 Capacitive touchscreen
Arquitecto especialista en gestion de proyectos si necesitas desarrollar algun proyecto en Bogota contactame en el 3006825874 o visita mi pagina en www.arquitectobogota.tk
0 comentarios:
Publicar un comentario