Description

Functions to control the device list: open and close devices and retrieve device information.

LibTiePie maintains a Device list, containing all available supported devices. Possible devices are oscilloscopes, generators and I2C hosts. Instruments can contain multiple devices, e.g. the Handyscope HS5 contains an oscilloscope, a generator and an I2C host.

After starting the application, the device list must be filled with all available devices, using LstUpdate(). When the application is running, the device list is automatically maintained. When new compatible devices are connected to the computer, they will be added to the device list automatically. When devices are disconnected from the computer, they are automatically removed from the list.

Getting device information

Before opening a device, information from the listed devices can be retrieved. This information can help opening the required device, when multiple devices are available in the list.

Opening a device

Before any device action can be performed a device needs to be opened. When a device in the device list is opened, a unique handle to the device is assigned. This handle is required to access the device.

LibTiePie has four functions for opening devices. One function for each device type (LstOpenOscilloscope, LstOpenGenerator and LstOpenI2CHost), and one (LstOpenDevice) to open a device by specifying its device type. A device can only be opened once.

Device open methods

LibTiePie supports three different methods for opening devices.

Open by device list index (IDKIND_INDEX), e.g.:
LibTiePieHandle_t hScp = LstOpenDevice( IDKIND_INDEX , 4 , DEVICETYPE_OSCILLOSCOPE ); // Try to open oscilloscope at device list index 4.
Open by serial number (IDKIND_SERIALNUMBER), e.g.:
LibTiePieHandle_t hGen = LstOpenDevice( IDKIND_SERIALNUMBER , 22110 , DEVICETYPE_GENERATOR ); // Try to open generator with serial number 22110.
Open by product id (IDKIND_PRODUCTID), e.g.:
LibTiePieHandle_t hI2C = LstOpenDevice( IDKIND_PRODUCTID , PID_HS5 , DEVICETYPE_I2CHOST ); // Try to open a Handyscope HS5 I2C host.

When a device cannot be opened the function to open returns LIBTIEPIE_HANDLE_INVALID.

Closing a disconnected device

When an open device is disconnected from the computer, the handle to that device will be no longer valid and the device needs to be closed using ObjClose(). Calling functions pointing to a disconnected device will set the status flag to LIBTIEPIESTATUS_OBJECT_GONE.

Combining devices

Several devices support combining, where multiple units can be combined to form a larger device. Two different methods are possible.

Automatic combining

This applies to the Handyscope HS5 and Handyscope HS6 DIFF.

Connect the instruments to each other using a special coupling cable and update the device list using LstUpdate(). A new combined device with a new (virtual) serial number will be added to the device list, the original devices remain present in the device list but can not be accessed anymore.

To undo an automatic combination, remove the coupling cable(s) and update the device list using LstUpdate().

Manual combining

This applies to the Handyscope HS4, Handyscope HS4 DIFF and ATS5004D.

Connect the instruments to each other using a special coupling cable and open the individual oscilloscopes to retrieve their handles. Then call a coupling function, supplying the handles of the devices to combine. A new combined device with a new (virtual) serial number will be added to the device list, the original devices remain present in the device list but their handles become invalid. These should be closed using ObjClose(). An example in C is available on the TiePie engineering website.

To undo a manual combination, remove the coupling cable, close the combined device using ObjClose() with the handle of the combined device. Finally remove the combined device from the device list using LstRemoveDevice() with the serial number of the combined device.

Opening a combined device

Opening a combined device can be done in the ways described before, with one restriction. When opening a combined device by product id (IDKIND_PRODUCTID), the id PID_COMBI must be used.

Modules
	Listed devices
	Functions to retrieve information from the listed devices.

	Notifications
	Functions to set notifications that are triggered when the device list is changed.

Functions
void	LstUpdate (void)
	Update the device list. More...

uint32_t	LstGetCount (void)
	Get the number of devices in the device list. More...

LibTiePieHandle_t	LstOpenDevice (uint32_t dwIdKind, uint32_t dwId, uint32_t dwDeviceType)
	Open a device and get a handle to the device. More...

LibTiePieHandle_t	LstOpenOscilloscope (uint32_t dwIdKind, uint32_t dwId)
	Open an oscilloscope and get a handle to the oscilloscope. More...

LibTiePieHandle_t	LstOpenGenerator (uint32_t dwIdKind, uint32_t dwId)
	Open a generator and get a handle to the generator. More...

LibTiePieHandle_t	LstOpenI2CHost (uint32_t dwIdKind, uint32_t dwId)
	Open an I2C host and get a handle to the I2C host. More...

uint32_t	LstCreateCombinedDevice (const LibTiePieHandle_t *pDeviceHandles, uint32_t dwCount)
	Create a combined instrument. More...

LibTiePieHandle_t	LstCreateAndOpenCombinedDevice (const LibTiePieHandle_t *pDeviceHandles, uint32_t dwCount)
	Create and open a combined instrument. More...

void	LstRemoveDevice (uint32_t dwSerialNumber)
	Remove an instrument from the device list so it can be used by other applications. More...

void	LstRemoveDeviceForce (uint32_t dwSerialNumber)
	Remove an instrument from the device list even when it is in use so it can be used by other applications. More...

Function Documentation

void LstUpdate ( void )

Update the device list.

This function searches for new instruments and adds these to the device list.

Status values

LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Example: LstUpdate(); // Search for new instruments

Since: 0.5

uint32_t LstGetCount ( void )

Get the number of devices in the device list.

Returns: The number of devices in the device list.

Status values

LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Since: 0.4.0

LibTiePieHandle_t LstOpenDevice	(	uint32_t	dwIdKind,
		uint32_t	dwId,
		uint32_t	dwDeviceType
	)

Open a device and get a handle to the device.

Parameters

[in]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the device to open as specified by `dwIdKind`.
[in]	dwDeviceType	A device type.

Returns: A device handle, or LIBTIEPIE_HANDLE_INVALID on error.

Status values

INITIALIZATION_FAILED	The instrument's initialization failed, please contact TiePie engineering support.
INVALID_EEPROM	The instrument's EEPROM content is damaged, please contact TiePie engineering support.
INVALID_FIRMWARE	The currently used firmware is not supported .
INVALID_DRIVER	The currently installed driver is not supported, see LstDevGetRecommendedDriverVersion(). (Windows only)
INVALID_VALUE	The value of dwIdKind or dwDeviceType is invalid.
INVALID_DEVICE_INDEX	The device index is invalid, must be < LstGetCount().
INVALID_PRODUCT_ID	There is no device with the requested product ID.
INVALID_DEVICE_SERIALNUMBER	There is no device with the requested serial number.
INVALID_DEVICE_TYPE	The device type is invalid.
INVALID_DRIVER	The currently installed driver is not supported, see LstDevGetRecommendedDriverVersion(). (Windows only)
UNSUCCESSFUL	The device is already open or an other error occurred.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Examples: LibTiePieHandle_t hScp = LstOpenDevice( IDKIND_INDEX , 4 , DEVICETYPE_OSCILLOSCOPE ); // Try to open oscilloscope at device list index 4.

LibTiePieHandle_t hI2C = LstOpenDevice( IDKIND_PRODUCTID , PID_HS5 , DEVICETYPE_I2CHOST ); // Try to open a Handyscope HS5 I2C host.

LibTiePieHandle_t hGen = LstOpenDevice( IDKIND_SERIALNUMBER , 22110 , DEVICETYPE_GENERATOR ); // Try to open generator with serial number 22110.

See also: LstOpenOscilloscope; LstOpenGenerator; LstOpenI2CHost; ObjClose

Since: 0.4.0

LibTiePieHandle_t LstOpenOscilloscope	(	uint32_t	dwIdKind,
		uint32_t	dwId
	)

Open an oscilloscope and get a handle to the oscilloscope.

Parameters

[in]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the oscilloscope to open as specified by `dwIdKind`.

Returns: A device handle, or LIBTIEPIE_HANDLE_INVALID on error.

Status values

INITIALIZATION_FAILED	The instrument's initialization failed, please contact TiePie engineering support.
INVALID_EEPROM	The instrument's EEPROM content is damaged, please contact TiePie engineering support.
INVALID_FIRMWARE	The currently used firmware is not supported .
INVALID_DRIVER	The currently installed driver is not supported, see LstDevGetRecommendedDriverVersion(). (Windows only)
INVALID_VALUE	The value of dwIdKind is invalid.
INVALID_DEVICE_INDEX	The device index is invalid, must be < LstGetCount().
INVALID_PRODUCT_ID	There is no device with the requested product ID.
INVALID_DEVICE_SERIALNUMBER	There is no device with the requested serial number.
INVALID_DRIVER	The currently installed driver is not supported, see LstDevGetRecommendedDriverVersion(). (Windows only)
UNSUCCESSFUL	The device is already open or an other error occured.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Examples: LibTiePieHandle_t hScp = LstOpenOscilloscope( IDKIND_INDEX , 4 ); // Try to open oscilloscope at device list index 4.

LibTiePieHandle_t hScp = LstOpenOscilloscope( IDKIND_SERIALNUMBER , 27917 ); // Try to open oscilloscope with serial number 27917.

LibTiePieHandle_t hScp = LstOpenOscilloscope( IDKIND_PRODUCTID , PID_HS5 ); // Try to open a Handyscope HS5 oscilloscope.

See also: LstOpenDevice; LstOpenGenerator; LstOpenI2CHost; ObjClose

Since: 0.4.0

LibTiePieHandle_t LstOpenGenerator	(	uint32_t	dwIdKind,
		uint32_t	dwId
	)

Open a generator and get a handle to the generator.

Parameters

[in]	dwIdKind	An id kind.
[in]	dwId	Device index, Product ID or serial number identifying the generator to open as specified by `dwIdKind`.

Returns: A device handle, or LIBTIEPIE_HANDLE_INVALID on error.

Status values

INITIALIZATION_FAILED	The instrument's initialization failed, please contact TiePie engineering support.
INVALID_EEPROM	The instrument's EEPROM content is damaged, please contact TiePie engineering support.
INVALID_FIRMWARE	The currently used firmware is not supported .
INVALID_DRIVER	The currently installed driver is not supported, see LstDevGetRecommendedDriverVersion(). (Windows only)
INVALID_VALUE	The value of dwIdKind is invalid.
INVALID_DEVICE_INDEX	The device index is invalid, must be < LstGetCount().
INVALID_PRODUCT_ID	There is no device with the requested product ID.
INVALID_DEVICE_SERIALNUMBER	There is no device with the requested serial number.
INVALID_DRIVER	The currently installed driver is not supported, see LstDevGetRecommendedDriverVersion(). (Windows only)
UNSUCCESSFUL	The device is already open or an other error occured.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Examples: LibTiePieHandle_t hGen = LstOpenGenerator( IDKIND_INDEX , 2 ); // Try to open generator at device list index 2.

LibTiePieHandle_t hGen = LstOpenGenerator( IDKIND_SERIALNUMBER , 22110 ); // Try to open generator with serial number 22110.

LibTiePieHandle_t hGen = LstOpenGenerator( IDKIND_PRODUCTID , PID_HS5 ); // Try to open a Handyscope HS5 generator.

See also: LstOpenDevice; LstOpenOscilloscope; LstOpenI2CHost; ObjClose

Since: 0.4.0

LibTiePieHandle_t LstOpenI2CHost	(	uint32_t	dwIdKind,
		uint32_t	dwId
	)

Open an I2C host and get a handle to the I2C host.

Parameters

[in]	dwIdKind	An id kind.
[in]	dwId	A device index, Product ID or serial number identifying the I2C host to open as specified by `dwIdKind`.

Returns: A device handle, or LIBTIEPIE_HANDLE_INVALID on error.

Status values

INITIALIZATION_FAILED	The instrument's initialization failed, please contact TiePie engineering support.
INVALID_EEPROM	The instrument's EEPROM content is damaged, please contact TiePie engineering support.
INVALID_FIRMWARE	The currently used firmware is not supported .
INVALID_DRIVER	The currently installed driver is not supported, see LstDevGetRecommendedDriverVersion(). (Windows only)
INVALID_VALUE	The value of dwIdKind is invalid.
INVALID_DEVICE_INDEX	The device index is invalid, must be < LstGetCount().
INVALID_PRODUCT_ID	There is no device with the requested product ID.
INVALID_DEVICE_SERIALNUMBER	There is no device with the requested serial number.
INVALID_DRIVER	The currently installed driver is not supported, see LstDevGetRecommendedDriverVersion(). (Windows only)
UNSUCCESSFUL	The device is already open or an other error occured.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Examples: LibTiePieHandle_t hI2C = LstOpenI2CHost( IDKIND_INDEX , 0 ); // Try to open I2C host at device list index 0.

LibTiePieHandle_t hI2C = LstOpenI2CHost( IDKIND_SERIALNUMBER , 26697 ); // Try to open I2C host with serial number 26697.

LibTiePieHandle_t hI2C = LstOpenI2CHost( IDKIND_PRODUCTID , PID_HS5 ); // Try to open a Handyscope HS5 I2C host.

See also: LstOpenDevice; LstOpenOscilloscope; LstOpenGenerator; ObjClose

Since: 0.4.0

uint32_t LstCreateCombinedDevice	(	const LibTiePieHandle_t *	pDeviceHandles,
		uint32_t	dwCount
	)

Create a combined instrument.

This function creates combined instrument from the indicated devices.

Parameters

[in]	pDeviceHandles	Pointer to an array of handles of the devices to combine.
[in]	dwCount	The number of device handles.

Returns: Serial number of the combined device, or zero on error.

Status values

NOT_SUPPORTED	Combining is not supported.
INVALID_HANDLE	One or more device handles are invalid or incompatible.
INVALID_VALUE	pDeviceHandles must be != `NULL` and the number of device handles must be >= 2.
OBJECT_GONE	One or more devices indicated by the device handles is no longer available.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

See also: LstCreateAndOpenCombinedDevice

Since: 0.4.4

LibTiePieHandle_t LstCreateAndOpenCombinedDevice	(	const LibTiePieHandle_t *	pDeviceHandles,
		uint32_t	dwCount
	)

Create and open a combined instrument.

This function creates a combined instrument from the indicated devices and opens it.

Parameters

[in]	pDeviceHandles	Pointer to an array of handles of the devices to combine.
[in]	dwCount	The number of device handles.

Returns: A device handle, or LIBTIEPIE_HANDLE_INVALID on error.

Status values

NOT_SUPPORTED	Combining is not supported.
INVALID_HANDLE	One or more device handles are invalid or incompatible.
INVALID_VALUE	pDeviceHandles must be != `NULL` and the number of device handles must be >= 2.
OBJECT_GONE	One or more devices indicated by the device handles is no longer available.
UNSUCCESSFUL	An error occurred during execution of the last called function.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

See also: LstCreateCombinedDevice

Since: 0.4.4

void LstRemoveDevice ( uint32_t dwSerialNumber )

Remove an instrument from the device list so it can be used by other applications.

Parameters

[in] dwSerialNumber Serial number of the device to remove.

Status values

UNSUCCESSFUL	Device is still open?
NOT_SUPPORTED	Device can't be removed from the list. To remove a combined Handyscope HS5, unplug the coupling cable and call LstUpdate().
INVALID_DEVICE_SERIALNUMBER	There is no device with the requested serial number.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Since: 0.4.0

See also: LstRemoveDeviceForce

void LstRemoveDeviceForce ( uint32_t dwSerialNumber )

Remove an instrument from the device list even when it is in use so it can be used by other applications.

Parameters

[in] dwSerialNumber Serial number of the device to remove.

Status values

NOT_SUPPORTED	Device can't be removed from the list. To remove a combined Handyscope HS5, unplug the coupling cable and call LstUpdate().
INVALID_DEVICE_SERIALNUMBER	There is no device with the requested serial number.
LIBRARY_NOT_INITIALIZED	The library is not initialized, see LibInit().
SUCCESS	The function executed successfully.

Since: 0.9.8

See also: LstRemoveDevice

Description

Getting device information

Opening a device

Device open methods

Closing a disconnected device

Combining devices

Automatic combining

Manual combining

Opening a combined device

Modules

Functions

Function Documentation