libtiepie-hw  1.1.3

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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

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]handleA device handle identifying the oscilloscope.
[in]chThe 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]handleA device handle identifying the oscilloscope.
[in]chThe 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]handleA device handle identifying the oscilloscope.
[in]chThe channel number identifying the channel, 0 to tiepie_hw_oscilloscope_get_channel_count() - 1.
[in]valueTIEPIE_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]handleA device handle identifying the oscilloscope.
[in]chThe 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]handleA device handle identifying the oscilloscope.
[in]chThe 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]handleA device handle identifying the oscilloscope.
[in]chThe 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]handleA device handle identifying the oscilloscope.
[in]chThe channel number identifying the channel, 0 to tiepie_hw_oscilloscope_get_channel_count() - 1.
[in]thresholdThe 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