quDIS
Data Structures | Typedefs | Enumerations | Functions
qudis.h File Reference

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 __int32 Int32
 
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...
 

Detailed Description

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.

Macro Definition Documentation

#define QDS_FeatureAbsolute   0x01

"Absolute": abs.

distance measurement

Definition at line 108 of file qudis.h.

Typedef Documentation

typedef __int32 Int32

32-Bit-Integer fuer MSVC

Definition at line 67 of file qudis.h.

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.

Parameters
devNoNumber of the device that produced the data
lengthNumber of triples of position values
indexSequence number of the first position of the packet
positionsArray 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.
markersMarker counter at the time of data acquisition

Definition at line 183 of file qudis.h.

Enumeration Type Documentation

Interface types.

Enumerator
IfNone 

Device invalid / not connected.

IfUsb3 

Device connected via USB.

IfTcp 

Device connected via ethernet (TCP/IP)

IfAll 

All physical interfaces.

Definition at line 117 of file qudis.h.

Laser wavelength control status.

Enumerator
LcOk 

Wavelength under control.

LcFail 

Wavelength control failed.

LcCalib 

Temperature calibration is running.

Definition at line 126 of file qudis.h.

Marker modes.

Enumerator
MrkOff 

Marker feature off.

Mrk1Cnt 

One single marker input, with counter.

MrkNone 

Reserved for future marker modes.

Definition at line 134 of file qudis.h.

Function Documentation

QDS_API int WINCC QDS_connect ( unsigned int  devNo)

Connect device.

Initializes and connects the selected device. This has to be done before any access to control variables or measured data.

Parameters
devNoSequence number of the device
Returns
Error code
QDS_API int WINCC QDS_disconnect ( unsigned int  devNo)

Disconnect device.

Closes the connection to the device.

Parameters
devNoSequence number of the device
Returns
Error code
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.

Parameters
ifacesInterfaces where devices are to be searched
devCountOutput: number of devices found
Returns
Error code
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.

Parameters
devNoSequence number of the device
enableEnables / disables angular mode
base1_2Baseline length of the first triangle (axes 1 vs. 2) [um]
base1_3Baseline length of the second triangle (axes 1 vs. 3) [um]
Returns
Error code
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.

Parameters
devNoSequence number of the device
modeMarker mode; currently only on or off
timeoutAuto reset time [ms]; 0 for no auto reset
Returns
Error code
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.

Parameters
devNoSequence number of the device
axisNoAxis number (0 ... 2)
qDataQuality related Data Set
Returns
Error code
QDS_API int WINCC QDS_getDeviceConfig ( unsigned int  devNo,
unsigned int *  axisCount,
int *  features 
)

Read device configuration.

Reads static device configuration data

Parameters
devNoSequence number of the device
axisCountOutput: Number of enabled axes
featuresOutput: Bitfield of enabled features, see QDS Feature Flags
Returns
Error code
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.

Parameters
devNoSequence number of the device
idOutput: programmed hardware ID of the device
serialNoOutput: The device's serial number. The string buffer should be NULL or at least 16 bytes long.
addressOutput: 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.
Returns
Error code
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.

Parameters
devNoSequence number of the device
stateOutput: wavelength control status
Returns
Error code
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.

Parameters
devNoSequence number of the device
positionsRelOutput: 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.
positionsAbsOutput: current absolute positions [nm] of axes 1, 2, and 3. The caller must provide an array of 3 Elements.
Returns
Error code
QDS_API int WINCC QDS_getSampleTime ( unsigned int  devNo,
unsigned int *  lbSampleTm 
)

Read back sample time.

Reads the sample time as set by QDS_setSampleTime.

Parameters
devNoSequence number of the device
lbSampleTmOutput: Logarithmic sample time. The actual sample time is (40us * 2^lbSampleTm).
Returns
Error code
QDS_API int WINCC QDS_registerExternalIp ( const char *  hostname)

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.

Parameters
hostnameHostname or IP Address in dotted decimal notation of the device to register.
Returns
Error code. QDS_NoDevice means here that the hostname could not be resolved. A return code of 0 doesn't guarantee that the device is reachable.
QDS_API int WINCC QDS_resetMarkerCounter ( unsigned int  devNo)

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.

Parameters
devNoSequence number of the device
Returns
Error code
QDS_API int WINCC QDS_resetRelPosition ( unsigned int  devNo,
unsigned int  axisNo 
)

Reset relative position.

Sets the relative position value of the corresponding axes to 0.

Parameters
devNoSequence number of the device
axisNoAxis number (0 ... 2)
Returns
Error code
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.

Parameters
devNoSequence number of the device
axisNoAxis number (0 ... 2)
enableEnables / disables the interface.
useLvdsUse LVDS output signals
clockSignal clock [40ns]. Range: 1 ... 64 (40ns ... 2.5us).
gapPause between two values [number of clock ticks]. Range is 0 ... 63.
bitsNumber of Bits a single value consists of. Range: 8 ... 48.
lbResolLogarithmic 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)
lbAvgTimeLogarithmic 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)
Returns
Error code
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.

Parameters
devNoSequence number of the device
cbRelCallback function for relative positions. Use NULL to unregister a function.
cbAbsCallback function for absolute positions. Use NULL to unregister a function.
Returns
Error code
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.

Parameters
devNoSequence number of the device
axisNoAxis number (0 ... 2)
enableEnables / disables the interface.
zeroOnResetIf the interface should transmit virtual displacements caused by resetting the axis.
resolutionThe displacement represented by a pair of edges [pm]. Allowed range is 1pm ... 1mm .
clockSignal clock [40ns]. The signal period is four times the clock time. Allowed range is 1 ... 32,767 (40ns ... 1.3ms).
lbAvgTimeLogarithmic 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).
Returns
Error code
QDS_API int WINCC QDS_setSampleTime ( unsigned int  devNo,
unsigned int  lbSampleTm 
)

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.

Parameters
devNoSequence number of the device
lbSampleTmLogarithmic sample time. The actual sample time will be (40us * 2^lbSampleTm). Range = 0...16
Returns
Error code