Tactex Controls TCIMTCEXP100 Touchpad Input Device User Manual Multi Touch Manual

Tactex Controls Inc. Touchpad Input Device Multi Touch Manual

Contents

Users Manual part 3

Part 3 – API ReferenceThis section provides a brief description of the API functions and datadefinitions.API Data StructuresMTCCreatetypedef struct MTCCREATE {char *inputPort; // name of the input driverchar *outputPort; // name of the output driverchar *mappingFile; // path and filename of the mapping filechar *normalFile; // path and filename of thenormalization file} MTCCreate;MTCCompTypetypedef enum {MTCCompNone,MTCCompThresh,MTCCompDefault} MTCCompType;MTCQueryTypetypedef enum {MTCQueryCurrent,MTCQueryDefault,MTCQueryMax,MTCQueryCount} MTCQueryType;MTCConfigtypedef struct MTCCONFIG {int nTaxels;int nRows;int nCols;float xDimension;float yDimension;char *unitDescriptor;} MTCConfig;MTC Express3-1
MTC Express3-2MTCPointertypedef struct MTCPOINTER {BOOL valid_pointer;int pointer_num;float pressure;float x_pos;float y_pos;float x_vel;float y_vel;} MTCPointer;API Function DescriptionsConnecting and DisconnectingMTCHandle MTC_New(MTCCreate mtcCreate)This function creates an instance of a Tactex MTC object. In theprocess, this function does the following:a. Allocates memory for the MTC object.b. Reads the mapping (configuration) file from disk.c. Reads the normalization file from disk. If a normalization file with the name specified does not exist, then one is automatically created.d. Opens the serial communication driver.e. "pings" the MTC to verify a connection.f. Determines the MTC Express firmware version.Parameters:mtcCreate - A structure specifying the input and output serial ports andlocations of the mapping and normalization files.Return:MTC_New() returns a handle to a touch pad instance. It returns NULL ifthe function failed to create a new instance of the MTC.MTC_GetLastError() can be called with a NULL argument todetermine the cause of failure.BOOL MTC_Delete(MTCHandle hMTC)This function stops the communication with the MTC identified by hMTCand frees the system resources allocated for the particular MTC.Parameters:hMTC - handle of the MTC.Return:MTC_Delete() returns a TRUE if successful. Otherwise a FALSE isreturned.
Version and ConfigurationBOOL MTC_GetAPIVersion(char *apiVer)This function fills the buffer pointed to by apiVer with an API versionstring. The API version sting is null-terminated and consists of no morethan 50 characters.Parameters:apiVer - pointer to a buffer which must be at least 50 bytes longReturn:MTC_GetAPIVersion() returns TRUE if successful. Otherwise FALSE isreturned.BOOL MTC_GetConfig(MTCHandle hMTC, MTCConfig *config)This function fills the config structure with the configuration data of thespecified MTC. If a MTC descriptor string has not been received fromthe MTC, the host computer will poll the MTC for its descriptor string.Parameters:hMTC - handle of the MTC from which the configuration data isrequested.config - pointer to a MTCConfig structure to be filled with theconfiguration data.Return:MTC_GetVersion() returns TRUE if successful, FALSE otherwise.Int MTC_GetDescriptorString(MTCHandle hMTC,char *descStr, intmsecWait)This function stops the data stream from the MTC, and fills the bufferpointed to by descStr with a null-terminated string containing theconfiguration information obtained from the MTC Express. Thisfunction will wait for a response from the MTC for up to msecWaitmilliseconds. The unit descriptor string will also be placed in theinternal API memory for future reference when MTC_GetConfig() iscalled. This function is automatically called by the API whenMTC_New is called, so a more efficient way to get the descriptor stringis to call MTC_GetConfig.Parameters:hMTC - handle of the MTC.descStr - pointer to place unit descriptor stringmsecWait - Allowed response time specified in millisecondsReturn:The length of the configuration string is returned. Zero is returned if theMTC failed to respond.MTC Express3-3
Error ReportingMTCErr MTC_GetLastError(MTCHandle hMTC)This function returns the error code associated with the specified MTC.If hMTC is NULL, then it returns general errors not associated with aspecific MTC. If no errors are associated with the specific MTC, thengeneral errors are checked. Once an error has been reported, it iscleared (i.e. subsequent calls to MTC_GetLastError() will not reportthe same event). However, some errors are accumulated andMTC_GetLastError() may be called successively in order to retrievethem.Parameters:hMTC - handle of the MTC.Return:The MTCErr is returned.char *MTC_GetErrorString(MTCErr errCode)This function returns a pointer to a null-terminated string that providesa brief description of the specified error code. Parameters:errCode - Error code specifying a MTC error return byMTC_GetLastError()Return:A pointer to the error string specified by errCode is returned.Control of the Data StreamBOOL MTC_GetIsConnected(MTCHandle hMTC, int msecWait)This function pings the specified MTC. It returns TRUE if the MTCresponds to the ping within the time specified by msecWait.Parameters:hMTC - handle of the MTC.msecWait – maximum allowable response time specified inmilliseconds.Return:ATRUE is returned if the host computer is connected to the MTC.Otherwise a FALSE is returned.MTC Express3-4
BOOL MTC_StartSendingData(MTCHandle hMTC, MTCCompTypecompressionType, int msecWait)This function initiates the stream of data from the MTC. It will wait upto msecWait milliseconds for a response before returning. It isnecessary to call this function before MTC_GetNormalizedData orMTC_GetRawData.Parameters:hMTC - handle of the MTC.compressionType - Instruct the MTC to use a specified compressionmethodmsecWait - Allowed response time specified in millisecondsReturn:ATRUE is returned if the data-stream was successfully initiated. If thedata-stream was not detected before the time-out period or if the hMTCis not valid, a FALSE is returned.BOOL MTC_StopSendingData(MTCHandle hMTC, int msecWait)This function stops the stream of data from the specified MTC. It willwait up to msecWait milliseconds for acknowledgement from the MTC.Parameters:hMTC - handle of the MTC.msecWait – Maximum allowable response time specified inmilliseconds.Return:ATRUE is returned if the data stream has been successfully initiated.Otherwise a FALSE is returned.MTC Express3-5
float MTC_SetSampleRate(MTCHandle hMTC, float sampleRate,MTCCompType compressionType, int msecWait)The sample rate of the MTC Express is the rate at which it measuresthe pressure over the entire pad (i.e. all 72 taxels). Data from the MTCExpress is transmitted over the serial cable after each completesample. Due to bandwidth limitation of the serial connection, highersampling frequencies must use data compression. This function setsthe MTC Express sample rate using the compressionType specified.Some MTC Express units may not be capable of sampling at thedesired sampleRate.Parameters:hMTC - handle of the MTC.sampleRate - desired MTC sample rate.compressionType - set the MTC compression type.msecWait - Allowed response time specified in millisecondsReturn:A sample rate closest to the input parameter sampleRate is returnedusing the compressionType specified. A sample rate of zero isreturned if the operation was unsuccessful.float MTC_GetSampleRate(MTCHandle hMTC, MTCCompTypecompressionType, MTCQueryType queryType)This function returns the rate at which the MTC Express can transmitdata using the compressionType specified. The queryType is used tospecify the current setting, default or maximum sample rates. Thisfunction does not change the operation of the API or MTC Express, itsimply reports what the MTC Express is capable of. SpecifyingMTCQueryCurrent ignores the compressionType and retrieves the lastsample rate requested of the connected MTC; useMTC_GetMeasuredSampleRate() to return the actual sample rate.Parameters:hMTC - handle of the MTC.compressionType - the MTC compression type. queryType - the current, default or maximum sample rate.Return:The (current, default or maximum) sample rate, in Hz, usingcompressionType.MTC Express3-6
float MTC_GetMeasuredSampleRate(MTCHandle hMTC)This function returns a measured sample rate from the specified MTC.This sample rate is calculated by dividing the number of samplesreceived from the MTC in a pre-set time period. Parameters:hMTC - handle of the MTC.Return:A measured sample rate, in Hz (samples/second), is returned.Control of NormalizationBOOL MTC_BeginNormalization(MTCHandle hMTC)This function starts the automatic normalization (calibration) process.It resets the data calibration parameters and sets a flag internal to theAPI so that subsequent calls to MTC_GetRawData orMTC_GetNormalizedData will update those parameters.Parameters:hMTC - handle of the MTC.Return:ATRUE is returned if the normalization process is started correctly.BOOL MTC_EndNormalization(MTCHandle hMTC, BOOL saveToDisk)This function completes the normalization process. This functionfreezes the API’s internal data calibration parameters. If saveToDisk isTRUE, the normalization file is overwritten, otherwise the normalizationdata continues to be used for this session, but the file is notoverwritten.Parameters:hMTC - handle of the MTC.saveToDisk - When TRUE, the normalization data is saved to disk.Return:TRUE is returned if the normalization process is successful.MTC Express3-7
Data Gatheringlong MTC_GetRawData(MTCHandle hMTC, WORD *dataPtr)This function fills the array pointed to by dataPtr with the taxel rawpressure data received from the MTC Express.Parameters:hMTC - handle of the MTC.dataPtr - pointer to a memory location capable of storing taxel data.The user is required to ensure that the array is long enough.Return:The MTC Express measures, or samples, the pressure on the touchpad up to 200 times per second. After each measurement, the MTCExpress transmits the data over the serial port, and tags the datapacket with its sample number. The MTC_GetRawData function returnsthat sample number if data is present. Otherwise 0is returned.long MTC_GetNormalizedData(MTCHandle hMTC, WORD *dataPtr)This function fills the array pointed to by dataPtr with normalized taxelpressure data.Parameters:hMTC - handle of the MTC.dataPtr - pointer to a memory location capable of storing normalizedtaxel data.Return:The sample number is returned if data is present. Otherwise 0isreturned.MTC Express3-8
Taxel Physical Configurationfloat MTC_GetTaxelX(MTCHandle hMTC, int taxelNum)This function returns the x-coordinate, in mm, of the taxel specified bytaxelNum. taxelNum is the index of the array filled byMTC_GetRawPressure or MTC_GetNormalizedPressure. The value oftaxelNum must be less than the value in the nTaxels field of theMTCConfig structure obtained using the MTC_GetConfig function.Parameters:hMTC - handle of the MTC.taxelNum - A specified taxel number.Return:This function returns the x-coordinate of the specified taxel in mm.float MTC_GetTaxelY(MTCHandle hMTC, int taxelNum)This function returns the y-coordinate, in mm, of the taxel specified bytaxelNum. taxelNum is the index of the array filled byMTC_GetRawPressure or MTC_GetNormalizedPressure. The value oftaxelNum must be less than the value in the nTaxels field of theMTCConfig structure obtained using the MTC_GetConfig function.Parameters:hMTC - handle of the MTC.taxelNum - A specified taxel number.Return:This function returns the y-coordinate of the specified taxel in mm.int MTC_GetTaxelCol (MTCHandle hMTC, int taxelNum)This function returns the column, between 1and nCols, of the taxelspecified by taxelNum. taxelNum is the index of the array filled byMTC_GetRawPressure or MTC_GetNormalizedPressure. The value oftaxelNum must be less than the value in the nTaxels field of theMTCConfig structure obtained using the MTC_GetConfig function.Parameters:hMTC - handle of the MTC.taxelNum - A specified taxel number.Return:This function returns the number of the column in which the specifiedtaxel is located.MTC Express3-9
int MTC_GetTaxelRow (MTCHandle hMTC, int taxelNum)This function returns the row, between 1and nRows, of the taxelspecified by taxelNum. taxelNum is the index of the array filled byMTC_GetRawPressure or MTC_GetNormalizedPressure. The value oftaxelNum must be less than the value in the nTaxels field of theMTCConfig structure obtained using the MTC_GetConfig function.Parameters:hMTC - handle of the MTC.taxelNum - A specified taxel number.Return:This function returns the number of the row in which the specified taxelis located.Pointer CalculationBOOL MTC_InitPointers(MTCHandle hMTC, int num_pointers,MTCPointer *pointer_data_array)This function initializes the pointer_data_array for the specified MTChandle. Parameters:hMTC - handle of the MTC.num_pointers - the total number of pointers you will ever want toresolve.pointer_data_array - pointer to a num_pointers element array oftype MTCPointer. The user is responsible for allocating the requiredmemory of size num_pointers*sizeof(MTCPointer).Return:MTC_InitPointers() returns a TRUE if successful. Otherwise a FALSEis returned.MTC Express3-10
int MTC_ResolvePointers(MTCHandle hMTC, int num_pointers,WORD *pressureData, int threshold, MTCPointer*pointer_data_array, long sampleNum)This function resolves pointer data from normalized pressure data. Thenumber of resolved pointers is limited to the num_pointers parameter.Athreshold parameter is used to limit the minimum pressure level atwhich pointers are resolved. This is used to adjust sensitivity.Parameters:hMTC - handle of the MTC.num_pointers - the total number of pointers you wish to resolve.pressureData - pointer to a memory location containing normalizedtaxel data.threshold - minimum pressure level at which pointers are resolved.pointer_data_array - pointer to an array of type MTCPointer withnum_pointers elements. This is where all resolved pointer data isstored.sampleNum - the sample number associated with the pressure data.Return:The number of pointers resolved is returned. Zero is returned if theMTC handle is invalid or if the pointer algorithm was unable to resolveany pointers.MTC Express3-11
Appendix A – Technical SpecificationsDimensions.......................................... (in, WxDxH)Package Outline ..........................7.50 x 6.69 x 0.38Electronics Bay ...........................7.06 x 2.25 x 0.50Active Tablet Area .......................5.75 x 3.75ConstructionEnclosure ..............................Milled AluminumActive Area............................PolycarbonateWeight ................................................(oz) 17.0Minimum Activation Pressure .............(psi) 0.4Maximum Indentation .........................(in) 0.08Noise and Vibration Emissions ..........NoneHorizontal pointing accuracy ..............(in) 0.05Operating Power Requirements .........120 VAC, 60Hz, 8 WSampling Rate ....................................(Hz) up to 200Pressure Resolution ...........................8 bitsInterface RS-232 Serial, .....................115 KBaudConnector ...........................................DB9 or Mac Serial AdadpterStorage Temperature ..........................(ºF) -40 to + 120Operating Temperature ......................(ºF) +35 to + 100Relative Humidity ................................(%) 0 to 95Note: This equipment has been tested and found to comply with the limits for aClass B digital device, pursuant to part 15 of the FCC Rules and ICES 03. Theselimits are designed to pro-vide reasonable protection against harmful interferencein a residential installation. This equipment generates, uses and can radiate radiofrequency energy and, if not in-stalled and used in accordance with theinstructions, may cause harmful interference to radio communications. However,there is no guarantee that interference will not occur in a particular installation. Ifthis equipment does cause harmful interference to radio or television reception,which can be determined by turning the equipment off and on, the user isencouraged to try to correct the interference by one or more of the followingmeasures:• Reorient or relocate the receiving antenna.• Increase the separation between the equipment and receiver.• Connect the equipment into an outlet on a circuit different from that towhich the receiver is connected.• Consult the dealer or an experienced radio/TV technician for help.Caution: Changes or modifications to this equipment, not expressly approved bythe manufacturer could void the user's authority to operate the equipment.MTC Expressi
Appendix B – Format of the Mapping FileThe mapping file has the following format:# Tactex Controls Inc.## Touch Tablet Mapping File$ 72 145 95 200 200## KEY:# row col x_coord y_coord##LED 1: 1 1 3.75 904 2 16.25 391 4 41.25 904 5 53.75 391 7 78.75 904 8 91.25 391 10 116.25 904 11 128.75 39##LED 2: 2 1 3.75 735 2 16.25 222 4 41.25 73...All of the lines beginning with #are comments – they have no effectwhen the mapping file is read by the API. One special line begins witha $character. There are five numbers in it:72 – this is the number of taxels in the pad145 – this is the width of the pad (x-dimension) in mm95 – this is the height of the pad (y-dimension) in mm200 – this is the default sample rate in samples-per-second (Hz)200 – this is the maximum compressed sample rate in HzThe lines following the header specify the locations of individual taxels.The order of the rows of data is important: the serial stream of data fromthe MTC Express is sent in the same order as the rows in the mappingfile. For each taxel, the following data is given:Row – the row numberColumn – the column numberx-coordinate – the location in mmy-coordinate – the location in mmPlease refer to section "Pad Configuration (Mapping)" for figuresdescribing the coordinate frames of reference.MTC Expressii
Appendix C – Format of the Normalization FileThe normalization file must have a specific format. The contents of thenormalization file look like this:# Tactex Controls Inc.# Copyright 1998# www.tactex.com tci@tactex.com## Touch Tablet Normalization File## Min Scale2 9.8365381 15.2686570 17.0499992 12.1785720 8.8189665 8.1190472 6.912162...All lines that begin with the #character are remarks and are ignored.Each row of the normalization file corresponds to an individual taxel.The ‘Min’ field indicates the taxel offset (minimum intensity with nopressure applied to pad). The ‘Scale’ field is the scaling factor used tonormalize the taxel responses. The normalized response is computedby the formula:NormalizedData = (RawData – Min) * ScaleMTC Expressiii
Appendix D – The Fine PrintMTC Express Product WarrantyTactex Controls Inc. ("Tactex") warrants to the original owner that the MTC Expresscontroller ("MTC Express") delivered in this package will be free from material defectsand workmanship for a period of one year following the date of manufacture or the dateof purchase as indicated on the returned warranty registration card, which ever is later.This warranty does not extend to damage to the MTC Express incurred duringshipping. Such shipping damage should be reported immediately to the claimsdepartment of the carrier that delivered the unit. In the event that the MTC Express failsto perform to specification due to a defect in materials or workmanship, customersmust contact Tactex to obtain a RMA (Returned Merchandise Authorization) numberand return the unit to Tactex Controls Inc. RMA numbers will only be issued to originalowners of items who have returned original warranty registration cards and will only beissued where the customer calls for a RMA number before the 1 year warranty termexpires. If the item is found to be defective Tactex will replace or repair the product atno charge except for as set forth below, provided that you deliver the item along withthe RMA number in the original container and pay the shipping charges. Tactex will notaccept the return of any product without an RMA number on the package. Tactexreserves the right to repair or replace the unit at their discretion. Tactex warrants therepaired or replaced unit for 90 days or the remainder of the one year warranty period,which ever is greater. No other warranty is given or implied as to the fitness for use orcompatibility for any particular purpose of the MTC Express with any given operatingsystem, software or hardware configuration. Tactex may not be held responsible fordamages, loss of profits, personal injury or property damage, expense orinconvenience or any other specific, incidental, speculative or consequential damagescaused by the use, mis-use or inability to use the MTC Express Controller and it'sbundled Software whether on account of material defect, negligence or otherwise. The warranty is void if the MTC Express is damaged due to mis-use, abuse, alteration,accident, electrical supply fluctuations or any other environmental occurrence. THEREARE NO USER SERVICEABLE PARTS INSIDE THE MTC EXPRESS UNIT. Openingthe MTC Express unit voids the warranty. This warranty is, and can only be, given byTactex to the original purchaser and may not be transferred. No warranty is given orimplied regarding any third party components or Software that may be bundled with theMTC Express Controller. Notwithstanding the foregoing, Tactex Controls Inc.'s totalliability for all claims under this warranty and the agreement of purchase and sale of anMTC Express shall not exceed the price paid for the MTC Express and shall not includeany other charges or expenses such as taxes, duties, shipping or insurance charges. Copyright and Patents The MTC Express user's guide and any accompanying Software and documentationthereto is subject to copyright 1999/2000 which is owned by Tactex and may not, inwhole or in part, be copied, scanned, photocopied or otherwise duplicated in any mediadigital or otherwise, without express written permission of Tactex. The ownership of allMTC Express Software is retained without exception by Tactex Controls Inc. and issubject to the MTC Express Software license agreement. This product is produced inCanada under license from the Canadian Space Agency US patent 5,917,180. Otherpatents pending.Trademarks "Smart Fabric", "Capturing Touch" and MTC Express are trademarks of TactexControls Inc.. Windows and Microsoft are registered trademarks of MicrosoftCorporation, MAX and MSP are trademarks of Opcode/IRCAM/Cycling74. All otherproducts mentioned may be trademarks of other companies and are used forillustrative purposes only without intent to infringe. MTC Expressiv
Y2K Tactex's MTC Express poses no Year 2000 issue. They are all Year 2000 Ready. Whileyour Tactex product is ready for the Year 2000, other parts of the computer systemwhich support your Tactex MTC Express, such as computer hardware, firmware,operating systems, and software applications, may not be Year 2000 ready. Users needto test their equipment and software, and contact the respective manufacturers ofthose products for more information. Tactex expressly disclaims any warranty of non-Tactex products used in conjunction with your MTC Express.WARNING ABOUT USE The MTC Express is intended for use as a computer input device for the purposes ofmusical entertainment and graphic arts only. Tactex products are not designed or builtwith components intended to ensure a level of reliability for applications where thesafety of individuals may be concerned. Do NOT use the MTC Express in clinical ormedical applications. Do NOT use the MTC Express to control moving vehicles, wheelchairs, industrial equipment, or machinery. Do NOT use the MTC Express to controlany equipment whereby the failure of the MTC Express or Software may cause injuryto a person or damage to property.MTC Express Software License Agreement Your MTC Express package has been delivered with application Software on a CD.Please read this Software license agreement ("license") carefully before installation.By installing the Software, you are agreeing to be bound by the terms of this license. 1. License: The Software accompanying this license, whether on disk, on compact disc,in read only memory, or any other media, and the related documentation (collectivelycalled, the "Tactex Software") are licensed, not sold, to you by Tactex Controls Inc.("Tactex"). The Tactex Software in this package and any copies, modifications anddistributions which this license authorizes you to make are subject to this license. 2. Permitted uses and restrictions The Tactex Software is licensed for use exclusivelywith the Tactex MTC Express. You do not have license to use all or part of the TactexSoftware in any application which does not require the user to own and operate aTactex MTC Express. Except as expressly permitted in this license, you may notdecompile, reverse engineer, disassemble, modify, rent, lease, loan, sublicense,distribute or create derivative works based upon the Tactex Software in whole or partor transmit the Tactex Software over a network or from one computer to another. Yourrights under this license will terminate automatically without notice from Tactex if youfail to comply with any term(s) of this license. In addition, Tactex reserves the right toterminate this license if a new version of the operating system is released which isincompatible with the Tactex Software.3. Disclaimer of warranty: Some of the Tactex Software may be designated as alpha,beta, development, pre-release, untested, or not fully tested versions of the TactexSoftware. Such Tactex Software may contain errors that could cause failures or lossof data, and may be incomplete or contain inaccuracies. You expressly acknowledgeand agree that use of the Tactex Software is at your sole risk. The Tactex Software isprovided "as is" and without warranty of any kind and Tactex and Tactex's licensor(s)(for the purposes of sections 3 and 4, Tactex and Tactex's licensor(s) shall becollectively referred to as "Tactex") expressly disclaim all warranties, express orimplied, including, but not limited to, the implied warranties of merchantability andfitness for a particular purpose. Tactex does not warrant that the functions containedin the Tactex Software will meet your requirements, or that the operation of the TactexSoftware will be uninterrupted or error-free, or that defects in the Tactex Software willbe corrected. Furthermore, Tactex does not warrant or make any representationsregarding the use or the results of the use of the Tactex Software or in terms of theircorrectness, accuracy, reliability, or otherwise. No oral or written information or adviceMTC Expressv
given by Tactex or a Tactex authorized representative shall create a warranty or in anyway increase the scope of this warranty. Should the Tactex Software prove defective,you (and not Tactex or a Tactex authorized representative) assume the entire cost ofall necessary servicing, repair or correction. The license fees for the Tactex Softwarereflect this allocation of risk. Some jurisdictions do not allow the exclusion of impliedwarranties, so the above exclusion may not apply to you. 4. Limitation of liability: Under no circumstances, shall Tactex be liable for anyincidental, special or consequential damages that result from the use or inability to usethe Tactex Software. In no event shall Tactex's total liability to you for all damages,losses, and causes of action (whether in contract, tort (including negligence) orotherwise) exceed the price paid for the MTC Express accompanying the TactexSoftware.5. Controlling law and severability: If there is a local subsidiary of Tactex in the countryin which the Tactex Software license was obtained, then the local law in which thesubsidiary sits shall govern this license. Otherwise, this license shall be governed bythe laws of Canada and the Province of British Columbia. If for any reason a court ofcompetent jurisdiction finds any provision, or portion thereof, to be unenforceable, theremainder of this license shall continue in full force and effect. 6. Complete agreement: This license constitutes the entire agreement between theparties with respect to the use of the Tactex Software and supersedes all prior orcontemporaneous understandings regarding such subject matter. No amendment to ormodification of this license will be binding unless in writing and signed by Tactex.MTC Expressvi

Navigation menu