Elo Touch CarrollTouch Programmer's Guide

Download

TouchSystem

Programmer's

Guide

CARROLLTOUCH

TOUCHPRODUCTS

ancompanyAMP

Touch System Programmer’s Guide

CARROLL TOUCH

TOUCH PRODUCTS

an AMP company

August 1996 Part #: 2970-0011-01-Rev A

Trademarks

Smart-Frame is a trademark of Carroll Touch, Round Rock, Texas.

IBM and PC are trademarks of International Business Machines Corporation.

All other brands and product names are trademarks of their respective owners.

Disclaimer

Carroll Touch has a policy of continually improving products as new technology becomes available. Carroll Touch reserves the right to make changes and improvements to the specifications of this equipment at any time without notice.

Carroll Touch has made every attempt to ensure that the information in this document is accurate and complete. Carroll Touch assumes no liability for any damages that result from the use of this manual or the equipment it documents. Carroll Touch reserves the right to make changes to this document at any time without notice.

CARROLL TOUCH Table of Contents

Welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

1. Introduction to Infrared Touch Systems . . . . . . . 1-1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Touch Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Touch Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Interpolating Touch Coordinates. . . . . . . . . . . . . . . . . . . . 1-3

Reporting Touch Coordinates . . . . . . . . . . . . . . . . . . . . . . 1-4

Failed Beams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Criteria for Failing a Beam . . . . . . . . . . . . . . . . . . . . . 1-5

Failed Beam Timing Parameters . . . . . . . . . . . . . . . . . 1-5

Criteria for Unfailing a Beam . . . . . . . . . . . . . . . . . . . 1-7

Failed Beam Reports . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7

2. Introduction to Guided Wave Touch Systems . . . 2-1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Touch Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Touch Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

EEPROM File and Parameters . . . . . . . . . . . . . . . . . . . . . 2-3

3. General Programming Issues . . . . . . . . . . . . . . . . 3-1

Hardware Configurations . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Built-In Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

External Controllers. . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Application Program Interface . . . . . . . . . . . . . . . . . . 3-4

Calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

Floating Point Calibration Program Design . . . . . . . . 3-7

Floating Point Calibration Examples. . . . . . . . . . . . . . 3-8

HBC I/O Registers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9

Sending a Touch Command to the HBC . . . . . . . . . . . 3-9

Receiving Touch Data from the HBC . . . . . . . . . . . . 3-10

Polling Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10

Interrupt Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11

Resetting the HBC. . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11

Table of Contents CARROLL TOUCH

4. Smart-Frame Protocol . . . . . . . . . . . . . . . . . . . . . . 4-1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

SFP and SFP-II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Types of SFP Commands . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Communication Commands . . . . . . . . . . . . . . . . . . . . 4-3

Reporting Method Commands. . . . . . . . . . . . . . . . . . . 4-3

Touch Mode Commands . . . . . . . . . . . . . . . . . . . . . . . 4-4

Information Request Commands. . . . . . . . . . . . . . . . . 4-5

System Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5

Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6

Touch System Initialization. . . . . . . . . . . . . . . . . . . . . . . . 4-7

Resetting the Touch System . . . . . . . . . . . . . . . . . . . . 4-7

Power Cycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7

Dedicated Reset Signal . . . . . . . . . . . . . . . . . . . . . 4-7

Break (Hardware Detected). . . . . . . . . . . . . . . . . . 4-7

HBC Hardware Reset Register . . . . . . . . . . . . . . . 4-8

Break (Firmware Detected) . . . . . . . . . . . . . . . . . . 4-8

Reset (45H) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8

Performing the Autobaud/Autoparity Sequence . . . . . 4-8

Checking for Touch System Errors . . . . . . . . . . . . . . . 4-9

Setting the Reporting Method and Touch Mode . . . . 4-10

Touch System Initialization Examples . . . . . . . . . . . . . . 4-10

Using Autobaud/Autoparity . . . . . . . . . . . . . . . . . . . 4-10

Using a Fixed Baud Rate. . . . . . . . . . . . . . . . . . . . . . 4-11

Using the HBC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11

Using an SBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12

Compatibility Issues/Programming Tips. . . . . . . . . . . . . 4-12

Number of Processors Independence . . . . . . . . . . . . 4-13

Firmware Version Independence. . . . . . . . . . . . . . . . 4-13

Frame Size Independence . . . . . . . . . . . . . . . . . . . . . 4-13

Touch System Response Time Independence . . . . . . 4-13

SFP Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14

Autobaud/Autoparity Delay Time. . . . . . . . . . . . . . . 4-14

Maximum Command Completion Time . . . . . . . . . . 4-14

Reset Time/Diagnostics Completion Time . . . . . . . . 4-14

SFP Programming Examples. . . . . . . . . . . . . . . . . . . . . . 4-14

5. Smart-Frame Protocol II . . . . . . . . . . . . . . . . . . . . 5-1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

Extensibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

Modal Protocols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

Backward Compatibility . . . . . . . . . . . . . . . . . . . . . . . 5-4

Types of SFP-II Functions. . . . . . . . . . . . . . . . . . . . . . . . . 5-5

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5

CARROLL TOUCH Table of Contents

Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6

Validation Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

Interpretation Layer. . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7

Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8

Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8

Validation Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9

Interpretation Layer. . . . . . . . . . . . . . . . . . . . . . . . . . 5-10

Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10

Reporting Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11

Report Transfer Mode . . . . . . . . . . . . . . . . . . . . . . . . 5-11

Error Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12

Invalid Command Number . . . . . . . . . . . . . . . . . . . . 5-12

Invalid Parameter Value . . . . . . . . . . . . . . . . . . . . . . 5-13

Unsupported Feature . . . . . . . . . . . . . . . . . . . . . . . . . 5-13

Invalid Byte Count. . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14

Not Enough Parameters. . . . . . . . . . . . . . . . . . . . . . . 5-17

Too Many Parameters . . . . . . . . . . . . . . . . . . . . . . . . 5-17

Overloaded Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18

Shared Parameters between SFP and SFP-II. . . . . . . . . . 5-19

Touch Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19

Report Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20

6. Touch Application Program Interface (TAPI) . . 6-1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

Installing a TAPI Driver . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3

SBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3

HBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4

RS-232 Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4

Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6

Determining if a TAPI Driver Is Installed. . . . . . . . . . . . . 6-7

Calling TAPI Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7

Touch System Initialization Using a TAPI Driver . . . . . . 6-8

TAPI Programming Examples. . . . . . . . . . . . . . . . . . . . . . 6-9

7. CTKERN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2

Calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2

Scaling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4

Touch Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5

Calibration and Scaling Examples. . . . . . . . . . . . . . . . . . . 7-5

Temporal Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8

Methods for Interfacing CTKERN and an Application

Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9

Polling Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9

Interrupt Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9

iii

Table of Contents CARROLL TOUCH

Loading the CTKERN Driver . . . . . . . . . . . . . . . . . . . . . . 7-9

Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9

Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10

Determining If the CTKERN Driver Is Installed . . . . . . 7-13

Calling CTKERN Functions . . . . . . . . . . . . . . . . . . . . . . 7-13

CALIB.EXE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13

Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14

Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15

Calibrate Mono, EGA, VGA Video Modes . . . . 7-16

Calibrate Other Video Modes . . . . . . . . . . . . . . . 7-17

Edit Entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18

Delete Entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18

CALIB.DAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-20

CTKERN Programming Examples . . . . . . . . . . . . . . . . . 7-20

8. Dynamic Link Library (DLL) Functions . . . . . . . 8-1

Calling Windows Driver DLL Functions . . . . . . . . . . . . . 8-2

A. Smart-Frame Protocol Command Reference . . . A-1

Add_Exit_Point_Modifier (29H) ()) . . . . . . . . . . . . . .A-5

Clear_Touch_Report_Buffer (3DH) (=) . . . . . . . . . . .A-6

Continuous_Mode (27H) (’) . . . . . . . . . . . . . . . . . . . .A-7

Coordinate_Reporting (23H) (#) . . . . . . . . . . . . . . . . .A-8

Echo_Off (21H) (!) . . . . . . . . . . . . . . . . . . . . . . . . . .A-10

Echo_On (20H) (SPACE) . . . . . . . . . . . . . . . . . . . . .A-11

Enter_Point_Mode (25H) (%) . . . . . . . . . . . . . . . . . .A-12

Exit_Point_Mode (28H) (() . . . . . . . . . . . . . . . . . . . .A-13

Get_Configuration_Report (33H) (3) . . . . . . . . . . . .A-14

Get_Error_Report (32H) (2) . . . . . . . . . . . . . . . . . . .A-15

Get_Failed_Beam_Report (36H) (6). . . . . . . . . . . . .A-19

Get_Firmware_Version_Report (34H) (4) . . . . . . . .A-21

Get_Frame_Size_Report (37H) (7) . . . . . . . . . . . . . .A-23

Get_One_Report (46H) (F) . . . . . . . . . . . . . . . . . . . .A-24

Get_State_Report (47H) (G) . . . . . . . . . . . . . . . . . . .A-25

Hardware_Flow_Control_Off (42H) (B). . . . . . . . . .A-27

Hardware_Flow_Control_On (41H) (A). . . . . . . . . .A-28

Report_Transfer_Off (43H) (C) . . . . . . . . . . . . . . . .A-29

Report_Transfer_On (44H) (D). . . . . . . . . . . . . . . . .A-30

Reset (45H) (E) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-31

Run_Diagnostics (3AH) (:) . . . . . . . . . . . . . . . . . . . .A-32

Scan_Reporting (22H) (”) . . . . . . . . . . . . . . . . . . . . .A-33

Software_Reset (3CH) (<). . . . . . . . . . . . . . . . . . . . .A-34

SwitchToSFP-II (65H) . . . . . . . . . . . . . . . . . . . . . . .A-35

Touch_Scanning_Off (2BH) (+) . . . . . . . . . . . . . . . .A-37

CARROLL TOUCH Table of Contents

Touch_Scanning_On (2AH) (*) . . . . . . . . . . . . . . . .A-38

Tracking_Mode (26H) (&) . . . . . . . . . . . . . . . . . . . .A-39

B. Smart-Frame Protocol II Function Reference . . B-1

GetConfiguration (11H) . . . . . . . . . . . . . . . . . . . . . . .B-3

GetCoordinateRanges (10H) . . . . . . . . . . . . . . . . . . . . B-8

GetProtocolVersion (65H). . . . . . . . . . . . . . . . . . . . .B-10

GetTouchState (01H). . . . . . . . . . . . . . . . . . . . . . . . . B-12

SetReportProperties (21H) . . . . . . . . . . . . . . . . . . . . B-14

SetReportTransferMode (22H) . . . . . . . . . . . . . . . . . B-19

SetTouchModes (20H) . . . . . . . . . . . . . . . . . . . . . . . B-24

SwitchToClassicSFP (64H). . . . . . . . . . . . . . . . . . . . B-29

C. TAPI Function Reference . . . . . . . . . . . . . . . . . . . C-1

CheckForReports (3) . . . . . . . . . . . . . . . . . . . . . . . . . . C-3

GetCommunicationParameters (4) . . . . . . . . . . . . . . . C-4

GetReports (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-6

GetTAPIDriverConfiguration (6) . . . . . . . . . . . . . . . .C-7

GetUserEventHandlerParameters (8) . . . . . . . . . . . . . C-8

Reset (0). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-9

SendCommand (1). . . . . . . . . . . . . . . . . . . . . . . . . . . C-10

SetCommunicationParameters (5). . . . . . . . . . . . . . . C-11

SetSBCFrameSize (40H). . . . . . . . . . . . . . . . . . . . . . C-13

SetUserEventHandler (7). . . . . . . . . . . . . . . . . . . . . .C-14

D. CTKERN Function Reference . . . . . . . . . . . . . . . D-1

GetCalibrationTableEntry (7) . . . . . . . . . . . . . . . . . . .D-5

GetCommunicationParameters (22) . . . . . . . . . . . . . .D-7

GetCTKERNDriverConfiguration (20). . . . . . . . . . . .D-8

GetCurrentCalibrationModeAndParameters (5) . . . . .D-9

GetCurrentScalingModeAndParameters (10) . . . . . .D-10

GetTAPIDriverConfiguration (19) . . . . . . . . . . . . . .D-11

GetTemporalFilterModeAndParameters (16) . . . . . .D-12

GetTouchState (1) . . . . . . . . . . . . . . . . . . . . . . . . . . .D-13

GetTouchSystemStatus/Configuration (17) . . . . . . .D-15

GetUserEventHandlerModeAndParameters (25) . . .D-16

GetZ-AxisScalingModeAndParameters (13) . . . . . .D-17

Reset (0). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-18

SendSmart-FrameProtocolCommand

AndGetReport (18) . . . . . . . . . . . . . . . . . . . . . . . .D-20

SetCalibrationMode (3). . . . . . . . . . . . . . . . . . . . . . .D-22

SetCalibrationParameters (4). . . . . . . . . . . . . . . . . . .D-23

SetCalibrationTableEntry (6) . . . . . . . . . . . . . . . . . .D-24

SetCommunicationParameters (21). . . . . . . . . . . . . .D-26

SetScalingMode (8). . . . . . . . . . . . . . . . . . . . . . . . . .D-28

Table of Contents CARROLL TOUCH

SetScalingParameters (9). . . . . . . . . . . . . . . . . . . . . .D-29

SetTemporalFilterMode (14). . . . . . . . . . . . . . . . . . .D-31

SetTemporalFilterParameters (15) . . . . . . . . . . . . . .D-34

SetTouchState (2) . . . . . . . . . . . . . . . . . . . . . . . . . . .D-36

SetUserEventHandlerMode (23) . . . . . . . . . . . . . . . .D-37

SetUserEventHandlerParameters (24). . . . . . . . . . . .D-39

SetZ-AxisScalingMode (11) . . . . . . . . . . . . . . . . . . .D-40

SetZ-AxisScalingParameters (12) . . . . . . . . . . . . . . .D-41

E. Dynamic Link Library (DLL) Function Reference E-1

DisableMouse (11) . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3

DisableTouch (12). . . . . . . . . . . . . . . . . . . . . . . . . . . . E-4

EnableMouse (9) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-5

EnableTouch (10) . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-6

GetMouseInfo (13) . . . . . . . . . . . . . . . . . . . . . . . . . . . E-7

GetTemporalFilterInfo (18). . . . . . . . . . . . . . . . . . . . . E-8

GetTouchInfo (14). . . . . . . . . . . . . . . . . . . . . . . . . . . . E-9

GetTouchStateandCoord (5) . . . . . . . . . . . . . . . . . . . E-10

InitializeTouch (16). . . . . . . . . . . . . . . . . . . . . . . . . . E-11

SetCalibInfo (7). . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-12

SetTemporalFilterInfo (17) . . . . . . . . . . . . . . . . . . . . E-14

SetTouchEvents (8) . . . . . . . . . . . . . . . . . . . . . . . . . . E-16

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .GL-1

Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IN-1

CARROLL TOUCH Table of Contents

List of Figures

Figure 1-1. Infrared Touch Frame . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Figure 1-2. Beam Averaging - Example 1 . . . . . . . . . . . . . . . . . . 1-3

Figure 1-3. Beam Averaging - Example 2 . . . . . . . . . . . . . . . . . . 1-4

Figure 2-1. Guided Wave Touch Screen . . . . . . . . . . . . . . . . . . . 2-2

Figure 3-1. Built-In Smart-Frame Controller Hardware . . . . . . . 3-2

Figure 3-2. RS-232 Controller Hardware (Modular IR Touch

Systems) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Figure 3-3. SBC and HBC Hardware (Modular IR Touch

Systems) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

Figure 3-4. Touch Control Software . . . . . . . . . . . . . . . . . . . . . . . 3-5

Figure 3-5. Touch Calibration Screen . . . . . . . . . . . . . . . . . . . . . 3-6

Figure 7-1. Touch System to Application Communication . . . . . 7-3

Figure 7-2. Calibration Mode Fixed or Automatic and Scaling

Mode Fixed or Automatic . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6

Figure 7-3. Calibration Mode Fixed or Automatic and Scaling

Mode Disabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7

Figure 7-4. Calibration Mode Disabled and Scaling Mode

Fixed or Automatic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7

Figure 7-5. Calibration Mode Disabled and Scaling Mode

Disabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8

Figure 7-6. Calibration Main Menu Screen . . . . . . . . . . . . . . . . 7-15

Figure 7-7. Calibration Menu Screen . . . . . . . . . . . . . . . . . . . . . 7-16

Figure 7-8. Calibration Target Screen . . . . . . . . . . . . . . . . . . . . 7-16

Figure 7-9. Calibration Other Video Mode Screen #1 . . . . . . . . 7-17

Figure 7-10. Calibration Other Video Mode Screen #2 . . . . . . . 7-17

Figure 7-11. Calibration Other Video Mode Screen #3 . . . . . . . 7-18

Figure 7-12. Calibration Manual Edit Menu Screen . . . . . . . . . 7-19

Figure 7-13. Calibration Exit Prompt Screen . . . . . . . . . . . . . . . 7-19

Figure B-1. Flow Diagram for Report Transfer Mode . . . . . . . . B-19

Figure D-1. Temporal Filter Spatial Box Size . . . . . . . . . . . . . .D-32

vii

Table of Contents CARROLL TOUCH

viii

CARROLL TOUCH Table of Contents

List of Tables

Table 1-1. Failed Beam Timing Parameters . . . . . . . . . . . . . . . . . 1-5

Table 3-1. HBC I/O Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9

Table 3-2. Status Register Bit 0 Values . . . . . . . . . . . . . . . . . . . 3-10

Table 3-3. Status Register Bit 1 Values . . . . . . . . . . . . . . . . . . . 3-10

Table 4-1. SFP Communication Commands . . . . . . . . . . . . . . . . 4-3

Table 4-2. SFP Reporting Method Commands . . . . . . . . . . . . . . 4-4

Table 4-3. SFP Touch Mode Commands . . . . . . . . . . . . . . . . . . . 4-4

Table 4-4. SFP Information Request Commands . . . . . . . . . . . . . 4-5

Table 4-5. SFP System Commands . . . . . . . . . . . . . . . . . . . . . . . 4-6

Table 4-6. SFP Default Settings . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9

Table 6-1. TAPI Error Messages and Explanations . . . . . . . . . . . 6-6

Table 7-1. CTKERN Error Messages . . . . . . . . . . . . . . . . . . . . . 7-10

Table A-1. SFP Commands in Alphabetical Order . . . . . . . . . . .A-3

Table A-2. SFP Commands in Numerical Order . . . . . . . . . . . . .A-4

Table A-3. Smart-Frame Protocol Error Report Error Codes . . .A-16

Table A-4. Touch System Default Settings . . . . . . . . . . . . . . . .A-34

Table B-1. SFP-II Functions in Alphabetical Order . . . . . . . . . . . B-2

Table B-2. SFP-II Functions in Numerical Order . . . . . . . . . . . .B-2

Table B-3. ComponentTypes, AttributeTags and

AttributeValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-5

Table C-1. TAPI Functions in Alphabetical Order . . . . . . . . . . . . C-2

Table C-2. TAPI Functions in Numerical Order . . . . . . . . . . . . . C-2

Table C-3. Typical BL/BH Register Contents . . . . . . . . . . . . . . . C-7

Table D-1. CTKERN Functions in Alphabetical Order . . . . . . . .D-3

Table D-2. CTKERN Functions in Numerical Order . . . . . . . . . .D-4

Table D-3. Typical BX Register Contents . . . . . . . . . . . . . . . . . .D-8

Table D-4. Typical BL/BH Register Contents . . . . . . . . . . . . . .D-11

Table E-1. Windows Driver DLL Functions in

Alphabetical Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2

Table E-2. Windows Driver DLL Functions in

Numerical Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2

Table E-3. Definition of Touch Events . . . . . . . . . . . . . . . . . . . E-17

Table of Contents CARROLL TOUCH

WelcomeWelcome

s computers become a part of daily life, a technology that makes

them easier to use has become a necessity. Carroll Touch provides

the solution through the power of touch.

Thank you for your purchase of a Carroll Touch product and welcome to Carroll Touch.

Purpose

Audience

Organization

This Programmer’s Guide is designed to:

• Give an overview of the touch technologies used by Carroll Touch,

with a particular emphasis on hardware and software information (such as calibration and initialization) needed by programmers.

• Define the use and functions of the Smart-Frame Protocol, the

Smart-Frame Protocol II, the Touch Application Program Interface (TAPI) driver, the CTKERN application interface, and the Windows driver dynamic link libraries (DLLs).

This guide is designed for the programmer or software engineer who integrates Carroll Touch touch systems with host computer systems.

Chapter 1, “Introduction to Infrared Touch Systems,” is an overview of Carroll Touch infrared touch system hardware and operating principles.

Touch System Programmer’s Guide xi

Welcome CARROLL TOUCH

Chapter 2, “Introduction to Guided Wave Touch Systems,” is an overview of Carroll Touch guided wave touch system hardware and operating principles.

Chapter 3, “General Programming Issues,” includes information on programming topics that apply to all Carroll Touch touch systems, such as calibration and HBC I/O registers.

Chapter 4, “Smart-Frame Protocol,” gives an overview of the SFP firmware protocol, including a discussion of command and report types, initialization, timing, and programming tips and examples.

Chapter 5, “Smart-Frame Protocol II,” gives an overview of the SFP-II firmware protocol, which extends the capabilities of SFP by offering support of z-axes and higher resolution. Explanations of command and report formats are included.

Chapter 6, “Touch Application Program Interface (TAPI),” includes an overview of the TAPI software functions, and TAPI driver installation and initialization information.

Chapter 7, “CTKERN,” includes an overview of the CTKERN software functions, CTKERN driver installation, and parameters. It also discusses the operation of the CTKERN calibration program (CALIB.EXE).

Chapter 8, “Dynamic Link Library (DLL) Functions,” describes how to use the DLL function calls to the Carroll Touch Windows driver.

Appendix A, “Smart-Frame Protocol Command Reference,” gives the specifications for each SFP command and report.

Appendix B, “Smart-Frame Protocol II Function Reference,” gives the specifications for each SFP-II function.

Appendix C, “TAPI Function Reference,” gives the specifications for each TAPI function.

Appendix D, “CTKERN Function Reference,” gives the specifications for each CTKERN function.

Appendix E, “Dynamic Link Library (DLL) Function Reference,” gives the specifications for each Windows driver DLL.

xii Touch System Programmer’s Guide

CARROLL TOUCH Welcome

Conventions

For clarity, this guide uses certain conventions to visually distinguish different types of information. The conventions are:

• Bold is used to emphasize a word or phrase, including definitions

of important concepts.

MALL CAPITAL LETTERS (such as SPACE or ENTER) indicates a

• S

key on the keyboard.

• Courier font indicates file names, directory names, messages

displayed by the computer, parameters in command lines, and information to be typed by the user.

• Italics indicate a command, function name, or mode (such as

Debug Mode).

• Reports (such as the Touch Coordinate Report) and menus (such as

the Configuration Menu) use initial capital letters.

• Courier italic font indicates a variable in a command line

for which you must substitute a value.

• Hexadecimal numbers in text are identified with capital H; for

example, 1BH is the hexadecimal value 1B. Command and report formats and examples reproduce numbers as they appear on the screen and thus do not use the H convention.

• Information of particular importance or actions that may have

undesirable results if performed improperly are included under the headings

Note and Caution.

Touch System Programmer’s Guide xiii

Welcome CARROLL TOUCH

xiv Touch System Programmer’s Guide

Introduction to

Introduction to Infrared Touch

Infrared Touch Systems

Systems

his chapter gives an overview of Carroll Touch scanning infrared

touch systems, and covers the following topics:

• Overview.

• Touch Frames.

• Touch Controllers.

• Interpolating Touch Coordinates.

• Reporting Touch Coordinates.

• Failed Beams.

Touch System Programmer’s Guide 1-1

Chapter 1 - Introduction to Infrared Touch Systems CARROLL TOUCH

Overview

A Carroll Touch infrared touch system consists of a touch controller and touch frame or a combined touch frame and controller. The touch system uses scanning infrared (IR) beam technology to detect operator input. Generating an invisible grid of IR light beams in front of the host video display screen, the touch system reports touch input when the IR light field is interrupted by a stylus (typically a finger). This input can be used by a touch application just as similar applications use input from pointing devices such as a mouse, light pen or trackball.

Touch Frames

The typical Carroll Touch touch frame is a thin, flat rectangle comprised of four joined printed circuit boards (PCBs). Two adjacent PCBs contain arrays of IR light emitting diodes (LEDs), while the other two PCBs contain arrays of phototransistor/receivers. Each IR LED and the phototransistor opposite it is called an opto-pair. The IR LED of each opto-pair emits an IR light beam that is detected by the phototransistor. The x-axis and y-axis arrays of opto-pairs are pulsed sequentially to create a grid of IR beams, as shown in Figure 1-1.

Figure 1-1. Infrared Touch Frame A beam, or a beam pair, consists of an IR LED and phototransistor

directly across from each other in the touch frame.

Touch Controller

The touch controller is the circuitry required to create and monitor the IR grid. A sequence of electrical pulses is sent to the LEDs to create the

1-2 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 1 - Introduction to Infrared Touch Systems

grid of IR beams in front of the video display surface. This grid of IR beams is the touch active area.

When a stylus enters the touch active area, light beams are obstructed at a particular location on the grid. The touch frame then transmits to the controller a list that indicates which beams have been interrupted. The controller converts this list into an x, y coordinate that identifies the location of the touch. The x, y coordinate data is transmitted to the host processor via the PC bus or the RS-232 serial port and is then processed and used by the application program.

Interpolating Touch Coordinates

To achieve finer resolution than the physical IR beam grid provides, Carroll Touch IR touch systems interpolate a virtual beam between each pair of physical beams. The physical beams are assigned even numbers (0, 2, 4, and so on). The virtual beams are assigned odd numbers (1, 3, 5, and so on). The combination of physical beams and virtual beams results in a set of logical beams.

The coordinate system formed by the logical beams is called the logical coordinate system. The origin of the logical coordinate system (0, 0) is located in the upper left corner of the display. When multiple beams are interrupted, the touch system averages them and reports one x, y logical coordinate pair to the host, a process known as beam averaging. Examples of beam averaging are shown in Figures 1-2 and 1-3.

02 04 0806 1000

00 02 04 06 08

4,4

Figure 1-2. Beam Averaging - Example 1 In Figure 1-2, beams 2, 4, and 6 are interrupted on both the x- and

y-axes. The logical coordinate pair reported to the host is 4, 4.

Touch System Programmer’s Guide 1-3

Chapter 1 - Introduction to Infrared Touch Systems CARROLL TOUCH

02 04 0806 1000

00 02 04 06 08

5,5

Figure 1-3. Beam Averaging - Example 2 In Figure 1-3, beams 2, 4, 6, and 8 are interrupted on both the x- and

y-axes. The logical coordinate pair reported to the host is 5, 5.

Reporting Touch Coordinates

For a touch to be reported, at least one x beam and one y beam must be interrupted. If no beams are interrupted in either the x- or y-axis, the touch is ignored.

The lowest logical coordinate reported for any axis on any touch frame is zero. The maximum logical coordinate that may be reported for a given touch frame axis may be determined from the number of physical beams on that touch frame axis as follows:

Failed Beams

Maximum logical coordinate = 2 x (number of physical beams - 1)

For example, on a frame that has 40 x-axis beams and 30 y-axis beams, the maximum logical coordinates for the frame are:

Maximum logical x coordinate = 2 x (40 - 1) = 78 Maximum logical y coordinate = 2 x (30 - 1) = 58

Therefore, the reported coordinates would range from 0 to 78 on the x-axis and from 0 - 58 on the y-axis.

Carroll Touch touch systems have incorporated into their firmware a mechanism for detecting defective beam pairs and removing them from consideration when determining the location of a stylus within the touch frame. This failed beam mechanism provides a measure of fault tolerance for the touch system so that, in the event of an opto-component

1-4 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 1 - Introduction to Infrared Touch Systems

failure, the touch system simply suffers a localized loss of resolution in one coordinate axis, rather than being completely inoperable.

Criteria for Failing a Beam

The touch system considers a beam to be interrupted if the IR light level at the phototransistor is below a threshold level. A beam is considered failed if it appears to be interrupted for a given period of time.

The touch system detects failed beams:

• During power up.

• When the touch system is reset using the SFP Reset (45H) command or BREAK.

• When the touch system diagnostics are run using the SFP Run_Diagnostics (3AH) command.

• While the touch system is scanning the beams during normal operation.

In the first three cases, the time required to fail a beam is less than one second. In the last case, the time required to fail a beam is determined by the failed beam timing parameters.

The touch system maintains a table of beams that have been determined to have failed.

Failed Beam Timing Parameters

The values for the various failed beam timing parameters are different for ASIC-based touch systems and non-ASIC-based touch systems, as shown in Table 1-1.

Table 1-1. Failed Beam Timing Parameters

Parameter

Valid Touch Fail Time 59 - 62 sec. 225 - 270 sec. Non-Contiguous Touch Fail Time 2.2 - 4.4 sec. 10 - 20 sec.

ASICBased

Non-ASICBased

Single Axis Touch Fail Time 2.2 - 4.4 sec. 10 - 20 sec. Unfail Time 2.2 - 4.4 sec. 10 - 20 sec.

A touch system is probably ASIC-based if it is a modular touch system, or an invasively integrated Smart-Frame with a five switch Communication Parameters jumper block on the frame. If you are

Touch System Programmer’s Guide 1-5

Chapter 1 - Introduction to Infrared Touch Systems CARROLL TOUCH

unsure whether your system is ASIC-based and if you need to know the values of the failed beam timing parameters, use the touch system diagnostics software (CTDIAG) to observe the amount of time required to fail beams that are interrupted by a valid touch.

Table 1-1 gives a range of values rather than a specific value because the touch system firmware checks for failed beams at a regular interval (2.2 seconds or 10 seconds). A beam that appears to be interrupted just after the firmware checks takes longer to fail than a beam that appears to be interrupted just before the firmware checks.

Note

Custom touch systems may have different values for the failed beam timing parameters from those given in Table 1-1.

During normal operation, with the touch system scanning the beams, a beam is considered failed if it is interrupted for the amount of time specified by the Valid Touch Fail Time parameter and if the pattern of interrupted beams appears to indicate a valid touch with a single stylus. (A touch is considered valid if there appears to be one and only one region of contiguous interrupted beams in each coordinate axis.) Thus, a single stylus that remains stationary within the touch screen for the Valid Touch Fail Time causes beams to be failed.

If beams are interrupted on only one axis of the touch frame, the interrupted beams are failed in the amount of time specified by the Single Axis Touch Fail Time parameter.

For any other pattern of interrupted beams, such as more than one region of interrupted beams in an axis, the interrupted beams are failed in the amount of time specified by the Non-Contiguous Touch Fail Time parameter. Thus, multiple styli that remain stationary for longer than the Non-Contiguous Touch Fail Time result in beams being failed, as do non-contiguous touches.

For example, if you place a piece of tape over the opto-devices in one axis of the touch screen, the beams obstructed by the tape are determined by the touch system firmware to be failed and are added to the failed beam table only after the amount of time specified by the Invalid Touch Fail Time parameter has elapsed. If you then remove the tape, the time specified in the Unfail Time parameter must elapse before the beams are considered unfailed by the touch system firmware.

1-6 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 1 - Introduction to Infrared Touch Systems

Criteria for Unfailing a Beam

If a failed beam appears not to be interrupted for the amount of time specified by the Unfail Time parameter, it is unfailed and removed from the failed beam table by the touch system firmware.

Failed Beam Reports

Two SFP commands can be used to generate reports related to the failed beam status of the touch system: Get_Error_Report (32H) and Get_Failed_Beam_Report (36H). See Appendix A, “Smart-Frame Protocol Command Reference,” for details on these commands.

Touch System Programmer’s Guide 1-7

Chapter 1 - Introduction to Infrared Touch Systems CARROLL TOUCH

1-8 Touch System Programmer’s Guide

Introduction to

Introduction to Guided Wave

Guided Wave Touch Systems

Touch Systems

his chapter gives an overview of Carroll Touch guided wave touch systems and covers the following topics:

• Overview.

• Touch Screens.

• Touch Controllers.

• EEPROM File and Parameters.

Touch System Programmer’s Guide 2-1

Chapter 2 - Introduction to Guided Wave Touch Systems CARROLL TOUCH

Overview

A Carroll Touch guided wave touch system consists of a touch controller and touch screen. The touch system uses guided acoustic wave (GW) technology to detect operator input for a variety of applications. Generating invisible acoustic waves, the touch system reports touch input when the wave motion is attenuated by a stylus (typically a finger). This input can be used by a touch application just as similar applications use input from pointing devices such as a mouse, light pen or trackball.

Touch Screens

Guided acoustic wave technology is based on transmitting acoustic waves through a glass overlay placed over the display surface. A transducer mounted on the edge of the glass emits an acoustic wave. The wave travels along the reflector array, is redirected across the overlay to the reflecting edge, and returns to the array where it is reflected back to the transducer. The first reflector will send a signal back first, then the second, and so on, as shown in Figure 2-1.

Figure 2-1. Guided Wave Touch Screen

Touch Controllers

The touch controller is the circuitry required to create and monitor the acoustic waves. A sequence of electrical pulses is sent to the transducer located in the upper left of the glass overlay to generate the acoustic waves. The area covered by the acoustic waves is the touch active area.

2-2 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 2 - Introduction to Guided Wave Touch Systems

When a stylus enters the touch active area, acoustic waves are attenuated at that location on the overlay. The touch screen then transmits to the controller information indicating the location of the attenuated waves. The controller converts this information to an x, y coordinate that identifies the location of the touch. The x, y coordinate data is transmitted to the host processor via the controller and is then processed and used by the application program.

EEPROM File and Parameters

Guided wave touch screens use an electrically erasable programmable read-only memory (EEPROM) chip. An associated file stores the values of the EEPROM parameters that control many features of the touch screen. The following EEPROM values may be displayed, modified, saved, and restored:

• Touch sensitivity.

• Touch active region.

• Transducer corner.

• Coordinate origin corner.

• Transducer orientation.

• Touch refresh time.

• No touch refresh time.

• Temporal filter space.

• Temporal filter time.

Touch System Programmer’s Guide 2-3

Chapter 2 - Introduction to Guided Wave Touch Systems CARROLL TOUCH

2-4 Touch System Programmer’s Guide

General

General Programming

Programming Issues

Issues

his chapter includes information that may apply to any Carroll

Touch touch system. It discusses the following topics:

• Hardware Configurations.

• Calibration.

• HBC I/O Registers.

Touch System Programmer’s Guide 3-1

Chapter 3 - General Programming Issues CARROLL TOUCH

Hardware Configurations

There are two major types of Carroll Touch controller configurations: built-in controllers (used in infrared Smart-Frames) and external controllers (used in modular infrared and guided wave touch systems).

Built-In Controllers

An infrared Smart-Frame touch system has controller electronics built onto the touch frame itself. The Smart-Frame touch system communicates directly with the host computer through the host serial port. Figure 3-1 illustrates the built-in Smart-Frame controller hardware.

Built-in Controller (Infrared SmartFrame)

RS-232 Cable

Host PC

Figure 3-1. Built-In Smart-Frame Controller Hardware The Smart-Frame communicates serially with the host computer using a

selectable baud rate (300, 600, 1200, 2400, 4800, 9600, 19,200 or autobaud) and parity (odd, even, none, autoparity). Default values for the standard Smart-Frame are autobaud and autoparity.

External Controllers

External controllers connect to the touch system via the Modular Digital Interface (MDI) cable in modular infrared touch systems or an 8-pin mini-DIN sensor cable in guided wave systems. The MDI cable carries digital signals, while the mini-DIN sensor cable carries analog signals.

A modular infrared touch system consists of any one of a number of IR-transparent protective bezels that house and protect a touch frame, matched with any one of three modular touch controllers: the software-

3-2 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 3 - General Programming Issues

based controller (SBC), hardware-based controller (HBC), and RS-232 controller. A guided wave touch system uses HBCs or RS-232 controllers. Figure 3-2 illustrates the RS-232 controller hardware.

External Controller (Guided Wave or Modular IR Touch Frame)

MDI/Sensor Cable

RS-232 Controller

RS-232 Cable

Host PC

Figure 3-2. RS-232 Controller Hardware (Modular IR Touch Systems) The RS-232 controller is a PCB that has its own protective housing and

requires an external power supply. The RS-232 controller communicates with the modular touch frame via the MDI cable and with the host computer through the host serial port.

The RS-232 controller communicates serially with the host computer using a selectable baud rate (300, 600, 1200, 2400, 4800, 9600, 19,200 or autobaud) and parity (odd, even, none, autoparity). Default values for the RS-232 controller are autobaud and autoparity.

Figure 3-3 illustrates the SBC and HBC controller hardware. The SBC and HBC are PCBs that fit into an expansion slot of an IBM-compatible PC, communicating with and drawing power for the touch system directly from the host through the PC bus. Both controllers communicate with the modular touch frame via the MDI cable.

The SBC and HBC communicate with the host via several I/O registers. The SBC and HBC also support interrupt-driven communications.

Touch System Programmer’s Guide 3-3

Chapter 3 - General Programming Issues CARROLL TOUCH

Modular IR Touch Frame

MDI Cable

SBC Controller

Card

Host Host PC PC

HBC Controller Card

SBC(TAPI) Driver

SBC TAPI Driver

PC Bus I/O Ports

Software Interrupt

Figure 3-3. SBC and HBC Hardware (Modular IR Touch Systems)

Application Program Interface

As shown in Figure 3-4, application programs may interface with Smart-Frame systems and systems using the HBC or RS-232 controller directly via the Smart-Frame Protocol. Smart-Frame systems and systems using the RS-232 controller are identical in terms of software. Both communicate using the Smart-Frame Protocol via the RS-232 serial interface. Systems using the HBC communicate with the application program using the Smart-Frame Protocol via the HBC I/O registers. For more details about the I/O registers, see “HBC I/O Registers” later in this chapter. The SBC cannot use the Smart-Frame Protocol directly because the SBC has no processor on board. The Smart-Frame Protocol is discussed in Chapter 4, “Smart-Frame Protocol.”

As also shown in Figure 3-4, application programs may interface with Smart-Frame systems and systems using the SBC, HBC, or RS-232 controller using the Smart-Frame Protocol via a Touch Application Program Interface (TAPI) driver. This is the same Smart-Frame Protocol used when interfacing directly to the touch system hardware.

3-4 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 3 - General Programming Issues

A P

CTKERN

P L

SMART-FRAME

PROTOCOL (VIA TAPI)

A T

SMART-FRAME

PROTOCOL (DIRECT)

O N

TAPI TAPI TAPI

RS-232

DRIVER

CTKERN

HBC

DRIVER

SBC

DRIVER

P R O G R A

SMARTFRAME

MDI

RS-232

CONTROLLER

HBC

CONTROLLER

FRAME

SBC

CONTROLLER

Figure 3-4. Touch Control Software There are three TAPI drivers: the SBC driver, the HBC driver, and the

RS-232 driver. The RS-232 driver works with Smart-Frames as well. Each TAPI driver communicates with the touch system using the hardware interface appropriate for the touch system, and with the application program using the TAPI functions that are accessed via a software interrupt. The TAPI interface is the same regardless of which TAPI driver is used. This means that you may make an application touch system hardware-independent by interfacing at the TAPI driver level rather than directly to the touch system hardware. The TAPI software functions are discussed in Chapter 6.

Figure 3-4 also shows that application programs may interface with Smart-Frame systems and systems using the SBC, HBC, or RS-232 controller via the CTKERN driver. The CTKERN driver communicates with the touch system using the TAPI driver appropriate for the touch system, and with the application program using the CTKERN functions, which are accessed via a software interrupt. CTKERN is a DOS driver that provides calibration and scaling support, as well as easy-to-use touch state reporting. CTKERN also features an installable user event handler that allows interrupt-driven communication with the application program. The CTKERN functions are discussed in Chapter 7.

Touch System Programmer’s Guide 3-5

Chapter 3 - General Programming Issues CARROLL TOUCH

TOUCH_MAX_Y

Calibration

The size of the display area of the video monitor frequently does not match the size of the touch active area of the touch frame. The touch active area is usually larger than the display area. The relationship of touch and video coordinates is shown in Figure 3-5. In addition, the display area on most video monitors may actually shift position or drift, while the touch active area remains constant. To establish and maintain alignment of the touch active area with the active display area, the touch screen must be calibrated. A calibration procedure such as the one that follows identifies the touch coordinates of the extreme outside corners of the video image displayed on the monitor and derives calibration parameters that may then be used to convert touch coordinates into video coordinates.

VIDEO_MAX_Y

TOUCH_MAX_X

VIDEO_MAX_X

Figure 3-5. Touch Calibration Screen It is strongly recommended that a calibration program be included in any

touch application or driver. Touch applications or drivers should not use hard-wired values that are specific to a particular touch frame and monitor. Use of a calibration program takes care of variations in monitor image size and location and allows touch applications to be used on different sizes of monitors and/or touch systems without modifying the touch application or driver.

This calibration must be performed at least once for each physical touch screen/video monitor pair. This procedure produces four calibration parameters that should be stored by the host computer in some form of nonvolatile storage, which lets the calibration be performed only once.

3-6 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 3 - General Programming Issues

Once calibration is completed, the host software may use the calibration parameters to convert touch coordinates into video coordinates (pixel coordinates). These may then be used in the remainder of the host software.

Some monitors do not maintain a constant video image size and placement for all of the video modes that they support. For this reason, the calibration should be performed using the same video mode as the touch application in order to assure an accurate calibration.

Floating Point Calibration Program Design

When designing a program to calibrate the touch screen, include the following steps:

1. Prompt the user to touch the upper left corner of the video screen.

2. Save the coordinates returned as TOUCH_UL_X and TOUCH_UL_Y.

3. Prompt the user to touch the lower right corner of the video screen.

4. Save the coordinates returned as TOUCH_LR_X and TOUCH_LR_Y.

A good way to prompt the user to touch the corners is to draw a border around the edge of the screen and prompt the user to touch each point using a target in the respective corner and text centered on the screen.

5. Calculate the four calibration parameters as follows:

OFFSET_X = TOUCH_UL_X OFFSET_Y = TOUCH_UL_Y

SCALE_X = VIDEO_MAX_X / (TOUCH_LR_X -

TOUCH_UL_X)

SCALE_Y = VIDEO_MAX_Y / (TOUCH_LR_Y -

TOUCH_UL_Y)

6. Save the four calibration parameters to a nonvolatile storage area, if available. If none is available, the calibration procedure must be followed each time the system is powered up.

The floating point calibration procedure is now complete. In your application program, convert the touch coordinates reported by the touch system into the equivalent video coordinates with these equations:

VIDEO_X = SCALE_X * (TOUCH_X - OFFSET_X) VIDEO_Y = SCALE_Y * (TOUCH_Y - OFFSET_Y)

Touch System Programmer’s Guide 3-7

Chapter 3 - General Programming Issues CARROLL TOUCH

You may also want to limit VIDEO_X and VIDEO_Y to the ranges defined by VIDEO_MAX_X and VIDEO_MAX_Y. It is recommended that the touch coordinates be converted to video coordinates immediately upon their receipt from the touch system, and that video coordinates be used in the remainder of the application program.

Floating Point Calibration Examples

If the coordinates resulting from calibration of a system with 640 x 480 resolution are:

TOUCH_UL_X = 10 TOUCH_UL_Y = 7

TOUCH_LR_X = 150 TOUCH_LR_Y = 110

and the system has a resolution of 640 x 480:

VIDEO_MAX_X = 639 VIDEO_MAX_Y = 479

the four calculated calibration parameters are:

OFFSET_X = 10 OFFSET_Y = 7

SCALE_X = 639 / (150 - 10) = 4.5643 SCALE_Y = 479 / (110 - 7) = 4.65

Following are three examples of how to solve for different values of VIDEO_X and VIDEO_Y:

If TOUCH_X = 7 and TOUCH_Y = 10, then:

VIDEO_X = 4.5643 * (10 - 10) = 0 VIDEO_Y = 4.65 * (7 - 7) = 0

If TOUCH_X = 60, and TOUCH_Y= 80, then:

VIDEO_X = 4.5643 * (60 - 10) = 228 VIDEO_Y = 4.65 * (80 - 7) = 339

If TOUCH_X = 150, and TOUCH_Y= 110, then:

VIDEO_X = 4.5643 * (150 - 10) = 639 VIDEO_Y = 4.65 * (110 - 7) = 479

3-8 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 3 - General Programming Issues

HBC I/O Registers

Overview

The HBC communicates with the PC through the PC bus via three consecutive I/O registers. The base address of these I/O registers is set by the I/O address jumpers on the HBC board, and may be set in increments of 16 to any I/O address between 200H and 3F0H inclusive. The three I/O registers are defined in Table 3-1.

Table 3-1. HBC I/O Registers

I/O Address Name

I/O Base Address

I/O Base Address + 1

I/O Base Address +2

The touch controller may be used in polling mode or in interrupt mode. In polling mode, the application software must check the Status Register before sending or receiving data. In interrupt mode, the application software must check the Status Register when sending data to the touch controller, but may install an interrupt handler to receive data from the touch controller. The interrupt number used is set by the interrupt number jumpers on the HBC board, as described in the HBC installation instructions. When using polling mode, set these jumpers to none to prevent the HBC from generating any interrupts.

Data Register R/W Used to send commands to

Status Register

Hardware Reset Register

Read/ Write

and receive reports from the touch controller.

R Used to check the touch

controller communications status (i.e. ready to receive commands, reports available).

W Used to reset the touch

controller.

Description

Sending a Touch Command to the HBC

The procedure used to send a touch command to the HBC is the same for both interrupt mode and polling mode.

Before sending a command to the touch controller, you must first perform an I/O read of the Status Register (Base Address + 1). Bit 0 of the Status Register indicates whether the touch controller is ready to

Touch System Programmer’s Guide 3-9

Chapter 3 - General Programming Issues CARROLL TOUCH

receive a command or whether it is busy. Table 3-2 shows the values of Bit 0 of the Status Register.

Table 3-2. Status Register Bit 0 Values

Bit 0 Description

0 Touch controller ready to receive command. 1 Touch controller busy.

If Bit 0 of the Status Register is 0, you may send a command to the touch controller by performing an I/O write to the Data Register (Base Address). If Bit 0 of the Status Register is 1, do not send a touch command to the touch controller.

Receiving Touch Data from the HBC

The procedure used to receive data from the HBC differs depending on which communication mode you are using.

Polling Mode

When using polling mode, the application software polls the Status Register (Base Address + 1) to check if touch data is available in the Data Register (Base Address).

Before reading the Data Register, you must first perform an I/O read of the Status Register. Bit 1 of the Status Register indicates whether there is touch data available in the Data Register. Table 3-3 shows the values of Bit 1 of the Status Register.

Table 3-3. Status Register Bit 1 Values

Bit 1 Description

0 Touch data available. 1 No touch data available.

If Bit 1 of the Status Register is 0, you may receive a byte of touch data by performing an I/O read of the Data Register. If Bit 1 of the Status Register is 1, there is no data available in the Data Register.

3-10 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 3 - General Programming Issues

Interrupt Mode

When using interrupt mode, the touch controller uses a PC hardware interrupt to notify the application software that touch data is available in the Data Register (Base Address). When the display is touched with touch enabled, or an information request command is received by the touch system, the touch system sends touch data to the Data Register.

The HBC then interrupts the host computer, indicating that data is available in the Data Register. The application software’s interrupt handler should perform an I/O read of the Data Register to receive a byte of touch data from the touch system.

Resetting the HBC

The procedure to perform a hardware reset on the HBC is the same for both interrupt and polling communication modes. To cause a hardware reset of the touch controller, perform an I/O write to the Hardware Reset Register (Base Address + 2).

Note that the value of the data byte written to the Hardware Reset Register does not matter.

Touch System Programmer’s Guide 3-11

Chapter 3 - General Programming Issues CARROLL TOUCH

3-12 Touch System Programmer’s Guide

Smart-Frame

Smart-Frame Protocol

Protocol

his chapter gives an overview of the SFP firmware protocol,

including a discussion of command and report types, initialization,

timing, and programming tips and examples.

The chapter discusses the following topics:

• Overview.

• SFP and SFP-II.

• Types of SFP Commands.

• Reports.

• Touch System Initialization.

• Touch System Initialization Examples.

• Using an SBC.

• Compatibility Issues/Programming Tips.

• SFP Timing.

• SFP Programming Examples.

See Appendix A, “Smart-Frame Protocol Command Reference,” for the specifications of each Smart-Frame Protocol command.

Touch System Programmer’s Guide 4-1

Chapter 4 - Smart-Frame Protocol CARROLL TOUCH

Overview

The Smart-Frame Protocol (SFP) regulates communication between the touch system and the application program.

Smart-Frame Protocol commands are used to:

• Initialize the touch system.

• Establish host-to-touch communications.

• Select the touch system reporting and operating modes.

• Request special reports.

• Manage report transfer.

• Execute diagnostic functions.

SFP and SFP-II

The SFP, defined in 1985, is currently used by most Carroll Touch touch systems, but will eventually be supplanted by Smart-Frame Protocol II (SFP-II) on newer touch systems.

The SFP is implemented as a modal protocol, meaning that, even if a touch system supports both the SFP and SFP-II, it can only support one protocol at a time and, during that time, cannot accept commands from the other protocol. To switch between protocols, use the

SwitchToSFP-II (65H) SFP command and the SwitchToClassicSFP (64H) SFP-II function.

Types of SFP Commands

Smart-Frame Protocol commands are grouped into five logical categories:

• Communication commands.

• Reporting method commands.

• Touch mode commands.

• Information request commands.

• System commands.

SFP commands may be invoked with either a hexadecimal code or an ASCII code, and many of the commands have associated reports. To issue a command under the Smart-Frame Protocol, simply type its function number. An SFP command example is 32, the hexadecimal code for the Get_Error_Report (32H) command.

4-2 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 4 - Smart-Frame Protocol

Communication Commands

Communication between the touch system and the host computer can be regulated by hardware or software flow control. Communication commands are shown in Table 4-1.

Table 4-1. SFP Communication Commands

Command Name

Hardware_Flow_Control_On 41H A None Hardware_Flow_Control_Off 42H B None Report_Transfer_Off 43H C None Report_Transfer_On 44H D None Get_One_Report 46H F varies

Hardware flow control regulates the transmission of data from the touch system to the host and from the host to the touch system by using RS-232 control signals. To enable and disable this type of data flow control, use the Hardware_Flow_Control_On (41H) and Hardware_Flow_Control_Off (42H) commands.

Software flow control regulates transmission of data from the touch system to the host on a report-by-report basis. To implement this type of data flow control, use the Report_Transfer_On (44H) command, Report_Transfer_Off (43H) command, or the Get_One_Report (46H) command.

Hex Code

ASCII Code

Associated Report

The default flow control method is software flow control.

Reporting Method Commands

Reporting methods determine the form in which data is sent from the touch system to the host. Both the desired reporting method and touch mode should be selected before turning touch system scanning on, although they may also be changed with scanning on. The commands used to select the reporting method are shown in Table 4-2.

Touch System Programmer’s Guide 4-3

Chapter 4 - Smart-Frame Protocol CARROLL TOUCH

Table 4-2. SFP Reporting Method Commands

Command Name

Hex Code

ASCII Code

Associated Report

Scan_Reporting 22H “ Scan Report Coordinate_Reporting 23H # Touch Coordinate Report

Add Exit Coordinate Point Report Non-Contiguous Coordinate Report

Scan reports present interrupt beam data with no software interpretation and are used for diagnostic and testing purposes. Coordinate reports present interrupt beam data in the form of x, y (x-axis, y-axis) coordinate pairs for application processing.

Touch Mode Commands

Touch mode commands select the conditions under which touch coordinates are reported when the reporting method is set to coordinate reporting. Touch mode commands are shown in Table 4-3.

Table 4-3. SFP Touch Mode Commands

Command Name

Hex Code

ASCII Code

Associated Report

Enter_Point_Mode 25H % Touch Coordinate Report Tracking_Mode 26H & Touch Coordinate Report Continuous_Mode 27H ‘ Touch Coordinate Report Exit_Point_Mode 28H ( Touch Coordinate Report Add_Exit_Point_

29H ) Touch Coordinate Report

Modifier*

*Add Exit Point is a modifier that is used with other touch modes. It is not a stand-alone touch mode.

To change the touch mode, simply send the touch mode command that selects the new touch mode. For example, to change from Enter Point Mode to Tracking Mode, send the Tracking_Mode (26H) command.

4-4 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 4 - Smart-Frame Protocol

Changing the touch mode clears the Add Exit Point modifier. To disable the Add Exit Point modifier without changing the current touch mode, simply send the desired touch mode command again.

For example, to select Tracking Mode with Add Exit Point, send the

Tracking_Mode (26H) command followed by the Add_Exit_Point_Modifier (29H) command. To deselect Add Exit Point

and remain in Tracking Mode, send the Tracking_Mode (26H) command again.

Information Request Commands

Information request commands query the touch system for system status reports, such as error, configuration, firmware version, failed beam, frame size, and state reports. Information request commands are shown in Table 4-4.

Table 4-4. SFP Information Request Commands

Command Name

Get_Error_Report 32H 2 Error Report Get_Configuration_Report 33H 3 Configuration Report Get_Firmware_Version_

Report Get_Failed_Beam_Report 36H 6 Failed Beam Report Get_Frame_Size_Report 37H 7 Frame Size Report Get_State_Report 47H G State Report

Hex Code

34H 4 Firmware Version

ASCII Code

Associated Report

Report

System Commands

System commands control all touch system functions such as initialization, software reset, diagnostics, and scanning. The system commands are shown in Table 4-5.

Touch System Programmer’s Guide 4-5

Chapter 4 - Smart-Frame Protocol CARROLL TOUCH

Table 4-5. SFP System Commands

Reports

Command Name

Echo_On 20H Space None Echo_Off 21H ! None Touch_Scanning_On 2AH * None Touch_Scanning_Off 2BH + None Run_Diagnostics 3AH : Error Report Software_Reset 3CH < None Clear_Touch_Report_Buffer 3DH = None Reset 45H E None SwitchToSFP-II 65H SFP-II Protocol

Hex Code

ASCII Code

Associated Report

Version Report or Error Report

An SFP report has the following format:

header reportbytes trailer

The trailer is always FF. An example of a report returned from the Get_Error_Report (32H) command is:

F8 00 FF

F8 is the header, 00 indicates no errors, and FF is the trailer. An

example of a touch coordinate report is:

FE 35 2D FF

FE is the header; 35 and 2D are the x, y touch coordinates; and FF is

the trailer.

4-6 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 4 - Smart-Frame Protocol

Touch System Initialization

To initialize a touch system that uses the Smart-Frame Protocol, take the following steps:

1. Reset the touch system.

2. Perform the autobaud/autoparity sequence, if appropriate, then the software reset command.

3. Check for any errors that may have been detected.

4. Set the desired reporting method and touch mode.

Details on each step are in the following sections.

Resetting the Touch System

The following methods may be used to reset the touch system. Be sure to use a method that is appropriate for the touch system being used.

Power Cycle

This method resets everything. For touch systems that communicate serially, Clear To Send (CTS) is deasserted (negative voltage) to indicate that the touch system is busy until the touch system is ready to accept commands. For serial touch systems that have their communication parameters set to autobaud/autoparity, this occurs when the touch system enters the autobaud sequence by sending breaks.

Dedicated Reset Signal

On some Smart-Frame systems, a dedicated reset signal line is present. If present, this signal is on pin 8 of the 2 x 5 pin communication connector that is on the frame. To reset the touch system, deassert this pin by applying negative voltage for a minimum of 10 ms. This type of reset is equivalent to cycling the power to the touch system. This signal is not present on the modular RS-232 controller.

Break (Hardware Detected)

For touch systems that use the modular RS-232 controller, a break of at least 400 ms resets the touch system. To send a break of 400 ms, set the Transmit Data (TD) signal to the “space” condition (positive voltage), wait 400 ms, and set the TD signal back to the “mark” condition (negative voltage). For PC systems, the “Set Break” bit in the Line Control Register of the 8250 USART chip is used to set and/or clear the break condition. This type of reset is equivalent to cycling the power to the touch system.

Touch System Programmer’s Guide 4-7

Chapter 4 - Smart-Frame Protocol CARROLL TOUCH

HBC Hardware Reset Register

For touch systems that use the modular HBC, writing any value to the HBC Hardware Reset Register (Base Address +2) resets the touch system. This type of reset is equivalent to cycling the power to the touch system.

Break (Firmware Detected)

For all touch systems that communicate serially, a break of at least 150ms resets the touch system. To send a break of 150ms, set the Transmit Data (TD) signal to the “space” condition (positive voltage), wait 150ms, and set the TD signal back to the “mark” condition (negative voltage). For PC systems, the “Set Break” bit in the Line Control Register of the 8250 USART chip is used to set and/or clear the break condition. This type of reset is equivalent to cycling the power to the touch system, except that Clear To Send (CTS) is not affected if hardware flow control was not enabled before the reset.

Reset (45H)

This Smart-Frame Protocol command resets everything. If the touch system communicates serially and hardware flow control is enabled, CTS is deasserted (negative voltage) to indicate that the touch system is busy until the touch system is ready to accept commands. For serial touch systems that have their communication parameters set to autobaud/autoparity, this occurs when the touch system enters the autobaud/autoparity sequence by sending breaks. If hardware flow control is disabled, Clear To Send (CTS) is not affected. This type of reset is equivalent to cycling the power to the touch system, except that the Clear To Send (CTS) is not affected if hardware flow control was not enabled before the reset. Also, if the touch system communicates serially but is set to use a fixed baud rate and parity (not autobaud/autoparity), or if the touch system uses the HBC, the touch system sends a Power Up Report (F1 FF) when it is ready to receive commands.

In all cases, the touch system is ready to receive commands within one second after the reset occurs. Touch applications must delay for one second after resetting the touch system. In cases where a break is sent, the one second time does not begin until the break is released.

Performing the Autobaud/Autoparity Sequence

If you are using a touch system that communicates serially and is set to use autobaud/autoparity, you must perform the autobaud/autoparity

4-8 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 4 - Smart-Frame Protocol

sequence to allow the touch system to establish baud rate and parity that is used by the host.

To perform the autobaud/autoparity sequence, the host must send five ASCII carriage returns (CR - 0DH) followed by a delay of at least 100ms after each carriage return. The touch system uses these carriage returns to determine the baud rate used by the host. When the touch system has determined the baud rate of the host, it stops sending breaks to the host; the host need not send additional carriage returns after this occurs. The simplest method, however, is for the host to send five carriage returns with delays and ignore the breaks sent by the touch system. This is the recommended method.

Regardless of whether or not the touch system uses autobaud/ autoparity, the host must send a Software_Reset (3CH) command followed by a delay of at least 100ms. This clears the touch system buffers and resets the touch system parameters listed in Table 4-6 to their defaults. If autobaud/autoparity is being used, this also establishes the parity being used by the host.

Table 4-6. SFP Default Settings

System Parameters Default Setting

Touch Scanning Off Reporting Method Coordinate reporting Touch Mode Tracking Mode Add Exit Point Modifier Off Report Transfer Off Hardware Flow Control Off

Checking for Touch System Errors

To confirm that the initialization sequence was successful, determine the status of the touch system by sending the Get_Error_Report (32H) command. The Error Report that is returned lists any errors detected by the touch system. Since report transfer has not been enabled yet, the host must enable it so that the touch system can transmit the Error Report. This is accomplished by sending the Report_Transfer_On

(44H) command to the touch system before sending the Get_Error_Report (32H) command.

Touch System Programmer’s Guide 4-9

Chapter 4 - Smart-Frame Protocol CARROLL TOUCH

The contents of the Error Report vary according to whether the touch system has a single processor or dual processors.

If the touch system did not detect any errors, the Error Report appears as follows:

F8 00 FF Reports no errors for single processor

systems.

F8 00 00 FF Reports no errors for dual processor

systems.

If the touch system detects errors, the 00 byte is replaced by an error code count, followed by error codes. These error codes are identified in the Get_Error_Report (32H) documentation in Appendix A.

If the Error Report is not received by the host, there is a communication error. Run the initialization sequence again or send the Echo_On (20H) command to determine the source of the communication problem.

Setting the Reporting Method and Touch Mode

The host may now complete the initialization sequence and enable touch system scanning. It should send the appropriate Smart-Frame Protocol commands to set the desired reporting method and touch mode, send any other parameters (such as hardware flow control, and so forth), then send the Touch_Scanning_On (2AH) command.

Touch System Initialization Examples

The following examples represent the recommended initialization sequences for various touch system hardware configurations.

Using Autobaud/Autoparity

To initialize a touch system that communicates serially and uses autobaud/autoparity, use the following initialization sequence:

1. Send a 400ms break. You may send a Reset (45H) command instead, but this only works if the touch system has previously been set to receive commands at the current baud rate and parity and is not recommended.

2. Wait one second for the touch system to complete its power-on testing.

4-10 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 4 - Smart-Frame Protocol

3. Send five carriage returns (CRs - 0DH) with a 100ms delay after each CR.

4. Send the Software_Reset (3CH) and delay 100ms.

5. Send the Report_Transfer_On (44H) command, followed by the Get_Error_Report (32H) command.

6. Read the Error Report sent by the touch system. If the report is received correctly and indicates no errors, the touch system is ready to use. If the report is not received correctly, or contains errors, take the appropriate action.

7. Send the Get_Frame_Size_Report (37H) command.

8. Read the Frame Size Report sent by the touch system. If the frame size is 223 x 223 (DFH x DFH), you can assume that the touch system is a guided acoustic wave system. If the frame size is reported as any other value, you can assume that the touch system is a scanning infrared system.

Using a Fixed Baud Rate

To initialize a touch system that communicates serially and used a fixed baud rate, use the following initialization sequence:

2. Wait one second for the touch system to complete its power-on testing.

3. Send the Software_Reset (3CH) command and delay 100ms.

4. Send the Report_Transfer_On (44H) command, followed by the Get_Error_Report (32H) command.

5. Read the Error Report sent by the touch system. If the report is received correctly and indicates no errors, the touch system is ready to use. If the report is not received correctly, or contains errors, take the appropriate action.

Using the HBC

To initialize a touch system that uses the modular hardware-based controller (HBC), use the following initialization sequence:

1. Write to the HBC Hardware Reset Register (Base Address +2).

2. Wait one second for the touch system to complete its power-on testing.

3. Send the Software_Reset (3CH) command and delay 100ms.

Touch System Programmer’s Guide 4-11

Chapter 4 - Smart-Frame Protocol CARROLL TOUCH

4. Send the Report_Transfer_On (44H) command, followed by the Get_Error_Report (32H) command.

Using an SBC

Touch systems that include the SBC are unique because they use the CPU of the host PC to manage the scanning of the frame and reporting of touch coordinates instead of using a dedicated microprocessor.

The following exceptions to the standard Smart-Frame Protocol exist for SBC-based touch systems:

• The scan reporting method is not supported by the SBC. Sending the Scan_Reporting (22H) command to the SBC has no effect.

• Sending the Echo_On (20H) command, the Echo_Off (21H) command, or the Reset (45H) command to the SBC has no effect, and causes the Invalid Command error to occur.

• The Hardware_Flow_Control_On (41H) and the Hardware_ Flow_Control_Off (42H) commands apply only to touch systems that communicate serially, and have no effect when sent to the SBC.

When using an SBC-based touch system, turning touch scanning on via the Touch_Scanning_On (2AH) command causes the SBC hardware to begin issuing hardware interrupts. Turning touch scanning off via the Touch_Scanning_Off (2BH) command causes the SBC hardware to stop issuing hardware interrupts. Since the SBC TAPI driver only uses host CPU time when an interrupt is issued by the SBC hardware, turning touch scanning off whenever possible releases host CPU time that would otherwise be used by the SBC TAPI driver for other uses.

Compatibility Issues/Programming Tips

An application or driver that is hard-wired to a typical size or model of CT touch system may require modification if a different touch system is used. Applications and drivers that use the Smart-Frame Protocol to interface to the touch system should be designed to work with all types and sizes of touch systems that use the Smart-Frame Protocol. This lets you continue to use the application or driver without modification if a different size and/or model of CT touch system is used. The following design rules should be followed.

4-12 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 4 - Smart-Frame Protocol

Number of Processors Independence

Get_Error_Report (32H) causes an Error Report to be returned that details the errors for each processor in the touch system. Use the Get_Configuration_Report (33H) command to get a Configuration Report that includes the number of processors in the touch system to properly interpret this report. Do not hard wire the code that interprets the Error Report to work with a specific number of processors.

Firmware Version Independence

Get_Firmware_Version_Report (34H) causes a Firmware Version Report to be returned that lists firmware versions for various touch system components. Do not hard wire the code that interprets the Firmware Version Report to only work with a specific number of version reports or a specific firmware version.

Frame Size Independence

If a software calibration and scaling program, as described in this guide, is used, a change to a touch system with a different size frame simply requires that the calibration program be run on the new touch system. The frame size difference is reflected in the calibration parameters, and the touch application or driver code itself does not need to be modified. Do not hard wire the touch application or driver to a specific frame size, since this requires the touch application or driver to be modified if a different size frame is used.

Touch System Response Time Independence

The amount of time required for a touch system to process a command may vary, depending upon the model of the touch system. This, coupled with the fact that there is no provision for software flow control in the host-to-touch system direction, means that the input queue of the touch system could overflow, causing commands to be missed if the touch system is bombarded with commands at a faster rate than it can process them. This usually occurs only when a long sequence of initialization commands is issued at a high baud rate.

To prevent this overrun and loss of command characters:

1. Use a delay of approximately 10 milliseconds between commands to allow the touch system time to process each command before the next is sent.

2. Use a lower baud rate.

Touch System Programmer’s Guide 4-13

Chapter 4 - Smart-Frame Protocol CARROLL TOUCH

Using a baud rate above 2400 baud does not produce any increase in apparent touch responsiveness. This is due to the fact that the communication bandwidth required to transmit the four-byte touch coordinate reports at the typical rate of 30 scans per second is slightly above 1200 baud. Therefore, using a baud rate above 2400 baud is unnecessary and merely reduces the noise immunity of the communication channel while producing no increase in apparent touch responsiveness.

SFP Timing

The following timing parameters apply to touch systems that use the Smart-Frame Protocol.

Autobaud/Autoparity Delay Time

During the autobaud/autoparity initialization sequence, a delay of at least 100 milliseconds must be present between the carriage returns and after the Software_Reset (3CH) command. This delay is required in order for the autobaud/autoparity algorithms to work properly.

Maximum Command Completion Time

The maximum amount of time required for a Smart-Frame Protocol command to be processed and a corresponding report (if any) to be generated is one second. Touch applications should use at least this amount of time as their time-out value when awaiting a Smart-Frame report.

Reset Time/Diagnostics Completion Time

The maximum amount of time required for a touch system that uses the Smart-Frame Protocol to become ready to begin the autobaud/ autoparity sequence or to receive commands is one second. Touch applications should either wait at least this amount of time or wait for some other signal that the touch system is ready to receive commands (such as the assertion of the Clear To Send (CTS) signal if serial hardware flow control is used) before beginning the autobaud/ autoparity sequence or sending commands to the touch system.

SFP Programming Examples

The Carroll Touch Driver/Demo Disk contains five short example programs under the heading of “Programmer’s Guide Programming Examples.” They demonstrate how to interface directly to RS-232-based and HBC-based touch systems using the Smart-Frame

4-14 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 4 - Smart-Frame Protocol

Protocol. Both a polling method and an interrupt-driven method are shown for each type of touch system. All of these programs were developed using Borland C. Minor modifications may be required for other compilers.

The example files are:

CT.H - Contains a CT header file. UART8250.H - Contains a 8250 serial UART header file. RS232POL.C - Contains an RS-232 polling example. RS232INT.C - Contains an RS-232 interrupt example. HBCPOL.C - Contains an HBC polling example. HBCINT.C - Contains an HBC interrupt example.

Touch System Programmer’s Guide 4-15

Chapter 4 - Smart-Frame Protocol CARROLL TOUCH

4-16 Touch System Programmer’s Guide

Smart-Frame

Smart-Frame Protocol II

Protocol II

his chapter gives an overview of the Smart-Frame Protocol-II, a

firmware protocol that extends the capabilities of the SFP by offering support for higher resolution and a z-axis. Explanations of command formats and report formats are included.

This chapter discusses the following topics:

• Overview.

• Types of SFP-II Functions.

• Functions.

• Commands.

• Reports.

• Error Reporting.

• Overloaded Functions.

• Shared Parameters between SFP and SFP-II.

See Appendix B, “Smart-Frame Protocol II Function Reference,” for the specifications of each Smart-Frame Protocol II function.

Touch System Programmer’s Guide 5-1

Chapter 5 - Smart-Frame Protocol II CARROLL TOUCH

Overview

The Smart-Frame Protocol II (SFP-II) is a firmware protocol intended to be the successor to the existing Smart-Frame Protocol firmware protocol, which was defined in 1985. Driving factors behind the development of the SFP-II protocol are:

• The introduction of touch systems using guided acoustic wave

technology, which supports high resolution touch coordinates as well as z-axis touch coordinates - features not supported by the existing Smart-Frame Protocol.

• The need for general and architectural enhancements to the SFP.

SFP-II has been initially implemented on guided acoustic wave systems, but is designed for and will be implemented on all Carroll Touch systems.

Extensibility

SFP-II is designed to support true extensibility, allowing features to be added or removed over time. It does this by providing a standard mechanism whereby applications or drivers that interface with the touch system can determine which features the touch system supports.

This mechanism consists of two parts: the touch system can report the protocol version (not to be confused with the firmware version) to an application or driver via the Protocol Version Report, and the application or driver can use the SetReportProperties (21H) command to request that a Report Properties Report be sent. This report includes a parameter called FunctionVersion that can be used to determine if a particular function is supported.

The protocol version number reflects the unique set of features supported by that version of the protocol. Any time that a feature is added, removed, or changed in such a way that it would be visible to the user using the published SFP-II functions, the protocol version number is incremented.

The protocol version number of the SFP is (retroactively) defined to be

1.0. Note, however, that because the SFP contains no mechanism for reporting the protocol version number, SFP touch systems do not actually respond with a Protocol Version Report. Instead, if an application or driver receives no response when attempting to switch to SFP-II mode using the SwitchToSFP-II (65H) SFP command, it should timeout waiting for the command, and then assume that the touch system only supports SFP (SFP 1.0).

5-2 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 5 - Smart-Frame Protocol II

Protocol version numbers greater than 1.0 but less than 2.0 will be used during the development of the SFP-II protocol. When the SFP-II protocol is complete, that is, when it incorporates the initial set of desired features, that version of the protocol will be given a version number of 2.0. Subsequent changes to the protocol will result in changes to the subminor, minor, or major portions of the protocol version number, depending upon the extent of the changes.

One of the main purposes for extensibility is to allow properly written applications and drivers to work with touch systems that support SFP and touch systems that support SFP-II. A “properly written” application or driver uses the following sequence of steps during touch system initialization to determine the protocol version and act accordingly:

1. Initialize the touch system using the common initialization

sequence.

2. Attempt to switch to SFP-II mode by issuing the SwitchToSFP-II

(65H) SFP command.

3. If the touch system does not respond with a Protocol Version

Report within the SFP timeout time (one second), the application or driver should assume that the touch system supports only the SFP (SFP 1.0), and use only SFP commands and expect only SFP reports.

4. If the touch system responds with a protocol version report that

indicates a protocol version number of 2.0 or above, the application or driver may use all of the standard SFP-II commands and reports. The application or driver may also (optionally) use SetReportProperties (21H) command to request Report Properties Reports to ensure that each command that it uses is supported. This optional step is recommended if the application uses commands or reports that were not included in the original SFP-II protocol (SFP

2.0).

In summary, applications or drivers can use the Protocol Version Report to determine the firmware protocol version. The protocol version can be used to determine whether the touch system supports only SFP or SFP and SFP-II. The application or driver may also use the Protocol Version Report in conjunction with the protocol version revision history to determine the exact features that the firmware supports. Finally, for maximum protection against protocol changes, the application or driver can use the SetReportProperties (21H) function to ensure that each command that it intends to use is supported.

Touch System Programmer’s Guide 5-3

Chapter 5 - Smart-Frame Protocol II CARROLL TOUCH

Modal Protocols

The SFP-II is implemented as a modal protocol, meaning that, even if a touch system supports both the SFP and SFP-II, it can only support one protocol at a time and, during that time, cannot accept commands from the other protocol. To switch between protocols, use the

SwitchToSFP-II (65H) SFP command and the SwitchToClassicSFP (64H) SFP-II function.

Note

The SFP-II protocol currently lacks many necessary features that are supported in SFP, so it is necessary for the host to switch between the SFP and SFP-II to access these features. When the SFP-II protocol specification is complete, it will include all necessary features, eliminating the need to switch protocols.

Backward Compatibility

Touch systems that implement SFP-II (known as SFP-II aware touch systems) also implement the existing SFP to ensure backward compatibility with existing touch systems and to avoid obsoleting the installed base of touch applications. Backward compatibility means that:

1. SFP-II aware touch systems may be used with existing

applications that use the SFP without requiring the application to be modified.

This is possible because the initialization sequence is identical for both SFP-II aware and non SFP-II aware touch systems, and because SFP-II aware touch systems power up under SFP and remain in SFP until explicitly commanded to switch to SFP-II.

2. Applications and drivers may be written to use both SFP-II aware

touch systems and non SFP-II aware touch systems (albeit with reduced functionality).

This is possible because a mechanism exists whereby applications and drivers can interrogate the touch system to determine whether the touch system supports SFP-II. The application or driver may choose to use the advanced functions of SFP-II or to use only the SFP.

5-4 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 5 - Smart-Frame Protocol II

Types of SFP-II Functions

SFP-II functions are currently grouped into four logical categories. The logical categories are reserved in groups of 16 (10H), with each group containing functions that have similar purposes.

• Reset and touch reporting:

GetTouchState (01H)

• Status reporting:

GetCoordinateRanges (10H) GetConfiguration (11H)

• Parameter setting and reporting:

SetTouchModes (20H) SetReportProperties (21H) SetReportTransferMode (22H)

• Mode switching:

SwitchToClassicSFP (64H) GetProtocolVersion (65H)

Functions

Touch systems that support SFP-II communicate with applications and drivers via the use of SFP-II functions. Each function consists of a command and a corresponding report, even if that report is simply a null report that only returns the report number and the command error status. The report number is the same as the command number for each command/report pair.

Each command/report pair may be thought of as corresponding to a function call in a language such as C, with the command parameters (if any) representing the parameters that are passed into the function, and the report parameters (if any) representing the parameters that are returned by the function.

The host computer sends SFP-II commands to the touch system, and the touch system responds by sending SFP-II reports to the host. The touch system must respond with the corresponding SFP-II report packet for each and every SFP-II command packet that it receives. The host, in turn, must wait until it receives the corresponding SFP-II report packet after sending an SFP-II command packet before it can send another SFP-II command packet.

The host should use a one second timeout when waiting for the report packet. If the report packet has not arrived after that time, the host should retry sending the command. If the touch system still does not

Touch System Programmer’s Guide 5-5

Chapter 5 - Smart-Frame Protocol II CARROLL TOUCH

respond after another timeout period, the host should send enough FFH bytes to ensure that the touch system’s input buffer overflows, and then retry the command again. Note that the host could certainly send the FFH bytes without retrying the command if it so chose. Refer to “Error Reporting,” later in this chapter, for more details on error handling.

This design greatly simplifies the handling of command and report packets for the touch system and the host. The touch system cannot queue up command packets from the host, thus preventing many potential overrun and timing problems.

Commands

An SFP-II command has the format:

header packetbytecount commandnumber optionalparameters trailer

header = Defined to be 66H.

packetbytecount

= Length of the command number + the command

parameters (if any) in bytes. For example, a command with two bytes of parameters has a byte count of 3 (one byte for the command number and two bytes for the parameters).

commandnumber

= One byte opcode that identifies the SFP-II command.

Valid opcodes are 00H through BFH.

optionalparameters

= Parameters for the SFP-II command. The maximum

number of parameter bytes is 252 (FCH).

trailer

= Defined to be FFH.

The maximum length of an SFP-II command packet is 256 bytes.

The format for SFP-II commands reflects the fact that SFP-II is a layered protocol. There are two layers, the validation layer and the interpretation layer.

5-6 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 5 - Smart-Frame Protocol II

Validation Layer

The format for SFP-II commands at the validation layer is:

header packetbytecount interpretationlayer trailer

The validation layer consists of the outer portions of the command format and “wraps” around the inner portions of the command format, or the interpretation layer. To detect a valid SFP-II command in the incoming stream of bytes, the touch system firmware detects the header, reads the byte count that follows the header, reads the number of bytes specified by the byte count (the command packet), and verifies that the following byte is a trailer byte. If the segment of the incoming byte stream under consideration fits this format, the segment is deemed to be a valid SFP-II command packet and the command number and parameters are forwarded to the interpretation layer.

Interpretation Layer

The format for SFP-II commands at the interpretation layer is:

commandnumber optionalparameters

To interpret the command, the touch system firmware first jumps to the appropriate command handler using a jump table. If the command number does not correspond to a defined SFP-II command, the command is deemed invalid and a report is sent to the host with the command error parameter set to the Invalid Command value.

If the command handler determines that the appropriate number of parameter bytes for the command is not present, or that one or more of the parameter bytes are otherwise invalid for the command (parameter is out of range, not set to a valid value for this particular touch system, and so forth), the corresponding SFP-II report is sent to the host with the command error parameter set to indicate the missing or invalid parameter byte. The parameters that the host sent in the command are echoed to the host in this report.

If the command handler determines that the appropriate number of parameter bytes for the command is present and that all of the parameter bytes are valid for that command, the touch system processes the command and sends the corresponding SFP-II report back to the host. The command error parameter is set to the “valid command and parameters” value to indicate that both the command and parameters were valid.

Touch System Programmer’s Guide 5-7

Chapter 5 - Smart-Frame Protocol II CARROLL TOUCH

The bytes within the command packet are indexed beginning at 0 for the SFP-II command number, and ending at (command packet byte count - 1) for the last parameter byte. The length of the command packet is given by the packet byte count from the validation layer.

Example

A simple example of an SFP-II command is the GetTouchState (01) command, which has one byte of data and no optional command parameters, is:

66 01 01 FF

A more complex example of a SFP-II command is the imaginary Fubar command, which expects a one byte parameter (bip) and a two byte parameter (flap):

66 04 <Fubar> <Bip> <FlapHi> <FlapLo> FF

Reports

If the command opcode for Fubar is 27H, and the values of the Bip and Flap parameters are 18H and 8923H, respectively, the command packet is as follows:

66 04 27 18 89 23 FF

An SFP-II report has the format:

header packetbytecount commanderrorstatus reportnumber optionalreportparameters trailer

header = Defined to be EOH.

packetbytecount

= Length of the report number + the command error status

+ the report parameters (if any) in bytes. For example, a report with two bytes of parameters would have a byte count of 4 (one byte for the command number, one byte for the command error status, and two bytes for the parameters).

commanderrorstatus

= A one byte parameter that indicates whether the SFP-II

command number and/or the SFP-II command

5-8 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 5 - Smart-Frame Protocol II

parameters of the SFP-II command packet that solicited the report were valid.

If the command number and parameters were all valid, this parameter is 0.

If there was an error associated with one of the command parameters, this parameter contains a number that points to the first byte of the parameter that was in error. If there are multiple parameters with errors, only the first one is indicated.

If the command number is invalid, this parameter is FFH.

If no SFP-II command packet was associated with this report (i.e, the report is an unsolicited report), this parameter is 0. Refer to “Error Reporting,” later in this chapter, for more information on this parameter.

reportnumber

= One byte opcode that identifies the SFP-II report. Valid

opcodes are 00H through BFH.

optionalreportparameters

= Parameters for the SFP-II report. The maximum number

of parameter bytes is 251 (FBH).

trailer= Defined to be FFH.

The maximum length of an SFP-II report packet is 256 bytes.

The generic report format for SFP-II reports reflects the fact that SFP-II is a layered protocol. There are two layers, the validation layer and the interpretation layer.

Validation Layer

The format for SFP-II reports at the validation layer is as follows:

header packetbytecount interpretationlayer trailer

Note that the validation layer consists of the outer portions of the report format and “wraps” around the inner portions of the format, or the interpretation layer. To detect a valid SFP-II report in the incoming stream of bytes, the host must detect the header, read the byte count that

Touch System Programmer’s Guide 5-9

Chapter 5 - Smart-Frame Protocol II CARROLL TOUCH

follows the header, read the number of bytes specified by the byte count (the report packet), and verify that the following byte is a trailer byte. If the segment of the incoming byte stream under consideration fits this format, the segment is deemed to be a valid SFP-II report packet and the command error status, report number, and parameters are forwarded to the interpretation layer.

Interpretation Layer

The format for SFP-II reports at the interpretation layer is as follows:

commanderrorstatus reportnumber optionalreportparameters

To interpret the report, the host should first examine the command error status parameter. If the command error status parameter indicates an error, the host should take the appropriate action.

The host should then examine the report number. If the report number does not correspond to a defined SFP-II report, the host should deem the report invalid.

Finally, the host should examine the report to determine that the appropriate number of parameter bytes for the report is present. If the appropriate number is not present, or one or more of the parameter bytes are otherwise invalid for the report (parameter is out of range and so forth), the host should deem the report invalid.

If the host determines that all information in the interpretation layer is valid, the host should process the command.

The bytes within the report packet are indexed beginning at 0 for the SFP-II report number, and ending at (report packet byte count - 1) for the last parameter byte. The length of the report packet is given by the packet byte count that was read during the validation layer.

Example

An example of a report issued in response to a valid SFP-II command, GetProtocolVersion (command 65), is:

E0 04 00 65 02 12 FF

E0 and FF are the header and footer, respectively. 04 indicates the

report contains four bytes. 00 is the command error status (Cmderr) and indicates the report is valid. 65 is the report number, which is the

5-10 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 5 - Smart-Frame Protocol II

command number. The parameters 02 and 12 represent the ProtocolVersionHi and ProtocolVersionLo bits, indicating protocol version 2.12.

Reporting Modes

Each SFP-II report has a reporting mode associated with it that specifies when the report is to be sent. The available reporting modes are:

Solicited Only Mode - The touch system sends the selected

report after receiving the corresponding command.

Parameter Change Mode- The touch system sends the selected

report after receiving the corresponding command and whenever any of the parameters contained in the report changes.

Continuous Mode - The touch system sends the selected

report after receiving the corresponding command and each time that it executes its main executive loop.

Parameter Change Mode and Continuous Mode produce “unsolicited reports,” because reports are sent by the touch system even though it has not received a corresponding SFP-II command. The default reporting mode of most reports is Parameter Change Mode. The exceptions to this are the Multi Touch State and Raw Touch State Reports, which are solicited only.

Use the SetReportProperties (21H) function to set the reporting mode of reports.

Report Transfer Mode

When report transfer is disabled, unsolicited reports are not transferred from the touch system to the host. Solicited reports continue to be transferred from the touch system to the host.

When report transfer is enabled, both solicited and unsolicited reports are transferred.

Use the SetReportTransferMode (22H) function to set the reporting mode of reports.

Touch System Programmer’s Guide 5-11

Chapter 5 - Smart-Frame Protocol II CARROLL TOUCH

Error Reporting

SFP-II uses a command error status parameter (Cmderr) to report errors in commands sent to the touch system. The one-byte parameter is part of every SFP-II report and indicates whether the SFP-II command number and/or command parameters were valid.

Note

The use of the Cmderr parameter to indicate unsupported features is especially useful during the period that the SFP-II specification is being developed. Features that have been specified but not yet implemented will be indicated in this manner. The host should

check Cmderr in all reports returned from the touch system to recognize these unsupported features.

Cmderr has a value of 0 if the command number and parameters are all valid, or if the report is an unsolicited report.

When an error occurs, the command number and parameter bytes (if any) that were sent by the host are echoed to the host in the corresponding report. The touch system does not take any of the actions and/or change the values of any of the parameters in the command.

Invalid Command Number

When an invalid command number is detected, an SFP-II report packet is sent with Cmderr set to FF.

For example, if function 93H is undefined and the host sends the following command:

66 01 93 FF

The touch system responds with the following report:

E0 02 FF 93 FF

The first FF byte is Cmderr and indicates that there is no command defined with an opcode value of 93H.

If function 94H is undefined and the host sends the following command:

66 04 94 01 02 03 FF

5-12 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 5 - Smart-Frame Protocol II

The touch system responds with the following report:

E0 05 FF 94 01 02 03 FF

The first FF byte is Cmderr and indicates that there is no command defined with an opcode value of 94H. Note that the parameters that were sent with the invalid command packet (01 02 03) are returned along with the invalid command number.

Invalid Parameter Value

When the parameter number is out of range, an SFP-II report packet is sent with Cmderr containing a number that points to the first byte of the parameter that was in error. If there were multiple parameters with errors, only the first one is indicated.

If the host sends the SetTouchModes (20H) command as follows:

66 04 20 01 04 03 FF

The touch system responds with the following report:

E0 05 02 20 01 04 03 FF

The 02 byte is Cmderr and indicates that the second parameter is out of range. (The value of 04 for TouchStateReportType is not among the valid values of 01, 02, or 03.) Since the 04 byte is out of range, the error results and is reported in Cmderr. The third parameter is also out of range. This parameter is the TouchReportingMode parameter, which has valid values of 00, 01, and 02. The 03 byte is out of range. However, this is not reported to the host because Cmderr only reports the first invalid parameter if multiple parameters are invalid.

Unsupported Feature

When a parameter value requests an option that the particular firmware implementation does not support, an SFP-II report packet is sent with Cmderr containing a number that points to the first byte of the parameter that was in error. If there were multiple parameters with errors, only the first one is indicated.

Suppose the host sends the SetTouchModes (20H) command as follows to (1) enable touch detection; (2) set the TouchStateReportType to the Multi Touch State Report; and (3) set the Touch Reporting Mode to Continuous:

Touch System Programmer’s Guide 5-13

Chapter 5 - Smart-Frame Protocol II CARROLL TOUCH

66 04 20 01 02 02 FF

If the particular firmware implementation in the touch system does not support the MultiTouchState value of the TouchStateReportType parameter (the first 02H byte in the command), the touch system responds with the following report:

E0 05 02 20 01 02 02 FF

The 02 byte is Cmderr and indicates that the second parameter is in error. This parameter is the TouchStateReportType parameter. The value of 02H is a valid value for this parameter and represents a request by the host that the touch data be returned using the Multi Touch State Report. However, since this particular firmware does not support the MultiTouchState reporting method, the touch system returns the error in Cmderr to indicate this to the host.

Invalid Byte Count

The touch system reports an invalid byte count if it reads the number of bytes specified by the byte count and the next byte received is not a command packet trailer byte.

Note that this means that if the number of bytes received after the byte count is less than the byte count, no error is generated until enough additional bytes are received to match the byte count or the touch system’s input buffer overflows. The touch system does not use any sort of timeout technique if it receives fewer bytes than expected.

This error also occurs if the touch system’s input buffer overflows while it is attempting to read the number of bytes specified by the byte count.

When an invalid byte count is detected, an SFP-II report packet is sent with the Cmderr parameter set to FEH and the SFP-II report number set to the command number.

For example, suppose the host sends the following command:

66 04 20 01 04 03 FF

Due to noise on the serial line, the touch system actually receives an extra byte after the first parameter as follows:

66 04 20 01 86 04 03 FF

5-14 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 5 - Smart-Frame Protocol II

The touch system responds with the following report:

E0 06 FE 20 01 86 04 03 FF

FE is the Cmderr parameter and indicates that a byte count mismatch

error occurred. 20 is the ReportNumber parameter, and the following four bytes echo the parameters that the touch system received.

As a second example, suppose the touch system has an input buffer size of 32 bytes and the host sends the following, lengthy, incorrect command:

66 50 FA 01 02 03 ... 4F FF

The touch system reads bytes until its input buffer overflows, then responds with the following report:

E0 06 FE FA 01 02 03 ... 1D FF

FE is the Cmderr parameter and indicates that a byte count mismatch

error occurred. The following 30 bytes echo the command number and parameters that the touch system received before the input buffer overflowed.

For a complex example, suppose the touch system has an input buffer size of 32 bytes and the host sends the command as follows:

66 04 20 01 04 03 FF

Due to noise on the serial line, the touch system actually receives a value of 40H (64 decimal) for the byte count instead of 04H as follows:

66 40 20 01 04 03 FF

The touch system reads all seven bytes of the command and places them in its input buffer. No report is sent because the touch system is expecting a command that is 64 bytes in length (not counting the header, byte count and trailer), but only 5 of the 64 bytes have arrived (the command number, the three parameter bytes, and the trailer, which the touch system interprets as byte 5 of the 64 bytes that it expects to receive).

The host can then wait until the command completion timeout time of one second has elapsed, and then re-send the command. The seven bytes contained in the command are interpreted by the touch system as bytes 6 through 12 of the 64 bytes that it is expecting, and it again sends

Touch System Programmer’s Guide 5-15

Chapter 5 - Smart-Frame Protocol II CARROLL TOUCH

no report. At this point, there are 14 bytes in the input buffer, with 18 bytes remaining.

If the host repeats the timeout and re-send cycle three more times, the input buffer overflows when the third command is sent, and the touch system responds with the following report:

E0 06 FE 20 01 04 03 FF 66 04 20 01 04 03 FF 66 04 20 01 04 03 FF 66 04 20 01 04 03 FF 66 04 20 01 FF

FE is the Cmderr parameter and indicates that a byte count mismatch

error occurred. The following 30 bytes echo the command number and parameters that the touch system received before the input buffer overflowed. The touch system is now looking for a new command, and if the host sent the command once more, the touch system would receive it, process it, and return a report (presuming no error occurred in sending this latest command).

The time to re-synchronize this entire sequence would be a little over four seconds - the original command timeout (one second) plus three retry timeouts (one second each). The fourth retry would not result in a timeout because the touch system would send the report that contained the bytes read.

The host need not wait for enough timeout and re-send cycles to fill the input buffer, however. The host can accelerate re-synchronization by issuing enough FFH bytes to flush the touch system’s input buffer. This forces the input buffer to overflow and causes the touch system to begin looking for a new command. For example, if the host had used this method after the first report timeout had occurred, the touch system would have responded with the following report:

E0 06 FE 20 01 04 03 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF

FE is Cmderr and indicates that a byte count mismatch error occurred.

The following 30 bytes echo the command number and parameters, as well as the flushing FFHs that the touch system received before the input buffer overflowed. The touch system is now looking for a new command, and if the host sent the command once more, the touch system would receive and process it, and return a report (presuming no error occurred in sending this latest command). With this approach, the time to re-sync is a little over one second (the timeout for only the original command).

5-16 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 5 - Smart-Frame Protocol II

Not Enough Parameters

If the number of command parameters is less than the number of command parameters expected for the command, an SFP-II report packet is sent with Cmderr pointing to the location of the first missing parameter (the trailer).

Note that this case differs from the invalid byte count case. In this case, the command packet byte count is consistent with the total number of bytes in the command number and parameters, there just weren’t enough parameters.

If the host sends the SetTouchModes (20H) command as follows to enable touch detection and set the TouchStateReportType to the Multi Touch State Report, but leaves off the required third parameter (the TouchReportingMode parameter):

66 03 20 01 02 FF

The touch system responds with the following report:

E0 04 03 20 01 02 FF

The 03 byte is Cmderr and indicates that a third parameter was expected but not present.

Too Many Parameters

If the number of command parameters is greater than the number of command parameters expected for the command, an SFP-II report packet is sent with Cmderr pointing to the location of the first extra parameter.

Suppose the host sends the SetTouchModes (20H) command as follows. The first three parameters correctly enable touch detection (01), set the TouchStateReportType to the Multi Touch State Report (02), and set the TouchReportingMode to Continuous (02). However, an erroneous fourth parameter (04) is also included:

66 05 20 01 02 02 04 FF

The touch system responds with the following report:

E0 06 04 20 01 02 02 04 FF

The 04 byte is Cmderr and indicates that an extra parameter (the fourth parameter) was present but not expected.

Touch System Programmer’s Guide 5-17

Chapter 5 - Smart-Frame Protocol II CARROLL TOUCH

Overloaded Functions

Some SFP-II functions are overloaded in a manner similar to the way that C++ supports overloaded functions.

An overloaded function is a function that is normally used to set the values of some parameters, but can also be used to get the values of the same parameters.

• To set the parameter values, the host sends the complete command

including all parameters. The touch system sets the parameters using the values sent by the host, and returns a report that contains the resulting values for the parameters.

• To get the parameter values, the host sends only the command

number with none of the parameter values present or a subset of the parameter values present, depending on the function definition. The touch system returns a report that contains the parameter values.

If the host sends a command that includes the command number and a partial list of parameters, it is an illegal action and an invalid parameter error is returned in Cmderr.

For example, to get the current touch values using the SetTouchModes (20H) command, the host sends the command as follows:

66 01 20 FF

The touch system responds with the following report:

E0 05 00 20 01 01 00 FF

This report indicates no errors in Cmderr and reports the values for the three parameters defined for the function that were in effect when the command was sent (01, 01, and 00). No parameter values were changed.

However, to set the touch values using the SetTouchModes (20H) command, the host sends the command as follows:

66 04 20 01 01 01 FF

The touch system responds with the following report:

E0 05 00 20 01 01 01 FF

5-18 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 5 - Smart-Frame Protocol II

This report indicates no errors in Cmderr and reports the values for the three parameters defined for the function after the parameter values were changed as a result of the host sending the command (three 01 values).

If the host sends a partial list of parameters for the SetTouchModes (20H) command as follows:

66 02 20 00 FF

The touch system responds with the following report:

E0 03 02 20 00 FF

This report indicates that the second parameter byte was erroneous via Cmderr (the 02 byte) and echoes the parameters that the host sent. A Cmderr value of 02H indicates that the touch system expected more parameters than were actually received.

Shared Parameters between SFP and SFP-II

Most global parameters (that is, parameters that are not associated with a particular function) in SFP and SFP-II are independent of one another. However, some global parameters are shared between SFP and SFP-II and maintain their value when the protocol changes.

Because touch systems that support SFP and SFP-II power up in the SFP, shared parameters have an SFP default value but no SFP-II default value. The initial value of shared parameters at the time that the touch system is switched to the SFP-II is equivalent to the value of the corresponding SFP parameter at that time.

The global parameters that are currently shared include Touch Detection and Report Transfer.

Touch Detection

In the SFP, the Touch Scanning parameter is enabled and disabled via the Touch_Scanning_On (2AH) and Touch_Scanning_Off (2BH) SFP commands and is reported in the Touch Scanning parameter of the Get_State_Report (47H) SFP command.

In SFP-II, the Touch Detection parameter is set and reported via the TouchDetection parameter of the SFP-II function.

Touch System Programmer’s Guide 5-19

Chapter 5 - Smart-Frame Protocol II CARROLL TOUCH

Report Transfer

The method of transferring reports differs slightly between SFP and SFP-II. In SFP, turning Report Transfer off disables all reports, both solicited and unsolicited. In SFP-II, setting the ReportTransferMode parameter to disabled inhibits unsolicited reports but does not inhibit solicited reports.

In the SFP, the Report Transfer parameter is enabled and disabled via the Report_Transfer_On (44H) and Report_Transfer_Off (43H) SFP commands and is reported in the Report Transfer parameter of the Get_State_Report (47H) SFP command.

In SFP-II, the ReportTransferMode parameter is set and reported via the ReportTransferMode parameter of the SetTouchModes (20H) SFP-II function.

If Report Transfer is disabled when the touch system is switched to SFP-II, any SFP reports that are pending at that time are sent before the SFP-II Protocol Version Report is sent. The Report Transfer parameter remains set to disabled.

Note

The Report Transfer shared parameter is implemented in the GW DSP Serial Controller in a different manner from that described here because the SetReportTransferMode (22H) SFP-II function is not implemented on this controller. The ReportTransfer parameter is shared as described, but when the controller is switched from SFP mode to SFP-II mode, the ReportTransfer shared parameter is set to enabled. When the controller is switched from SFP-II back to SFP, the ReportTransfer shared parameter does not change value.

5-20 Touch System Programmer’s Guide

Touch

Touch Application

Application Program Interface

Program Interface (TAPI)

(TAPI)

his chapter includes an overview of the TAPI software functions,

the specifications for each function, TAPI driver installation and

initialization, and programming examples.

The chapter discusses the following topics:

• Overview.

• Installing a TAPI Driver.

• Determining if a TAPI Driver Is Installed.

• Calling TAPI Functions.

• Touch System Initialization Using a TAPI Driver.

• TAPI Programming Examples.

See Appendix C, “TAPI Function Reference,” for the specifications of each TAPI function.

Touch System Programmer’s Guide 6-1

Chapter 6 - Touch Application Program Interface (TAPI) CARROLL TOUCH

Overview

The Touch Application Program Interface (TAPI) is a set of software functions that lets an application communicate with a Carroll Touch touch system using the Smart-Frame Protocol without interfacing directly to the hardware. Using the TAPI interface protocol yields the following benefits:

• An application that interfaces to a TAPI driver is independent of

the touch system hardware. Each touch system hardware configuration has a TAPI driver, and all of these TAPI drivers share a common interface (the TAPI interface). As a result, an application that uses TAPI may be used with various touch system hardware configurations without modification by simply loading the appropriate TAPI driver.

• It is generally easier to write an application that uses TAPI

software interrupt calls to communicate with the touch system than to write an application that interfaces directly to the touch system hardware.

The TAPI interface does not include support for calibration or touch coordinate scaling. These two functions must be performed by the touch application itself, just as in touch applications that interface directly to the touch system hardware.

There are three TAPI drivers:

• Software-based controller (SBC) driver.

• Hardware-based controller (HBC) driver.

• RS-232 controller driver.

TAPI driver is a generic term used to describe all three drivers. Each TAPI driver is a terminate-and-stay-resident (TSR) program that makes it possible to use the touch system via a software interrupt rather than by directly accessing the touch system hardware.

The SBC driver must be loaded to use a touch system that uses the SBC. The SBC is unable to use the Smart-Frame Protocol directly because the SBC has no processor on board. Use of the HBC or RS-232 drivers with touch systems that use the HBC or RS-232 controller is optional, since the application may interface directly to the HBC or RS-232 controller using the Smart-Frame Protocol.

The TAPI drivers run on an IBM or IBM-compatible PC. Each TAPI driver communicates with any Carroll Touch touch system or controller

6-2 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 6 - Touch Application Program Interface (TAPI)

that recognizes the Smart-Frame Protocol and communicates either serially through a comm port or directly through the PC bus.

Installing a TAPI Driver

To install a TAPI driver, simply run the executable driver file with additional command line parameters, if appropriate, from the DOS command line. This loads the driver into memory as a TSR program.

SBC Driver

If you have set the I/O address or the interrupt number parameter of the SBC to values other than the default parameters, or if you are using a touch frame that has a different number of x-axis or y-axis beams than the default, you must provide the correct values for these parameters on the command line when installing the SBC driver.

The SBC driver command line has the following syntax:

SBC options

The available options are:

U = Uninstalls the driver.

An = I/O address. n may range from 200H to 3F0H. The

default is 300H.

In = Interrupt number override. n may be 2, 3, 4, 5, or 7. The

default is 7.

Xn = Number of x beams on frame. The default is 40.

Yn = Number of y beams on frame. The default is 30.

Sn = TAPI software interrupt. n may be the number of any

unused software interrupt. The default is 55H.

The command line is case insensitive and the command line parameters may be arranged in any order. For example, to install an SBC driver using an I/O address of 320H, interrupt 5, and 30 x-beams and 20 y-beams, you can type either:

SBC A320 I5 X30 Y20 or sbc i5 x30 a320 y20

Touch System Programmer’s Guide 6-3

Chapter 6 - Touch Application Program Interface (TAPI) CARROLL TOUCH

HBC Driver

If you have set the I/O address or the interrupt number parameters of the HBC to values other than the default parameters, you must provide the correct values for these parameters on the command line when installing the HBC driver.

The HBC driver command line has the following syntax:

HBC options

The available options are:

U = Uninstalls the driver.

An = I/O address. n may range from 200H to 3F0H. The

default is 300H.

In = Interrupt number. n may be 2, 3, 4, 5, or 7. The default

is 7.

Sn = TAPI software interrupt. n may be the number of any

unused software interrupt. The default is 55H.

The command line is case insensitive and the command line parameters may be arranged in any order. For example, to install an HBC driver using an I/O address of 340H, hardware interrupt 2, and software interrupt 57H, you can type either:

HBC A340 I2 S57

hbc i2 a340 s57

RS-232 Driver

If you have set the baud rate or parity parameters of the RS-232 controller board to values other than the default values of autobaud/autoparity, or if you are using an RS-232 port other than the default value of COM1, you must provide the correct values for these parameters on the command line when installing the RS-232 driver.

The RS-232 driver command line has the following syntax:

RS232 options

The available options are:

6-4 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 6 - Touch Application Program Interface (TAPI)

U = Uninstalls the driver.

Cn = Serial port. n may be 1 or 2. The default is 1. If the A and

I parameters are used, the C parameter is ignored.

Bn = Baud rate. n may be 3, 12, 24, 48, or 96. The default is

48.

Pn = Parity. n may be E (even), O (odd) or N (none). The

default is N.

Sn = TAPI software interrupt. n may be any unused software

interrupt. The default is 55H.

An = I/O address override. n may range from 0H to FFFFH.

The A and I parameters must be used together. An error condition occurs if one override parameter is used without the other being present.

In = Interrupt number override. n may be 2, 3, 4, 5, 6, or 7.

The A and I parameters must be used together. An error condition occurs if one override parameter is used without the other being present.

The command line is case insensitive and the command line parameters may be arranged in any order. For example, to operate the RS-232 controller at a baud rate of 4800 with no parity through serial communication port 1, you can type either:

RS232 C1 B48 PN or rs232 b48 c1 pn

If you wish to use the RS-232 driver with a serial port that uses a base I/O address and/or interrupt number other than the standard values of 3F8H and 4 for COM1 or 2F8H and 3 for COM2, you may use the A and I parameters to override the default values.

Touch System Programmer’s Guide 6-5

Chapter 6 - Touch Application Program Interface (TAPI) CARROLL TOUCH

Error Messages

Table 6-1 defines the error messages and meanings for the TAPI drivers.

Table 6-1. TAPI Error Messages and Explanations

Message: Invalid command line parameter.

Valid command line parameters are:

Meaning: The command line syntax is invalid. The installation

process is aborted.

Message: A CT driver is already installed at

software interrupt xxH.

Meaning: A CT driver has been previously installed on the same

software interrupt. xxH denotes the software interrupt. The TAPI driver looks only for the string CT DRIVER

-. It does not look for a specific type of driver.

Message: Communication error - unable to send

command. Check that the touch system is properly connected.

Meaning: The TAPI driver could not initialize the touch system

because the driver could not send commands to the touch system. A timeout occurred while attempting to transmit the command.

Message: Communication error - report expected

but not received. Check that the touch system is properly connected.

Meaning: The TAPI driver could not initialize the touch system

because a report that was expected was not received. A timeout occurred while waiting for the report.

Message: The selected RS-232 serial port was

not found.

Meaning: The RS-232 driver could not initialize the touch system

because the driver could not find the specified serial port.

6-6 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 6 - Touch Application Program Interface (TAPI)

Table 6-1. TAPI Error Messages and Explanations (Continued)

Message: TAPI driver installation failed. Meaning: This error message accompanies other error messages

and indicates that installation was aborted due to the stated condition.

Message: Communication error - report expected

but not received. Check that the touch system is properly connected.

Meaning: The TAPI driver could not initialize the touch system

because a report that was expected was not received. A timeout occurred while waiting for the report.

Message: No TAPI driver resident at software

interrupt XXH. Uninstall aborted.

Meaning: An attempt is made to uninstall a TAPI driver at

software interrupt XXH, but no TAPI signature is detected at that software interrupt.

Message: The I/O Address Override (a) and

Interrupt Number override (i) parameters must both be present in order to override the I/O address and interrupt number.

Meaning: One override parameter is present without the other.

Determining if a TAPI Driver Is Installed

An application program may determine if a TAPI driver is installed by performing a string compare starting at the address pointed to by the TAPI software interrupt vector +2. For all TAPI drivers, the first 9 characters read CT DRIVER. The type of driver is identified by an additional string:

CT DRIVER - SBC Identifies an SBC driver. CT DRIVER - HBC Identifies an HBC driver. CT DRIVER - 232 Identifies an RS-232 driver.

Calling TAPI Functions

To call a TAPI function, load the registers as described in the “Call with” sections for the TAPI functions described in Appendix C. Then,

Touch System Programmer’s Guide 6-7

Chapter 6 - Touch Application Program Interface (TAPI) CARROLL TOUCH

call the TAPI driver software interrupt and read the registers as described in the “Returns” section for that function.

The following example illustrates how to call TAPI functions:

int SendSmartFrameCommand (char command, int TAPI_sw_int) {

union REGS regs;

regs.x.ax = 1; regs.h.bh = 0; regs.h.bl = 0x32; int86 (0x55, ®s, ®s);

if (regs.x.cx)

return (1);

return (0);

} /* SendSmartFrameCommand */

Touch System Initialization Using a TAPI Driver

To initialize the touch system using a TAPI driver, send the following functions and commands in this order:

1. Call Reset (0).

2. Call SendCommand (1), with the Software_Reset (3CH) as the

Smart-Frame command (BL = 3CH). If SendCommand returns a nonzero value in CX, abort the routine.

3. Wait at least 100 ms.

4. Call SendCommand (1), with Report_Transfer_On (44H) as the

Smart-Frame command (BL = 44H).

5. Call SendCommand (1), using Get_Error_Report (32H).

6. Call GetReports (2), which loads the report into the report buffer

pointed to by BX and DX.

7. Read the Error Report out of the buffer. If there are no errors, the

report reads F8 00 FF.

At this point you may set the desired touch mode using SendCommand (1) with the appropriate Smart-Frame Protocol command, then turn on scanning by using SendCommand (1) with a Touch_Scanning_On (2AH) command. The touch system is now initialized.

6-8 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 6 - Touch Application Program Interface (TAPI)

TAPI Programming Examples

The CT Driver/Demo Disk contains three short example programs under the heading of “Programmer’s Guide Programming Examples.” They demonstrate how to interface to RS-232-based and HBC-based touch systems via a TAPI driver using the Smart-Frame Protocol. Both a polling method and an interrupt-driven method are shown for each type of touch system. All of these programs were developed using Borland C. Minor modifications may be required for other compilers.

The example files are:

CT.H Contains a Carroll Touch header file. TAPIPOL.C Contains a TAPI polling example. TAPIINT.C Contains a TAPI interrupt example.

Touch System Programmer’s Guide 6-9

Chapter 6 - Touch Application Program Interface (TAPI) CARROLL TOUCH

6-10 Touch System Programmer’s Guide

CTKERN

his chapter describes the features and capabilities of the CTKERN

driver, as well as its installation procedures and parameters. It also discusses the operation of the CTKERN calibration program (CALIB.EXE).

This chapter discusses the following topics:

• Overview.

• Calibration.

• Scaling.

• Touch Reporting.

• Calibration and Scaling Examples.

• Temporal Filter.

• Methods for Interfacing CTKERN and an Application Program.

• Loading the CTKERN Driver.

• Determining if the CTKERN Driver Is Installed.

• Calling CTKERN Functions.

• CALIB.EXE.

• CALIB.DAT.

• CTKERN Programming Examples.

See Appendix D, “CTKERN Function Reference,” for the specifications of each CTKERN function.

Touch System Programmer’s Guide 7-1

Chapter 7 - CTKERN CARROLL TOUCH

Overview

The CTKERN driver communicates with the touch system using the TAPI driver appropriate for the touch system, and with the application program using the CTKERN functions, which are accessed via a software interrupt.

CTKERN is a DOS driver that offers the following features:

• Calibration support, including multiple calibrations to allow for

monitors that do not maintain a constant image size when displaying multiple video modes.

• Touch coordinate scaling support, including multiple sets of

scaling parameters to automatically support multiple video modes.

• Easy-to-use touch state reporting.

• Support for user-installable touch event handlers for

interrupt-driven applications.

• Uninstall capability.

Calibration

The application software may not issue TAPI function calls while CTKERN is loaded. In fact, when CTKERN loads, it reads the TAPI software interrupt vector, saves it, and uses it to call the TAPI driver instead of the software interrupt. The TAPI software interrupt is replaced by a pointer to a return from interrupt instruction within CTKERN, blocking any calls to TAPI. The return from interrupt instruction is followed by a NOP and the CT DRIVER - string, so that the driver detection mechanism continues to indicate an installed TAPI driver at the TAPI software interrupt. When CTKERN is unloaded, it replaces the TAPI software interrupt vector with the value that was saved, re-enabling calls to TAPI.

The overall relationship between the touch hardware, the TAPI drivers, the CTKERN driver, and the application software is illustrated in Figure 7-1.

CTKERN allows up to ten sets of video mode specific calibration parameters. By using multiple calibrations, CTKERN can allow for monitors that do not maintain a constant image size when displaying multiple video modes. One of these sets is designated as the default calibration.

There are three options for calibration: disabled, fixed, and automatic. If calibration is disabled, the touch coordinates reported by CTKERN

7-2 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 7 - CTKERN

Application Software

(CTKERN function calls)

(CTKERN User Event Handler)

CTKERN Driver

(TAPI function calls)

(TAPI User Event Handler)

TAPI Driver (SBC, HBC, RS-232)

(Serial Xmit or I/O Ports)

(Hardware Interrupt)

Touch Hardware (SBC, HBC, RS-232)

Figure 7-1. Touch System to Application Communication are not calibrated. If fixed calibration is selected, the default calibration

is always used, regardless of the BIOS video mode being used. If automatic calibration is selected, CTKERN intercepts BIOS Int 10H and watches for SetVideoMode (0). When a SetVideoMode function occurs, CTKERN switches to the calibration parameters for that video mode if they exist. If no calibration exists for that video mode, CTKERN switches to the default calibration parameters.

SetCalibrationParameters (4) may also be used to set the calibration parameters to arbitrary values that are not related to any calibration table entry.

CTKERN attempts to read a file of calibration parameters (stored, by default, in CALIB.DAT) when it is loaded. This file is created by CALIB.EXE, the CTKERN calibration program, described later in this chapter. If no calibration file is present or if the calibration file contains multiple default calibrations, CTKERN does not load, but instead prints an appropriate error message.

The CTKERN internal table of calibration parameters may be read or modified while CTKERN is loaded by calling GetCalibrationTableEntry (7) or SetCalibrationTableEntry (6), respectively.

Touch System Programmer’s Guide 7-3

Chapter 7 - CTKERN CARROLL TOUCH

Scaling

CTKERN has the ability to scale the touch coordinates to a user-defined coordinate system. There are three options for scaling: disabled, fixed, and automatic.

If scaling is disabled, the touch coordinates reported by CTKERN are not scaled.

If fixed scaling is selected, the touch coordinates reported by CTKERN are scaled using 0, 0 for the upper left x and y scaling parameters and (Xres - 1, Yres - 1) from the calibration parameters of the default calibration entry for the lower right x and y scaling parameters, then are passed on to the application program. If no calibration entry is marked as the default, the Xres, Yres values of the first calibration entry (calibration table index 0) are used.

If automatic scaling is selected, the touch coordinates reported by CTKERN are scaled using 0, 0 for the upper left x and y scaling parameters and (Xres - 1, Yres - 1) from the calibration parameters for the currently selected BIOS video mode for the lower right x and y scaling parameters, then are passed on to the application program. The driver determines the video mode by intercepting calls to BIOS mode 10H function 0 (Set Video Mode). If an entry in the table of calibration parameters that corresponds to that video mode exists, the Xres, Yres values of those calibration parameters are used. If no such entry exists, the Xres, Yres values of the default calibration parameters are used. If no calibration entry is marked as the default, the Xres, Yres values of the first calibration entry (calibration table index 0) are used.

SetScalingParameters (9) may also be used to set the scaling parameters to arbitrary values that are not related to the Xres and Yres parameters in any calibration table entry.

CTKERN has the ability to scale the z-axis pressure parameter returned by touch systems that support z-axis pressure detection. There are only two options for z-axis scaling: disabled and enabled. When z-axis scaling is disabled, the raw z-axis parameter reported by the touch system is reported by CTKERN. If z-axis scaling is enabled, the z-axis parameter reported by the touch system is scaled linearly within the range defined by user-definable minimum and maximum pressure values.

7-4 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 7 - CTKERN

Touch Reporting

The application program may get touch reporting information from CTKERN either by calling GetTouchState (1) that returns the current touch state, or by setting up a user event handler that is called whenever the touch state changes by using SetUserEventHandlerMode (23).

Possible touch states are:

NT Not touched, with scaled (if enabled), calibrated (if enabled)

coordinates of the last place the screen was touched. If the screen has not been touched since the driver was last loaded or reset, the coordinates returned are 0, 0.

TO Touched, with scaled (if enabled), calibrated (if enabled)

coordinates of where the screen is currently being touched.

NC Non-contiguous.

The touch state is automatically maintained by CTKERN using an interrupt-driven background process.

CTKERN also includes SetTouchState (2) to manually set the touch state to a user-specified state. This can be useful for debugging and so forth.

Calibration and Scaling Examples

Because the calibration and scaling modes of CTKERN may be independently set, there are four possible combinations of calibration and scaling modes, as shown in Figure 7-2 through 7-5:

Figure 7-2: Calibration mode = Fixed or automatic

Scaling mode = Fixed or automatic

Figure 7-3: Calibration mode = Fixed or automatic

Scaling mode = Disabled

Figure 7-4: Calibration mode = Disabled

Scaling mode = Fixed or automatic

Figure 7-5: Calibration mode = Disabled

Scaling mode = Disabled

Each figure illustrates the touch coordinates that are returned for that particular combination of calibration and scaling modes. The touch

Touch System Programmer’s Guide 7-5

Chapter 7 - CTKERN CARROLL TOUCH

active area is indicated by the striped area. The range of touch coordinates that are returned by a touch within the touch active area is indicated by the coordinate pairs at the upper left and lower right corners of either the touch active area defined during calibration (the inner rectangle) or the touch active area of the touch system (the outer rectangle).

The examples all assume the following:

• A touch frame with 80 logical x-axis coordinates numbered 0 - 79,

and 60 logical y-axis coordinates numbered 0 - 59.

• Scaling parameters set to match a 640 x 480 VGA display.

Upper left x = 0 Upper left y = 0 Lower right x = 639 Lower right y = 479

• Touches at (5, 4) and (74, 55) for the upper left and lower right

corners, respectively, during calibration.

The numbers on the outside of the outer rectangle indicate the logical touch coordinates along each axis.

(0,0)

74 79

(639,479)

Figure 7-2. Calibration Mode Fixed or Automatic and Scaling Mode

Fixed or Automatic

7-6 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 7 - CTKERN

(639,479)

(0,0)

74 79

(69,51)

Figure 7-3. Calibration Mode Fixed or Automatic and Scaling Mode

Disabled

(0,0)

74 79

Figure 7-4. Calibration Mode Disabled and Scaling Mode Fixed or

Automatic

Touch System Programmer’s Guide 7-7

Chapter 7 - CTKERN CARROLL TOUCH

(79,59)

(0,0)

74 79

Figure 7-5. Calibration Mode Disabled and Scaling Mode Disabled

Temporal Filter

When enabled, the temporal filter acts much like a low pass filter in the time domain for all touch state transitions. You must define two parameters, Spatial Filter Box Size and Temporal Filter Time.

When the stylus touches the screen, the center of the spatial filter box is set to the coordinates where the screen was first touched. The touch state is set to “touched” only after the stylus has remained in the spatial filter box for the length of time specified by the Temporal Filter Time parameter.

If the stylus moves beyond the spatial filter box, the Temporal Filter Time and the center of the spatial filter box are reset. The coordinates are not updated until the stylus has once again remained in the spatial filter box for the Temporal Filter Time. The coordinates associated with the “not touched” state are still the exit point, but the touch state becomes “not touched” only after the stylus is out of the screen for the Temporal Filter Time. The touch state is set to “non-contiguous” only after a non-contiguous stylus has been in the touch screen for the Temporal Filter Time.

7-8 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 7 - CTKERN

Methods for Interfacing CTKERN and an Application Program

Application programs generally use either an interrupt mode or a polling mode to retrieve touch information.

Polling Mode

Using the polling mode, the application program periodically checks the touch state using GetTouchState (1). If the application does this at a comparatively rapid rate, touch state information is current. If the application polls at a slower rate, there is danger of missing transitions in the touch state during the time between polls.

Interrupt Mode

In the interrupt mode, the application program installs a CTKERN user event handler (UEH) using SetUserEventHandler (7). Whenever the touch state changes, CTKERN places the touch state parameters in the CPU registers and calls the application’s UEH. The application’s UEH then reads the parameters from the registers and copies them into variables within the application. The application program should keep the CTKERN UEH as short as possible, as touch information may be lost if the screen is touched while the hardware interrupts are turned off. If the CTKERN UEH is disabled for a period of time then re-enabled, touch state changes that occurred while the UEH was disabled are lost.

Loading the CTKERN Driver

Command Line

The CTKERN driver command line has the following syntax:

ctkern options

The available options follow.

U = Uninstalls the driver.

Tn = TAPI software interrupt. n may be any unused software

interrupt. The default is 55H.

Kn = CTKERN software interrupt. n may be any unused

software interrupt. The default is 56H.

Touch System Programmer’s Guide 7-9

Chapter 7 - CTKERN CARROLL TOUCH

Dx = Pathname to calibration data file. x may be any valid

pathname. The default is CALIB.DAT in the current DOS drive and directory.

The command line is case-insensitive and the command line parameters may be arranged in any order. An example command line is:

CTKERN K59 t57

If you use the uninstall command line parameter (U) to uninstall a CTKERN driver that is installed on an interrupt other than the default, you must also specify the CTKERN software interrupt on the command line by using the K parameter. For example, to uninstall a copy of CTKERN that was installed on software interrupt 59, use the following command line:

CTKERN U K59

Error Messages

Table 7-1 defines the error messages and meanings for the CTKERN driver.

Table 7-1. CTKERN Error Messages

Message: A CT driver is already installed at

software interrupt xxH.

Meaning: A CT driver has been previously installed on S/W

interrupt xxH. CTKERN looks only for the string CT DRIVER - . It does not look for a specific type of driver.

Message: Bad calibration entry in CALIB.DAT as

follows:

<the text line in CALIB.DAT that has the problem> Meaning: A calibration entry in CALIB.DAT has bad syntax. Message: CTKERN installation failed. Meaning: This error message accompanies other error messages

and indicates that installation was aborted.

7-10 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 7 - CTKERN

Table 7-1. CTKERN Error Messages (Continued)

Message: Invalid command line parameter.

Valid CTKERN command line parameters

are:

(followed by a list of valid command line parameters) Meaning: The CTKERN command line syntax is invalid. Message: No CALIB.DAT file found. Meaning: The calibration data file could not be found. Message: No TAPI driver loaded at software

interrupt xxH.

Meaning: CTKERN could not find a TAPI driver at S/W interrupt

xxH. Message: TAPI driver communication error -

invalid report received.

Check that the touch system is

properly connected.

Meaning: CTKERN could not initialize the touch system because

an invalid SFP report was received. Message: TAPI driver communication error -

report expected but not received.

Check that touch system is properly

connected.

Meaning: CTKERN could not initialize the touch system because

an SFP report that was expected was not received. (The

TAPI CheckForReports function returned a report length

of 0 in CX and CTKERN timed out waiting for the

report.) Message: TAPI driver communication error -

unable to send command.

Check that the touch system is

properly connected.

Meaning: The CTKERN driver could not initialize the touch

system because the TAPI driver reported that it could not

send SFP commands to the touch system. (The TAPI

SendCommand function returned an error code in CX.)

Touch System Programmer’s Guide 7-11

Chapter 7 - CTKERN CARROLL TOUCH

Table 7-1. CTKERN Error Messages (Continued)

Message: The CALIB.DAT file contains multiple

default calibrations.

Meaning: CALIB.DAT contains more than one default calibration. Message: The CALIB.DAT file does not contain a

default calibration.

Meaning: The calibration data file contains no default calibration. Message: The CALIB.DAT file is invalid. Meaning: The calibration data file does not contain the string

Carroll Touch Calibration Data File as

its first line of text. Message: The calibration parameters of the

following calibration entry in

CALIB.DAT are too large for the touch

system currently being used (the sum

of the offset value and span value is

greater or equal to the frame size in

one or both axes):

(followed by the bad calibration entry)

Enter a Y to truncate the X and/or Y

span values to the frame size so that

this entry is valid for the touch

system being used and continue loading

CTKERN. Press any other key to abort

CTKERN installation.

Meaning: A calibration entry has parameters too large for the touch

system being used.

Press the Y key to truncate the value and continue to load.

You must truncate all out of range calibration entries for

CTKERN to load. The truncation applies only to the

CTKERN driver resident in memory; the CALIB.DAT

file is not modified. Run CALIB.EXE to modify the

CALIB.DAT file so it contains calibration entries that

are correct for the touch system in use.

Press any key other than Y to abort CTKERN and display

the bad calibration entry.

7-12 Touch System Programmer’s Guide

CARROLL TOUCH Chapter 7 - CTKERN

Determining If the CTKERN Driver Is Installed

An application program may determine if the CTKERN driver is installed by performing a string compare starting at the address pointed to by the CTKERN software interrupt vector + 2. For all CT drivers, the first nine characters will be CT DRIVER. The type of driver (CTKERN in this case) is identified by an additional string:

CT DRIVER - CTKERN

Calling CTKERN Functions

The CTKERN functions may be accessed via the CTKERN driver software interrupt (default 56H).

To call a CTKERN function, load the registers as described in the “Call with” section for the CTKERN functions described in Appendix D. Then call the CTKERN driver software interrupt (default 56H) and read the registers as described in the “Returns” section for that function.

CALIB.EXE

An example of a CTKERN function call is:

int GetTouchState (int ctkern_sw_int, int *x_coordinate, int *y_coordinate) { union REGS regs; int touch_state;

regs.x.ax =1; int86(ctkern_sw_int, ®s, ®s);

touch_state = (int) regs.h.bl; *x_coordinate = regs.x.cx; *y_coordinate = regs.x.dx;

return(touch_state);

} /* GetTouchState */

Note that both a TAPI driver and the CTKERN driver must be installed to run CALIB.EXE, the CTKERN calibration program.

Touch System Programmer’s Guide 7-13

Elo Touch CarrollTouch Programmer's Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Table of Contents

List of Figures

List of Tables

WelcomeWelcome

Purpose

Audience

Organization

Conventions

Overview

Touch Frames

Touch Controller

Interpolating Touch Coordinates

Reporting Touch Coordinates

Failed Beams

Criteria for Failing a Beam

Failed Beam Timing Parameters

Criteria for Unfailing a Beam

Failed Beam Reports

Overview

Touch Screens

Touch Controllers

EEPROM File and Parameters

Hardware Configurations

Built-In Controllers

External Controllers

Application Program Interface

Calibration

Floating Point Calibration Program Design

Floating Point Calibration Examples

Overview

Sending a Touch Command to the HBC

Receiving Touch Data from the HBC

Polling Mode

Interrupt Mode

Resetting the HBC

Smart-Frame Protocol

Overview

SFP and SFP-II

Types of SFP Commands

Communication Commands

Reporting Method Commands

Touch Mode Commands

Information Request Commands

System Commands

Reports

Touch System Initialization

Resetting the Touch System

Power Cycle

Dedicated Reset Signal

Break (Hardware Detected)

HBC Hardware Reset Register

Break (Firmware Detected)

Reset (45H)

Performing the Autobaud/Autoparity Sequence

Checking for Touch System Errors

Setting the Reporting Method and Touch Mode

Touch System Initialization Examples

Using Autobaud/Autoparity

Using a Fixed Baud Rate

Using the HBC

Using an SBC

Compatibility Issues/Programming Tips

Number of Processors Independence

Firmware Version Independence

Frame Size Independence

Touch System Response Time Independence

SFP Timing

Autobaud/Autoparity Delay Time

Maximum Command Completion Time

Reset Time/Diagnostics Completion Time

SFP Programming Examples

Smart-Frame Protocol II

Overview

Extensibility

Modal Protocols

Backward Compatibility