Device Enumeration

This section describes device enumeration, querying information about attached devices and their connection topology.

Simple Device Enumeration

The simplest way to gather information about the available video capture devices is querying DeviceEnum.devices(). The class method returns a flat list of DeviceInfo objects.

The following code snippet shows how to get the list of devices and print device information to the console:

def print_device_list():
    print("Enumerating all attached video capture devices...")

    device_list = ic4.DeviceEnum.devices()

    if len(device_list) == 0:
        print("No devices found")
        return

    print(f"Found {len(device_list)} devices:")

    for device_info in device_list:
        print(format_device_info(device_info))

The device information is printed using a simple helper function:

def format_device_info(device_info: ic4.DeviceInfo) -> str:
    return f"Model: {device_info.model_name} Serial: {device_info.serial}"

Query Interface/Device Topology

Device enumeration can also be performed on a per-interface basis. Interfaces are the physical pieces of hardware that cameras are attached to, e.g. USB controllers or network adapters.

To get a list of the available interfaces in the system, query DeviceEnum.interfaces(). Each interface can in turn be queried for the currently attached video capture devices using Interface.devices.

The following code snippet shows how to get the list of interfaces. It then prints interface information and device information to the console:

def print_interface_device_tree():
    print("Enumerating video capture devices by interface...")

    interface_list = ic4.DeviceEnum.interfaces()

    if len(interface_list) == 0:
        print("No interfaces found")
        return

    for itf in interface_list:
        print(f"Interface: {itf.display_name}")
        print(f"\tProvided by {itf.transport_layer_name} [TLType: {str(itf.transport_layer_type)}]")

        device_list = itf.devices

        if len(device_list) == 0:
            print("\tNo devices found")
            continue

        print(f"\tFound {len(device_list)} devices:")

        for device_info in device_list:
            print(f"\t\t{format_device_info(device_info)}")

Receiving Device Arrival and Removal Notifications

DeviceEnum objects allow registering an event handler that notifies the program of changes in the list of available devices. To get notified about changes to the connected devices, register a callback function using DeviceEnum.event_add_device_list_changed().

The following code snippet shows how to register and finally unregister a device-list-changed event handler:

def example_device_list_changed():
    enumerator = ic4.DeviceEnum()

    token = enumerator.event_add_device_list_changed(handle_device_list_changed)

    print("Waiting for DeviceListChanged event")
    print("Press Enter to exit")
    input()

    # Technically, this is not necessary, because the enumerator object is deleted when the function is exited
    # But for demonstration purposes, the event handler is removed:
    enumerator.event_remove_device_list_changed(token)

An example device-list-changed handler can look like this:

def handle_device_list_changed(device_enum: ic4.DeviceEnum):
    print("Device list changed!")

    print(f"Found {len(ic4.DeviceEnum.devices())} devices")

    print(ic4.DeviceEnum.devices())