Functions to control the SafeGround feature of an oscilloscope channel. More...

Collaboration diagram for SafeGround:

Functions
TIEPIE_HW_API tiepie_hw_bool	tiepie_hw_oscilloscope_channel_has_safeground (tiepie_hw_handle handle, uint16_t ch)
	Check whether the specified channel has SafeGround.

TIEPIE_HW_API tiepie_hw_bool	tiepie_hw_oscilloscope_channel_get_safeground_enabled (tiepie_hw_handle handle, uint16_t ch)
	Check whether SafeGround is enabled for a specified channel.

TIEPIE_HW_API tiepie_hw_bool	tiepie_hw_oscilloscope_channel_set_safeground_enabled (tiepie_hw_handle handle, uint16_t ch, tiepie_hw_bool value)
	Enable or disable SafeGround for a specified channel.

TIEPIE_HW_API double	tiepie_hw_oscilloscope_channel_get_safeground_threshold_min (tiepie_hw_handle handle, uint16_t ch)
	Get the minimum SafeGround threshold current for the specified channel.

TIEPIE_HW_API double	tiepie_hw_oscilloscope_channel_get_safeground_threshold_max (tiepie_hw_handle handle, uint16_t ch)
	Get the maximum SafeGround threshold current for the specified channel.

TIEPIE_HW_API double	tiepie_hw_oscilloscope_channel_get_safeground_threshold (tiepie_hw_handle handle, uint16_t ch)
	Get the actual SafeGround threshold current for the specified channel.

TIEPIE_HW_API double	tiepie_hw_oscilloscope_channel_set_safeground_threshold (tiepie_hw_handle handle, uint16_t ch, double threshold)
	Set the SafeGround threshold current for the specified channel.

Detailed 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 threshold 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, TIEPIE_HW_EVENT_OSCILLOSCOPE_SAFEGROUND_ERROR. See also Callbacks.

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

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

Function Documentation

◆ tiepie_hw_oscilloscope_channel_has_safeground()

TIEPIE_HW_API tiepie_hw_bool tiepie_hw_oscilloscope_channel_has_safeground	(	tiepie_hw_handle	handle,
		uint16_t	ch
	)

Check whether the specified channel has SafeGround.

Parameters

[in]	handle	A device handle identifying the oscilloscope.
[in]	ch	The channel number identifying the channel, `0` to `tiepie_hw_oscilloscope_get_channel_count() - 1`.

Returns: TIEPIE_HW_BOOL_TRUE if SafeGround is available, TIEPIE_HW_BOOL_FALSE otherwise.

Status values

TIEPIE_HW_STATUS_INVALID_CHANNEL
TIEPIE_HW_STATUS_INVALID_HANDLE	The handle is not a valid oscilloscope handle.
TIEPIE_HW_STATUS_OBJECT_GONE
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS

Since: 1.0

◆ tiepie_hw_oscilloscope_channel_get_safeground_enabled()

TIEPIE_HW_API tiepie_hw_bool tiepie_hw_oscilloscope_channel_get_safeground_enabled	(	tiepie_hw_handle	handle,
		uint16_t	ch
	)

Check whether SafeGround is enabled for a specified channel.

Parameters

[in]	handle	A device handle identifying the oscilloscope.
[in]	ch	The channel number identifying the channel, `0` to `tiepie_hw_oscilloscope_get_channel_count() - 1`.

Returns: TIEPIE_HW_BOOL_TRUE if SafeGround is enabled, TIEPIE_HW_BOOL_FALSE otherwise.

Status values

TIEPIE_HW_STATUS_NOT_SUPPORTED	The indicated channel does not have SafeGround.
TIEPIE_HW_STATUS_INVALID_CHANNEL
TIEPIE_HW_STATUS_INVALID_HANDLE	The handle is not a valid oscilloscope handle.
TIEPIE_HW_STATUS_OBJECT_GONE
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS

See also: tiepie_hw_oscilloscope_channel_has_safeground; tiepie_hw_oscilloscope_channel_set_safeground_enabled

Since: 1.0

◆ tiepie_hw_oscilloscope_channel_set_safeground_enabled()

TIEPIE_HW_API tiepie_hw_bool tiepie_hw_oscilloscope_channel_set_safeground_enabled	(	tiepie_hw_handle	handle,
		uint16_t	ch,
		tiepie_hw_bool	value
	)

Enable or disable SafeGround for a specified channel.

When SafeGround is enabled for a channel and a ground current larger than the selected current threshold 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]	handle	A device handle identifying the oscilloscope.
[in]	ch	The channel number identifying the channel, `0` to `tiepie_hw_oscilloscope_get_channel_count() - 1`.
[in]	value	TIEPIE_HW_BOOL_TRUE to enable SafeGround or TIEPIE_HW_BOOL_FALSE to disable SafeGround.

Returns: TIEPIE_HW_BOOL_TRUE if SafeGround is enabled, TIEPIE_HW_BOOL_FALSE otherwise.

Status values

TIEPIE_HW_STATUS_UNSUCCESSFUL	A ground current larger than the selected threshold caused SafeGround to be disabled again, or the scope is measuring.
TIEPIE_HW_STATUS_NOT_SUPPORTED	The indicated channel does not have SafeGround.
TIEPIE_HW_STATUS_INVALID_CHANNEL
TIEPIE_HW_STATUS_INVALID_HANDLE	The handle is not a valid oscilloscope handle.
TIEPIE_HW_STATUS_OBJECT_GONE
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS

See also: tiepie_hw_oscilloscope_channel_has_safeground; tiepie_hw_oscilloscope_channel_get_safeground_enabled

Since: 1.0

◆ tiepie_hw_oscilloscope_channel_get_safeground_threshold_min()

TIEPIE_HW_API double tiepie_hw_oscilloscope_channel_get_safeground_threshold_min	(	tiepie_hw_handle	handle,
		uint16_t	ch
	)

Get the minimum SafeGround threshold current for the specified channel.

Parameters

[in]	handle	A device handle identifying the oscilloscope.
[in]	ch	The channel number identifying the channel, `0` to `tiepie_hw_oscilloscope_get_channel_count() - 1`.

Returns: Minimum SafeGround threshold current, in Ampere.

Status values

TIEPIE_HW_STATUS_NOT_SUPPORTED	The indicated channel does not have SafeGround.
TIEPIE_HW_STATUS_INVALID_CHANNEL
TIEPIE_HW_STATUS_INVALID_HANDLE	The handle is not a valid oscilloscope handle.
TIEPIE_HW_STATUS_OBJECT_GONE
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS

See also: tiepie_hw_oscilloscope_channel_has_safeground; tiepie_hw_oscilloscope_channel_get_safeground_threshold_max; tiepie_hw_oscilloscope_channel_get_safeground_threshold; tiepie_hw_oscilloscope_channel_set_safeground_threshold

Since: 1.0

◆ tiepie_hw_oscilloscope_channel_get_safeground_threshold_max()

TIEPIE_HW_API double tiepie_hw_oscilloscope_channel_get_safeground_threshold_max	(	tiepie_hw_handle	handle,
		uint16_t	ch
	)

Get the maximum SafeGround threshold current for the specified channel.

Parameters

[in]	handle	A device handle identifying the oscilloscope.
[in]	ch	The channel number identifying the channel, `0` to `tiepie_hw_oscilloscope_get_channel_count() - 1`.

Returns: Maximum SafeGround threshold current, in Ampere.

Status values

TIEPIE_HW_STATUS_NOT_SUPPORTED	The indicated channel does not have SafeGround.
TIEPIE_HW_STATUS_INVALID_CHANNEL
TIEPIE_HW_STATUS_INVALID_HANDLE	The handle is not a valid oscilloscope handle.
TIEPIE_HW_STATUS_OBJECT_GONE
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS

See also: tiepie_hw_oscilloscope_channel_has_safeground; tiepie_hw_oscilloscope_channel_get_safeground_threshold_min; tiepie_hw_oscilloscope_channel_get_safeground_threshold; tiepie_hw_oscilloscope_channel_set_safeground_threshold

Since: 1.0

◆ tiepie_hw_oscilloscope_channel_get_safeground_threshold()

TIEPIE_HW_API double tiepie_hw_oscilloscope_channel_get_safeground_threshold	(	tiepie_hw_handle	handle,
		uint16_t	ch
	)

Get the actual SafeGround threshold current for the specified channel.

Parameters

[in]	handle	A device handle identifying the oscilloscope.
[in]	ch	The channel number identifying the channel, `0` to `tiepie_hw_oscilloscope_get_channel_count() - 1`.

Returns: The currently set SafeGround threshold current, in Ampere.

Status values

TIEPIE_HW_STATUS_NOT_SUPPORTED	The indicated channel does not have SafeGround.
TIEPIE_HW_STATUS_INVALID_CHANNEL
TIEPIE_HW_STATUS_INVALID_HANDLE	The handle is not a valid oscilloscope handle.
TIEPIE_HW_STATUS_OBJECT_GONE
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS

See also: tiepie_hw_oscilloscope_channel_has_safeground; tiepie_hw_oscilloscope_channel_get_safeground_threshold_min; tiepie_hw_oscilloscope_channel_get_safeground_threshold_max; tiepie_hw_oscilloscope_channel_set_safeground_threshold

Since: 1.0

◆ tiepie_hw_oscilloscope_channel_set_safeground_threshold()

TIEPIE_HW_API double tiepie_hw_oscilloscope_channel_set_safeground_threshold	(	tiepie_hw_handle	handle,
		uint16_t	ch,
		double	threshold
	)

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]	handle	A device handle identifying the oscilloscope.
[in]	ch	The channel number identifying the channel, `0` to `tiepie_hw_oscilloscope_get_channel_count() - 1`.
[in]	threshold	The required threshold current, in Ampere.

Returns: The actual set SafeGround threshold current, in Ampere.

Status values

TIEPIE_HW_STATUS_VALUE_MODIFIED	The requested threshold current is within the valid range, but not available. The closest valid value is set.
TIEPIE_HW_STATUS_VALUE_CLIPPED	The requested threshold current is outside the valid range and clipped to the closest limit.
TIEPIE_HW_STATUS_INVALID_VALUE
TIEPIE_HW_STATUS_UNSUCCESSFUL	The scope is measuring.
TIEPIE_HW_STATUS_NOT_SUPPORTED	The indicated channel does not have SafeGround.
TIEPIE_HW_STATUS_INVALID_CHANNEL
TIEPIE_HW_STATUS_INVALID_HANDLE	The handle is not a valid oscilloscope handle.
TIEPIE_HW_STATUS_OBJECT_GONE
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS

See also: tiepie_hw_oscilloscope_channel_has_safeground; tiepie_hw_oscilloscope_channel_get_safeground_threshold_min; tiepie_hw_oscilloscope_channel_get_safeground_threshold_max; tiepie_hw_oscilloscope_channel_get_safeground_threshold

Since: 1.0