Campbell Scientific TDRSDK User Manual
INSTRUCTION MANUAL
TDRSDK Software
Development Kit for TDR100
8/05
Copyright (c) 2005
Campbell Scientific, Inc.
TDRSDK Table of Contents
PDF viewers note: These page numbers refer to the printed version of this document. Use
the Adobe Acrobat® bookmarks tab for links to specific sections.
1. Overview.......................................................................1
1.1 Purpose of TDRSDK................................................................................1
1.2 Requirements............................................................................................1
1.3 Description of TDRSDK package............................................................1
2. TDRSDK Description...................................................2
2.1 Description of TDRCOM.DLL ................................................................2
2.2 Task complete or data available notification after command issued........2
2.2.1 Using the Call-back method..............................................................2
2.2.2 Using the State Machine method.......................................................2
3. TDR100 Command Set ................................................2
3.1 Commands for error odes, serial port control, call-back and
state machine queries ...........................................................................3
3.2 Commands to retrieve TDR100 waveform parameter values...................5
3.3 Commands for setting TDR100 parameters .............................................5
3.4 Commands to execute TDR100 measurements and to retrieve data.........8
4. Sample Programs......................................................15
Appendices
A. TDR100 Command Protocol...................................A-1
B. TDR100 Response Protocol................................... B-1
i
This is a blank page.
TDRSDK Software Development Kit for TDR100
1. Overview
1.1 Purpose of TDRSDK
TDR100 Software Development Kit, TDRSDK, allows users to create custom
applications that communicate directly with the TDR100. This is
accomplished by using a dynamically linked library (DLL). The DLL
functions as a transparent interface between a 32-bit personal computer (PC)
and the TDR100. The DLL allows access to the entire TDR100 command set.
Applications can be written using C++, Delphi (Pascal) and Visual Basic
including Microsoft Excel.
1.2 Requirements
The TDRCOM.DLL is designed to run in the Microsoft 32-bit Windows
environment, which presently includes Windows97, Windows98, WindowsNT,
Windows2000 and WindowsXP. The TDRCOM.DLL is designed solely for
the purpose of communicating with Campbell Scientific, Inc. TDR100 Time
Domain Reflectometer over direct connect RS232 serial communications at
one of three baud rates, 9600bps, 19.2kbps, 57.6kbps (default).
1.3 Description of TDRSDK package
The TDRSDK software package includes the following on a compact disk:
1. Executable install program for installing TDRSDK on the computer to be
used.
2. Dynamically Linked Library (DLL) file that is installed when the setup
application is run. The DLL contains calls TDR100 command set
functions for setting parameter, retrieving data and control functions.
3. Operating manual
4. Example programs in C++, Delphi (Pascal) and Visual Basic including
Microsoft Excel.
1
TDRSDK Software Development Kit for TDR100
2. TDRSDK Description
2.1 Description of TDRCOM.DLL
TDRCOM.DLL is a dynamically linked library, DLL, comprised of functions
that allow control and monitoring of a TDR100 using PC serial
communications. The DLL functions are called by a program written by the
user, and the TDR100 communication protocol is transparent. Each DLL
function is defined with a name and a number. The functions perform a range
of TDR100 tasks including setting measurement parameters and collecting
waveform data.
2.2 Task complete or data available notification after command
issued
To enhance PC performance, query methods are used to determine if
information is available from the TDR100. Many of the TDRCOM.DLL API
functions only initiate commands to the TDR100 and do not continue to
execute while the TDR100 is running the assigned task. The Call-back and
State Machine methods are used to determine when the TDR100 has completed
a task.
2.2.1 Using the Call-back method
When programming in C++ or Pascal, a call-back procedure can be used to
notify the user program that data is available from the TDR100. The call-back
procedure uses 2 two parameters, (1) DLL command number and (2) error
code, to determine which command to execute and which part of the user
program to notify when data is available from TDR100. DLL function
RegCallBack is used to pass the address of the procedure in the user program
that will be notified when data available.
2.2.2 Using the State Machine method
The State Machine method is used in Visual Basic (including Excel). The
main part of the DLL will be implemented as a state machine, incrementally
stepping through short blocks of functionality (states). At regular time
intervals an Application Program Interface (API) function queries the state
machine to determine if data is available from the TDR100. When the data is
signaled to be available, a separate command is issued to retrieve the data from
the DLL to the user program
3. TDR100 Command Set
The TDR100 command set is also called the TDR100COM Application
Program Interface (API). Each command has an associated command number
that is used in DLL execution.
2
TDRSDK Software Development Kit for TDR100
3.1 Commands for error codes, serial port control, call-back
and state machine queries
1. ReadErrorCode
Allows the calling application to get an error string by specifying the API
function number, and error code. This is used to determine reason for error on
failure of a DLL command.
int ReadErrorCode(int apiNumber, int errCode, char errStr, int strSiz)
Parameters: apiNumber: API function number
errCode: return non-zero value from each API function
errStr: describes Error in a string
strSiz: buffer size for errStr.
Return Codes: 0 = Success
1 = Unknown Error Code
2. SetCommPort
Allows the calling application to specify the communications port and the
communication baud rate. The comm port values are limited to those available
on the machine. The baud rate is limited to 9600bps, 19200bps, or 57600bps.
The default baud rate value is 57600bps. Changing baud rate requires
repositioning jumpers inside TDR100. See TDR100 Ope r at i ng Ma nual .
int SetCommPort(short portNbr, int baudRate)
Parameters: portNbr: Communications port number, i.e. 1 for Com1
baudRate: Communications baud rate, i.e. 57600
Return Codes: 0 = Success
1 = Parameter out of Range
3. CloseCommPort
Allows the calling application to close the current communications port
previously opened using ‘SetCommPort’;
int CloseCommPort
Parameters: None
Return Codes: 0 = Success
1 = Failure
4. RegCallBack
Allows the calling application to register a call-back procedure with the DLL.
This call-back procedure will allow the DLL to notify the calling application
when a command response is received from the TDR100. The call-back
procedure will have parameters to report command type and success/failure.
The procedure cannot be an object method. This method does not wor k wi t h
VB or VBA. See examples.
int RegCallBack (int cmdType, int errCode))
3
TDRSDK Software Development Kit for TDR100
Parameters: CBfunc: Pointer to procedure that will be called (if
cmdType: API function numbers
errCode: error code for the cmdType.
Return Codes: 0 = Success
1 = Failure
5. GetDLLver
Allows the calling application to obtain the DLL version.
int GetDLLver(char Ver, int iStrSize)
Parameters: Ver: Pointer to a string buffer. Upon successful return, will
iStrSize: Integer, size of pVer string buffer
Return Codes: 0 = Success
1 = String buffer too small
6. QuerySM
required), upon receipt of a TDR100 command response.
contain the version in the form ‘1.0’.
Allows the calling application to check the current state of the state machine in
the DLL. This function returns immediately. An application is required to
make the request according to the current state; otherwise, an error code will be
returned. See the VBA examples.
int QuerySM(int FuncNbr)
Parameters: FuncNbr: pointer to integer value, returns function number
being processed or data available from.
Return Codes: 0 = Idle
n = still processing request
100 = Get data successfully
101 = CRC16 check error
102 = Wrong response
7. ReadSM_State
Allows the calling application to translate state number to a state string.
int ReadSM_State(int stateNbr, char stateStr, int strSiz)
Parameters: stateNbr: state numbers.
stateStr: state described in a string.
strSiz: buffer size for stateStr.
4
Return Codes: 0 = Success
1 = Failure
TDRSDK Software Development Kit for TDR100
3.2 Commands to retrieve TDR100 waveform parameter values
The waveform parameter values are (1) relative propagation velocity, Vp, (2)
waveform averaging, (3) number of data points in waveform, (4) distance to
beginning of waveform, (5) length of waveform window, (6) probe rod length,
(7) probe offset, and (8) cell constant or Kp.
When a ‘request’ c ommand is issued, Callback or State Machine is used to
determine if requested data is available. When Callback or State Machine is
satisfied the data is written to the DLL. A ‘get’ command is then used to get
the data from the DLL to the API.
8. ReqSettings
Allows calling application to request current TDR100 parameter settings. If no
error occurred, current settings will be available from the DLL, and can be
retrieved using the GetSetting (#9) API call after you receive a call back or get
a state 100. Result: Settings values are sent by the TDR100 to the DLL.
int ReqSettings
Parameters: None
Return Codes: 0 = Success
1 = Failure
9. GetSetting
Allows calling application to get TDR100 parameter settings stored in DLL.
This command, if successful, will return a record containing a setting. This
command must be called repeatedly to get all 9 settings.
int GetSetting(int recNbr, float Fval)
Parameters: recNbr: number counting from 1 in a data structure.
Fval: Pointer to a floating point value.
Return Codes: 0 = Success
1 = Failure
3.3 Commands for setting TDR100 parameters
10. SetVpSetting
Allows calling application to set the TDR100 relative propagation velocity, Vp.
When transaction is complete, the call-back procedure will be called (if
required), or the state machine can be queried until non-zero state is obtained.
int SetVpSetting(float fValue)
Parameters: fValue: Float, value with which to set TDR100 Vp setting.
Return Code: 0 = Success
1 = Failure
5
Loading...