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 to para30.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.