Clarify what the -pluginUUID option passed in by StreamDeck is doing and how it is used

Author: strohganoff

pyproject.toml

@@ -7,7 +7,7 @@
 
 [project]
     name = "streamdeck-plugin-sdk"
-    version = "0.2.1"
+    version = "0.2.2"
     description = "Write Streamdeck plugins using Python"
     readme = "README.md"
     authors = [

streamdeck/__main__.py

@@ -203,7 +203,7 @@ def main():
     args = cast(CliArgsNamespace, parser.parse_args())
 
     info = json.loads(args.info)
-    plugin_name = info["plugin"]["uuid"]
+    plugin_uuid = info["plugin"]["uuid"]
 
     action_scripts = determine_action_scripts(
         plugin_dir=args.plugin_dir,
@@ -214,7 +214,10 @@ def main():
 
     manager = PluginManager(
         port=args.port,
-        plugin_uuid=args.pluginUUID,
+        plugin_uuid=plugin_uuid,
+        # NOT the configured plugin UUID in the manifest.json,
+        # which can be pulled out of `info["plugin"]["uuid"]`
+        plugin_registration_uuid=args.pluginUUID,
         register_event=args.registerEvent,
         info=info,
     )

streamdeck/command_sender.py

@@ -257,17 +257,23 @@ def send_to_plugin(
     def send_action_registration(
         self,
         register_event: str,
-        plugin_uuid: str,
+        plugin_registration_uuid: str,
     ) -> None:
-        """Send a payload to another plugin.
+        """Registers a plugin with the Stream Deck software very shortly after the plugin is started.
+
+        Upon running a plugin's startup command, the Stream Deck software will pass in args that include a
+        register event type string (almost definitely "registerPlugin") and a unique random ID, which the
+        plugin needs to immediately send back as an event message in order to register itself.
+        If the Stream Deck software doesn't receive this event after a very brief period, it will keep
+        trying to re-run the plugin until getting the event.
 
         Args:
-            action: The unique identifier of the receiving plugin's action.
-                If your plugin supports multiple actions, you should use this value to find out
-                which action was triggered.
-            payload: The data that will be received by the receiving plugin.
+            register_event (str): The registration event type, passed in by the Stream Deck software as -registerEvent option.
+                It's value will almost definitely will be "registerPlugin".
+            plugin_registration_uuid (str): Randomly-generated unique ID passed in by StreamDeck as -pluginUUID option,
+                used to send back in the registerPlugin event. Note that this is NOT the manifest.json -configured plugin UUID value.
         """
         self._send_event(
             event=register_event,
-            uuid=plugin_uuid,
-        )
+            uuid=plugin_registration_uuid,
+        )

streamdeck/manager.py

@@ -29,20 +29,27 @@ class PluginManager:
     def __init__(
         self,
         port: int,
-        plugin_uuid: str,  # Passed in by Streamdeck to the entry-point script. should we compare what's in the manifest.json file?
+        plugin_uuid: str,
+        plugin_registration_uuid: str,  # Passed in by Streamdeck to the entry-point script. should we compare what's in the manifest.json file?
         register_event: Literal["registerPlugin"],  # Passed in by Streamdeck to the entry-point script. Will this always be "registerPlugin"?
         info: dict[str, Any]
     ):
         """Initialize a PluginManager instance.
 
         Args:
             port (int): The port number for WebSocket connection.
-            plugin_uuid (str): The unique identifier for the plugin.
-            register_event (str): The registration event type.
+            plugin_uuid (str): The unique identifier for the plugin, as configured in the manifest.json file.
+                This can be retrieved either from the manifest.json, or from the -info json object string option passed in by
+                the Stream Deck software under `{"plugin": {"uuid": "MY-PLUGIN-UUID"}}`
+            plugin_registration_uuid (str): Randomly-generated unique ID passed in by Stream Deck as -pluginUUID option,
+                used to send back in the registerPlugin event.
+            register_event (str): The registration event type, passed in by the Stream Deck software as -registerEvent option.
+                It's value will almost definitely will be "registerPlugin".
             info (dict[str, Any]): The information related to the plugin.
         """
         self._port = port
         self.uuid = plugin_uuid
+        self._registration_uuid = plugin_registration_uuid
         self._register_event = register_event
         self._info = info
 
@@ -65,7 +72,7 @@ def run(self) -> None:
         with WebSocketClient(port=self._port) as client:
             command_sender = StreamDeckCommandSender(client)
 
-            command_sender.send_action_registration(register_event=self._register_event, plugin_uuid=self.uuid)
+            command_sender.send_action_registration(register_event=self._register_event, plugin_registration_uuid=self._registration_uuid)
 
             for message in client.listen_forever():
                 data: EventBase = event_adapter.validate_json(message)

tests/test_plugin_manager.py

@@ -1,3 +1,4 @@
+import uuid
 from typing import cast
 from unittest.mock import MagicMock, Mock
 
@@ -22,12 +23,14 @@ def plugin_manager(port_number: int) -> PluginManager:
         PluginManager: An instance of PluginManager with test parameters.
     """
     plugin_uuid = "test-plugin-uuid"
+    plugin_registration_uuid = str(uuid.uuid1())
     register_event = "registerPlugin"
     info = {"some": "info"}
 
     return PluginManager(
         port=port_number,
         plugin_uuid=plugin_uuid,
+        plugin_registration_uuid=plugin_registration_uuid,
         register_event=register_event,
         info=info
     )
@@ -43,7 +46,6 @@ def patch_websocket_client(monkeypatch: pytest.MonkeyPatch) -> tuple[MagicMock,
     Returns:
         tuple: Mocked instance of WebSocketClient, and a fake DialRotateEvent.
     """
-
     mock_websocket_client = MagicMock(spec=WebSocketClient)
 
     mock_websocket_client.__enter__.return_value = mock_websocket_client
@@ -117,7 +119,7 @@ def test_plugin_manager_sends_registration_event(mock_command_sender: Mock, plug
 
     mock_command_sender.send_action_registration.assert_called_once_with(
         register_event=plugin_manager._register_event,
-        plugin_uuid=plugin_manager.uuid,
+        plugin_registration_uuid=plugin_manager._registration_uuid,
     )
 
 
@@ -135,4 +137,4 @@ def test_plugin_manager_process_event(patch_websocket_client: tuple[MagicMock, E
     spied_event_adapter_validate_json.assert_called_once_with(fake_event_message.model_dump_json())
     assert spied_event_adapter_validate_json.spy_return == fake_event_message
 
-    cast(Mock, plugin_manager._registry.get_action_handlers).assert_called_once_with(fake_event_message.event)
+    cast(Mock, plugin_manager._registry.get_action_handlers).assert_called_once_with(fake_event_message.event)