ucapi 0.1.6__tar.gz → 0.2.0__tar.gz

{ucapi-0.1.6 → ucapi-0.2.0}/CHANGELOG.md

@@ -11,6 +11,14 @@ _Changes in the next release_
 
 ---
 
+## 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)).
+
 ## v0.1.6 - 2024-03-04
 ### Added
 - Media-player RepeatMode enum and new features: context_menu, settings

{ucapi-0.1.6/ucapi.egg-info → ucapi-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ucapi
-Version: 0.1.6
+Version: 0.2.0
 Summary: Python wrapper for the Unfolded Circle Integration API
 Author-email: Unfolded Circle ApS <hello@unfoldedcircle.com>
 License: MPL-2.0

{ucapi-0.1.6 → ucapi-0.2.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.2.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.2.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.2.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.6 → ucapi-0.2.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.6 → ucapi-0.2.0}/ucapi/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.1.6'
-__version_tuple__ = version_tuple = (0, 1, 6)
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)

{ucapi-0.1.6 → ucapi-0.2.0}/ucapi/api.py

@@ -25,6 +25,7 @@ from zeroconf import IPVersion
 from zeroconf.asyncio import AsyncServiceInfo, AsyncZeroconf
 
 import ucapi.api_definitions as uc
+from ucapi import media_player
 from ucapi.entities import Entities
 
 _LOG = logging.getLogger(__name__)
@@ -258,10 +259,14 @@ class IntegrationAPI:
         :param category: event category
         """
         data = {"kind": "event", "msg": msg, "msg_data": msg_data, "cat": category}
+        data_dump = json.dumps(data)
+        # filter fields
+        if _LOG.isEnabledFor(logging.DEBUG):
+            data_log = json.dumps(data) if filter_log_msg_data(data) else data_dump
 
         for websocket in self._clients:
-            data_dump = json.dumps(data)
-            _LOG.debug("[%s] ->: %s", websocket.remote_address, data_dump)
+            if _LOG.isEnabledFor(logging.DEBUG):
+                _LOG.debug("[%s] ->: %s", websocket.remote_address, data_log)
             try:
                 await websocket.send(data_dump)
             except websockets.exceptions.WebSocketException:
@@ -282,10 +287,12 @@ class IntegrationAPI:
             websockets.ConnectionClosed: When the connection is closed.
         """
         data = {"kind": "event", "msg": msg, "msg_data": msg_data, "cat": category}
+        data_dump = json.dumps(data)
 
         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 event: connection no longer established")
@@ -843,3 +850,29 @@ def local_hostname() -> str:
         os.getenv("UC_MDNS_LOCAL_HOSTNAME")
         or f"{socket.gethostname().split('.', 1)[0]}.local."
     )
+
+
+def filter_log_msg_data(data: dict[str, Any]) -> bool:
+    """
+    Filter attribute fields to exclude for log messages in the given msg data dict.
+
+    Attention: the dictionary is modified!
+
+    - Attributes are filtered in `data["msg_data"]["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
+    return False

{ucapi-0.1.6 → ucapi-0.2.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.6 → ucapi-0.2.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"
 
@@ -42,8 +43,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.2.0/ucapi/remote.py

@@ -0,0 +1,167 @@
+"""
+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.
+    """  # noqa
+
+    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.2.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.6 → ucapi-0.2.0/ucapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ucapi
-Version: 0.1.6
+Version: 0.2.0
 Summary: Python wrapper for the Unfolded Circle Integration API
 Author-email: Unfolded Circle ApS <hello@unfoldedcircle.com>
 License: MPL-2.0

{ucapi-0.1.6 → ucapi-0.2.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