Complete support for StreamDeck Neo

Author: Vlad Ilie

src/StreamDeck/Devices/StreamDeck.py

@@ -52,6 +52,8 @@ class StreamDeck(ABC):
     KEY_COLS = 0
     KEY_ROWS = 0
 
+    TOUCH_KEY_COUNT = 0
+
     KEY_PIXEL_WIDTH = 0
     KEY_PIXEL_HEIGHT = 0
     KEY_IMAGE_FORMAT = ""
@@ -64,6 +66,12 @@ class StreamDeck(ABC):
     TOUCHSCREEN_FLIP = (False, False)
     TOUCHSCREEN_ROTATION = 0
 
+    SCREEN_PIXEL_WIDTH = 0
+    SCREEN_PIXEL_HEIGHT = 0
+    SCREEN_IMAGE_FORMAT = ""
+    SCREEN_FLIP = (False, False)
+    SCREEN_ROTATION = 0
+
     DIAL_COUNT = 0
 
     DECK_TYPE = ""
@@ -72,7 +80,7 @@ class StreamDeck(ABC):
 
     def __init__(self, device):
         self.device = device
-        self.last_key_states = [False] * self.KEY_COUNT
+        self.last_key_states = [False] * (self.KEY_COUNT + self.TOUCH_KEY_COUNT)
         self.last_dial_states = [False] * self.DIAL_COUNT
         self.read_thread = None
         self.run_read_thread = False
@@ -292,6 +300,15 @@ def key_count(self):
         :return: Number of physical buttons.
         """
         return self.KEY_COUNT
+    
+    def touch_key_count(self):
+        """
+        Retrieves number of touch buttons on the attached StreamDeck device.
+
+        :rtype: int
+        :return: Number of touch buttons.
+        """
+        return self.TOUCH_KEY_COUNT
 
     def dial_count(self):
         """
@@ -376,6 +393,26 @@ def touchscreen_image_format(self):
             'flip': self.TOUCHSCREEN_FLIP,
             'rotation': self.TOUCHSCREEN_ROTATION,
         }
+    
+    def screen_image_format(self):
+        """
+        Retrieves the image format accepted by the screen of the Stream
+        Deck. Images should be given in this format when drawing on
+        screen.
+
+        .. seealso:: See :func:`~StreamDeck.set_screen_image` method to
+                     draw an image on the StreamDeck screen.
+
+        :rtype: dict()
+        :return: Dictionary describing the various image parameters
+                 (size, image format).
+        """
+        return {
+            'size': (self.SCREEN_PIXEL_WIDTH, self.SCREEN_PIXEL_HEIGHT),
+            'format': self.SCREEN_IMAGE_FORMAT,
+            'flip': self.SCREEN_FLIP,
+            'rotation': self.SCREEN_ROTATION,
+        }
 
     def set_poll_frequency(self, hz):
         """
@@ -619,3 +656,30 @@ def set_touchscreen_image(self, image, x_pos=0, y_pos=0, width=0, height=0):
 
         """
         pass
+
+    @abstractmethod
+    def set_key_color(self, key, r, g, b):
+        """
+        Sets the color of the touch buttons. These buttons are indexed
+        in order after the standard keys.
+
+        :param int key: Index of the button
+        :param int r: Red value
+        :param int g: Green value
+        :param int b: Blue value
+
+        """
+        pass
+
+    @abstractmethod
+    def set_screen_image(self, image):
+        """
+        Draws an image on the touchless screen of the StreamDeck.
+
+        .. seealso:: See :func:`~StreamDeck.screen_image_format` method for
+                     information on the image format accepted by the device.
+
+        :param enumerable image: Raw data of the image to set on the button.
+                                 If `None`, the screen will be cleared.
+        """
+        pass

src/StreamDeck/Devices/StreamDeckMini.py

@@ -121,3 +121,9 @@ def set_key_image(self, key, image):
 
     def set_touchscreen_image(self, image, x_pos=0, y_pos=0, width=0, height=0):
         pass
+
+    def set_key_color(self, key, r, g, b):
+        pass
+
+    def set_screen_image(self, image):
+        pass

src/StreamDeck/Devices/StreamDeckNeo.py

@@ -17,6 +17,8 @@ class StreamDeckNeo(StreamDeck):
     KEY_COLS = 4
     KEY_ROWS = 2
 
+    TOUCH_KEY_COUNT = 2
+
     KEY_PIXEL_WIDTH = 96
     KEY_PIXEL_HEIGHT = 96
     KEY_IMAGE_FORMAT = "JPEG"
@@ -26,6 +28,12 @@ class StreamDeckNeo(StreamDeck):
     DECK_TYPE = "Stream Deck Neo"
     DECK_VISUAL = True
 
+    SCREEN_PIXEL_WIDTH = 248
+    SCREEN_PIXEL_HEIGHT = 58
+    SCREEN_IMAGE_FORMAT = "JPEG"
+    SCREEN_FLIP = (True, True)
+    SCREEN_ROTATION = 0
+
     IMAGE_REPORT_LENGTH = 1024
     IMAGE_REPORT_HEADER_LENGTH = 8
     IMAGE_REPORT_PAYLOAD_LENGTH = IMAGE_REPORT_LENGTH - IMAGE_REPORT_HEADER_LENGTH
@@ -75,8 +83,24 @@ class StreamDeckNeo(StreamDeck):
         0x02, 0x8a, 0x28, 0xa0, 0x02, 0x8a, 0x28, 0xa0, 0x0f, 0xff, 0xd9
     ]
 
+    # 248 x 58 black JPEG
+    BLANK_SCREEN_IMAGE = [
+        0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10, 0x4a, 0x46, 0x49, 0x46, 0x00, 0x01, 0x01, 0x00, 0x00, 0x01, 0x00, 0x01, 0x00,
+        0x00, 0xff, 0xdb, 0x00, 0x43, 0x00, 0x08, 0x06, 0x06, 0x07, 0x06, 0x05, 0x08, 0x07, 0x07, 0x07, 0x09, 0x09, 0x08,
+        0x0a, 0x0c, 0x14, 0x0d, 0x0c, 0x0b, 0x0b, 0x0c, 0x19, 0x12, 0x13, 0x0f, 0x14, 0x1d, 0x1a, 0x1f, 0x1e, 0x1d, 0x1a,
+        0x1c, 0x1c, 0x20, 0x24, 0x2e, 0x27, 0x20, 0x22, 0x2c, 0x23, 0x1c, 0x1c, 0x28, 0x37, 0x29, 0x2c, 0x30, 0x31, 0x34,
+        0x34, 0x34, 0x1f, 0x27, 0x39, 0x3d, 0x38, 0x32, 0x3c, 0x2e, 0x33, 0x34, 0x32, 0xff, 0xc0, 0x00, 0x0b, 0x08, 0x00,
+        0x3a, 0x00, 0xf8, 0x01, 0x01, 0x11, 0x00, 0xff, 0xc4, 0x00, 0x15, 0x00, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00,
+        0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x08, 0xff, 0xc4, 0x00, 0x14, 0x10, 0x01, 0x00, 0x00,
+        0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xda, 0x00, 0x08, 0x01,
+        0x01, 0x00, 0x00, 0x3f, 0x00, 0x9f, 0xc0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+        0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+        0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+        0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x7f, 0xff, 0xd9
+    ]
+
     def _read_control_states(self):
-        states = self.device.read(4 + self.KEY_COUNT)
+        states = self.device.read(4 + self.KEY_COUNT + self.TOUCH_KEY_COUNT)
         if states is None:
             return None
 
@@ -114,7 +138,7 @@ def get_firmware_version(self):
         return self._extract_string(version[6:])
 
     def set_key_image(self, key, image):
-        if min(max(key, 0), self.KEY_COUNT) != key:
+        if min(max(key, 0), self.KEY_COUNT - 1) != key:
             raise IndexError("Invalid key index {}.".format(key))
 
         image = bytes(image or self.BLANK_KEY_IMAGE)
@@ -143,5 +167,46 @@ def set_key_image(self, key, image):
             bytes_remaining = bytes_remaining - this_length
             page_number = page_number + 1
 
+    def set_key_color(self, key, r, g, b):
+        if min(max(key, 0), self.KEY_COUNT + self.TOUCH_KEY_COUNT - 1) != key:
+            raise IndexError("Invalid touch key index {}.".format(key))
+        
+        if r > 255 or r < 0 or g > 255 or g < 0 or b > 255 or b < 0:
+            raise ValueError("Invalid color")
+        
+        payload = bytearray(32)
+        payload[0:6] = [0x03, 0x06, key, r, g, b]
+        self.device.write_feature(payload)
+
+    def set_screen_image(self, image):
+        if not image:
+            image = self.BLANK_SCREEN_IMAGE
+
+        image = bytes(image)
+
+        page_number = 0
+        bytes_remaining = len(image)
+        while bytes_remaining > 0:
+            this_length = min(bytes_remaining, self.IMAGE_REPORT_PAYLOAD_LENGTH)
+            bytes_sent = page_number * self.IMAGE_REPORT_PAYLOAD_LENGTH
+
+            header = [
+                0x02,  # 0
+                0x0b,  # 1
+                0x00,  # 2
+                0x01 if this_length == bytes_remaining else 0x00, # 3 is the last report?
+                this_length & 0xff,  # 5 bytecount high byte
+                (this_length >> 8) & 0xff,  # 4 bytecount high byte
+                page_number & 0xff,  # 7 pagenumber low byte
+                (page_number >> 8) & 0xff  # 6 pagenumber high byte
+            ]
+
+            payload = bytes(header) + image[bytes_sent:bytes_sent + this_length]
+            padding = bytearray(self.IMAGE_REPORT_LENGTH - len(payload))
+            self.device.write(payload + padding)
+
+            bytes_remaining = bytes_remaining - this_length
+            page_number = page_number + 1
+
     def set_touchscreen_image(self, image, x_pos=0, y_pos=0, width=0, height=0):
         pass

src/StreamDeck/Devices/StreamDeckOriginal.py

@@ -125,3 +125,9 @@ def set_key_image(self, key, image):
 
     def set_touchscreen_image(self, image, x_pos=0, y_pos=0, width=0, height=0):
         pass
+
+    def set_key_color(self, key, r, g, b):
+        pass
+
+    def set_screen_image(self, image):
+        pass

src/StreamDeck/Devices/StreamDeckOriginalV2.py

@@ -143,3 +143,9 @@ def set_key_image(self, key, image):
 
     def set_touchscreen_image(self, image, x_pos=0, y_pos=0, width=0, height=0):
         pass
+
+    def set_key_color(self, key, r, g, b):
+        pass
+
+    def set_screen_image(self, image):
+        pass

src/StreamDeck/Devices/StreamDeckPedal.py

@@ -52,3 +52,9 @@ def set_key_image(self, key, image):
 
     def set_touchscreen_image(self, image, x_pos=0, y_pos=0, width=0, height=0):
         pass
+
+    def set_key_color(self, key, r, g, b):
+        pass
+
+    def set_screen_image(self, image):
+        pass

src/StreamDeck/Devices/StreamDeckPlus.py

@@ -490,3 +490,9 @@ def set_touchscreen_image(self, image, x_pos=0, y_pos=0, width=0, height=0):
 
             bytes_remaining = bytes_remaining - this_length
             page_number = page_number + 1
+
+    def set_key_color(self, key, r, g, b):
+        pass
+
+    def set_screen_image(self, image):
+        pass

src/StreamDeck/Devices/StreamDeckXL.py

@@ -145,3 +145,9 @@ def set_key_image(self, key, image):
 
     def set_touchscreen_image(self, image, x_pos=0, y_pos=0, width=0, height=0):
         pass
+
+    def set_key_color(self, key, r, g, b):
+        pass
+
+    def set_screen_image(self, image):
+        pass

src/StreamDeck/ImageHelpers/PILHelper.py

@@ -96,6 +96,24 @@ def create_touchscreen_image(deck, background='black'):
     return _create_image(deck.touchscreen_image_format(), background)
 
 
+def create_screen_image(deck, background='black'):
+    """
+    Creates a new PIL Image with the correct image dimensions for the given
+    StreamDeck device's creen.
+
+    .. seealso:: See :func:`~PILHelper.to_native_screen_format` method for converting a
+                 PIL image instance to the native screen image format of a given
+                 StreamDeck device.
+
+    :param StreamDeck deck: StreamDeck device to generate a compatible image for.
+    :param str background: Background color to use, compatible with `PIL.Image.new()`.
+
+    :rtype: PIL.Image
+    :return: Created PIL image
+    """
+    return _create_image(deck.screen_image_format(), background)
+
+
 def create_scaled_image(deck, image, margins=[0, 0, 0, 0], background='black'):
     """
     .. deprecated:: 0.9.5
@@ -152,6 +170,30 @@ def create_scaled_touchscreen_image(deck, image, margins=[0, 0, 0, 0], backgroun
     return _scale_image(image, deck.touchscreen_image_format(), margins, background)
 
 
+def create_scaled_screen_image(deck, image, margins=[0, 0, 0, 0], background='black'):
+    """
+    Creates a new screen image that contains a scaled version of a given image,
+    resized to best fit the given StreamDeck device's screen with the given
+    margins around each side.
+
+    The scaled image is centered within the new screen image, offset by the given
+    margins. The aspect ratio of the image is preserved.
+
+    .. seealso:: See :func:`~PILHelper.to_native_screen_format` method for converting a
+                 PIL image instance to the native key image format of a given
+                 StreamDeck device.
+
+    :param StreamDeck deck: StreamDeck device to generate a compatible image for.
+    :param Image image: PIL Image object to scale
+    :param list(int): Array of margin pixels in (top, right, bottom, left) order.
+    :param str background: Background color to use, compatible with `PIL.Image.new()`.
+
+    :rtrype: PIL.Image
+    :return: Loaded PIL image scaled and centered
+    """
+    return _scale_image(image, deck.screen_image_format(), margins, background)
+
+
 def to_native_format(deck, image):
     """
     .. deprecated:: 0.9.5
@@ -192,3 +234,19 @@ def to_native_touchscreen_format(deck, image):
     :return: Image converted to the given StreamDeck's native touchscreen format
     """
     return _to_native_format(image, deck.touchscreen_image_format())
+
+def to_native_screen_format(deck, image):
+    """
+    Converts a given PIL image to the native screen image format for a StreamDeck,
+    suitable for passing to :func:`~StreamDeck.set_screen_image`.
+
+    .. seealso:: See :func:`~PILHelper.create_screen_image` method for creating a PIL
+                 image instance for a given StreamDeck device.
+
+    :param StreamDeck deck: StreamDeck device to generate a compatible native image for.
+    :param PIL.Image image: PIL Image to convert to the native StreamDeck image format
+
+    :rtype: enumerable()
+    :return: Image converted to the given StreamDeck's native screen format
+    """
+    return _to_native_format(image, deck.screen_image_format())

src/example_basic.py

@@ -85,6 +85,10 @@ def key_change_callback(deck, key, state):
     # Print new key state
     print("Deck {} Key {} = {}".format(deck.id(), key, state), flush=True)
 
+    # Don't try to draw an image on a touch button
+    if key >= deck.key_count():
+        return
+
     # Update the key image based on the new key state.
     update_key_image(deck, key, state)