ucapi 0.4.0__tar.gz → 0.5.0__tar.gz

{ucapi-0.4.0 → ucapi-0.5.0}/CHANGELOG.md

@@ -11,6 +11,20 @@ _Changes in the next release_
 
 ---
 
+## v0.5.0 - 2025-12-17
+### Breaking Changes
+- Enhance entity command handler with WS client connection parameter in `CommandHandler` callback and `Entity.command`
+  method to allow clients to send back event messages ([#38](https://github.com/unfoldedcircle/integration-python-library/pull/38)).
+  - The implementation is currently backward-compatible but will be removed in a future release.
+
+### Added
+- New voice-assistant entity with voice-stream session handling ([#38](https://github.com/unfoldedcircle/integration-python-library/pull/38)).
+  - This requires firmware 2.8.2 or newer to work correctly.
+
+### Changed
+- Remove logging in Entities.get method if entity doesn't exist. This could lead to excessive logging in some integrations ([#38](https://github.com/unfoldedcircle/integration-python-library/pull/38)).
+- Prepare for Python 3.12 and 3.13: replace `asyncio.get_event_loop()` calls in the examples with `asyncio.new_event_loop()` ([#39](https://github.com/unfoldedcircle/integration-python-library/pull/39)).
+
 ## v0.4.0 - 2025-11-24
 ### Breaking Changes
 - A WebSocket disconnection no longer emits the `DISCONNECT` event, but the new `CLIENT_DISCONNECTED` event ([#35](https://github.com/unfoldedcircle/integration-python-library/pull/35)).

{ucapi-0.4.0/ucapi.egg-info → ucapi-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucapi
-Version: 0.4.0
+Version: 0.5.0
 Summary: Python wrapper for the Unfolded Circle Integration API
 Author-email: Unfolded Circle ApS <hello@unfoldedcircle.com>
 License: MPL-2.0
@@ -16,16 +16,16 @@ Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Home Automation
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown; charset=UTF-8
 License-File: LICENSE
+Requires-Dist: protobuf~=6.33.2
 Requires-Dist: pyee>=9.0
 Requires-Dist: websockets>=14.0
 Requires-Dist: zeroconf>=0.120.0
 Provides-Extra: testing
-Requires-Dist: pylint; extra == "testing"
+Requires-Dist: pylint==4.0.4; extra == "testing"
 Requires-Dist: flake8-docstrings; extra == "testing"
 Requires-Dist: flake8; extra == "testing"
 Requires-Dist: black; extra == "testing"
@@ -38,12 +38,14 @@ Dynamic: license-file
 [![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 devices](https://www.unfoldedcircle.com/)
-by wrapping the [WebSocket Integration API](https://github.com/unfoldedcircle/core-api/tree/main/integration-api).
+by wrapping the [WebSocket Integration API](https://github.com/unfoldedcircle/core-api/tree/main/integration-api)
+and supporting the [available entities](https://unfoldedcircle.github.io/core-api/entities/).
 
-It's an alpha release (in our eyes). Breaking changes are to be expected and missing features will be continuously added.
-Based on our [Node.js integration library](https://github.com/unfoldedcircle/integration-node-library).
+> [!NOTE]
+> Please note that this library is more of a convenience Python wrapper for the WebSocket Integreation-API than a
+> full-featured SDK. It is based on our [Node.js integration library](https://github.com/unfoldedcircle/integration-node-library).
 
-❗️**Attention:**
+> [!IMPORTANT]
 > This is our first Python project, and we don't see ourselves as Python professionals.  
 > Therefore, the library is most likely not yet that Pythonic!  
 > We are still learning and value your feedback on how to improve it :-)
@@ -51,10 +53,15 @@ Based on our [Node.js integration library](https://github.com/unfoldedcircle/int
 Not yet supported:
 
 - Secure WebSocket
-- Token based authentication
+- Token-based authentication
 
 Requirements:
-- Python 3.10 or newer
+- Python 3.11 or newer
+
+Integrations using this library:
+  - [Android TV integration](https://github.com/unfoldedcircle/integration-androidtv)
+  - [Apple TV integration](https://github.com/unfoldedcircle/integration-appletv)
+  - [Denon AVR integration](https://github.com/unfoldedcircle/integration-denonavr)
 
 ## Installation
 
@@ -63,8 +70,7 @@ Use pip:
 pip3 install ucapi
 ```
 
-See [examples directory](https://github.com/aitatoi/integration-python-library/blob/main/examples) for a minimal
-integration driver example. More examples will be published.
+See [examples directory](https://github.com/aitatoi/integration-python-library/blob/main/examples) for some minimal integration driver examples.
 
 ### Environment Variables
 

{ucapi-0.4.0 → ucapi-0.5.0}/README.md

@@ -4,12 +4,14 @@
 [![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 devices](https://www.unfoldedcircle.com/)
-by wrapping the [WebSocket Integration API](https://github.com/unfoldedcircle/core-api/tree/main/integration-api).
+by wrapping the [WebSocket Integration API](https://github.com/unfoldedcircle/core-api/tree/main/integration-api)
+and supporting the [available entities](https://unfoldedcircle.github.io/core-api/entities/).
 
-It's an alpha release (in our eyes). Breaking changes are to be expected and missing features will be continuously added.
-Based on our [Node.js integration library](https://github.com/unfoldedcircle/integration-node-library).
+> [!NOTE]
+> Please note that this library is more of a convenience Python wrapper for the WebSocket Integreation-API than a
+> full-featured SDK. It is based on our [Node.js integration library](https://github.com/unfoldedcircle/integration-node-library).
 
-❗️**Attention:**
+> [!IMPORTANT]
 > This is our first Python project, and we don't see ourselves as Python professionals.  
 > Therefore, the library is most likely not yet that Pythonic!  
 > We are still learning and value your feedback on how to improve it :-)
@@ -17,10 +19,15 @@ Based on our [Node.js integration library](https://github.com/unfoldedcircle/int
 Not yet supported:
 
 - Secure WebSocket
-- Token based authentication
+- Token-based authentication
 
 Requirements:
-- Python 3.10 or newer
+- Python 3.11 or newer
+
+Integrations using this library:
+  - [Android TV integration](https://github.com/unfoldedcircle/integration-androidtv)
+  - [Apple TV integration](https://github.com/unfoldedcircle/integration-appletv)
+  - [Denon AVR integration](https://github.com/unfoldedcircle/integration-denonavr)
 
 ## Installation
 
@@ -29,8 +36,7 @@ Use pip:
 pip3 install ucapi
 ```
 
-See [examples directory](https://github.com/aitatoi/integration-python-library/blob/main/examples) for a minimal
-integration driver example. More examples will be published.
+See [examples directory](https://github.com/aitatoi/integration-python-library/blob/main/examples) for some minimal integration driver examples.
 
 ### Environment Variables
 

ucapi-0.5.0/docs/setup.md

@@ -0,0 +1,43 @@
+# Development Setup
+
+This library requires Python 3.10 or newer.
+
+Install build tools:
+```shell
+pip3 install build setuptools setuptools_scm
+```
+
+Build:
+```shell
+python -m build
+```
+
+Local installation:
+```shell
+pip3 install --force-reinstall dist/ucapi-$VERSION-py3-none-any.whl
+```
+
+## Protobuf
+
+1. Optional (recommended): install the Python plugin toolchain for consistent results:
+   ```bash
+   python3 -m pip install --upgrade grpcio-tools protobuf
+   ```
+2. From the project root, run:
+   ```bash
+   python3 scripts/compile_protos.py
+   ```
+   - This will generate `ucapi/proto/ucr_integration_voice_pb2.py` (and `.pyi` if supported).
+3. Add and commit the generated files to Git:
+   ```bash
+   git add ucapi/proto/ucr_integration_voice_pb2.py ucapi/proto/ucr_integration_voice_pb2.pyi || true
+   git commit -m "Generate protobuf Python modules for voice integration"
+   ```
+
+Notes:
+- The library does not re-generate at build time; we ship the generated code with the package.
+- If you prefer using system `protoc`, ensure it’s on `PATH`; the script will fall back to it automatically.
+- Imports at runtime (if/when needed) will look like:
+  ```python
+  from ucapi.proto import ucr_integration_voice_pb2 as voice_pb2
+  ```

{ucapi-0.4.0 → ucapi-0.5.0}/examples/README.md

@@ -1,6 +1,6 @@
 # API wrapper examples
 
-This directory contains a few examples on how to use the Remote Two Integration-API wrapper.
+This directory contains a few examples on how to use the Remote Two/3 Integration-API wrapper.
 
 Each example uses a driver metadata definition file. It's a json file named after the example.
 The most important fields are:
@@ -39,3 +39,9 @@ and are not yet available as typed Python objects.
 
 See `Setting` object definition and the referenced SettingTypeNumber, SettingTypeText, SettingTypeTextArea,
 SettingTypePassword, SettingTypeCheckbox, SettingTypeDropdown, SettingTypeLabel. 
+
+## voice
+
+The [voice ](voice.py) example shows how to use the voice-assistant entity and receiving a microphone audio stream.
+
+Firmware version 2.8.2 or higher is required.

{ucapi-0.4.0 → ucapi-0.5.0}/examples/hello_integration.py

@@ -6,12 +6,12 @@ from typing import Any
 
 import ucapi
 
-loop = asyncio.get_event_loop()
+loop = asyncio.new_event_loop()
 api = ucapi.IntegrationAPI(loop)
 
 
 async def cmd_handler(
-    entity: ucapi.Button, cmd_id: str, _params: dict[str, Any] | None
+    entity: ucapi.Button, cmd_id: str, _params: dict[str, Any] | None, websocket: Any
 ) -> ucapi.StatusCodes:
     """
     Push button command handler.
@@ -21,6 +21,7 @@ async def cmd_handler(
     :param entity: button entity
     :param cmd_id: command
     :param _params: optional command parameters
+    :param websocket: optional client connection for sending directed events
     :return: status of the command
     """
     print(f"Got {entity.id} command request: {cmd_id}")

{ucapi-0.4.0 → ucapi-0.5.0}/examples/remote.py

@@ -20,7 +20,7 @@ from ucapi.ui import (
     create_ui_text,
 )
 
-loop = asyncio.get_event_loop()
+loop = asyncio.new_event_loop()
 api = ucapi.IntegrationAPI(loop)
 
 # Simple commands which are supported by this example remote-entity
@@ -46,7 +46,7 @@ supported_commands = [
 
 
 async def cmd_handler(
-    entity: ucapi.Remote, cmd_id: str, params: dict[str, Any] | None
+    entity: ucapi.Remote, cmd_id: str, params: dict[str, Any] | None, websocket: Any
 ) -> ucapi.StatusCodes:
     """
     Remote command handler.
@@ -56,6 +56,7 @@ async def cmd_handler(
     :param entity: remote entity
     :param cmd_id: command
     :param params: optional command parameters
+    :param websocket: optional client connection for sending directed events
     :return: status of the command
     """
     print(f"Got {entity.id} command request: {cmd_id}")

{ucapi-0.4.0 → ucapi-0.5.0}/examples/setup_flow.py

@@ -6,7 +6,7 @@ from typing import Any
 
 import ucapi
 
-loop = asyncio.get_event_loop()
+loop = asyncio.new_event_loop()
 api = ucapi.IntegrationAPI(loop)
 
 
@@ -38,7 +38,7 @@ async def handle_driver_setup(
     """
     Start driver setup.
 
-    Initiated by Remote Two to set up the driver.
+    Initiated by Remote Two/3 to set up the driver.
 
     :param msg: value(s) of input fields in the first setup screen.
     :return: the setup action on how to continue
@@ -157,7 +157,7 @@ async def handle_user_data_response(msg: ucapi.UserDataResponse) -> ucapi.SetupA
 
 
 async def cmd_handler(
-    entity: ucapi.Button, cmd_id: str, _params: dict[str, Any] | None
+    entity: ucapi.Button, cmd_id: str, _params: dict[str, Any] | None, websocket: Any
 ) -> ucapi.StatusCodes:
     """
     Push button command handler.
@@ -167,6 +167,7 @@ async def cmd_handler(
     :param entity: button entity
     :param cmd_id: command
     :param _params: optional command parameters
+    :param websocket: optional client connection for sending directed events
     :return: status of the command
     """
     print(f"Got {entity.id} command request: {cmd_id}")

ucapi-0.5.0/examples/voice.json

@@ -0,0 +1,18 @@
+{
+  "driver_id": "voice_test",
+  "version": "0.0.1",
+  "min_core_api": "0.20.0",
+  "name": { "en": "Voice test" },
+  "icon": "uc:integration",
+  "description": {
+    "en": "Minimal Python integration driver example for voice commands."
+  },
+  "port": 9084,
+  "developer": {
+    "name": "Unfolded Circle ApS",
+    "email": "hello@unfoldedcircle.com",
+    "url": "https://www.unfoldedcircle.com"
+  },
+  "home_page": "https://www.unfoldedcircle.com",
+  "release_date": "2025-12-11"
+}

ucapi-0.5.0/examples/voice.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""Simple voice assistant entity integration example.
+
+Requires firmware 2.8.2 or newer.
+
+See the [Android TV integration](https://github.com/unfoldedcircle/integration-androidtv)
+for a full implementation.
+"""
+
+import asyncio
+import logging
+from asyncio import sleep
+from typing import Any
+
+import ucapi
+from ucapi import (
+    AssistantError,
+    AssistantErrorCode,
+    AssistantEvent,
+    AssistantEventType,
+    VoiceAssistant,
+)
+from ucapi.api_definitions import AssistantSttResponse, AssistantTextResponse
+from ucapi.voice_assistant import Attributes as VAAttr
+from ucapi.voice_assistant import (
+    AudioConfiguration,
+)
+from ucapi.voice_assistant import Commands as VACommands
+from ucapi.voice_assistant import Features as VAFeatures
+from ucapi.voice_assistant import (
+    SampleFormat,
+    VoiceAssistantEntityOptions,
+)
+from ucapi.voice_stream import VoiceEndReason, VoiceSession, VoiceSessionClosed
+
+loop = asyncio.new_event_loop()
+api = ucapi.IntegrationAPI(loop)
+
+
+@api.listens_to(ucapi.Events.CONNECT)
+async def on_connect() -> None:
+    # When the remote connects, we just set the device state. We are ready all the time!
+    await api.set_device_state(ucapi.DeviceStates.CONNECTED)
+
+
+@api.listens_to(ucapi.Events.SUBSCRIBE_ENTITIES)
+async def on_subscribe_entities(entity_ids: list[str]) -> None:
+    for entity_id in entity_ids:
+        api.configured_entities.update_attributes(entity_id, {VAAttr.STATE: "ON"})
+
+
+async def on_voice_cmd(
+    entity: ucapi.VoiceAssistant,
+    cmd_id: str,
+    params: dict[str, Any] | None,
+    websocket: Any,
+) -> ucapi.StatusCodes:
+    """
+    Voice assistant command handler.
+
+    Called by the integration-API if a command is sent to a configured voice_assistant-entity.
+
+    :param entity: Voice assistant entity
+    :param cmd_id: command
+    :param params: optional command parameters
+    :param websocket: optional client connection for sending directed events
+    :return: status of the command
+    """
+    print(f"Got {entity.id} command request: {cmd_id} {params}")
+    if params is None:
+        return ucapi.StatusCodes.BAD_REQUEST
+
+    session_id = params.get("session_id", 0)
+    if session_id <= 0:
+        return ucapi.StatusCodes.BAD_REQUEST
+
+    if cmd_id == VACommands.VOICE_START:
+        asyncio.create_task(start_voice(websocket, session_id))
+        # Acknowledge start; binary audio will arrive on the WS binary channel
+        return ucapi.StatusCodes.OK
+    return ucapi.StatusCodes.NOT_IMPLEMENTED
+
+
+async def start_voice(websocket: Any, session_id: int):
+    # Here we'd set up the voice communication to the target device / system
+    await sleep(0.5)
+
+    # Once ready, send the READY event to the remote to start the voice stream.
+    # Otherwise, AssistantEventType.ERROR should be sent instead.
+    ready_evt = AssistantEvent(
+        type=AssistantEventType.READY,
+        entity_id=entity.id,
+        session_id=session_id,
+    )
+    await api.send_assistant_event(websocket, ready_evt)
+
+
+async def on_voice_session(session: VoiceSession):
+    print(
+        f"Voice stream started: session={session.session_id}, "
+        f"{session.config.channels}ch @ {session.config.sample_rate} Hz {session.config.sample_format}"
+    )
+
+    # Note: a real driver should check if the session_id matches the one from the voice_start command
+
+    total = 0
+    try:
+        async for frame in session:  # frame is bytes
+            total += len(frame)
+            # feed frame into your voice assistant / LLM here
+            print(f"Got {len(frame)} bytes of audio data")
+        print(f"Voice stream ended: session={session.session_id}, bytes={total}")
+
+        event = AssistantEvent(
+            type=AssistantEventType.STT_RESPONSE,
+            entity_id=session.entity_id,
+            session_id=session.session_id,
+            data=AssistantSttResponse(
+                text="I'm just a demo and I don't know what you said."
+            ),
+        )
+        await session.send_event(event)
+
+        await sleep(1)
+        event = AssistantEvent(
+            type=AssistantEventType.TEXT_RESPONSE,
+            entity_id=session.entity_id,
+            session_id=session.session_id,
+            data=AssistantTextResponse(
+                success=True, text=f"You have sent {total} bytes of audio data"
+            ),
+        )
+        await session.send_event(event)
+
+        await sleep(1)
+    except VoiceSessionClosed as ex:
+        print(
+            f"Voice stream session {session.session_id} closed (bytes={total})! Reason: {ex.reason}, exception: {ex.error}"
+        )
+        if ex.reason == VoiceEndReason.REMOTE:
+            return  # Remote disconnected
+        event = AssistantEvent(
+            type=AssistantEventType.ERROR,
+            entity_id=session.entity_id,
+            session_id=session.session_id,
+            data=AssistantError(
+                code=(
+                    AssistantErrorCode.TIMEOUT
+                    if ex.reason == VoiceEndReason.TIMEOUT
+                    else AssistantErrorCode.UNEXPECTED_ERROR
+                ),
+                message=f"Reason: {ex.reason}, exception: {ex.error}",
+            ),
+        )
+        await session.send_event(event)
+
+    # final event
+    event = AssistantEvent(
+        type=AssistantEventType.FINISHED,
+        entity_id=session.entity_id,
+        session_id=session.session_id,
+    )
+    await session.send_event(event)
+
+
+if __name__ == "__main__":
+    logging.basicConfig()
+
+    entity = VoiceAssistant(
+        identifier="va_main",
+        name={"en": "Demo Voice Assistant"},
+        features=[VAFeatures.TRANSCRIPTION, VAFeatures.RESPONSE_TEXT],
+        attributes={VAAttr.STATE.value: "ON"},
+        options=VoiceAssistantEntityOptions(
+            audio_cfg=AudioConfiguration(
+                channels=1, sample_rate=16000, sample_format=SampleFormat.I16
+            ),
+        ),
+        cmd_handler=on_voice_cmd,
+    )
+
+    api.available_entities.add(entity)
+    api.set_voice_stream_handler(on_voice_session)
+
+    loop.run_until_complete(api.init("voice.json"))
+    loop.run_forever()

{ucapi-0.4.0 → ucapi-0.5.0}/pyproject.toml

@@ -16,11 +16,11 @@ classifiers = [
     "Operating System :: OS Independent",
     "Topic :: Software Development :: Libraries",
     "Topic :: Home Automation",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
 ]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 dependencies = [
+    "protobuf~=6.33.2",
     "pyee>=9.0",
     "websockets>=14.0",
     "zeroconf>=0.120.0",
@@ -40,7 +40,7 @@ content-type = "text/markdown; charset=UTF-8"
 
 [project.optional-dependencies]
 testing = [
-    "pylint",
+    "pylint==4.0.4",
     "flake8-docstrings",
     "flake8",
     "black",
@@ -48,7 +48,7 @@ testing = [
 ]
 
 [tool.setuptools]
-packages = ["ucapi"]
+packages = ["ucapi", "ucapi.proto"]
 platforms = ["any"]
 license-files = ["LICENSE"]
 
@@ -57,6 +57,7 @@ write_to = "ucapi/_version.py"
 
 [tool.isort]
 profile = "black"
+skip_glob = ["ucapi/proto/*_pb2.py", "ucapi/proto/*_pb2.pyi"]
 
 [tool.pylint.exceptions]
 overgeneral-exceptions = ["builtins.BaseException", "builtins.Exception"]
@@ -64,10 +65,13 @@ overgeneral-exceptions = ["builtins.BaseException", "builtins.Exception"]
 [tool.pylint.format]
 max-line-length = "88"
 
-[tool.pylint.MASTER]
+[tool.pylint.main]
 ignore-paths = [
     # ignore generated file
-    "ucapi/_version.py"
+    "ucapi/_version.py",
+    # ignore generated protobuf modules (Python + type stubs and optional gRPC stubs)
+    "ucapi/proto/.*_pb2.py",
+    "ucapi/proto/.*_pb2.pyi",
 ]
 
 [tool.pylint."messages control"]
@@ -93,3 +97,13 @@ disable = [
 # This flag controls whether inconsistent-quotes generates a warning when the
 # character used as a quote delimiter is used inconsistently within a module.
 check-quote-consistency = true
+
+
+[tool.black]
+line-length = 88
+# Exclude generated protobuf modules, even if passed explicitly to Black
+force-exclude = """
+(
+  proto/.+_pb2(?:_grpc)?\\.pyi?$  # *_pb2.py, *_pb2.pyi, *_pb2_grpc.py
+)
+"""

{ucapi-0.4.0 → ucapi-0.5.0}/requirements.txt

@@ -2,6 +2,7 @@
 # Waiting for: https://github.com/pypa/pip/issues/11440
 # Workaround: use a pre-commit hook with https://github.com/scikit-image/scikit-image/blob/main/tools/generate_requirements.py
 
+protobuf~=6.33.2
 pyee>=9.0
 websockets>=14.0
 zeroconf>=0.120.0