GUsb.Device

g GObject.GInterface GObject.GInterface Gio.Initable Gio.Initable GObject.GInterface->Gio.Initable GObject.Object GObject.Object GUsb.Device GUsb.Device GObject.Object->GUsb.Device Gio.Initable->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 (interface, 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 (interface, flags)

remove_tag (tag)

reset ()

set_configuration (configuration)

set_interface_alt (interface, alt)

Virtual Methods

Inherited:

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

Properties

Name

Type

Flags

Short Description

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

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

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

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

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:
Raises:

GLib.Error

Returns:

True on success

Return type:

bool

Claim an interface of the device.

New in version 0.1.0.

clear_events()

Clear all the events saved by the device.

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

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

New in version 0.1.0.

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

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

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

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

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

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

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

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

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

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.

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

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

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

New in version 0.3.8.

get_tags()
Returns:

string tags

Return type:

[str]

Gets all the tags.

New in version 0.4.4.

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.

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.

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

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

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.

invalidate()

Invalidates the caches used in GUsb.Device.get_interfaces().

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

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

New in version 0.1.0.

release_interface(interface, flags)
Parameters:
Raises:

GLib.Error

Returns:

True on success

Return type:

bool

Release an interface of the device.

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

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

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