ucapi 0.1.7__tar.gz → 0.3.0__tar.gz

{ucapi-0.1.7 → ucapi-0.3.0}/CHANGELOG.md

@@ -11,6 +11,17 @@ _Changes in the next release_
 
 ---
 
+## v0.3.0 - 2024-04-25
+### Added
+- New media-player attribute MEDIA_POSITION_UPDATED_AT ([feature-and-bug-tracker#443](https://github.com/unfoldedcircle/feature-and-bug-tracker/issues/443)).
+### Changed
+- Filter out base64 encoded media-player image fields in entity_states response log messages ([#22](https://github.com/unfoldedcircle/integration-python-library/issues/22)).
+- Require websockets version v14 or newer.
+
+## v0.2.0 - 2024-04-28
+### Added
+- New remote-entity type. Requires remote-core / Core Simulator version 0.43.0 or newer.
+
 ## v0.1.7 - 2024-03-13
 ### Changed
 - Filter out base64 encoded media-player image fields in log messages ([#17](https://github.com/unfoldedcircle/integration-python-library/issues/17)).

{ucapi-0.1.7 → ucapi-0.3.0}/CONTRIBUTING.md

@@ -25,7 +25,7 @@ We love contributions from everyone.
 Either by opening a feature request describing your proposed changes before submitting code, or by contacting us on
 one of the other [feedback channels](#feedback-speech_balloon).
 
-Since this library is being used in integration drivers running on the embedded Remote Two device,
+Since this library is being used in integration drivers running on the embedded UC Remote devices,
 we have to make sure it remains compatible with the embedded runtime environment and runs smoothly.
 
 Submitting pull requests for typos, formatting issues etc. are happily accepted and usually approved relatively quick.  
@@ -36,7 +36,8 @@ With that out of the way, here's the process of creating a pull request and maki
 
 1. Fork the repo.
 
-2. Make your changes or enhancements (preferably on a feature-branch).
+2. Make your changes or enhancements.  
+   This should be done in a dedicated branch and not on the main branch to easily submit individual pull requests.
 
    Contributed code must be licensed under the [Mozilla Public License 2.0](https://choosealicense.com/licenses/mpl-2.0/),
    or a compatible license, if existing parts of other projects are reused (e.g. MIT licensed code).  
@@ -53,13 +54,16 @@ With that out of the way, here's the process of creating a pull request and maki
 
 3. Make sure your changes follow the project's code style and the lints pass described in [Code Style](docs/code_guidelines.md).
 
-4. Push to your fork.
+4. Push to your fork.  
+   Do not include any project configuration changes in the `.idea` folder! If you are also using an IntelliJ product,
+   chances are that you're using a different IDE, version or other settings, which can cause issues.
+   For example, between IntelliJ Ultimate and PyCharm.
 
 5. Submit a pull request.
 
 At this point we will review the PR and give constructive feedback.  
 This is a time for discussion and improvements, and making the necessary changes will be required before we can
-merge the contribution.
+merge the contribution. Furthermore, all the automated checks must pass, otherwise the pull request will not be merged.
 
 ### Feedback :speech_balloon:
 

{ucapi-0.1.7/ucapi.egg-info → ucapi-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: ucapi
-Version: 0.1.7
+Version: 0.3.0
 Summary: Python wrapper for the Unfolded Circle Integration API
 Author-email: Unfolded Circle ApS <hello@unfoldedcircle.com>
 License: MPL-2.0
@@ -8,7 +8,7 @@ Project-URL: Homepage, https://www.unfoldedcircle.com/
 Project-URL: Source Code, https://github.com/unfoldedcircle/integration-python-library
 Project-URL: Bug Reports, https://github.com/unfoldedcircle/integration-python-library/issues
 Project-URL: Discord, http://unfolded.chat/
-Project-URL: Forum, http://unfolded.community/
+Project-URL: Forum, https://unfolded.community/
 Platform: any
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -22,7 +22,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown; charset=UTF-8
 License-File: LICENSE
 Requires-Dist: pyee>=9.0
-Requires-Dist: websockets>=11.0
+Requires-Dist: websockets>=14.0
 Requires-Dist: zeroconf>=0.120.0
 Provides-Extra: testing
 Requires-Dist: pylint; extra == "testing"
@@ -30,13 +30,14 @@ Requires-Dist: flake8-docstrings; extra == "testing"
 Requires-Dist: flake8; extra == "testing"
 Requires-Dist: black; extra == "testing"
 Requires-Dist: isort; extra == "testing"
+Dynamic: license-file
 
 # Python API wrapper for the UC Integration API
 [![PyPi](https://img.shields.io/pypi/v/ucapi.svg)](https://pypi.org/project/ucapi)
 [![License](https://img.shields.io/github/license/unfoldedcircle/integration-python-library.svg)](LICENSE)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-This library simplifies writing Python based integrations for the [Unfolded Circle Remote Two](https://www.unfoldedcircle.com/)
+This library simplifies writing Python-based integrations for the [Unfolded Circle Remote devices](https://www.unfoldedcircle.com/)
 by wrapping the [WebSocket Integration API](https://github.com/unfoldedcircle/core-api/tree/main/integration-api).
 
 It's an alpha release (in our eyes). Breaking changes are to be expected and missing features will be continuously added.

{ucapi-0.1.7 → ucapi-0.3.0}/README.md

@@ -3,7 +3,7 @@
 [![License](https://img.shields.io/github/license/unfoldedcircle/integration-python-library.svg)](LICENSE)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-This library simplifies writing Python based integrations for the [Unfolded Circle Remote Two](https://www.unfoldedcircle.com/)
+This library simplifies writing Python-based integrations for the [Unfolded Circle Remote devices](https://www.unfoldedcircle.com/)
 by wrapping the [WebSocket Integration API](https://github.com/unfoldedcircle/core-api/tree/main/integration-api).
 
 It's an alpha release (in our eyes). Breaking changes are to be expected and missing features will be continuously added.

{ucapi-0.1.7 → ucapi-0.3.0}/examples/README.md

@@ -19,6 +19,12 @@ to start with an integration driver for the Remote Two.
 
 It defines a single push button with a callback handler. When pushed, it just prints a message in the console.
 
+## remote
+
+The [remote.py](remote.py) example shows how to use the [remote-entity](https://github.com/unfoldedcircle/core-api/blob/main/doc/entities/entity_remote.md).
+
+It defines some simple commands, a custom button mapping and user interface pages for the available commands. 
+
 ## setup_flow
 
 The [setup_flow](setup_flow.py) example shows how to define a dynamic setup flow for the driver setup.

ucapi-0.3.0/examples/remote.json

@@ -0,0 +1,18 @@
+{
+  "driver_id": "remote_test",
+  "version": "0.0.1",
+  "min_core_api": "0.20.0",
+  "name": { "en": "Remote test" },
+  "icon": "uc:integration",
+  "description": {
+    "en": "Minimal Python integration driver example with a remote entity."
+  },
+  "port": 9084,
+  "developer": {
+    "name": "Unfolded Circle ApS",
+    "email": "hello@unfoldedcircle.com",
+    "url": "https://www.unfoldedcircle.com"
+  },
+  "home_page": "https://www.unfoldedcircle.com",
+  "release_date": "2024-04-08"
+}

ucapi-0.3.0/examples/remote.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""Remote entity integration example. Bare minimum of an integration driver."""
+import asyncio
+import json
+import logging
+import sys
+from typing import Any
+
+import ucapi
+from ucapi import remote
+from ucapi.remote import *
+from ucapi.remote import create_send_cmd, create_sequence_cmd
+from ucapi.ui import (
+    Buttons,
+    DeviceButtonMapping,
+    Size,
+    UiPage,
+    create_btn_mapping,
+    create_ui_icon,
+    create_ui_text,
+)
+
+loop = asyncio.get_event_loop()
+api = ucapi.IntegrationAPI(loop)
+
+# Simple commands which are supported by this example remote-entity
+supported_commands = [
+    "VOLUME_UP",
+    "VOLUME_DOWN",
+    "HOME",
+    "GUIDE",
+    "CONTEXT_MENU",
+    "CURSOR_UP",
+    "CURSOR_DOWN",
+    "CURSOR_LEFT",
+    "CURSOR_RIGHT",
+    "CURSOR_ENTER",
+    "MY_RECORDINGS",
+    "MY_APPS",
+    "REVERSE",
+    "PLAY",
+    "PAUSE",
+    "FORWARD",
+    "RECORD",
+]
+
+
+async def cmd_handler(
+    entity: ucapi.Remote, cmd_id: str, params: dict[str, Any] | None
+) -> ucapi.StatusCodes:
+    """
+    Remote command handler.
+
+    Called by the integration-API if a command is sent to a configured remote-entity.
+
+    :param entity: remote entity
+    :param cmd_id: command
+    :param params: optional command parameters
+    :return: status of the command
+    """
+    print(f"Got {entity.id} command request: {cmd_id}")
+
+    state = None
+    match cmd_id:
+        case remote.Commands.ON:
+            state = remote.States.ON
+        case remote.Commands.OFF:
+            state = remote.States.OFF
+        case remote.Commands.TOGGLE:
+            if entity.attributes[remote.Attributes.STATE] == remote.States.OFF:
+                state = remote.States.ON
+            else:
+                state = remote.States.OFF
+        case remote.Commands.SEND_CMD:
+            command = params.get("command")
+            # It's up to the integration what to do with an unknown command.
+            # If the supported commands are provided as simple_commands, then it's
+            # easy to validate.
+            if command not in supported_commands:
+                print(f"Unknown command: {command}", file=sys.stderr)
+                return ucapi.StatusCodes.BAD_REQUEST
+
+            repeat = params.get("repeat", 1)
+            delay = params.get("delay", 0)
+            hold = params.get("hold", 0)
+            print(f"Command: {command} (repeat={repeat}, delay={delay}, hold={hold})")
+        case remote.Commands.SEND_CMD_SEQUENCE:
+            sequence = params.get("sequence")
+            repeat = params.get("repeat", 1)
+            delay = params.get("delay", 0)
+            hold = params.get("hold", 0)
+            print(
+                f"Command sequence: {sequence} (repeat={repeat}, delay={delay}, hold={hold})"
+            )
+        case _:
+            print(f"Unsupported command: {cmd_id}", file=sys.stderr)
+            return ucapi.StatusCodes.BAD_REQUEST
+
+    if state:
+        api.configured_entities.update_attributes(
+            entity.id, {remote.Attributes.STATE: state}
+        )
+
+    return ucapi.StatusCodes.OK
+
+
+@api.listens_to(ucapi.Events.CONNECT)
+async def on_connect() -> None:
+    """When the UCR2 connects, send the device state."""
+    # This example is ready all the time!
+    await api.set_device_state(ucapi.DeviceStates.CONNECTED)
+
+
+def create_button_mappings() -> list[DeviceButtonMapping | dict[str, Any]]:
+    """Create a demo button mapping showing different composition options."""
+    return [
+        # simple short- and long-press mapping
+        create_btn_mapping(Buttons.HOME, "HOME", "GUIDE"),
+        # use channel buttons for volume control
+        create_btn_mapping(Buttons.CHANNEL_DOWN, "VOLUME_DOWN"),
+        create_btn_mapping(Buttons.CHANNEL_UP, "VOLUME_UP"),
+        create_btn_mapping(Buttons.DPAD_UP, "CURSOR_UP"),
+        create_btn_mapping(Buttons.DPAD_DOWN, "CURSOR_DOWN"),
+        create_btn_mapping(Buttons.DPAD_LEFT, "CURSOR_LEFT"),
+        create_btn_mapping(Buttons.DPAD_RIGHT, "CURSOR_RIGHT"),
+        # use a send command
+        create_btn_mapping(
+            Buttons.DPAD_MIDDLE, create_send_cmd("CONTEXT_MENU", hold=1000)
+        ),
+        # use a sequence command
+        create_btn_mapping(
+            Buttons.BLUE,
+            create_sequence_cmd(
+                [
+                    "CURSOR_UP",
+                    "CURSOR_RIGHT",
+                    "CURSOR_DOWN",
+                    "CURSOR_LEFT",
+                ],
+                delay=200,
+            ),
+        ),
+        # Safety off: don't use a DeviceButtonMapping data class but a dictionary.
+        # This is useful for directly reading a json configuration file.
+        {"button": "POWER", "short_press": {"cmd_id": "remote.toggle"}},
+    ]
+
+
+def create_ui() -> list[UiPage | dict[str, Any]]:
+    """Create a demo user interface showing different composition options."""
+    # Safety off again: directly use json structure to read a configuration file
+    with open("remote_ui_page.json", "r", encoding="utf-8") as file:
+        main_page = json.load(file)
+
+    # On-the-fly UI composition
+    ui_page1 = UiPage("page1", "Main")
+    ui_page1.add(create_ui_text("Hello remote entity", 0, 0, size=Size(4, 1)))
+    ui_page1.add(create_ui_icon("uc:home", 0, 2, cmd="HOME"))
+    ui_page1.add(create_ui_icon("uc:up-arrow-bold", 2, 2, cmd="CURSOR_UP"))
+    ui_page1.add(create_ui_icon("uc:down-arrow-bold", 2, 4, cmd="CURSOR_DOWN"))
+    ui_page1.add(create_ui_icon("uc:left-arrow", 1, 3, cmd="CURSOR_LEFT"))
+    ui_page1.add(create_ui_icon("uc:right-arrow", 3, 3, cmd="CURSOR_RIGHT"))
+    ui_page1.add(create_ui_text("Ok", 2, 3, cmd="CURSOR_ENTER"))
+
+    ui_page2 = UiPage("page2", "Page 2")
+    ui_page2.add(
+        create_ui_text(
+            "Pump up the volume!",
+            0,
+            0,
+            size=Size(4, 2),
+            cmd=create_send_cmd("VOLUME_UP", repeat=5),
+        )
+    )
+    ui_page2.add(
+        create_ui_text(
+            "Test sequence",
+            0,
+            4,
+            size=Size(4, 1),
+            cmd=create_sequence_cmd(
+                [
+                    "CURSOR_UP",
+                    "CURSOR_RIGHT",
+                    "CURSOR_DOWN",
+                    "CURSOR_LEFT",
+                ],
+                delay=200,
+            ),
+        )
+    )
+    ui_page2.add(create_ui_text("On", 0, 5, cmd="on"))
+    ui_page2.add(create_ui_text("Off", 1, 5, cmd="off"))
+
+    return [main_page, ui_page1, ui_page2]
+
+
+if __name__ == "__main__":
+    logging.basicConfig()
+
+    entity = ucapi.Remote(
+        "remote1",
+        "Demo remote",
+        [remote.Features.ON_OFF, remote.Features.TOGGLE],
+        {remote.Attributes.STATE: remote.States.OFF},
+        simple_commands=supported_commands,
+        button_mapping=create_button_mappings(),
+        ui_pages=create_ui(),
+        cmd_handler=cmd_handler,
+    )
+    api.available_entities.add(entity)
+
+    loop.run_until_complete(api.init("remote.json"))
+    loop.run_forever()

ucapi-0.3.0/examples/remote_ui_page.json

@@ -0,0 +1,65 @@
+{
+  "page_id": "media",
+  "name": "Media",
+  "grid": { "width": 4, "height": 6 },
+  "items": [
+    {
+      "type": "text",
+      "text": "Recordings",
+      "command": {
+        "cmd_id": "MY_RECORDINGS"
+      },
+      "location": { "x": 0, "y": 2 },
+      "size": { "width": 2, "height": 1 }
+    },
+    {
+      "type": "text",
+      "text": "Apps",
+      "command": {
+        "cmd_id": "MY_APPS"
+      },
+      "location": { "x": 2, "y": 2 },
+      "size": { "width": 2, "height": 1 }
+    },
+    {
+      "type": "icon",
+      "icon": "uc:bw",
+      "command": {
+        "cmd_id": "REVERSE"
+      },
+      "location": { "x": 0, "y": 5 }
+    },
+    {
+      "type": "icon",
+      "icon": "uc:play",
+      "command": {
+        "cmd_id": "PLAY"
+      },
+      "location": { "x": 1, "y": 5 }
+    },
+    {
+      "type": "icon",
+      "icon": "uc:pause",
+      "command": {
+        "cmd_id": "PAUSE"
+      },
+      "location": { "x": 2, "y": 5 }
+    },
+    {
+      "type": "icon",
+      "icon": "uc:ff",
+      "command": {
+        "cmd_id": "FORWARD"
+      },
+      "location": { "x": 3, "y": 5 }
+    },
+    {
+      "type": "icon",
+      "icon": "uc:rec",
+      "command": {
+        "cmd_id": "RECORD"
+      },
+      "location": { "x": 2, "y": 4 }
+    }
+  ]
+}

{ucapi-0.1.7 → ucapi-0.3.0}/pyproject.toml

@@ -22,7 +22,7 @@ classifiers = [
 requires-python = ">=3.10"
 dependencies = [
     "pyee>=9.0",
-    "websockets>=11.0",
+    "websockets>=14.0",
     "zeroconf>=0.120.0",
 ]
 dynamic = ["version"]
@@ -36,7 +36,7 @@ content-type = "text/markdown; charset=UTF-8"
 "Source Code" = "https://github.com/unfoldedcircle/integration-python-library"
 "Bug Reports" = "https://github.com/unfoldedcircle/integration-python-library/issues"
 "Discord"     = "http://unfolded.chat/"
-"Forum"       = "http://unfolded.community/"
+"Forum"       = "https://unfolded.community/"
 
 [project.optional-dependencies]
 testing = [

{ucapi-0.1.7 → ucapi-0.3.0}/requirements.txt

@@ -3,5 +3,5 @@
 # Workaround: use a pre-commit hook with https://github.com/scikit-image/scikit-image/blob/main/tools/generate_requirements.py
 
 pyee>=9.0
-websockets>=11.0
+websockets>=14.0
 zeroconf>=0.120.0

{ucapi-0.1.7 → ucapi-0.3.0}/ucapi/__init__.py

@@ -35,6 +35,7 @@ from .climate import Climate  # noqa: F401
 from .cover import Cover  # noqa: F401
 from .light import Light  # noqa: F401
 from .media_player import MediaPlayer  # noqa: F401
+from .remote import Remote  # noqa: F401
 from .sensor import Sensor  # noqa: F401
 from .switch import Switch  # noqa: F401
 

{ucapi-0.1.7 → ucapi-0.3.0}/ucapi/_version.py

@@ -1,8 +1,13 @@
-# file generated by setuptools_scm
+# file generated by setuptools-scm
 # don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import Tuple, Union
+    from typing import Tuple
+    from typing import Union
+
     VERSION_TUPLE = Tuple[Union[int, str], ...]
 else:
     VERSION_TUPLE = object
@@ -12,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.1.7'
-__version_tuple__ = version_tuple = (0, 1, 7)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)

{ucapi-0.1.7 → ucapi-0.3.0}/ucapi/api.py

@@ -16,11 +16,11 @@ from typing import Any, Callable
 import websockets
 from pyee.asyncio import AsyncIOEventEmitter
 
+# Note: websockets v14 doesn't have websockets.server anymore
+from websockets import serve
+
 # workaround for pylint error: E0611: No name 'ConnectionClosedOK' in module 'websockets' (no-name-in-module)  # noqa
 from websockets.exceptions import ConnectionClosedOK
-
-# workaround for pylint error: E1101: Module 'websockets' has no 'serve' member (no-member)  # noqa
-from websockets.server import serve
 from zeroconf import IPVersion
 from zeroconf.asyncio import AsyncServiceInfo, AsyncZeroconf
 
@@ -28,6 +28,11 @@ import ucapi.api_definitions as uc
 from ucapi import media_player
 from ucapi.entities import Entities
 
+try:
+    from ._version import version as __version__
+except ImportError:
+    __version__ = "unknown"
+
 _LOG = logging.getLogger(__name__)
 _LOG.setLevel(logging.DEBUG)
 
@@ -125,9 +130,10 @@ class IntegrationAPI:
         )
 
         _LOG.info(
-            "Driver is up: %s, version: %s, listening on: %s:%d",
+            "Driver is up: %s, version: %s, api: %s, listening on: %s:%d",
             self._driver_info["driver_id"],
             self._driver_info["version"],
+            __version__,
             host,
             port,
         )
@@ -163,6 +169,7 @@ class IntegrationAPI:
             _LOG.info("WS: Connection closed")
 
         except websockets.exceptions.ConnectionClosedError as e:
+            # no idea why they made code & reason deprecated...
             _LOG.info("WS: Connection closed with error %d: %s", e.code, e.reason)
 
         except websockets.exceptions.WebSocketException as e:
@@ -210,6 +217,7 @@ class IntegrationAPI:
         """
         await self._send_ws_response(websocket, req_id, "result", msg_data, status_code)
 
+    # pylint: disable=R0917
     async def _send_ws_response(
         self,
         websocket,
@@ -240,7 +248,9 @@ class IntegrationAPI:
 
         if websocket in self._clients:
             data_dump = json.dumps(data)
-            _LOG.debug("[%s] ->: %s", websocket.remote_address, data_dump)
+            if _LOG.isEnabledFor(logging.DEBUG):
+                data_log = json.dumps(data) if filter_log_msg_data(data) else data_dump
+                _LOG.debug("[%s] ->: %s", websocket.remote_address, data_log)
             await websocket.send(data_dump)
         else:
             _LOG.error("Error sending response: connection no longer established")
@@ -261,12 +271,13 @@ class IntegrationAPI:
         data = {"kind": "event", "msg": msg, "msg_data": msg_data, "cat": category}
         data_dump = json.dumps(data)
         # filter fields
+        data_log = ""
         if _LOG.isEnabledFor(logging.DEBUG):
             data_log = json.dumps(data) if filter_log_msg_data(data) else data_dump
 
         for websocket in self._clients:
             if _LOG.isEnabledFor(logging.DEBUG):
-                _LOG.debug("[%s] ->: %s", websocket.remote_address, data_log)
+                _LOG.debug("[%s] =>: %s", websocket.remote_address, data_log)
             try:
                 await websocket.send(data_dump)
             except websockets.exceptions.WebSocketException:
@@ -469,7 +480,7 @@ class IntegrationAPI:
         self, websocket, req_id: int, msg_data: dict[str, Any] | None
     ) -> None:
         if not msg_data:
-            _LOG.warning("Ignoring _entity_command: called with empty msg_data")
+            _LOG.warning("Ignoring entity command: called with empty msg_data")
             await self.acknowledge_command(
                 websocket, req_id, uc.StatusCodes.BAD_REQUEST
             )
@@ -635,6 +646,7 @@ class IntegrationAPI:
             websocket, uc.WsMsgEvents.DRIVER_SETUP_CHANGE, data, uc.EventCategory.DEVICE
         )
 
+    # pylint: disable=R0917
     async def request_driver_setup_user_confirmation(
         self,
         websocket,
@@ -858,21 +870,41 @@ def filter_log_msg_data(data: dict[str, Any]) -> bool:
 
     Attention: the dictionary is modified!
 
-    - Attributes are filtered in `data["msg_data"]["attributes"]`
+    - Attributes are filtered in `data["msg_data"]`:
+      - dict object: key `attributes`
+      - list object: every list item `attributes`
     - Filtered attributes: `MEDIA_IMAGE_URL`
 
     :param data: the message data dict
     :return: True if a field was filtered, False otherwise
     """
     # filter out base64 encoded images in the media player's media_image_url attribute
-    if (
-        "msg_data" in data
-        and "attributes" in data["msg_data"]
-        and media_player.Attributes.MEDIA_IMAGE_URL in data["msg_data"]["attributes"]
-        and data["msg_data"]["attributes"][
-            media_player.Attributes.MEDIA_IMAGE_URL
-        ].startswith("data:")
-    ):
-        data["msg_data"]["attributes"][media_player.Attributes.MEDIA_IMAGE_URL] = "***"
-        return True
+    if "msg_data" in data:
+        if (
+            "attributes" in data["msg_data"]
+            and media_player.Attributes.MEDIA_IMAGE_URL
+            in data["msg_data"]["attributes"]
+            and data["msg_data"]["attributes"][
+                media_player.Attributes.MEDIA_IMAGE_URL
+            ].startswith("data:")
+        ):
+            data["msg_data"]["attributes"][
+                media_player.Attributes.MEDIA_IMAGE_URL
+            ] = "data:***"
+            return True
+
+        if isinstance(data["msg_data"], list):
+            for item in data["msg_data"]:
+                if (
+                    "attributes" in item
+                    and media_player.Attributes.MEDIA_IMAGE_URL in item["attributes"]
+                    and item["attributes"][
+                        media_player.Attributes.MEDIA_IMAGE_URL
+                    ].startswith("data:")
+                ):
+                    item["attributes"][
+                        media_player.Attributes.MEDIA_IMAGE_URL
+                    ] = "data:***"
+            return True
+
     return False

{ucapi-0.1.7 → ucapi-0.3.0}/ucapi/button.py

@@ -59,8 +59,6 @@ class Button(Entity):
             EntityTypes.BUTTON,
             ["press"],
             {Attributes.STATE: States.AVAILABLE},
-            None,
-            None,
-            area,
-            cmd_handler,
+            area=area,
+            cmd_handler=cmd_handler,
         )

{ucapi-0.1.7 → ucapi-0.3.0}/ucapi/climate.py

@@ -79,8 +79,9 @@ class Climate(Entity):
 
     See https://github.com/unfoldedcircle/core-api/blob/main/doc/entities/entity_climate.md
     for more information.
-    """  # noqa
+    """
 
+    # pylint: disable=R0917
     def __init__(
         self,
         identifier: str,

{ucapi-0.1.7 → ucapi-0.3.0}/ucapi/cover.py

@@ -78,8 +78,9 @@ class Cover(Entity):
 
     See https://github.com/unfoldedcircle/core-api/blob/main/doc/entities/entity_cover.md
     for more information.
-    """  # noqa
+    """
 
+    # pylint: disable=R0917
     def __init__(
         self,
         identifier: str,

{ucapi-0.1.7 → ucapi-0.3.0}/ucapi/entity.py

@@ -23,6 +23,7 @@ class EntityTypes(str, Enum):
     CLIMATE = "climate"
     LIGHT = "light"
     MEDIA_PLAYER = "media_player"
+    REMOTE = "remote"
     SENSOR = "sensor"
     SWITCH = "switch"
 
@@ -35,6 +36,7 @@ class Entity:
     for more information.
     """
 
+    # pylint: disable=R0917
     def __init__(
         self,
         identifier: str,
@@ -42,8 +44,8 @@ class Entity:
         entity_type: EntityTypes,
         features: list[str],
         attributes: dict[str, Any],
-        device_class: str | None,
-        options: dict[str, Any] | None,
+        device_class: str | None = None,
+        options: dict[str, Any] | None = None,
         area: str | None = None,
         cmd_handler: CommandHandler = None,
     ):

{ucapi-0.1.7 → ucapi-0.3.0}/ucapi/light.py

@@ -65,8 +65,9 @@ class Light(Entity):
 
     See https://github.com/unfoldedcircle/core-api/blob/main/doc/entities/entity_light.md
     for more information.
-    """  # noqa
+    """
 
+    # pylint: disable=R0917
     def __init__(
         self,
         identifier: str,

{ucapi-0.1.7 → ucapi-0.3.0}/ucapi/media_player.py

@@ -78,6 +78,7 @@ class Attributes(str, Enum):
     MUTED = "muted"
     MEDIA_DURATION = "media_duration"
     MEDIA_POSITION = "media_position"
+    MEDIA_POSITION_UPDATED_AT = "media_position_updated_at"
     MEDIA_TYPE = "media_type"
     MEDIA_IMAGE_URL = "media_image_url"
     MEDIA_TITLE = "media_title"
@@ -193,8 +194,9 @@ class MediaPlayer(Entity):
 
     See https://github.com/unfoldedcircle/core-api/blob/main/doc/entities/entity_media_player.md
     for more information.
-    """  # noqa
+    """
 
+    # pylint: disable=R0917
     def __init__(
         self,
         identifier: str,

ucapi-0.3.0/ucapi/remote.py

@@ -0,0 +1,168 @@
+"""
+Remote entity definitions.
+
+:copyright: (c) 2024 by Unfolded Circle ApS.
+:license: MPL-2.0, see LICENSE for more details.
+"""
+
+import dataclasses
+from enum import Enum
+from typing import Any
+
+from ucapi.api_definitions import CommandHandler
+from ucapi.entity import Entity, EntityTypes
+from ucapi.ui import DeviceButtonMapping, EntityCommand, UiPage
+
+
+class States(str, Enum):
+    """Remote entity states."""
+
+    UNAVAILABLE = "UNAVAILABLE"
+    UNKNOWN = "UNKNOWN"
+    ON = "ON"
+    OFF = "OFF"
+
+
+class Features(str, Enum):
+    """Remote entity features."""
+
+    ON_OFF = "on_off"
+    TOGGLE = "toggle"
+    SEND_CMD = "send_cmd"
+
+
+class Attributes(str, Enum):
+    """Remote entity attributes."""
+
+    STATE = "state"
+
+
+class Commands(str, Enum):
+    """Remote entity commands."""
+
+    ON = "on"
+    OFF = "off"
+    TOGGLE = "toggle"
+    SEND_CMD = "send_cmd"
+    SEND_CMD_SEQUENCE = "send_cmd_sequence"
+
+
+class Options(str, Enum):
+    """Remote entity options."""
+
+    SIMPLE_COMMANDS = "simple_commands"
+    BUTTON_MAPPING = "button_mapping"
+    USER_INTERFACE = "user_interface"
+
+
+def create_send_cmd(
+    command: str,
+    delay: int | None = None,
+    repeat: int | None = None,
+    hold: int | None = None,
+) -> EntityCommand:
+    """
+    Create a remote send command.
+
+    :param command: command to send.
+    :param delay: optional delay in milliseconds after the command or between repeats.
+    :param repeat: optional repeat count of the command.
+    :param hold: optional hold time in milliseconds.
+    :return: the created EntityCommand.
+    """
+    params = {"command": command}
+    if delay:
+        params["delay"] = delay
+    if repeat:
+        params["repeat"] = repeat
+    if hold:
+        params["hold"] = hold
+    return EntityCommand(Commands.SEND_CMD.value, params)
+
+
+def create_sequence_cmd(
+    sequence: list[str],
+    delay: int | None = None,
+    repeat: int | None = None,
+) -> EntityCommand:
+    """
+    Create a remote send sequence command.
+
+    :param sequence: list of simple commands.
+    :param delay: optional delay in milliseconds between the commands in the sequence.
+    :param repeat: optional repeat count of the sequence.
+    :return: the created EntityCommand.
+    """
+    params = {"sequence": sequence}
+    if delay:
+        params["delay"] = delay
+    if repeat:
+        params["repeat"] = repeat
+    return EntityCommand(Commands.SEND_CMD_SEQUENCE.value, params)
+
+
+def _list_items_asdict(obj: list[Any]):
+    """Convert a list with (mixed) dataclass items to dictionary mapping items."""
+    return list(
+        map(
+            lambda item: (
+                dataclasses.asdict(item) if dataclasses.is_dataclass(item) else item
+            ),
+            obj,
+        )
+    )
+
+
+class Remote(Entity):
+    """
+    Remote entity class.
+
+    See https://github.com/unfoldedcircle/core-api/blob/main/doc/entities/entity_remote.md
+    for more information.
+    """
+
+    # pylint: disable=R0917
+    def __init__(
+        self,
+        identifier: str,
+        name: str | dict[str, str],
+        features: list[Features],
+        attributes: dict[str, Any],
+        simple_commands: list[str] | None = None,
+        button_mapping: list[DeviceButtonMapping | dict[str, Any]] | None = None,
+        ui_pages: list[UiPage | dict[str, Any]] | None = None,
+        area: str | None = None,
+        cmd_handler: CommandHandler = None,
+    ):
+        """
+        Create remote entity instance.
+
+        :param identifier: entity identifier
+        :param name: friendly name
+        :param features: remote features
+        :param attributes: remote attributes
+        :param simple_commands: optional list of supported remote command identifiers
+        :param button_mapping: optional command mapping of physical buttons
+               Either with DeviceButtonMapping items or plain dictionary items.
+        :param ui_pages: optional user interface page definitions.
+               Either with UiPage items or plain dictionary items.
+        :param area: optional area
+        :param cmd_handler: handler for entity commands
+        """
+        options: dict[str, Any] = {}
+        if simple_commands:
+            options["simple_commands"] = simple_commands
+        if button_mapping:
+            options["button_mapping"] = _list_items_asdict(button_mapping)
+        if ui_pages:
+            options["user_interface"] = {"pages": _list_items_asdict(ui_pages)}
+        super().__init__(
+            identifier,
+            name,
+            EntityTypes.REMOTE,
+            features,
+            attributes,
+            options=options,
+            area=area,
+            cmd_handler=cmd_handler,
+        )

{ucapi-0.1.7 → ucapi-0.3.0}/ucapi/sensor.py

@@ -64,8 +64,9 @@ class Sensor(Entity):
 
     See https://github.com/unfoldedcircle/core-api/blob/main/doc/entities/entity_sensor.md
     for more information.
-    """  # noqa
+    """
 
+    # pylint: disable=R0917
     def __init__(
         self,
         identifier: str,

{ucapi-0.1.7 → ucapi-0.3.0}/ucapi/switch.py

@@ -61,8 +61,9 @@ class Switch(Entity):
 
     See https://github.com/unfoldedcircle/core-api/blob/main/doc/entities/entity_switch.md
     for more information.
-    """  # noqa
+    """
 
+    # pylint: disable=R0917
     def __init__(
         self,
         identifier: str,

ucapi-0.3.0/ucapi/ui.py

@@ -0,0 +1,191 @@
+"""
+User interface definitions.
+
+:copyright: (c) 2024 by Unfolded Circle ApS.
+:license: MPL-2.0, see LICENSE for more details.
+"""
+
+from dataclasses import KW_ONLY, dataclass
+from enum import Enum
+
+
+@dataclass
+class EntityCommand:
+    """Remote command definition for a button mapping or UI page definition."""
+
+    cmd_id: str
+    params: dict[str, str | int | list[str]] | None = None
+
+
+class Buttons(str, Enum):
+    """Physical buttons."""
+
+    BACK = "BACK"
+    HOME = "HOME"
+    VOICE = "VOICE"
+    VOLUME_UP = "VOLUME_UP"
+    VOLUME_DOWN = "VOLUME_DOWN"
+    MUTE = "MUTE"
+    DPAD_UP = "DPAD_UP"
+    DPAD_DOWN = "DPAD_DOWN"
+    DPAD_LEFT = "DPAD_LEFT"
+    DPAD_RIGHT = "DPAD_RIGHT"
+    DPAD_MIDDLE = "DPAD_MIDDLE"
+    GREEN = "GREEN"
+    YELLOW = "YELLOW"
+    RED = "RED"
+    BLUE = "BLUE"
+    CHANNEL_UP = "CHANNEL_UP"
+    CHANNEL_DOWN = "CHANNEL_DOWN"
+    PREV = "PREV"
+    PLAY = "PLAY"
+    NEXT = "NEXT"
+    POWER = "POWER"
+
+
+@dataclass
+class DeviceButtonMapping:
+    """Physical button command mapping."""
+
+    button: str
+    """Physical button identifier. See Buttons for Remote Two identifiers."""
+    short_press: EntityCommand | None = None
+    """Short press command of the button."""
+    long_press: EntityCommand | None = None
+    """Long press command of the button."""
+
+
+def create_btn_mapping(
+    button: Buttons,
+    short: str | EntityCommand | None = None,
+    long: str | EntityCommand | None = None,
+) -> DeviceButtonMapping:
+    """
+    Create a physical button command mapping.
+
+    :param button: physical button identifier.
+    :param short: associated short-press command to the physical button.
+                  A string parameter corresponds to a simple command, whereas an
+                  ``EntityCommand`` allows to customize the command.
+    :param long: associated long-press command to the physical button
+    :return: the created DeviceButtonMapping
+    """
+    if isinstance(short, str):
+        short = EntityCommand(short)
+    if isinstance(long, str):
+        long = EntityCommand(long)
+    return DeviceButtonMapping(button.value, short_press=short, long_press=long)
+
+
+@dataclass
+class Size:
+    """Item size in the button grid. Default size if not specified: 1x1."""
+
+    width: int = 1
+    height: int = 1
+
+
+@dataclass
+class Location:
+    """Button placement in the grid with 0-based coordinates."""
+
+    x: int
+    y: int
+
+
+@dataclass
+class UiItem:
+    """
+    A user interface item is either an icon or text.
+
+    - Icon and text items can be static or linked to a command specified in the
+      `command` field.
+    - Default size is 1x1 if not specified.
+    """
+
+    type: str
+    location: Location
+    size: Size | None = None
+    icon: str | None = None
+    text: str | None = None
+    command: EntityCommand | None = None
+
+
+def create_ui_text(
+    text: str,
+    x: int,
+    y: int,
+    size: Size | None = None,
+    cmd: str | EntityCommand | None = None,
+) -> UiItem:
+    """
+    Create a text UI item.
+
+    :param text: the text to show in the UI item.
+    :param x: x-position, 0-based.
+    :param y: y-position, 0-based.
+    :param size: item size, defaults to 1 x 1 if not specified.
+    :param cmd: associated command to the text item. A string parameter corresponds to
+                a simple command, whereas an ``EntityCommand`` allows to customize the
+                command for example with number of repeats.
+    :return: the created UiItem
+    """
+    if isinstance(cmd, str):
+        cmd = EntityCommand(cmd)
+    return UiItem("text", Location(x, y), size=size, text=text, command=cmd)
+
+
+def create_ui_icon(
+    icon: str,
+    x: int,
+    y: int,
+    size: Size | None = None,
+    cmd: str | EntityCommand | None = None,
+) -> UiItem:
+    """
+    Create an icon UI item.
+
+    The icon identifier consists of a prefix and a resource identifier,
+    separated by `:`. Available prefixes:
+      - `uc:` - integrated icon font
+      - `custom:` - custom resource
+
+    :param icon: the icon identifier of the icon to show in the UI item.
+    :param x: x-position, 0-based.
+    :param y: y-position, 0-based.
+    :param size: item size, defaults to 1 x 1 if not specified.
+    :param cmd: associated command to the text item. A string parameter corresponds to
+                a simple command, whereas an ``EntityCommand`` allows to customize the
+                command for example with number of repeats.
+    :return: the created UiItem
+    """
+    if isinstance(cmd, str):
+        cmd = EntityCommand(cmd)
+    return UiItem("icon", Location(x, y), size=size, icon=icon, command=cmd)
+
+
+@dataclass
+class UiPage:
+    """
+    Definition of a complete user interface page.
+
+    Default grid size is 4x6 if not specified.
+    """
+
+    page_id: str
+    name: str
+    _: KW_ONLY
+    grid: Size = None
+    items: list[UiItem] = None
+
+    def __post_init__(self):
+        """Post initialization to set required fields."""
+        # grid and items are required Integration-API fields
+        if self.grid is None:
+            self.grid = Size(4, 6)
+        if self.items is None:
+            self.items = []
+
+    def add(self, item: UiItem):
+        """Append the given UiItem to the page items."""
+        self.items.append(item)

{ucapi-0.1.7 → ucapi-0.3.0/ucapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: ucapi
-Version: 0.1.7
+Version: 0.3.0
 Summary: Python wrapper for the Unfolded Circle Integration API
 Author-email: Unfolded Circle ApS <hello@unfoldedcircle.com>
 License: MPL-2.0
@@ -8,7 +8,7 @@ Project-URL: Homepage, https://www.unfoldedcircle.com/
 Project-URL: Source Code, https://github.com/unfoldedcircle/integration-python-library
 Project-URL: Bug Reports, https://github.com/unfoldedcircle/integration-python-library/issues
 Project-URL: Discord, http://unfolded.chat/
-Project-URL: Forum, http://unfolded.community/
+Project-URL: Forum, https://unfolded.community/
 Platform: any
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -22,7 +22,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown; charset=UTF-8
 License-File: LICENSE
 Requires-Dist: pyee>=9.0
-Requires-Dist: websockets>=11.0
+Requires-Dist: websockets>=14.0
 Requires-Dist: zeroconf>=0.120.0
 Provides-Extra: testing
 Requires-Dist: pylint; extra == "testing"
@@ -30,13 +30,14 @@ Requires-Dist: flake8-docstrings; extra == "testing"
 Requires-Dist: flake8; extra == "testing"
 Requires-Dist: black; extra == "testing"
 Requires-Dist: isort; extra == "testing"
+Dynamic: license-file
 
 # Python API wrapper for the UC Integration API
 [![PyPi](https://img.shields.io/pypi/v/ucapi.svg)](https://pypi.org/project/ucapi)
 [![License](https://img.shields.io/github/license/unfoldedcircle/integration-python-library.svg)](LICENSE)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-This library simplifies writing Python based integrations for the [Unfolded Circle Remote Two](https://www.unfoldedcircle.com/)
+This library simplifies writing Python-based integrations for the [Unfolded Circle Remote devices](https://www.unfoldedcircle.com/)
 by wrapping the [WebSocket Integration API](https://github.com/unfoldedcircle/core-api/tree/main/integration-api).
 
 It's an alpha release (in our eyes). Breaking changes are to be expected and missing features will be continuously added.

{ucapi-0.1.7 → ucapi-0.3.0}/ucapi.egg-info/SOURCES.txt

@@ -11,6 +11,9 @@ docs/setup.md
 examples/README.md
 examples/hello_integration.json
 examples/hello_integration.py
+examples/remote.json
+examples/remote.py
+examples/remote_ui_page.json
 examples/setup_flow.json
 examples/setup_flow.py
 ucapi/__init__.py
@@ -24,8 +27,10 @@ ucapi/entities.py
 ucapi/entity.py
 ucapi/light.py
 ucapi/media_player.py
+ucapi/remote.py
 ucapi/sensor.py
 ucapi/switch.py
+ucapi/ui.py
 ucapi.egg-info/PKG-INFO
 ucapi.egg-info/SOURCES.txt
 ucapi.egg-info/dependency_links.txt

{ucapi-0.1.7 → ucapi-0.3.0}/ucapi.egg-info/requires.txt

@@ -1,5 +1,5 @@
 pyee>=9.0
-websockets>=11.0
+websockets>=14.0
 zeroconf>=0.120.0
 
 [testing]