unfoldedcircle/core-api

API specifications for Remote Two by Unfolded Circle

Unfolded Circle Core APIs

This repository contains API specifications of Unfolded Circle Remote Two products.

Overview

• Remote Two user interface

API definitions:

• WebSocket Integration API defined with AsyncAPI.
• WebSocket Core API defined with AsyncAPI
• REST Core API defined with OpenAPI
• WebSocket Dock API defined with AsyncAPI

Integration driver documentation:

• Remote Two entities.
• How to write an integration driver.
• WebSocket handling: authentication, keep alive, error handling.

Integration API

The Remote Two WebSockets integrations API allows writing device integrations for the Unfolded Circle Remote Two and former YIO remote devices.
At the moment only user integrations running on an external host are supported.

The integration driver acts as server and the Remote Two as client. The remote connects to the integration when an integration instance is configured. Whenever the remote enters standby it may choose to disconnect and automatically reconnect again after wakeup.

The goal of the integration API is to cover not only simple static drivers, like controlling GPIOs on a Raspberry Pi, but also support to integrate existing home automation hubs like Home Assistant, Homey, openHAB etc.
The focus of the integration API is on entity integration, not on controlling or configuring the Remote Two. Please refer to the core-API for further functionality.

An integration driver usually doesn't need to use the core-API as well, unless it also wants to customize certain device behaviour or automatically add or configure its entities to the users profile.

Develop integration drivers

Since we are providing an API and not an SDK for a specific programming language, one can develop integrations in any language which is capable running a WebSockets server.

The downside of an API is that more low-level coding is required. In our case this involves running a WebSocket server, handling the connections from the Remote Two, and parsing the JSON payload in the WebSocket text messages. However, once this is done, the required API message interactions are rather simple to handle.

See how to write an integration driver for more information about how to develop an integration driver for the Remote Two.

Examples

• API models in Rust
• Node.js API wrapper for the UC Integration API
• Python API wrapper library for the UC Integration API
  Integrations using the Python API wrapper:
  • Android TV integration
  • Apple TV integration
  • Denon AVR integration
• Home Assistant integration written in Rust

We plan to release more examples in the future.

Core APIs

The Remote Two WebSockets & REST core APIs allow you to interact with the Unfolded Circle remote-core application and take full control of its features.

See core-api directory for more information.

Other resources

• remote-core simulator to start developing integrations without a Remote Two device
• Open Source remote-ui application

API versioning

The API is versioned according to SemVer.
The initial public release will be 1.0.0 once it is considered stable enough with some initial integration implementations and developer examples.

Any major version zero (0.y.z) is for initial development and may change at any time!
I.e. backward compatibility for minor releases is not yet established, anything MAY change at any time!

Recent changes

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

The Dock-API follows an independent release process. The Dock-API changes are listed in the Dock-API changelog.

Contributions

Please read our contribution guidelines before opening a pull request.

License

We have published the API specifications and documentations under the CC-BY-AS-4.0 (Creative Commons Attribution-ShareAlike 4.0 International) license. Please see LICENSE file.
All code examples in this repository are licensed under the Apache License 2.0.
All graphics copyright © Unfolded Circle ApS 2022.

core-api's Issues

Extending on/off switch entity to multi-state switch or list entity

Is your feature request related to a problem? Please describe.

Anticipating the openHAB integration, I wonder how will be modeled openHAB items with multiple states. For example : house mode can be AWAY/HOME/NIGHT, alarm modes, audio inputs, light scene modes... Plenty of my items are multistate item.

Describe the solution you'd like

It would be great to "extend" the switch to a multistate switch that could display as a list, a dropdown list or a multi-options item. Such an item could handle the commands NEXT and PREVIOUS to change from one mode to the next (as TOGGLE does for a 2-states switch)

Describe alternatives you've considered

No idea how to model multistate items by now !

Additional context

New command "Wait until WiFi"

I would have liked to build this myself and send a pull request for this enhancement, but I have no clue in which repo to do it...

Since it takes a while to connect to WiFi, it would be amazing if there was a command like "Wait for WiFi" when turning on an activity. Now I need to add a delay of 2 seconds even though this is sometimes too short and sometimes completely unnecessary.

Update AsyncAPI version to 2.4.0

Wait for an update of the AsyncAPI validation GitHub action WaleedAshraf/asyncapi-github-action, or replace it with a
DIY GitHub action calling the validation tool.

v0.0.6 of the action only supports AsyncAPI 2.2.0

[bug] min_core_api is not checked

Description

I noticed that I can enter any string or version number for min_core_api in the setup json data and it is not checked by the remote when you add the integration to it. Neither the API nor the web configurator give any feedback that the currently used core API is older than the one required by the integration.

How to Reproduce

1. Set min_core_api in setup.json to a currently non existing version like 2.0
2. Add the integration to the remote

Expected behavior

When adding an integration the API should check if the version number from min_core_api is higher than the core api version on the remote and should inform inform the user in this case via the the web configuratior and/or remote ui.

Your Environment

• Version used:
• Running on:
  • Remote Two (FW 1.7.7)
  • Simulator (v0.43.0-beta)
• Operating System and version if not running on a remote device: Ubuntu 22.04 (UC VM Image)

Link Home Assistant open source integration once published

The Home Assistant integration will be the first open source integration driver for the Remote Two written in Rust.
Update documentation with link to repository.

Publish Core API

Publish the REST and WebSocket based core APIs in this repository.

Additional tasks:

• add links in documentation.
• GitHub actions for validating AsyncAPI & OpenAPI definitions.
• badges in main README for all validation actions.
• GitHub actions for generating html documentation from API definitions.

Stopped driver reconnects after standby

Description

If you stop an external driver via the the REST API (PUT /intg/drivers/{driverId}), wait for the remote to go into standby and then exit standby mode the driver is not in idle status anymore and tries to reconnect.
I'm not sure if this is a bug or the expected behaviour. Otherwise this can be converted into a feature request.

How to Reproduce

1. Stop an external driver via the REST API (PUT /intg/drivers/{driverId})
2. Wait for the remote to enter standby mode
3. Exit standby mode

Expected behavior

All stopped drivers should have the same status before the remote has entered standby mode.

Your Environment

• Version used: 1.7.7
• Running on:
  • Remote Two

Additional context

I personally use the start and stop command for test versions of my integrations that are not running 24/7. When the driver is not in idle mode the remote constantly tries to reconnect to the integration and I need to delete the driver configuration to stop this.

Move common models in AsyncAPI definitions into shared external files

The core and integration APIs share common models which should not be copy pasted all over the place.

Even though the AsyncAPI specification supports external references, the tooling support to handle external references is quite disappointing.
Especially if one is used to the great swagger-cli bundle support with OpenAPI definitions. This puts everything back into one file for all the other tools not able to handle external references.

The AsyncAPI Bundler has serious issues bundling external references. Last time I've checked all reused references were duplicated, instead of being referenced in the final YAML file!

Most likely this issue needs to be fixed first: asyncapi/bundler#34
Otherwise, we have to hack together something, since copying and pasting the shared definitions between the different APIs makes no sense...

Search replacement for swagger-validator-action

The GitHub action mbowman100/swagger-validator-action@master used to validate OpenAPI seems unmaintained. It's only a matter of time until GitHub disables the set-output command and the action breaks.
I've opened an issue: mbowman100/swagger-validator-action#16

We should search for an alternative if the action is no longer maintained, e.g. https://github.com/char0n/swagger-editor-validate seems to be up to date.

Media player entity missing commands

Actually the media player entity has most builtin commands : play/pause, arrow keys, home, back...
But some important commands are missing and are commonly used by media players :

• Context menu : popup menu for media streamers or bluray players (mapped to KEYCODE_TV_MEDIA_CONTEXT_MENU for android tv integration)
• Keypad numbers 0 to 9 : mapped to KEYCODE_0 > KEYCODE_9 for android TV integration for example => useful to create a dedicated numpad page
• Audio and subtitles language switching : this one is more tricky as there are no common commands, but they are usually mapped to keyboard keys
• Keyboard keys : A-Z (KEYCODE_A... for android TV integration). Some applications use keys as shortcuts (kodi) to enable audio/subtitles language switching, display or hide OSD or menu

The current workaround is to create individual home assistant scripts per command to make the link and add them to the remote.

Also a customizable "send command" in the UI where the user can type in the command could be a good idea too if you don't want to declare all the commands.

I know that the remote entity is also planned apart, but to avoid declaring 2 entities for the same device like in home assistant, I think you should consider adding some of those missing (common) commands, especially the context menu.

Thank you

Link Rust API models once published

Update documentation with link to Rust API models repository.

Link dock API once published

Update documentation with link to dock API repository.

Missing hostname or device ID in APIs

Actually while using mdns discovery you can get the hostname of the remote as a unique ID in the format RemoteTwo-.local

But there this info cannot be retrieved using APIs

The use case is the following : adding the remote two to Home assistant (not the HA integration driver, but add the RC2 to home assistant to control it from HA)

1. Detect devices through mdns
2. User can select one of them or if not detected properly he will submit the IP address or hostname directly
3. The integration will store the new device information BUT will check before if the device does not already exist
   **=> problem we don't have any available device ID (serial number, hostname or mac address) to distinguish devices

The hostname and/or serial number and/or mac address should be added to remote API /pub/version of /pub/* to avoid unnecessary authentication

Thank you

Link remote-ui application once published

Update documentation with link to remote-ui repository.

Research API documentation website generator

As an integration developer I'd like to have an easy to access and browsable API documentation.
As an API developer I'd like to have a simple documentation tool, preferrably in Markdown, with diagram embedding support and not have to learn yet another documentation format or deal with html & css layouting.

The current solution with simple markdown files in this GitHub repository is not very end-user friendly. It's very simple for API developers to add things, but it's getting more complicated to group content and adding an easy navigation.

Research better documentation website generators and evaluate which tool to use. Requirements:

• easy to use for writing technical documentation, tailored to developers
• must support Markdown files as input
• GitHub integration, automated publishing with changed or added input documents
• should support Mermaid diagrams
  • already used in markdown files
  • supported by GitHub: https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/
• should support draw.io diagrams
• free to use or with reasonable licensing costs

At the moment we are aware of the following solutions:

• Hugo
  • Used in the former YIO project
• GitBook
  • Free for open source projects

Reddit discussion with lots of options: https://www.reddit.com/r/selfhosted/comments/kphfbl/is_there_a_self_hosted_gitbook_alternative/

[Question] Media Player Additional Features?

When using a media player entity to represent a set-top-box, how is it best to facilitate the number buttons, record and recorded shows buttons? The set-top-box (TiVo) I use also has a "Thumbs Up" and "Thumbs Down" functionality, how could these also be represented?

Expected Behavior or Design

I would expect the CHANNEL_SWITCHER to also include number buttons.

Current Behavior or Design

Currently the feature for CHANNEL_SWITCHER does not facilitate number buttons that would be used for changing channels. I also cannot see a feature that would imply the ability to record.

Possible Solution

I guess the options I'm after could be provided as additional Button entities that are associated with the same entity_id. However, this could overwhelm the UI or become cumbersome.

One option would be to provide additional features: -

1. NUMBER_BUTTONS - this would be responsible for the number commands for a media player
2. DVR - this would be responsible for providing functionality for "Record" and "My Recordings"
3. FAVOURITES - to expose a like and dislike option to mimic the thumbs up and down

Detailed Description and Additional Information

Publish generated HTML documentation from API definitions

• use GitHub action to generate html documentation from AsyncAPI definition
• use GitHub action to publish generated html documenation to GitHub pages
• activate GitHub pages
• add index page(s) for all generated API documentations

ENHANCEMENT request : Bluetooth range extension

What a wonderful product, I just signed up for the reservation form. Cannot wait to get my hands on one.
Please redirect me if this is not the right place to post this, so I apologize in advance.
Is there a way to extend the range of Bluetooth from either the remote or the dock station to devices far away in the house (locked in a server/media room), such as Nvidia Shield, etc...? Similar to what Home Assistant has introduced in HA last update with ESPHome BLE proxies?
Thank you

Integration API: playlist handling, browsing, searching

Define & describe playlist handling, browsing, searching functionality for the media player entity

Publish Firecamp project file for Integration API

As an integration developer I'd like to have an easy way to interact with the API without writing code. This simplifies learning the API, exploring features and speeds up development.

AC:

• Firecamp project file for the WebSocket Integration API.
• Project file must contain examples of all mandatory messages.
• Project file should contain all optional messages which are at least in state 🔍 Api definition review.

Optional: check current WebSocket support in Postman if it reached a usable state. Since we'll release a Postman collection for the Core REST API, it would be convenient having everything in one tool.

Integration API: finalize multi-device instance handling

Finalize the integration API definition for multi-device instance drivers.

Most messages are already defined, but the payload needs to be finalized and reviewed.

• Message flow concept: Multi Device Instance Driver
• AsyncAPI definition: tagged with #multi-device