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().

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

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

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

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

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

Function Documentation

bool8_t ScpHasConnectionTest ( TpDeviceHandle_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.
DEVICE_GONE	The device indicated by the device 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	(	TpDeviceHandle_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 not valid.
INVALID_HANDLE	The handle is not a valid oscilloscope handle.
DEVICE_GONE	The device indicated by the device 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 ( TpDeviceHandle_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.
DEVICE_GONE	The device indicated by the device 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 ( TpDeviceHandle_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.
DEVICE_GONE	The device indicated by the device 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	(	TpDeviceHandle_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.
DEVICE_GONE	The device indicated by the device 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