3. Modules: Communication Transports

3.1. Transport (Abstract Base)

class StreamDeck.Transport.Transport.Transport

Bases: ABC

Base transport layer, representing an abstract communication back-end which can be used to discovery attached StreamDeck devices.

class Device

Bases: ABC

Base connection device, representing an abstract connected device which can be communicated with by an upper layer high level protocol.

abstractmethod close() → None: Closes the device for input/output.

See also

See open() for the corresponding open method.

abstractmethod connected() → bool

Indicates if the physical device object this instance is attached to is still connected to the host.

Return type:: bool
Returns:: True if the device is still connected, False otherwise.

abstractmethod is_open() → bool

Indicates if the physical device object this instance is attached to has been opened by the host.

Return type:: bool
Returns:: True if the device is open, False otherwise.

abstractmethod open() → None: Opens the device for input/output. This must be called prior to sending or receiving any reports.

See also

See close() for the corresponding close method.

abstractmethod path() → str

Retrieves the logical path of the attached device within the current system. This can be used to uniquely differentiate one device from another.

Return type:: str
Returns:: Logical device path for the attached device.

abstractmethod product_id() → int

Retrieves the product ID value of the attached device.

Return type:: int
Returns:: Product ID of the attached device.

abstractmethod read(length: int) → bytes

Performs a blocking read of a HID In report from the open HID device.

Parameters:: length (int) – Maximum length of the In report to read.
Return type:: list(byte)
Returns:: List of bytes containing the read In report. The first byte of the report will be the Report ID of the report that was read.

abstractmethod read_feature(report_id: int, length: int) → bytes

Reads a HID Feature report from the open HID device.

Parameters:

report_id (int) – Report ID of the report being read.
length (int) – Maximum length of the Feature report to read.

Return type:

list(byte)

Returns:

List of bytes containing the read Feature report. The first byte of the report will be the Report ID of the report that was read.

abstractmethod vendor_id() → int

Retrieves the vendor ID value of the attached device.

Return type:: int
Returns:: Vendor ID of the attached device.

abstractmethod write(payload: bytes) → int

Sends a HID Out report to the open HID device.

Parameters:: payload (enumerable()) – Enumerate list of bytes to send to the device, as an Out report. The first byte of the report should be the Report ID of the report being sent.
Return type:: int
Returns:: Number of bytes successfully sent to the device.

abstractmethod write_feature(payload: bytes) → int

Sends a HID Feature report to the open HID device.

Parameters:: payload (enumerable()) – Enumerate list of bytes to send to the device, as a feature report. The first byte of the report should be the Report ID of the report being sent.
Return type:: int
Returns:: Number of bytes successfully sent to the device.

abstractmethod enumerate(vid: int, pid: int) → list[Device]

Enumerates all available devices on the system using the current transport back-end.

Parameters:

vid (int) – USB Vendor ID to filter all devices by, None if the device list should not be filtered by vendor.
pid (int) – USB Product ID to filter all devices by, None if the device list should not be filtered by product.

Return type:

list(Transport.Device)

Returns:

List of discovered devices that are available through this transport back-end.

abstractmethod static probe() → None: Attempts to determine if the back-end is installed and usable. It is expected that probe failures throw exceptions detailing their exact cause of failure.

exception StreamDeck.Transport.Transport.TransportError

Bases: Exception

Exception thrown when attempting to access a device using a backend transport that has failed (for example, if the requested device could not be accessed).

3.2. ‘LibUSB HIDAPI’ Library Transport

class StreamDeck.Transport.LibUSBHIDAPI.LibUSBHIDAPI

Bases: Transport

USB HID transport layer, using the LibUSB HIDAPI dynamically linked library directly via ctypes.

class Device(hidapi, device_info)

Bases: Device

close(): Closes the device for input/output.

See also

See open() for the corresponding open method.

connected()

Indicates if the physical device object this instance is attached to is still connected to the host.

Return type:: bool
Returns:: True if the device is still connected, False otherwise.

is_open()

Indicates if the physical device object this instance is attached to has been opened by the host.

Return type:: bool
Returns:: True if the device is open, False otherwise.

open(): Opens the device for input/output. This must be called prior to sending or receiving any reports.

See also

See close() for the corresponding close method.

path()

Retrieves the logical path of the attached device within the current system. This can be used to uniquely differentiate one device from another.

Return type:: str
Returns:: Logical device path for the attached device.

product_id()

Retrieves the product ID value of the attached device.

Return type:: int
Returns:: Product ID of the attached device.

read(length)

Performs a blocking read of a HID In report from the open HID device.

Parameters:: length (int) – Maximum length of the In report to read.
Return type:: list(byte)
Returns:: List of bytes containing the read In report. The first byte of the report will be the Report ID of the report that was read.

read_feature(report_id, length)

Reads a HID Feature report from the open HID device.

Parameters:

report_id (int) – Report ID of the report being read.
length (int) – Maximum length of the Feature report to read.

Return type:

list(byte)

Returns:

List of bytes containing the read Feature report. The first byte of the report will be the Report ID of the report that was read.

vendor_id()

Retrieves the vendor ID value of the attached device.

Return type:: int
Returns:: Vendor ID of the attached device.

write(payload)

Sends a HID Out report to the open HID device.

Parameters:: payload (enumerable()) – Enumerate list of bytes to send to the device, as an Out report. The first byte of the report should be the Report ID of the report being sent.
Return type:: int
Returns:: Number of bytes successfully sent to the device.

write_feature(payload)

Sends a HID Feature report to the open HID device.

Parameters:: payload (enumerable()) – Enumerate list of bytes to send to the device, as a feature report. The first byte of the report should be the Report ID of the report being sent.
Return type:: int
Returns:: Number of bytes successfully sent to the device.

enumerate(vid, pid)

Enumerates all available devices on the system using the current transport back-end.

Parameters:

vid (int) – USB Vendor ID to filter all devices by, None if the device list should not be filtered by vendor.
pid (int) – USB Product ID to filter all devices by, None if the device list should not be filtered by product.

Return type:

list(Transport.Device)

Returns:

List of discovered devices that are available through this transport back-end.

static probe(): Attempts to determine if the back-end is installed and usable. It is expected that probe failures throw exceptions detailing their exact cause of failure.