This repository contains API specifications of Unfolded Circle Remote products.
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.
The Remote WebSockets integration-API allows writing device integrations for the Unfolded Circle Remote devices.
At the moment only user integrations running on an external host are supported.
ℹ️ Beta release 1.9.0 allows to install custom integration drivers on the Remote. This is a developer preview feature to test their integrations.
The integration driver acts as server and the Remote device 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 device. 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.
Since we are providing an API and not an SDK for a specific programming language, one can develop external integrations in any language which is capable running a WebSockets server and handling JSON data.
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 device, 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 devices.
- API models in Rust
- Node.js API wrapper for the UC Integration-API
Integrations using the Node.js API wrapper: - Python API wrapper library for the UC Integration-API
Integrations using the Python API wrapper: - Home Assistant integration written in Rust
We plan to release more examples in the future.
The UC Remote WebSockets & REST Core-APIs allow you to interact with the Unfolded Circle remote-core service and take full control of its features.
See core-api directory for more information.
- remote-core simulator to start developing integrations without a UC Remote device
- Open Source remote-ui application
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!
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.
Please read our contribution guidelines before opening a pull request.
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.