Chapter 4

SmartSet Tutorial

Introduction to the SmartSet Program

Running SmartSet

Main Menu Categories

Sample SmartSet Session

Enabling Touch Reporting
Changing the Touch Mode
Calibration
Range Checking Mode
Trim Mode
Scaling
Axis Inversion
Saving the Setup
Second Calibration/Scaling
Programming Multiple Controllers

Where to Go From Here


This chapter will introduce some of the important concepts in touchscreen driver programming as they relate to the SmartSet controllers. The concepts will be presented in tutorial form using software accompanying this manual.

Introduction to the SmartSet Program

The SMARTSET.EXE program is found on the SmartSet Companion Disk which may be downloaded separately from www.elotouch.com. The SMARTSET program, (indicated in this manual by capital letters), requires an IBM PC or compatible running MS-DOS. We recommend connecting the SmartSet controller to a PC for this tutorial even if your target platform is not a PC running DOS. Elo's DOS driver, ELODEV, is not required.

This tutorial will use the SMARTSET program to go beyond the basic issue of receiving touchscreen coordinates and demonstrate many of the features of the SmartSet controller family. These features include on-board calibration, coordinate scaling, diagnostics, various operating modes, communication protocols, timers, filtering parameters, and NVRAM. Two-way communication is used between the host driver software and the controller's firmware for sending commands and receiving responses.

SMARTSET is useful to driver writers in the following ways:

Besides programmers, others may use SMARTSET in the following ways:

Running SmartSet

SMARTSET is invoked by typing:

SMARTSET (not case sensitive)

at the DOS prompt.

Figure 4-1. SmartSet Utility Interface Selection

Select Serial, PC-Bus, or Micro Channel interface. (A selection for Micro Channel replaces PC-Bus if you are running on a system with a Micro Channel bus.)

Enter the Base I/O Port address or COM port as requested. SMARTSET locates the controller and displays the controller's jumper settings as shown below:

Figure 4-2. SmartSet Utility Jumper Settings Display

NOTE

A warning message is displayed if the controller is not detected. You may proceed to the Main Menu and SMARTSET will assume default settings for all controller parameters. You may then change any parameters and save all settings to a disk file. This file can later be transferred to a connected controller. If you change the communication parameters from the Main Menu, SMARTSET will attempt to establish communication with the controller again.

 

 

 

 

 

Press a key to display the Main Menu, shown below.

Figure 4-3. SmartSet Utility Main Menu

The top of the screen shows the version of the SMARTSET program, the type of controller and touchscreen, the ROM revision level of the controller firmware, and the Owner ID string, factory set to "EloInc." unless you have a special OEM configuration.

The bottom of the screen contains some status information which is updated after each command. The Communication Status indicates if SMARTSET is communicating with a connected controller. The communication status may change if communication parameters are changed. The bottom line says "Idle" if SMARTSET is ready to accept a command, or indicates a command is in progress. The help line gives context sensitive help on the highlighted command. Additional information can be displayed for the highlighted command at any time by pressing the [F1] key.

The left half of the screen, the Main Menu, lists categories of available controller commands. The right half, or submenu, lists available controller commands for each category and their current setting. Use the arrow keys to move the highlighting up or down on the Main Menu. The submenu changes with each category. Press the right arrow key or [Enter] to move the highlighting to the submenu for the highlighted category. Press the left arrow to move back. When the highlighting is in the submenu, controller parameters may be changed. Hot keys indicated for the Main Menu categories may be used to jump quickly from submenu to submenu.

Take a moment to move through the menus using the arrow keys and hot keys. Press [F1] for help on any category or controller command. Do not change any settings yet.

Main Menu Categories

The Main Menu includes the following categories, described in general below. All commands will be detailed later in this manual.

Load/Save Setup Lets you load and save controller settings to disk and/or nonvolatile RAM (NVRAM). Saving settings to NVRAM will change the controller's power-on defaults, unless the controller is booting from jumper settings. Saving settings to disk will allow other controllers to be quickly programmed to the identical settings. Multiple controllers can be programmed identically by loading settings from disk, then saving those settings in NVRAM.
Communications Lets you examine and change the parameters for communication with the SmartSet controllers. The parameters and their use vary depending on the interface.
Touch Mode Various options can be selected for which portions of a touch will be reported. You may select the initial touch point, the last point touched (the untouch point), the entire stream of intervening points (stream points), intervening points which do not repeat the coordinate value (tracking points), or combinations of these. Touch coordinates may be trimmed and scaled to specified ranges.
Touch Reporting Used to select various touch reporting options, touch packet emulation, and low power mode.
Calibration A touchscreen calibration sequence may be performed, or calibration points specified manually. X and Y axes may be swapped.
Scaling Touch coordinate scaling ranges can be specified with any axis inversion.
Timer Lets you select and configure the on-board timer features of the controller.
Filter Allows you to select low-level filtering parameters for optimizing controller performance for extreme environments.
Touch Testing Allows you to test the touchscreen and see the data transmitted by the controller.
Diagnostics Runs the various on-board diagnostic routines.
Reset Controller Performs a soft or hard reset on the controller.
ASCII Setup Lets you communicate directly with the controller by entering command packets with the keyboard. By manually communicating with the controller and studying its responses, you can learn the details of the host-controller interaction.
Exit Exits the SMARTSET program.

Sample SmartSet Session

We will now proceed to configure some basic operating parameters of the SmartSet controller. The SMARTSET program will be used to change settings and examine their effects. Press [F1] for on-line information for each command, or refer to Chapter 6 for detailed information.

Enabling Touch Reporting

First confirm touch reporting is enabled by pressing "P" for the "Touch Reporting" menu, then moving the highlighting to "Touch Reporting" and press [Enter] so "Report" is indicated. (Only serial controllers power-on enabled).

Skip to Touch Testing by pressing "T". Touch the touchscreen. X and Y coordinates will be displayed for the position of your touch, as well as a constant Z-axis value will vary with pressure on IntelliTouch screens, or remain constant on AccuTouch screens.

Figure 4-4. SmartSet Utility Touch Testing Display.

The Touch Flag indicates whether a touch coordinate is for the point of Initial touch, the point of release (Untouch), or points between those events (Stream).

Changing the Touch Mode

The SmartSet controller can be configured so it reports any combination of these types of events. Press [ESC] to exit the Touch Testing screen, and "M" to enter the Touch Mode submenu. Use the arrow keys and [Enter] to enable various combinations of "Initial Touches", "Stream Touches", and "Untouches". Type "T" to return to the Touch Testing screen to examine their effects.

Return the controller to the "Enabled" setting for "Initial Touches", "Stream Touches", and "Untouches".

Calibration

The need for calibration is unique to the touchscreen. Unlike mouse or keyboard applications where the cursor is part of the image, a touchscreen is a physical overlay with an independent coordinate system. Only by knowing the position of the image can the touchscreen coordinates be converted into image coordinates.

Besides the differences in touchscreens and controllers, calibration also compensates for the variation in video image among displays. The image is affected by horizontal and vertical adjustments on the monitor and by the physical mounting of the touchscreen.

Additional calibration complications include image blooming, where bright-colored images expand, and the "pin cushion" effect, which causes the corners of the display to be stretched. Poor display linearity can cause similarly-sized boxes to be larger at the edges of the screen than they are in the middle, or vice-versa. The displayed image can also be tilted. Even changing video modes can affect the screen size.

Perfect calibration cannot be achieved in all circumstances. For example, the user can encounter parallax problems with a change in position, or because the present user is not the same stature as the person who calibrated the screen.

Even the most sophisticated calibration techniques can only partially overcome such variations. Therefore, most touchscreen software uses only a two or three-point calibration sequence and instead relies on well-placed touch zones and appropriate user feedback.

The three-point calibration sequence used by the SMARTSET program automatically corrects inverted touchscreen installations and backwards cable connections.

Type "T" and locate the corner where the X and Y values of the touchscreen are lowest. This is the default origin of the touchscreen coordinate system. The X and Y coordinates increase as you move to the diagonally opposite corner. Because the coordinate values at the extremes of the touchscreen vary with every touchscreen and controller combination, touchscreen coordinates are only useful if mapped to the coordinate system of the image behind the touchscreen.

For example, your touchscreen may have its origin in the lower-left corner and have a coordinate system ranging from 352,536 to 3715,3550. The active area of the touchscreen will usually extend beyond the image, into the overscan area of video displays. Your image may have its origin in the upper-left corner and have a coordinate system from 1,1 to 80,25.

In Figure 4-5 below, Rx and Ry denote the raw coordinate system of the touchscreen controller, and Sx and Sy denote the coordinate system for the screen image. Rxlow, Rylow, Rxhigh, and Ryhigh are the calibration points for the position of the image in raw coordinates. Given point Cx and Cy in raw coordinates, the X and Y values must be determined in screen coordinates.

Figure 4-5. Calibration Point Coordinates

We will now use the on-board calibration and scaling features of the SmartSet controller so coordinates will be reported in the coordinate system of your image. (If you do not wish to use this feature of the SmartSet controller, Appendix B gives generalized calibration and scaling algorithms that a driver program can use.)

Go to the Calibration submenu. Note the default calibration points are 0-4095 for each axis. Choose "Do Calibration", type "C" to calibrate in 80x25 text mode, and touch the three points indicated.

When you complete the calibration sequence and return to the menu, the calibration points have been changed. The new calibration points are the coordinates of the upper-left and lower-right corners of the 80x25 image.

If the default orientation of your touchscreen had the origin in the lower-left corner, as is typical, the calibration points will reflect a change in orientation by having a low value greater than the high value in the Y axis. If your origin was in the upper-right, the X values will be reversed. The process of calibration not only defines the position of your image, it also aligns the origin of the touchscreen coordinate system with that of the image. This is called hardware axis inversion. In general, the first calibration point becomes the origin.

The third calibration point was used only to detect swapped axes. This can correct inverted cabling or touchscreens rotated 90°. Normally after calibrating, the X/Y Axis field indicates Normal, not Swapped.

You may have noticed that the calibration routine did not acquire its calibration points in the corners of the video image. The points taken are offset from the corners, then extrapolated to achieve an estimated value at the corners. This is because the image on some monitors is not very linear, and usually least linear in the corners, due to the "pin cushion" effect. By acquiring calibration points near the corners instead of at the corners, more of the video will be closely calibrated with the touchscreen.

The calibration routine used by SMARTSET lets you select a video mode supported by your display before you calibrate. As the screen size and position may vary among video modes, you should calibrate in the video mode used by your application. For our example, we calibrated in text mode.

Typically, touchscreen driver developers will write their own calibration routine rather than using this feature of SMARTSET. Later in this manual, sample source code for a calibration program is given.

Now Enable the Calibration Mode on the Touch Mode submenu. The calibration points are ignored until Calibration Mode is enabled.

Return to the Touch Testing screen. Notice that the origin is now in the upper-left corner, and the coordinate is approximately 0,0 at the edge of the image, and 4095,4095 at the lower right corner of the image. If you touch beyond the image in the overscan area, you will see negative coordinates in the upper left, and coordinates greater than 4095,4095 in the lower right.

Range Checking Mode

Next, Enable Range Checking on the Touch Mode submenu. This mode instructs the controller to check if a touch is within the calibrated area or in the overscan area.

Return to the Touch Testing screen again. Now the controller indicates "out of range" by adding 40 to the Status field when you touch the overscan area. Range Checking does not affect the coordinates. The only effect is a slight degradation in coordinate throughput because the controller has to perform additional analysis.

Trim Mode

Enable Trim Mode on the Touch Mode submenu. This mode instructs the controller to push the coordinates of a touch in the overscan area to the edge of the calibrated area. In most applications, a touch in the overscan area should be accepted as a valid touch in the closest touch zone on the edge of the image. Trim Mode only works if Range Checking is also Enabled.

Return to the Touch Testing screen again. The Status still indicates "out of Range" when you touch the overscan area. However, the coordinates are trimmed to 0,0 and 4095,4095 at the extremes.

Scaling

The process of scaling is similar to that of calibration. Usually it is desired to map the touch coordinates into a range other than the controller's default range of 0 to 4095. For our example, we will want coordinates scaled to values of 1 to 80 horizontally and 1 to 25 vertically.

Select the Scaling submenu by pressing "S". Change the X Low value to 1, the X High to 80, the Y Low to 1, and the Y High to 25.

Now, return to the Touch Mode submenu and enable Scaling. The scaling values are ignored until Scaling Mode is enabled.

On the Touch Testing screen, observe how the coordinates are scaled to 80x25. The combination of calibration and scaling now make the touch coordinates match the image coordinates. A touch on the touchscreen now reports the character location on the image. This is the mode where the touchscreen data is most useful to an application.

Axis Inversion

The coordinate scaling values can be signed numbers from -32767 to +32768. If the low scale value is greater than the high value, software axis inversion is indicated. Software axis inversion is performed after any automatic hardware axis inversions directed by the calibration points. For example, the corrected hardware origin may be the upper left, but on one application screen, 1st Quadrant 1000x1000 Cartesian Coordinates may be desired with the origin in the lower left. Simply set the scaling values 0-999 and 999-0 for X and Y. The calibration points do not need to be changed.

Each axis may also be inverted by selecting the Orientation command on the Scaling submenu.

Saving the Setup

Once all controller parameters have been configured with the SMARTSET program, the Load/Save Setup command may be used to load and save the settings to disk and/or nonvolatile RAM (NVRAM).

Saving settings to NVRAM will change the controller's power-on defaults, unless you have an AccuTouch controller which is booting from jumper settings (J7 is installed).

Saving settings to disk will allow other controllers to be quickly programmed to the identical settings.

Type "L" to jump to the Load/Save Setup submenu. Select Save for the Data Direction, and To Disk for the Destination. Move the highlighting to Setup and press [Enter]. The status line says it is creating or updating the "SmartSet configuration file".

Before we demonstrate restoring the settings from disk, let's change the settings by using the Reset command to restore all defaults. Press "R" to jump to the Reset Menu. Use [F1] to display the differences between Soft Reset and Hard Reset. Execute a Hard Reset. Depending on OEM options, a Hard Reset may take a few seconds. Watch the status line until it reports Idle. Scroll through the menus and verify that the calibration, scaling, modes, and all other parameters are reset.

Now select Load From Disk on the Load/Save Setup submenu. Move the highlighting to Setup, and press [Enter]. Scroll through the menus and verify that the calibration, scaling, modes, and all other parameters are restored.

The same procedure is used for loading and saving all parameters from/to NVRAM. Simply change the Data Source/Destination to NVRAM.

Second Calibration/Scaling

The SmartSet controllers can also store a secondary set of calibration and scaling values in NVRAM which can be recalled at any time.

Create a secondary set of calibration and scaling values by changing the values on the Calibration and Scaling submenus. Now select Save to Disk, highlight 2nd Calib/Scaling, and press [Enter]. The modified calibration and scaling values are added to the SMARTSET.DAT file.

Restoring the Setup from Disk will restore the primary calibration and scaling values. Selecting Load From Disk and 2nd Calib/Scaling will replace the primary values with the secondary values saved on disk.

The same procedure is used for loading and saving the secondary values from/to NVRAM. Simply change the Data Source/Destination to NVRAM.

Programming Multiple Controllers

In most applications, more than one touchscreen will be used. The SMARTSET program includes a feature for quickly configuring power-on defaults on multiple controllers.

Once a setup has been saved to disk (and optionally secondary calibration and scaling values), the Program Controller command on the Load/Save Setup submenu can be used. In one operation, this command loads the setup from disk and saves it to the controller's NVRAM. The controller can then be replaced with another controller, and identical settings programmed in one operation.

Where To Go From Here

From the Main Menu, type "R" and select Soft Reset to restore the default settings of the controller. You may now exit the SMARTSET program by selecting Exit from the Main Menu.

In the next chapter, we will discuss how data is communicated to the SmartSet controllers. The ASCII Setup portion of the SMARTSET program will be used to study this communication and the command structure.

Chapter 6 then describes the commands supported by the SmartSet controllers. The commands in the SMARTSET program correspond to the controller command set.