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]	hDevice	A device handle identifying the oscilloscope.
[in]	wCh	The 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_INITIALIZED	The 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]	hDevice	A device handle identifying the oscilloscope.
[in]	wCh	The 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_INITIALIZED	The 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]	hDevice	A device handle identifying the oscilloscope.
[in]	wCh	The channel number identifying the channel, `0` to `ScpGetChannelCount() - 1`.
[in]	bEnable	BOOL8_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_INITIALIZED	The 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]	hDevice	A device handle identifying the oscilloscope.
[in]	wCh	The 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_INITIALIZED	The 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]	hDevice	A device handle identifying the oscilloscope.
[in]	wCh	The 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_INITIALIZED	The 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]	hDevice	A device handle identifying the oscilloscope.
[in]	wCh	The 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_INITIALIZED	The 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]	hDevice	A device handle identifying the oscilloscope.
[in]	wCh	The channel number identifying the channel, `0` to `ScpGetChannelCount() - 1`.
[in]	dThreshold	The 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_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

See also: ScpChHasSafeGround; ScpChGetSafeGroundThresholdMin; ScpChGetSafeGroundThresholdMax; ScpChGetSafeGroundThreshold

Since: 0.6