Add the MiraBox StreamDock device family

CHANGELOG

@@ -1,3 +1,21 @@
+Unreleased:
+	- Added the MiraBox StreamDock family: 293, 293 V3, 293s V3, K1 Pro, M3, M18,
+	  N1, N3, N4, N4 Pro and XL, across 26 product ids. They speak a text-tagged
+	  HID protocol rather than Elgato's binary one, so they share a StreamDock
+	  base class that holds the protocol and per-model data tables. Only the N3
+	  has been verified against hardware.
+	- Moved the Stream Dock 293S onto that base class as StreamDock293s, since it
+	  speaks the same protocol. Mirabox293S still resolves to it and is
+	  deprecated. The connect sequence and the key maps are unchanged; its
+	  reports now go out at the 513 bytes it declares, rather than the 514 an
+	  off-by-one slice assignment was producing.
+	- Fixed the CLE clear command addressing its key id one byte early, which
+	  made it clear key 0 instead of the key asked for. The 293S, which had the
+	  parameter right, is unaffected.
+	- to_native_key_format() takes an optional key index, for devices whose keys
+	  are cutouts in one shared panel and are framed per key. Existing callers
+	  are unaffected.
+
 Fork version 0.2.0:
 	- Merged upstream up to the 0.10.0 changes listed below.
 	- Added RotatedDeck, a wrapper presenting a deck as if it had been turned by

README.md

@@ -34,9 +34,23 @@ variants:
 * StreamDeck Studio
 * StreamDeck XL
 
-This fork additionally supports:
-
-* Mirabox Stream Dock 293S
+This fork additionally supports the MiraBox StreamDock family, which speaks its
+own protocol rather than Elgato's:
+
+* StreamDock 293 and 293 V3
+* StreamDock 293s (also known as the Mirabox Stream Dock 293S) and 293s V3
+* StreamDock K1 Pro
+* StreamDock M3 and M18
+* StreamDock N1
+* StreamDock N3
+* StreamDock N4 and N4 Pro
+* StreamDock XL
+
+Of these, the 293s and the N3 have been verified against hardware. The rest are
+built from the reverse-engineered protocol tables credited below and are
+untested, so reports either way are welcome. Their key grids and knobs are
+mapped; secondary LCD strips are not, except on the 293s, where the side strip
+is driven as a sixth column of keys.
 
 ## Package Installation:
 
@@ -107,6 +121,21 @@ development and maintenance of this library:
 If you've contributed in some manner, but I've accidentally missed you in the
 list above, please let me know.
 
+The MiraBox StreamDock protocol is undocumented by the vendor. The support in
+this fork rests on independent reverse engineering by:
+
+- [rescbr](https://github.com/rescbr), for the Stream Dock 293S, the first of
+  these devices supported here and the source of the shared protocol's framing
+- [Phaeilo](https://github.com/Phaeilo), for the pure-Python HID transport
+  ([StreamDock-Device-SDK#76](https://github.com/MiraboxSpace/StreamDock-Device-SDK/pull/76))
+- [stevemurr](https://github.com/stevemurr), for the MOD mode select, the connect
+  handshake, and the CONNECT keepalive and HAN semantics
+  ([streamdock](https://github.com/stevemurr/streamdock))
+- [4ndv](https://github.com/4ndv), for [mirajazz](https://github.com/4ndv/mirajazz),
+  against which the command frames were corroborated
+- [rigor789](https://github.com/rigor789), for
+  [mirabox-streamdock-node](https://github.com/rigor789/mirabox-streamdock-node)
+
 
 ## License:
 

doc/source/modules/devices.rst

@@ -87,11 +87,73 @@ StreamDeck XL
 Mirabox Stream Dock 293S
 =========================
 
+.. automodule:: StreamDeck.Devices.StreamDock293s
+   :members:
+   :show-inheritance:
+
 .. automodule:: StreamDeck.Devices.Mirabox293S
    :members:
    :show-inheritance:
 
 
+=========================
+StreamDock (Abstract Base)
+=========================
+
+.. automodule:: StreamDeck.Devices.StreamDock
+   :members:
+   :show-inheritance:
+
+
+=========================
+StreamDock Models
+=========================
+
+.. automodule:: StreamDeck.Devices.StreamDockN3
+   :members:
+   :show-inheritance:
+
+.. automodule:: StreamDeck.Devices.StreamDockN1
+   :members:
+   :show-inheritance:
+
+.. automodule:: StreamDeck.Devices.StreamDockN4
+   :members:
+   :show-inheritance:
+
+.. automodule:: StreamDeck.Devices.StreamDockN4Pro
+   :members:
+   :show-inheritance:
+
+.. automodule:: StreamDeck.Devices.StreamDock293
+   :members:
+   :show-inheritance:
+
+.. automodule:: StreamDeck.Devices.StreamDock293V3
+   :members:
+   :show-inheritance:
+
+.. automodule:: StreamDeck.Devices.StreamDock293sV3
+   :members:
+   :show-inheritance:
+
+.. automodule:: StreamDeck.Devices.StreamDockXL
+   :members:
+   :show-inheritance:
+
+.. automodule:: StreamDeck.Devices.StreamDockM3
+   :members:
+   :show-inheritance:
+
+.. automodule:: StreamDeck.Devices.StreamDockM18
+   :members:
+   :show-inheritance:
+
+.. automodule:: StreamDeck.Devices.StreamDockK1Pro
+   :members:
+   :show-inheritance:
+
+
 ============
 Rotated Deck
 ============

src/StreamDeck/DeviceManager.py

@@ -7,7 +7,6 @@
 
 from collections.abc import Callable
 
-from .Devices.Mirabox293S import Mirabox293S
 from .Devices.StreamDeck import StreamDeck
 from .Devices.StreamDeckMini import StreamDeckMini
 from .Devices.StreamDeckNeo import StreamDeckNeo
@@ -18,6 +17,18 @@
 from .Devices.StreamDeckPlusXL import StreamDeckPlusXL
 from .Devices.StreamDeckStudio import StreamDeckStudio
 from .Devices.StreamDeckXL import StreamDeckXL
+from .Devices.StreamDock293 import StreamDock293
+from .Devices.StreamDock293s import StreamDock293s
+from .Devices.StreamDock293sV3 import StreamDock293sV3
+from .Devices.StreamDock293V3 import StreamDock293V3
+from .Devices.StreamDockK1Pro import StreamDockK1Pro
+from .Devices.StreamDockM3 import StreamDockM3
+from .Devices.StreamDockM18 import StreamDockM18
+from .Devices.StreamDockN1 import StreamDockN1
+from .Devices.StreamDockN3 import StreamDockN3
+from .Devices.StreamDockN4 import StreamDockN4
+from .Devices.StreamDockN4Pro import StreamDockN4Pro
+from .Devices.StreamDockXL import StreamDockXL
 from .ProductIDs import USBProductIDs, USBVendorIDs
 from .Transport import Transport
 from .Transport.Dummy import Dummy
@@ -148,7 +159,33 @@ def _default_factory(self) -> list[StreamDeck]:
             (USBVendorIDs.USB_VID_ELGATO, USBProductIDs.USB_PID_STREAMDECK_STUDIO, StreamDeckStudio),
             (USBVendorIDs.USB_VID_ELGATO, USBProductIDs.USB_PID_STREAMDECK_PLUS, StreamDeckPlus),
             (USBVendorIDs.USB_VID_ELGATO, USBProductIDs.USB_PID_STREAMDECK_PLUS_XL, StreamDeckPlusXL),
-            (USBVendorIDs.USB_VID_MIRABOX, USBProductIDs.USB_PID_MIRABOX_STREAMDOCK_293S, Mirabox293S),
+            # MiraBox StreamDock.
+            (USBVendorIDs.USB_VID_MIRABOX, USBProductIDs.USB_PID_MIRABOX_STREAMDOCK_293S, StreamDock293s),
+            (USBVendorIDs.USB_VID_STREAMDOCK_5500, USBProductIDs.USB_PID_STREAMDOCK_293, StreamDock293),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6603, USBProductIDs.USB_PID_STREAMDOCK_293_V3, StreamDock293V3),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6603, USBProductIDs.USB_PID_STREAMDOCK_293_V3_B, StreamDock293V3),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6603, USBProductIDs.USB_PID_STREAMDOCK_293_V3_C, StreamDock293V3),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6603, USBProductIDs.USB_PID_STREAMDOCK_293S_V3, StreamDock293sV3),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6603, USBProductIDs.USB_PID_STREAMDOCK_N1, StreamDockN1),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6603, USBProductIDs.USB_PID_STREAMDOCK_N1_B, StreamDockN1),
+            (USBVendorIDs.USB_VID_STREAMDOCK_1500, USBProductIDs.USB_PID_STREAMDOCK_N3_D, StreamDockN3),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6602, USBProductIDs.USB_PID_STREAMDOCK_N3, StreamDockN3),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6602, USBProductIDs.USB_PID_STREAMDOCK_N3_B, StreamDockN3),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6602, USBProductIDs.USB_PID_STREAMDOCK_N3_C, StreamDockN3),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6603, USBProductIDs.USB_PID_STREAMDOCK_N3, StreamDockN3),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6603, USBProductIDs.USB_PID_STREAMDOCK_N3_B, StreamDockN3),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6602, USBProductIDs.USB_PID_STREAMDOCK_N4, StreamDockN4),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6603, USBProductIDs.USB_PID_STREAMDOCK_N4_B, StreamDockN4),
+            (USBVendorIDs.USB_VID_MIRABOX, USBProductIDs.USB_PID_STREAMDOCK_N4_PRO, StreamDockN4Pro),
+            (USBVendorIDs.USB_VID_MIRABOX, USBProductIDs.USB_PID_STREAMDOCK_N4_PRO_B, StreamDockN4Pro),
+            (USBVendorIDs.USB_VID_MIRABOX, USBProductIDs.USB_PID_STREAMDOCK_N4_PRO_C, StreamDockN4Pro),
+            (USBVendorIDs.USB_VID_MIRABOX, USBProductIDs.USB_PID_STREAMDOCK_XL, StreamDockXL),
+            (USBVendorIDs.USB_VID_MIRABOX, USBProductIDs.USB_PID_STREAMDOCK_XL_B, StreamDockXL),
+            (USBVendorIDs.USB_VID_MIRABOX, USBProductIDs.USB_PID_STREAMDOCK_M3, StreamDockM3),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6603, USBProductIDs.USB_PID_STREAMDOCK_M18, StreamDockM18),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6603, USBProductIDs.USB_PID_STREAMDOCK_M18_B, StreamDockM18),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6603, USBProductIDs.USB_PID_STREAMDOCK_K1_PRO, StreamDockK1Pro),
+            (USBVendorIDs.USB_VID_STREAMDOCK_6603, USBProductIDs.USB_PID_STREAMDOCK_K1_PRO_B, StreamDockK1Pro),
         ]
 
         streamdecks = list()