GUsb.Device¶

Subclasses:: None

Methods¶

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

class	`error_quark` ()
	`add_tag` (tag)
	`bulk_transfer` (endpoint, data, timeout, cancellable)
	`bulk_transfer_async` (endpoint, data, timeout, cancellable, callback, *user_data)
	`bulk_transfer_finish` (res)
	`claim_interface` (iface, flags)
	`clear_events` ()
	`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_bos_descriptor` (capability)
	`get_bos_descriptors` ()
	`get_bus` ()
	`get_children` ()
	`get_configuration` ()
	`get_configuration_index` ()
	`get_created` ()
	`get_custom_index` (class_id, subclass_id, protocol_id)
	`get_device_class` ()
	`get_device_protocol` ()
	`get_device_subclass` ()
	`get_events` ()
	`get_hid_descriptor_default` ()
	`get_hid_descriptors` ()
	`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_string_descriptor_bytes` (desc_index, langid)
	`get_string_descriptor_bytes_full` (desc_index, langid, length)
	`get_tags` ()
	`get_vid` ()
	`get_vid_as_str` ()
	`has_tag` (tag)
	`interrupt_transfer` (endpoint, data, timeout, cancellable)
	`interrupt_transfer_async` (endpoint, data, timeout, cancellable, callback, *user_data)
	`interrupt_transfer_finish` (res)
	`invalidate` ()
	`is_emulated` ()
	`open` ()
	`release_interface` (iface, flags)
	`remove_tag` (tag)
	`reset` ()
	`set_configuration` (configuration)
	`set_interface_alt` (iface, 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_instance	`GObject.Object`	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

Added in version 0.1.0.

add_tag(tag)¶

Parameters:: tag (str) – a tag, for example bootloader or runtime-reload

Adds a tag, which is included in the JSON log to identify the specific device.

For instance, there might be a pre-update runtime, a bootloader and a post-update runtime and allowing tags to be saved to the backend object allows us to identify each version of the same physical device.

Added in version 0.4.1.

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 milliseconds) 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.

Added 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 milliseconds) 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

Added 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.

Added in version 0.1.0.

claim_interface(iface, flags)¶

Parameters:

iface (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.

Added in version 0.1.0.

clear_events()¶: Clear all the events saved by the device.

Added in version 0.4.4.

close()¶

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

Closes the device when it is no longer required.

Added 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 milliseconds) 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.

Added 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 milliseconds) 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

Added 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.

Added in version 0.1.0.

get_address()¶

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

Gets the USB address for the device.

Added in version 0.1.0.

get_bos_descriptor(capability)¶

Parameters:: capability (int) – a BOS capability type
Raises:: GLib.Error
Returns:: a GUsb.BosDescriptor or None for not found
Return type:: GUsb.BosDescriptor

Gets the first bos_descriptor that matches the descriptor capability. If you want to find all the BOS descriptors that match (there may be other matching BOS descriptors you have to use g_usb_device_get_bos_descriptors() and check each one manually.

Added in version 0.4.0.

get_bos_descriptors()¶

Raises:: GLib.Error
Returns:: an array of BOS descriptors
Return type:: [GUsb.BosDescriptor]

Gets all the BOS descriptors exported by the device.

The first time this method is used the hardware is queried and then after that cached results are returned. To invalidate the caches use GUsb.Device.invalidate().

Added in version 0.4.0.

get_bus()¶

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

Gets the USB bus number for the device.

Added in version 0.1.0.

get_children()¶

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

Gets the device children if any exist.

Added 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.

Added 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.

Added in version 0.3.5.

get_created()¶

Returns:: a GLib.DateTime
Return type:: GLib.DateTime

Gets the date and time that the GUsb.Device was created.

This can be used as an indicator if the device replugged, as the vendor and product IDs may not change for some devices. Use g_date_time_equal() to verify equality.

Added in version 0.4.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.

Added 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.

Added 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().

Added 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().

Added in version 0.2.4.

get_events()¶

Returns:: an array of events
Return type:: [GUsb.DeviceEvent]

Gets all the events saved by the device.

Events are only collected when the G_USB_CONTEXT_FLAGS_SAVE_EVENTS flag is used before enumerating the context. Events can be used to replay device transactions.

Added in version 0.4.0.

get_hid_descriptor_default()¶

Raises:: GLib.Error
Returns:: a HID descriptor, or None
Return type:: GLib.Bytes

Gets the default HID descriptors exported by the device.

If more than one interface exports a HID descriptor, use GUsb.Device.get_hid_descriptors() instead.

Added in version 0.4.7.

get_hid_descriptors()¶

Raises:: GLib.Error
Returns:: an array of HID descriptors
Return type:: [GLib.Bytes]

Gets all the HID descriptors exported by the device.

The first time this method is used the hardware is queried and then after that cached results are returned. To invalidate the caches use GUsb.Device.invalidate().

Added in version 0.4.7.

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.

Added 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.

The first time this method is used the hardware is queried and then after that cached results are returned. To invalidate the caches use GUsb.Device.invalidate().

Added in version 0.2.8.

get_manufacturer_index()¶

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

Gets the index for the Manufacturer string descriptor.

Added in version 0.1.0.

get_parent()¶

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

Gets the device parent if one exists.

Added in version 0.2.4.

get_pid()¶

Returns:: an ID.
Return type:: int

Gets the product ID for the device.

Added 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.

Added 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.

Added 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.

Added in version 0.2.4.

get_product_index()¶

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

Gets the index for the Product string descriptor.

Added 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.

Added 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.

Added 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

Added 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.

Added in version 0.1.0.

get_string_descriptor_bytes(desc_index, langid)¶

Parameters:

desc_index (int) – the index for the string descriptor to retrieve
langid (int) – the language ID

Raises:

GLib.Error

Returns:

a possibly UTF-16 string, or None on error.

Return type:

GLib.Bytes

Get a raw string descriptor from the device. The returned string should be freed with GLib.Bytes.unref() when no longer needed. The descriptor will be at most 128 btes in length, if you need to issue a request with either a smaller or larger descriptor, you can use GUsb.Device.get_string_descriptor_bytes_full instead.

Added in version 0.3.6.

get_string_descriptor_bytes_full(desc_index, langid, length)¶

Parameters:

desc_index (int) – the index for the string descriptor to retrieve
langid (int) – the language ID
length (int) – size of the request data buffer

Raises:

GLib.Error

Returns:

a possibly UTF-16 string, or None on error.

Return type:

GLib.Bytes

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

Added in version 0.3.8.

get_tags()¶

Returns:: string tags
Return type:: [str]

Gets all the tags.

Added in version 0.4.4.

get_vid()¶

Returns:: an ID.
Return type:: int

Gets the vendor ID for the device.

Added 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.

Added in version 0.2.4.

has_tag(tag)¶

Parameters:: tag (str) – a tag, for example bootloader or runtime-reload
Returns:: True on success
Return type:: bool

Checks if a tag has been used to identify the specific device.

Added in version 0.4.3.

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 milliseconds) 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.

Added 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 milliseconds) 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

Added 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.

Added in version 0.1.0.

invalidate()¶: Invalidates the caches used in GUsb.Device.get_interfaces().

Added in version 0.4.0.

is_emulated()¶

Returns:: True if the device is emulated and not backed by a physical device.
Return type:: bool

Gets if the device is emulated.

Added in version 0.4.4.

open()¶

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

Opens the device for use.

Warning: this function is synchronous.

Added in version 0.1.0.

release_interface(iface, flags)¶

Parameters:

iface (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.

Added in version 0.1.0.

remove_tag(tag)¶

Parameters:: tag (str) – a tag, for example bootloader or runtime-reload

Removes a tag, which is included in the JSON log to identify the specific device.

Added in version 0.4.4.

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.

Added 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.

Added in version 0.1.0.

set_interface_alt(iface, alt)¶

Parameters:

iface (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.

Added 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