Tews Technologies TDRV003-SW-65 User manual

The Embedded I/O Compan
y
TDRV003-SW-65
Windows Device Driver
16(8) Digital I/O
Version 2.0.x
User Manual
Issue 2.0.0
June 2011
TEWS TECHNOLOGIES GmbH
Am Bahnhof 7 25469 Halstenbek, Germany
Phone: [phone] Fax: [phone]
e-mail: [e-mail] www.tews.com

TDRV003-SW-65 – Windows Device Driver Page 2 of 59
TDRV003-SW-65
Windows Device Driver
16(8) Digital I/O
Supported Modules:
TPMC670
TPMC671
This document contains information, which is
proprietary to TEWS TECHNOLOGIES GmbH. Any
reproduction without written permission is forbidden.
TEWS TECHNOLOGIES GmbH has made any
effort to ensure that this manual is accurate and
complete. However TEWS TECHNOLOGIES GmbH
reserves the right to change the product described
in this document at any time without notice.
TEWS TECHNOLOGIES GmbH is not liable for any
damage arising out of the application or use of the
device described herein.
¤2005-2011 by TEWS TECHNOLOGIES GmbH
Issue Description Date
1.0.0 First Issue October 12, 2005
1.0.1 Example CloseHandle() corrected, New Address TEWS LLC,
file list changed
May 19, 2008
1.0.2 Files moved to subdirectory June 23, 2008
2.0.0 Windows7 support and API functions added March 21, 2011

TDRV003-SW-65 – Windows Device Driver Page 3 of 59
Table of Contents
1 INTRODUCTION......................................................................................................... 4
2 INSTALLATION.......................................................................................................... 5
2.1 Software Installation .......................................................................................................................5
2.1.1 Windows 2000 / XP..............................................................................................................5
2.1.2 Windows 7............................................................................................................................6
2.2 Confirming Driver Installation .......................................................................................................6
3 DRIVER CONFIGURATION ....................................................................................... 7
3.1 Event Queue Configuration ...........................................................................................................7
4 API DOCUMENTATION ............................................................................................. 8
4.1 General Functions...........................................................................................................................8
4.1.1 tdrv003Open ........................................................................................................................8
4.1.2 tdrv003Close ......................................................................................................................10
4.2 Device Access Functions.............................................................................................................12
4.2.1 tdrv003InputRead...............................................................................................................12
4.2.2 tdrv003OutputWrite ............................................................................................................14
4.2.3 tdrv003OutputRead............................................................................................................16
4.2.4 tdrv003OutputWriteMask ...................................................................................................18
4.2.5 tdrv003OutputSetBits .........................................................................................................20
4.2.6 tdrv003OutputClearBits......................................................................................................22
4.2.7 tdrv003EventWait...............................................................................................................24
4.2.8 tdrv003DebouncerEnable ..................................................................................................26
4.2.9 tdrv003DebouncerDisable .................................................................................................28
4.2.10 tdrv003WatchdogEnable ...............................................................................................30
4.2.11 tdrv003WatchdogDisable...............................................................................................32
4.2.12 tdrv003WatchdogReset .................................................................................................34
5 DEVICE DRIVER PROGRAMMING ......................................................................... 36
5.1 TDRV003 Files and I/O Functions................................................................................................36
5.1.1 Opening a TDRV003 Device..............................................................................................36
5.1.2 Closing a TDRV003 Device ...............................................................................................38
5.1.3 TDRV003 Device I/O Control Functions ............................................................................39
5.1.3.1 IOCTL_TDRV003_READ ...........................................................................................41
5.1.3.2 IOCTL_TDRV003_WRITE .........................................................................................42
5.1.3.3 IOCTL_TDRV003_OUTPUTGET...............................................................................44
5.1.3.4 IOCTL_TDRV003_WRITEMASK ...............................................................................46
5.1.3.5 IOCTL_TDRV003_OUTPUTSETBITS .......................................................................48
5.1.3.6 IOCTL_TDRV003_OUTPUTCLEARBITS ..................................................................50
5.1.3.7 IOCTL_TDRV003_WAIT_EVENT ..............................................................................52
5.1.3.8 IOCTL_TDRV003_DEBENABLE ...............................................................................54
5.1.3.9 IOCTL_TDRV003_DEBDISABLE ..............................................................................56
5.1.3.10 IOCTL_TDRV003_WDENABLE...............................................................................57
5.1.3.11 IOCTL_TDRV003_WDDISABLE..............................................................................58
5.1.3.12 IOCTL_TDRV003_WDRESET .................................................................................59

TDRV003-SW-65 – Windows Device Driver Page 4 of 59
1 Introduction
The TDRV003-SW-65 Windows device driver is a kernel mode driver which allows the operation of
supported hardware modules on an Intel or Intel-compatible Windows operating system. Supported
Windows versions are:
¾Windows 2000
¾Windows XP
¾Windows XP Embedded
¾Windows 7 (32bit and 64bit)
The standard file and device (I/O) functions (CreateFile, CloseHandle, and DeviceIoControl) provide
the basic interface for opening and closing a resource handle and for performing device I/O control
operations.
The TDRV003 device driver supports the following features:
¾write new output value
¾write new output value with mask
¾set/clear individual output lines
¾read state of input lines
¾wait for interrupt events (rising/falling edge) on each input line
¾start and stop the output watchdog
¾acknowledge watchdog errors
¾configure & start and stop input debouncing
The TDRV003-SW-65 supports the modules listed below:
TPMC670 16(8) Digital Input (24V)
16(8) Digital Output (24V, 0.5A)
(50 pin connector)
PMC
TPMC671 16 Digital Input (24V)
16 Digital Output (24V, 0.5A)
(64 pin connector)
PMC
In this document all supported modules and devices will be called TDRV003. Specials for
certain devices will be advised.
To get more information about the features and use of TDRV003 devices it is recommended to read
the manuals listed below.
TPMC670/TPMC671 User manual
TPMC670/TPMC671 Engineering Manual

TDRV003-SW-65 – Windows Device Driver Page 5 of 59
2Installation
Following files are located in directory TDRV003-SW-65 on the distribution media:
i386\ Directory containing driver files for 32bit Windows versions
amd64\ Directory containing driver files for 64bit Windows versions
installer_32bit.exe Installation tool for 32bit systems (Windows XP or later)
installer_64bit.exe Installation tool for 64bit systems (Windows XP or later)
tdrv003.inf Windows installation script
tdrv003.h Header file with IOCTL codes and structure definitions
example\tdrv003exa.c Example application
api\tdrv003api.c Application Programming Interface source
api\tdrv003api.h Application Programming Interface header
TDRV003-SW-65-2.0.0.pdf This document
Release.txt Information about the Device Driver Release
ChangeLog.txt Release history
2.1 Software Installation
2.1.1 Windows 2000 / XP
This section describes how to install the TDRV003 Device Driver on a Windows 2000 / XP operating
system.
After installing the TDRV003 card(s) and boot-up your system, Windows 2000/XPsetupwillshowa
"New hardware found" dialog box.
1. The "UpgradeDeviceDriverWizard" dialog box will appear on your screen.
Click "Next" button to continue.
2. In the following dialog box, choose "Search for a suitable driver for my device".
Click "Next" button to continue.
3. Insert the TDRV003 driver media; select "Disk Drive" in the dialog box.
Click "Next" button to continue.
4. Now the driver wizard should find a suitable device driver on the media.
Click "Next" button to continue.
5. Complete the upgrade device driver and click "Finish"totakeallthechangeseffect.
6. Now copy all needed files (tdrv003.h and API files) to the desired target directories.
After successful installation the TDRV003 device driver will start immediately and creates devices
(TDRV003_1, TDRV003_2 ...) for all recognized TDRV003 modules.

TDRV003-SW-65 – Windows Device Driver Page 6 of 59
2.1.2 Windows 7
This section describes how to install the TDRV003-SW-65 Device Driver on a Windows 7 (32bit or
64bit) operating system.
Depending on the operating system type, execute the installer binaries foreither32bitor64bit
systems. This will install all required driver files using an installationwizard.
Copy needed files (tdrv003.h and API files) to desired target directory.
After successful installation a device is created for each module found (TDRV003_1, TDRV003_2 ...).
2.2 Confirming Driver Installation
To confirm that the driver has been properly loaded, perform the following steps:
1. Open the Windows Device Manager:
a. For Windows 2000 / XP, open the "Control Panel"from"My Computer" and click the
"System" icon and choose the "Hardware" tab, and then click the "Device Manager"
button.
b. For Windows 7, open the "Control Panel"from"My Computer" and then click the
"Device Manager"entry.
2. Click the "+" in front of "Embedded I/O".
The driver "TEWS TECHNOLOGIES – TDRV003 Digital I/O (TPMC670)" should appear for
each installed device.

TDRV003-SW-65 – Windows Device Driver Page 7 of 59
3 Driver Configuration
3.1 Event Queue Configuration
After Installation of the TDRV003 Device Driver the number concurrent event controlled read request
is limited to 10.
If the default values are not suitable the configuration can be changed by modifying the registry, for
instance with regedt32.
To change the number of queue entries the following value must be modified.
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\tdrv003\Parameters\NumReqEntries
Valid values are in range between 1 and 100.

TDRV003-SW-65 – Windows Device Driver Page 8 of 59
4 API Documentation
4.1 General Functions
4.1.1 tdrv003Open
NAME
tdrv003Open – Opens a Device
SYNOPSIS
TDRV003_HANDLE tdrv003Open
(
char *DeviceName
);
DESCRIPTION
Before I/O can be performed to a device, a file descriptor must be opened by a call to this function.
PARAMETERS
DeviceName
This parameter points to a null-terminated string that specifies the name of the device.
EXAMPLE
#include “tdrv003api.h”
TDRV003_HANDLE hdl;
/*
** open file descriptor to device
*/
hdl = tdrv003Open(“\\\\.\\TDRV003_1” );
if (hdl == NULL)
{
/* handle open error */
}

TDRV003-SW-65 – Windows Device Driver Page 9 of 59
RETURNS
A device handle, or NULL if the function fails. To get extended error information, call GetLastError.
ERROR CODES
All error codes are standard error codes set by the I/O system.

TDRV003-SW-65 – Windows Device Driver Page 10 of 59
4.1.2 tdrv003Close
NAME
tdrv003Close – Closes a Device
SYNOPSIS
TDRV003_STATUS tdrv003Close
(
TDRV003_HANDLE hdl
);
DESCRIPTION
This function closes previously opened devices.
PARAMETERS
hdl
This value specifies the device handle to the hardware module retrieved by acalltothe
corresponding open-function.
EXAMPLE
#include “tdrv003api.h”
TDRV003_HANDLE hdl;
TDRV003_STATUS result;
/*
** close file descriptor to device
*/
result = tdrv003Close( hdl );
if (result != TDRV003_OK)
{
/* handle close error */
}

TDRV003-SW-65 – Windows Device Driver Page 11 of 59
RETURNS
On success TDRV003_OK, or an appropriate error code.
ERROR CODES
All error codes are standard error codes set by the I/O system.

TDRV003-SW-65 – Windows Device Driver Page 12 of 59
4.2 Device Access Functions
4.2.1 tdrv003InputRead
NAME
tdrv003InputRead – read state of input lines
SYNOPSIS
TDRV003_STATUS tdrv003InputRead
(
TDRV003_HANDLE hdl,
unsigned short *pInputBuf
);
DESCRIPTION
This function reads the current state of the input lines.
PARAMETERS
hdl
This argument specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
pInputBuf
This argument points to a buffer where the value will be returned.

TDRV003-SW-65 – Windows Device Driver Page 13 of 59
EXAMPLE
#include “tdrv003api.h”
TDRV003_HANDLE hdl;
TDRV003_STATUS result;
unsigned short data;
result = tdrv003InputRead(hdl, &data);
if (result != TDRV003_OK)
{
/* handle error */
}
RETURNS
On success, TDRV003_OK is returned. In the case of an error, the appropriate error code is returned
by the function.
ERROR CODES
TDRV003_ERR_INVALID_HANDLE The specified TDRV003_HANDLE is invalid.

TDRV003-SW-65 – Windows Device Driver Page 14 of 59
4.2.2 tdrv003OutputWrite
NAME
tdrv003OutputWrite – write a new value to the output port
SYNOPSIS
TDRV003_STATUS tdrv003OutputWrite
(
TDRV003_HANDLE hdl,
unsigned short OutputValue
);
DESCRIPTION
This function writes a new value to the output port.
PARAMETERS
hdl
This argument specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
OutputValue
This argument specifies the new output value. Bit 0 specifies the new state of output line 1; bit 1
specifies the new state for output line 2 and so on.
EXAMPLE
#include “tdrv003api.h”
TDRV003_HANDLE hdl;
TDRV003_STATUS result;
// set OUTPUT1 and OUTPUT16 and clear all other
result = tdrv003OutputWrite(hdl, 0x8001);
if (result != TDRV003_OK)
{
/* handle error */
}

TDRV003-SW-65 – Windows Device Driver Page 15 of 59
RETURNS
On success, TDRV003_OK is returned. In the case of an error, the appropriate error code is returned
by the function.
ERROR CODES
TDRV003_ERR_INVALID_HANDLE The specified TDRV003_HANDLE is invalid.
TDRV003_ERR_IO The output register is locked by a watchdog failure.
Execute the function tdrv003WatchdogReset to
reset the watchdog error.

TDRV003-SW-65 – Windows Device Driver Page 16 of 59
4.2.3 tdrv003OutputRead
NAME
tdrv003OutputRead – read current state of output lines
SYNOPSIS
TDRV003_STATUS tdrv003OutputRead
(
TDRV003_HANDLE hdl,
unsigned short *pOutputBuf
);
DESCRIPTION
This function reads the current state of the output lines.
PARAMETERS
hdl
This argument specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
pOutputBuf
This argument points to a buffer where the value will be returned.

TDRV003-SW-65 – Windows Device Driver Page 17 of 59
EXAMPLE
#include “tdrv003api.h”
TDRV003_HANDLE hdl;
TDRV003_STATUS result;
unsigned short data;
result = tdrv003OutputRead(hdl, &data);
if (result != TDRV003_OK)
{
/* handle error */
}
RETURNS
On success, TDRV003_OK is returned. In the case of an error, the appropriate error code is returned
by the function.
ERROR CODES
TDRV003_ERR_INVALID_HANDLE The specified TDRV003_HANDLE is invalid.
TDRV003_ERR_IO The output register is locked by a watchdog failure.
Execute the function tdrv003WatchdogReset to
reset the watchdog error.

TDRV003-SW-65 – Windows Device Driver Page 18 of 59
4.2.4 tdrv003OutputWriteMask
NAME
tdrv003OutputWriteMask – writes a masked value to the output port
SYNOPSIS
TDRV003_STATUS tdrv003OutputWriteMask
(
TDRV003_HANDLE hdl,
unsigned short OutputValue,
unsigned short mask
);
DESCRIPTION
This control function writes a masked value to the output port. Only those bits in value for which the
corresponding bit position in the mask is set to 1 will be changed in the output port.
PARAMETERS
hdl
This argument specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
OutputValue
This argument specifies the masked value for the output port. Bit 0 corresponds to the first
output line; bit 1 corresponds to the second output line and so on.
mask
This argument specifies the mask for relevant bits. Bit 0 corresponds to the first output line; bit 1
corresponds to the second output line and so on.
Only those bits in OutputValue for which the corresponding bit position in this mask is set to 1
will be changed in the output port.

TDRV003-SW-65 – Windows Device Driver Page 19 of 59
EXAMPLE
#include “tdrv003api.h”
TDRV003_HANDLE hdl;
TDRV003_STATUS result;
// clear OUTPUT1 and set OUTPUT16 and leave all other lines unchanged
result = tdrv003OutputWriteMask(hdl, 0x8000, 0x8001);
if (result != TDRV003_OK)
{
/* handle error */
}
RETURNS
On success, TDRV003_OK is returned. In the case of an error, the appropriate error code is returned
by the function.
ERROR CODES
TDRV003_ERR_INVALID_HANDLE The specified TDRV003_HANDLE is invalid.
TDRV003_ERR_IO The output register is locked by a watchdog failure.
Execute the function tdrv003WatchdogReset to
reset the watchdog error.

TDRV003-SW-65 – Windows Device Driver Page 20 of 59
4.2.5 tdrv003OutputSetBits
NAME
tdrv003OutputSetBits – set specific output lines
SYNOPSIS
TDRV003_STATUS tdrv003OutputSetBits
(
TDRV003_HANDLE hdl,
unsigned short OutputBits
);
DESCRIPTION
This function sets specific bits in the output port to active state (1).
PARAMETERS
hdl
This argument specifies the device handle to the hardware module retrieved by a call to the
corresponding open-function.
OutputBits
This argument specifies a mask of relevant bits to set. Bit 0 corresponds to the first output line;
bit 1 corresponds to the second output line and so on. Bits which are set (1) inthismaskwillbe
set in the corresponding bits in the output port.
EXAMPLE
#include “tdrv003api.h”
TDRV003_HANDLE hdl;
TDRV003_STATUS result;
// set OUTPUT1 and OUTPUT16 to active state
result = tdrv003OutputSetBits(hdl, (1<<15) | (1<<0));
if (result != TDRV003_OK)
{
/* handle error */
}