quDIS
|
Control and acquisition functions for quDIS. More...
Go to the source code of this file.
Data Structures | |
struct | QDS_QMeasure |
Signal quality measures. More... | |
Macros | |
Function declarations | |
Technical definitions, mainly for the Windows DLL interface. | |
#define | EXTC extern |
Storage class for C. | |
#define | WINCC __stdcall |
Calling convention for Windows. | |
#define | QDS_API EXTC __declspec(dllimport) |
For external use of this header. | |
Device constants | |
Properties of the quDIS | |
#define | QDS_AXES_CNT 3 |
Number of axes. | |
Return values of the functions | |
All functions of this lib - as far as they can fail - return one of these constants for success control. | |
#define | QDS_Ok 0 |
No error. | |
#define | QDS_Error -1 |
Unspecified error. | |
#define | QDS_Timeout 1 |
Communication timeout. | |
#define | QDS_NotConnected 2 |
No active connection to device. | |
#define | QDS_DriverError 3 |
Error in comunication with driver. | |
#define | QDS_DeviceLocked 7 |
Device is already in use by other. | |
#define | QDS_Unknown 8 |
Unknown error. | |
#define | QDS_NoDevice 9 |
Invalid device number in function call. | |
#define | QDS_NoAxis 10 |
Invalid axis number in function call. | |
#define | QDS_ParamOutOfRg 11 |
A parameter exceeds the allowed range. | |
quDIS feature flags | |
The flags describe optional features of the quDIS device. They are used by QDS_getDeviceConfig . | |
#define | QDS_FeatureAbsolute 0x01 |
"Absolute": abs. More... | |
Typedefs | |
typedef int | bln32 |
Boolean; to avoid troubles with incomplete C99 implementations. | |
typedef void(* | QDS_PositionCallback )(unsigned int devNo, unsigned int length, unsigned int index, const double *const positions[QDS_AXES_CNT], const Int32 *const markers[QDS_AXES_CNT]) |
Position callback function. More... | |
Enumerations | |
enum | QDS_InterfaceType { IfNone = 0x00, IfUsb3 = 0x10, IfTcp = 0x02, IfAll = 0x12 } |
Interface types. More... | |
enum | QDS_LCtlState { LcOk = 0x00, LcFail = 0x01, LcCalib = 0x02 } |
Laser wavelength control status. More... | |
enum | QDS_MrkMode { MrkOff = 0x00, Mrk1Cnt = 0x01, MrkNone = 0x02 } |
Marker modes. More... | |
Functions | |
QDS_API int WINCC | QDS_discover (QDS_InterfaceType ifaces, unsigned int *devCount) |
Discover devices. More... | |
QDS_API int WINCC | QDS_getDeviceInfo (unsigned int devNo, int *id, char *serialNo, char *address) |
Device information. More... | |
QDS_API int WINCC | QDS_registerExternalIp (const char *hostname) |
Register IP device in external Network. More... | |
QDS_API int WINCC | QDS_connect (unsigned int devNo) |
Connect device. More... | |
QDS_API int WINCC | QDS_disconnect (unsigned int devNo) |
Disconnect device. More... | |
QDS_API int WINCC | QDS_getDeviceConfig (unsigned int devNo, unsigned int *axisCount, int *features) |
Read device configuration. More... | |
QDS_API int WINCC | QDS_getLambdaControlState (unsigned int devNo, QDS_LCtlState *state) |
Get wavelength control status. More... | |
QDS_API int WINCC | QDS_setSampleTime (unsigned int devNo, unsigned int lbSampleTm) |
Set sample time. More... | |
QDS_API int WINCC | QDS_getSampleTime (unsigned int devNo, unsigned int *lbSampleTm) |
Read back sample time. More... | |
QDS_API int WINCC | QDS_resetRelPosition (unsigned int devNo, unsigned int axisNo) |
Reset relative position. More... | |
QDS_API int WINCC | QDS_getPositions (unsigned int devNo, double *positionsRel, double *positionsAbs) |
Read positions. More... | |
QDS_API int WINCC | QDS_estimateSignalQuality (unsigned int devNo, unsigned int axisNo, QDS_QMeasure *qData) |
Estimate signal quality. More... | |
QDS_API int WINCC | QDS_setPositionCallback (unsigned int devNo, QDS_PositionCallback cbRel, QDS_PositionCallback cbAbs) |
Register callback function. More... | |
QDS_API int WINCC | QDS_enableMarkers (unsigned int devNo, QDS_MrkMode mode, unsigned int timeout) |
Enable marker function. More... | |
QDS_API int WINCC | QDS_resetMarkerCounter (unsigned int devNo) |
Reset marker counter. More... | |
QDS_API int WINCC | QDS_setHsslParams (unsigned int devNo, unsigned int axisNo, bln32 enable, bln32 useLvds, unsigned int clock, unsigned int gap, unsigned int bits, unsigned int lbResol, unsigned int lbAvgTime) |
Set HSSL parameters. More... | |
QDS_API int WINCC | QDS_setQuadratureParams (unsigned int devNo, unsigned int axisNo, bln32 enable, bln32 zeroOnReset, unsigned int resolution, unsigned int clock, unsigned int lbAvgTime) |
Set quadrature parameters. More... | |
QDS_API int WINCC | QDS_enableAngularMode (unsigned int devNo, bln32 enable, unsigned int base1_2, unsigned int base1_3) |
Enable Angular Measurement. More... | |
Control and acquisition functions for quDIS.
Defines functions for connecting and controlling the quDIS device. The functions are not thread safe!
Definition in file qudis.h.
#define QDS_FeatureAbsolute 0x01 |
typedef void(* QDS_PositionCallback)(unsigned int devNo, unsigned int length, unsigned int index, const double *const positions[QDS_AXES_CNT], const Int32 *const markers[QDS_AXES_CNT]) |
Position callback function.
A function of this type can be registered as callback function for new position values with QDS_setPositionCallback. This mechanism allows to achieve much higher data rates than polling every single sample.
The position measurements are taken on a regular timebase, the results are buffered for a short time and packed together to fit the requirements of the transport medium. When the packet arrives at the PC, the callback function is called as soon as possible. If the PC cannot process the data fast enough, the delay between measurement and call will increase with the filling level of the device internal buffers. Data packets will get lost when the buffers are full.
markers returns the value of a counter that counts rising and falling level of an external input signal. See QDS_enableMarkers.
The index counts the data since the begin of the measurement, i.e. it is incremented from call to call by length. It also counts data that have been lost due to performance problems of the control PC. To avoid overflow, the index is resetted from time to time.
The buffers that contain the data are static and will be overwritten in the next call. It must not be free()'d or used by the application to store data.
devNo | Number of the device that produced the data |
length | Number of triples of position values |
index | Sequence number of the first position of the packet |
positions | Array of three pointers, pointing to arrays of positions [nm] of axes 1, 2, and 3. In angular mode (see QDS_enableAngularMode), arrays 2 and 3 contain angle values 1-2 and 1-3 in uDegrees. |
markers | Marker counter at the time of data acquisition |
enum QDS_InterfaceType |
enum QDS_LCtlState |
enum QDS_MrkMode |
Connect device.
Initializes and connects the selected device. This has to be done before any access to control variables or measured data.
devNo | Sequence number of the device |
Disconnect device.
Closes the connection to the device.
devNo | Sequence number of the device |
QDS_API int WINCC QDS_discover | ( | QDS_InterfaceType | ifaces, |
unsigned int * | devCount | ||
) |
Discover devices.
The function searches for connected QDS devices on USB and LAN and initializes internal data structures per device. Devices that are in use by another application or PC are not found. The function must be called before connecting to a device and must not be called as long as any devices are connected.
The number of devices found is returned. In subsequent functions, devices are identified by a sequence number that must be less than the number returned.
ifaces | Interfaces where devices are to be searched |
devCount | Output: number of devices found |
QDS_API int WINCC QDS_enableAngularMode | ( | unsigned int | devNo, |
bln32 | enable, | ||
unsigned int | base1_2, | ||
unsigned int | base1_3 | ||
) |
Enable Angular Measurement.
For angular measurement two right angled triangles are considered. The length of one cathetus is constant and known while the other cathetus is given by the difference of axis 1 and axis 2 (or axis 3, respectively) relative distances. In the angular mode, the smaller angles of both triangles are calculated and replace the relative distances of axes 2 and 3 while axis 1 stays unchanged.
devNo | Sequence number of the device |
enable | Enables / disables angular mode |
base1_2 | Baseline length of the first triangle (axes 1 vs. 2) [um] |
base1_3 | Baseline length of the second triangle (axes 1 vs. 3) [um] |
QDS_API int WINCC QDS_enableMarkers | ( | unsigned int | devNo, |
QDS_MrkMode | mode, | ||
unsigned int | timeout | ||
) |
Enable marker function.
The marker feature allows to correlate the measured positions with an external electrical trigger signal. The rising and falling edges are counted, the current counter value can be read out together with the corresponding positions. The marker counter is resetted automatically when the trigger level is low for the auto reset tim.
devNo | Sequence number of the device |
mode | Marker mode; currently only on or off |
timeout | Auto reset time [ms]; 0 for no auto reset |
QDS_API int WINCC QDS_estimateSignalQuality | ( | unsigned int | devNo, |
unsigned int | axisNo, | ||
QDS_QMeasure * | qData | ||
) |
Estimate signal quality.
Reads an estimated signal quality from the device. Currently, only the (normalized) interferogram contrast is available. Other quality related measures will be added.
devNo | Sequence number of the device |
axisNo | Axis number (0 ... 2) |
qData | Quality related Data Set |
QDS_API int WINCC QDS_getDeviceConfig | ( | unsigned int | devNo, |
unsigned int * | axisCount, | ||
int * | features | ||
) |
Read device configuration.
Reads static device configuration data
devNo | Sequence number of the device |
axisCount | Output: Number of enabled axes |
features | Output: Bitfield of enabled features, see QDS Feature Flags |
QDS_API int WINCC QDS_getDeviceInfo | ( | unsigned int | devNo, |
int * | id, | ||
char * | serialNo, | ||
char * | address | ||
) |
Device information.
Returns available information about a device. The function can not be called before QDS_discover but the devices don't have to be connected . All Pointers to output parameters may be zero to ignore the respective value.
devNo | Sequence number of the device |
id | Output: programmed hardware ID of the device |
serialNo | Output: The device's serial number. The string buffer should be NULL or at least 16 bytes long. |
address | Output: The device's interface address if applicable. Returns the IP address in dotted-decimal notation or the string "USB", respectively. The string buffer should be NULL or at least 16 bytes long. |
QDS_API int WINCC QDS_getLambdaControlState | ( | unsigned int | devNo, |
QDS_LCtlState * | state | ||
) |
Get wavelength control status.
Reads the status of the laser wavelength control. After starting, the device is calibrating the laser temperature for some time. In this time, no reliable position information is available. Caused by external influences, such as extreme environmental temperature, the wavelength control may fail to hold the wavelength.
devNo | Sequence number of the device |
state | Output: wavelength control status |
QDS_API int WINCC QDS_getPositions | ( | unsigned int | devNo, |
double * | positionsRel, | ||
double * | positionsAbs | ||
) |
Read positions.
Reads the measured positions of all axes at the same time. In angular mode (see QDS_enableAngularMode) the relative positions 2 and 3 are replaced by the respective angles.
devNo | Sequence number of the device |
positionsRel | Output: current relative positions [nm] of axes 1, 2, and 3, or position of axis 1 and angles 1-2, 1-3 [uDegrees]. The caller must provide an array of 3 Elements. |
positionsAbs | Output: current absolute positions [nm] of axes 1, 2, and 3. The caller must provide an array of 3 Elements. |
Read back sample time.
Reads the sample time as set by QDS_setSampleTime.
devNo | Sequence number of the device |
lbSampleTm | Output: Logarithmic sample time. The actual sample time is (40us * 2^lbSampleTm). |
Register IP device in external Network.
QDS_discover is able to find devices connected via TCP/IP in the same network segment, but it can't "look through" routers. To connect devices in external networks, reachable by routing, the IP addresses of those devices have to be registered prior to calling QDS_discover. The function registers one device and can be called several times.
The function will return QDS_Ok if the name resolution succeeds (QDS_NoDevice otherwise); it doesn't test if the device is reachable. Registered and reachable devices will be found by QDS_discover.
hostname | Hostname or IP Address in dotted decimal notation of the device to register. |
Reset marker counter.
The marker counter is reset to 0 or 1, depending on the current level of the trigger signal. This guarantees that the LSB of the marker counter always reflects the trigger signal level.
devNo | Sequence number of the device |
Reset relative position.
Sets the relative position value of the corresponding axes to 0.
devNo | Sequence number of the device |
axisNo | Axis number (0 ... 2) |
QDS_API int WINCC QDS_setHsslParams | ( | unsigned int | devNo, |
unsigned int | axisNo, | ||
bln32 | enable, | ||
bln32 | useLvds, | ||
unsigned int | clock, | ||
unsigned int | gap, | ||
unsigned int | bits, | ||
unsigned int | lbResol, | ||
unsigned int | lbAvgTime | ||
) |
Set HSSL parameters.
Sets parameters of the device's HSSL interface for an axis. The parameters are stored in the device and will be reloaded at the next start.
devNo | Sequence number of the device |
axisNo | Axis number (0 ... 2) |
enable | Enables / disables the interface. |
useLvds | Use LVDS output signals |
clock | Signal clock [40ns]. Range: 1 ... 64 (40ns ... 2.5us). |
gap | Pause between two values [number of clock ticks]. Range is 0 ... 63. |
bits | Number of Bits a single value consists of. Range: 8 ... 48. |
lbResol | Logarithmic physical distance represented by the least significant bit of the HSSL output. The resolution can be varied only in powers of two: resolution = 1pm * (2 ^ lbResol). Range: 0 ... 40 (1pm ... 1m) |
lbAvgTime | Logarithmic average time for transmited positions. The average time can be varied only in powers of two: time = 80ns * (2 ^ lbAvgTime). Range: 0 ... 15 (80ns ... 2.6ms) |
QDS_API int WINCC QDS_setPositionCallback | ( | unsigned int | devNo, |
QDS_PositionCallback | cbRel, | ||
QDS_PositionCallback | cbAbs | ||
) |
Register callback function.
Registers a callback function for a device that will be called when new position data are available. A callback function registered previously is unregistered. The feature requires an USB connection to the device; on ethernet the call will have no effect.
devNo | Sequence number of the device |
cbRel | Callback function for relative positions. Use NULL to unregister a function. |
cbAbs | Callback function for absolute positions. Use NULL to unregister a function. |
QDS_API int WINCC QDS_setQuadratureParams | ( | unsigned int | devNo, |
unsigned int | axisNo, | ||
bln32 | enable, | ||
bln32 | zeroOnReset, | ||
unsigned int | resolution, | ||
unsigned int | clock, | ||
unsigned int | lbAvgTime | ||
) |
Set quadrature parameters.
Sets parameters of the device's quadrature interface for an axis. The parameters are stored in the device and will be reloaded at the next start.
devNo | Sequence number of the device |
axisNo | Axis number (0 ... 2) |
enable | Enables / disables the interface. |
zeroOnReset | If the interface should transmit virtual displacements caused by resetting the axis. |
resolution | The displacement represented by a pair of edges [pm]. Allowed range is 1pm ... 1mm . |
clock | Signal clock [40ns]. The signal period is four times the clock time. Allowed range is 1 ... 32,767 (40ns ... 1.3ms). |
lbAvgTime | Logarithmic average time for transmited positions. The average time can be varied only in powers of two: time = 80ns * (2 ^ lbAvgTime). Range: 0 ... 15 (80ns ... 2.6ms). |
Set sample time.
Sets the sample time, i.e. the inverse frequency of position updates. Internally, the device is sampling with 25kHz and can calculate averages over powers of 2 of internal samples. The sample time affects relative and absolute positions of all axes.
devNo | Sequence number of the device |
lbSampleTm | Logarithmic sample time. The actual sample time will be (40us * 2^lbSampleTm). Range = 0...16 |