DeviceRegistry (Class)

class usbx.DeviceRegistry

USB device registry.

The registry maintains a list of connected USB devices. It can notify a client about connected and disconnected USB devices.

All methods consistently return the same Device instance for the same physical USB device as long as it is plugged in.

find_device(match: Callable[[Device], bool] = None, **kwargs) → Device | None

Find the first USB device matching the specified criteria.

Criteria can be specified as keyword arguments. They match the properties of the Device class, i.e. vid, pid, manufacturer, product, serial:

find_device(vid=0x1234, product='Webcam ABC')

Alternatively, a matching function taking a Device object as the single parameter can be specified:

find_device(lambda device: device.vid == 0x1234)

If both criteria and a matching function are specified, both must match.

Parameters:

  • match – Lambda function testing if a device matches.

  • kwargs – Keywords arguments specifying matching criteria as property name/value pairs.

Returns:

Matching Device object or None.

find_devices(match: Callable[[Device], bool] = None, **kwargs) → list[Device]

Find USB devices matching the specified criteria.

Criteria can be specified as keyword arguments. They match the properties of the Device class, i.e. vid, pid, manufacturer, product, serial:

find_devices(vid=0x1234, product='Webcam ABC')

Alternatively, a matching function taking a Device object as the single parameter can be specified:

find_devices(lambda device: device.vid == 0x1234)

If both criteria and a matching function are specified, both must match.

Parameters:

  • match – Lambda function testing if a device matches.

  • kwargs – Keywords arguments specifying matching criteria as property name/value pairs.

Returns:

List of matching Device objects.

get_devices() → list[Device]

Get the list of currently connected USB devices.

Returns:

list of Device objects

on_connected(callback: Callable[[Device], None] | None) → None

Register a function to be called when a USB device is connected.

The function’s only parameter will receive the Device instance that has been connected.

The callback function will be called from a background thread. It should not execute long-running operations as it blocks further notifications.

Parameters:

callback – Function to be called, or None to cancel callbacks.

on_disconnected(callback: Callable[[Device], None] | None) → None

Register a function to be called when a USB device has been disconnected.

The function’s only parameter will receive the Device instance that has been disconnected. Even though the device has been connected, the instance retains the descriptive information about the device.

The callback function will be called from a background thread. It should not execute long-running operations as it blocks further notifications.

Parameters:

callback – Function to be called, or None to cancel callbacks.