LibTiePie  0.6.1
Library for interfacing TiePie engineering instruments
Device list

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.

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.

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

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_INITIALIZEDThe 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_INITIALIZEDThe 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]dwIdKindAn id kind.
[in]dwIdA device index, Product ID or serial number identifying the device to open as specified by dwIdKind.
[in]dwDeviceTypeA 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_SERIALNUMBERThere 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]dwIdKindAn id kind.
[in]dwIdA 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_SERIALNUMBERThere 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]dwIdKindAn id kind.
[in]dwIdDevice 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_SERIALNUMBERThere 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]dwIdKindAn id kind.
[in]dwIdA 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_SERIALNUMBERThere 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]pDeviceHandlesPointer to an array of handles of the devices to combine.
[in]dwCountThe 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_INITIALIZEDThe 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]pDeviceHandlesPointer to an array of handles of the devices to combine.
[in]dwCountThe 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_INITIALIZEDThe 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]dwSerialNumberSerial 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_SERIALNUMBERThere 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