Tactex Controls TCIMTCEXP100 Touchpad Input Device User Manual Multi Touch Manual

Tactex Controls Inc. Touchpad Input Device Multi Touch Manual

Contents

Users Manual part 2

Part 2 – MTC Express Developer’s GuideIntroductionWhat’s an API?Tactex provides an Application Program Interface (API) for developmentof custom applications and MAX external objects utilising the MTCExpress. This API is provided for both Windows 95/98 and Mac OS 8platforms. The MTC Express API consists of a set of software tools thata software developer can use to build applications which connect to theMTC Express and control the data stream from it.Who Should Read This?This Developer’s Guide is required reading if you want to do one of thefollowing:• create a MAX external object in C• create a software application that uses input from the MTCExpress• create a plug-in for an existing application that uses input fromthe MTC Express.Overview of the APIThe API consists of a set of C-language libraries to which the developerscan link to their custom code. The API provides features for accessing raw data from the individualpressure sensors, calibrated data, or resolved pointer locations andintensities. The API initiates a serial communication link with the MTC Express. Itdecodes the serial data stream, and determines the x-y coordinates ofeach data element by means of configuration information held in a"mapping" file. The API also provides an automatic means of calibrating,or "normalizing" the data. The API handles the serial connection to thetouch-pad, as well as the disk file I/O required for calibration andconfiguration. Several C-source files (for both Windows 95/98 and MacOS 8) are included which demonstrate the use of the API withinapplications.MTC Express2-1
RequirementsIn order to use the API, you must:• know how to use the C programming language• know how to program for Win32 applications or Mac OSapplications• have a computer with one of the following developmentsystems: - Macintosh Metrowerks CodeWarrior release 5- Windows 9x Metrowerks CodeWarrior release 3- Microsoft Visual C++ version 5Which Files Do I Need?The MTC Express API is a collection of functions that have beencompiled into a C-language library. Although the functional interface isidentical (with a few small exceptions) between Macintosh OSapplications, Win32 applications, and Macintosh MAX applications,different libraries and header files are required for each. Macintosh applications:mtc_ppc.libmtc.hmtc_mac.hMAX external objects:mtc_max.libmtc.hmtc_max.hWin32 applications:mtcwin32.libmtc.hmtc_win32.hMTC Express2-2
BasicsThis section provides the basic information you will need to use the API.Some examples which describe the use of the API are shown. Moredetailed descriptions of the functions can be found in the API Referencesection.Gathering data from the MTC ExpressApplications accessing MTC Express first need to establish a connectionto the MTC Express through the API. Before exiting your application, theconnection to the MTC Express must be released. The figure belowillustrates the typical functional flow when gathering MTC Express data.The following sections provide the instructions how to implement theflow chart.MTC Express2-3
Establishing a Connection to the MTC ExpressInitiating a connection to the MTC Express is straightforward. You needto know the following things:• The name and location of the mapping file (more on thatlater).• The name and location of the normalization file (more on thatlater, too).• The name of the serial port to which the MTC Express isconnected.The following snippet of code demonstrates a function that establishesa connection to an MTC Express on serial port A of a Macintosh.#include "mtc_mac.h"#include "mtc.h"static MTCHandle myMTC;static MTCCompType myUseCompression = MTCCompNone;const int kWaitTime = 500;BOOL connect_to_mtc(void){MTCCreate myMtcCreate;// myMtcCreate specifies the serial port // and file paths&names:// Mac OS serial input drivermyMtcCreate.inputPort = (char *)"\p.AIn"; // Mac OS serial output drivermyMtcCreate.outputPort = (char *)"\p.AOut";// path and filenamesmyMtcCreate.mappingFile = "mapping.txt";myMtcCreate.normalFile = "normal.txt";myMTC = MTC_New(myMtcCreate);if (!myMTC) return(FALSE);// Start the data streamMTC_StartSendingData(myMTC, myUseCompression, kWaitTime);return(TRUE);}MTC Express2-4
The function MTC_New takes as its only parameter an MTCcreatestructure. Filling the MTCCreate structure is the key to successfullyconnecting to the MTC Express. That structure has four fields:inputPort and outputPort –The MTC Express API is a software layer that lies in-between theoperating system serial driver and your application. When you callMTC_New, the API takes the names of the serial driver that youspecify in the MTCCreate structure and passes them through to theoperating system. On the Macintosh, serial connections have names such as"Modem" for the benefit of the user, as well as two driver names foreach serial port, such as ".AIn" and ".AOut". The API requiresyou to use the driver names. Furthermore, since the MacintoshDevice Manager expects these to be pascal strings (i.e. unsignedchar arrays with the first character being the string length) ratherthan null-terminated strings, you must provide pascal strings.MetroWerks CodeWarrior allows you to use the escape code ’\p’as the first character to cause the compiler to generate a pascalstring. Hence the two lines of code above which declare pascalstrings, "\p.AIn", and cast them as character arrays for thepurposes of assigning the fields of the MTCCreate structure. Tomake your job somewhat easier, the Macintosh OS provides a setof tools in the Communication Toolbox for determining which serialdrivers are installed in your system, and what their serial drivernames are.On Win32 systems, the situation is much easier. There is only onedriver name for both input and output. The serial port names aretypically "com1" , "com2" , etc. The Win32 OS expects a null-terminated string, so the simple assignment such as myMtcCreate.inputPort = myMtcCreate.outputPort = "com1";is all that is required.mappingFile– This is a pointer to a null-terminated string specifying the path andfilename of the mapping file (described subsequently). A validmapping file must be present in the specified location or MTC_Newwill fail to complete a connection and it will return NULL.normalFile – This is a pointer to a null-terminated string specifying the path andfilename of the normalization file (also described subsequently). Ifa normalization file with the specified name does not exist, then theAPI will create one with default calibration parameters.MTC Express2-5
The MTC_New function returns a "handle to the MTC", myMTC. Nearlyevery other function in the API takes that handle as its first parameter.That’s why myMTC is declared as a global variable in the code above – ifyou lose its value, subsequent calls to the API functions will fail. Notethat for cross-platform compatibility, the API uses the type definition BOOLand the defined values TRUE and FALSE. These are defined inmtc_mac.h, mtc_max.h, and mtc_win32.h.The function MTC_StartSendingData is called to start the stream of datafrom the MTC Express to the computer. (Without this call, the MTCExpress would sit there idly.) You provide three parameters:myMtc – this is the handle to the MTC which you were just given.myUseCompression – this specifies which method of data compression to use for theserial communication. For most purposes, you can simply use thevalue MTCCompNone, as shown. kWaitTime – several of the API functions send a message to the MTC Expressover the serial port and expect a particular response. In thisexample, MTC_StartSendingData sends a message to initiate thedata streaming. You can specify to the API how long it should waituntil the it receives the anticipated response – here we will wait upto 500 milliseconds. MTC_StartSendingData will not return until thefirst packet of data has been received from the MTC Express orkWaitTime has elapsed. MTC_StartSendingData will return TRUE ifthe data stream was initiated successfully, or FALSE if the API failedto receive data from the MTC within the specified time. Getting the Touch-Pad Configuration DataAs you will see in subsequent sections, the API sends your applicationtaxel data by filling a WORD array (WORD is a 16-bit unsigned integer, whichhas been defined in mtc_mac.h, mtc_max.h and mtc_win32.h). It is yourresponsibility to allocate the memory required for that array. How muchmemory should you allocate? Well, you probably already know that theMTC Express has 72 taxels, so you could simply declare an array likethis:WORD myTaxelPressures[72];MTC Express2-6
But that is not the recommended way. At present, the MTC Express isthe only product which uses this API, but Tactex is sure to introducemore products in future. Those future products may have a differentnumber of taxels and a different physical configuration. (Most of thoseproperties are defined in the mapping file, which we will discuss later.) Ifyou want your application to remain compatible with future products,then you can’t make assumptions about the number of taxels, theindividual taxel locations, or the size and shape of the touch pad. TheAPI provides means of obtaining this information. The following snippetof code shows how to determine the number of taxels and then allocatesan appropriate amount of memory for the taxel data.WORD *allocate_mtc_data_mem(void){MTCConfig myConfig;// Get the number of taxels in// the MTC Express unit.MTC_GetConfig(myMTC, &myConfig);// Allocate the memory needed for data storage.return(malloc(myConfig.nTaxels * sizeof(WORD)));}The function above calls the API function MTC_GetConfig to fill theMTCConfig structure. The MTCConfig structure holds information relatedto the size of the pad and the general arrangement of taxels, amongother things. In this example, we want to know how many taxels the padhas, and that value is held in the nTaxels field. Getting Data from the MTC ExpressOnce a connection to the MTC Express has been established, you canaccess the data steam. The data is available in two flavours: (1) "raw"data is delivered just as the MTC Express spits it out, or (2) "normalized"data has been calibrated to provide similar outputs for similar pressureapplied to each taxel. Raw data directly from the MTC Express can beaccessed by using the MTC_GetRawData function. Normalized data fromthe MTC Express can be accessed by using theMTC_GetNormalizedData function. The following exampledemonstrates a function which fills an array with normalized data.MTC Express2-7
long gather_mtc_data(WORD *pPress){long sampleNum;// Loop here until we get some data.do{// Request normalized data.sampleNum = MTC_GetNormalizedData(myMTC, pPress);// We could have used the following // to request raw data:// sampleNum = MTC_GetRawData(// myMTC, pPress);} while (sampleNum == 0);// Record sample number for timing.return (sampleNum);}After a call to the example gather_mtc_data function, the WORD arraypointed to by pPress will be filled with data. Three things are importantto know about that data:- The data is in the range of 0to MTC_FullScale. MTC_FullScaleis defined to be 1023 in the mtc.h. - The order of the data is the order in which data is streamed fromthe MTC Express. You cannot make any assumptions about howthe geometric configuration of the taxels relates to the order of thedata. The API provides several means to associate the data withthe physical locations of the taxels; these are described in thesection entitled "Pad Configuration (Mapping)".- Only the latest data is reported. If several samples have beenreceived in-between calls to MTC_Get…Data, all but the latest dataare thrown away.The functions MTC_GetNormalizedData and MTC_GetRawData bothreturn immediately (i.e. they do not wait for new data to arrive). They willfill pPress with the latest data that has been received, provided it has notbeen accessed by a previous call to MTC_GetNormalizedData orMTC_GetRawData. In other words, the API will report any given data onlyonce. The MTC_Get…Data functions return the sample number of thatdata. If no data has arrived since the last call to an MTC_Get…Datafunction, then they will return 0.MTC Express2-8
Processing the Pressure DataAs mentioned previously, the pressure data is reported as a WORD array.Both raw and normalized data are in the range of 0to MTC_FullScale.And, as also previously mentioned, it is your responsibility to allocatememory for the data. After the API has delivered the data, you are freeto use it as you will. In most cases, it will be necessary to relate the datato a physical location on the pad. Correlating data to the physicallocation is such an important topic that it has its own section in this guide– please refer to "Pad Configuration (Mapping)".Closing a connection to the MTC ExpressBefore your application exits, it must disconnect from the MTC Expressusing the MTC_Delete function. This allows the API to close the serialport and free system resources. The following code segmentdemonstrates a proper MTC Express shut-down and freeing the localdata memory.void disconnect_from_mtc(WORD *pPress){// Stop data stream & close the connectionMTC_Delete(myMTC);// Render MTC handle invalidmyMTC = (MTCHandle)0;// Free pointer to data storagefree(pPress);pPress = NULL;}A Complete ExampleThe foregoing has provided enough information for you to create asimple application. An example application is given on the CD in thefollowing location:For Macintosh – MTC Express:Projects:Mac:Example1-basic:For Windows – E:\Projects\Win32\MSVC Example1 Basic\Pad Configuration (Mapping)The Mapping FileYour MTC Express contains an embedded array of 72 pressure sensingelements called taxels. Information regarding the physical configurationof the pad is stored in a disk file called the mapping file. The mappingfile defines the number of taxels, the xy-coordinates of individual taxelsin millimetres, and the row/column locations of the taxels, among otherthings.MTC Express2-9
For the purposes of the demonstration application provided with yourMTC Express, the mapping file is named mapping.txt, and it is locatedin the same folder as the application. However, the name of themapping file and its location are specified by the developer (that is, you).You specify the name and location when you call the MTC_Createfunction, as shown previously.The API requires a specific format of the mapping file. In order to usethe API, you will probably never need to know what the format of themapping file is (or even to look at the mapping file, for that matter).However, for curious developers, the mapping file format is described inAppendix B.Where are the taxels?If your application works with the taxel data stream (as opposed to thepointer information), you will almost certainly need to know the physicallocation of the taxel to which any given data applies. The API providestwo means to do this.The first way to determine the location of a taxel is to access the xy-coordinate information. The figure below shows the Cartesiancoordinate frame used to specify the xy-coordinate information. As youcan see, the left side of the pad corresponds to x=0, the bottom of thepad corresponds to y=0, and the origin of the coordinate frame (i.e. thelocation x=0, y=0) is at a point slightly off the lower left corner of the pad.MTC Express2-10
The API function that you can use to determine the size of the pad is:MTC_GetConfig()The API functions you can use to access the xy-coordinates of the taxelsare:MTC_GetTaxelX()MTC_GetTaxelY()The second way to determine the location of a taxel is to access the row-column coordinates. Although the row-column coordinates are similar tothe xy-coordinates in some ways, using them may be simpler in someinstances. The figure below illustrates the row-column coordinate frame.Notice that unlike the Cartesian coordinate system, the row-columncoordinates start at (1,1) in the top left corner (this corresponds to thetypical way arrays and matrices are indexed).The API function that you can use to determine the size of the pad is:MTC_GetConfig()The API functions that you can use to access the row-columncoordinates (i.e. indices) of the taxels are:MTC_GetTaxelCol()MTC_GetTaxelRow()MTC Express2-11
Calibration (Normalization)The nature of the MTC Express Smart Fabric surface is such that theresponse of an individual taxel to a given applied pressure may not beidentical to the response of another taxel under the same pressure.Therefore, the API provides a means to calibrate, or normalize, the pad. The normalization procedure should be performed when you first receivethe MTC Express and when you want to adjust the sensitivity level.Refer to the Part 1: Owner’s Guide for additional information about theprocedure. Normalization only needs to be performed occasionallybecause the results can be saved in a normalization file. For thepurposes of the demonstration programs provided with your MTCExpress, the normalization file is named normal.txt, and it is located inthe same folder as the application program. You specify the name andlocation when you call the MTC_Create function, as shown previously.Normalizing the MTC ExpressYour application can support the process of normalization, if desired.The normalization procedure requires you to gather data from the MTCExpress while the user applies uniform pressure over the pad, asdescribed in Part 1: Owner’s Guide. This is illustrated in the followingfunctional flow diagram.MTC Express2-12
The following code example demonstrates the normalization procedurewhen using the API.#include "mtc_mac.h"#include "mtc.h"BOOL normalize_my_mtc(){MTCHandle myMTC;MTCCreate myCreate;MTCConfig myMTCConfig;long sampleNum;BOOL allDone;WORD *pPress;// Establish a connectionmyCreate.inputPort = (char *)"\p.AIn";myCreate.outputPort = (char *)"\p.AOut";myCreate.mappingFile = "mapping.txt";myCreate.normalFile = "normal.txt";myMTC = MTC_New(myCreate);if (!myMTC) return FALSE;// Find the number of taxels in the // MTC Express and allocate the memory // needed for data storage.MTC_GetConfig(myMTC, &myMTCConfig);pPress = malloc(myMTCConfig.nTaxels * sizeof(WORD));if(!pPress){// Report memory allocation errorMTC_Delete(myMTC)return(FALSE);}// Start the data streamMTC_StartSendingData(myMTC, MTCCompNone, 500);// Configure the API to begin the // normalization procedureMTC_BeginNormalization(myMTC);// Loop here until the user indicates he’s // completed the normalization proceduredo {MTC Express2-13
// gather datasampleNum = MTC_GetNormalizedData(myMTC, pPress);// placeholder for your function// to wait for user’s signalallDone = isNormalizationDone();// use the data here, if desired.}while (!allDone);// Stop the normalization procedureMTC_EndNormalization(myMTC, TRUE);// Disconnect from the MTC ExpressMTC_Delete(myMTC);// Render MTC handle invalidmyMTC = (MTCHandle)0;// Free the taxel data storage memoryfree(pPress);pPress = NULL;return(TRUE);}This example is very similar to previous examples. MTC_New is called toestablish a connection, MTC_Config is called to determine how manytaxels there are, and MTC_StartSendingData is called to initiate thedata stream. Then, MTC_BeginNormalization is called to start thenormalization process. The only parameter passed toMTC_BeginNormalization is the handle to the MTC. Following the foregoing set-up, the program enters a loop which gathersdata. It is essential that this loop is carried out – data gathering isnecessary for the normalization to work, and API does not automaticallycall for data. That’s just the way it is. At any rate, if your applicationallows the user to normalize the MTC Express, it will most likely benecessary to display the data to the user. On every call toMTC_GetNormalizedData made in this loop, the API updates thecalibration parameters.At some point, the user will decide that the normalization process iscomplete, and will strike a key or make a menu choice. In the exampleabove, the call to isNormlalizationDone is a placeholder for yourapplication to insert the appropriate way to check if the user hasindicated that normalization is complete. After exiting the loop,MTC Express2-14
MTC_EndNormalization is called. That function signals to the API tofreeze the calibration parameters. The second parameter toMTC_EndNormalization is a BOOL which directs the API to whether ornot to overwrite the existing normalization file.MTC Express2-15

Navigation menu