API definition of the Unfolded Circle WebSocket Integration-API for Remote Two/3 (UCR Integration-API in short).
API message status legend:
| Icon | Description |
|---|---|
| 💡 | Idea, not yet official part of API definition. |
| 🚧 | Planned feature and most likely not (fully) implemented in the initial release. |
| 👷 | API definition is work in progress, not ready yet for implementation. |
| 🔍 | Api definition review & implementation. |
| 🧪 | API has been implemented in the UC Remote and is currently being tested. |
| 🚀 | Ready to use - feedback welcomed. |
Simple integrations with static entities don't need to implement all messages.
All required messages are tagged with the 🍕 emoji.
The UCR Integration-API allows writing device integration drivers for the Unfolded Circle Remotes.
ℹ️ Starting with the UCR2 firmware beta release 1.9.0, custom integration drivers can be installed on the UC Remote.
The integration driver acts as server and the UC Remote 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 connect again after wakeup.
The goal of the Integration-API is to cover simple static drivers like controlling GPIOs on a Raspberry Pi, up to
integrating existing home automation hubs like Home Assistant, Homey, ioBroker, openHAB etc.
The focus of the integration API is on entity integration, not on controlling or configuring the UC Remote. Please
refer to the Core-API for other functionality: https://github.com/unfoldedcircle/core-api
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!
Local test server.
The API token is either provided in the auth-token header while upgrading to a WebSocket connection,
or with an authentication message.
auth_required
message event after the WebSocket connection is established. The UC Remote will then authenticate with the
auth request message.authentication message
with code: 200 and req_id: 0 after the WebSocket connection has been established by the UC Remote.Local test server.
The API token is either provided in the auth-token header while upgrading to a WebSocket connection,
or with an authentication message.
auth_required
message event after the WebSocket connection is established. The UC Remote will then authenticate with the
auth request message.authentication message
with code: 200 and req_id: 0 after the WebSocket connection has been established by the UC Remote.Integration API for the UC Remote to interact with custom devices.
The publish channel lists all messages that the UC Remote sends to an integration driver server.
Accepts one of the following messages:
🚀 Authenticate a connection.
Sent by the UC Remote after an auth_required request by the integration driver.
{
"kind": "req",
"id": 0,
"msg": "auth",
"msg_data": {
"token": "string"
}
}
🚀 🍕 Get version information about the integration driver.
{
"kind": "req",
"id": 0,
"msg": "get_driver_version"
}
🚀 🍕 Retrieve the integration driver metadata.
The metadata is used to setup the driver in the remote / web-configurator and start the setup flow.
{
"kind": "req",
"id": 0,
"msg": "get_driver_metadata"
}
🧪 Event to establish connection to entities or devices.
Optional: this event instructs the integration to establish the required connections to interact with the provided entities or devices.
The integration should send device_state events to inform the UC Remote about the connection state.
For simple drivers without dynamic devices the msg_data object can be omitted. In this case, the connect event
is for the overall integration driver and not for a specific device.
{
"kind": "event",
"msg": "connect",
"cat": "DEVICE",
"ts": "2019-08-24T14:15:22Z",
"msg_data": {
"device_id": "string"
}
}
🧪 Event to stop the connection to entities or devices.
Optional: this event instructs the integration to stop the interactions with the provided entities or devices,
because the UC Remote temporarily doesn't need the entities. It's up to the integration what to do, but it
needs to be prepared to react on a connect event.
The integration should send device_state events to inform the UC Remote about the connection state.
For simple drivers without dynamic devices the msg_data object can be omitted. In this case, the disconnect
event is for the overall integration driver and not for a specific device.
{
"kind": "event",
"msg": "disconnect",
"cat": "DEVICE",
"ts": "2019-08-24T14:15:22Z",
"msg_data": {
"device_id": "string"
}
}
🚀 🍕 Get the current integration driver or device state.
Called by the UC Remote when it needs to synchronize the device state, e.g. after waking up from standby, or if
it doesn't receive regular device_state events.
The device_id property is only required if the driver supports multiple device instances.
Note: this request will not be answered with a response message but with an event.
For simple drivers without dynamic devices the msg_data object can be omitted. In this case, the request
is for the overall integration driver and not for a specific device.
{
"kind": "req",
"id": 0,
"msg": "get_device_state",
"msg_data": {
"device_id": "string"
}
}
🚀 Start driver setup.
If a driver includes a setup_data_schema object in its driver metadata, it enables the dynamic driver setup
process. The setup process can be a simple "start-confirm-done" between the UC Remote and the integration
driver, or a fully dynamic, multi-step process with user interactions, where the user has to provide additional
data or select different options.
The reconfigure flag indicates if the user wants to reconfigure an already configured driver in the Remote.
It's up to the driver on how to handle a reconfiguration request and run a different logic. For example, this
allows to show an options screen to change certain values, or present the option to modify, add or delete
provided device entities.
After confirming the setup_driver request, the integration driver has to send driver_setup_change events:
event_type: SETUP with state: SETUP is a progress event to keep the process running, see below.event_type: SETUP with state: WAIT_USER_ACTION can be sent to the UC Remote to request a user
interaction: either a confirmation to press next to continue the process, or input values.event_type: STOP with event: OK finishes the setup process and the UC Remote creates an integration instance.event_type: STOP with event: ERROR aborts the setup process.⚠️ If the setup process takes more than a few seconds, the integration should send driver_setup_change events
with state: SETUP to the UC Remote to show a setup progress to the user and prevent an inactivity timeout.
Default setup timeouts:
If no setup is needed, but the integration driver requires to show additional information to the user before
the integration is setup (e.g. terms & conditions, further help information or web links, etc.), it can define
an "information settings page" with text labels in setup_data_schema without any input fields. In this case
the integration simply has to respond with a driver_setup_change event message with
event_type: STOP and state: OK after confirming the setup_driver request message.
{
"kind": "req",
"id": 0,
"msg": "setup_driver",
"msg_data": {
"reconfigure": true,
"setup_data": {
"property1": "string",
"property2": "string"
}
}
}
🚀 Provide requested driver setup data.
Set required data to configure the integration driver or continue the setup process.
Defined user actions to set in the request body action field:
input_values: if the user was requested to enter settings, e.g. connection or credential parameters to a
device or service.confirm: response to the user action confirmation. Set to true if the user had to perform an action like
pressing a button on a device and then confirms the action with continuing the setup process.false value is not yet used but might be used in the future for yes / no choices.The state field in the response message indicate the current state of the setup process.
{
"kind": "req",
"id": 0,
"msg": "set_driver_user_data",
"msg_data": {
"input_values": {
"property1": "string",
"property2": "string"
}
}
}
🚀 Abort a driver setup.
If the user aborts the setup process, the UC Remote sends this event. Further messages from the integration from the setup process will be ignored afterwards.
{
"kind": "event",
"msg": "abort_driver_setup",
"cat": "DEVICE",
"ts": "2019-08-24T14:15:22Z",
"msg_data": {
"error": "NONE"
}
}
🚀 🍕 Retrieve the available entities from the integration driver.
Called while configuring profiles and assigning entities to pages or groups in the web-configurator or the embedded editor of the remote UI.
With the optional filter, only entities of a given type can be requested.
{
"kind": "req",
"id": 0,
"msg": "get_available_entities",
"msg_data": {
"filter": {
"device_id": "string",
"entity_type": "button"
}
}
}
🚀 🍕 Subscribe to events.
Subscribe to entity state change events to receive entity_change events from the integration driver.
If no entity IDs are specified then events for all available entities are sent to the UC Remote.
{
"kind": "req",
"id": 0,
"msg": "subscribe_events",
"msg_data": {
"device_id": "string",
"entity_ids": [
"string"
]
}
}
🧪 Unsubscribe from events.
If no entity IDs are specified then all events for all available entities are stopped.
This message is sent by the UC Remote if a previously configured entity is no longer used and therefore no longer interested in entity updates. If the integration driver keeps sending events for the unsubscribed entities then they are simply discarded.
{
"kind": "req",
"id": 0,
"msg": "unsubscribe_events",
"msg_data": {
"device_id": "string",
"entity_ids": [
"string"
]
}
}
🚀 🍕 Get the current state of the configured entities.
Called by the UC Remote when it needs to synchronize the dynamic entity attributes, e.g. after connection setup or waking up from standby.
The integration should only send the state of the configured entities to reduce communication overhead,
especially if there are many available entities, from which only a few are getting configured on the remote.
Any additional data will be ignored.
Furthermore, the integration driver is free to decide which entity states it wants to send back. It's even advisable to use dirty flags in the integration driver if there are a lot of entities, and only return the changed data.
⚠️ Future change announcement: this request will be enhanced with a force flag (or the like) to signal that
all entity states are required, and no data should be suppressed. This will happen for example after the
remote is restarted.
For simple drivers without dynamic devices the msg_data.device_id property can be omitted.
In this case, the request is for the overall integration driver and not for a specific device.
{
"kind": "req",
"id": 0,
"msg": "get_entity_states",
"msg_data": {
"device_id": "string"
}
}
🚀 🍕 Execute an entity command.
Instruct the integration driver to execute a command like "turn on" or "change temperature".
Optional command data like temperature value or channel number can be provided in the params array.
The parameter objects are described in the entity feature definitions.
The result response is to acknowledge the command and to return any immediate failures in case the driver
already knows it's unable to perform the command due to invalid data, device communication issues etc.
After successfully executing a command, the UC Remote expects an entity_change event with the updated feature
value(s).
{
"kind": "req",
"id": 123,
"msg": "entity_command",
"msg_data": {
"entity_type": "button",
"entity_id": "button-1",
"cmd_id": "press"
}
}
{
"kind": "req",
"id": 124,
"msg": "entity_command",
"msg_data": {
"entity_type": "switch",
"entity_id": "switch-1",
"cmd_id": "on"
}
}
{
"kind": "req",
"id": 124,
"msg": "entity_command",
"msg_data": {
"entity_type": "switch",
"entity_id": "switch-1",
"cmd_id": "off"
}
}
{
"kind": "req",
"id": 125,
"msg": "entity_command",
"msg_data": {
"entity_type": "light",
"entity_id": "light-1",
"cmd_id": "on"
}
}
{
"kind": "req",
"id": 125,
"msg": "entity_command",
"msg_data": {
"entity_type": "light",
"entity_id": "light-1",
"cmd_id": "on",
"params": {
"brightness": 50,
"temperature": 70
}
}
}
{
"kind": "req",
"id": 126,
"msg": "entity_command",
"msg_data": {
"entity_type": "cover",
"entity_id": "blind-1",
"cmd_id": "up"
}
}
{
"kind": "req",
"id": 126,
"msg": "entity_command",
"msg_data": {
"entity_type": "cover",
"entity_id": "blind-1",
"cmd_id": "position",
"params": {
"position": 50
}
}
}
{
"kind": "req",
"id": 127,
"msg": "entity_command",
"msg_data": {
"entity_type": "cover",
"entity_id": "blind-2_cover-only",
"cmd_id": "open"
}
}
{
"kind": "req",
"id": 127,
"msg": "entity_command",
"msg_data": {
"entity_type": "cover",
"entity_id": "blind-2_cover-only",
"cmd_id": "close"
}
}
🚀 UC Remote goes into standby event.
Notification event that the UC Remote goes into standby mode and won't process incoming events anymore.
TODO add standby type in msg_data? E.g. "screen off" & "sleep" for the integration to be notified that the UC Remote is no longer reachable? While the screen is off, the remote API is still running, but might soon go into sleep state.
{
"kind": "event",
"msg": "enter_standby",
"cat": "REMOTE",
"ts": "2019-08-24T14:15:22Z",
"msg_data": {}
}
🚀 UC Remote leaves standby event.
Notification event that the UC Remote is out of standby. The integration should resume operation if it
suspended it while receiving the enter_standby event.
This allows the integration to submit any entity state changes. Otherwise the UC Remote will likely request an
entity state update.
{
"kind": "event",
"msg": "exit_standby",
"cat": "REMOTE",
"ts": "2019-08-24T14:15:22Z",
"msg_data": {}
}
🧪 Remote version information response.
{
"kind": "resp",
"req_id": 0,
"msg": "version",
"code": 200,
"msg_data": {
"model": "string",
"device_name": "string",
"hostname": "string",
"address": "string",
"api": "string",
"core": "string",
"ui": "string",
"os": "string"
}
}
🚀 Supported entity types response.
{
"kind": "resp",
"req_id": 0,
"msg": "supported_entity_types",
"code": 200,
"msg_data": [
"string"
]
}
🚀 Configured entities response.
The returned entity identifiers are configured in the Remote.
{
"kind": "resp",
"req_id": 0,
"msg": "configured_entities",
"code": 200,
"msg_data": [
"string"
]
}
🧪 Active localization settings of the UC Remote.
{
"kind": "resp",
"req_id": 0,
"msg": "localization_cfg",
"code": 200,
"msg_data": {
"language_code": "string",
"country_code": "string",
"time_zone": "string",
"time_format_24h": true,
"measurement_unit": "METRIC"
}
}
🔍 Driver runtime information from the UC Remote.
{
"kind": "resp",
"req_id": 0,
"msg": "runtime_info",
"code": 200,
"msg_data": {
"driver_id": "string",
"intg_ids": [
"string"
],
"log_id": "string"
}
}
Integration API for the UC Remote to receive messages from integration drivers.
The subscribe channel lists all messages that the integration driver server sends to the UC Remote.
Accepts one of the following messages:
🚀 Authentication request event after connection is established.
This event is only sent if the integration doesn't support header based authentication during connection setup.
The UC Remote will then authenticate with the auth request message.
{
"kind": "event",
"msg": "auth_required",
"cat": "string",
"ts": "2019-08-24T14:15:22Z",
"msg_data": {
"name": "string",
"version": {
"api": "string",
"driver": "string"
}
}
}
🚀 🍕 Authentication response.
The authentication result is provided in the code attribute:
200: success, API can be used and message requests are accepted.401: authentication failed, the provided token is not valid.If the driver doesn't support or require authentication, it still needs to send the authentication message
with code: 200 and req_id: 0 after the WebSocket connection has been established by the UC Remote.
It's recommended to send the optional driver version object in the the msg_data payload to avoid eventual additional message exchanges.
{
"kind": "resp",
"req_id": 0,
"msg": "authentication",
"code": 200,
"msg_data": {
"name": "string",
"version": {
"api": "string",
"driver": "string"
}
}
}
🚀 🍕 Command result message.
A result message is a response message containing a result code and optional error information without further payload.
Common response message properties.
{
"kind": "resp",
"req_id": 123,
"msg": "result",
"code": 200
}
{
"kind": "resp",
"req_id": 124,
"msg": "result",
"code": 400,
"msg_data": {
"code": "INV_ARGUMENT",
"message": "Invalid argument. Foo must be a positive number."
}
}
🚀 🍕 Integration driver version information response.
{
"kind": "resp",
"req_id": 0,
"msg": "driver_version",
"code": 200,
"msg_data": {
"name": "string",
"version": {
"api": "string",
"driver": "string"
}
}
}
🧪 🍕 Integration driver metadata response.
{
"kind": "resp",
"req_id": 0,
"msg": "driver_metadata",
"code": 200,
"msg_data": {
"driver_id": "string",
"name": {},
"driver_url": "http://example.com",
"auth_method": "HEADER",
"version": "string",
"min_core_api": "string",
"icon": "string",
"description": {},
"developer": {
"name": "string",
"url": "http://example.com",
"email": "user@example.com"
},
"home_page": "http://example.com",
"device_discovery": true,
"setup_data_schema": {
"title": {},
"settings": [
{
"id": "string",
"label": {},
"field": {
"number": {
"value": 0,
"min": 0,
"max": 0,
"steps": 0,
"decimals": 0,
"unit": {}
}
}
}
]
},
"release_date": "2019-08-24"
}
}
🚀 🍕 Current integration driver or device state event.
If there's a device communication issue or other error, this state will inform the user with a UI notification about the issue.
This event should be triggered by the integration driver whenever the state changes. Furthermore, the UC Remote
can request the current state with the get_device_state request.
{
"kind": "event",
"msg": "device_state",
"cat": "DEVICE",
"ts": "2019-08-24T14:15:22Z",
"msg_data": {
"device_id": "string",
"state": "CONNECTED"
}
}
🚀 Driver setup state change event.
Emitted for all driver setup flow state changes.
Different change events:
SETUP: send progress, setup is still running WAIT_USER_ACTION: integration driver requires user inputOK: integration setup successfully completedERROR: integration setup failed{
"kind": "event",
"msg": "driver_setup_change",
"cat": "DEVICE",
"ts": "2019-08-24T14:15:22Z",
"msg_data": {
"event_type": "START",
"state": "SETUP",
"error": "NONE",
"require_user_action": {
"input": {
"title": {},
"settings": [
{
"id": "string",
"label": {},
"field": {
"number": {
"value": 0,
"min": 0,
"max": 0,
"steps": 0,
"decimals": 0,
"unit": {}
}
}
}
]
}
}
}
}
🚀 🍕 Current state of the entities.
Response message of the get_entity_states request. Contains the dynamic attributes of all entities.
The msg_data payload is an array of the entity_change event.
{
"kind": "resp",
"req_id": 0,
"msg": "entity_states",
"code": 200,
"msg_data": [
{
"device_id": "string",
"entity_type": "string",
"entity_id": "string",
"attributes": {}
}
]
}
🚀 🍕 Available entities response.
This message contains the available entities from the integration driver the UC Remote can configure.
If the get_available_entities request included a filter, it is returned in the message data with only the
matching entities.
{
"kind": "resp",
"req_id": 0,
"msg": "available_entities",
"code": 200,
"msg_data": {
"filter": {
"device_id": "string",
"entity_type": "button"
},
"available_entities": [
{
"entity_id": "string",
"entity_type": "string",
"device_id": "string",
"features": [
"string"
],
"name": {},
"area": "string"
}
]
}
}
🚀 🍕 Entity state change event.
Emitted when an attribute of an entity changes, e.g. is switched off. Either after an entity_command or if the
entity is updated manually through a user or an external system. This keeps the UC Remote in sync with the real
state of the entity without the need of constant polling.
An entity attribute has changed.
{
"kind": "event",
"msg": "entity_change",
"cat": "ENTITY",
"ts": "2019-08-24T14:15:22Z",
"msg_data": {
"device_id": "string",
"entity_type": "string",
"entity_id": "string",
"attributes": {}
}
}
🔍 New entity available event.
Optional event to notify the UC Remote that new entities are available.
{
"kind": "event",
"msg": "entity_available",
"cat": "ENTITY",
"ts": "2019-08-24T14:15:22Z",
"msg_data": {
"entity_id": "string",
"entity_type": "string",
"device_id": "string",
"features": [
"string"
],
"name": {},
"area": "string"
}
}
🔍 Entity removed event.
Optional event to notify the UC Remote that entities were removed and no longer available.
{
"kind": "event",
"msg": "entity_removed",
"cat": "ENTITY",
"ts": "2019-08-24T14:15:22Z",
"msg_data": {
"device_id": "string",
"entity_type": "string",
"entity_id": "string"
}
}
🧪 Get UC Remote version information.
ℹ️️ implemented in firmware 0.9.2.
{
"kind": "req",
"id": 0,
"msg": "get_version"
}
🧪 Get supported entities in the UC Remote.
ℹ️️ implemented in firmware 0.9.2.
This is a metadata request for supported entities in the UC Remote and allows the client to check if it's still compatible. New releases can support new entities or entities might get renamed in major updates.
{
"kind": "req",
"id": 0,
"msg": "get_supported_entity_types"
}
🧪 Retrieve configured entities from this integration.
ℹ️️ implemented in firmware 0.9.2.
Request the configured entities in the UC Remote originating from this integration. These are all the entities
which have been configured in the UC Remote.
⚠️ This doesn't mean that all entities are actively being used (assigned in a profile and shown in the user
interface).
This allows the driver e.g. to optimize its device communication and only consider actively used entities.
Another option for the driver to be notified about used entities is through the subscribe_events requests.
{
"kind": "req",
"id": 0,
"msg": "get_configured_entities"
}
🧪 Retrieve the localization settings of the UC Remote.
ℹ️️ implemented in firmware 0.9.2.
The active localization settings of the UC Remote can be used if the integration driver requires localized settings for texts or units of measurements.
For language texts the driver should always provide an english option in addition to any localized texts.
{
"kind": "req",
"id": 0,
"msg": "get_localization_cfg"
}
🔍 Retrieve driver runtime information from the Remote.
ℹ️️ implemented in firmware 0.9.2.
Request driver runtime information from the Remote. This returns driver and instance identifiers for advanced usage of the REST Core-API. These identifiers could also be propagated to a home automation system to interact with the Remote and REST Core-API.
{
"kind": "req",
"id": 0,
"msg": "get_runtime_info"
}
🚀 Generic request message.
This message defines the common structure of a request message. The receiver must reply with a response message.
Common request message properties.
🚀 Generic response message.
This message defines the common structure of a response message which is sent back after receiving a request message.
Common response message properties.
🚀 Generic event message.
Common event message properties.
🚀 🍕 Command result message.
A result message is a response message containing a result code and optional error information without further payload.
Common response message properties.
🚀 Authentication request event after connection is established.
This event is only sent if the integration doesn't support header based authentication during connection setup.
The UC Remote will then authenticate with the auth request message.
🚀 Authenticate a connection.
Sent by the UC Remote after an auth_required request by the integration driver.
🚀 🍕 Authentication response.
The authentication result is provided in the code attribute:
200: success, API can be used and message requests are accepted.401: authentication failed, the provided token is not valid.If the driver doesn't support or require authentication, it still needs to send the authentication message
with code: 200 and req_id: 0 after the WebSocket connection has been established by the UC Remote.
It's recommended to send the optional driver version object in the the msg_data payload to avoid eventual additional message exchanges.
🚀 🍕 Get version information about the integration driver.
🚀 🍕 Integration driver version information response.
🚀 🍕 Retrieve the integration driver metadata.
The metadata is used to setup the driver in the remote / web-configurator and start the setup flow.
🧪 🍕 Integration driver metadata response.
🚀 UC Remote goes into standby event.
Notification event that the UC Remote goes into standby mode and won't process incoming events anymore.
TODO add standby type in msg_data? E.g. "screen off" & "sleep" for the integration to be notified that the UC Remote is no longer reachable? While the screen is off, the remote API is still running, but might soon go into sleep state.
🚀 UC Remote leaves standby event.
Notification event that the UC Remote is out of standby. The integration should resume operation if it
suspended it while receiving the enter_standby event.
This allows the integration to submit any entity state changes. Otherwise the UC Remote will likely request an
entity state update.
🧪 Event to establish connection to entities or devices.
Optional: this event instructs the integration to establish the required connections to interact with the provided entities or devices.
The integration should send device_state events to inform the UC Remote about the connection state.
For simple drivers without dynamic devices the msg_data object can be omitted. In this case, the connect event
is for the overall integration driver and not for a specific device.
🧪 Event to stop the connection to entities or devices.
Optional: this event instructs the integration to stop the interactions with the provided entities or devices,
because the UC Remote temporarily doesn't need the entities. It's up to the integration what to do, but it
needs to be prepared to react on a connect event.
The integration should send device_state events to inform the UC Remote about the connection state.
For simple drivers without dynamic devices the msg_data object can be omitted. In this case, the disconnect
event is for the overall integration driver and not for a specific device.
🚀 🍕 Get the current integration driver or device state.
Called by the UC Remote when it needs to synchronize the device state, e.g. after waking up from standby, or if
it doesn't receive regular device_state events.
The device_id property is only required if the driver supports multiple device instances.
Note: this request will not be answered with a response message but with an event.
For simple drivers without dynamic devices the msg_data object can be omitted. In this case, the request
is for the overall integration driver and not for a specific device.
🚀 🍕 Current integration driver or device state event.
If there's a device communication issue or other error, this state will inform the user with a UI notification about the issue.
This event should be triggered by the integration driver whenever the state changes. Furthermore, the UC Remote
can request the current state with the get_device_state request.
🚀 Start driver setup.
If a driver includes a setup_data_schema object in its driver metadata, it enables the dynamic driver setup
process. The setup process can be a simple "start-confirm-done" between the UC Remote and the integration
driver, or a fully dynamic, multi-step process with user interactions, where the user has to provide additional
data or select different options.
The reconfigure flag indicates if the user wants to reconfigure an already configured driver in the Remote.
It's up to the driver on how to handle a reconfiguration request and run a different logic. For example, this
allows to show an options screen to change certain values, or present the option to modify, add or delete
provided device entities.
After confirming the setup_driver request, the integration driver has to send driver_setup_change events:
event_type: SETUP with state: SETUP is a progress event to keep the process running, see below.event_type: SETUP with state: WAIT_USER_ACTION can be sent to the UC Remote to request a user
interaction: either a confirmation to press next to continue the process, or input values.event_type: STOP with event: OK finishes the setup process and the UC Remote creates an integration instance.event_type: STOP with event: ERROR aborts the setup process.⚠️ If the setup process takes more than a few seconds, the integration should send driver_setup_change events
with state: SETUP to the UC Remote to show a setup progress to the user and prevent an inactivity timeout.
Default setup timeouts:
If no setup is needed, but the integration driver requires to show additional information to the user before
the integration is setup (e.g. terms & conditions, further help information or web links, etc.), it can define
an "information settings page" with text labels in setup_data_schema without any input fields. In this case
the integration simply has to respond with a driver_setup_change event message with
event_type: STOP and state: OK after confirming the setup_driver request message.
🚀 Abort a driver setup.
If the user aborts the setup process, the UC Remote sends this event. Further messages from the integration from the setup process will be ignored afterwards.
🚀 Driver setup state change event.
Emitted for all driver setup flow state changes.
Different change events:
SETUP: send progress, setup is still running WAIT_USER_ACTION: integration driver requires user inputOK: integration setup successfully completedERROR: integration setup failed🚀 Provide requested driver setup data.
Set required data to configure the integration driver or continue the setup process.
Defined user actions to set in the request body action field:
input_values: if the user was requested to enter settings, e.g. connection or credential parameters to a
device or service.confirm: response to the user action confirmation. Set to true if the user had to perform an action like
pressing a button on a device and then confirms the action with continuing the setup process.false value is not yet used but might be used in the future for yes / no choices.The state field in the response message indicate the current state of the setup process.
🚀 🍕 Retrieve the available entities from the integration driver.
Called while configuring profiles and assigning entities to pages or groups in the web-configurator or the embedded editor of the remote UI.
With the optional filter, only entities of a given type can be requested.
🚀 🍕 Available entities response.
This message contains the available entities from the integration driver the UC Remote can configure.
If the get_available_entities request included a filter, it is returned in the message data with only the
matching entities.
🚀 🍕 Subscribe to events.
Subscribe to entity state change events to receive entity_change events from the integration driver.
If no entity IDs are specified then events for all available entities are sent to the UC Remote.
🧪 Unsubscribe from events.
If no entity IDs are specified then all events for all available entities are stopped.
This message is sent by the UC Remote if a previously configured entity is no longer used and therefore no longer interested in entity updates. If the integration driver keeps sending events for the unsubscribed entities then they are simply discarded.
🧪 Get UC Remote version information.
ℹ️️ implemented in firmware 0.9.2.
🧪 Remote version information response.
🧪 Get supported entities in the UC Remote.
ℹ️️ implemented in firmware 0.9.2.
This is a metadata request for supported entities in the UC Remote and allows the client to check if it's still compatible. New releases can support new entities or entities might get renamed in major updates.
🚀 Supported entity types response.
🧪 Retrieve configured entities from this integration.
ℹ️️ implemented in firmware 0.9.2.
Request the configured entities in the UC Remote originating from this integration. These are all the entities
which have been configured in the UC Remote.
⚠️ This doesn't mean that all entities are actively being used (assigned in a profile and shown in the user
interface).
This allows the driver e.g. to optimize its device communication and only consider actively used entities.
Another option for the driver to be notified about used entities is through the subscribe_events requests.
🚀 Configured entities response.
The returned entity identifiers are configured in the Remote.
🧪 Retrieve the localization settings of the UC Remote.
ℹ️️ implemented in firmware 0.9.2.
The active localization settings of the UC Remote can be used if the integration driver requires localized settings for texts or units of measurements.
For language texts the driver should always provide an english option in addition to any localized texts.
🧪 Active localization settings of the UC Remote.
🔍 Retrieve driver runtime information from the Remote.
ℹ️️ implemented in firmware 0.9.2.
Request driver runtime information from the Remote. This returns driver and instance identifiers for advanced usage of the REST Core-API. These identifiers could also be propagated to a home automation system to interact with the Remote and REST Core-API.
🔍 Driver runtime information from the UC Remote.
🚀 🍕 Get the current state of the configured entities.
Called by the UC Remote when it needs to synchronize the dynamic entity attributes, e.g. after connection setup or waking up from standby.
The integration should only send the state of the configured entities to reduce communication overhead,
especially if there are many available entities, from which only a few are getting configured on the remote.
Any additional data will be ignored.
Furthermore, the integration driver is free to decide which entity states it wants to send back. It's even advisable to use dirty flags in the integration driver if there are a lot of entities, and only return the changed data.
⚠️ Future change announcement: this request will be enhanced with a force flag (or the like) to signal that
all entity states are required, and no data should be suppressed. This will happen for example after the
remote is restarted.
For simple drivers without dynamic devices the msg_data.device_id property can be omitted.
In this case, the request is for the overall integration driver and not for a specific device.
🚀 🍕 Current state of the entities.
Response message of the get_entity_states request. Contains the dynamic attributes of all entities.
The msg_data payload is an array of the entity_change event.
🚀 🍕 Execute an entity command.
Instruct the integration driver to execute a command like "turn on" or "change temperature".
Optional command data like temperature value or channel number can be provided in the params array.
The parameter objects are described in the entity feature definitions.
The result response is to acknowledge the command and to return any immediate failures in case the driver
already knows it's unable to perform the command due to invalid data, device communication issues etc.
After successfully executing a command, the UC Remote expects an entity_change event with the updated feature
value(s).
🚀 🍕 Entity state change event.
Emitted when an attribute of an entity changes, e.g. is switched off. Either after an entity_command or if the
entity is updated manually through a user or an external system. This keeps the UC Remote in sync with the real
state of the entity without the need of constant polling.
An entity attribute has changed.
🔍 New entity available event.
Optional event to notify the UC Remote that new entities are available.
🔍 Entity removed event.
Optional event to notify the UC Remote that entities were removed and no longer available.
Common request message properties.
Common response message properties.
Common event message properties.
For simple drivers without dynamic devices the msg_data object can be omitted. In this case, the request
is for the overall integration driver and not for a specific device.
For simple drivers without dynamic devices the msg_data.device_id property can be omitted.
In this case, the request is for the overall integration driver and not for a specific device.
The msg_data payload is an array of the entity_change event.
For simple drivers without dynamic devices the msg_data object can be omitted. In this case, the connect event
is for the overall integration driver and not for a specific device.
For simple drivers without dynamic devices the msg_data object can be omitted. In this case, the disconnect
event is for the overall integration driver and not for a specific device.
TODO add standby type in msg_data? E.g. "screen off" & "sleep" for the integration to be notified that the UC Remote is no longer reachable? While the screen is off, the remote API is still running, but might soon go into sleep state.
An entity attribute has changed.
See entity documentation for attributes payload.
Request message ID which is reflected in response message.
Integration driver metadata.
Optional information about the integration developer.
Integration driver authentication method if a token is required.
The JSON auth message is used if a token is configured but no authentication method is set.
Optional filters
Common definition of an entity. Concrete entities are: cover, button, climate, ir_emitter, light,
media_player, remote,sensor, switch.
See entity documentation for more information.
The entity_type value acts as discriminator for the entity type, which defines the supported features and
options of an entity.
E.g. a simple button entity supports on / off, whereas a cover entity can be a simple window cover with only
the ability to open / close, or a venetian blind with position and tilting features.
See polymorphism support in AsyncAPI specification
for more information.
A button entity can fire an event or start an action which cannot be further controlled once started.
This can be used for "fire and forget" commands, e.g. running a system command, sending an IR code, restart a device, reset something etc.
A button is stateless. To represent something that can be turned on and off, then the switch entity should be
used.
See button entity documentation for more information.
A switch entity can turn something on or off and the current state should be readable by the integration driver.
If the state can't be read, the readable option property can be set to false. This should be avoided
whenever possible, because the UC Remote either has to assume the current state, or the UI needs to ask the
user for the current state.
If the switch controls a light source, then the 'light' entity is usually a better choice.
See switch entity documentation for more information.
A climate entity controls heating, ventilation and air conditioning (HVAC) devices. This can range from simple fans to personal air conditioning units to integrated building devices.
See climate entity documentation for more information.
Entity for covering or opening things like blinds, window covers, curtains, etc. The entity features specify
the abilities of the cover and the controllable properties, whereas the device_class specifies the UI
representation.
See cover entity documentation for more information.
An IR-emitter entity allows to send IR commands in PRONTO hex format.
This entity allows to integrate external IR blasters and emitters. Once added to a Remote, a new IR-emitter output is registered which can be used for IR-remote entities. Similar as adding a new dock.
See IR-emitter entity documentation for more information.
A light entity can be switched on and off and depending on its features, the light source can be further controlled like setting brightness, hue, color saturation and color temperature.
The HSV color model is used for adjusting color and brightness.
See light entity documentation for more information.
A media player entity controls playback of media on a device. This could be an online music streaming service, a TV, a stereo or a video player.
See media player entity documentation for more information.
A remote entity can send commands to a controllable device.
See remote entity documentation for more information.
A sensor entity provides measured values from devices or dedicated hardware sensors.
The device class specifies the type of sensor and links it with a default unit of measurement to display in the user
interface.
custom device class allows arbitrary UI labels and units.temperature device class performs automatic conversion between °C and °F.See sensor entity documentation for more information.
Supported entities, defined as extensible enum: already known entity types are in the enum, but other string values are allowed for forward compatability.
SETUP: setup in progressWAIT_USER_ACTION: setup flow is waiting for user input. See require_user_action for requested input.OK: setup finished successfullyERROR: setup errorMore detailed error reason for state: ERROR condition.
Confirmation screen
Settings definition page, e.g. to configure an integration driver.
An input setting is of a specific type defined in field.type which defines how it is presented to the user.
Inspired by the Homey SDK settings concept.
Number input with optional min, max, steps and decimals properties. The default value must be specified
in value. An optional unit of the number setting can be specified in units, which will be displayed next to
the input field.
Single line of text input.
TODO: format specifier for e.g. email, url, date, datetime etc.?
Multi-line text input, e.g. for providing a description.
Password or pin entry field with the input text hidden from the user. Otherwise the same as text input.
Checkbox setting with true / false values.
Dropdown setting to pick a single value from a list. All values must be strings.
Additional read-only text for information purpose between other settings. Supports Markdown formatting.
User input result of a SettingsPage as key values.
Language culture code: starting with the two-letter ISO-639-1
code, followed by an optional ISO-3166 country code,
separated by an underscore.
Examples: en, en_UK, en_US, de, de_DE, de_CH etc.
Optional icon identifier. If specified the icon will be set. An empty identifier while updating the object removes the existing icon.
A user interface item is either an icon, text or media information from a media-player entity.
command field.Grid layout size.
Item size in the button grid. Default size if not specified: 1 x 1
Button placement in the grid with 0-based coordinates.
Supported IR formats by the emitter