IN THIS CHAPTER , I WILL SHOW YOU how to install, connect, and program a mini-sized touchscreen display to a RasPi Model B. I will also explain the SPI bus and how you can use a Linux file to control a GPIO pin because both these functionalities are required for this project.
A touchscreen in is just an ordinary LCD device that has an additional human-interface device (HID) that allows users to touch the screen to further interact with the RasPi in accordance with an underlying control/display program. I will be using the 2.8-inch (diagonal) PiTFT, distributed by Adafruit Industries and shown in Figure 2-1 .
Figure 2-1 Adafruit PiTFT Model 1601.
This touchscreen is very compact and is specifically designed to be plugged into either a Model A or B RasPi. Incidentally, the figure shows the touchscreen mounted on a Model B RasPi, which happens to be running the classic Blender video Big Buck Bunny . I will demonstrate how to display this video later on in this chapter.
Figure 2-2 shows a side view of the touchscreen mounted on a Model B RasPi, where it is plugged directly into P1, which is the 26-pin GPIO connector.
Figure 2-2 PiTFT mounted on a Model B RasPi.
I will now provide you with a bit of background on the touchscreen technology now that I have shown you the actual touchscreen that will be used for this chapter’s project.
I will begin this discussion by giving credit to Steve Kolokowsky, of the Cypress Semiconductor Corp., whose white-paper content I freely used in this chapter. Incidentally, Planet Analog published Steve’s white paper entitled “Touchscreens 101” in 2009. Touchscreens may be classified as either resistive or capacitive. Their functions are identical, but how they achieve their functionality is completely different. I will begin by describing the resistive touchscreen because this is the type used in this project.
Figure 2-3 shows a layer-view cutaway of a resistive touchscreen.
Figure 2-3 Cutaway view of a resistive touchscreen.
The touchscreen is made up of six layers, as you can see from the figure. The top layer is a protective flexible, clear-plastic layer, which is the one you press your fingertip or plastic stylus against. Immediately underneath the plastic overlay is the ITO X -layer. ITO is an acronym for “indium-tin-oxide,” which is a mildly conductive metal alloy. The ITO layer is extremely thin and transparent. It can be thought of as a two-dimensional resistor that is used to detect the X -axis touchpoint coordinate. I will discuss how this is accomplished after I introduce the remaining layers. Next follows a layer of nonconductive transparent dots that provide an air gap between the ITO X -layer and the ITO Y -layer, which is located immediately under the dot layer. The ITO Y -layer is made up of the same material as the X -layer, and it is used to detect the Y -axis touchpoint coordinate. A thin glass layer lies directly under the ITO Y -layer, and it provides a stable platform for all the layers above it. Finally, a LCD display with a backlight is positioned under all the layers just discussed. It should be noted that the LCD used in touchscreen design should be very quiet from an electrical noise perspective so as to minimize potential interference with the touchsensor elements.
Figure 2-4 is a block diagram illustrating all the interconnected components necessary to detect the X -axis touch-coordinate point.
Figure 2-4 Block diagram of the X -axis touch-sensor layer.
There are three flexible metalized traces printed on the X -axis ITO layer; two are vertical bus lines, and the third is a horizontal sense line. The left-hand bus line has +5 VDC applied to it from the touchscreen controller chip. The right-hand bus line is at ground or 0-VDC potential. These bus lines will cause a distributed current flow across the ITO layer because the ITO alloy acts more like a resistor than a perfect conductor.
The ITO layer will deform when a fingertip or a plastic stylus, as shown in the figure, is pressed onto the outermost poly layer. This deformation causes a slight disruption in current flow, which can be detected by the sense line as a voltage between 0 and 5 V. The deformed ITO layer acts as a virtual potentiometer in which the sense line is the virtual center tap, as shown in Figure 2-5 .
Figure 2-5 Deformed ITO layer as a virtual potentiometer.
The sense line is connected to an analog-to-digital converter (ADC) within the touchscreen controller, and the digital equivalent to the sensed voltage is then sent to the RasPi for further processing. The ADC typically has either 10 or 12 bits of resolution depending on the size and resolution of the touchscreen sensor. However, you do not have to be concerned with the actual ADC bit resolution because that is already figured into the RasPi driver software. Figure 2-6 is a block diagram showing all the interconnected components necessary to detect the Y -axis touch coordinate point.
Figure 2-6 Y -axis touch sensor layer block diagram.
The Y -axis is essentially identical to the X -axis except that all the bus and sense lines are oriented 90° to those of the X -axis. The touchscreen controller will energize the Y -axis bus lines only milliseconds after completing the X -axis coordinate read operation. Obviously, the touchpoint is the same for the Y -axis as it is for the X -axis because the Y -axis ITO layer is directly under the X -axis, separated by the insulating dot layer.
The touchscreen just described is also referred to as a four-wire touchscreen , as the number refers to the interconnecting wires between the ITO layers and the controller. Five- and eight-wire resistive touchscreens are also available, as they offer improved accuracy and sensitivity. Those systems are more complex and expensive than the unit we will be using, and the improved qualities are not required for this project.
The resistive touchscreen has a few limitations that you should know about. While not terribly limiting, they do impose some constraints regarding how to properly use this type of touchscreen.
The protective top poly screen is 20 to 25 percent opaque, which reduces the overall LCD luminance. This might cause problems when the touchscreen is used outdoors under a bright sun.
The ITO layers can be a bit nonuniform, which leads to nonlinear resistance within the layer. This translates to inaccurate coordinate position sensing.
Resistance touchscreens often require more recalibrations than capacitive touchscreens. This might be a nuisance if the touchscreen is remotely deployed and development tools not readily available to accomplish the recalibration.
I also should mention that both the X and Y digital coordinate values are sent to the RasPi using the SPI Protocol, which I will describe following discussion of the capacitive touchscreen. Although this project uses the resistive version, I believe that it is important to understand how both the resistive and capacitive touchscreens function and when to select one or the other for use in a specific project.
You are probably quite familiar with capacitive touchscreens because they are used universally in just about all modern smart phones and tablets. The capacitive touchscreen functions in a somewhat similar fashion to the resistive version, but it uses a somewhat different layer structure, as can be seen in Figure 2-7 .
Figure 2-7 Cutaway view of a capacitive touchscreen.
This touchscreen uses a glass top layer, which provides 100 percent clarity. The next layer is an ITO layer consisting of an array of closely spaced dots, which are one part of the capacitive sensing scheme. Following this layer is a pressure-sensitive adhesive (PSA) that closely couples the two ITO layers while providing an insulator between them. The next layer consists of more ITO dots, similar to the layer above. The two ITO layers make up a fine grid of microcapacitors, with the PSA layer acting as a dielectric. The display LCD is placed beneath the second ITO layer, completing the touchscreen assembly.
The essence of touch sensing is that when a fingertip or appropriate stylus touches the top glass cover, it will slightly affect the capacitance of one or more of the microcapacitors beneath the touchpoint. The touch effect is not much, generally about a 4 to 5 percent change, but the touchscreen controller can detect this small change in capacitance. The touchscreen controller also uses individual wires to connect to each row and column of the microcapacitor array, and it will poll or sense these wires to detect the capacitors that have changed value as a result of the touch.
As you can imagine, this sensing scheme is quite stable and requires little to no recalibration once it is set up. There is, however, one issue regarding coordinate resolution, which you can see from Figure 2-8 . The problem is that placing a fingertip on the top glass screen will affect more than one or two microcapacitors, thus hindering accurate sensing of the desired touchpoint.
Figure 2-8 Touching a capacitive screen.
The solution to this problem is to employ a technique known as projected capacitive sensing . This technique uses all the changed values of the microcapacitors in and around the touchpoint to determine the center of gravity of the touchpoint by a process of interpolation. Note that no physical changes were done to the ITO dots to implement this technique. It’s all accomplished by software residing in the touchscreen controller.
NOTE
As of February 2015, Adafruit Industries offered a capacitive touchscreen for sale. It is Model 1983 and is a little more expensive than the resistive model I am using for this project. All the software that I describe in this chapter can be used on either type of touchscreen without any modifications as to the type.
There are a few limitations or constraints that you should know before using a capacitive touchscreen in a project. For example:
Wearing a glove likely will not result in enough of a capacitance change to be detected. You probably already know this if you tried to use a gloved hand with your smart phone.
Extreme weather also can affect these touchscreens. It is not that the screens themselves are affected; rather, it’s just that people’s fingers cannot change the capacitance at the touchpoint sufficiently owing to the environmental conditions. In such a situation, it would be wise to use an appropriate stylus designed to work with these touchscreens.
Some people have a condition, colloquially known as “zombie fingers,” and cannot reliably operate a capacitive touchscreen. Their only alternative is to use a stylus.
I will next discuss how a resistive touchscreen interfaces with a RasPi using the SPI Protocol. This interface is typical, but it is not mandatory for connecting touchscreens to RasPi-type controllers.
The touchscreen controller sends and receives data from a RasPi using the SPI Protocol, which the RasPi supports in the Wheezy Linux distribution. SPI is a bit-serial protocol, which I explain in the following sidebar if you wish to understand it further. However, you can skip reading the sidebar without any loss of continuity regarding this project.
The serial peripheral interface (SPI) is one of several bit-serial data communication channels that the RasPi supports. It is a synchronous serial data link that uses one master device and one or more slave devices. A minimum of four data lines are used with SPI, and Table 2-1 shows the names associated with the master (RasPi) and slave (1601) device. Figure 2-9 is a simplified block diagram showing the principal components used in a SPI data link.
TABLE 2-1 SPI Data-Line Descriptions
Figure 2-9 Simplified block diagram of an SPI data link.
Usually, two shift registers are involved in the data link, as shown in the figure. These registers may be hardware or software depending on the devices involved. The RasPi and PiTFT both implement their shift registers in software. The two shift registers form what is known as an interchip circular buffer arrangement that is the heart of the SPI.
Data communication is initiated by the master by first selecting the required slave. The RasPi selects the 1601 by bringing the SS line to a low state or 0 VDC. During each clock cycle, the master sends a bit to the slave, which reads it from the MOSI line. Concurrently, the slave sends a bit to the master, which reads it from the MISO line. This operation is known as full-duplex communication , that is, simultaneous reading and writing between master and slave.
The clock frequency used depends primarily on the slave’s response speed. The touchscreen controller in the PiTFT can run at 32 MHz, which easily should be compatible with the RasPi’s computational rate. The PiTFT clock speed may be adjusted if the display becomes erratic or sputters. I show how this is done in the installation instructions that follow.
The preceding sidebar completes the background on how touchscreens function. It is now time to discuss how to install an Adafruit resistive touchscreen with a Model B RasPi.
I have separated the installation process into four sections as follows:
1. Hardware installation
2. Software installation
3. Configuration
4. Calibration
The hardware installation is quite simple: simply plug the matching 26-connector into the Model B RasPi. This is all that is needed if want the touchscreen installation to be barebones as far as the physical setup. However, I wanted it to be a bit fancier, so I elected to install the RasPi and PiTFT in a custom case. The case I used was the PiBow case with a PiTFT extension available from Adafruit Industries as Model 2779. Figure 2-10 shows the final installation, and I believe that it really looks like a finished product instead of an experimental project.
Figure 2-10 PiTFT with RasPi installed in a PiBow case.
One modification to the PiBow case is necessary if you wish to use the Pi Cobbler with the RasPi/PiTFT combination. I have made this modification, as you can clearly see in the figure. Figure 2-11 is a close-up of the modification showing where the Pi Cobbler ribbon cable exits the PiBow case.
Figure 2-11 Pi Cobbler ribbon cable pass-through in the PiBow case.
The modification involves cutting off a piece of plastic from stack layer four, as shown in Figure 2-12 , to allow room for the Pi Cobbler ribbon cable to pass through the PiBow case.
Figure 2-12 Modification to PiBow stack layer four.
The Pi Cobbler ribbon cable then can be plugged into the 26-pin extension socket as shown in Figure 2-13 . The ribbon also must be carefully folded back to allow it to pass over the socket and out of the PiBow case.
Figure 2-13 Back view of the PiTFT.
You also should note how the flexible ribbon cable from the PiTFT display is inserted into the touchscreen controller socket. Be very careful to carefully align this cable with the socket because serious problems will result if it is not inserted correctly into the socket. Figure 2-14 shows the PiBow stack arranged up to and including stack layer four to help guide you with case installation.
Figure 2-14 Partial PiBow case installation.
The Pi Cobbler cable should now easily fit in the new opening created by cutting the plastic piece from the PiBow stack layer four. I would suggest that you now complete the PiBow case installation by placing the remaining stacking layers and fastening them with the long nylon screws and nuts. I would also caution you that I had to slightly file the right-hand side tips of the PiTFT printed circuit board (PCB) to provide clearance for the two nylon screws. You may not have to modify them because I only had to file them down about 1/32 of an inch, and manufacturing tolerances are such that yours may fit as built.
This section concerns the optional installation of four 6-mm slim tactile buttons on the PiTFT PCB, one of which is shown in Figure 2-15 . A package of 20 of these buttons may be purchased from Adafruit (Part No. 1489).
Figure 2-15 Tactile switch.
The four buttons will need to be soldered into the PCB holes located at the bottom of the touchscreen. These tactile buttons, when pressed, will ground RasPi GPIO pins 18, 20, 22, and 23. Their functionality is uncommitted and available for use in a program. The button connected to pin 23 may function as a RasPi reset when the PiTFT software is loaded. You must choose this feature during the PiTFT configuration process.
Completing the optional button installation finishes the physical installation. It is now time to discuss software installation.
There are three approaches you can take when it comes to installing the driver software that supports the PiTFT. The first is to use a prebuilt Wheezy image that already includes all the PiTFT drivers as well as some testing software. This image is available courtesy of Adafruit at http://adafruit-download.s3.amazonaws.com/ 2015-02-16-raspbian-pitft28r_150312.zip. This is a 3.28-GB image that also would need to be written onto an SD card using the procedure detailed in Chapter 1 . The folks at Adafruit refer to this approach as an “easy install,” which it is, and I would definitely recommend it to my readers who are not comfortable with running scripts or compiling and building code.
The second approach involves downloading and running a script or helper file from the Adafruit learn website at https://learn.adafruit.com/adafruit-pitft-28-inch-resistive-touchscreen-display-raspberry-pi/easy-install . The helper file found on this site automates many process steps, including downloading files and compiling and installing them onto an existing Wheezy distribution. I would recommend this approach for several reasons. The first is that you may already have a customized Linux distribution set up that you do not want to discard. Another reason is that you will learn a lot about the PiTFT setup and will be able to modify it to suit your specific needs, which is not possible with a prebuilt image.
The third approach involves manually integrating a series of libraries and support code into an existing Wheezy distribution. This involves essentially following a manual series of steps that have been automated by the helper file used in the second approach. I would recommend this approach only to those experienced readers who are very comfortable compiling, building, and installing Linux kernel code.
I will present the second approach because it is a good learning experience yet not too overwhelming. This software installation generally follows the second approach, where a helper file is used to install the necessary software. For readers interested in this process, I will also present an example later on in this chapter on how to compile and build a program.
This installation generally follows the Adafruit tutorial, as mentioned earlier. I have arranged it in a step-by-step sequence, which you should follow to ensure a successful completion. I will also be using a headless or Secure Shell Protocol (SSH) link to the RasPi because it was easier for me to read the text on a laptop screen rather than attempting to read the smaller text on the PiTFT screen. You certainty may use the PiTFT screen if you’re comfortable with the text size. It will not be possible to use both the PiTFT and the HDMI displays simultaneously because of the framebuffer selection, which I will explain later.
1. I will start by assuming that you have a fresh install of the latest Wheezy Linux distribution. The latest is always available from http://www.raspberrypi.org/downloads/ .
2. Update and upgrade the installed distribution.
3. Download and install the helper file. Be patient; the install can take up to 20 minutes.
4. Run the actual PiTFT configuration using the helper file.
5. At the end of the configuration process, you will be asked two questions. The first is whether you want the PiTFT to be the console text screen. The second will be whether you want the button connected to GPIO pin 23 to act as a reset, as I mentioned earlier. Answer the questions to suit your personal preferences. Figure 2-16 is a screenshot showing these questions.
Figure 2-16 PiTFT configuration questions.
6. All that’s left is to reboot the RasPi to have the PiTFT completely set up.
I will show you how to check the PiTFT installation in the following calibration section.
The good news for this step is that all the PiTFT configuration has already been accomplished if you used the helper file approach. However, I will cover some details about manually configuring this touchscreen because it will help you to understand the process.
The PiTFT configuration process involves modifying an existing text file, which will hold the device’s parameters. I would strongly suggest that you use the already installed nano text editor because I have found it to be easy to use and very convenient. Enter the following to start modifying this configuration file:
Enter the following code after the last line in the existing config file:
After you enter all the code, press CTRL-O (^O) to save the modified file. Then press CTRL-X (^X) to exit the nano editor.
There are few things that you should know regarding the PiTFT parameters. In the last line, the parameter pitft.rotate=90
sets the view for the PiTFT screen. There are four choices for the view prospective:
0: Portrait with the screen bottom near the USB jacks
90: Landscape with the screen bottom near the headphone jack
180: Portrait with the screen top near the USB jacks
270: Landscape with the screen top near the headphone jack
The parameter speed=32000000
sets the touchscreen clock rate. You might need to adjust this downward to 16000000
if the screen starts appearing erratic or jumpy.
Finally, the parameter fps=20
sets the number of frames shown per second. The default value should be fine, but if you reset the clock rate, this parameter might have to be lowered by a few frames per second.
The next section concerns calibration. Again, as with the configuration section, all the required calibrations have already been done if you used the helper file for the PiTFT installation.
For a touchscreen, calibration is really about matching the logical coordinates with the physical screen, where the LCD origin coordinates (0, 0) are located at the appropriate screen corner and the maximum LCD coordinates (320, 240) are at the diagonally opposite corner. Once these are set, all the logical touchpoints should linearly match the physical ones. This means that if you touch the screen in precisely the center with a stylus, you should return the midpoint LCD coordinates (160, 120). It is also important to realize that the touchscreen controller returns absolute numbers based on the number of ADC bits. The PiTFT uses a multichannel 12-bit ADC, which means that the reported values will range from 0 to 4095. Remember from your high school math that 12 bits can represent 4096 separate whole numbers or, more precisely, 212 = 4096. Now the X -axis must be physically matched to the LCD’s 320-pixel range, which means that the absolute value must be scaled or reduced proportionally to match the 0- to 319-pixel range. The same is true for the Y -axis, except that the scale factor matches the 0 to 4095 absolute range with a 0- to 239-pixel range. Now let’s move on to starting the calibration process.
The first step in this calibration process is to create an udev rule, which will fix or persist a logical name for the PiTFT. The current Linux device manager is named udev, and it uses text-based rules to manage all the devices connected to the Linux computer on which it is installed. Enter the following to use the nano editor to create a text file to hold the rule:
Next, enter the following into this file:
NOTE
I had to break this statement up to fit this book’s format. You should keep it all in one line when you enter it.
After you save and exit the nano editor, you will need to remove and reinstall the touchscreen driver in order for the new udev rule to take effect. Enter the following to accomplish this:
You should next check to see if the driver installation and rule change were effective. Enter the following:
This command results in an eventx
being returned, where the x
stands for a number starting at 0. Figure 2-17
shows the result of running this command on my RasPi.
Figure 2-17
Screenshot for the ls
command executed on the touchscreen.
Your number may be different from 0 because the event number is assigned based on the number of keyboards/mice and similar input devices that are actively connected to the RasPi. You are now ready to install the touchscreen library and test the software, which will allow you to both debug and calibrate the touchscreen.
evtest
and tslib
Enter the following command to install both the test software and the supporting touchscreen library:
Next, run the evtest
application by entering
You should now be viewing the initial evtest
screen, which shows some configuration information and is awaiting a touch event or input, as shown in Figure 2-18
.
Figure 2-18
Initial evtest
screenshot.
Next, use a plastic stylus to carefully and briefly touch the center point of the touchscreen. You should see a series of events captured by the evtest
application, as shown in Figure 2-19
.
Figure 2-19 Touchpoint event screenshot.
Actually, 19 events were captured, from which I shortened the display to 10. Each event is time-stamped with the number of elapsed seconds from 1/1/1970. Of course, we are only interested in the time frame surrounding the events, which lasted only 0.172861 second or approximately 173 milliseconds. Two principal event types are shown, 1 and 3. Event type 1 is the BTN_TOUCH
with a value of 1 to start and a value of 0 after the touch is lifted. Event 3 has three subcodes, which report the absolute X
- and Y
-coordinates as well as an absolute pressure reading. If you closely examine Figure 2-19
, you will see that the X
-coordinate values hover around 2300, and the Y
-coordinate values hover around 2050. This
makes sense when you consider that the absolute X
and Y
ranges are 0 to 4095. I touched the stylus near the screen center, which resulted in having approximate center value readings.
The origin point or coordinate values (0, 0) are at the upper left-hand corner, and the maximum coordinate values of (4095, 4095) are at the lower right-hand corner because the screen has been logically rotated 90°, as was shown in the configuration section. Also recall that these absolute coordinate values must be scaled to match the LCD pixel range, as I explained earlier.
The measurement of absolute pressure is a bit more complex because it involves measuring the cross-layer resistance between the X -ITO and Y -ITO layers. Suffice it to say that a higher reported number corresponds to higher applied touchpoint pressure. It would depend on the specific application using the touchscreen whether or not the pressure measurement was actually used. However, I do believe that pressure measurements are used in the normal internal operation of the touchscreen controller in order to achieve specific functionalities.
Adafruit has provided the following Python script to automatically run the touchscreen calibration. You will need to enter the following:
NOTE
The preceding must be entered on the same line. It was split to match this book’s format.
After you have downloaded the Python script, enter the following to run it:
Figure 2-20 shows the result of running this script on the touchscreen I previously set up with my RasPi using the helper file.
Figure 2-20 Screenshot of the automatic calibration script results.
You will be presented with a question at the end of the script results asking whether or not to update the current configuration. I answered yes because the current configuration exactly matched the old configuration.
I will now discuss a manual calibration procedure that might come in handy for readers who believe that the automatic calibration is not quite precise enough for their use. You will need to have already downloaded and installed both the tslib
and libts-bin
packages for the manual calibration to work. I discussed how this was done in the evtest
and tslib
section.
Enter the following to start the manual calibration:
NOTE
The preceding must be entered on the same line. It was split to match this book’s format.
Figure 2-21 shows the result of entering the preceding command.
Figure 2-21 Manual calibration screenshot.
You need to touch the center of the touchpoint shown in the figure. Four more touchpoints will appear on the screen, each one at a time to be touched. Figure 2-22 shows the result of the five touches and the set of new calibration constants that will be used as a result of this manual calibration.
Figure 2-22 Manual calibration results.
You may run the following test to check on how well the new calibration constants are working. Enter the following to initiate the test:
NOTE
The preceding must be entered on the same line. It was split to match this book’s format.
Figure 2-23 shows what will appear on the touchscreen as a result of running this command.
Figure 2-23
ts_test
touchscreen display.
A corresponding coordinate display will also appear on the console screen. However, the coordinates shown will be in terms of the LCD pixels and not the absolute coordinates shown in previous figures. Apparently, the ts_test
program automatically scales the absolute coordinates before displaying them.
I next drew a short line from the displayed touchpoint to the left in order to generate some sample coordinates. Figure 2-24 is a console screenshot, which has been shortened, to show the results of the line drawn on the touchscreen.
Figure 2-24 Console display for a straight horizontal line drawn on the touchscreen.
You may see from the figure that the X values increase from 160 to about 290, while the Y values remain reasonably constant around 120. These numbers translate into a horizontal line drawn on the touchscreen from the center to the right edge, which is exactly what I did. The pressure readings average about 120, which corresponds to medium force applied to the stylus used to draw the line. I also later tried drawing another line using more force on the stylus and recorded pressure readings up to about 139. I later determined that simply using a fingertip on the touchscreen could generate readings up around 220. I can only conclude that the area of applied pressure plays some role in determining the ultimate pressure reading. Based on my findings, I would be a bit leery of relying on pressure readings to derive any conclusions about any specific touchscreen event other than when it started and stopped.
I did another check using the ts_test
application in which I tapped both the origin and maximum touchpoints on the touchscreen. Figure 2-25
shows these two points as tiny white dots. I touched the Draw button on the screen to show where I placed these two dots.
Figure 2-25 Max and min touchpoint test.
The console screen displayed the minimum point as (5, 5) and the maximum point as (319, 237). These are very close to the expected values of (0, 0) and (320, 240), respectively. If you examine the figure very closely, you will see that the origin touchpoint was slightly down and away from the true origin, which is the upper right-hand corner of the slightly lighter-colored touchscreen region. The maximum touchpoint is almost dead centered on the lower right-hand corner, which is reflected in the reported coordinate position. Also notice that the touchscreen region precisely fills the complete LCD display area. This may be due to the physical area needed by the sense lines, or it could be an artifact of the manual calibration that I did just prior to this test.
This last test completes my calibration discussion. I do want to make you aware that the Adafruit PiTFT tutorial I referenced earlier contains several more calibration techniques that you can do, especially if you are using the touchscreen with X-Windows. I will next discuss the framebuffer, a term I used earlier but deferred explaining what it is and how it is used in conjunction with a touchscreen.
It is important for you to understand the framebuffer concept because it affects how the PiTFT functions with regard to the regular HDMI display. A framebuffer (FB) may simply be defined as a place in dynamic memory that contains one complete video frame to be displayed. Each location in an FB contains 3 bytes whose values represent the RGB intensities for each displayed pixel. Video frame sizes vary depending on the display device. The underlying touchscreen LCD used in this project is 320 × 240 pixels in size for a total of 76,800 pixels. This makes the total memory required for an FB to be 230,400 bytes or 225 kB because each pixel uses 3 bytes.
The actual hardware implementation used in the RasPi is fairly complex because it involves the central processing unit ( CPU), a graphical processing unit (GPU), and a series of mailbox registers to control the flow of video data between the two processors. I elected not to include a detailed discussion of the hardware implementation because it would significantly add complexity to this chapter with little reader benefit because you have no programmatic control of internal FP operations. You can, however, use a nice little Adafruit application to view the FB contents.
Enter the following to download and install the FBI application:
You will need a test image to check out this viewer application. Once again, Adafruit comes to the rescue. Enter the following to download a test image precisely sized for the touchscreen LCD:
NOTE
The preceding must be entered on the same line. It was split to match this book’s format.
Figure 2-26 shows the image displayed on the touchscreen.
Figure 2-26 Adapiluv320x240.jpg displayed on the PiTFT.
Sharp-eyed readers may have noticed that I used the identifier fb1
in the preceding command to display the downloaded image. This is the PiTFT logical
name
, which is the identifier associated with the PiTFT touchscreen. For all intents and purposes, it is the driver name, which the operating system (OS) uses to send and receive data to/from the device. I had also used fp1
previously in the manual calibration command sequence. There is also another FB device installed on the OS, and that is fb0
, which is the HDMI display. You can only have one FB device active at a time, which is the reason I mentioned much earlier in this chapter that the touchscreen and the HDMI display could not be used simultaneously. You should also realize that the composite output is the analog conversion of the HDMI display, so you cannot “cheat” the system and try to run the touchscreen and get a composite output. This is all the more reason to use a headless development station, from which you get the best of both worlds, a working touchscreen and a large development display.
In this brief section I will show how to set up and run a video on the touchscreen. This video player application nicely demonstrates the LCD screen video capabilities, even though running a video player has nothing to do with typical touchscreen operations.
The first step is downloading a video, which will be the source of the demonstration. I would recommend the classic Big Buck Bunny video, which has been sized for the PiTFT and may be downloaded from Adafruit using the following command:
NOTE
The preceding must be entered on the same line. It was split to match this book’s format.
Once the video is downloaded, you will need to download and install the player application. Enter the following to install the mplayer
application:
Then enter the following to run this video:
NOTE
The preceding must be entered on the same line. It was split to match this book’s format.
NOTE
I ran this without audio, but I am fairly certain that a music track accompanies the video. You might try plugging an amplified speaker into the RasPi stereo jack to see whether the music plays.
At this point, I will conclude my touchscreen background discussion and proceed to explain this chapter’s project.
The demonstration screen project is quite simple: display a button on the touchscreen that when clicked by either a stylus or fingertip will toggle a light-emitting diode (LED) connected to one of the RasPi’s GPIO pins. While the project goals are quite easy, getting to an actual implementation will involve a bit of work.
The code for this project is written in the C language, which has been around for a comparatively long time. Do not fear if you are skittish about using C because I have provided step-by-step instructions on how to compile and build the source code, and I have made the source code available on this book’s companion website. Before jumping into the project code, I make a brief diversion into the concept of Linux file input-output (I/O).
Some readers may already know that the Linux OS treats almost everything as a file if you also consider a directory as a special file type. This means that I/O commands can be directed to a file where it effectively interfaces to the outside world. This is great news and can simplify programming to a great extent. I will use a practical example to demonstrate how this file I/O functions.
The PiTFT has four LEDs built in, which provide backlighting for the display. As most of you know, a liquid crystal display (LCD) is essentially a dark display without backlighting. I will demonstrate how to control the touchscreen’s backlighting using file I/O.
You first need to ensure that the PiTFT is plugged into the 26-pin connector. Next, enter the following command:
This command created a series of files and directories that will allow us to control the backlights. Enter the next command to confirm that the master directory was created:
You should see a display similar to Figure 2-27 .
Figure 2-27
ls
command run on the /sys/class/gpio
directory.
Just ensure that you have a directory with the number 508 in the title. Given that the 508 directory exists, enter the following to create an output type direction for this newly create GPIO control file (also be looking at the touchscreen when you enter this command):
If all went as it should, the PiTFT should go dark because the backlighting turned off. It turned off because the preceding command set the file direction as an output, and a 0 was automatically sent to the corresponding GPIO pin. Enter the following to turn the backlighting on again:
You will now see the touchscreen display because the backlighting is turned on again. Note that nothing in these commands changed the content of what is displayed; they only toggled the backlighting LEDs to allow you to see or not see the touchscreen. You change the 1 to a 0 in the preceding command to turn off the backlighting. Try experimenting with these commands to convince yourself of their utility.
This project sets up a rectangular button on the touchscreen that will be used to control a LED. The LED will simply be turned on or off, which is known as toggling . The button color and text will also change reflecting the state of the LED.
You will need a little hardware setup to run this project. I used a LED in series with a 220-Ω resistor connected on a solderless breadboard. I also used a Pi Cobbler to extend all the GPIO lines from the touchscreen. The complete physical setup was shown earlier in Figure 2-10 . The wiring schematic is shown in Figure 2-28 .
Figure 2-28 buttonExample schematic.
I will now show you the C program that creates a button on the touchscreen that controls a LED. This program is an adaptation of an existing program named buttonExample.c created by Mark Williams. The original, unaltered version is available for download from GitHub at https://github.com/mwilliams03/Pi-Touchscreen -basic/blob/master/buttonExample.c . My modified version is as follows:
I will not attempt to go through all the code because it is fairly extensive, but I will point out that I generously sprinkled comments throughout the code to help you understand what was happening in a particular code section or module.
Here are the steps to compile, build, and run this program:
1. Download and install the wiringPi package found at wiringpi.com . Do not use the GitHub version of wiringPi because it is not the version required for this installation.
2. Download and install the zip file from Mark Williams’ GitHub site at https://github.com/mwilliams03/Pi-Touchscreen-basic .
3. Extract all the files into a single directory. My directory was named Pi-Touchscreen -basic-master. The following files should be in this directory:
a. README
b. buttonExample.c
c. font_8x8.c
d. framebuffer.c
e. main.c
f. touch.c
g. touch.h
4. Download the source code from the book’s companion website. It is entitled buttonExample.c.
5. Replace the existing buttonExample.c with this version.
6. Compile it by running this command:
7. Build it by entering:
8. Install it by entering:
9. Run it by entering:
If all goes well, you should see the button displayed on the touchscreen, as shown in Figure 2-29 .
Figure 2-29 Initial touchscreen with the buttonExample program running.
Now press the button on the touchscreen, and two things should happen. First, the button should change to what is shown in Figure 2-30 .
Figure 2-30 Touchscreen after pressing the button.
Second, the LED should be on. If not, check that you used sudo
in the command; otherwise, the OS will not permit the file to be written.
This is a permissions issue, which I discussed in Chapter 1
. The other reason could be that the LED is connected backwards.
A connected console screen also will show all the events as they are happening, just as it was with earlier demonstrations. Figure 2-31 is a snapshot of some button-pressing events for this application.
Figure 2-31 Event log for button presses.
This concludes my simple demonstration project. It obviously may be extended to include additional buttons that can trigger other I/O events as well as start or stop other processes. You can really dive deep into this area because most readers will realize that most smart phones have a myriad of touchscreen activities that trigger all sorts of events, e.g., “Hello Siri.”
One last item: I strongly recommend that you do not disassemble your touchscreen project if you intend to do the software-defined radio (SDR) project in Chapter 7 . The touchscreen PiTFT is used as is in that project, and it would be a shame to have to rebuild it all if you want to explore the wonderful world of SDR.
This was a chapter about touchscreens, and it concluded with a simple demonstration of a single button that toggled a LED. I also dug deeply into what makes a touchscreen function, pointing out the different types and their pros and cons. Linux file I/O also was covered, and I demonstrated how to use simple file I/O to control the touchscreen LCD.
