BluBerriSix A TFT TouchScreen Arduino Tutorial
BluBerriSix A TFT TouchScreen Arduino Tutorial
by hausofpayne17
2019 is the 20th anniversary of the RIM Blackberry on the touch events. This screen is very similar to
850! This little Canadian invention changed the way Adafruit and other TFT shields/screens. So if you're
the world communicates. It's long gone, but its legacy here, stick around for the show.
continues!
We'll build a simplified 2 app version of my
In this instructable, you'll learn how to use the bluBerriSIX sketch.
MCUfriend.com 2.4" TFT display shield for the
Uno/Mega. You'll learn how to display graphic Let's get started!
objects and text and how to receive touches and act
A texting app using HC-12. TFT display and touch sensing concepts.
https://www.youtube.com/watch?v=OYfai-0g7ck
- An MCUfriend 2.4" TFT shield These libraries can be installed with the Library
Manager inside the Arduino IDE.
The following libraries:
To load a library, go to the Sketch -> Include Library -
- Adafruit_GFX library > Manage Libraries... menu option.
- Adafruit Touchscreen library In the 'filter your search...' field, enter the first few
characters of the libary's name and then select and fried it. I spent two weeks of growing frustration trying
install the appropriate library. When done, just back to find correct libraries before realizing that the screen
your way out of this screen. was dead. BE CAREFUL!
We'll build a simpler version of the bluBerriSIX You'll also be able to return to the main menu by
sketch. pressing the 'Home' icon in the lower left of this
particular display. If you don't have such an icon,
It'll have, you'll just have to define a 'home' region of your
screen. You'll learn how to determine screen touch
- a splash screen regions in this tutorial.
- a main menu screen with two buttons Although this is a simplified project, it's still rather
long. I'll provide versions of the Arduino sketches at
- a Saucy 7 app each major stage so you can upload them if you wish.
The whole project is highly documented. But the this when we get to that section of the sketch.
details follow.
funcX[], funcY[] and func[] are arrays that work to
Start a fresh Arduino project and call it 'tft demo' or determine which app button was pressed on the main
any other name you'd like. menu screen and then use that information to launch
the respective app.
The first code panel above shows us defining global
variables. We also add in the libraries we'll need to lastTouch and tThresh are used in the touch
use for both the display function of the screen and the methods to make sure we don't get multiple touches
touch detection of the screen. from pressing the screen too long. More on that later.
We also define the Analog Pins with reference to their The mode variable will control which screen is
screen-specific purposes. displayed and the tMode variable will control which
touch methods are being used at any given time.
We define the tft object (display) and the ts object
(touch) as references for their respective functions. In the setup() block, we open a Serial channel should
we want to use Serial.println() commands for
We define some 16 bit colour constants to make it debugging. You don't need this line should you not
easy to render the colours for the screen and for text wish to do Serial Monitor debugging.
and graphics objects. You'll notice there is a URL to a
website that has a Colour Picker and converter to The next four lines are just setup code for the tft
convert visible colours to their 16 bit hexadecimal object.
values. It's a very helpful tool.
Next we set the orientation of the screen to Portrait
In the second code panel, we define the global mode.
variables for our app-specific purposes.
The randomSeed() command just starts the random
The cString, letter and letterX and letterY strings number generator for later use by the Saucy 7 app.
and arrays are used to a) display the letters on the
buttons for the text entry app and b) match the x and Finally we call the splash screen method.
y coordinates of a touch with the x and y coordinates
of each respective letter on the keyboard. More about
We'll now start building the spash screen. large basic text size. We set the x and y position for
the text cursor and we set the text colour. Finally the
But first, please look at the picture for screen and print("TFT") command actually draws the blue, size
touch mapping. Notice that the origins are in different '5' text at the specified position.
locations. For display, the origin (0,0) is in the top left
of the screen (when the RESET button is on top) and As you increase text size, you'll see that the
grows from left to right and from top to bottom. characters get more and more chunky. So going
above 5 is probably not helpful. At the end of this
For touch detection, the origin is in the lower left tutorial, I'll show you how to use bitmap fonts to
corner of the screen and grows from left to right and get nicer looking text in your apps.The tradeoff is
bottom to top. that using bitmap font sets takes up a lot of
memory in your Arduino which will limit your
So DISPLAY AND TOUCH MAPS ARE DEFINED sketch sizes.
SEPARATELY and have different resolutions. The
display has a resolution of 240 by 320 and the touch We repeat similar commands for the other two text
has a much higher resolution as you'll soon see. items on the splash screen.
Go to an area of your sketch below the loop(){} Finally we delay for 2.5 seconds to give the user a
method and we'll enter the splash() method code. chance to read the screen's contents before the app
moves to the main menu screen.
We start by doing a fillScreen() command to fill the
screen with the WHITE colour we defined in the Go ahead and upload this sketch to your Arduino. It
header code. should display the splash screen.
Download
https://www.instructables.com/ORIG/FFJ/06EQ/JVMNOWU7/FFJ06EQJVMNOWU7.ino
…
The showTouch() method is very useful to help you see if the 'Home' button on the screen was pressed.
get the touch coordinates of different parts of the the '<=' operators allow for the width and height of the
screen. You'll need to do this for defining the touch Home button. The coordinates specified are the x-
regions for your buttons. centre and y-centre coordinates of the Home button.
If it's pressed, mode is set to 0 which will eventually
Go ahead and enter this method below your splash() mean 'Go to Main Menu Screen'. More on that later.
method done previously.
Finally we update lastTouch to the current system
Here's how it works. time millis() to get ready for a later touch event.
The if statement determines if a sufficient time has Please now go the the loop() block and add the line
passed since the last touch. It takes the current showTouch();
system time millis() and subtracts the lastTouch
time. If it's greater than the tThresh value (200 At this point, upload your sketch and try it. It will draw
milliseconds), it accepts the touch. Otherwise, it will the splash screen and if you start touching the
disregard accidental multi-touch events. screen, the TOUCH x and y coordinates will be
displayed on the screen.
Next, the getpoint() command gets the x,y and z
coordinates of the touch. The z coordinate is a Before moving on, let's revisit two important lines of
measure of touch pressure. code:
If the pressure is within the max and min constants pinMode(YP, OUTPUT); //restore the TFT control
we defined in the sketch header, the method will first pins
change the YP and XM pins back to OUTPUT,
putting the screen in DISPLAY mode. pinMode(XM, OUTPUT);// for display after
detecting a touch
Next it will draw a white rectangle to erase any
coordinates that may have been displayed previously. Any time you want to display something on the
screen, you MUST execute these two commands to
The sketch then sets the font to size 2, black colour change the screen from TOUCH mode into DISPLAY
and displays the x (p.x) and y (p.y) coordinates on the mode. Otherwise, your display commands won't
screen. You can then make a note of these locations work.
to help you program your touch zones for your own
sketches. Well done so far! Take a break!
Download
https://www.instructables.com/ORIG/FV9/M1O3/JVMNOWUU/FV9M1O3JVMNOWUU.ino
…
We'll now build our Main Menu screen with two which is the y-offset for drawing the ball. We do this
buttons you can press to activate each app. The so that we can use the same method for drawing the
method is called menuScreen(). ball on the menu screen AND on the Saucy 7 app
screen. The offset just allows us to programatically
We start by putting the screen in DISPLAY mode. adjust the y-coordinate of the ball up or down.
Then we set the font size, colour and position and The draw7Ball(0) method is called from within
print the 'Main Menu' text. draw7Icon(0). It also takes a parameter which allows
us to adjust the vertical position of the ball depending
We now draw two rectangles that are the buttons. on if we drawing it on the menu screen or on the app
screen.
All graphics commands have a similar structure:
The fillCircle() command takes 4 arguments.
graphicShape(x coordinate, y coordinate, width,
height, COLOUR) - x coordinate of the centre of the circle
- x coordinate - top left for rectangular objects, centre - y coordinate of the centre of the circle
for circles
- radius of the circle (in pixels)
- y coordinate - top left for rectangular objects, centre
for circles - COLOUR - a colour constant we defined in the
header
- width - width of the object in pixels
Finally the drawTextIcon() method is called to draw
- COLOUR - a colour constant we defined in the the icon for the Text Entry app.
header
You can try running the method by commenting out
Finally we call two methods to draw the Saucy 7 icon the splash() method in setup() and adding
and the QWERTY Text Entry icon. Those are menuScreen().
separate methods.
Upload the sketch to your Arduino and try it out!
The draw7icon(0) method takes an integer parameter
The sevenScreen() method will draw the screen for If the Home button is pressed, it will end the app and
the app, including drawing the ball and then return to the main menu screen. Otherwise, the
displaying the instructions. method will generate a random number between 0
and 7(exclusive) and pass the corresponding text
The sevenInstr() method displays the instructions as message from the response[] array to the
well as clearing the screen from previous responses. show7Response() method.
It also draws the 'Response' button.
Finally, the backToMenu() method watches for a
The show7Response() method handles clearing the touch of the Home button and returns control to the
previous response method from the screen, main menu screen.
displaying an animated 'thinking...' message and then
displaying the randomly chosen response message. The readMenuTouch() method watches for a touch
event when you're on the main menu screen. When a
read7Touch() is the method that waits for a touch touch is detected, it passes the x and y coordinates to
event to produce the randomly generated message. the getFunc(x,y) method which looks in the funcX[]
The touch code is very similar to the showTouch() and funcY[] arrays to match the x and y coordinates
diagnostic method described earlier. For simplicity, of the touch. It then returns the number from the func[]
the method will accept a touch anywhere on the array for the app that was selected. '1' is Saucy 7 and
screen as the 'Respond' button touch. '2' is the text entry app. It then sets the mode to that
app's value so that the app will be executed.
At the top of the method, we define a response[] array
of strings that are the messages that can be
generated from a touch event.
We'll now start to build the loop() block code to that the display screen doesn't endlessly redraw.
handle displaying the appropriate screen and then
calling the appropriate touch methods based on the The bottom switch structure controls which touch
option currently selected. methods are being executed based on the user-
selected app option as represented by the value of
The loop() method consists of two switch() structures. tMode.
The top switch structure handles displaying the Load the sketch into your Arduino and you should be
appropriate screen depending upon which option is able to select and use the Saucy 7 app.
selected. It also sets the tMode value for the
appropriate touch method to run for the current You've done a lot of work! Take a break :-)
selected option. Finally it sets the mode value to 9 so
Step 10: The Text Entry App - We're in the Home Stretch!
We'll now incorporate the text entry app's methods. letterX[] and letterY[] arrays to trying a find a match
that is close to the x and y coordinates passed from
makeKbd() draws the keyboard on the screen. readKbdTouch(). If it finds a match, it returns the
corresponding letter to the readKbdTouch
It draws six filled rounded rectangles and then method.Notice that we initialize the theChar variable
overlays the appropriate letter on each 'key' by getting to 32 which is the ASCII code for a space character, '
the letter from the cString string which it prints on the '. We do this so that if the user touches an area away
screen over the key. Notice that the second last from the keyboard, it won't display non-available
parameter in a fillRoundedRect() command is the characters.
radius of each corner in pixels. The higher this value,
the more rounded the corners. The displayMsg(theChar) method takes the character
returned from curChar(x,y) and appends it to the msg
The readKbdTouch() method works similar to the string. It then displays the message on the screen.
other touch detection methods.
Finally, we'll update the loop() block to accept the text
If a touch is detected that's NOT on the Home button, entry app selection.
it passes the x and y coordinates to the curChar(x,y)
method which returns the character that corresponds Upload the tftDemo sketch to your Arduino and you
to that x and y location on the screen. The message should be able to use the completed app.
that has been 'typed' is then displayed on the screen
using the 'displayMsg(theChar) method. Congratulations! you've built a TFT touchscreen app!
Take the rest of the day off!
The curChar(x,y) method searches through the
Step 11: Gettin' Slick! - Using Adafruit Bitmap Fonts in Your Sketch.
The standard tft font set is okay. But it's nicer if we Add the following command,
can use proper bitmapped fonts in our TFT sketches.
tft.setFont(&FreeSerifBoldItalic18pt7b);
The downside is that loading font sets into the
Arduino memory takes up significant space. In fact, Now any print() commands will use the currently
it's very easy to fill your sketch with so many fonts specified font. To change to a different font, you
that it won't load into the Arduino. would use another tft.setFont() command with the
next font you would want to use.
The fonts are available inside the Adafruit_GFX
library folder that you already installed for this project. To set the font back to the standard tft font, just use a
An excellent tutorial on using fonts is at this site. tft.setFont(); command with no parameter.
In the Header area of your sketch, add the font Upload the sketch to your Arduino and you should
reference for the font you wish to use. We'll use the see the splash screen now uses the bitmap font for
FreeSerifBoldItalic18p7b font for this example. rendering the text on the screen. You'll notice that the
size of the sketch is significantly larger now that
#include <Fonts/FreeSerifBoldItalic18pt7b.h> you've included a font.
tft.drawLine(x1, y1, x2,y2, COLOUR); Play around with these commands and explore how
they can add to your TFT projects.
The following examples use the tft.color565 method
to let you specify the colour based on red, green and Learning to use a TFT screen is challenging and you
blue values. This is an alternative way to using the should be proud of yourself for taking the time to learn
constant defined HEX colour values we used in our these first steps.
sketch.
TFT screens can add an attractive and useful
tft.drawRoundRect(x, y,width,height,radius, Graphical User Interface aspect to your Arduino
tft.color565(255, 0, 0)); // this would be red projects.
tft.drawCircle(x, y, radius, tft.color565(0, 255, 0)); // Thanks for working through this tutorial.
this would be green
NOW GO OUT AND MAKE SOMETHING
tft.drawTriangle(vertex1x, vertex1y ,vertex2x, WONDERFUL!
vertex2y, vertex3x, vertex3y, tft.color565(0, 0, 255));