********************************************************************************************
*                            DMC-Touch-Panel Driver
*
*                            TSC-10/LD Version1.1.2
*
*                            Rev.A    January 7, 2006
*
********************************************************************************************

*DMC Co., Ltd does not provide technical support, a maintenance, etc to this driver software 
 and this document.
 DMC will not be liable for any damage and loss caused by the use of this software. DMC will
 not be liable for any type of compensation.
 This software is subject to change without notice.

********************************************************************************************
1.OUTLINE
********************************************************************************************
	The TSC-10/LD mouse emulation software lets you use our touch screen controller,
	the TSC-10/IC and TSC-20/IC just as though you were using a mouse by operating 
	the touch screen.
	Mouse operation is emulated as a xinput driver of XWindow system.
	This book is an instructions manual of setting programs, such as a driver and
	a calibration, etc.

	By XF86Config setting, operation by either USB or RS-232C communication is possible.

	EUSB
		+----------------------------------------------+
		|     @@@@       XWindow                   |
		+-------------------------------------+        |
		|     XINPUT driver  dmc_drv.o        |        |
		+-------------------------------------+--------+
		|                       OS                     |
		+-------------------------------------+        |
		|     usb driver      usbdmc.o        |  <--In Kernel2.6, it is usbdmc.ko
		+-------------------------------------+--------+
		|                       HW                     |
		+----------------------------------------------+
	
	ERS-232C
		+----------------------------------------------+
		|     @@@@       XWindow                   |
		+-------------------------------------+        |
		|     XINPUT driver  dmc_drv.o        |        |
		+-------------------------------------+--------+
		|                       OS                     |
		+-------------------------------------+        |
		|          RS-232C driver             |        |
		+-------------------------------------+--------+
		|                       HW                     |
		+----------------------------------------------+
	
		*RS-232C driver can communicate by the tty driver of OS attachment.

********************************************************************************************
2.SPEC
********************************************************************************************
	Correspondence
		USB (USB Specification 1.1 Low Speed)
		Asynchronous Serial (RS-232C)

	Setting program
		(1)Calibration
			2/3/4/5/9 points
		(2)Coordinate output rate (point/sec)
			30 p/s
			50 p/s
			80 p/s
			100 p/s
			130 p/s
			150 p/s
		(3)Beep sound
			Touch down beep ON/OFF
			Touch up beep ON/OFF

	XINPUT Driver
		(1)By the xinput specification driver of a XWindow system, touch input
		   is outputted as mouse input. Of course, the concurrent use with 
		   a mouse is possible.
		(2)A calibration data is saved in following order.
			EEPROM on a controller
			"dmc_calib.dat" file
		     *Error data are disregarded.
		(3)The "dmc_calib.dat" file can be specified with a directory in XF86Config.
		(4)When a driver (XWindow) starts up, calibration data are read
		   in following order.
			"dmc_calib.dat" file
			EEPROM on a controller
		     *It is used giving priority to the data in EEPROM.
	USB Driver
		(1)The USB driver is used from a XINPUT driver.
			You have to load the USB driver, before starting XWindow.
		(2)Since the USB driver is a kernel driver, it is dependent on a kernel 
		   version.
			Therefore, it is necessary to recompile the USB driver in usage's 
			environment.

********************************************************************************************
3.Development / Checking of operations environment
********************************************************************************************
	Development environment
		CPU		AthlonXP
		Distribution	Vine2.6r4
		Kernel		Kernel-2.4.22-0vl2.10-i686
	Checking environment
		CPU		x86 architecture
				  Pentium 4
				  AthlonXP
	                	  ViaC3
		--------+------------------------------
			| kernel	XWindow
		--------+------------------------------
		Vine2.6 | 2.4.22	4.2.0
		Vine3.1 | 2.4.27	6.7.0
		Redhat8	| 2.4.18-14	4.2.0
		Redhat9 | 2.4.20-8	4.3.0
		Fedora3	| 2.6.9		6.8.1
		Fedora4	| 2.6.11	6.8.2
		---------------------------------------
		*Re-conpile is required for a USB driver.
		*When compiling a XINPUT driver on Redhat 8, it is necessary to remove
		 the following comment.
			MODULE_GCC_FLAGS=#-fno-merge-constants

********************************************************************************************
4.Exposition of file
********************************************************************************************
	Please expand tpxxxxxx.tgz by the arbitrary directories on Linux.
	The contents are as follows.

	   [TSC10LD_Vxxx] 		<---'xxx' is a version number
	     |
	     +-- XF86Config             XF86Config sample
	     +-- dmc_calib.dat          Initial data sample of a calibration
	     +-- objinstall             The batch file for object installation
	     +-- [driver]               --- Driver directory ---
	     |      |
	     |      +-- makefile
	     |      +-- xf86DMC.h       Driver header
	     |      +-- xf86DMC.c       Driver source
	     |      +-- dmc_drv.o       Driver
	     |
	     +-- [usb]			--- USB driver directory (kernel 2.4) ---
	     |	    |
	     |	    +-- makefile
	     |      +-- <usbdmc.h>      Driver header:usb26/usbdmc.h is used.
	     |      +-- <usbdmc.c>      Driver source:usb26/usbdmc.c is used.
	     |      +-- usbdmc.o        Driver
	     |
	     +-- [usb26]		--- USB driver directory (kernel 2.6) ---
	     |	    |
	     |	    +-- makefile
	     |      +-- usbdmc.h        Driver header
	     |      +-- usbdmc.c        Driver source
	     |      +-- usbdmc.o        Driver
	     |
	     +-- [tbctl]                --- Setting program directory ---
	            |
	            +-- makefile
	            +-- tb.h            header
	            +-- tbctl.c         Main program source
	            +-- tbcalib.c       Calibration program source
	            +-- tbtest.c        Touch input trace test program source
	            +-- tbselector.c    Button selector program source
	            +-- ulib.c          Library for XWindow
	            +-- xilib.c         xinput interface library
	            +-- tbctl           Main execution object
	            +-- tbcalib         Calibration execution object
	            +-- tbtest          Touch input trace test execution object
	            +-- tbselector      Button selector execution object

********************************************************************************************
5.Execution
********************************************************************************************
	It is also possible to use an object as it is without compiling,if it is 
	the same environment as the above development environment.
	It will operate, if the version and CPU of XWindow are the same.
	Please refer to a remarks 2, when compile is required.

	*Operate by root user.

	(1)In USB operation, USB device is created and it loads USB driver.
		kernel2.4
			$ cd /dev/usb
			$ mknod dmc0 c 180 181             ...create device
			$ cd <install-TSC10LD_Vxxx>/usb
			$ insmod usbdmc.o                  ...load
	  	kernel2.6 (It is not necessary to create the device)
			$ cd <install-TSC10LD_Vxxx>/usb26
			$ insmod usbdmc.ko                 ...load

	(2)Please copy the object in the uncompressed file to a predetermined directory.
	   A batch file named "objinstall" is prepared.

			object            	directory
			----------------------------------------------------------
			dmc_drv.o               /usr/X111R6/lib/modules/input
			tbctl                   /usr/X11R6/bin
			tbcalib                 /usr/X11R6/bin
			tbtest                  /usr/X11R6/bin
			tbselector              /usr/X11R6/bin

		*If tbctl, tbcalib, tbtest, and tbselector are directory which specify 
		 the execution pass, they do not need to be /usr/X11R6/bin.

	(3)Please refer to XF86Config and correct /etc/X11/XF86Config.

	   *It will correct /etc/X11/XF86Config-4 if it is Vine2.6.
	    That is, please correct XF86Config which XWindow uses.

	  Registration as a pointer device.
	   		Section "ServerLayout"
			   Identifier     "Anaconda Configured"
			   Screen         0  "Screen0" 0 0
			   InputDevice    "Mouse0" "CorePointer"
			   InputDevice    "Mouse1" "SendCoreEvents"    <--- Addition
			   InputDevice    "Keyboard0" "CoreKeyboard"
			EndSection

	   USB=Device is added.
		kernel2.4
		  Section "InputDevice"
		    Identifier  "Touch"
		    Driver      "dmc"
		    Option      "USB"  "1"
		    Option      "Device"  "/dev/usb/dmc0" ...The device name created by (1)
		    Option      "SaveFile" "/etc/X11/dmc_calib.dat"
		  EndSection
		kernel2.6
		  Section "InputDevice"
		    Identifier  "Touch"
		    Driver      "dmc"
		    Option      "USB"  "1"
		    Option      "Device"  "/dev/dmc0"    ...The device name created by (1)			    Option      "SaveFile" "/etc/X11/dmc_calib.dat"
		  EndSection
			
	    RS-232C=Device is added
		  Section "InputDevice"
		    Identifier  "Touch"
		    Driver      "dmc"
		    Option      "Device"  "/dev/ttyS0"   ...Connection serial port
		    Option      "SaveFile" "/etc/X11/dmc_calib.dat"
		  EndSection

	(4)Please copy dmc_calib.dat in the uncompressed file to /etc/X11.
	   And, correct if needed.
	   Please refer to a remarks 1 for details.

			# ---------------------------------
			# DMC-Touch-Panel setup
			# ---------------------------------
			PenDownBeep  1
			PenUpBeep    1
			SamplingRate 0
			# ---------------------------------
			# raw data
			# ---------------------------------
			RawX0   56
			RawY0   65
			RawX1   919
			RawY1   929
			# ---------------------------------
			# calibration data
			# ---------------------------------
			CalX0   25
			CalY0   25
			CalX1   999
			CalY1   743

	(5)If XWindow is restarted, a driver will operate.
	   *When a touch screen does not operate, the power source of a touch screen
	    controller is re-switched on and please restart a system.

	(6)If touch input is possible, in "$tbctl", please start a setting program and
	   perform the calibration of a touch screen.

********************************************************************************************
6.Setting program
********************************************************************************************
	6-1.tbctl
		Executing of "tbctl" displays the following main windows.
		Each button is clicked and each function is performed.

	             +----------------------------------------------------+
	             | TSC-10/LD Control Main                             |
	             +----------------------------------------------------+
	             |                                         Ver1.x.x   |
	             | < Sampling Rate >        < Sound >                 | 
	             |      30 p/s          Touch Down Beep on        |
	             |      50 p/s          Touch Up Beep on          |
	             |      80 p/s                                      |
	             |     100 p/s                                      |
	             |     130 p/s                                      |
	             |     150 p/s                                      |
		     | +---------------------+ +------------------------+ |
		     | |        Apply        | |       Test...        	| |
		     | +---------------------+ +------------------------+ |
		     | +---------------------+				  |
		     | |    Run Selector     |				  |
		     | +---------------------+				  |
		     |							  |
		     | < Calibration Points > < Calibration Time Out >    |
	             |     2 point             10 sec                 |
	             |     3 point             20 sec                 |
	             |     4 point             60 sec                 |
	             |     5 point					  |
		     |	   9 point					  |
	             | +------------------------------------------------+ |
	             | |               Calibration...                   | |
	             | +------------------------------------------------+ |
		     +----------------------------------------------------+

		< Sampling Rate >
		Coordinate output rate. (point/sec)

		< Sound >
		Enable or disable the Sound option that accompanies simulated touch screen
		presses.

		< Apply >
		Applies all changes.

		< Test >
		Invokes the pointing device test utility. (tbtest)

		< Run Selector >
		Invokes button selector utility. (tbselector)

		< Calibration Points >
		Specifies the number of calibration points to be used. (Now "2 points" only)

		< Calibration Time Out >
		Indicates the calibration timeout value if the calibration point is not
		touched within the specified period. Defined in seconds.

		< Calibration >
		Invokes the calibration procedure. (tbcalib)

	6-2.tbcalib
		Once invoked the calibration screen is displayed requesting that
		each calibration point be selected in turn.

         +----------------------------------------------------------------------+
         | {                                                                   |
         |                                                                      |
         |                                                                      |
         |           Executing Calibration. Please touch mark!!                 |
         |           TIME-OUT = 10 sec                                          |
         |                                                                      |
         |                                                                      |
         |                                                                      |
         |                                                                      |
         |                                                                      |
         |                                                                      |
         |                                                                      |
         |                                                                      |
         |                                                                      |
         |                                                                      |
         +----------------------------------------------------------------------+


		The dialog of calibration completion.
			+-----------------------------+
	       	        | TSC-10/LD-Clibration Result |
			+-----------------------------+
			|   Saved Calibration Data!!  |
			|    +-------+   +------+     |
			|    |  OK   |   |Cancel|     |
			|    +-------+   +------+     |
			+-----------------------------+

		Selection of the OK button saves calibration data to EEPROM
		and dmc_calib.dat file.
		Failure to select the OK button within a certain time will result in the new 
		calibration data being discarded.

		The dialog of calibration timeout.
			+-----------------------------+
	        	| TSC-10/LD-Clibration Result |
			+-----------------------------+
			|                             |
			|   Calibration Time Out!!    |
			|                             |
			+-----------------------------+

		When the calibration point is not touched within the specified period,
		the calibration data are not saved.

	6-3.tbselector
		The button mode of touch input can be changed.
		If tbselector is executed, the "SELECTOR" window will open.
			+------------+
	        	| SELECTOR |X|
			+---+---+----+
			| L | M | R  |
			+---+---+----+

		The L/M/R button is equivalent to the Left/Middle/Right button of a mouse.
		By default, the SELECTOR automatically switches back to the Left button
		after a single Middle or Right button action has been performed.

		*A display position and window size can be changed with the parameter
		 when executing tbselector.
		     tbselector <x> <y> <size-x> <size-y>
			parameter: <x>      x-coordinate of window display starting point.
				   <y>      y-coordinate of window displya starting point.
				   <size-x> Window size of the horizontal direction.
				   <size-y> Window size of the vertical direction.
		(Example)When a screen is 1280x1024, the window is displayed on the lower
			 right as a window size of 100x100.
				$ tbselector 1180 924 100 100
				$

********************************************************************************************
Remarks 1.  Calibration data file
********************************************************************************************
	The initial value of calibration data is specified. This file is read at the time of
	driver (XWindow) starting. 

	*The dirver always gives priority to the EEPROM data.

	Format
		<id-string>  <num>
		Between <id-string> and <num>, one or more spaces are required.

		<id-string>
			PenDownBeep
				Enables or Disables the sound of Pen Down Beep.
					0=Disable
					1=Enable
			PenUpBeep
				Enables or Disables the sound of Pen Up Beep.
					0=Disable
					1=Enable
			SamplingRate
				The sampling rate of coordinates is chosen.
					0=30 p/s
					1=50 p/s
					2=80 p/s
					3=100 p/s
					4=130 p/s
					5=150 p/s
			RawXn/Yn
				Coordinate for each calibration X/Y-axis calibration point
				where 'n' is within the range 0-8 for each configured
				calibration point.
			CalXn/Yn
				Calibration reference points, define the placement of the
				points using a coodinate based at top left.

	(Example) *"#" of the sentence recognizes the line as a comment.
		# ---------------------------------
		# DMC-Touch-Panel setup
		# ---------------------------------
		PenDownBeep  1
		PenUpBeep    1
		SamplingRate 0
		# ---------------------------------
		# raw data
		# ---------------------------------
		RawX0   56
		RawY0   65
		RawX1   919
		RawY1   929
		# ---------------------------------
		# calibration data
		# ---------------------------------
		CalX0   25
		CalY0   25
		CalX1   999
		CalY1   743

********************************************************************************************
Remarks 2.  Method of compile and execute of XINPUT driver
********************************************************************************************
	It compiles in the environment which can compile the application of XWindow.
	Please copy directory "tp" to arbitrary location.

	Setting program
		(1)It moves to copied tp/tbctl and compiles.
			$ make
		(2)tbctl, tbcalib and tbtest are copied.
			$ cp -pf tbctl tbcalib tbtest /usr/X11R6/bin
		(3)tbctl is executed.
			$ tbctl

	driver
		(1)The header file included in the XWindow source is required.
			http://xfree.org/
		   Please download the corresponding source of a version.
		(2)Please expand the downloaded XWindow source to /usr/X11R6/.
		(3)It moves to copied tp/driver and compiles.
			$ make		
		(4)dmc_drv.o is copied.
			$ cp -pf dmc_drv.o /usr/X11R6/lib/modules/input
		(5)Copied dmc_drv.o will be executed if XWindow is restarted.

		*To /usr/X11R6/xc/programs/Xserver/hw/xfree86/input/dmc
		 of the expanded XWindow source, you may copy and compile xf86DMC.c
		 and xf86DMC.h.
		*You have to load the USB driver, before starting XWindow.
		*In Redhat8, when compiling xinput driver, unless it removes of 
		 the following comments in driver/Makefile and carries out "make",
		 it does not operate normally.
				MODULE_GCC_FLAGS=#-fno-merge-constants
						 |---This is removed.

********************************************************************************************
Remarks 3.  Method of compile and execute of USB driver
********************************************************************************************
kernel2.4
	(1)Please install the kernel source. However, compile of the kernel is unnecessary.
	(2)It moves to TSC10LD_Vxxx/usb.
	(3)"makefile" is edited. Please set the pass of the INCLUDE source in makefile by
	   linux currently used.
			F
			TARGET=usbdmc.o usbtest
			
			#LINUX=linux-2.4
			LINUX=linux@@@@@@@<------Usually, this point is edited.
			
			INCLUDE= /usr/src/$(LINUX)/include
			#KCFLAGS= -D__KERNEL__ -I$(INCLUDE) -Wall -Wstrict-prototypes -O2 \
			#         -fomit-frame-pointer -pipe -DMODULE
			KCFLAGS=	-D__KERNEL__ \
						-I$(INCLUDE) \
			F
	(4)It compiles.
		$ make clean all
	(5)If compile finishes correctly, it will be used loading.
		$ insmod usbdmc.o

		*You have to load the USB driver, before starting XWindow.

kernel2.6
	(1)Please install the kernel source.
	(2)It moves to TSC10LD_Vxxx/usb26.
	(3)"makefile" is edited. Please set the pass of the INCLUDE source in makefile by
	   linux currently used.
			F
			TARGET:=usbdmc.ko
			
			KDIR=/usr/src/redhat/BUILD/kernel-2.6.9/linux-2.6.9  <------Usually,
								       this point is edited.
			KCFLAGS+=-DKER25=1
			F
	(4)It compiles.
		$ make clean all
		*When an error occurs in compile, it may be necessary to compile the kernel
		 itself once.
	(5)If compile finishes correctly, it will be used loading.
		$ insmod usbdmc.ko
		*You have to load the USB driver, before starting XWindow.

********************************************************************************************
Remarks 4.  Uninstallation
********************************************************************************************
	Uninstallation executes the contrary of copy work in chapter 5.

		File			Directory
		----------------------------------------------------------
		dmc_drv.o               /usr/X111R6/lib/modules/input
		tbctl                   /usr/X11R6/bin
		tbcalib                 /usr/X11R6/bin
		tbtest                  /usr/X11R6/bin
		tbselector              /usr/X11R6/bin
		dmc_calib.dat           /etc/X11

		*This directory is in the condition where objinstall was used.
		 When you copied manually, please delete the file of that location.

********************************************************************************************
Remarks 5.  Connection test
********************************************************************************************
	It is the example of a connection test with touch screen controller.
	When making it operate from console or XWindow, without operating XWindow,
	it performs in the situation that there is no touch setting by XF86Config setting.

	*Operate by root user.

	(1)RS-232C (tbctl/tpin.c)

	**Communication is not normal when this is not received.

		[root@localhost /root]# ./tpin /dev/ttyS0
		path=3 raw mode
		>> touch-panel test prog. open [/dev/ttyS0]
		in = $12                        .....It receives from the controller
						     at the time of OPEN.**
		                                <----<return>
		*** command ***
		  1:reset         2:specify
		  3:goto XYP      4:goto IDLE from XYP
		 10:read status  11:read eeprom
		1                               <----Item 1 is chosen.
		input = .....[1] 1
		OUT len=1 $55 
		write 1 22
		in = $06                        .....ACK(=0x06) is received.**
		                                <----<return>
		*** command ***
		  1:reset         2:specify
		  3:goto XYP      4:goto IDLE from XYP
		 10:read status  11:read eeprom
		2                               <----Item 2 is chosen.
		input = .....[2] 2
		OUT len=2 $5 $41 
		write 2 22
		in = $06                        .....ACK(=0x06) is received.**
		                                <----<return>
		*** command ***
		  1:reset         2:specify
		  3:goto XYP      4:goto IDLE from XYP
		 10:read status  11:read eeprom
		3                               <----Item 3 is chosen.
		input = .....[3] 3
		OUT len=1 $31 
		write 1 22
		     ......Coordinates will be displayed if touch input is carried out.
		PenDown:(x,y)=(642,536)=($0282,$0218) : $02 $82 $02 $18
		PenDown:(x,y)=(642,536)=($0282,$0218) : $02 $82 $02 $18
		PenDown:(x,y)=(642,536)=($0282,$0218) : $02 $82 $02 $18
		PenUp

	(2) USBiusb/usbtest.c)
		[root@localhost usb]# insmod usbdmc.o
		Warning: loading usbdmc.o will taint the kernel: no license
		  See http://www.tux.org/lkml/#export-tainted for information about 
		  tainted modules
		Module usbdmc loaded, with warnings
		[root@localhost usb]# ./usbtest 2
		reset
		specify
		goto xyp
		ok
		get status 3190 
		read eeprom res 0
		goto xyp                        ......Waiting for touch input.
		     ......Coordinates will be displayed if touch input is carried out.
		Touch 11 ON  ( 884, 597)
		Touch 10 OFF ( 884, 597)
		Touch 11 ON  ( 890, 602)
		Touch 10 OFF ( 890, 602)

********************************************************************************************
Remarks 6.  Compatibility
********************************************************************************************
	The following cautions are required when upgrading from a former version.

	dmc_calib.dat
		It does not have the compatibility from a former version. It is necessary
		to re-create with this version.

	Calibration data in EEPROM
		It does not have the compatibility from a former version. It is necessary
		to re-create with this version.




Copyright (C) 2005-2006 DMC Co., Ltd
	Permission is hereby granted, free of charge, to any person obtaining a
	copy of this software and associated documentation files (the "Software"),
	to deal in the Software without restriction, including without limitation
	the rights to use, copy, modify, merge, publish, distribute, sublicense,
	and/or sell copies of the Software, and to permit persons to whom the
	Software is furnished to do so, subject to the following conditions:

	The above copyright notice and this permission notice shall be included in
	all copies or substantial portions of the Software.

	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
	THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
	WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
	OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
	SOFTWARE.

	Except as contained in this notice, the name of the DMC Co., Ltd shall not 
	be used in advertising or otherwise to promote the sale, use or other dealings
	in this Software without prior written authorization from DMC Co., Ltd.




This document can be freely distributed, but any alternation to this document is prohibited.
