GUsb.Device¶

Subclasses:	None

Methods¶

Inherited:	GObject.Object (37), Gio.Initable (2)
Structs:	GObject.ObjectClass (5)

class	`error_quark` ()
	`bulk_transfer` (endpoint, data, timeout, cancellable)
	`bulk_transfer_async` (endpoint, data, timeout, cancellable, callback, *user_data)
	`bulk_transfer_finish` (res)
	`claim_interface` (interface, flags)
	`close` ()
	`control_transfer` (direction, request_type, recipient, request, value, idx, data, timeout, cancellable)
	`control_transfer_async` (direction, request_type, recipient, request, value, idx, data, timeout, cancellable, callback, *user_data)
	`control_transfer_finish` (res)
	`get_address` ()
	`get_bus` ()
	`get_children` ()
	`get_configuration` ()
	`get_configuration_index` ()
	`get_custom_index` (class_id, subclass_id, protocol_id)
	`get_device_class` ()
	`get_device_protocol` ()
	`get_device_subclass` ()
	`get_interface` (class_id, subclass_id, protocol_id)
	`get_interfaces` ()
	`get_manufacturer_index` ()
	`get_parent` ()
	`get_pid` ()
	`get_pid_as_str` ()
	`get_platform_id` ()
	`get_port_number` ()
	`get_product_index` ()
	`get_release` ()
	`get_serial_number_index` ()
	`get_spec` ()
	`get_string_descriptor` (desc_index)
	`get_vid` ()
	`get_vid_as_str` ()
	`interrupt_transfer` (endpoint, data, timeout, cancellable)
	`interrupt_transfer_async` (endpoint, data, timeout, cancellable, callback, *user_data)
	`interrupt_transfer_finish` (res)
	`open` ()
	`release_interface` (interface, flags)
	`reset` ()
	`set_configuration` (configuration)
	`set_interface_alt` (interface, alt)

Virtual Methods¶

Inherited:	GObject.Object (7), Gio.Initable (1)

Properties¶

Name	Type	Flags
`context`	`GUsb.Context`	w/co
`libusb-device`	`int`	r/w/co
`platform-id`	`str`	w/co

Signals¶

Inherited:	GObject.Object (1)

Fields¶

Inherited:	GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r
priv	`GUsb.DevicePrivate`	r

Class Details¶

class GUsb.Device(**kwargs)¶

Bases:	`GObject.Object`, `Gio.Initable`
Abstract:	No
Structure:	`GUsb.DeviceClass`

classmethod error_quark()¶

Returns:	Our personal error quark.
Return type:	`int`

New in version 0.1.0.

bulk_transfer(endpoint, data, timeout, cancellable)¶

Parameters:

endpoint (int) – the address of a valid endpoint to communicate with
data (bytes) – a suitably-sized data buffer for either input or output
timeout (int) – timeout timeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use 0.
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None

Raises:

GLib.Error

Returns:

True on success

actual_length:	the actual number of bytes sent, or `None`

Return type:

(bool, actual_length: int)

Perform a USB bulk transfer.

Warning: this function is synchronous, and cannot be cancelled.

New in version 0.1.0.

bulk_transfer_async(endpoint, data, timeout, cancellable, callback, *user_data)¶

Parameters:

endpoint (int) – the address of a valid endpoint to communicate with
data (bytes) – a suitably-sized data buffer for either input or output
timeout (int) – timeout timeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use 0.
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None
callback (Gio.AsyncReadyCallback or None) – the function to run on completion
user_data (object or None) – the data to pass to callback

Do an async bulk transfer

New in version 0.1.0.

bulk_transfer_finish(res)¶

Parameters:	res (`Gio.AsyncResult`) – the `Gio.AsyncResult`
Raises:	`GLib.Error`
Returns:	the actual number of bytes sent, or -1 on error.
Return type:	`int`

Gets the result from the asynchronous function.

New in version 0.1.0.

claim_interface(interface, flags)¶

Parameters:	interface (`int`) – bInterfaceNumber of the interface you wish to claim flags (`GUsb.DeviceClaimInterfaceFlags`) – `GUsb.DeviceClaimInterfaceFlags`
Raises:	`GLib.Error`
Returns:	`True` on success
Return type:	`bool`

Claim an interface of the device.

New in version 0.1.0.

close()¶

Raises:	`GLib.Error`
Returns:	`True` on success
Return type:	`bool`

Closes the device when it is no longer required.

New in version 0.1.0.

control_transfer(direction, request_type, recipient, request, value, idx, data, timeout, cancellable)¶

Parameters:

direction (GUsb.DeviceDirection) –
request_type (GUsb.DeviceRequestType) – the request type field for the setup packet
recipient (GUsb.DeviceRecipient) –
request (int) – the request field for the setup packet
value (int) – the value field for the setup packet
idx (int) – the index field for the setup packet
data (bytes) – a suitably-sized data buffer for either input or output
timeout (int) – timeout timeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use 0.
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None

Raises:

GLib.Error

Returns:

True on success

actual_length:	the actual number of bytes sent, or `None`

Return type:

(bool, actual_length: int)

Perform a USB control transfer.

Warning: this function is synchronous, and cannot be cancelled.

New in version 0.1.0.

control_transfer_async(direction, request_type, recipient, request, value, idx, data, timeout, cancellable, callback, *user_data)¶

Parameters:

direction (GUsb.DeviceDirection) –
request_type (GUsb.DeviceRequestType) –
recipient (GUsb.DeviceRecipient) –
request (int) –
value (int) –
idx (int) –
data (bytes) – a suitably-sized data buffer for either input or output
timeout (int) – timeout timeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use 0.
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None
callback (Gio.AsyncReadyCallback or None) – the function to run on completion
user_data (object or None) – the data to pass to callback

Do an async control transfer

New in version 0.1.0.

control_transfer_finish(res)¶

Parameters:	res (`Gio.AsyncResult`) – the `Gio.AsyncResult`
Raises:	`GLib.Error`
Returns:	the actual number of bytes sent, or -1 on error.
Return type:	`int`

Gets the result from the asynchronous function.

New in version 0.1.0.

get_address()¶

Returns:	The 8-bit address
Return type:	`int`

Gets the USB address for the device.

New in version 0.1.0.

get_bus()¶

Returns:	The 8-bit bus number
Return type:	`int`

Gets the USB bus number for the device.

New in version 0.1.0.

get_children()¶

Returns:	an array of `GUsb.Device`
Return type:	[`GUsb.Device`]

Gets the device children if any exist.

New in version 0.2.4.

get_configuration()¶

Raises:	`GLib.Error`
Returns:	The bConfigurationValue of the active config, or -1 on error
Return type:	`int`

Get the bConfigurationValue for the active configuration of the device.

Warning: this function is synchronous.

New in version 0.1.0.

get_configuration_index()¶

Returns:	a string descriptor index.
Return type:	`int`

Get the index for the active Configuration string descriptor ie, iConfiguration.

New in version 0.3.5.

get_custom_index(class_id, subclass_id, protocol_id)¶

Parameters:	class_id (`int`) – a device class, e.g. 0xff for VENDOR subclass_id (`int`) – a device subclass protocol_id (`int`) – a protocol number
Raises:	`GLib.Error`
Returns:	a non-zero index, or 0x00 for failure
Return type:	`int`

Gets the string index from the vendor class interface descriptor.

New in version 0.2.5.

get_device_class()¶

Returns:	a device class number, e.g. 0x09 is a USB hub.
Return type:	`int`

Gets the device class, typically a GUsb.DeviceClassCode.

New in version 0.1.7.

get_device_protocol()¶

Returns:	a device protocol number.
Return type:	`int`

Gets the device protocol qualified by the class and subclass numbers. See GUsb.Device.get_device_class() and GUsb.Device.get_device_subclass().

New in version 0.2.4.

get_device_subclass()¶

Returns:	a device subclass number.
Return type:	`int`

Gets the device subclass qualified by the class number. See GUsb.Device.get_device_class().

New in version 0.2.4.

get_interface(class_id, subclass_id, protocol_id)¶

Parameters:	class_id (`int`) – a device class, e.g. 0xff for VENDOR subclass_id (`int`) – a device subclass protocol_id (`int`) – a protocol number
Raises:	`GLib.Error`
Returns:	a `GUsb.Interface` or `None` for not found
Return type:	`GUsb.Interface`

Gets the first interface that matches the vendor class interface descriptor. If you want to find all the interfaces that match (there may be other ‘alternate’ interfaces you have to use GUsb.Device.get_interfaces() and check each one manally.

New in version 0.2.8.

get_interfaces()¶

Raises:	`GLib.Error`
Returns:	an array of interfaces or `None` for error
Return type:	[`GUsb.Interface`]

Gets all the interfaces exported by the device.

New in version 0.2.8.

get_manufacturer_index()¶

Returns:	a string descriptor index.
Return type:	`int`

Gets the index for the Manufacturer string descriptor.

New in version 0.1.0.

get_parent()¶

Returns:	`GUsb.Device` or `None`
Return type:	`GUsb.Device`

Gets the device parent if one exists.

New in version 0.2.4.

get_pid()¶

Returns:	an ID.
Return type:	`int`

Gets the product ID for the device.

New in version 0.1.0.

get_pid_as_str()¶

Returns:	an string ID, or `None` if not available.
Return type:	`str`

Gets the product ID for the device as a string.

New in version 0.2.4.

get_platform_id()¶

Returns:	The platform ID, e.g. “usb:02:00:03:01”
Return type:	`str`

Gets the platform identifier for the device.

When the device is removed and then replugged, this value is not expected to be different.

New in version 0.1.1.

get_port_number()¶

Returns:	The 8-bit port number
Return type:	`int`

Gets the USB port number for the device.

New in version 0.2.4.

get_product_index()¶

Returns:	a string descriptor index.
Return type:	`int`

Gets the index for the Product string descriptor.

New in version 0.1.0.

get_release()¶

Returns:	a version number in BCD format.
Return type:	`int`

Gets the BCD firmware version number for the device.

New in version 0.2.8.

get_serial_number_index()¶

Returns:	a string descriptor index.
Return type:	`int`

Gets the index for the Serial Number string descriptor.

New in version 0.1.0.

get_spec()¶

Returns:	a specification revision in BCD format.
Return type:	`int`

Gets the BCD specification revision for the device. For example, 0x0110 indicates USB 1.1 and 0x0320 indicates USB 3.2

New in version 0.3.1.

get_string_descriptor(desc_index)¶

Parameters:	desc_index (`int`) – the index for the string descriptor to retrieve
Raises:	`GLib.Error`
Returns:	a newly-allocated string holding the descriptor, or `None` on error.
Return type:	`str`

Get a string descriptor from the device. The returned string should be freed with GLib.free() when no longer needed.

New in version 0.1.0.

get_vid()¶

Returns:	an ID.
Return type:	`int`

Gets the vendor ID for the device.

New in version 0.1.0.

get_vid_as_str()¶

Returns:	an string ID, or `None` if not available.
Return type:	`str`

Gets the vendor ID for the device as a string.

New in version 0.2.4.

interrupt_transfer(endpoint, data, timeout, cancellable)¶

Parameters:

endpoint (int) – the address of a valid endpoint to communicate with
data (bytes) – a suitably-sized data buffer for either input or output
timeout (int) – timeout timeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use 0.
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None

Raises:

GLib.Error

Returns:

True on success

actual_length:	the actual number of bytes sent, or `None`

Return type:

(bool, actual_length: int)

Perform a USB interrupt transfer.

Warning: this function is synchronous, and cannot be cancelled.

New in version 0.1.0.

interrupt_transfer_async(endpoint, data, timeout, cancellable, callback, *user_data)¶

Parameters:

endpoint (int) – the address of a valid endpoint to communicate with
data (bytes) – a suitably-sized data buffer for either input or output
timeout (int) – timeout timeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use 0.
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None
callback (Gio.AsyncReadyCallback or None) – the function to run on completion
user_data (object or None) – the data to pass to callback

Do an async interrupt transfer

New in version 0.1.0.

interrupt_transfer_finish(res)¶

Parameters:	res (`Gio.AsyncResult`) – the `Gio.AsyncResult`
Raises:	`GLib.Error`
Returns:	the actual number of bytes sent, or -1 on error.
Return type:	`int`

Gets the result from the asynchronous function.

New in version 0.1.0.

open()¶

Raises:	`GLib.Error`
Returns:	`True` on success
Return type:	`bool`

Opens the device for use.

Warning: this function is synchronous.

New in version 0.1.0.

release_interface(interface, flags)¶

Parameters:	interface (`int`) – bInterfaceNumber of the interface you wish to release flags (`GUsb.DeviceClaimInterfaceFlags`) – `GUsb.DeviceClaimInterfaceFlags`
Raises:	`GLib.Error`
Returns:	`True` on success
Return type:	`bool`

Release an interface of the device.

New in version 0.1.0.

reset()¶

Raises:	`GLib.Error`
Returns:	`True` on success
Return type:	`bool`

Perform a USB port reset to reinitialize a device.

If the reset succeeds, the device will appear to disconnected and reconnected. This means the self will no longer be valid and should be closed and rediscovered.

This is a blocking function which usually incurs a noticeable delay.

New in version 0.1.0.

set_configuration(configuration)¶

Parameters:	configuration (`int`) – the configuration value to set
Raises:	`GLib.Error`
Returns:	`True` on success
Return type:	`bool`

Set the active bConfigurationValue for the device.

Warning: this function is synchronous.

New in version 0.1.0.

set_interface_alt(interface, alt)¶

Parameters:	interface (`int`) – bInterfaceNumber of the interface you wish to release alt (`int`) – alternative setting number
Raises:	`GLib.Error`
Returns:	`True` on success
Return type:	`bool`

Sets an alternate setting on an interface.

New in version 0.2.8.

Property Details¶

GUsb.Device.props.context¶

Name:	`context`
Type:	`GUsb.Context`
Default Value:	`None`
Flags:	`WRITABLE`, `CONSTRUCT_ONLY`

GUsb.Device.props.libusb_device¶

Name:	`libusb-device`
Type:	`int`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

GUsb.Device.props.platform_id¶

Name:	`platform-id`
Type:	`str`
Default Value:	`None`
Flags:	`WRITABLE`, `CONSTRUCT_ONLY`