3. Modules: Communication Transports
3.1. Transport (Abstract Base)
- class StreamDeck.Transport.Transport.Transport
Base transport layer, representing an abstract communication back-end which can be used to discovery attached StreamDeck devices.
- class Device
Base connection device, representing an abstract connected device which can be communicated with by an upper layer high level protocol.
- abstract close()
Closes the device for input/output.
See also
See
open()
for the corresponding open method.
- abstract 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.
- abstract 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.
- abstract 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.
- abstract 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.
- abstract 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.
- abstract 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.
- abstract 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.
- abstract 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.
- abstract 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.
- abstract 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.
- exception StreamDeck.Transport.Transport.TransportError
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:
StreamDeck.Transport.Transport.Transport
USB HID transport layer, using the LibUSB HIDAPI dynamically linked library directly via ctypes.
- class Device(hidapi, device_info)
Bases:
StreamDeck.Transport.Transport.Transport.Device
Creates a new HID device instance, used to send and receive HID reports from/to an attached USB HID device.
- Parameters
device_info (dict()) – Device information dictionary describing a single unique attached USB HID device.
- close()
Closes the HID device for input/output.
See also
See
open()
for the corresponding open method.
- connected()
Indicates if the physical HID device 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 HID device for input/output. This must be called prior to sending or receiving any HID reports.
See also
See
close()
for the corresponding close method.
- path()
Retrieves the logical path of the attached HID device within the current system. This can be used to differentiate one HID device from another.
- Return type
str
- Returns
Logical device path for the attached device.
- read(length)
Performs a non-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.
- 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 USB HID devices on the system.
- 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(HID.Device)
- Returns
List of discovered USB HID devices.
- 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.