LibTiePie  0.9.13
Library for interfacing TiePie engineering instruments

Description

Functions to control the SafeGround feature of an oscilloscope channel.

SafeGround is a system that connects the negative side of an oscilloscope input to the oscilloscope's ground and real time monitors the ground current of that input. This turns a differential input into a single ended input. When the ground current exceeds a selected value, the ground connection of the input is immediately opened, avoiding that the ground current becomes too large and causes damage.

An event can be generated to inform that the ground was disconnected, LIBTIEPIE_EVENTID_SCP_SAFEGROUNDERROR. See also Notifications.

SafeGround is not available for all instruments. Use ScpChHasSafeGround() to check whether SafeGround is available for your instrument.

By default SafeGround is disabled and the threshold current is set to 30 mA.

Functions

bool8_t ScpChHasSafeGround (LibTiePieHandle_t hDevice, uint16_t wCh)
 Check whether the specified channel has SafeGround. More...
 
bool8_t ScpChGetSafeGroundEnabled (LibTiePieHandle_t hDevice, uint16_t wCh)
 Check whether SafeGround is enabled for a specified channel. More...
 
bool8_t ScpChSetSafeGroundEnabled (LibTiePieHandle_t hDevice, uint16_t wCh, bool8_t bEnable)
 Enable or disable SafeGround for a specified channel. More...
 
double ScpChGetSafeGroundThresholdMin (LibTiePieHandle_t hDevice, uint16_t wCh)
 Get the minimum SafeGround threshold current for the specified channel. More...
 
double ScpChGetSafeGroundThresholdMax (LibTiePieHandle_t hDevice, uint16_t wCh)
 Get the maximum SafeGround threshold current for the specified channel. More...
 
double ScpChGetSafeGroundThreshold (LibTiePieHandle_t hDevice, uint16_t wCh)
 Get the actual SafeGround threshold current for the specified channel. More...
 
double ScpChSetSafeGroundThreshold (LibTiePieHandle_t hDevice, uint16_t wCh, double dThreshold)
 Set the SafeGround threshold current for the specified channel. More...
 

Function Documentation

bool8_t ScpChHasSafeGround ( LibTiePieHandle_t  hDevice,
uint16_t  wCh 
)

Check whether the specified channel has SafeGround.

Parameters
[in]hDeviceA device handle identifying the oscilloscope.
[in]wChThe channel number identifying the channel, 0 to ScpGetChannelCount() - 1.
Returns
BOOL8_TRUE if SafeGround is available, BOOL8_FALSE otherwise.
Status values
INVALID_CHANNEL The requested channel number is invalid.
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
Since
0.6
bool8_t ScpChGetSafeGroundEnabled ( LibTiePieHandle_t  hDevice,
uint16_t  wCh 
)

Check whether SafeGround is enabled for a specified channel.

Parameters
[in]hDeviceA device handle identifying the oscilloscope.
[in]wChThe channel number identifying the channel, 0 to ScpGetChannelCount() - 1.
Returns
BOOL8_TRUE if SafeGround is enabled, BOOL8_FALSE otherwise.
Status values
NOT_SUPPORTED The indicated channel does not have SafeGround.
INVALID_CHANNEL The requested channel number is invalid.
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
ScpChHasSafeGround
ScpChSetSafeGroundEnabled
Since
0.6
bool8_t ScpChSetSafeGroundEnabled ( LibTiePieHandle_t  hDevice,
uint16_t  wCh,
bool8_t  bEnable 
)

Enable or disable SafeGround for a specified channel.

When a SsfeGround is enabled and a ground current larger than the selected current threahold starts flowing, SafeGround is immediately disabled by the instrument. Remove the (wrong) ground connection before enabling SafeGround.

SafeGround can only be enabled or disabled when the scope is not performing a measurement.

Parameters
[in]hDeviceA device handle identifying the oscilloscope.
[in]wChThe channel number identifying the channel, 0 to ScpGetChannelCount() - 1.
[in]bEnableBOOL8_TRUE to enable SafeGround or BOOL8_FALSE to disable SafeGround.
Returns
BOOL8_TRUE if SafeGround is enabled, BOOL8_FALSE otherwise.
Status values
UNSUCCESSFUL A ground current larger than the selected threshold caused SafeGround to be disabled again, or the scope is measuring.
NOT_SUPPORTED The indicated channel does not have SafeGround.
INVALID_CHANNEL The requested channel number is invalid.
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
ScpChHasSafeGround
ScpChGetSafeGroundEnabled
Since
0.6
double ScpChGetSafeGroundThresholdMin ( LibTiePieHandle_t  hDevice,
uint16_t  wCh 
)

Get the minimum SafeGround threshold current for the specified channel.

Parameters
[in]hDeviceA device handle identifying the oscilloscope.
[in]wChThe channel number identifying the channel, 0 to ScpGetChannelCount() - 1.
Returns
Minimum SafeGround threshold current, in Ampere.
Status values
NOT_SUPPORTED The indicated channel does not have SafeGround.
INVALID_CHANNEL The requested channel number is invalid.
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
ScpChHasSafeGround
ScpChGetSafeGroundThresholdMax
ScpChGetSafeGroundThreshold
ScpChSetSafeGroundThreshold
Since
0.6
double ScpChGetSafeGroundThresholdMax ( LibTiePieHandle_t  hDevice,
uint16_t  wCh 
)

Get the maximum SafeGround threshold current for the specified channel.

Parameters
[in]hDeviceA device handle identifying the oscilloscope.
[in]wChThe channel number identifying the channel, 0 to ScpGetChannelCount() - 1.
Returns
Maximum SafeGround threshold current, in Ampere.
Status values
NOT_SUPPORTED The indicated channel does not have SafeGround.
INVALID_CHANNEL The requested channel number is invalid.
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
ScpChHasSafeGround
ScpChGetSafeGroundThresholdMin
ScpChGetSafeGroundThreshold
ScpChSetSafeGroundThreshold
Since
0.6
double ScpChGetSafeGroundThreshold ( LibTiePieHandle_t  hDevice,
uint16_t  wCh 
)

Get the actual SafeGround threshold current for the specified channel.

Parameters
[in]hDeviceA device handle identifying the oscilloscope.
[in]wChThe channel number identifying the channel, 0 to ScpGetChannelCount() - 1.
Returns
The currently set SafeGround threshold current, in Ampere.
Status values
NOT_SUPPORTED The indicated channel does not have SafeGround.
INVALID_CHANNEL The requested channel number is invalid.
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
ScpChHasSafeGround
ScpChGetSafeGroundThresholdMin
ScpChGetSafeGroundThresholdMax
ScpChSetSafeGroundThreshold
Since
0.6
double ScpChSetSafeGroundThreshold ( LibTiePieHandle_t  hDevice,
uint16_t  wCh,
double  dThreshold 
)

Set the SafeGround threshold current for the specified channel.

The SafeGround threshold can only be set when the scope is not performing a measurement.

Parameters
[in]hDeviceA device handle identifying the oscilloscope.
[in]wChThe channel number identifying the channel, 0 to ScpGetChannelCount() - 1.
[in]dThresholdThe required threshold current, in Ampere.
Returns
The actual set SafeGround threshold current, in Ampere.
Status values
VALUE_MODIFIED The requested threshold current is within the valid range, but not available. The closest valid value is set.
VALUE_CLIPPED The requested threshold current is outside the valid range and clipped to the closest limit.
INVALID_VALUE The requested value is invalid.
UNSUCCESSFUL The scope is measuring.
NOT_SUPPORTED The indicated channel does not have SafeGround.
INVALID_CHANNEL The requested channel number is invalid.
INVALID_HANDLE The handle is not a valid oscilloscope handle.
OBJECT_GONE The object indicated by the handle is no longer available.
LIBRARY_NOT_INITIALIZEDThe library is not initialized, see LibInit().
SUCCESS The function executed successfully.
See also
ScpChHasSafeGround
ScpChGetSafeGroundThresholdMin
ScpChGetSafeGroundThresholdMax
ScpChGetSafeGroundThreshold
Since
0.6