Initialization of a device¶
To initialize (or “configure”) a device, the application must point the library to a configuration file, shipped as part of the product. This configuration file is typically named “tdc_gpx3.ini” and frequently referred to as the ini file. The ini file may contain references to other files (such as firmware files, calibration data and others). These files are best stored in the same folder as the ini file.
Initialization is done by calling sc_tdc_init_inifile()
with the name
of the ini file or the full path to that file.
Device descriptor¶
A call to sc_tdc_init_inifile()
returns a non-negative (>= 0) integer
if the initialization was successful. This number is referred to as a
device descriptor in the API of the library and must be used in all
other function calls related to the initialized device.
Error reporting¶
If initialization was not successful, a negative value – an error code –
is returned, indicating the reason of failure.
Error codes are listed in File scTDC_error_codes.h and their macro
names start with SC_TDC_ERR_
.
A human-readable, textual description of the error can be obtained
using the sc_get_err_msg()
function. Most other functions of the scTDC
library, if they return a signed integer type, indicate errors by returning
negative values that translate into textual descriptions via
sc_get_err_msg()
.
Initialization errors¶
Common error codes returned from sc_tdc_init_inifile()
and its
variants are
-9
(SC_TDC_ERR_BADCONFI
): either the specified ini file was not found, or it contained syntactic errors.-12
(SC_TDC_ERR_DEVCLS_LD
): secondary libraries were missing or did not have the right variant between 32-bit and 64-bit (see Requirements to the placement of files)-15
(SC_TDC_ERR_FPGA_INIT
): something went wrong inside the hardware while trying to initialize it. Resetting the hardware with a power cycle (power off + power on) may help. Providing the wrong firmware file can also lead to this error code.-98
(SC_TDC_ERR_NO_DEVICE
): no device was found. Is the device powered on and connected to the PC? Often there is a way to check hardware connectivity from the operating system (such as in the device manager of Windows for USB devices, or the Ethernet adapter dialog of Windows for Ethernet-based devices).
Requirements to the placement of files¶
This section is written with Windows as the operating system in mind:
An application that is linked to the scTDC library can only be started
if the library file scTDC1.dll
and a second dependent library
pthreadVC2.dll
are found, which can be ensured by putting these
files in the same folder as the application executable (*.exe
) file.
At the point where the application initializes the device, the scTDC library attempts to dynamically load secondary libraries, and read configuration files which should also be put into the folder of the application executable. In case of libraries, make sure to pick the right variant between 32-bit and 64-bit. The following is a list of files whose presence is required for the initialization step:
libraries related to the hardware interface (one of the following combinations)
scDeviceClass60.dll
,okFrontPanel.dll
(for USB TDCs)scDeviceClass450.dll
(for Ethernet interface)scDeviceClass6010.dll
,FTD3XX.dll
(for ReconFlexTM cameras)
if you have a ReconFlexTM camera product, the library
para3.dll
, (sometimes it must be renamed topara30.dll
).the configuration file
tdc_gpx3.ini
USB TDCs with a
scDeviceClass60.dll
require a firmware file with the*.bit
file name extension.if your demo software folder includes files
cal_i.tif
,cal_xyt.txt
, they should be copied to the folder of your application.
Missing secondary libraries result in an error code -12
(SC_TDC_ERR_DEVCLS_LD
) returned by the initialization function.
Overriding settings of the ini file by software¶
Of the parameters listed in the ini file, some can be changed after initializing the device, whereas others have to be set before initialization and cannot be changed afterwards. For the latter type, there are means to modify the parameter values by application code before initializing the device while leaving the original ini file untouched.
There are two options for overriding settings of the ini file. The
sc_ConfigLine
interface was the first available option. The newer
“override registry” interface is recommended for development of newer
applications.
sc_ConfigLine
interface¶
This interface requires application code to provide all entries of the
ini file in an array of sc_ConfigLine
structs. This may make it
necessary for the application code to parse the ini file. After
initialization of the device, there is no connection to any ini file on
hard disk which prevents live-tuning of certain ini file parameters
during sequences of measurements in the DebugLevel > 0
modes —
sometimes used for diagnosis and calibration.
Prepare an array of sc_ConfigLine
structs, then pass it into
sc_tdc_init_with_config_lines()
to initialize the device.
“override registry” interface¶
This interface enables initialization of a device from an ini file, as
usual, while replacing only a selected set of parameters with modified values.
After initialization, a connection to the ini file on hard disk remains
and live-tuning of ini file parameters in the DebugLevel > 0
modes is
possible.
Call sc_tdc_overrides_create()
to prepare a new override registry,
then add entries to it using sc_tdc_overrides_add_entry()
. Finally,
call sc_tdc_init_inifile_override()
to initialize the device. The
library copies the contents and associates them with the device descriptor.
After initialization, it is possible to close the override registry via
sc_tdc_overrides_close()
, to release its memory, while the overridden
values remain in effect for the initialized device.