Python HID-Automatisierung

Nutze Python für direkte Hardware-Steuerung

Python ist exzellent, wenn das Stream Deck Teil deiner eigenen lokalen Anwendung ist. Es ist nicht der normale Weg für ein Marketplace-Plugin innerhalb der Stream Deck Desktop-App.

1. Was die Python-Bibliothek macht

python-elgato-streamdeck ist eine Python-3-Bibliothek zur direkten Steuerung von Stream Deck Geräten. Sie kann Geräte auflisten, ein Deck öffnen, die Helligkeit setzen, Tastenbilder zeichnen, Tastenzustände lesen und Callbacks für Tasten, Dials und Touch-Events auf unterstützter Hardware registrieren.

Das macht sie ideal für:

• lokale Automatisierungs-Panels,
• Home-Lab-Steuerungen,
• Monitoring-Dashboards,
• CI/CD-Steuerpulte,
• OBS- oder Mediensteuerung außerhalb des offiziellen Plugin-Modells,
• Hardware-Prototyping,
• kioskartige Dashboards.

2. Was sie nicht macht

Sie gibt dir nicht automatisch:

• die Action-Registrierung in der Stream Deck App,
• Marketplace-Plugin-Packaging,
• Property Inspectors,
• die Integration in Nutzerprofile,
• den offiziellen Plugin-Manifest-Workflow.

Wenn du das brauchst, nutze das offizielle TypeScript SDK.

3. Installation

python -m venv .venv
source .venv/bin/activate
pip install streamdeck pillow

Unter Linux erfordert HID-Zugriff häufig udev-Regeln oder das Ausführen mit erhöhten Berechtigungen. Bevorzuge eine udev-Regel gegenüber dem Ausführen der Automatisierung als root.

4. Minimaler direkter Controller

from PIL import Image, ImageDraw
from StreamDeck.DeviceManager import DeviceManager
from StreamDeck.ImageHelpers import PILHelper


def render_key(deck, text: str):
    image_format = deck.key_image_format()
    image = Image.new("RGB", (image_format["size"][0], image_format["size"][1]), "black")
    draw = ImageDraw.Draw(image)
    draw.text((10, 10), text, fill="white")
    return PILHelper.to_native_key_format(deck, image)


decks = DeviceManager().enumerate()

if not decks:
    raise RuntimeError("No Stream Deck devices found")

deck = decks[0]
deck.open()
deck.reset()
deck.set_brightness(40)

for key in range(deck.key_count()):
    deck.set_key_image(key, render_key(deck, str(key + 1)))


def on_key_change(deck, key, state):
    if state:
        deck.set_key_image(key, render_key(deck, "ON"))
    else:
        deck.set_key_image(key, render_key(deck, "OFF"))


deck.set_key_callback(on_key_change)

input("Press Enter to exit...")
deck.reset()
deck.close()

5. Gerätebesitz

Direkte HID-Steuerung bedeutet üblicherweise, dass dein Prozess das Gerät besitzt. Wenn die offizielle Stream Deck App ebenfalls versucht, dieselbe Hardware zu nutzen, erwarte Konflikte.

Praktische Regeln:

• Stoppe die Stream Deck App, wenn du direkte Python-Steuerung testest.
• Schließe das Deck beim Beenden sauber.
• Halte die Reconnect-Logik einfach und sichtbar.
• Nimm nicht an, dass jedes Modell dieselbe Tastenanzahl, Bildschirmgröße, Dials oder Touch-Events hat.

6. Gute Python-Architektur

Trenne das Geräte-Rendering von der Businesslogik:

app/
├── deck/
│   ├── devices.py
│   ├── renderer.py
│   └── callbacks.py
├── integrations/
│   ├── home_assistant.py
│   ├── prometheus.py
│   └── github_actions.py
└── main.py

Halte Callbacks klein. Ein Tasten-Callback sollte Arbeit in eine Queue stellen oder Zustand umschalten, nicht bei langsamen HTTP-Aufrufen blockieren.

7. Tipps zum Bild-Rendering

• Rendere in der von der Bibliothek zurückgegebenen Tastenbildgröße des Geräts.
• Nutze PILHelper.to_native_key_format, bevor du Bilder an das Deck sendest.
• Cache statische Bilder.
• Begrenze die Rate häufiger Zustands-Updates.
• Nutze Text und Icons mit hohem Kontrast.
• Teste auf dem physischen Modell, das du einsetzen willst.

8. Async und langlaufende Arbeit

Für Dashboards, die Dienste abfragen:

• lass eine Schleife für das Polling zuständig sein,
• lass eine Schicht für das Rendering zuständig sein,
• entprelle Updates, damit Tasten nicht flackern,
• behandle API-Ausfälle mit einem sichtbaren degradierten Zustand,
• verbinde Geräte nach Ruhezustand oder USB-Trennungen neu.

9. Wann Python TypeScript schlägt

Python ist besser, wenn:

• das Deck nur für deine eigene Maschine oder dein Team ist,
• direkter Hardware-Besitz akzeptabel ist,
• du wissenschaftliche, Automatisierungs-, Linux- oder Ops-Bibliotheken brauchst,
• du schnellen Klebstoff-Code rund um lokale APIs willst,
• Packaging über den Stream Deck Marketplace irrelevant ist.

10. Wann Python nicht passt

Nutze stattdessen das offizielle SDK, wenn:

• Nutzende das Plugin über Stream Deck installieren sollen,
• Actions in der Stream Deck Action-Liste erscheinen sollen,
• jede Action einen Property Inspector braucht,
• Nutzende deine Actions mit anderen Profilen mischen sollen,
• die Marketplace-Distribution wichtig ist.