|
TDCBase
|
Control and data acquisition functions for quTAG MC and quTAG HR. More...
#include "tdcdecl.h"Go to the source code of this file.
Macros | |
Size constants | |
| #define | TDC_QUTAG_CHANNELS 32 |
| Number of hardware input stop channels. | |
| #define | TDC_COINC_CHANNELS 59 |
| Number of internal event and coincidence counters. | |
Typedefs | |
| typedef Int32 | TDC_FeatureFlags |
| A combination of feature Flags. | |
Enumerations | |
| enum | TDC_DevType { DEVTYPE_QUTAG_MC, DEVTYPE_QUTAG_HR, DEVTYPE_NONE } |
| Type of the TDC device. More... | |
| enum | TDC_FeatureFlag { FEATURE_HBT = 0x0001, FEATURE_LIFETIME = 0x0002, FEATURE_MARKERS = 0x0020, FEATURE_FILTERS = 0x0040, FEATURE_EXTCLK = 0x0080, FEATURE_DEVSYNC = 0x0100 } |
| Bitmasks for feature inquiry. | |
| enum | TDC_FileFormat { FORMAT_ASCII, FORMAT_BINARY, FORMAT_COMPRESSED, FORMAT_RAW, FORMAT_NONE } |
| Output file format. More... | |
| enum | TDC_SignalCond { SCOND_LVTTL = 1, SCOND_NIM = 2, SCOND_MISC = 3, SCOND_NONE = 4 } |
| Type of signal conditioning. More... | |
| enum | TDC_FilterType { FILTER_NONE, FILTER_MUTE, FILTER_COINC, FILTER_SYNC, FILTER_INVALID } |
| Type of output filter. More... | |
| enum | TDC_SimType { SIM_FLAT, SIM_NORMAL, SIM_NONE } |
| Type of generated timestamps. More... | |
Functions | |
| TDC_API double TDC_CC | TDC_getVersion () |
| Get Library Version. More... | |
| TDC_API const char *TDC_CC | TDC_perror (int rc) |
| Get Error Message. More... | |
| TDC_API int TDC_CC | TDC_getTimebase (double *timebase) |
| Get Time Base. More... | |
| TDC_API int TDC_CC | TDC_init (int deviceId) |
| Initialize and Start. More... | |
| TDC_API int TDC_CC | TDC_deInit () |
| Disconnect and uninitialize. More... | |
| TDC_API TDC_DevType TDC_CC | TDC_getDevType () |
| Get type of connected device. More... | |
| TDC_API Bln32 TDC_CC | TDC_checkFeatureHbt () |
| Check for HBT feature. More... | |
| TDC_API Bln32 TDC_CC | TDC_checkFeatureLifeTime () |
| Check for lifetime feature. More... | |
| TDC_API TDC_FeatureFlags TDC_CC | TDC_checkFeatures () |
| Check for device features. More... | |
| TDC_API Int32 TDC_CC | TDC_getChannelCount () |
| Get number of channels. More... | |
| TDC_API int TDC_CC | TDC_getClockState (Bln32 *locked, Bln32 *uplink) |
| Inquire Clock Sync State. More... | |
| TDC_API int TDC_CC | TDC_enableExternalClock (Bln32 enable) |
| Configure external clock. More... | |
| TDC_API int TDC_CC | TDC_disableClockReset (Bln32 disable) |
| Disable Start Input Clock Reset. More... | |
| TDC_API int TDC_CC | TDC_getClockResetDisabled (Bln32 *disabled) |
| Read back Clock Reset Mode. More... | |
| TDC_API int TDC_CC | TDC_preselectSingleStop (Bln32 single) |
| Preselect histogram mode. More... | |
| TDC_API int TDC_CC | TDC_getSingleStopPreselection (Bln32 *single) |
| Preselection mode. More... | |
| TDC_API int TDC_CC | TDC_startCalibration () |
| Internal Calibration. More... | |
| TDC_API int TDC_CC | TDC_getCalibrationState (Bln32 *active) |
| Inquire Calibration State. More... | |
| TDC_API int TDC_CC | TDC_enableChannels (Bln32 enStart, Int32 channelMask) |
| Enable TDC Channels. More... | |
| TDC_API int TDC_CC | TDC_getChannelsEnabled (Bln32 *enStart, Int32 *channelMask) |
| Retrieve active channels. More... | |
| TDC_API int TDC_CC | TDC_enableMarkers (Int32 markerMask) |
| Enable Markers. More... | |
| TDC_API int TDC_CC | TDC_getMarkersEnabled (Int32 *markerMask) |
| Retrieve active markers. More... | |
| TDC_API int TDC_CC | TDC_configureSignalConditioning (Int32 channel, TDC_SignalCond conditioning, Bln32 edge, double threshold) |
| Configure Signal Conditioning. More... | |
| TDC_API int TDC_CC | TDC_getSignalConditioning (Int32 channel, Bln32 *edge, double *threshold) |
| Read back Signal Conditioning Parameters. More... | |
| TDC_API int TDC_CC | TDC_configureSyncDivider (Int32 divider, Bln32 reconstruct) |
| Configure Start Input Divider. More... | |
| TDC_API int TDC_CC | TDC_getSyncDivider (Int32 *divider, Bln32 *reconstruct) |
| Read back Start Input Divider. More... | |
| TDC_API int TDC_CC | TDC_setCoincidenceWindow (Int32 coincWin) |
| Set Coincidence Window. More... | |
| TDC_API int TDC_CC | TDC_configureFilter (Int32 channel, TDC_FilterType type, Int32 chMask) |
| Configure Output Filter. More... | |
| TDC_API int TDC_CC | TDC_getFilter (Int32 channel, TDC_FilterType *type, Int32 *chMask) |
| Read back Output Filters. More... | |
| TDC_API int TDC_CC | TDC_setExposureTime (Int32 expTime) |
| Set Exposure Time. More... | |
| TDC_API int TDC_CC | TDC_getDeviceParams (Int32 *coincWin, Int32 *expTime) |
| Read Back Device Parameters. More... | |
| TDC_API int TDC_CC | TDC_setChannelDelay (Int32 channel, Int32 delay) |
| Set Channel Delay Time. More... | |
| TDC_API int TDC_CC | TDC_getChannelDelay (Int32 channel, Int32 *delay) |
| Read back Channel Delay Time. More... | |
| TDC_API int TDC_CC | TDC_configureSelftest (Int32 channelMask, Int32 period, Int32 burstSize, Int32 burstDist) |
| Configure Selftest. More... | |
| TDC_API int TDC_CC | TDC_getDataLost (Bln32 *lost) |
| Check for data loss. More... | |
| TDC_API int TDC_CC | TDC_setTimestampBufferSize (Int32 size) |
| Set Timestamp Buffer Size. More... | |
| TDC_API int TDC_CC | TDC_getTimestampBufferSize (Int32 *size) |
| Read back Timestamp Buffer Size. More... | |
| TDC_API int TDC_CC | TDC_enableTdcInput (Bln32 enable) |
| Enable Physical Input. More... | |
| TDC_API int TDC_CC | TDC_freezeBuffers (Bln32 freeze) |
| Freeze internal Buffers. More... | |
| TDC_API int TDC_CC | TDC_getCoincCounters (Int32 *data, Int32 *updates) |
| Retrieve Coincidence Counters. More... | |
| TDC_API int TDC_CC | TDC_getLastTimestamps (Bln32 reset, Int64 *timestamps, Uint8 *channels, Int32 *valid) |
| Retrieve Last Timestamp Values. More... | |
| TDC_API int TDC_CC | TDC_writeTimestamps (const char *filename, TDC_FileFormat format) |
| Write Timestamp Values to File. More... | |
| TDC_API int TDC_CC | TDC_inputTimestamps (const Int64 *timestamps, const Uint8 *channels, Int32 count) |
| Input Synthetic Timestamps. More... | |
| TDC_API int TDC_CC | TDC_readTimestamps (const char *filename, TDC_FileFormat format) |
| Read Timestamps. More... | |
| TDC_API int TDC_CC | TDC_generateTimestamps (TDC_SimType type, double *par, Int32 count) |
| Generate Timestamps. More... | |
Control and data acquisition functions for quTAG MC and quTAG HR.
The header defines functions that allow to control the quTAG time-to-digital converter (TDC) and acquire data from it. The received timestamp data can be retrieved programatically or stored in a file. They are also processed to a set of histograms internally.
Use TDC_init to start and connect to the device and TDC_deInit to close the connection. Set device parameters with TDC_setExposureTime etc. and enable Measurement with TDC_enableChannels. Customize the timestamp buffer with TDC_setTimestampBufferSize and retrieve timestamps with TDC_getLastTimestamps or TDC_writeTimestamps.
TDC_inputTimestamps, TDC_readTimestamps, and TDC_generateTimestamps allow to work with generated or saved timestamps. Interference with real data from the device should be avoided (see TDC_enableTdcInput).
If no device is connected, the library falls into a demo mode where all parameter setting and getting calls return without error.
Definition in file tdcbase.h.
| enum TDC_DevType |
| enum TDC_FileFormat |
| enum TDC_FilterType |
| enum TDC_SignalCond |
| enum TDC_SimType |
Type of generated timestamps.
Check for HBT feature.
Checks if the HBT feature is available for the connected device. This feature is necessary to use the functions of tdchbt.h .
Check for lifetime feature.
Checks if the Lifetime feature is available for the connected device. This feature is necessary to use the functions of tdclifetm.h .
| TDC_API TDC_FeatureFlags TDC_CC TDC_checkFeatures | ( | ) |
Check for device features.
Retreives all available device features.
| TDC_API int TDC_CC TDC_configureFilter | ( | Int32 | channel, |
| TDC_FilterType | type, | ||
| Int32 | chMask | ||
| ) |
Configure Output Filter.
Configures a filter for the output (and data transfer) of time tags. Filtered events are registered by the device and processed for coincidence detection, but not transferred to the PC. Filters are implemented only for five channels.
| channel | Number of the input channel to configure, 1..5. Channel 0 (Start) can't be filtered. |
| type | Type of the filter. By default, no filter is active. |
| chMask | Bitfield to select stop channels for "Coinc" and "Sync" filters. (e.g. 6 means correlate with channels 2 and 4). Channel 0 (Start) can't be used here. |
| TDC_API int TDC_CC TDC_configureSelftest | ( | Int32 | channelMask, |
| Int32 | period, | ||
| Int32 | burstSize, | ||
| Int32 | burstDist | ||
| ) |
Configure Selftest.
The function enables the generation of test signals in the device.
| channelMask | Bitfield that selects the stop channels to be fired internally (e.g. 5 means signal generation on channels 1 and 3) |
| period | Period of all test singals in units of 4ns, Range = 2 ... 100 |
| burstSize | Number of periods in a burst, Range = 1 ... 1000 |
| burstDist | Distance between bursts in units of 16ns, Range = 2 ... 10000 |
| TDC_API int TDC_CC TDC_configureSignalConditioning | ( | Int32 | channel, |
| TDC_SignalCond | conditioning, | ||
| Bln32 | edge, | ||
| double | threshold | ||
| ) |
Configure Signal Conditioning.
Configures a channel's signal conditioning. Primarily, a conditioning type is selected. Depending on the type, the detailed settings may be relevant or ignored by the function, see TDC_SignalCond. For full access to the details use SCOND_MISC as type.
| channel | Number of the input channel to configure, 0=Start |
| conditioning | Type of signal conditioning. By default it is SCOND_MISC |
| edge | Selects the signal edge that is processed as an event: rising (1, default) or falling (0) |
| threshold | Voltage threshold that is used to identify events, in V. Allowed range: -2 ... 3V; default value: 1V; internal resolution: 1.47mV |
Configure Start Input Divider.
Configures the input divider of the start channel. The function is only available for quTAG HR.
| divider | Number of events to skip before one is passed + 1. Only the following values are allowed: 1, 2, 4, 8 |
| reconstruct | Reconstruct the skipped events in software. |
Disconnect and uninitialize.
Disconnects a connected device and stops the internal event loop.
Disable Start Input Clock Reset.
The function allows to disable the clock reset. By default, the start input of the device is used to reset the internal clock. Those events themselves are not transmitted to the PC. If disabled, the start input works as a ordinary stop channel. The clock is never resetted. The feature is only available for quTAG HR.
| disable | Disable (true) or enable (false) the clock reset. |
Enable TDC Channels.
Selects the stop channels that contribute to the timestamp output stream. Bit 0 enables stop channel 1 etc.
| enStart | Enable the start channel |
| channelMask | Bitfield with activation flags for every TDC stop channel. (e.g. 5 means activate channels 1 and 3) |
Configure external clock.
Allows to use the external clock.
| enable | Disable(false) or enable (true) the external clock. |
Enable Markers.
The markers are low resolution timestamps triggered over the GPIO port. Markers 0-3 are triggerd by the rising edges of the signals, markers 5-9 by the falling edges. Marker 4 is a 1ms timer tick. If enabled, the Markers are included in timestamp protocol files with channel numbers 100-104 and 200-203. By default, all markers are deactivated. The function allows to enable or disable the single marker channels.
| markerMask | Bitfield with activation flags for every marker channel. (e.g. 5 means activate markers 0 and 2) |
Enable Physical Input.
Enables input from the physical channels of the TDC device or the internal selftest. If disabled, the software ignores those "real" events, the device and its coincidence counters are not affected. By default the input is enabled.
When working with software input (TDC_readTimestamps, TDC_generateTimestamps, ...) this function can be used to avoid real and simulated input to be mixed up.
| enable | Enable (1) or disable (0) TDC input |
Freeze internal Buffers.
The function can be used to freeze the internal buffers, allowing to retrieve multiple histograms with the same integration time. When frozen, no more events are added to the built-in histograms and timestamp buffer. The coincidence counters are not affected. Initially, the buffers are not frozen. All types of histograms calculated by software are affected.
| freeze | freeze (1) or activate (0) the buffers |
| TDC_API int TDC_CC TDC_generateTimestamps | ( | TDC_SimType | type, |
| double * | par, | ||
| Int32 | count | ||
| ) |
Generate Timestamps.
The function generates synthetic timestamps for demonstration and simulation purposes. Timesamps are processed just like "raw" data from a real device.
The channel mask (see TDC_enableChannels) is considered. At least one channel has to be enabled!
| type | Type of time diff distribution |
| par | Type specific parameter set. Parameters should be chosen so that most time diffs are positive. Negative diffs are dropped. |
| count | Number of timestamps to generate |
Inquire Calibration State.
Returns if the internal calibration is active, see TDC_startCalibration.
| active | output: if the calibration procedure is currently running |
Get number of channels.
Returns the number of hardware input channels, depending on the number of modules.
Read back Channel Delay Time.
Reads back the delay time as set with TDC_setChannelDelay.
| channel | Input Channel to read back, 0 for the start input |
| delay | Ouput: Delay [ps] |
Retrieve active channels.
Returns the channel mask as set with TDC_enableChannels.
| enStart | Output: If the start channel is enabled |
| channelMask | Output: Bitfield with activation flags. |
Read back Clock Reset Mode.
Returns if the clock reset by the start input is disabled, see TDC_disableClockReset. The feature is only available for quTAG HR.
| disabled | Output: Clock reset disabled (true) or enabled (false). |
Inquire Clock Sync State.
Returns the current state of clock synchronisation.
| locked | output: if the device's clock is locked to an external source (a downlink or an external clock input) |
| uplink | output: if a clock uplink to another device has been established |
Retrieve Coincidence Counters.
Retrieves the most recent values of the built-in coincidence counters. The coincidence counters are not accumulated, i.e. the counter values for the last exposure (see TDC_setExposureTime ) are returned.
The array contains count rates for all 32+1 channels, and rates for coincidences of events detected on the first 5 channels. Events are coincident if they happen within the coincidence window (see TDC_setCoincidenceWindow ).
| data | Output: Counter values. The array must have at least 59 elements. The counters come in the following order: Singles: 0(Start), 1, 2, ..., 32, Coincidences: 1/2, 1/3, 2/3, 1/4, 2/4, 3/4, 1/5, 2/5, 3/5, 4/5, 1/2/3, 1/2/4, 1/3/4, 2/3/4, 1/2/5, 1/3/5, 2/3/5, 1/4/5, 2/4/5, 3/4/5, 1/2/3/4, 1/2/3/5, 1/2/4/5, 1/3/4/5, 2/3/4/5, 1/2/3/4/5 |
| updates | Output: Number of data updates by the device since the last call. Pointer may be NULL. |
Check for data loss.
Timestamps of events detected by the device can get lost if their rate is too high for the USB interface or if the PC is unable to receive the data in time. The TDC recognizes this situation and signals it to the PC (with high priority).
The function checks if a data loss situation is currently detected or if it has been latched since the last call. If you are only interested in the current situation, call the function twice; the first call will delete the latch.
| lost | Output: Current and latched data loss state. |
Read Back Device Parameters.
Reads the device parameters back from the device. All Parameters are output parameters but may be NULL-Pointers if the result is not required.
| coincWin | Output: Coincidence window, see TDC_setCoincidenceWindow |
| expTime | Output: Exposure time, see TDC_setExposureTime |
| TDC_API TDC_DevType TDC_CC TDC_getDevType | ( | ) |
Get type of connected device.
Returns the type of the device connected. Requires initialisation.
| TDC_API int TDC_CC TDC_getFilter | ( | Int32 | channel, |
| TDC_FilterType * | type, | ||
| Int32 * | chMask | ||
| ) |
Read back Output Filters.
Reads back the output filtering parameters.
| channel | Number of the input channel to read out. |
| type | Type of the filter. |
| chMask | Bitfield to select channels for "Coinc" and "Sync" filters. |
| TDC_API int TDC_CC TDC_getLastTimestamps | ( | Bln32 | reset, |
| Int64 * | timestamps, | ||
| Uint8 * | channels, | ||
| Int32 * | valid | ||
| ) |
Retrieve Last Timestamp Values.
Retrieves the timestamp values of the last n detected events on all TDC channels. The buffer size must have been set with TDC_setTimestampBufferSize , otherwise 0 data will be returned.
| reset | If the data should be cleared after retrieving. |
| timestamps | Output: Timestamps of the last events in ps. The array must have at least size elements, see TDC_setTimestampBufferSize . A NULL pointer is allowed to ignore the data. |
| channels | Output: Numbers of the channels where the events have been detected. Every array element belongs to the timestamp with the same index. Range is 0...31 for channels 1...32. The array must have at least size elements, see TDC_setTimestampBufferSize . A NULL pointer is allowed to ignore the data. |
| valid | Output: Number of valid entries in the above arrays. May be less than the buffer size if the buffer has been cleared. |
Retrieve active markers.
Returns the marker mask as set with TDC_enableMarkers.
| markerMask | Output: Bitfield with activation flags. |
Read back Signal Conditioning Parameters.
Reads back the signal conditioning parameters. These are the parameters that are actually in effect, they may differ from those set by TDC_configureSignalConditioning in two cases:
| channel | Number of the input channel to read out, 0=Start. |
| edge | The signal edge that is processed as an event: rising (1) or falling (0) |
| threshold | Voltage threshold that is used to identify events, in V. |
Preselection mode.
Retrieves the histogram preselection mode as controlled by TDC_preselectSingleStop.
| single | Output: start stop (true) or start multistop (false) mode |
Read back Start Input Divider.
Reads back the input divider configuration of the start channel, see TDC_configureSyncDivider.
| divider | Output: Number of events to skip before one is passed + 1. |
| reconstruct | Output: Reconstruct the skipped events in software. |
Get Time Base.
Returns the time base (the resolution) of the TDC device. It is used as time unit by many other functions.
| timebase | Output: Time base in seconds |
Read back Timestamp Buffer Size.
Reads back the buffer size as set by TDC_setTimestampBufferSize.
| size | Output: Buffer size; |
Get Library Version.
Returns the version number of the library. The integer part of the number denotes main releases, the fractional part Bugfixes without API change.
Initialize and Start.
The function disconnects from any connected devices, initializes internal data and starts an event loop for data acquisition. It discovers devices connected to the computer, and connects to the first device that matches the given device ID. (The device ID is an identification number programmed by the user.)
The function should be called before any other TDC functions, except TDC_getVersion. Alternatively TDC_discover and TDC_connect can be used to handle multiple devices from one program.
If no device is found, the function returns TDC_NotConnected. If that error code is ignored, the library falls into a demo mode where all parameter setting and getting calls return without error.
| deviceId | Identification number of the device to connect. The special value -1 matches all devices. |
| TDC_API int TDC_CC TDC_inputTimestamps | ( | const Int64 * | timestamps, |
| const Uint8 * | channels, | ||
| Int32 | count | ||
| ) |
Input Synthetic Timestamps.
The function allows to input synthetic timestamps for demonstration and simulation purposes. Timesamps are processed just like "raw" data from a real device. is connected; otherwise it will return an error.
| timestamps | Input: Array of timestamps to process. The timestamps should be in strictly increasing order, otherwise some functions will fail. |
| channels | Input: Array of corresponding channel numbers. |
| count | Number of valid elements in both arrays. |
Get Error Message.
Returns the error message corresponding to the given return code.
| rc | A TDC return code |
Preselect histogram mode.
In four channel mode (with start input active) start events are not transferred to the PC. It therefore can't decide if a stop event is the first or a subsequent one following the start. This setting allows to produce valid start stop histograms even in four channel mode by filtering subsequent stops already in the device. Note that start multistop histograms (HBT and Lifetime features) will also be affected.
| single | preselect start stop (true) or start multistop histograms (false, default) |
| TDC_API int TDC_CC TDC_readTimestamps | ( | const char * | filename, |
| TDC_FileFormat | format | ||
| ) |
Read Timestamps.
The function allows to read timestamps from file for demonstration or delayed processing. It works only with files in a binary format (see TDC_FileFormat). It can read files with or without the 40 bytes header. When the header is present in demo mode (i.e. without a device connected), the HBT and Lifetime options from the source device come into effect.
In the compressed format, the reconstruction of the original timestamps can't be guaranteed. Detector delays (see TDC_setChannelDelay) are not compensated in this function because this is already done in TDC_writeTimestamps.
| filename | Name of the binary input file |
| format | Input format. Only binary formats are valid. If the file has a valid header, the parameter is not used; the format is retrieved from the file itself. |
Set Channel Delay Time.
Different signal runtimes cause relative delay times of the signals at different channels. The function allows to configure a delay per channel that will be compensated including the changed sorting of events. If not set, all delays are 0. The compensation is carried out in hardware.
| channel | Input channel to configure, 0 for the start input |
| delay | Delay Time [ps], Range = -50ns ... 50ns (quTAG MC); -100ns ... 100ns (quTAG HR) |
Set Coincidence Window.
Sets the coincidence time window for the integrated coincidence counting.
| coincWin | Coincidence window in ps, Range = 0 ... 2,000,000,000 |
Set Exposure Time.
Sets the exposure time (or integration time) of the internal coincidence counters.
| expTime | Exposure time in ms, Range = 0 ... 65535 |
Set Timestamp Buffer Size.
Sets the size of a ring buffer that stores the timestamps of the last detected events. The buffer's contents can be retrieved with TDC_getLastTimestamps. By default, the buffersize is 0. When the function is called, the buffer is cleared.
| size | Buffer size; Range = 1 ... 1000000 |
Internal Calibration.
Starts the internal calibration procedure. The procedure takes some seconds and can't be stopped. During calibration, no time tags output.
| TDC_API int TDC_CC TDC_writeTimestamps | ( | const char * | filename, |
| TDC_FileFormat | format | ||
| ) |
Write Timestamp Values to File.
Starts or stops writing the timestamp values to a file continously. The timestamps written are already corrected by the detector delays, see TDC_setChannelDelay.
Timestamps come in ps; channel numbers start with 0 in binary formats, with 1 in ASCII. A channel >= 100 is associated with marker input events: 100-103: rising edge, 105-108: falling edge, 104 is a millisecond tick. The follwing file formats are available:
The header of the binary formats is dedicated for use in TDC_readTimestamps; it should be skipped when evaluating with external tools.
Writing in the ASCII format requires much more CPU power and about twice as much disk space than using the binary format. The compressed format again saves half of the disk space, allowing higher event rates with not-so-fast disks. The Timestamps are truncated in this format leading to an overflow every 11 s. It is possible to convert a binary file to ASCII format offline by using this function together with TDC_readTimestamps.
If the specified file exists it will be overwritten. The function checks if the file can be opened; write errors that occur later in the actual writing process (disk full e.g.) will not be reported.
| filename | Name of the file to use. To stop writing, call the function with an empty or null filename. |
| format | Output format. Meaningless if writing is to be stopped. FORMAT_NONE also stops writing. |
1.8.10