libtiepie-hw  1.2.5
Device list

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

Collaboration diagram for Device list:

Modules

 Listed devices
 Functions to retrieve information from the listed devices.
 
 Callbacks
 Functions to set callbacks that are triggered when the device list is changed.
 

Functions

TIEPIE_HW_API void tiepie_hw_devicelist_update (void)
 Update the device list. More...
 
TIEPIE_HW_API tiepie_hw_bool tiepie_hw_devicelist_get_usb_hotplug_detect_enabled (void)
 Get the current enabled state of the USB hot plug detection. More...
 
TIEPIE_HW_API tiepie_hw_bool tiepie_hw_devicelist_set_usb_hotplug_detect_enabled (tiepie_hw_bool value)
 Set the USB hot plug detection enabled state. More...
 
TIEPIE_HW_API uint32_t tiepie_hw_devicelist_get_count (void)
 Get the number of devices in the device list. More...
 
TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelist_get_item_by_product_id (tiepie_hw_productid product_id)
 Get handle to device list item by product id. More...
 
TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelist_get_item_by_index (uint32_t index)
 Get handle to device list item by product id. More...
 
TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelist_get_item_by_serial_number (uint32_t serial_number)
 Get handle to device list item by product id. More...
 
TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelistitem_open_device (tiepie_hw_handle handle, uint32_t device_type)
 Open a device and get a handle to the device. More...
 
TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelistitem_open_oscilloscope (tiepie_hw_handle handle)
 Open an oscilloscope and get a handle to the oscilloscope. More...
 
TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelistitem_open_generator (tiepie_hw_handle handle)
 Open a generator and get a handle to the generator. More...
 
TIEPIE_HW_API const tiepie_hw_demo_infotiepie_hw_devicelist_get_demo_device_info (void)
 Get list of available demo devices. More...
 
TIEPIE_HW_API uint32_t tiepie_hw_devicelist_create_demo_device (tiepie_hw_productid product_id)
 Create a demo instrument. More...
 
TIEPIE_HW_API uint32_t tiepie_hw_devicelist_create_combined_device (const tiepie_hw_handle *handles, uint32_t count)
 Create a combined instrument. More...
 
TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelist_create_and_open_combined_device (const tiepie_hw_handle *handles, uint32_t count)
 Create and open a combined instrument. More...
 
TIEPIE_HW_API void tiepie_hw_devicelist_remove_device (uint32_t serial_number, tiepie_hw_bool force)
 Remove an instrument from the device list so it can be used by other applications. More...
 
TIEPIE_HW_API void tiepie_hw_devicelist_remove_unused_devices (void)
 Remove unused instruments from the device list so they can be used by other applications. More...
 

Detailed Description

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

libtiepie-hw maintains a device list, containing all available supported devices. Possible devices are oscilloscopes and, generators. Instruments can contain multiple devices, e.g. the Handyscope HS5 contains an oscilloscope and a generator.

After starting the application, the device list must be filled with all available devices, using tiepie_hw_devicelist_update(). 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-hw has three functions for opening devices. One function for each device type (tiepie_hw_devicelistitem_open_oscilloscope, tiepie_hw_devicelistitem_open_generator), and one (tiepie_hw_devicelistitem_open_device) to open a device by specifying its device type. A device can only be opened once.

Device open methods

libtiepie-hw supports three different methods for opening devices.

When a device cannot be opened the function to open returns TIEPIE_HW_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 tiepie_hw_object_close(). Calling functions pointing to a disconnected device will set the status flag to TIEPIE_HW_STATUS_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 all instruments with CMI interface: the Handyscope HS5, Handyscope HS6, Handyscope HS6 DIFF, WiFiScope WS5, WiFiScope WS6, WiFiScope WS6 DIFF and the Automotive Test Scopes ATS610004D-XMSG, ATS605004D-XMS, ATS610004DW-XMSG, and ATS605004DW-XMS. For the WiFiScopes this only applies when connected via USB, when connected via LAN or Wifi, combining is no possible.

Connect the instruments to each other using a special coupling cable and update the device list using tiepie_hw_devicelist_update(). 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 tiepie_hw_devicelist_update().

Manual combining

This applies to the Handyscope HS3, Handyscope HS4, Handyscope HS4 DIFF and WiFiScope WS4 DIFF and and the Automotive Test Scopes ATS5004D and ATS5004DW. For the WiFiScopes this only applies when connected via USB, when connected via LAN or Wifi, combining is no possible.

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 tiepie_hw_object_close(). 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 tiepie_hw_object_close() with the handle of the combined device. Finally remove the combined device from the device list using tiepie_hw_devicelist_remove_device() 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, the id TIEPIE_HW_PRODUCTID_COMBI must be used.

Function Documentation

◆ tiepie_hw_devicelist_update()

TIEPIE_HW_API void tiepie_hw_devicelist_update ( void  )

Update the device list.

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

Status values
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS
See also
tiepie_hw_devicelist_set_usb_hotplug_detect_enabled
Example
tiepie_hw_devicelist_update(); // Search for new instruments
TIEPIE_HW_API void tiepie_hw_devicelist_update(void)
Update the device list.
Since
1.0

◆ tiepie_hw_devicelist_get_usb_hotplug_detect_enabled()

TIEPIE_HW_API tiepie_hw_bool tiepie_hw_devicelist_get_usb_hotplug_detect_enabled ( void  )

Get the current enabled state of the USB hot plug detection.

Returns
TIEPIE_HW_BOOL_TRUE if enabled, TIEPIE_HW_BOOL_FALSE otherwise.
Status values
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS
See also
tiepie_hw_devicelist_set_usb_hotplug_detect_enabled
Since
1.0

◆ tiepie_hw_devicelist_set_usb_hotplug_detect_enabled()

TIEPIE_HW_API tiepie_hw_bool tiepie_hw_devicelist_set_usb_hotplug_detect_enabled ( tiepie_hw_bool  value)

Set the USB hot plug detection enabled state.

When hot plug detection is enabled, a USB device that is connected to the computer and detected by the operating system, will be automatically added to the device list.

When hot plug detection is disabled, a USB device that is connected to the computer and detected by the operating system, will not be automatically added to the device list. This allows another instance of libtiepie to open the instrument. To add the instrument to the device list anyway, use tiepie_hw_devicelist_update().

Parameters
[in]valueTIEPIE_HW_BOOL_TRUE to enable, TIEPIE_HW_BOOL_FALSE to disable.
Returns
TIEPIE_HW_BOOL_TRUE if enabled, TIEPIE_HW_BOOL_FALSE otherwise.
Status values
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS
See also
tiepie_hw_devicelist_get_usb_hotplug_detect_enabled
tiepie_hw_devicelist_update
Since
1.0

◆ tiepie_hw_devicelist_get_count()

TIEPIE_HW_API uint32_t tiepie_hw_devicelist_get_count ( void  )

Get the number of devices in the device list.

Returns
The number of devices in the device list.
Status values
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS
Since
1.0

◆ tiepie_hw_devicelist_get_item_by_product_id()

TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelist_get_item_by_product_id ( tiepie_hw_productid  product_id)

Get handle to device list item by product id.

Returns
handle.
Status values
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_INVALID_PRODUCT_ID
TIEPIE_HW_STATUS_SUCCESS
See also
tiepie_hw_object_close
Since
1.0

◆ tiepie_hw_devicelist_get_item_by_index()

TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelist_get_item_by_index ( uint32_t  index)

Get handle to device list item by product id.

Returns
handle.
Status values
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_INVALID_DEVICE_INDEX
TIEPIE_HW_STATUS_SUCCESS
See also
tiepie_hw_object_close
Since
1.0

◆ tiepie_hw_devicelist_get_item_by_serial_number()

TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelist_get_item_by_serial_number ( uint32_t  serial_number)

Get handle to device list item by product id.

Returns
handle.
Status values
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_INVALID_DEVICE_SERIALNUMBER
TIEPIE_HW_STATUS_SUCCESS
See also
tiepie_hw_object_close
Since
1.0

◆ tiepie_hw_devicelistitem_open_device()

TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelistitem_open_device ( tiepie_hw_handle  handle,
uint32_t  device_type 
)

Open a device and get a handle to the device.

Parameters
[in]handleA handle identifying the object.
[in]device_typeA device type.
Returns
A device handle, or TIEPIE_HW_HANDLE_INVALID on error.
Status values
TIEPIE_HW_STATUS_INITIALIZATION_FAILED
TIEPIE_HW_STATUS_INVALID_EEPROM
TIEPIE_HW_STATUS_INVALID_FIRMWARE
TIEPIE_HW_STATUS_INVALID_VALUE The value of Id_kind or Device_type is invalid.
TIEPIE_HW_STATUS_INVALID_DEVICE_TYPE
TIEPIE_HW_STATUS_UNSUCCESSFUL The device is already open or an other error occurred.
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS
Examples
tiepie_hw_handle scp = tiepie_hw_devicelistitem_open_device(devicelist_item_handle, TIEPIE_HW_DEVICETYPE_OSCILLOSCOPE); // Try to open oscilloscope at device list index 4.
tiepie_hw_object_close(devicelist_item_handle);
tiepie_hw_handle gen = tiepie_hw_devicelistitem_open_device(devicelist_item_handle, TIEPIE_HW_DEVICETYPE_GENERATOR); // Try to open generator with serial number 22110.
tiepie_hw_object_close(devicelist_item_handle);
See also
tiepie_hw_devicelistitem_open_oscilloscope
tiepie_hw_devicelistitem_open_generator
tiepie_hw_object_close
Since
1.0

◆ tiepie_hw_devicelistitem_open_oscilloscope()

TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelistitem_open_oscilloscope ( tiepie_hw_handle  handle)

Open an oscilloscope and get a handle to the oscilloscope.

Parameters
[in]handleA handle identifying the object.
Returns
A device handle, or TIEPIE_HW_HANDLE_INVALID on error.
Status values
TIEPIE_HW_STATUS_INITIALIZATION_FAILED
TIEPIE_HW_STATUS_INVALID_EEPROM
TIEPIE_HW_STATUS_INVALID_FIRMWARE
TIEPIE_HW_STATUS_INVALID_VALUE The value of Id_kind is invalid.
TIEPIE_HW_STATUS_UNSUCCESSFUL The device is already open or an other error occured.
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS
Examples
tiepie_hw_handle scp = tiepie_hw_devicelistitem_open_oscilloscope(devicelist_item_handle); // Try to open oscilloscope at device list index 4.
tiepie_hw_object_close(devicelist_item_handle);
TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelistitem_open_oscilloscope(tiepie_hw_handle handle)
Open an oscilloscope and get a handle to the oscilloscope.
tiepie_hw_handle scp = tiepie_hw_devicelistitem_open_oscilloscope(devicelist_item_handle); // Try to open oscilloscope with serial number 27917.
tiepie_hw_object_close(devicelist_item_handle);
tiepie_hw_handle scp = tiepie_hw_devicelistitem_open_oscilloscope(devicelist_item_handle); // Try to open a Handyscope HS5 oscilloscope.
tiepie_hw_object_close(devicelist_item_handle);
See also
tiepie_hw_devicelistitem_open_device
tiepie_hw_devicelistitem_open_generator
tiepie_hw_object_close
Since
1.0

◆ tiepie_hw_devicelistitem_open_generator()

TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelistitem_open_generator ( tiepie_hw_handle  handle)

Open a generator and get a handle to the generator.

Parameters
[in]handleA handle identifying the object.
Returns
A device handle, or TIEPIE_HW_HANDLE_INVALID on error.
Status values
TIEPIE_HW_STATUS_INITIALIZATION_FAILED
TIEPIE_HW_STATUS_INVALID_EEPROM
TIEPIE_HW_STATUS_INVALID_FIRMWARE
TIEPIE_HW_STATUS_INVALID_VALUE The value of Id_kind is invalid.
TIEPIE_HW_STATUS_UNSUCCESSFUL The device is already open or an other error occured.
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS
Examples
tiepie_hw_handle gen = tiepie_hw_devicelistitem_open_generator(devicelist_item_handle); // Try to open generator at device list index 2.
tiepie_hw_object_close(devicelist_item_handle);
TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelistitem_open_generator(tiepie_hw_handle handle)
Open a generator and get a handle to the generator.
tiepie_hw_handle gen = tiepie_hw_devicelistitem_open_generator(devicelist_item_handle); // Try to open generator with serial number 22110.
tiepie_hw_object_close(devicelist_item_handle);
tiepie_hw_handle gen = tiepie_hw_devicelistitem_open_generator(devicelist_item_handle); // Try to open a Handyscope HS5 generator.
tiepie_hw_object_close(devicelist_item_handle);
See also
tiepie_hw_devicelistitem_open_device
tiepie_hw_devicelistitem_open_oscilloscope
tiepie_hw_object_close
Since
1.0

◆ tiepie_hw_devicelist_get_demo_device_info()

TIEPIE_HW_API const tiepie_hw_demo_info* tiepie_hw_devicelist_get_demo_device_info ( void  )

Get list of available demo devices.

Returns
A list of available demo devices.
Since
1.0
Example
if(item)
for(; item->product_id != TIEPIE_HW_PRODUCTID_NONE; item++)
printf("name: %s, name_short: %s, product_id: %d\n", item->name, item->name_short, item->product_id);
TIEPIE_HW_API const tiepie_hw_demo_info * tiepie_hw_devicelist_get_demo_device_info(void)
Get list of available demo devices.
@ TIEPIE_HW_PRODUCTID_NONE
Unknown/invalid TIEPIE_HW_ID.
Definition: libtiepie-hw.h:1783
Definition: libtiepie-hw.h:1865
const char * name
Definition: libtiepie-hw.h:1867
const char * name_short
Definition: libtiepie-hw.h:1868
tiepie_hw_productid product_id
Definition: libtiepie-hw.h:1866

◆ tiepie_hw_devicelist_create_demo_device()

TIEPIE_HW_API uint32_t tiepie_hw_devicelist_create_demo_device ( tiepie_hw_productid  product_id)

Create a demo instrument.

Parameters
[in]product_idThe product ID of the demo instrument to create
Returns
Serial number of the demo device, or zero on error.
Since
1.0

◆ tiepie_hw_devicelist_create_combined_device()

TIEPIE_HW_API uint32_t tiepie_hw_devicelist_create_combined_device ( const tiepie_hw_handle handles,
uint32_t  count 
)

Create a combined instrument.

This function creates combined instrument from the indicated devices.

Parameters
[in]handlesPointer to an array of handles of the devices to combine.
[in]countThe number of device handles.
Returns
Serial number of the combined device, or zero on error.
Status values
TIEPIE_HW_STATUS_NOT_SUPPORTED Combining is not supported.
TIEPIE_HW_STATUS_INVALID_HANDLE One or more device handles are invalid or incompatible.
TIEPIE_HW_STATUS_INVALID_VALUE p_device_handles must be != NULL and the number of device handles must be >= 2.
TIEPIE_HW_STATUS_OBJECT_GONE One or more devices indicated by the device handles is no longer available.
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS
See also
tiepie_hw_devicelist_create_and_open_combined_device
Since
1.0

◆ tiepie_hw_devicelist_create_and_open_combined_device()

TIEPIE_HW_API tiepie_hw_handle tiepie_hw_devicelist_create_and_open_combined_device ( const tiepie_hw_handle handles,
uint32_t  count 
)

Create and open a combined instrument.

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

Parameters
[in]handlesPointer to an array of handles of the devices to combine.
[in]countThe number of device handles.
Returns
A device handle, or TIEPIE_HW_HANDLE_INVALID on error.
Status values
TIEPIE_HW_STATUS_NOT_SUPPORTED Combining is not supported.
TIEPIE_HW_STATUS_INVALID_HANDLE One or more device handles are invalid or incompatible.
TIEPIE_HW_STATUS_INVALID_VALUE p_device_handles must be != NULL and the number of device handles must be >= 2.
TIEPIE_HW_STATUS_OBJECT_GONE One or more devices indicated by the device handles is no longer available.
TIEPIE_HW_STATUS_UNSUCCESSFUL
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS
See also
tiepie_hw_devicelist_create_combined_device
Since
1.0

◆ tiepie_hw_devicelist_remove_device()

TIEPIE_HW_API void tiepie_hw_devicelist_remove_device ( uint32_t  serial_number,
tiepie_hw_bool  force 
)

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

Parameters
[in]serial_numberSerial number of the device to remove.
[in]forceForce the removal, even when the device is open.
Status values
TIEPIE_HW_STATUS_UNSUCCESSFUL Device is still open?
TIEPIE_HW_STATUS_NOT_SUPPORTED Device can't be removed from the list. To remove a combined Handyscope HS5, unplug the coupling cable and call tiepie_hw_devicelist_update().
TIEPIE_HW_STATUS_INVALID_DEVICE_SERIALNUMBER
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS
Since
1.0

◆ tiepie_hw_devicelist_remove_unused_devices()

TIEPIE_HW_API void tiepie_hw_devicelist_remove_unused_devices ( void  )

Remove unused instruments from the device list so they can be used by other applications.

Status values
TIEPIE_HW_STATUS_LIBRARY_NOT_INITIALIZED
TIEPIE_HW_STATUS_SUCCESS
Since
1.0