Page 1
TPRO/TSAT-PCI
SYNCHRONIZABLE TIMECODE
GENERATOR with
UNIVERSAL PCI BUS INTERFACE
Windows Driver Application Programmer’s Guide
95 Methodist Hill Drive
Rochester, NY 14623
Phone: US +1.585.321.5800
Fax: US +1.585.321.5219
www.spectracomcorp.com
Part Number 1186-5002-0050
Manual Revision C
December 2010
Page 2
Copyright © 2009 Spectracom Corporation. The contents of this publication may not be reproduced
in any form without the written permission of Spectracom Corporation. Printed in USA.
Specifications subject to change or improvement without notice.
Spectracom, NetClock, Ageless, TimeGuard, TimeBurst, TimeTap, LineTap, MultiTap, VersaTap, and
Legally Traceable Time are Spectracom registered trademarks. All other products are identified by
trademarks of their respective companies or organizations. All rights reserved.
Page 3
LIMITED WARRANTY
SPECTRACOM LIMITED WARRANTY
Spectracom warrants each new product manufactured and sold by
it to be free from defects in software, material, workmanship, and
construction, except for batteries, fuses, or other material normally
consumed in operation that may be contained therein AND AS
NOTED BELOW, for five years after shipment to the original
purchaser (which period is referred to as the “warranty period”).
This warranty shall not apply if the product is used contrary to the
instructions in its manual or is otherwise subjected to misuse,
abnormal operations, accident, lightning or transient surge, repairs
or modifications not performed by Spectracom.
The GPS receiver is warranted for one year from date of shipment
and subject to the exceptions listed above. The power adaptor, if
supplied, is warranted for one year from date of shipment and
subject to the exceptions listed above.
THE ANALOG CLOCKS ARE WARRANTED FOR ONE YEAR
FROM DATE OF SHIPMENT AND SUBJECT TO THE EXCEPTIONS
LISTED ABOVE.
THE TIMECODE READER/GENERATORS ARE WARRANTED FOR
ONE YEAR FROM DATE OF SHIPMENT AND SUBJECT TO THE
EXCEPTIONS LISTED ABOVE.
The Rubidium oscillator, if supplied, is warranted for two years from
date of shipment and subject to the exceptions listed above.
All other items and pieces of equipment not specified above,
including the antenna unit, antenna surge suppressor and antenna
pre-amplifier are warranted for 5 years, subject to the exceptions
listed above.
WARRANTY CLAIMS
Spectracom’s obligation under this warranty is limited to in-factory
service and repair, at Spectracom’s option, of the product or the
component thereof, which is found to be defective. If in
Spectracom’s judgment the defective condition in a Spectracom
product is for a cause listed above for which Spectracom is not
responsible, Spectracom will make the repairs or replacement of
components and charge its then current price, which buyer agrees
to pay.
Spectracom shall not have any warranty obligations if the
procedure for warranty claims is not followed. Users must notify
Spectracom of the claim with full information as to the claimed
defect. Spectracom products shall not be returned unless a return
authorization number is issued by Spectracom.
Spectracom products must be returned with the description of the
claimed defect and identification of the individual to be contacted
if additional information is needed. Spectracom products must be
returned properly packed with transportation charges prepaid.
Shipping expense: Expenses incurred for shipping Spectracom
products to and from Spectracom (including international customs
fees) shall be paid for by the customer, with the following
exception. For customers located within the United States, any
product repaired by Spectracom under a “warranty repair” will be
shipped back to the customer at Spectracom’s expense unless
special/faster delivery is requested by customer.
Spectracom highly recommends that prior to returning equipment for
service work, our technical support department be contacted to
provide trouble shooting assistance while the equipment is still
installed. If equipment is returned without first contacting the support
department and “no problems are found” during the repair work,
an evaluation fee may be charged.
EXCEPT FOR THE LIMITED WARRANTY STATED ABOVE,
SPECTRACOM DISCLAIMS ALL WARRANTIES OF ANY KIND
WITH REGARD TO SPECTRACOM PRODUCTS OR OTHER
MATERIALS PROVIDED BY SPECTRACOM, INCLUDING
WITHOUT LIMITATION ANY IMPLIED WARRANTY OR
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Spectracom shall have no liability or responsibility to the original
customer or any other party with respect to any liability, loss, or
damage caused directly or indirectly by any Spectracom product,
material, or software sold or provided by Spectracom, replacement
parts or units, or services provided, including but not limited to any
interruption of service, excess charges resulting from malfunctions of
hardware or software, loss of business or anticipatory profits
resulting from the use or operation of the Spectracom product or
software, whatsoever or howsoever caused. In no event shall
Spectracom be liable for any direct, indirect, special or
consequential damages whether the claims are grounded in
contract, tort (including negligence), or strict liability.
EXTENDED WARRANTY COVERAGE
Extended warranties can be purchased for additional periods
beyond the standard five-year warranty. Contact Spectracom no
later than the last year of the standard five-year warranty for
extended coverage.
SPECTRACOM 95 Methodist Hill Drive Rochester, NY 14623
+1.585.321.5800 FAX: +1.585.321.5218 www.spectracomcorp.com sales@spectracomcorp.com
Page 4
Page 5
Spectracom Corporation TPRO-PCI-U/TSAT-PCI-U — Windows Driver
iii
Table of Contents
1 OVERVIEW
2 INSTALLING THE DRIVER
2.1 Running the TPRO/TSAT Control Utility ........................................................................................ 2-2
2.2 Clock Daemon Utilities................................................................................................................... 2-2
2.3 Example Executables and Source Code ....................................................................................... 2-4
3 INTERFACE TO THE WINDOWS API
3.1 Header File .................................................................................................................................... 3-1
3.2 TPRO API — Routine Descriptions ............................................................................................... 3-7
..................................................................................................
...............................................................................
................................................................
1-1
2-1
3-1
Synchronizable Timecode Generator Application Programmer’s Guide
Page 6
Page 7
Spectracom Corporation TPRO-PCI-U/TSAT-PCI-U — Windows Driver
1-1
1 Overview
1.1
General
The TPRO/TSAT PCI Windows Driver provides an interface between the PCI board and
applications developed for 32-bit or 64-bit Windows™ operating systems. In addition to the
interface library, a Control Utility program, Time Daemon Utility and example programs with
source code are provided. The TPRO/TSAT PCI Windows Driver has been tested for
compatibility with the following versions of Windows:
• Windows 2000
• Windows XP
• Windows Server 2003
• Windows Vista
• Windows Server 2008 & R2
• Windows 7
The 32-bit library file and DLL (tpro.lib & tpro.dll) can be found in the “KSI\Dev”
directory under “Program Files”. Similarly, the 64-bit versions of the same files are located
in the “KSI\Dev64” directory under “Program Files (x86)“ on 64-bit operating systems.
1.2
Features
The TPRO/TSAT PCI Windows Driver includes the following:
• Interface API library that accesses all of the PCI board features
• Example programs with source code, utilizing the API library
• A Control Utility that can be used to retrieve data from the card and/or modify card
settings
• A Time Daemon tray Utility and Time Daemon service that query the TPRO/TSAT-PCI
card and sets the computer’s system clock at a user-defined interval
Synchronizable Timecode Generator Application Programmer’s Guide
Page 8
Page 9
Spectracom Corporation TPRO-PCI-U/TSAT-PCI-U — Windows Driver
2-1
2 Installing the Driver
NOTE: If your system is equipped with the TPRO-TSAT PCI software driver, it must be
uninstalled before installing the new, updated driver. To uninstall the driver:
1. Go to “Control Panel”, “Add/Remove Programs”
2. Remove “TPRO-TSAT PCI”
To install the driver, perform the following steps:
1. Install the TPRO/TSAT-PCI card in a vacant slot on the computer to be used.
2. Switch on the PC power. Once the PC is running, Windows may prompt you to install the
newly found hardware. Disregard and cancel this dialog box.
3. Insert the CD with the TPRO/TSAT-PCI driver into the CD-ROM drive and follow the
automated installation procedure. If Auto-Run is disabled, manually install the driver by
running “setup.exe” from the Windows driver folder located on the CD.
4. Once the driver installation has completed, the computer must be rebooted for the changes
to take effect.
The following folders are created in the Program Files folder under “KSI” when the driver is
installed:
• control – contains the Clock Daemon utilities, daemon.ini, and Control utility
• dev – contains “tpro.h” and “tpro.dll” files needed for application software
development
• documentation – contains PCI user manual and application programmer’s guide
• drivers – contains all Windows driver files
• examples – contains example executables and source code for each TPRO API
Synchronizable Timecode Generator Application Programmer’s Guide
Page 10
TPRO-PCI-U/TSAT-PCI-U — Windows Driver Spectracom Corporation
2-2
2.1 Running the TPRO/TSAT Control Utility
1. From the Windows Start menu, select the “Programs” folder.
2. Select the “Spectracom\PCI” folder.
3. Select the “TPRO-TSAT Control Utility” program.
2.2 Clock Daemon Utilities
Two clock daemon utilities are provided that can be used to set the computer’s system clock:
“Clock Daemon.exe” and “ClockDaemonService.exe”. Both will query the TPRO/TSAT PCI and
set the system clock on a periodic basis.
NOTE: If the PCI board is not synchronized to an external reference, the system clock will not
be set.
Clock Daemon.exe:
When the driver is installed, a shortcut to “Clock Daemon.exe” is automatically added to the
user’s Startup folder and will run automatically from the system tray when the computer boots
up.
A small icon — — will show up in the system tray. Double click on that icon to display a
window. A shortcut can also be found in the “Start/Spectracom Corp/PCI” Windows Start
menu.
Synchronizable Timecode Generator Application Programmer’s Guide
Page 11
TPRO-PCI-U/TSAT-PCI-U Spectracom Corporation
2-3
Device Name: Will select which board you want to use as a time source.
The default is“tpropci0”.
Update Interval: Controls how often the PCI board time will be queried.
The default is “300” seconds.
To enable the clock daemon on startup, make sure the “Enable On Startup” checkbox has been
selected before starting the program.
ClockDaemonService.exe:
“Clock DaemonService.exe” will set the computer’s system clock as does the “Clock
Daemon.exe”, but it will run as a Windows service. It will run automatically at boot-up and does
not need to be added to the user’s Startup folder. The program can be found in the folder
C:\Program Files\KSI\control and a shortcut can be found in the “Start/Spectracom
Corp/PCI” Windows Start menu.
NOTE: Do not attempt to run “Clock DaemonService.exe” and “Clock Daemon.exe” at the
same time. When running the Clock Daemon Service, stop “Clock Daemon.exe” and
remove it from the Startup folder.
Executing ClockDaemonService.exe from the command prompt stops, removes, installs, and
starts the "Clock Daemon" service. The service startup type defaults to automatic. To remove
the "Clock Daemon" service, run ClockDaemonService.exe from a command prompt with the -r
option (ClockDaemonService.exe -r).
The controls for device name and update interval are setup by the “daemon.ini” located in the
folder C:\Program Files\KSI\control.
Synchronizable Timecode Generator Application Programmer’s Guide
Page 12
TPRO-PCI-U/TSAT-PCI-U — Windows Driver Spectracom Corporation
2-4
2.3 Example Executables and Source Code
The driver package includes folders with example programs to interface to the board. The
source code and make files for the example programs are included. All of the example
programs were compiled using Visual Studio 2005. All example programs are 32-bit
applications.
To see usage help for any example program, execute the program with no parameters:
> HW_GetTime.exe
Synchronizable Timecode Generator Application Programmer’s Guide
Page 13
Spectracom Corporation TPRO-PCI-U/TSAT-PCI-U — Windows Driver
3-1
3 Interface to the Windows API
3.1 Header File
The following is the “TPRO.H” API Interface Header File.
/*****************************************************************
**
** Module: tpro.h
** Date: 08/08/2007
** Purpose: Contains structures and definions used to interface
** with the TPRO-PCI or TSAT-PCI API. Applications
** that access the API should include this header.
**
** Copyright(C) 2007 Spectracom Corporation. All Rights Reserved
**
******************************************************************
** Modifications:
**
** 08/08/2007 Multi-user enablement
**
******************************************************************/
#ifndef _defined_TPRO_
#define _defined_TPRO_
#pragma pack(8)
#ifdef __cplusplus
extern "C" {
#endif
#define DLL_EXPORT __declspec(dllexport)
/***************************************************************************
SUPPORT CONSTANTS
***************************************************************************/
/**
*** Heartbeat constants
**/
#define SIG_PULSE (0xE5) // signal type for PCI card
#define SIG_SQUARE (0xE7) // signal type for PCI card
#define SIG_NO_JAM (0) // output type for PCI card
#define SIG_JAM (1) // output type for PCI card
#define HEART_NORMAL (0) // signal type for CPCI card
#define HEART_INVERT (8) // signal type for CPCI card
#define HEART_DISABLE (0) // output type for CPCI card
#define HEART_ENABLE (4) // output type for CPCI card
#define CLK_10MHZ (0) // clock frequency for CPCI board
#define CLK_3MHZ (1) // clock frequency for CPCI board
#define CLK_1MHZ (2) // clock frequency for CPCI board
#define CLK_1KHZ (3) // clock frequency for CPCI board
/*
Synchronizable Timecode Generator Application Programmer’s Guide
Page 14
TPRO-PCI-U/TSAT-PCI-U — Windows Driver Spectracom Corporation
3-2
** Length of firmware rev string
*/
#define TPRO_FIRMWARE_LENGTH ( 4 )
/*
** Length of driver version string "XX.YY"
** (not including termination)
*/
#define TPRO_DRV_VERSION_LENGTH ( 5 )
/**
*** Match constants
**/
#define MATCH_TIME_START (0) // start time
#define MATCH_TIME_STOP (1) // stop time
/*
** board sync options
*/
#define TPRO_DISABLE_SYNC ( 0x0 ) /* freewheel */
#define TPRO_ENABLE_SYNC ( 0x1 ) /* sync to input */
#define TPRO_SYNC_STAT_FREE ( 0x0 ) /* sync is freewheel */
/**
*** Oscillator frequencies - for Compact PCI Card Only
**/
#define OSC_OUT_OFF (0)
#define OSC_OUT_1KHZ (1)
#define OSC_OUT_1MHZ (2)
#define OSC_OUT_5MHZ (3)
#define OSC_OUT_10MHZ (4)
/***************************************************************************
OBJECTS
***************************************************************************/
/*==========================================================================
TPRO BOARD OBJECT
==========================================================================*/
typedef struct TPRO_BoardObj
{ /*----------------------------------------------------------------------*/
void *hDevice;
unsigned short options;
unsigned char slotPosition;
} /*----------------------------------------------------------------------*/
TPRO_BoardObj;
/*==========================================================================
TPRO ALTITUDE OBJECT
==========================================================================*/
typedef struct TPRO_AltObj
{ /*----------------------------------------------------------------------*/
float meters; /*-- meters --------------*/
} /*----------------------------------------------------------------------*/
TPRO_AltObj;
/*==========================================================================
TPRO DATE OBJECT
==========================================================================*/
typedef struct TPRO_DateObj
{ /*----------------------------------------------------------------------*/
unsigned short year; /*-- year ----------------*/
Synchronizable Timecode Generator Application Programmer’s Guide
Page 15
Spectracom Corporation TPRO-PCI-U/TSAT-PCI-U — Windows Driver
3-3
unsigned char month; /*-- month ---------------*/
unsigned char day; /*-- day -----------------*/
} /*----------------------------------------------------------------------*/
TPRO_DateObj;
/*==========================================================================
TPRO LONGITUDE/LATTITUDE OBJECT
==========================================================================*/
typedef struct TPRO_LongLat
{ /*----------------------------------------------------------------------*/
unsigned short degrees; /*-- degrees -------------*/
float minutes; /*-- minutes -------------*/
} /*----------------------------------------------------------------------*/
TPRO_LongObj, TPRO_LatObj;
/*==========================================================================
TPRO MATCH OBJECT
==========================================================================*/
typedef struct TPRO_MatchObj
{ /*----------------------------------------------------------------------*/
unsigned char matchType; /*-- start/stop time -----*/
double seconds; /*-- seconds -------------*/
unsigned char minutes; /*-- minutes -------------*/
unsigned char hours; /*-- hours ---------------*/
unsigned short days; /*-- days ----------------*/
} /*----------------------------------------------------------------------*/
TPRO_MatchObj;
/*==========================================================================
TPRO SATINFO OBJECT
==========================================================================*/
typedef struct TPRO_SatObj
{ /*----------------------------------------------------------------------*/
unsigned char satsTracked; /*-- num sats tracked ----*/
unsigned char satsView; /*-- num sats in view ----*/
} /*----------------------------------------------------------------------*/
TPRO_SatObj;
/*==========================================================================
TPRO HEARTBEAT OBJECT
==========================================================================*/
typedef struct TPRO_HeartObj
{ /*----------------------------------------------------------------------*/
unsigned char signalType; /*-- heart signal type ---*/
unsigned char outputType; /*-- jamming option ------*/
unsigned char clockFreq; /*-- clock freq for CPCI -*/
double frequency; /*-- heartbeat freq ------*/
} /*----------------------------------------------------------------------*/
TPRO_HeartObj;
/*==========================================================================
TPRO TIME OBJECT
==========================================================================*/
typedef struct TPRO_TimeObj
{ /*----------------------------------------------------------------------*/
double secsDouble; /*-- seconds -------------*/
unsigned char seconds; /*-- seconds -------------*/
unsigned char minutes; /*-- minutes -------------*/
unsigned char hours; /*-- hours ---------------*/
unsigned short days; /*-- days ----------------*/
Synchronizable Timecode Generator Application Programmer’s Guide
Page 16
TPRO-PCI-U/TSAT-PCI-U — Windows Driver Spectracom Corporation
3-4
unsigned short year; /*-- year for CPCI board -*/
unsigned short sync; /*--sync flags (0x91xx boards -*/
} /*----------------------------------------------------------------------*/
TPRO_TimeObj;
/*==========================================================================
TPRO WAIT OBJECT
==========================================================================*/
typedef struct TPRO_WaitObj
{ /*----------------------------------------------------------------------*/
unsigned int ticks; /*-- # ticks to wait -----*/
double seconds; /*-- seconds -------------*/
unsigned char minutes; /*-- minutes -------------*/
unsigned char hours; /*-- hours ---------------*/
unsigned short days; /*-- days ----------------*/
unsigned short year; /*-- year for cPCI card --*/
unsigned char month; /*-- month for cPCI card -*/
unsigned char day; /*-- day for cPCI card ---*/
} /*----------------------------------------------------------------------*/
TPRO_WaitObj;
/*==========================================================================
TPRO MEM OBJECT FOR PEEK/POKE
==========================================================================*/
typedef struct TPRO_MemObj
{ /*----------------------------------------------------------------------*/
unsigned short offset;
unsigned long value;
} /*----------------------------------------------------------------------*/
TPRO_MemObj;
/***************************************************************************
ERROR CODES
***************************************************************************/
#define TPRO_SUCCESS (0) // success
#define TPRO_HANDLE_ERR (1) // error creating handle to device
#define TPRO_OBJECT_ERR (2) // error creating device object
#define TPRO_CLOSE_HANDLE_ERR (3) // error closing device handle
#define TPRO_DEVICE_NOT_OPEN_ERR (4) // tpro device was not opened
#define TPRO_INVALID_BOARD_TYPE_ERR (5) // function is not available for board type
#define TPRO_FREQ_ERR (6) // invalid frequency
#define TPRO_YEAR_PARM_ERR (7) // invalid year parameter
#define TPRO_DAY_PARM_ERR (8) // invalid day parameter
#define TPRO_HOUR_PARM_ERR (9) // invalid hour parameter
#define TPRO_MIN_PARM_ERR (10) // invalid minutes parameter
#define TPRO_SEC_PARM_ERR (11) // invalid seconds parameter
#define TPRO_DELAY_PARM_ERR (12) // invalid delay factor
#define TPRO_TIMEOUT_ERR (13) // device timed out
#define TPRO_COMM_ERR (14) // error communicating with driver
#define TPRO_DEV_BUSY (15) // The driver is currently busy executing a request
from a different user
/***************************************************************************
PUBLIC ROUTINE PROTOTYPES
***************************************************************************/
DLL_EXPORT
unsigned char TPRO_open (TPRO_BoardObj **hnd, char *deviceName);
DLL_EXPORT
unsigned char TPRO_close (TPRO_BoardObj *hnd);
DLL_EXPORT
Synchronizable Timecode Generator Application Programmer’s Guide
Page 17
Spectracom Corporation TPRO-PCI-U/TSAT-PCI-U — Windows Driver
3-5
unsigned char TPRO_flushFIFO (TPRO_BoardObj *hnd);
DLL_EXPORT
unsigned char TPRO_getAltitude (TPRO_BoardObj *hnd, TPRO_AltObj *Altp);
DLL_EXPORT
unsigned char TPRO_getDate (TPRO_BoardObj *hnd, TPRO_DateObj *Datep);
DLL_EXPORT
unsigned char TPRO_getDriver (TPRO_BoardObj *hnd, char *driver);
DLL_EXPORT
unsigned char TPRO_getFirmware (TPRO_BoardObj *hnd, char *firmware);
DLL_EXPORT
unsigned char TPRO_getFPGA (TPRO_BoardObj *hnd, char *fpga);
DLL_EXPORT
unsigned char TPRO_getLatitude (TPRO_BoardObj *hnd, TPRO_LatObj *Latp);
DLL_EXPORT
unsigned char TPRO_getLongitude (TPRO_BoardObj *hnd, TPRO_LongObj *Longp);
DLL_EXPORT
unsigned char TPRO_getSatInfo (TPRO_BoardObj *hnd, TPRO_SatObj *Satp);
DLL_EXPORT
unsigned char TPRO_getTime (TPRO_BoardObj *hnd, TPRO_TimeObj *Timep);
DLL_EXPORT
unsigned char TPRO_resetFirmware (TPRO_BoardObj *hnd);
DLL_EXPORT
unsigned char TPRO_setHeartbeat (TPRO_BoardObj *hnd, TPRO_HeartObj *Heartp);
DLL_EXPORT
unsigned char TPRO_setMatchTime (TPRO_BoardObj *hnd, TPRO_MatchObj *Matchp);
DLL_EXPORT
unsigned char TPRO_setOscillator (TPRO_BoardObj *hnd, unsigned char *freq);
DLL_EXPORT
unsigned char TPRO_setPropDelayCorr (TPRO_BoardObj *hnd, int *us);
DLL_EXPORT
unsigned char TPRO_setTime (TPRO_BoardObj *hnd, TPRO_TimeObj *Timep);
DLL_EXPORT
unsigned char TPRO_setYear (TPRO_BoardObj *hnd, unsigned short *yr);
DLL_EXPORT
unsigned char TPRO_simEvent (TPRO_BoardObj *hnd);
DLL_EXPORT
unsigned char TPRO_synchControl (TPRO_BoardObj *hnd, unsigned char *enbp);
DLL_EXPORT
unsigned char TPRO_synchStatus (TPRO_BoardObj *hnd, unsigned char *status);
DLL_EXPORT
unsigned char TPRO_waitEvent (TPRO_BoardObj *hnd, TPRO_WaitObj *waitp);
DLL_EXPORT
unsigned char TPRO_waitHeartbeat (TPRO_BoardObj *hnd, unsigned int *ticks);
DLL_EXPORT
unsigned char TPRO_waitMatch (TPRO_BoardObj *hnd, unsigned int *ticks);
DLL_EXPORT
unsigned char TPRO_peek (TPRO_BoardObj *hnd, TPRO_MemObj *Mem);
Synchronizable Timecode Generator Application Programmer’s Guide
Page 18
TPRO-PCI-U/TSAT-PCI-U — Windows Driver Spectracom Corporation
3-6
DLL_EXPORT
unsigned char TPRO_poke (TPRO_BoardObj *hnd, TPRO_MemObj *Mem);
#ifdef __cplusplus
}
#endif
#pragma pack()
#endif // _defined_TPRO_
Synchronizable Timecode Generator Application Programmer’s Guide
Page 19
Spectracom Corporation TPRO-PCI-U/TSAT-PCI-U — Windows Driver
3-7
3.2 TPRO API — Routine Descriptions
The TPRO-PCI driver permits overlapping use of the TPRO-waitXXX routines and other device
access routines.
NOTE: Simultaneous access to the device requires multiple open device handles. (If an
application requires access to the device driver from two different threads, each thread
must have its own device handle.)
3.2.1.1.1 TPRO_open
unsigned char TPRO_open (TPRO_BoardObj **hnd, char *deviceName);
This routine allocates a TPRO_BoardObj obect, sets a handle to the TPRO/TSAT, and sets the
driver firmware, fpga revision (if applicable), and the driver revision strings.
Arguments: Pointer to TPRO_BoardObj handle
Device name - "TPROpci0"
Returns: TPRO_OBJECT_ERR – error allocating board object
TPRO_HANDLE_ERR – error retrieving handle to device
TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
3.2.1.1.2 TPRO_close
unsigned char TPRO_close (TPRO_BoardObj *hnd);
This routine frees the allocated board object and closes the handle to the TPRO/TSAT device.
Arguments: Pointer to TPRO_BoardObj
Returns: TPRO_CLOSE_HANDLE_ERR – error closing handle to device
TPRO_DEVICE_NOT_OPEN - device is not open
TPRO_SUCCESS - success
3.2.1.1.3 TPRO_getAltitude
unsigned char TPRO_getAltitude (TPRO_BoardObj *hnd, TPRO_AltObj *Altp);
This routine retrieves the altitude information from the TSAT board. Altitude distance is in
meters.
Arguments: Pointer to TPRO_BoardObj
Pointer to TPRO_AltObj
Returns: TPRO_INVALID_BOARD_TYPE_ERR – invalid board type for function
TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
Synchronizable Timecode Generator Application Programmer’s Guide
Page 20
TPRO-PCI-U/TSAT-PCI-U — Windows Driver Spectracom Corporation
3-8
3.2.1.1.4 TPRO_getDate
unsigned char TPRO_getDate (TPRO_BoardObj *hnd, TPRO_DateObj *Datep);
This routine retrieves the current date from the TPRO/TSAT board. The date is in Gregorian
Format.
Arguments: Pointer to TPRO_BoardObj
Pointer to TPRO_DateObj
Returns: TPRO_INVALID_BOARD_TYPE_ERR – invalid board type for function
TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
3.2.1.1.5 TPRO_getLatitude
unsigned char TPRO_getLattitude(TPRO_BoardObj *hnd, TPRO_LatObj *Latp);
This routine retrieves the latitude information from the TSAT device.
Arguments: Pointer to TPRO_BoardObj
Pointer to TPRO_LatObj
Returns: TPRO_INVALID_BOARD_TYPE_ERR – invalid board type for function
TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
3.2.1.1.6 TPRO_getLongitude
unsigned char TPRO_getLongitude(TPRO_BoardObj *hnd, TPRO_LongObj *Longp);
This routine retrieves the longitude information from the TSAT device.
Arguments: Pointer to the TPRO_BoardObj
Pointer to the TPRO_LongObj
Returns: TPRO_INVALID_BOARD_TYPE_ERR – invalid board type for function
TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
Synchronizable Timecode Generator Application Programmer’s Guide
Page 21
Spectracom Corporation TPRO-PCI-U/TSAT-PCI-U — Windows Driver
3-9
3.2.1.1.7 TPRO_getSatInfo
unsigned char TPRO_getSatInfo(TPRO_BoardObj *hnd, TPRO_SatObj *Satp);
This routine retrieves the number of satellites tracked from the TSAT device.
Arguments: Pointer to the TPRO_BoardObj
Pointer to the TPRO_SatObj
Returns: TPRO_INVALID_BOARD_TYPE_ERR – invalid board type for function
TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
3.2.1.1.8 TPRO_getTime
unsigned char TPRO_getTime(TPRO_BoardObj *hnd, TPRO_TimeObj *Timep);
This routine retrieves the current time from the TPRO/TSAT device. The seconds value is
received as type double.
Arguments: Pointer to the TPRO_BoardObj
Pointer to the TPRO_TimeObj
Returns: TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
3.2.1.1.9
3.2.1.1.10 TPRO_resetFirmware
unsigned char TPRO_resetFirmware(TPRO_BoardObj *hnd);
This routine resets the firmware programmed on the TPRO/TSAT device. This function is for
troubleshooting purposes only and should not be used in the main application.
Arguments: Pointer to the TPRO_BoardObj
Returns: TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
Synchronizable Timecode Generator Application Programmer’s Guide
Page 22
TPRO-PCI-U/TSAT-PCI-U — Windows Driver Spectracom Corporation
3-10
3.2.1.1.11 TPRO_setHeartbeat
unsigned char TPRO_setHeartbeat(TPRO_BoardObj *hnd, TPRO_HeartObj *Heartp);
This routine controls the hearbeat output. The heartbeat output may be a square wave or pulse
at various frequencies.
Arguments: Pointer to the TPRO_BoardObj
Pointer to the TPRO_HeartObj
Returns: TPRO_FREQ_ERR – invalid frequency value
TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
3.2.1.1.12 TPRO_setMatchTime
unsigned char TPRO_setMatchTime(TPRO_BoardObj *hnd, TPRO_MatchObj *Matchp);
This routine drives the match output line high (start time) or low (stop time) when the desired
time is met.
Arguments: Pointer to the TPRO_BoardObj
Pointer to the TPRO_MatchObj
Returns: TPRO_DAY_PARM_ERR - invalid days parameter (must be 0-366)
TPRO_HOUR_PARM_ERR – invalid hours parameter (must be 0 – 23)
TPRO_MIN_PARM_ERR - invalid minutes parameter (must be 0 – 59)
TPRO_SEC_PARM_ERR - invalid seconds paramter (must be 0 – 69)
TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
3.2.1.1.13 TPRO_setPropDelayCorr
unsigned char TPRO_setPropDelayCorr (TPRO_BoardObj *hnd, int *us);
This routine sets the propagation delay correction factor.
Arguments: Pointer to the TPRO_BoardObj
Pointer to correction factor in microseconds
Returns: TPRO_DELAY_PARM_ERR – invalid propagation delay factor
TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
Synchronizable Timecode Generator Application Programmer’s Guide
Page 23
Spectracom Corporation TPRO-PCI-U/TSAT-PCI-U — Windows Driver
3-11
3.2.1.1.14 TPRO_setTime
unsigned char TPRO_setTime(TPRO_BoardObj *hnd, TPRO_TimeObj *Timep);
This routine sets the time on the on-board clock of the TPRO/TSAT device. If the board is
synchronized to a GPS antenna this value will not be accepted.
Arguments: Pointer to the TPRO_BoardObj
Pointer to the TPRO_TimeObj
Returns: TPRO_DAY_PARM_ERR - invalid days parameter (must be 0-366)
TPRO_HOUR_PARM_ERR – invalid hours parameter (must be 0 – 23)
TPRO_MIN_PARM_ERR - invalid minutes parameter (must be 0 – 59)
TPRO_SEC_PARM_ERR - invalid seconds paramter (must be 0 – 69)
TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
3.2.1.1.15 TPRO_setYear
unsigned char TPRO_setYear(TPRO_BoardObj *hnd, unsigned short *yr);
This routine programs the TPRO/TSAT device with the desired year. If the board is
synchronized to a GPS antenna this value will not be accepted.
Arguments: Pointer to the TPRO_BoardObj
Pointer to the desired year
Returns: TPRO_INVALID_BOARD_TYPE_ERR – invalid board type for function
TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
3.2.1.1.16 TPRO_simEvent
unsigned char TPRO_simEvent(TPRO_BoardObj *hnd);
This routine simulates an external time tag event.
Arguments: Pointer to the TPRO_BoardObj
Returns: TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
Synchronizable Timecode Generator Application Programmer’s Guide
Page 24
TPRO-PCI-U/TSAT-PCI-U — Windows Driver Spectracom Corporation
3-12
3.2.1.1.17 TPRO_synchControl
unsigned char TPRO_synchControl(TPRO_BoardObj *hnd, unsigned char *enbp);
This routine commands the TPRO/TSAT device to synchronize to input or freewheel. This
distinction is made using the enable argument. If the enable argument is (0) the clock will
freewheel, otherwise it will synchronize to input. When disabling synchronization (freewheeling),
the device will continue to synchronize until the time is set.
Arguments: Pointer to the TPRO_BoardObj
Pointer to the synch enable
Returns: TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
3.2.1.1.18 TPRO_synchStatus
unsigned char TPRO_synchStatus(TPRO_BoardObj *hnd, unsigned char *status);
This routine reports the synchronization status of the TPRO/TSAT device. When status is equal
to zero, the device is freewheeling. Otherwise the device is synchronized to its input.
Arguments: Pointer to the TPRO_BoardObj
Pointer to the synch status variable
Returns: TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
3.2.1.1.19 TPRO_waitEvent
unsigned char TPRO_waitEvent(TPRO_BoardObj *hnd, TPRO_WaitObj*waitp);
This routine will report the time an external event was detected on the Time Tag Input pin. The
routine will block for a given number of ticks (in milliseconds) until an event occurs or the timeout
period has been reached.
Arguments: Pointer to the TPRO_BoardObj
Pointer to wait time
Returns: TPRO_TIMEOUT_ERR – routine has timed-out
TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
Synchronizable Timecode Generator Application Programmer’s Guide
Page 25
Spectracom Corporation TPRO-PCI-U/TSAT-PCI-U — Windows Driver
3-13
3.2.1.1.20 TPRO_waitHeartbeat
unsigned char TPRO_waitHeartbeat(TPRO_BoardObj *hnd, unsigned int *ticks);
This routine will reports the condition of the heartbeat output. The routine will block for a given
number of ticks (in milliseconds) until a heartbeat occurs or the timeout period has been
reached.
Arguments: Pointer to the TPRO_BoardObj
Pointer to timeout variable in milliseconds
Returns: TPRO_TIMEOUT_ERR – routine has timed-out
TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
3.2.1.1.21 TPRO_waitMatch
unsigned char TPRO_waitMatch(TPRO_BoardObj *hnd, unsigned int *ticks);
This routine will reports the condition of the match start time. The routine will block for a given
number of ticks (in milliseconds) until a match start time occurs or the timeout period has been
reached.
Arguments: Pointer to the TPRO_BoardObj
Pointer to wait time
Returns: TPRO_TIMEOUT_ERR – routine has timed-out
TPRO_COMM_ERR - error communicating with driver
TPRO_SUCCESS - success
Synchronizable Timecode Generator Application Programmer’s Guide
Page 26
TPRO-PCI-U/TSAT-PCI-U — Windows Driver Spectracom Corporation
3-14
Synchronizable Timecode Generator Application Programmer’s Guide
Page 27
Spectracom Corporation TPRO-PCI-U/TSAT-PCI-U — Windows Driver
3-15
Document Revision History
Rev
ECN
Description
Date
A
2325
First draft of Spectracom documentation for this product.
B 2332
Minor corrections.
C
2552
Added 32/64-bit Lib/DLL comments. Added Windows 7 support
comment. Other minor corrections.
December 2010
Synchronizable Timecode Generator Application Programmer’s Guide
Page 28
Spectracom Corporation
95 Methodist Hill Drive
Rochester, NY 14623
www.spectracomcorp.com
Phone: US +1.585.321.5800
Fax: US +1.585.321.5219
Loading...