System Requirements

Operating System Support

  • Cross-platform support:
    • Windows: Windows 10/11 (recommended)
    • macOS: macOS 10.5+
    • Linux: Ubuntu 20.04+
  • Python: 3.7+ (3.9+ recommended)

Hardware Requirements

  • USB port (for connecting StreamDock devices)
  • Sufficient memory to run Python applications

Dependency Installation

Python Package Dependencies

The Python StreamDock SDK requires the following Python packages:

Core Dependencies

pip install Pillow

pip install pyusb

Platform-specific Dependencies

Linux Systems

pip install pyudev

Windows Systems

pip install hidapi

macOS Systems

brew install hidapi

System Built-in Modules

The following modules are part of the Python standard library and require no additional installation:

  • threading - Thread support
  • ctypes - C foreign function library
  • time - Time-related functions
  • abc - Abstract base classes
  • os - Operating system interface
  • io - Input/output operations
  • asyncio - Async I/O (for async callbacks)

System Dependencies

Ubuntu/Debian

# Install USB device access support
sudo apt-get update
sudo apt-get install libudev-dev libusb-1.0-0-dev libhidapi-libusb0

# Optional: Install udev rules to allow non-root users to access devices
sudo cp /path/to/sdk/udev-rules/99-streamdock.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

CentOS/RHEL/Fedora

# Install development tools and libraries
sudo yum groupinstall "Development Tools"
sudo yum install libudev-devel libusb1-devel libhidapi-libusb0

# Or use dnf (newer versions)
sudo dnf groupinstall "Development Tools"
sudo dnf install libudev-devel libusb1-devel

Arch Linux

sudo pacman -S libusb libudev libhidapi-libusb0

Installation Methods

# Install from PyPI
pip install streamdock-sdk

# Or install from source
git clone https://github.com/MiraboxSpace/StreamDock-Device-SDK.git
cd StreamDock-Device-SDK/Python-SDK
pip install -e .

Manual Installation

  1. Clone or download SDK source code
  2. Install Python dependencies
  3. Add src directory to Python path
# Download SDK
git clone https://github.com/MiraboxSpace/StreamDock-Device-SDK.git
cd StreamDock-Device-SDK/Python-SDK

# Install dependencies
pip install Pillow pyusb

# Linux additional dependencies
pip install pyudev

# Windows additional dependencies
pip install hidapi

Basic Usage

Import Modules

from StreamDock.DeviceManager import DeviceManager
from StreamDock.ImageHelpers.PILHelper import create_image, to_native_key_format
import threading
import time

Basic Usage Flow

# 1. Create device manager
manager = DeviceManager()

# 2. Start device listening (for hot-plug detection)
listen_thread = threading.Thread(target=manager.listen)
listen_thread.daemon = True
listen_thread.start()

# 3. Enumerate currently connected devices
devices = manager.enumerate()
print(f"Found {len(devices)} StreamDock devices")

# 4. Operate each device
for device in devices:
    try:
        # Open device
        device.open()

        # Initialize device (wake screen, set brightness, clear icons)
        device.init()

        # Set key event callback
        def key_callback(device, key, state):
            action = "pressed" if state else "released"
            print(f"Device {device.getPath()} key {key} {action}")

        device.set_key_callback(key_callback)

        # Set device brightness (0-100)
        device.set_brightness(80)

        # Set background image (ensure image file exists)
        device.set_touchscreen_image("background.jpg")

        # Set key icons
        device.set_key_image(1, "icon1.jpg")
        device.set_key_image(2, "icon2.jpg")

        # Refresh display
        device.refresh()

        # Wait for some time
        time.sleep(5)

    except Exception as e:
        print(f"Error operating device: {e}")

    finally:
        # Close device
        device.close()

Advanced Usage Examples

Create Dynamic Images Using PILHelper

from PIL import Image, ImageDraw, ImageFont
from StreamDock.ImageHelpers.PILHelper import create_image, to_native_key_format

def create_key_image(text, background_color='blue', text_color='white'):
    """Create key image with text"""
    # Create blank image
    image = create_image(device, background=background_color)
    draw = ImageDraw.Draw(image)

    # Load font
    try:
        font = ImageFont.truetype("arial.ttf", 40)
    except:
        font = ImageFont.load_default()

    # Draw text
    bbox = draw.textbbox((0, 0), text, font=font)
    text_width = bbox[2] - bbox[0]
    text_height = bbox[3] - bbox[1]

    x = (image.width - text_width) // 2
    y = (image.height - text_height) // 2

    draw.text((x, y), text, fill=text_color, font=font)

    return image

# Usage example
for key in range(1, min(device.KEY_COUNT + 1, 16)):
    # Create icon with numbers
    image = create_key_image(str(key))

    # Convert to device native format
    native_image = to_native_key_format(device, image)

    # Save temporary file and set to device
    temp_file = f"temp_key_{key}.jpg"
    native_image.save(temp_file, "JPEG", quality=100)
    device.set_key_image(key, temp_file)

Async Event Handling

import asyncio

async def async_key_handler(device, key, state):
    """Async key event handler"""
    if state:  # Key pressed
        print(f"Key {key} was pressed")

        # Simulate async operation
        await asyncio.sleep(0.5)

        # Update key icon
        image = create_key_image(f"OK", background_color='green')
        native_image = to_native_key_format(device, image)
        native_image.save(f"async_key_{key}.jpg", "JPEG", quality=100)
        device.set_key_image(key, f"async_key_{key}.jpg")

# Set async callback
device.set_key_callback_async(async_key_handler)

# Run async event loop
async def main():
    # Device initialization code...

    # Keep program running
    while True:
        await asyncio.sleep(1)

asyncio.run(main())

Troubleshooting

Common Issues

1. Device Cannot Be Detected

Problem: enumerate() returns empty list

Solution:

  • Check if device is properly connected
  • Confirm device driver is installed
  • Check USB permissions (may need sudo or configure udev rules)
  • Use lsusb command to confirm device is visible
lsusb | grep -i streamdock

2. Permission Error

Problem: Permission denied error

Solution:

  • Run program with sudo
  • Configure udev rules to allow user access to devices

Create /etc/udev/rules.d/99-streamdock.rules file:

# StreamDock device rules
SUBSYSTEM=="usb", ATTR{idVendor}=="5500", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="5548", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="6603", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="6602", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="EEEF", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="1500", MODE="0666"

Then reload rules:

sudo udevadm control --reload-rules
sudo udevadm trigger

3. Image Display Issues

Problem: Images cannot be displayed correctly

Solution:

  • Confirm image file exists and is readable
  • Check image format (JPEG recommended)
  • Confirm image dimensions meet device requirements
  • Check if image path is correct

4. Dependency Installation Failure

Problem: Error when installing dependencies with pip

Solution:

  • Update pip: pip install --upgrade pip
  • Use system package manager to install system dependencies
  • Install in virtual environment
# Create virtual environment
python3 -m venv streamdock-env
source streamdock-env/bin/activate

# Install dependencies
pip install Pillow pyudev

Debugging Tips

Enable Verbose Logging

import logging

# Set log level
logging.basicConfig(level=logging.DEBUG)

# Add logging in code
logger = logging.getLogger(__name__)
logger.debug("Debug information")

Check Device Information

for device in devices:
    print(f"Device path: {device.getPath()}")
    print(f"Device type: {device.DECK_TYPE}")
    print(f"Key count: {device.KEY_COUNT}")
    print(f"Screen size: {device.TOUCHSCREEN_PIXEL_WIDTH}x{device.TOUCHSCREEN_PIXEL_HEIGHT}")
    print(f"Key size: {device.KEY_PIXEL_WIDTH}x{device.KEY_PIXEL_HEIGHT}")

Performance Optimization

Image Processing Optimization

  1. Pre-convert images: Pre-convert all images at program startup
  2. Use caching: Cache converted images to avoid repeated processing
  3. Batch operations: Batch set multiple key icons
  4. Appropriate quality settings: Set JPEG quality to 85-95 to balance quality and performance

Thread Management

  1. Use thread pools: Use thread pool management for large numbers of device operations
  2. Avoid blocking: Do not perform time-consuming operations in callback functions
  3. Reasonable timeouts: Set reasonable timeouts for device operations
Last Updated:
Contributors: JKWTCN