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 :any:`sc_tdc_init_inifile` with the name of the ini file or the full path to that file. .. _DeviceDescriptorRef: Device descriptor ----------------- A call to :any:`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 :ref:`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 :any:`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 :any:`sc_get_err_msg`. Initialization errors --------------------- Common error codes returned from :any:`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 :ref:`ReqPlacementOfFilesRef`) * ``-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). .. _ReqPlacementOfFilesRef: 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 ReconFlex\ :sup:`TM` cameras) * if you have a ReconFlex\ :sup:`TM` 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 :any:`sc_ConfigLine` interface was the first available option. The newer "override registry" interface is recommended for development of newer applications. :any:`sc_ConfigLine` interface `````````````````````````````` This interface requires application code to provide **all entries** of the ini file in an array of :any:`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 :any:`sc_ConfigLine` structs, then pass it into :any:`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 :any:`sc_tdc_overrides_create` to prepare a new *override registry*, then add entries to it using :any:`sc_tdc_overrides_add_entry`. Finally, call :any:`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 :any:`sc_tdc_overrides_close`, to release its memory, while the overridden values remain in effect for the initialized device.