Carrol Touch TouchSystems CarrollTouch Prog Programmer'S Manual Download Page 78

Page: 78 / 274

Touch System Programmer’s Guide

6-1

Touch
Application
Program Interface
(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
Application
Program Interface
(TAPI)

Summary of Contents for TouchSystems CarrollTouch Prog

Page 1: ...CARROLL TOUCH TOUCH PRODUCTS an company AMP Touch System Programmer s Guide ...

Page 2: ...Touch System Programmer s Guide CARROLL TOUCH TOUCH PRODUCTS an AMP company Part 2970 0011 01 Rev A August 1996 ...

Page 3: ...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...

Page 4: ...g 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 Calibrati...

Page 5: ...cking 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 Indep...

Page 6: ...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 ...

Page 7: ...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 46...

Page 8: ...0 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...

Page 9: ... 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 ...

Page 10: ...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 Fi...

Page 11: ...Table of Contents CARROLL TOUCH viii ...

Page 12: ...mmands 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...

Page 13: ...Table of Contents CARROLL TOUCH x ...

Page 14: ...icular 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 Audience This guide is designed for the programmer or software en...

Page 15: ... 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 Fun...

Page 16: ...on 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 va...

Page 17: ...Welcome CARROLL TOUCH xiv Touch System Programmer s Guide ...

Page 18: ...tems 1 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 T Introduction to Infrared Touch Systems ...

Page 19: ...ll 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 de...

Page 20: ...he 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 lo...

Page 21: ...ed from the number of physical beams on that touch frame axis as follows 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 ...

Page 22: ...s 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 A...

Page 23: ...e 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 Si...

Page 24: ...t 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 ...

Page 25: ...Chapter 1 Introduction to Infrared Touch Systems CARROLL TOUCH 1 8 Touch System Programmer s Guide ...

Page 26: ...n to Guided Wave Touch Systems 2 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 T Introduction to Guided Wave Touch Systems ...

Page 27: ...ns 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...

Page 28: ...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 b...

Page 29: ...Chapter 2 Introduction to Guided Wave Touch Systems CARROLL TOUCH 2 4 Touch System Programmer s Guide ...

Page 30: ... 3 1 General Programming Issues 3 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 T General Programming Issues ...

Page 31: ...e 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...

Page 32: ...ntroller 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 dr...

Page 33: ...t 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...

Page 34: ...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 i...

Page 35: ...displayed on the monitor and derives calibration parameters that may then be used to convert touch coordinates into video coordinates 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...

Page 36: ...UCH_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...

Page 37: ...s 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...

Page 38: ...ch 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 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 sendi...

Page 39: ...cation 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 If Bit 1 of the Status Re...

Page 40: ...uch 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 communicatio...

Page 41: ...Chapter 3 General Programming Issues CARROLL TOUCH 3 12 Touch System Programmer s Guide ...

Page 42: ...ng 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 T Smart Frame Pr...

Page 43: ...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 fi...

Page 44: ...e 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 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 to...

Page 45: ... 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 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 ...

Page 46: ... 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 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 Table 4 4 SFP Informat...

Page 47: ...d 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 Table 4 5 SFP System Commands Command Name Hex Code ASCII Code Associated Report 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_...

Page 48: ...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 negati...

Page 49: ...bled 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 o...

Page 50: ...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 Checking for Touch System Errors To confirm that the initialization sequence was successful determine the s...

Page 51: ...e 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 Initial...

Page 52: ... a touch system that communicates serially and used a fixed baud rate 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 3 Send the ...

Page 53: ...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 issuin...

Page 54: ...ize 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 i...

Page 55: ... 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 tou...

Page 56: ...l 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 ...

Page 57: ...Chapter 4 Smart Frame Protocol CARROLL TOUCH 4 16 Touch System Programmer s Guide ...

Page 58: ...esolution 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 T Smart...

Page 59: ...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...

Page 60: ... 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 ap...

Page 61: ...own 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 initializat...

Page 62: ... 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 Th...

Page 63: ...ntial 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...

Page 64: ... 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 pres...

Page 65: ...meter bip and a two byte parameter flap 66 04 Fubar Bip FlapHi FlapLo FF 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 Reports An SFP II report has the format header packetbytecount commanderrorstatus reportnumber optionalreportparameters trailer header Defined to be EOH pack...

Page 66: ...e 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...

Page 67: ...efined 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 det...

Page 68: ...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 a...

Page 69: ...ze 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 c...

Page 70: ...r 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...

Page 71: ...uch 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 over...

Page 72: ...efore 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 pl...

Page 73: ...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 sys...

Page 74: ...e 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 ...

Page 75: ... 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 s...

Page 76: ...s 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 p...

Page 77: ...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 i...

Page 78: ...tallation 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 T Touch Application ProgramInterface TAPI ...

Page 79: ...y 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 ...

Page 80: ...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 o...

Page 81: ...ftware 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 or hbc i2 a340 s57 RS 232 Driver If you have set the baud rate ...

Page 82: ...erride 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 ...

Page 83: ...he 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...

Page 84: ... 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 occur...

Page 85: ...lowing 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 repor...

Page 86: ...ate 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...

Page 87: ...Chapter 6 Touch Application Program Interface TAPI CARROLL TOUCH 6 10 Touch System Programmer s Guide ...

Page 88: ...B 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 spec...

Page 89: ...ctor 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 s...

Page 90: ...o 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 i...

Page 91: ... 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 calibrat...

Page 92: ...eing 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 poss...

Page 93: ...e 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...

Page 94: ... System Programmer s Guide 7 7 Figure 7 3 Calibration Mode Fixed or Automatic and Scaling Mode Disabled Figure 7 4 Calibration Mode Disabled and Scaling Mode Fixed or Automatic 0 0 0 0 5 4 55 59 74 79 69 51 0 0 0 0 5 4 55 59 74 79 639 479 ...

Page 95: ... 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 w...

Page 96: ...ler 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 hardwa...

Page 97: ...or 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 o...

Page 98: ...uld 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 w...

Page 99: ...ue 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 ...

Page 100: ...ERN 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 An example of a CTKERN function call is int GetTouchState int ctkern_sw_int int x_coordina...

Page 101: ...he default or from an installed CTKERN driver if specified on the command line If the I and D command line parameters are both specified the I parameter takes precedence and CALIB EXE loads the calibration data from the installed CTKERN driver To run CALIB EXE using the default values for the CTKERN software interrupt and read the calibration data from CALIB EXE in the current DOS drive and direct...

Page 102: ...ion table entry You are prompted to enter the calibration table index number for the default The default calibration table entry holds the calibration parameters that are used when the calibration and or scaling modes are set to fixed A default calibration table entry must be specified before exiting calibration Press 0 through 9 to display the calibration parameters for the selected calibration t...

Page 103: ...n prompted to remove your finger This process is repeated for the lower right corner and the main menu screen reappears Figure 7 8 Calibration Target Screen CTKERN Calibration V1 0 Table BiosVideo Flags Scaling Calib Params Index Mode hex Default Graphics Text Xres Yres Xoff Yoff Xspan Yspan 0 03 Yes Text 080 025 02 03 72 58 Calibration Menu 1 MONO Text 80x25 BIOS 03H 2 EGA Graphics 640x350 BIOS 1...

Page 104: ...ibration Other Video Mode Screen 2 To calibrate to a video mode that CALIB cannot display calibration target screens for take the following steps Press ESC to exit this screen then exit from this program Display a full screen image in the video mode to be calibrated for and mark the upper left and lower right corners of the image with tape Enter this calibration program again select the calibratio...

Page 105: ...2 The screen displays the calibration parameters for the selected calibration table entry along with the list of menu options You may use the keys listed in the Manual Edit Menu to edit the calibration table entry parameters When the parameters are edited as desired and you exit the manual edit menu screen the Main Menu screen reappears Delete Entry Press the D key to set all calibration parameter...

Page 106: ...ibrations are specified a message appears and you are given the option of either returning to the Main Menu or exiting CALIB without saving any calibration data Figure 7 13 Calibration Exit Prompt Screen CTKERN Calibration V1 0 Table BiosVideo Flags Scaling Calib Params Index Mode hex Default Graphics Text Xres Yres Xoff Yoff Xspan Yspan 0 03 Yes Text 080 025 05 05 64 48 Main Menu Select parameter...

Page 107: ...0002 00004 00068 00059 Decimal entries are five characters long and hexadecimal entries are four characters long The spacing between entries serves to organize them into groups CTKERN and CALIB EXE read CALIB DAT with any spacing white space independent but CALIB EXE writes the file in this format so it is more readable CTKERN Programming Examples The CT Driver Demo Disk contains three short examp...

Page 108: ...Control Panel but may also be used by an application which can then control the driver directly from within the application itself This chapter presents the information you need to use the DLLs for the Windows 3 x driver and covers the following topic Calling Windows Driver DLL Functions See Appendix E Dynamic Link Library DLL Function Reference for the specifications of each DLL T Dynamic Link Li...

Page 109: ...ucture similar to the following for the function parameter typedef struct tagTOUCHEVENTS char user_touch_event char user_untouch_event char user_noncontig_event TOUCHEVENTS_TYPE 4 Create a variable using the data structure for a function similar to the following static TOUCHEVENTS_TYPE touchevents 5 Populate the data structure and call the function All CT Windows driver functions have either no pa...

Page 110: ...ort_Buffer 3DH Continuous_Mode 27H Coordinate_Reporting 23H Echo_Off 21H Echo_On 20H Enter_Point_Mode 25H Exit_Point_Mode 28H Get_Configuration_Report 33H Get_Error_Report 32H Get_Failed_Beam_Report 36H Get_Firmware_Version_Report 34H Get_Frame_Size_Report 37H Get_One_Report 46H Get_State_Report 47H Hardware_Flow_Control_Off 42H Hardware_Flow_Control_On 41H Report_Transfer_Off 43H Report_Transfer_...

Page 111: ...ame Protocol Command Reference CARROLL TOUCH A 2 Touch System Programmer s Guide Run_Diagnostics 3AH Scan_Reporting 22H Software_Reset 3CH SwitchToSFP II 65H Touch_Scanning_Off 2BH Touch_Scanning_On 2AH Tracking_Mode 26H ...

Page 112: ...FF Get_Error_Report 32H 2 F8 Na A1 An Nb B1 Bn FF Get_Failed_Beam_Report 36H 6 FA Nx X1 T1 Xn Tn Ny Y1 S1 Yn Sn FF Get_Firmware_Version_Report 34H 4 F6 Nv V1 Vn FF Get_Frame_Size_Report 37H 7 F4 Nx Ny FF Get_One_Report 46H F F5 FF or any other report Get_State_Report 47H G F2 Nx S1 Sn FF Hardware_Flow_Control_Off 42H B _ Hardware_Flow_Control_On 41H A _ Report_Transfer_Off 43H C _ Report_Transfer_...

Page 113: ...uch_Scanning_On _ 2BH Touch_Scanning_Off _ 32H 2 Get_Error_Report F8 Na A1 An Nb B1 Bn FF 33H 3 Get_Configuration_Report F7 Nt T1 Tn FF 34H 4 Get_Firmware_Version_Report F6 Nv V1 Vn FF 36H 6 Get_Failed_Beam_Report FA Nx X1 T1 Xn Tn Ny Y1 S1 Yn Sn FF 37H 7 Get_Frame_Size_Report F4 Nx Ny FF 3AH Run_Diagnostics F8 Na A1 An Nb B1 Bn FF 3CH Software_Reset _ 3DH Clear_Touch_Report_Buffer _ 41H A Hardwar...

Page 114: ...Point Mode and the Add Exit Point modifier is set a Touch Coordinate Report is sent when the stylus enters the touch active area and an Add Exit Point Coordinate Report is sent when the stylus is removed from the touch active area The touch system default is Add Exit Point modifier disabled Report Format The Add Exit Point Coordinate Report has the following format FD X Y FF FD Start of Add Exit P...

Page 115: ...inate or Non Contiguous Coordinate Report from the touch report buffer This command is useful when the host does not need old touch data such as when it is moving from one menu page to the next The command does not stop a report in the process of being transmitted Once transmission has begun the entire report is transmitted Reports requested by the host cannot be cleared from the touch report buff...

Page 116: ...ether the stylus is moving or stationary Process control applications use Continuous Mode to control specific functions such as filling a tank Report Format When the touch mode is set to Continuous Mode the touch system reports the coordinates of the stylus using the Touch Coordinate Report See Coordinate Reporting 23H in this appendix for the format of the Touch Coordinate Report and Non Contiguo...

Page 117: ...ng The system default reporting method is coordinate reporting Report Format The current touch mode determines the type of report that is sent and when it is sent The Touch Coordinate Report has the following format FE X Y FF FE Start of Touch Coordinate Report X X axis logical touch coordinate Y Y axis logical touch coordinate FF End of report Non Contiguous Coordinate Reports are issued whenever...

Page 118: ...ndicate a specific selection or trigger a critical function See Add_Exit_Point_Modifier 29H in this appendix for details of the Add Exit Point Coordinate Report Example An example of a Touch Coordinate Report is FE 04 10 FF It indicates that the center of the stylus at logical coordinate x is 4 and the center of the stylus at logical coordinate y is 16 See Also Scan_Reporting 22H Enter_Point_Mode ...

Page 119: ...ff character is not sent back to the host Echo_Off is the system default Example The example below sends the Echo_On 20H command followed by a test sequence that checks every bit position and ends with the Echo_Off 21H command 20 01 02 04 08 10 20 40 80 21 Note While Echo Mode is on wait for each byte to be echoed back before sending the next byte to the touch system See Also Echo_On 20H ...

Page 120: ...munications are operating correctly send the Echo_On 20H command a test sequence and the Echo_Off 21H command The touch system should return the Echo_On character and the test sequence exactly as it was transmitted from the host Example The example below sends the Echo_On 20H command followed by a test sequence that checks every bit position and ends with the Echo_Off 21H command 20 01 02 04 08 10...

Page 121: ...ansmitted until an empty scan no stylus located within the touch active area is detected indicating that the stylus has left the touch active area Enter Point Mode is most commonly used to select a sequence of items on a single menu or when an immediate response is required Report Format See Coordinate Reporting 23H in this appendix for the format of the Touch Coordinate Report and Non Contiguous ...

Page 122: ...oint Mode is used for menu selection It lets the stylus enter the touch active area and move to the desired target without activating a selection until the stylus leaves the touch active area This can be advantageous for small or very complex screen designs or for educational purposes when the user is not familiar with the selections Report Format See Coordinate Reporting 23H in this appendix for ...

Page 123: ... Report Na Number of processors in the touch system Aa Identifier of first processor An Identifier of last processor FF End of report Note The identifiers for each processor no longer have any meaning associated with them but are included for historical reasons The Get_Configuration_Report 33H command has been retained so that the number of processors in the touch system may be determined Example ...

Page 124: ... Bn FF F8 Start of Error Report Na Number of first processor errors to follow Aa An Error codes defined in Table A 3 Nb Number of second processor errors to follow Ba Bn Error codes defined in Table A 3 FF End of report If the touch system does not detect any errors the following report is sent F8 00 FF Reports no errors for single processor systems F8 00 00 FF Reports no errors for dual processor...

Page 125: ...SDSF Frame Modular Controller 02H RAM Random Access Memory verification error The processor RAM has an error and must be repaired 68705 Smart Frame Frame 8031 Pre modular separate controller UFP III Controller 8031 Smart Frame SDSF Frame Modular Controller 03H A D converter error An error has been detected in the analog digital circuitry and must be repaired 68705 Smart Frame Frame 8031 Pre modula...

Page 126: ...han it could process them Increase the timing delay between commands 0AH Invalid command received A command that is not recognized as valid was received from the host Note that a 0DH will be treated as valid command during the autobaud phase but as an invalid command after the autobaud phase 0BH External RAM Random Access Memory checksum verification error 68705 Smart Frame N A No external RAM 803...

Page 127: ...one failed beam s detected error was found See Also Get_Configuration_Report 33H Get_Firmware_Version_Report 34H Software_Reset 3CH Run_Diagnostics 3AH 12H 18H Reserved 19H External Read Only memory ROM checksum verification error 68705 Smart Frame N A No external ROM 8031 Pre modular separate controller UFP III Frame EEPROM 8031 Smart Frame SDSF Frame EEPROM Modular Frame EEPROM 1AH up Reserved T...

Page 128: ...e is not functioning if the touch system hardware allows this If the touch system hardware does not allow such an analysis the status indicator is set to firmware could not determine problem 0 for all failed beams specified in the Failed Beam Report Report Format The Failed Beam Report has the following format FA Nx Xa Ta Xn Tn Ny Ya Sa Yn Sn FF FA Start of Failed Beam Report Nx Number of x beam r...

Page 129: ...f failed y beams has the same values 0 4 and definitions as status of failed x beams FF End of report Example An example of a Failed Beam Report is FA 01 03 02 00 FF It indicates that there is one failed x beam beam number 3 that its LED failed and that there are no failed y beams See Also Failed Beams in Chapter 2 ...

Page 130: ...n of second component Vn Firmware version of last component FF End of report Example A Firmware Version Report for a touch system with one firmware version to report follows F6 01 2D 30 30 30 34 2D 30 30 2D 2D FF The 2D 2D parameters indicate one firmware version report ASCII 0004 00 Caution Do not hard wire the code that interprets the Firmware Version Report so that it only works with a specific...

Page 131: ...he reported firmware versions are as follows 68705 Smart Frame Firmware version 1 Slave processor EPROM Firmware version 2 Master processor EPROM 8031 Pre Modular UFP III Firmware version 1 EPROM Firmware version 2 EEROM if present otherwise EPROM firmware version is repeated 8031 Smart Frame SDSF and Modular Firmware version 1 EPROM Firmware version 2 EEROM ...

Page 132: ...ies the size of the touch frame expressed as the number of logical coordinates on each axis Report Format The Frame Size Report has the following format F4 X Y FF F4 Start of Frame Size Report X Number of x axis logical coordinates Y Number of y axis logical coordinates FF End of report Example An example Frame Size Report is F4 4F 3B FF It indicates that the coordinate ranges are 0 78 x axis logi...

Page 133: ...ed off Note When using the Get_One_Report 46H command with hardware flow control off wait until the full report sequence is received before sending the next command to the touch system Report Format If no reports are available to be transmitted when the Get_One_Report 46H command is sent the touch system returns a Null Report to the host The report has the following format F5 FF F5 Start of Null R...

Page 134: ...wing format F2 NS SRM SOM STS SUE SRT SHF FF F2 Start of State Report NS Number of state bytes returned SRM Reporting method 1 Coordinate method 2 Scan method SOM Touch Mode 1 Tracking Mode Add Exit Point modifier off 2 Enter Point Mode Add Exit Point modifier off 3 Continuous Mode Add Exit Point modifier off 4 Exit Point Mode Add Exit Point modifier off 5 Tracking Mode Add Exit Point modifier on ...

Page 135: ...of report Note The SOM byte is not valid under scan reporting Example An example of a State Report is F2 06 01 03 02 01 02 01 FF The six state bytes indicate the reporting method is coordinate the touch mode is continuous touch scanning is on reserved bit report transfer is on and hardware flow control is off ...

Page 136: ...the host Data Terminal Ready DTR is ignored by the touch system and Smart Frame Protocol reports are always transmitted For touch systems that use the modular RS 232 controller Clear To Send CTS is always asserted indicating that the touch system is ready to receive commands even when it is not For Smart Frame type touch systems CTS follows the state of Request To Send RTS signal from the host and...

Page 137: ...erforming some other activity and is not ready to receive commands The Data Terminal Ready DTR signal is used to regulate data transmission from the touch system to the host The host controls the state of the DTR signal and should assert DTR by applying a positive voltage and deassert DTR by applying a negative voltage If the host asserts DTR the touch system transmits Smart Frame Protocol reports...

Page 138: ...s to scan until another report is generated and stored in the touch report buffer The touch system then stops scanning and waits for the host to send either the Report_Transfer_On 44H Get_One_Report 46H or Clear_Touch_Report_Buffer 3DH command When the host sends Report_Transfer_On 44H the touch system sends the coordinates in the touch report buffer if any or scans until another report is ready f...

Page 139: ...ommand Description The Report_Transfer_On 44H command allows the Smart Frame to send reports to the host computer Use this command when the host processor is fast enough to receive touch data at the rate at which it is sent The system default setting for report transfer is off See Also Report_Transfer_Off 43H Get_One_Report 46H ...

Page 140: ...Guide A 31 Reset 45H E Command Description When the touch system receives the Reset 45H command the touch system reenters initialization mode Use this command for resetting the touch system to initialization mode at the end of an application See Also Touch System Initialization in Chapter 4 ...

Page 141: ...Report The touch system then resets the system defaults just as if the power had been turned off and then on again The performance of these diagnostics routines may take up to one second to complete Since the touch system defaults are reset the host must send either the Report_Transfer_On 44H command or the Get_One_Report 46H command to the touch system so that the host can receive the Error Repor...

Page 142: ...e upper left corner Touch modes are not recognized when the reporting method is set to scan reporting The scan reporting method is not supported by the software based controller SBC Report Format The Scan Report has the following format FB Nx Xa Xb Xc Xn Ny Ya Yb Yc Yn FF FB Start of Scan Report Nx Number of x axis physical beams interrupted Xa Xn List of x axis physical beams interrupted Ny Numbe...

Page 143: ...g the autobaud autoparity sequence and must be followed by a delay of at least 100 milliseconds to allow time for the initialization sequence to finish if autobaud autoparity is being used It is recommended but not required that a 100 millisecond delay be included even if autobaud autoparity is not being used See Also Get_Error_Report 32H Table A 4 Touch System Default Settings System Parameter De...

Page 144: ... The version report is structured such that it is also a legal SFP report that is none of the bytes between the header and the trailer are larger than DFH This means that an application that uses a layered protocol for validating SFP reports can continue to use its SFP report validation layer until after this report is received Refer to the GetProtocolVersion 65H SFP II command in Appendix B for a...

Page 145: ...04 00 65 02 20 FF As a second example assume the touch system is using SFP report transfer is disabled and an SFP Error Report that indicates no errors for a one processor touch system is pending The host sends the SwitchToSFP II SFP command as follows 65 Once the touch system successfully switches to SFP II it responds first with the pending SFP Error Report then the Protocol Version Report as fo...

Page 146: ... Touch_Scanning_Off 2BH Command Description The Touch_Scanning_Off 2BH command causes the touch system to stop scanning the infrared beams Use this command when the touch system is not currently being used as an input device The touch system default is touch scanning off See Also Touch_Scanning_On 2AH ...

Page 147: ...the infrared beams When Report Transfer is also on the touch system sends interrupted beam data to the host in the formats defined by the currently selected reporting method Both the desired reporting method and touch mode should be selected before touch scanning is turned on although they may also be changed with touch scanning on The touch system default setting is touch scanning off See Also To...

Page 148: ...rts when the stylus is stationary and resumes sending Touch Coordinate Reports if the stylus begins to move again Tracking Mode is fundamentally identical to Continuous Mode except that the touch system does not send redundant Touch Coordinate Reports when the stylus is stationary Tracking Mode is used in applications where cursor positioning is required such as graphics applications Tracking Mode...

Page 149: ...Appendix A Smart Frame Protocol Command Reference CARROLL TOUCH A 40 Touch System Programmer s Guide ...

Page 150: ...n alphabetic and numeric order respectively and subsequently gives the details of each SFP II function GetConfiguration 11H GetCoordinateRanges 10H GetProtocolVersion 65H GetTouchState 01H SetReportProperties 21H SetReportTransferMode 22H SetTouchModes 20H SwitchToClassicSFP 64H T Smart Frame Protocol II Function Reference ...

Page 151: ...etCoordinateRanges 10H GetProtocolVersion 65H GetTouchState 01H SetReportProperties 21H SetReportTransferMode 22H SetTouchModes 20H SwitchToClassicSFP 64H Table B 2 SFP II Functions in Numerical Order Hexadecimal Function Function Name 01H GetTouchState 10H GetCoordinateRanges 11H GetConfiguration 20H SetTouchModes 21H SetReportProperties 22H SetReportTransferMode 64H SwitchToClassicSFP 65H GetPro...

Page 152: ... be added as needed Application or driver software that seeks to list the entire configuration of a touch system should maintain a table of strings that match the defined component types attribute types and attribute values and should display those strings if the numeric values for the types and values correspond to a string in the table If a numeric value for a type or value does not correspond t...

Page 153: ... Unknown The component exists and has attributes but its type could not be determined 1 Sensor frame This is the touch sensing portion of the touch system such as a GW sensor or IR frame 2 Controller This is the portion of the touch system that controls one or more touch sensing portions of the touch system 3 Processor This is the portion of the touch system that executes the operating firmware No...

Page 154: ...trol uses to detect touches 02 Interface Specifies the interface method used by the controller 03 GW Dual Sensitivity Specifies whether the controller supports the dual sensitivity feature i e it supports two sensitivity parameters the Entry Sensitivity and Tracking Sensitivity parameters as opposed to one sensitivity parameter the Touch Sensitivity parameter 00 Unknown 01 Infrared 02 Guided Wave ...

Page 155: ...cessor 03 with one attribute 01 of processor family 01 of DSP 01 A guided wave sensor with a guided wave serial 8051 touch system may report E0 13 00 11 03 01 01 01 02 02 03 01 02 02 01 03 01 03 01 01 02 FF The above report is the same as the previous report except that the controller supports dual sensitivity 01 and the processor is of the 8051 family 02 A guided wave sensor with a guided wave du...

Page 156: ...mponent is a frame 01 with one attribute 01 of touch technology 01 of IR 01 The second component is a controller 02 which happens to be integrated with the frame with three attributes 03 a touch technology attribute 01 of IR 01 an interface attribute 02 of RS 232 01 and a sensitivity attribute 03 which does not support dual sensitivity 00 The third component of the controller is a processor 03 wit...

Page 157: ...m will report for each coordinate axis Report Format 10 XMinHi XMinLo XMaxHi XMaxLo YMinHi YMinLo YMaxHi YMaxLo ZMinHi ZMinLo ZMaxHi ZMaxLo XMinHi XMinLo Minimum x axis coordinate 16 bit XMaxHi XMaxLo Maximum x axis coordinate 16 bit YMinHi YMinLo Minimum y axis coordinate 16 bit YMaxHi YMaxLo Maximum y axis coordinate 16 bit ZMinHi ZMinLo Minimum z axis coordinate 16 bit ZMaxHi ZMaxLo Maximum z a...

Page 158: ...h system responds with a Coordinate Ranges Report similar to the following E0 0E 00 10 00 00 07 AA 00 00 0B AB 00 01 00 0F FF In this example the x axis coordinates range from 0 to 1962 00H to 07AAH the y axis coordinates range from 0 to 2987 00H to 0BABH and the z axis coordinates range from 1 to 15 01H to 000FH ...

Page 159: ...tocol Version Report returns the version number of the firmware protocol in an xx yz format using Binary Coded Decimal BCD encoding This report is also sent in response to the SwitchToSFP II 65H SFP command if a touch system that supports SFP II receives that command while it is in SFP mode This mechanism can used by an application to determine if the touch system supports SFP II Report Format 65 ...

Page 160: ...Reference Touch System Programmer s Guide B 11 The touch system responds with a Protocol Version Report similar to the following E0 04 00 65 02 13 FF In this example the protocol version is 2 13 See Also SwitchToSFP II 65H in Appendix A SwitchToClassicSFP 64H ...

Page 161: ...ld use either the TouchReportingMode parameter in the SetTouchModes 20H command the preferred method or the ReportingMode parameter in the SetReportProperties 21H command to indicate under what conditions the Touch State Report should be sent To send Touch State Reports to the host only when requested set the Reporting Mode to solicited only To send Touch State Reports continuously or whenever a p...

Page 162: ... 16 bit z coordinate Example To determine the location of a touch the host sends the GetTouchState 01H command as follows 66 01 01 FF The touch system responds with a Touch State Report similar to the following E0 09 00 01 01 00 0C 07 D3 00 00 FF In this example the screen is being touched at x 12 000CH and y 2003 07D3H The z axis is not supported See Also SetTouchModes 20H SetReportProperties 21H...

Page 163: ...Solicited Only Mode The touch system only sends the selected report in response to having received the corresponding command Parameter Change Mode The touch system sends the selected report both in response to having received the corresponding command and whenever any of the parameters contained in the report changes Continuous Mode The touch system sends the selected report in response to having ...

Page 164: ...here is one place in the code that decides when to send a report for all reports then no extra development effort is required to allow the report to be set to all modes even though it doesn t make sense to do so In fact extra development effort would be required to prevent the report from being able to be set to all reporting modes If however a situation arises where it is deemed necessary to proh...

Page 165: ...on number of 02 or greater to a function The ability to assign version numbers of 02 or greater is reserved for future firmware implementations Refer to Extensibility in Chapter 5 for more information regarding the use of this parameter Examples If the host sends the SetReportProperties 21H command as follows 66 02 21 01 FF The touch system responds with the following report assuming that function...

Page 166: ...ast 00 The reporting mode parameter is undefined and reported as 00 in the next to last 00 If function 01 is defined and the continuous reporting mode 02 is valid for that particular function and the host sends the SetReportProperties 21H command as follows 66 03 21 01 02 FF The touch system responds with the following report E0 05 00 21 01 02 01 FF This report indicates no errors in Cmderr and re...

Page 167: ... 18 Touch System Programmer s Guide This report indicates that the second parameter byte was erroneous via Cmderr the 02 byte This indicates that the reporting mode property could not be set to continuous 02 for this particular function See Also SetReportTransferMode 22H ...

Page 168: ...arameter Change Mode or Continuous Mode using SetTouchModes 20H The SetReportTransferMode 22H command sets the ReportTransferMode SFP II global parameter via the ReportTransferMode function parameter When ReportTransferMode is set to disabled the transfer of unsolicited reports from the touch system to the host is inhibited The transfer of solicited reports from the touch system to the host is una...

Page 169: ...e SFP II global parameter to a value other than enabled or disabled an invalid parameter error is returned in Cmderr The primary purpose of the SetReportTransferMode 22H command is to provide the host computer with the means to implement software flow control in the touch system to host direction The host may use the SetReportTransferMode 22H command to inhibit report transfer from the touch syste...

Page 170: ...rMode Returns the value to which the ReportTransferMode SFP II global parameter is currently set Legal values for the report transfer mode parameter are 00 Disabled The transfer of unsolicited reports from the touch system to the host is inhibited 01 Enabled The transfer of both solicited and unsolicited reports from the touch system to the host is unaffected Examples If the host sends the SFP Rep...

Page 171: ...H command as follows to set the state of the ReportTransferMode SFP II global parameter to disabled and inhibits unsolicited reports 66 02 22 00 FF The touch system responds with a Report Transfer Mode Report to indicate the new state of the ReportTransferMode parameter E0 03 00 22 00 FF If the screen is touched again the touch system does not send any Touch State Reports because all unsolicited r...

Page 172: ...hen sends another command as follows 66 01 65 FF The touch system again responds with a Protocol Version Report similar to the following E0 04 00 65 01 15 FF Again this report is sent even though the ReportTransferMode global parameter is set to disabled because it is a solicited report See Also SetReportProperties 21H ...

Page 173: ...number with any other combination of parameters an invalid parameter error is returned in Cmderr The SetTouchModes 20H command sets the report properties of each of the Touch State Reports to implement the functionality specified by the TouchStateReportType and TouchReportingMode parameters For example if the TouchStateReportType parameter was set to Touch State Report and the TouchReportingMode p...

Page 174: ...ll shared parameters there is no SFP II default for this parameter The initial value of this parameter is equivalent to the value of the corresponding SFP parameter at the time that the touch system is switched to the SFP II protocol Refer to Chapter 5 for more details on shared parameters TouchStateReportType Selects the type of touch state report that is to be sent when the touch system detects ...

Page 175: ... the touch reporting mode parameter match the values for the ReportingMode parameter in SetReportProperties 21H Report Description The Set Touch Modes Report returns the current values of the parameters that control how the touch system detects and reports touch information Report Format 20 TouchDetection TouchStateReportType TouchReportingMode TouchDetection Reports the enable status of the touch...

Page 176: ...ges including coordinate changes 02 Continuous The touch system sends the touch state report both in response to having received the corresponding command and each time that it executes its main executive loop This should mean that the touch system reports the touch state after every scan Note that the values for the touch reporting mode parameter match the values for the ReportingMode parameter i...

Page 177: ...et to 02 reflects the fact that the touch system expected more parameters than were actually received If the host sends the SetTouchModes 20H 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 This report indicates no errors in Cmderr and reports the values for the three parameters defined for the function after the parameter values ...

Page 178: ...5H SFP command Command Format 64 Report Description The Switch To Classic SFP Report reports to the host the result of the touch system s attempt to return to the classic SFP Report Format 64 SwitchResult SwitchResult Indicates whether the switch to SFP mode was successful 00H Switch successful 01H Switch failed touch system still in SFP II Examples While in SFP II mode the host sends the SwitchTo...

Page 179: ...Appendix B Smart Frame Protocol II Function Reference CARROLL TOUCH B 30 Touch System Programmer s Guide ...

Page 180: ... numeric order respectively and subsequently gives the details of each function CheckForReports 3 GetCommunicationParameters 4 GetReports 2 GetTAPIDriverConfiguration 6 GetUserEventHandlerParameters 8 Reset 0 SendCommand 1 SetCommunicationParameters 5 SetSBCFrameSize 40H SetUserEventHandler 7 T TAPI Function Reference ...

Page 181: ...iverConfiguration 6 GetUserEventHandlerParameters 8 Reset 0 SendCommand 1 SetCommunicationParameters 5 SetSBCFrameSize 40H SetUserEventHandler 7 Table C 2 TAPI Functions in Numerical Order Function AX Function Name 0 Reset 1 SendCommand 2 GetReports 3 CheckForReports 4 GetCommunicationParameters 5 SetCommunicationParameters 6 GetTAPIDriverConfiguration 7 SetUserEventHandler 8 GetUserEventHandlerPa...

Page 182: ...eports Call with AX 3 function number Returns AX 3 function number CX Number of bytes available for transfer to the report buffer 0 No reports available no bytes transferred nonzero Reports were available number of bytes available for transfer to the buffer Notes The application program may use this function to poll the driver to determine if any reports are available The SBC driver does not retur...

Page 183: ...iver type in order to interpret the driver specific parameters If this is not done that is the application is hard wired to a specific driver type the resulting touch application may not be compatible with other TAPI drivers Call with AX 4 function number Returns AX 4 function number BH Driver type 0 SBC driver 1 HBC driver 2 RS 232 driver If BH 0 SBC or 1 HBC the additional returns are BL Interru...

Page 184: ...CARROLL TOUCH Appendix C TAPI Function Reference Touch System Programmer s Guide C 5 CL Baud rate 0 300 1 600 2 1200 3 2400 4 4800 5 9600 ...

Page 185: ...le number of bytes transferred to the report buffer Notes The report buffer is an area of memory in the application program that is dedicated to receiving Smart Frame Protocol reports One or several reports may be sent to the report buffer Only complete reports are sent to the report buffer No partial reports are sent The buffer size value passed in CX is the maximum number of bytes that the TAPI ...

Page 186: ...ion number CX Protocol version number 01 00 Indicates SFP all other Indicates the specific version number of SFP II If the driver version is represented as X YZ then the version number in register BX is in the following format 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 Notes Table C 3 gives examples of how version numbers are represented in BX BH 0 X BL Y Z Table C 3 Typical BL BH Register Contents Version N...

Page 187: ... Add Exit Point Coordinate Report report header FDH Non Contiguous Coordinate Report report header FCH and Scan Report report header FBH are all classified as coordinate reports and are enabled if bit 0 of the event mask is set All other reports are classified as non coordinate reports and are enabled if bit 1 of the event mask is set If the user event handler is enabled for all reports both event...

Page 188: ...fer only clears the TAPI report buffer It does not send a Clear_Touch_Report_Buffer 3DH command to the touch system Call with AX 0 function number BH 0 BL Select driver touch system reset 0 Reset touch system and driver 1 Reset driver only 2 Reset touch system only 3 Reset report buffer only Returns AX 0 function number CX Reset result 0 Reset OK 1 TAPI driver could not send commands to touch syst...

Page 189: ...ber CX Command status 0 Command accepted 1 Command could not be transmitted to the touch system because a time out occurred The TAPI driver has a time out value of approximately 150 ms 2 Command not supported by TAPI driver The SBC driver does not support the full Smart Frame command set If a valid SFP command is sent but is not supported by the SBC driver CX is set to 2 Notes For more specific in...

Page 190: ...he driver type in order to interpret the driver specific parameters If this is not done that is the application is hard wired to a specific driver type the resulting touch application may not be compatible with other TAPI drivers Call with AX 5 function number BH Driver type 0 SBC driver 1 HBC driver 2 RS 232 driver If BH 0 SBC or 1 HBC the additional calls are BL Interrupt number Valid values are...

Page 191: ... not contain a value representing the RS 232 comm port being used Note that sending the SetCommunicationParameters function only changes the communication parameters for commands that are subsequently sent to the touch system by the TAPI driver The touch system communication parameters must also be set to the same communication parameters for proper communication to take place If an SBC or HBC is ...

Page 192: ... This function is supported by the SBC driver only Call with AX 40H function number BX Number of physical beams on the x axis CX Number of physical beams on the y axis Returns AX 40H function number Notes It is best to set the frame size parameters by passing them on the command line when loading the SBC driver Avoid using this command since it violates the philosophy of interchangeability between...

Page 193: ...corresponds to the type of report is set When the UEH is called the CPU registers contain the following BX Segment of the TAPI driver s internal report buffer CX Number of report bytes available for transfer DX Offset of the TAPI driver s internal report buffer The UEH may then read report bytes from the buffer up to the number of bytes in CX Any bytes read from the buffer beyond the value passed ...

Page 194: ...ent address of user event handler DX Offset address of user event handler Returns AX 7 function number Notes Hardware interrupts are disabled during the user event handler The interrupt enable flag is cleared with a CLI instruction Use of reentrant function calls such as BIOS calls in the user event handler is acceptable as is the use of TAPI function calls in the user event handler However use of...

Page 195: ...rEventHandler 7 read one report per event in the user event handler and exit the UEH with an AX nonzero causing the report buffer to be cleared Before terminating the user program be sure to disable the UEH either by using SetUserEventHandler 7 or Reset 0 Otherwise when the TAPI driver calls the address of where the user program s event handler was it will now be an invalid address The SBC driver ...

Page 196: ... GetCurrentScalingModeAndParameters 10 GetTemporalFilterModeAndParameters 16 GetTAPIDriverConfiguration 19 GetTouchState 1 GetTouchSystemStatus Configuration 17 GetUserEventHandlerModeAndParameters 25 GetZ AxisScalingModeAndParameters 13 Reset 0 SendSmartFrameProtocolCommandAndGetReport 18 SetCalibrationMode 3 SetCalibrationParameters 4 SetCalibrationTableEntry 6 SetCommunicationParameters 21 SetS...

Page 197: ...x D CTKERN Function Reference CARROLL TOUCH D 2 Touch System Programmer s Guide SetTouchState 2 SetUserEventHandlerMode 23 SetUserEventHandlerParameters 24 SetZ AxisScalingMode 11 SetZ AxisScalingParameters 12 ...

Page 198: ...arameters 16 GetTAPIDriverConfiguration 19 GetTouchState 1 GetTouchSystemStatus Configuration 17 GetUserEventHandlerModeAndParameters 25 GetZ AxisScalingModeAndParameters 13 Reset 0 SendSmartFrameProtocolCommandAndGetReport 18 SetCalibrationMode 3 SetCalibrationParameters 4 SetCalibrationTableEntry 6 SetCommunicationParameters 21 SetScalingMode 8 SetScalingParameters 9 SetTemporalFilterMode 14 Set...

Page 199: ...Mode 9 SetScalingParameters 10 GetCurrentScalingModeAndParameters 11 SetZ AxisScalingMode 12 SetZ AxisScalingParameters 13 GetZ AxisScalingModeAndParameters 14 SetTemporalFilterMode 15 SetTemporalFilterParameters 16 GetTemporalFilterModeAndParameters 17 GetTouchSystemStatus Configuration 18 SendSmartFrameProtocolCommandAndGetReport 19 GetTAPIDriverConfiguration 20 GetCTKERNDriverConfiguration 21 S...

Page 200: ...Call with AL 7 function number BH Calibration table entry retrieval method 00 Retrieve by calibration table index 01 Retrieve by searching for a video mode BL Calibration table index if BH 00 BL BIOS video mode to search for if BH 01 CX Segment of eight word buffer to hold the calibration data structure DX Offset of eight word buffer to hold the calibration data structure Returns AL Calibration st...

Page 201: ...ault calibration flag 0 This entry is not the default calibration 1 This entry is the default calibration Notes The internal calibration table consists of ten sets of calibration parameters The valid range for the calibration table index parameter is 0 through 9 If this function is called with a calibration table index outside this range the calibration status is set to 01 the calibration table in...

Page 202: ...pplication program should read the BH driver type register to determine how to interpret the remaining registers Call with AL 22 function number Returns BH Driver type 0 SBC driver 1 HBC driver 2 RS 232 driver If BH 0 SBC or 1 HBC the additional returns are BL Interrupt number CX I O address If BH 2 RS 232 the additional returns are BL Comm port 1 COM1 2 COM2 CH Parity 0 None 1 Odd 2 Even CL Baud ...

Page 203: ...nction number Returns BX CTKERN driver version number If the CTKERN driver version is represented as X YZ then the version number in register BX is in the following format 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 Notes Table D 3 gives examples of how version numbers are represented in BX BH 0 X BL Y Z Table D 3 Typical BX Register Contents Version Number Register BH Contents Register BL Contents 1 0 01 00 ...

Page 204: ...ation data structure returned are undefined Call with AL 5 function number CX Segment of four word buffer to hold the calibration data structure DX Offset of four word buffer to hold the calibration data structure Returns BL Calibration mode 00 Calibration disabled 01 Fixed calibration 02 Automatic calibration The calibration data structure that contains the calibration data for the calibration th...

Page 205: ... data structure are undefined Call with AL 10 function number CX Segment of four word buffer to hold the scaling data structure DX Offset of four word buffer to hold the scaling data structure Returns BL Scaling mode 00 Scaling disabled 01 Fixed scaling 02 Automatic scaling The scaling data structure that contains the scaling data for the scaling that is in effect at the time that this function is...

Page 206: ...function number Returns BX TAPI driver version number If the driver version is represented as X YZ then the version number in register BX is in the following format 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 Notes Table D 4 gives examples of how version numbers are represented in BX BH 0 X BL Y Z Table D 4 Typical BL BH Register Contents Version Number Register BH Contents Register BL Contents 1 0 01 00 2 1 ...

Page 207: ...onal returns are CX Spatial filter box size expressed as a percentage of the full screen size DX User specified temporal filter time ms This parameter returns the exact number of milliseconds set by the call to SetTemporalFilterParameters 15 If BL is 01 absolute parameters the additional returns are CH Spatial filter box size x actual size of the box in pixels CL Spatial filter box size y actual s...

Page 208: ... SetScalingParameters 9 for more information about setting the default origin All touch coordinates reported are scaled and calibrated according to the scaling and calibration modes and parameters that are in effect at the time that the touch event occurred not at the time that the coordinates are reported For example if the scaling mode was set to fixed with Xres Yres set to 640 200 and the scree...

Page 209: ...y the minimum and maximum z axis pressure values If the touch system hardware does not support the z axis BH is set to 0 if z axis scaling is disabled If z axis scaling is enabled BH is set to the minimum pressure value If the calibration mode is set to fixed or auto and the screen is touched outside of the calibrated area the coordinates of the point inside the calibrated area closest to the loca...

Page 210: ...ructure for details the host received unexpected data from the touch system or expected data was missing 02 Unable to communicate with the touch system Touch system status configuration data structure in the buffer pointed to by CX and DX is BYTE Number of processors BYTE Number of processor 1 errors 8 BYTES Processor 1 errors BYTE Number of processor 2 errors 8 BYTES Processor 2 errors WORD X fra...

Page 211: ...AndParameters 25 Description This function returns the parameters associated with the user event handler Call with AL 25 function number Returns BL User event handler mode 00 User event handler disabled 01 User event handler enabled CX Segment address of user event handler DX Offset address of user event handler ...

Page 212: ...D 17 GetZ AxisScalingModeAndParameters 13 Description This function gets the z axis scaling parameters Call with AL 13 function number Returns BL Z axis scaling mode 00 Z axis scaling disabled 01 Z axis scaling enabled CL Minimum z axis pressure value DL Maximum z axis pressure value ...

Page 213: ...eset touch system only Returns AL Reset result 0 Reset OK 1 The TAPI driver indicated that it could not send commands to the touch system 2 The TAPI driver indicated that it received an error report from the touch system that contained error codes 3 The TAPI driver indicated that it did not receive the expected error report from the touch system Notes If BL 0 Reset touch system and driver 1 Reset ...

Page 214: ... D CTKERN Function Reference Touch System Programmer s Guide D 19 2 Call TAPI with BL 2 Reset touch system only 3 Send init string via TAPI to set the touch system to the tracking with add exit touch mode and enable scanning ...

Page 215: ...ment of report buffer that holds the Smart Frame Protocol report received from the touch system DX Offset of report buffer that holds the Smart Frame Protocol report received from the touch system Returns AL Smart Frame Protocol command status 00 Smart Frame Protocol command accepted 01 Invalid SFP command An SFP command other than Get_Failed_Beam_Report 36H and State_Report 47H was sent CX Number...

Page 216: ...that a timeout occurred and no report bytes were transferred The report buffer should be at least 64 bytes long Since the CTKERN driver can transfer a maximum of 512 bytes to the report buffer the maximum report buffer size necessary is 512 bytes No touch data is processed while this command is processed The actual algorithm used in this command is 1 Disable TAPI driver event handler 2 Send comman...

Page 217: ...tomatic the raw touch coordinates are calibrated using the calibration parameters for the currently selected BIOS video mode The driver determines the video mode by intercepting calls to BIOS mode 10H function 0 SetVideoMode If an entry in the table of calibration parameters that corresponds to that video modes exists those calibration parameters are used If no such entry exists the default calibr...

Page 218: ... lets you set the calibration parameters to arbitrary values that are not related to the calibration parameters in any calibration table entry The calibration mode should be set to fixed when this function is used If the calibration mode is set to automatic the next video mode change causes the calibration parameters to be overwritten by the calibration parameters that correspond to the calibratio...

Page 219: ...ucture DX Offset of eight word buffer that holds the calibration data structure Returns AL Calibration status 00 Calibration table entry set successfully 01 Calibration table index out of range 02 Calibration offset and or span out of range Calibration data structure in the buffer pointed to by CX and DX WORD VideoMode WORD Flags WORD Xres WORD Yres WORD Xoff WORD Yoff WORD Xspan WORD Yspan The bi...

Page 220: ...default calibration flag is set the default calibration flag of all of the other calibration table entries is cleared This is done in order to help ensure that there is only one default calibration Setting the calibration table entry for the calibration that is currently in effect does not immediately affect the current calibration or scaling parameters For example if the calibration mode is set t...

Page 221: ...ion number BH Driver type 0 SBC driver 1 HBC driver 2 RS 232 driver If BH 0 SBC or 1 HBC the additional calls are BL Interrupt number Valid values are 2 3 4 5 and 7 CX I O address Valid values are from 200H through 3F0H in 10H increments 200H 210H 220H 3F0H If BH 2 RS 232 the additional calls are CH Parity 0 None 1 Odd 2 Even CL Baud rate 0 300 1 600 2 1200 3 2400 4 4800 5 9600 Returns CX Status 0...

Page 222: ...tes This function is very similar to GetCommunicationParameters 22 except that register BL does not contain a value representing the RS 232 communication port being used Sending this function causes CTKERN to modify the communication parameters and then reset the touch system just as if Reset 0 was called For any touch system other than an RS 232 based touch system using autobaud autoparity the co...

Page 223: ...s 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 before being passed on to the application program The driver determines the video mode by intercepting calls to BIOS mode 10H function 0 SetVideoMode If an entry in the table of calibration p...

Page 224: ... that are not related to the Xres and Yres parameters in any calibration table entry The scaling mode should be set to fixed when using this function If the scaling mode is set to automatic the next video mode change causes the scaling parameters to be overwritten by the scaling parameters that correspond to the calibration table entry for that video mode The default origin for the Touch Coordinat...

Page 225: ...left x 0 Upper left y 479 Lower right x 639 Lower right y 0 The screen reports 0 479 when the upper left corner is touched 639 0 when the lower right corner is touched and 0 0 when the lower left corner is touched This places the origin in the lower left corner By swapping either or both axes the origin may be placed in any corner ...

Page 226: ...inates 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 th...

Page 227: ... is run on several monitors of differing sizes the absolute size of the spatial filter box will vary and may need to be adjusted The Temporal Filter Time is specified in milliseconds The valid range for this parameter is between 0 ms and 2000 ms and the default is 500 ms The actual filter time that is used however is restricted to multiples of 55 ms The actual formula used is as follows absolute t...

Page 228: ...ime value is set to a value large enough so that entry and exit coordinate transients resulting from the stylus not entering leaving straight into out of the screen are eliminated but small enough so that the delay time is not noticeable The typical range of values to achieve this is 100ms through 500ms ...

Page 229: ...x would vary if the display resolution changed as a result of a change in the BIOS video mode Note that while the same percentage is used for both the x and y axes the absolute size of the box is not necessarily square The box instead has the same aspect ratio as the display No correction for display aspect ratio is performed The absolute pixel value is derived by taking a percentage of either the...

Page 230: ... the time value is 495 The filter time resolution is 55 ms which means that the actual amount of time that is required to trigger a touch may vary from the actual filter time by 55 ms Normally the time value is set to a value large enough so that entry and exit coordinate transients resulting from the stylus not entering leaving straight into out of the screen are eliminated but small enough so th...

Page 231: ...hed x y set to last place the screen was touched 01 Touched x y set to where the screen is touched 02 Non contiguous x y undefined CX X coordinate DX Y coordinate Notes If calling this function causes the touch state to change and a CTKERN user event handler is installed and enabled the user event handler is called just as if the change in touch state had resulted from an actual touch You must ens...

Page 232: ...n installed and enabled execution of the user program is halted and the event handler subroutine is called whenever the touch state changes When the UEH is called the CPU registers contain the following BH Z axis touch pressure BL Touch state 0 Not touched x y set to last place screen was touched 1 Touched x y set to where the screen is touched 2 Non contiguous x y undefined CX X coordinate DX Y c...

Page 233: ...o allow the TAPI driver to continue to process hardware interrupts from the touch system If the UEH takes too long to return the TAPI driver may miss hardware interrupts from the touch system The UEH is called once and only once each time the touch state changes While the UEH is disabled CTKERN continues to update the touch state When re enabled after being disabled the UEH is NOT called to notify...

Page 234: ...ce Touch System Programmer s Guide D 39 SetUserEventHandlerParameters 24 Description This function sets the user event handler parameters Call with AL 24 function number CX Segment address of user event handler DX Offset address of user event handler ...

Page 235: ... scaling mode 00 Z axis scaling disabled 01 Z axis scaling enabled Notes If 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 CTKERN is determined by linearly scaling the raw z axis parameter reported by the touch system within the range defined by the minimum and maximum z axis press...

Page 236: ...mber CL Minimum z axis pressure value DL Maximum z axis pressure value Notes The origin of the z axis parameter may be changed from the minimum z axis pressure value to the maximum z axis pressure value by specifying a larger value for the maximum z axis pressure value than for the minimum z axis pressure value The default value for the minimum and maximum z axis pressure values are 0 and 255 resp...

Page 237: ...Appendix D CTKERN Function Reference CARROLL TOUCH D 42 Touch System Programmer s Guide ...

Page 238: ...ndix Subsequent sections give specific details on each function its data structure and function call DisableMouse 11 DisableTouch 12 EnableMouse 9 EnableTouch 10 GetMouseInfo 13 GetTemporalFilterInfo 18 GetTouchInfo 14 GetTouchStateandCoord 5 InitializeTouch 16 SetCalibInfo 7 SetTemporalFilterInfo 17 SetTouchEvents 8 T Dynamic Link Library DLL Function Reference ...

Page 239: ...tMouseInfo 13 GetTemporalFilterInfo 18 GetTouchInfo 14 GetTouchStateandCoord 5 InitializeTouch 16 SetCalibInfo 7 SetTemporalFilterInfo 17 SetTouchEvents 8 Table E 2 Windows Driver DLL Functions in Numerical Order Ordinal Export Value Function Name 5 GetTouchStateandCoord 7 SetCalibInfo 8 SetTouchEvents 9 EnableMouse 10 EnableTouch 11 DisableMouse 12 DisableTouch 13 GetMouseInfo 14 GetTouchInfo 16 ...

Page 240: ...unction Reference Touch System Programmer s Guide E 3 DisableMouse 11 Description This function disables the mouse IMPORTS Statement in the Definition File DisableMouse MOUSE 11 Functions Prototype void FAR PASCAL DisableMouse Function Call DisableMouse ...

Page 241: ...CARROLL TOUCH E 4 Touch System Programmer s Guide DisableTouch 12 Description This function disables the touch system IMPORTS Statement in the Definition File DisableTouch MOUSE 12 Functions Prototype void FAR PASCAL DisableTouch Function Call DisableTouch ...

Page 242: ...ion Reference Touch System Programmer s Guide E 5 EnableMouse 9 Description This function enables the mouse for user input IMPORTS Statement in the Definition File EnableMouse MOUSE 9 Functions Prototype void FAR PASCAL EnableMouse Function Call EnableMouse ...

Page 243: ...LL TOUCH E 6 Touch System Programmer s Guide EnableTouch 10 Description This function enables the touch system for user input IMPORTS Statement in the Definition File EnableTouch MOUSE 10 Functions Prototype void FAR PASCAL EnableTouch Function Call EnableTouch ...

Page 244: ...flags variable define MFLAG_ENABLED0x01 Mouse is enabled define MF_INT33H 0x02 Int 33H mouse found 0x04 0x08 0x10 0x20 define MF_ON_SLAVCPIC0x040 Mouse is on slave PIC define MF_MOUSE_EXISTS0x080 Mouse was found at boot time Definitions of mouse types for the mouse_type variable define MT_NO_MOUSE 0 define MT_BUS 1 define MT_SERIAL 2 define MT_INPORT 3 define MT_PS2 4 define MT_HP 5 define MT_INT3...

Page 245: ...E 8 Touch System Programmer s Guide GetTemporalFilterInfo 18 Description To be determined IMPORTS Statement in the Definition File To be determined Functions Prototype To be determined Data Structure and Parameter Variable To be determined Function Call To be determined ...

Page 246: ...ameter Variable Definitions of the flag byte touch_flags define TF_ENABLED 0x01 Touch is enabled 0x02 0x04 0x08 0x10 0x20 define TF_ON_SLAVEPIC0x040 Touch is on slave PIC define TF_TOUCH_EXISTS 0x080 Touch was found at boot time Definitions of touch types for the touch_type variable define TT_NO_TOUCH 0 define TT_TAPI 1 define TT_HBC 2 define TT_RS232 3 typedef struct tagTOUCHINFO char touch_flags...

Page 247: ...tended purpose for this function is to provide raw touch data to a calibration program IMPORTS Statement in the Definition File GetTouchStateandCoord Mouse 5 Functions Prototype void FAR PASCAL GetTouchStateandCoord LPSTR Data Structure and Parameter Variable define NOT_TOUCHED 0 define TOUCHED 1 typedef struct tagTOUCHSTATEANDCOORDS char touch_state char Xcoord char Ycoord TOUCHSTATEANDCOORDS_TYP...

Page 248: ...itializes the touch system The touch system type and communication parameters that were in effect when Windows was started are used IMPORTS Statement in the Definition File InitializeTouch MOUSE 16 Functions Prototype void FAR PASCAL InitializeTouch LPSTR Data Structure and Parameter Variable static char initresult Function Call InitializeTouch initresult ...

Page 249: ...d to the upper left and lower right corners of the video image This is typically done by displaying touch targets in the corners and using the GetTouchStateandCoord function to get the raw touch information You then calculate the calibration parameters as shown in the CalculateCalibInfo function and send them to the driver via SetCalibInfo IMPORTS Statement in the Definition File SetCalibInfo MOUS...

Page 250: ...ag_float static float Ymag_float static float Xoff_float static float Yoff_float Xmag_float video_max_xy touch_lr_x touch_ul_x calibinfo Xmag Xmag_float Ymag_float video_max_xy touch_lr_y touch_ul_y calibinfo Ymag Ymag_float Xoff_float Xmag_float touch_ul_x calibinfo Xoff Xoff_float Yoff_float Ymag_float touch_ul_y calibinfo Yoff Yoff_float CalculateCalibInfo CalculateCalibInfo SetCalibInfo calibi...

Page 251: ...e 0 define TFTI_142ms 1 define TFTI_285ms 2 define TFTI_428ms 3 define TFTI_571ms 4 define TFTI_714ms 5 define TFTI_857ms 6 define TFTI_1000ms 7 Definitions of legal values for the temporal_filter_space variable define TFSP_0 0 define TFSP_1 1 define TFSP_2 2 define TFSP_3 3 define TFSP_4 4 define TFSP_5 5 define TFSP_6 6 define TFSP_7 7 define TFSP_8 8 define TFSP_9 9 define TFSP_A A define TFSP_...

Page 252: ...ry DLL Function Reference Touch System Programmer s Guide E 15 Function Call temporalfilter_params TFTime TFTI_142ms temporalfilter_params TFSpace TFSP_2 SetTemporalFilter temporalfilter_params if temporalfilter_params FF then T_F_ not supported ...

Page 253: ...ts LPSTR Data Structure and Parameter Variable typedef struct tagTOUCHEVENTS char user_touch_event char user_untouch_event char user_noncontig_event TOUCHEVENT_TYPE static TOUCHEVENTS_TYPE touchevents Function Call touchevents user_touch_event 2 touchevents user_untouch_event 3 touchevents user_noncontig_event 0 SetTouchEvents touchevents Table E 3 Definition of Touch Events Event Definition Touch...

Page 254: ...ouch screen which either replaces or is fastened over the existing bezel of the monitor broken beam A beam in which the infrared light level received by the infrared sensitive phototransistor falls below a threshold value set by the touch system firmware In normal operation this is due to a stylus obstructing the beam path from the LED to the phototransistor Broken beams may also result from a def...

Page 255: ...the serial RS 232 controller EEPROM An electrically erasable programmable read only memory EEPROM chip Enter Point Mode A touch reporting type under the SFP that reports only the coordinates at which a stylus enters the touch screen Add Exit Point reporting can be added as a modifier Exit Point Mode A touch reporting type under the SFP that reports only the coordinates at which the stylus exits th...

Page 256: ...ccupy the spaces between physical beams In each axis the number of logical beams is twice the number of physical beams minus one logical coordinates A coordinate system consisting of an x and y axis each made up of logical beams The origin of the coordinate system is the upper left corner of the display touch frame logical frame size The logical frame size is double the physical frame size minus o...

Page 257: ...that determines the form used to send data from the touch system to the host The touch system reports a list of physical beams that are interrupted in each axis See also coordinate reporting scanning infrared technology See infrared touch technology serial RS 232 controller A touch system independent digital controller containing a microprocessor This controller requires an external 12V power supp...

Page 258: ...ter space A parameter that defines a guardband around a touch point within which other touches are not reported This reduces demands upon system processing temporal filter time A parameter that reduces the frequency of coordinate reporting which helps differentiate valid touches from noise and other transient events touch active area The area inside the touch frame or touch screen that is sensitiv...

Page 259: ...overlay containing a transducer and reflectors 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 Touch S...

Page 260: ...oparity sequence 4 8 4 9 4 14 automatic calibration 7 2 D 22 automatic scaling 7 4 D 28 autoparity 3 2 3 3 B backward compatibility 5 4 baud rate 3 2 3 3 4 9 beam 1 2 beam averaging 1 3 beam pair 1 2 bezels 3 2 BIOS video mode D 5 D 22 built in controllers 3 2 C CALIB DAT 7 3 7 10 7 14 7 20 CALIB EXE 7 3 7 13 calibration 3 6 4 13 7 2 7 5 D 22 automatic 7 2 D 22 calibration table 7 15 D 5 D 22 D 24...

Page 261: ...rpretation layer SFP II 5 6 5 7 command packet SFP II 5 5 5 7 command trailer SFP II 5 6 command validation layer SFP II 5 6 5 7 communication commands SFP 4 3 component B 3 Configuration Report 4 5 4 13 A 14 Continuous Mode 5 11 B 14 Continuous_Mode 27H SFP command 4 4 A 7 controller 1 2 2 2 3 2 coordinate origin corner 2 3 Coordinate Ranges Report B 8 Coordinate_Reporting 23H SFP command 4 4 A 8...

Page 262: ...installing the driver 7 13 interrupt mode 7 9 overview 7 2 polling mode 7 9 programming examples 7 20 Reset 0 D 18 scaling automatic 7 4 disabled 7 4 example 7 5 fixed 7 4 z axis parameter 7 4 SendSmart FrameProtocolCommandAndGetReport 18 D 20 SetCalibrationMode 3 D 22 SetCalibrationParameters 4 D 23 SetCalibrationTableEntry 6 D 24 SetCommunicationParameters 21 D 26 SetScalingMode 8 D 28 SetScalin...

Page 263: ...ta structure 8 2 definition 8 1 DisableMouse 11 E 3 DisableTouch 12 E 4 EnableMouse 9 E 5 EnableTouch 10 E 6 functions list in alphabetical order E 2 functions list in numerical order E 2 GetMouseInfo 13 E 7 GetTemporalFilterInfo 18 E 9 E 14 GetTouchInfo 14 E 9 GetTouchStateandCoord 5 E 10 IMPORTS statement in the DEF file 8 2 InitializeTouch 16 E 11 LPSTR parameter 8 2 parameter variable 8 2 SetC...

Page 264: ... C 13 Frame Size Report 4 5 A 23 function prototype 8 2 FunctionVersion 5 2 G Get Configuration Report B 3 B 4 Get_Configuration_Report 33H SFP command 4 5 4 13 A 14 Get_Error_Report 32H SFP command 1 7 4 5 4 9 4 13 6 8 A 15 Get_Failed_Beam_Report 36H SFP command 1 7 4 5 A 19 Get_Firmware_Version_Report 34H SFP command 4 5 4 13 A 21 Get_Frame_Size_Report 37H SFP command 4 5 A 23 Get_One_Report 46H...

Page 265: ...tTouchStateandCoord 5 DLL function E 10 GetTouchSystemStatus Configuration 17 CTKERN function D 15 GetUserEventHandlerModeAndParameters 25 CTKERN function D 16 GetUserEventHandlerParameters 8 TAPI function C 8 GetZ AxisScalingModeAndParameters 13 CTKERN function D 17 global parameters 5 19 guided acoustic wave touch system 2 2 3 2 3 3 5 2 H hardware flow control 4 3 4 9 hardware handshaking A 27 A...

Page 266: ... 6 invalid byte count 5 14 invalid command numbers 5 12 invalid parameter value 5 13 Invalid Touch Fail Time 1 6 L layered protocol 5 6 light emitting diodes 1 2 logical beams 1 3 logical coordinate system 1 3 M maximum logical coordinate 1 4 MDI cable 3 2 3 3 mini DIN sensor cable 3 2 modal protocol 4 2 5 4 mode switching commands SFP II 5 5 Modular Digital Interface see MDI 3 2 modular infrared ...

Page 267: ... 3 9 3 10 7 9 D 37 programming examples CTKERN 7 20 SFP 4 14 TAPI 6 9 protocol version 5 2 5 3 Protocol Version Report 4 6 5 2 5 3 5 20 A 35 B 10 R Raw Touch State Report 5 11 reentrant function calls C 15 reflector array 2 2 report buffer C 6 report format SFP 4 6 report format SFP II 5 8 report header SFP 4 6 report header SFP II 5 8 report interpretation layer SFP II 5 10 report packet SFP II 5...

Page 268: ...ected 4 7 using the Reset 45H SFP command 4 8 re synchronization 5 16 RS 232 controller 3 3 3 4 RS 232 driver 3 5 6 2 RS 232 driver command line 6 4 RS 232 serial interface 3 4 Run_Diagnostics 3AH SFP command 4 6 A 32 S saving calibrations 7 19 SBC driver 3 5 6 2 SBC driver command line 6 3 scaling automatic 7 4 D 28 disabled 7 4 D 28 fixed 7 4 D 28 D 29 modes 7 5 D 10 parameters D 10 D 29 Scan Re...

Page 269: ...Mode 23 CTKERN function 7 5 D 37 SetUserEventHandlerParameters 24 CTKERN function D 39 SetVideoMode 0 7 3 SetZ AxisScalingMode 11 CTKERN function D 40 SetZ AxisScalingParameters 12 CTKERN function D 41 SFP Add_Exit_Point_Modifier 29H A 5 application program interface 3 4 Clear_Touch_Report_Buffer 3DH A 6 command categories 4 2 commands 4 2 commands list in alphabetical order A 3 commands list in n...

Page 270: ...g method commands 4 3 reports 4 6 Reset 45H A 31 Run_Diagnostics 3AH A 32 Scan_Reporting 22H A 33 Software_Reset 3CH A 34 SwitchToSFP II 65H A 35 system commands 4 5 timing parameters autobaud autoparity delay 4 14 maximum command completion 4 14 reset diagnostics completion 4 14 touch mode commands 4 4 Touch_Scanning_Off 2BH A 37 Touch_Scanning_On 2AH A 38 Tracking_Mode 26H A 39 using an SBC 4 12...

Page 271: ...t validation layer 5 9 reporting mode Continuous Mode 5 11 Parameter Change Mode 5 11 Solicited Only Mode 5 11 reset and touch reporting commands 5 5 SetReportProperties 21H B 14 SetReportTransferMode 22H B 19 SetTouchModes 20H B 24 shared parameters 5 19 ReportTransferMode 5 20 Touch Detection 5 19 status reporting commands 5 5 SwitchToClassicSFP 64H B 29 shared parameters 5 19 Single Axis Touch ...

Page 272: ...rs 4 C 4 GetReports 2 C 6 GetTAPIDriverConfiguration 6 C 7 GetUserEventHandlerParameters 8 C 8 HBC driver 6 2 initializing a touch system 6 8 installing a driver 6 3 6 7 installing the HBC driver 6 4 installing the RS 232 driver 6 4 overview 6 2 programming examples 6 9 Reset 0 C 9 RS 232 driver 6 2 SBC driver 6 2 SendCommand 1 C 10 SetCommunicationParameters 5 C 11 SetSBCFrameSize 40H C 13 SetUse...

Page 273: ...ngs A 34 touch system diagnostics software 1 6 Touch_Scanning_Off 2BH SFP command 4 6 4 12 5 19 A 37 Touch_Scanning_On 2AH SFP command 4 6 4 10 4 12 5 19 6 8 A 38 Tracking Mode A 39 Tracking_Mode 26H SFP command 4 4 A 39 transducer 2 2 2 3 TSR program 6 2 U Unfail Time 1 6 1 7 unsolicited reports 5 11 B 14 unsupported feature 5 13 untouch event E 16 user event handler 3 5 7 9 D 16 D 37 D 39 V Vali...

Page 274: ...uch 512 244 3500 Switchboard 2800 Oakmont Drive 800 386 8241 Toll Free Round Rock Texas 78664 512 388 5643 Order Assistance 512 388 5509 Technical Support 512 244 7040 Fax http www carrolltouch com 512 388 5668 Bulletin Board 14400K N81 ...

Search results

Summary of Contents for TouchSystems CarrollTouch Prog

Reviews:

Related manuals for TouchSystems CarrollTouch Prog

Brands by name

Popular brands

Carrol Touch TouchSystems CarrollTouch Prog, Programmer'S Manual

Search results

Summary of Contents for TouchSystems CarrollTouch Prog

Reviews:

Related manuals for TouchSystems CarrollTouch Prog

Brands by name

Popular brands