unfoldedcircle/integration-python-library

Python API wrapper for the Unfolded Circle Integration API

Python API wrapper for the UC Integration API

This library simplifies writing Python based integrations for the Unfolded Circle Remote Two by wrapping the WebSocket Integration API.

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.

❗️Attention:

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 :-)

Not yet supported:

• Secure WebSocket
• Token based authentication

Requirements:

• Python 3.10 or newer

Installation

Use pip:

pip3 install ucapi

See examples directory for a minimal integration driver example. More examples will be published.

Environment Variables

Certain features can be configured by environment variables:

Variable	Values	Description
UC_CONFIG_HOME	directory path	Configuration directory to save the user configuration from the driver setup. Default: $HOME or current directory
UC_INTEGRATION_INTERFACE	address	Listening interface for WebSocket server. Default: 0.0.0.0
UC_INTEGRATION_HTTP_PORT	number	WebSocket listening port. Default: port field in driver metadata json file, if not specified: 9090
UC_MDNS_LOCAL_HOSTNAME	hostname	Published local hostname in mDNS service announcement. Default: short hostname with .local domain.
UC_DISABLE_MDNS_PUBLISH	true / false	Disables mDNS service advertisement. Default: false

Versioning

We use SemVer for versioning. For the versions available, see the tags and releases on this repository.

Changelog

The major changes found in each new release are listed in the changelog and under the GitHub releases.

Contributions

Please read our contribution guidelines before opening a pull request.

License

This project is licensed under the Mozilla Public License 2.0. See the LICENSE file for details.

integration-python-library's Issues

How to use? setup.py install is deprecated

/opt/homebrew/lib/python3.11/site-packages/setuptools/_distutils/cmd.py:66: SetuptoolsDeprecationWarning: setup.py install is deprecated.
!!

        ********************************************************************************
        Please avoid running ``setup.py`` directly.
        Instead, use pypa/build, pypa/installer or other
        standards-based tools.

        See https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html for details.
        ********************************************************************************

!!

Where's the wheelfile.whl mentionend in the README pip3 install /path/to/wheelfile.whl?

As long as this library isn't published, can't it be referenced with a relative path in requirements.txt of an integration?

UC_INTEGRATION_INTERFACE is an optional ENV var

The UC_INTEGRATION_INTERFACE environment variable is an optional setting to configure the listening interface.

Current behaviour is that if it is not set, the WebSocket listening doesn't work.

Expected: optional env var, if not set use 0.0.0.0

Simplify entity attribute updates

At the moment one has to use the ucapi.configured_entities.update_attributes method to change an entity attribute.

With the new entity command handler, this is a bit akward. The received entity object should allow direct attribute updates, which also trigger a change event. Directly modifying an attribute on the received entity will not trigger any events.

Proposed changes:

• add an update_attribute method to the entity class
  • either a generic method for all subclassed entities, or a concrete method per entity.
  • for most use cases, a single attribute update is enough. But there are cases where multiple attributes must be updated at the same time, e.g. for light color changes.
    • Either add an additional update_attributes method, or design a single method which allows both.
• changed attributes will trigger a change event

This could then be used in a command handler:

async def switch_cmd_handler(
    entity: ucapi.Switch, cmd_id: str, _params: dict[str, Any] | None
) -> ucapi.StatusCodes:
    print(f"Got {entity.id} command request: {cmd_id}")

    state = None
    if cmd_id == switch.Commands.ON:
        # implement ON logic...
        state = switch.States.ON
    elif cmd_id == switch.Commands.OFF:
        # implement OFF logic...
        state = switch.States.OFF

    if state:
        entity.update_attribute(switch.Attributes.STATE, state)

    return ucapi.StatusCodes.OK

Integrations crash if UC_INTEGRATION_HTTP_PORT ENV var is not set

Integrations crash if UC_INTEGRATION_HTTP_PORT is not set:

  File "/Users/mzehnder/projects/personal/yio-remote/aitatoi/integration-denonavr/venv/lib/python3.11/site-packages/ucapi/api.py", line 67, in init
    self.driverInfo["driver_url"] = self.getDriverUrl(
                                    ^^^^^^^^^^^^^^^^^^
  File "/Users/mzehnder/projects/personal/yio-remote/aitatoi/integration-denonavr/venv/lib/python3.11/site-packages/ucapi/api.py", line 108, in getDriverUrl
    return "ws://" + self._interface + ":" + port
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^~~~~~
TypeError: can only concatenate str (not "NoneType") to str

Expected: no runtime error, defined error and exit code if a required setting is missing.
There should also be a default port if the integration doesn't overwrite it. AFAIK the Node library has a default port set.

Refactor entity management

The separate backing lists for available and configured entities makes it more difficult for the integrations to properly manage entity states and attributes.
Furthermore, the get_available_entities should return all entities, no matter if the Remote Two has subscribed to certain entities or not. (This probably needs some clarifications in the WebSocket Integration-API as well).
There should only be one backing list with either additional attributes or metadata holding the subscription state.

[QUESTION]: How to listen for `get_available_entities`

This may a be a daft question... how would I listen to the WsMessages.GET_AVAILABLE_ENTITIES so that I can rebuild the list of available entities? This message seems to be issued when the Reload link is clicked in the Web Configurator.

What I'm trying to achieve... As I iterate through building the integration I will be adding new entities (mainly buttons) and quite possibly removing them too. I'm looking for a way to effectively be able to build those entities for both a new setup and for an existing setup. In addition any buttons I remove should also be removed (or at the very list flagged for removal).

I hope this makes sense.

Filter out base64 encoded images in json message log

Some integrations send base64 encoded images in the media_image_url field. This causes excessive logging and needs to be filtered out.