Description

Functions to perform a connection test.

To check whether the measurement probe on a channel is electrically connected to the device under test, a connection test can be performed on instruments with SureConnect. To find out whether the connection test is ready, ScpIsConnectionTestCompleted() can be polled, or a notification can be used. When the connection test is ready, connection test data indicating the connection status of the input(s) can be collected using ScpGetConnectionTestData().

Connection test is not available for all instruments. Use ScpHasConnectionTest() to check whether connection test is available for your instrument.

Functions
bool8_t	ScpHasConnectionTest (LibTiePieHandle_t hDevice)
	Check whether the specified oscilloscope supports connection testing. More...

bool8_t	ScpChHasConnectionTest (LibTiePieHandle_t hDevice, uint16_t wCh)
	Check whether a specified channel of a specified oscilloscope supports connection testing. More...

bool8_t	ScpStartConnectionTest (LibTiePieHandle_t hDevice)
	Perform a connection test on all enabled channels of a specified oscilloscope. More...

bool8_t	ScpIsConnectionTestCompleted (LibTiePieHandle_t hDevice)
	Check whether the connection test on a specified oscilloscope is completed. More...

uint16_t	ScpGetConnectionTestData (LibTiePieHandle_t hDevice, LibTiePieTriState_t *pBuffer, uint16_t wChannelCount)
	Get the connection test result data for a specified oscilloscope. More...

Function Documentation

bool8_t ScpHasConnectionTest ( LibTiePieHandle_t hDevice )

Check whether the specified oscilloscope supports connection testing.

Parameters

[in] hDevice A device handle identifying the oscilloscope.

Returns: BOOL8_TRUE when at least one channel supports connection testing, BOOL8_FALSE otherwise.

Status values

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: ScpChHasConnectionTest

Since: 0.4.0

bool8_t ScpChHasConnectionTest	(	LibTiePieHandle_t	hDevice,
		uint16_t	wCh
	)

Check whether a specified channel of a specified oscilloscope supports connection testing.

Parameters

[in]	hDevice	A device handle identifying the oscilloscope.
[in]	wCh	A channel number identifying the channel, `0` to `ScpGetChannelCount() - 1`.

Returns: BOOL8_TRUE if the channel supports connection test, 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.

See also: ScpHasConnectionTest

Since: 0.4.0

bool8_t ScpStartConnectionTest ( LibTiePieHandle_t hDevice )

Perform a connection test on all enabled channels of a specified oscilloscope.

Parameters

[in] hDevice A device handle identifying the oscilloscope.

Returns: BOOL8_TRUE if started successfully, BOOL8_FALSE otherwise.

Status values

UNSUCCESSFUL	No channels are enabled or a measurement is busy.
NOT_SUPPORTED	The oscilloscope does not support connection test.
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: ScpHasConnectionTest; ScpChHasConnectionTest; ScpIsConnectionTestCompleted; ScpGetConnectionTestData

Since: 0.5

bool8_t ScpIsConnectionTestCompleted ( LibTiePieHandle_t hDevice )

Check whether the connection test on a specified oscilloscope is completed.

Parameters

[in] hDevice A device handle identifying the oscilloscope.

Returns: BOOL8_TRUE if completed, BOOL8_FALSE otherwise.

Status values

NOT_SUPPORTED	The oscilloscope does not support connection test.
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: ScpHasConnectionTest; ScpChHasConnectionTest; ScpStartConnectionTest; notification Connection test completed; ScpGetConnectionTestData

Since: 0.4.0

uint16_t ScpGetConnectionTestData	(	LibTiePieHandle_t	hDevice,
		LibTiePieTriState_t *	pBuffer,
		uint16_t	wChannelCount
	)

Get the connection test result data for a specified oscilloscope.

The test result data is presented in an array pBuffer with an element for each channel. Each element contains the connection test status for a channel:

LIBTIEPIE_TRISTATE_UNDEFINED this channel is not enabled or does not support connection test.
LIBTIEPIE_TRISTATE_FALSE this channel has no connection
LIBTIEPIE_TRISTATE_TRUE this channel has connection

Parameters

[in]	hDevice	A device handle identifying the oscilloscope.
[out]	pBuffer	A pointer to a LibTiePieTriState_t array.
[in]	wChannelCount	The length of the LibTiePieTriState_t array.

Returns: The number of elements written in the LibTiePieTriState_t array.

Status values

NOT_SUPPORTED	The oscilloscope does not support connection test.
INVALID_VALUE	The pointer `pBuffer` was `NULL` or `wChannelCount` was `0`.
UNSUCCESSFUL	No connection test result data available.
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.

Example: uint16_t wChannelCount = ScpGetChannelCount( hDevice );
LibTiePieTriState_t* pConnections = malloc( sizeof( LibTiePieTriState_t ) * wChannelCount );
ScpGetConnectionTestData( hDevice , pConnections , wChannelCount );
printf( "ScpGetConnectionTestData ( ):\n" );
for( uint16_t i = 0 ; i < wChannelCount ; i++ )
switch( pConnections )
{
case LIBTIEPIE_TRISTATE_UNDEFINED:
printf( "- Ch%u Undefined\n", i + 1 );
break;
case LIBTIEPIE_TRISTATE_FALSE:
printf( "- Ch%u Not connected\n", i + 1 );
break;
case LIBTIEPIE_TRISTATE_TRUE:
printf( "- Ch%u Connected\n", i + 1 );
break;
default:
printf( "- Ch%u Invalid value\n", i + 1 );
break;
}
free( pConnections );

See also: ScpHasConnectionTest; ScpChHasConnectionTest; ScpStartConnectionTest; ScpIsConnectionTestCompleted

Since: 0.4.0