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.
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.
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.
TIEPIE_HW_API uint32_t	tiepie_hw_devicelist_get_count (void)
	Get the number of devices in the device list.
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.
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.
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.
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.
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_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_API const tiepie_hw_demo_info *	tiepie_hw_devicelist_get_demo_device_info (void)
	Get list of available demo devices.
TIEPIE_HW_API uint32_t	tiepie_hw_devicelist_create_demo_device (tiepie_hw_productid product_id)
	Create a demo instrument.
TIEPIE_HW_API uint32_t	tiepie_hw_devicelist_create_combined_device (const tiepie_hw_handle *handles, uint32_t count)
	Create a combined instrument.
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.
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.
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.

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.

• Open by device list index, e.g.:

  tiepie_hw_handle devicelist_item_handle = tiepie_hw_devicelist_get_item_by_index(4);
  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);

• Open by serial number, e.g.:

  tiepie_hw_handle devicelist_item_handle = tiepie_hw_devicelist_get_item_by_serial_number(22110);
  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);

• Open by product id, e.g.:

  tiepie_hw_handle devicelist_item_handle = tiepie_hw_devicelist_get_item_by_product_id(TIEPIE_HW_PRODUCTID_HS5);
  tiepie_hw_handle scp = tiepie_hw_devicelistitem_open_device(devicelist_item_handle, TIEPIE_HW_DEVICETYPE_OSCILLOSCOPE); // Try to open a Handyscope HS5 oscilloscope.
  tiepie_hw_object_close(devicelist_item_handle);

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

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]

value

TIEPIE_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]	handle	A handle identifying the object.
[in]	device_type	A 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 devicelist_item_handle = tiepie_hw_devicelist_get_item_by_index(4);
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 devicelist_item_handle = tiepie_hw_devicelist_get_item_by_serial_number(22110);
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]

handle

A 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 devicelist_item_handle = tiepie_hw_devicelist_get_item_by_index(4);
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_handle devicelist_item_handle = tiepie_hw_devicelist_get_item_by_serial_number(27917);
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 devicelist_item_handle = tiepie_hw_devicelist_get_item_by_product_id(TIEPIE_HW_PRODUCTID_HS5);
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]

handle

A 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 devicelist_item_handle = tiepie_hw_devicelist_get_item_by_index(2);
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_handle devicelist_item_handle = tiepie_hw_devicelist_get_item_by_serial_number(22110);
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 devicelist_item_handle = tiepie_hw_devicelist_get_item_by_product_id(TIEPIE_HW_PRODUCTID_HS5);
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

const tiepie_hw_demo_info* item = tiepie_hw_devicelist_get_demo_device_info();
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_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_id

The 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]	handles	Pointer to an array of handles of the devices to combine.
[in]	count	The 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]	handles	Pointer to an array of handles of the devices to combine.
[in]	count	The 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_number	Serial number of the device to remove.
[in]	force	Force 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