diff --git a/.github/workflows/openapi.yml b/.github/workflows/openapi.yml index 06c16fc..a5e1873 100644 --- a/.github/workflows/openapi.yml +++ b/.github/workflows/openapi.yml @@ -23,11 +23,10 @@ jobs: steps: - name: Checkout repository uses: actions/checkout@v6 - - name: Validate - uses: mbowman100/swagger-validator-action@master - with: - files: | - ./core-api/rest/UCR-core-openapi.yaml + - name: Validate with redocli CLI + run: | + docker pull redocly/cli + docker run --rm -v $PWD/core-api/rest:/spec -e REDOCLY_TELEMETRY=false redocly/cli lint UCR-core-openapi.yaml publish: name: Publish GitHub pages diff --git a/core-api/rest/CHANGELOG.md b/core-api/rest/CHANGELOG.md index 134b130..14aed5d 100644 --- a/core-api/rest/CHANGELOG.md +++ b/core-api/rest/CHANGELOG.md @@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 This section contains unreleased changes which will be part of an upcoming release. +### Fixed +- Schema validation errors found with the new redocly-cli linter. + +### Changed +- Migrate OAS specification from 3.0.3 to 3.1.1. + --- ## 0.45.3 diff --git a/core-api/rest/UCR-core-openapi.yaml b/core-api/rest/UCR-core-openapi.yaml index d784a4c..363ad3f 100644 --- a/core-api/rest/UCR-core-openapi.yaml +++ b/core-api/rest/UCR-core-openapi.yaml @@ -1,58 +1,119 @@ -openapi: 3.0.3 +openapi: 3.1.1 info: title: Remote Two/3 REST Core-API + summary: REST Core-API for Remote Two/3 version: 0.45.3 contact: name: API Support - url: 'https://github.com/unfoldedcircle/core-api/issues' + url: https://github.com/unfoldedcircle/core-api/issues email: support@unfoldedcircle.com license: name: Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) - url: 'https://creativecommons.org/licenses/by-sa/4.0/' - description: "The Unfolded Circle REST Core-API for Remote Two/3 (_UCR REST Core-API_ in short) allows to configure the remote and\nmanage custom resource files. Furthermore, API-keys for the WebSocket & REST APIs can be created.\n\n## Overview\n\nThe Unfolded Circle Remote Core-APIs consist of:\n- this REST API\n- the [UCR WebSocket Core-API](https://github.com/unfoldedcircle/core-api/tree/main/core-api/websocket),\n providing asynchronous events.\n\nThe focus of the Core-APIs is to provide all functionality for the UI application and the web-configurator. \nThey allow to interact with the Unfolded Circle remote-core service and take full control of its features.\n\nThe Core-APIs may also be used by other external systems and integration drivers, if specific configuration or\ninteraction features are required, which are not present in the [UCR Integration-API](https://github.com/unfoldedcircle/core-api/tree/main/integration-api).\n\n## Authentication\n\nAll API endpoints besides `/api/pub` are secured. Available authentication methods are:\n- `Basic Auth` for every request. \n This should only be used for simple testing. At the moment there's only a single user account available for the\n web-configurator.\n - User: `web-configurator`\n - Password: generated pin shown in the remote-UI.\n- `Bearer Token` for every request. \n This is the preferred authentication method for external systems communicating with the UCR REST Core-API.\n - See `/auth/api_keys` endpoints on how to create and manage API keys.\n - Only the `admin` role is supported at the moment. More roles will be added in the future.\n - Example for a curl request: \n `curl 'http://$IP/api/system' --header 'Authorization: Bearer $API_KEY'`\n- `Cookie` based session login with the `/api/pub/login` endpoint. \n This is the preferred method for web frontends like the web-configurator.\n\n## \U0001F6A7 Missing Features\n\nThe following features will be continuously added (in no particular order):\n\n- Upload of custom certificate\n- Static network configuration\n\nPlease check the [core-api GitHub issues](https://github.com/unfoldedcircle/core-api/issues) for the current state. \n\n## API Versioning\n\nThe API is versioned according to [SemVer](https://semver.org/). \nThe initial public release will be `1.0.0` once it is considered stable enough with some initial integration\nimplementations and developer examples.\n\n**Any major version zero (`0.y.z`) is for initial development and may change at any time!** \nI.e. backward compatibility for minor releases is not yet established, anything MAY change at any time!\nWe try avoiding it, but it might still happen...\n" -externalDocs: - description: Find out more about the Remotes - url: 'https://www.unfoldedcircle.com/' + url: https://creativecommons.org/licenses/by-sa/4.0/ + description: | + The Unfolded Circle REST Core-API for Remote Two/3 (_UCR REST Core-API_ in short) allows to configure the remote and + manage custom resource files. Furthermore, API-keys for the WebSocket & REST APIs can be created. + + ## Overview + + The Unfolded Circle Remote Core-APIs consist of: + - this REST API + - the [UCR WebSocket Core-API](https://github.com/unfoldedcircle/core-api/tree/main/core-api/websocket), + providing asynchronous events. + + The focus of the Core-APIs is to provide all functionality for the UI application and the web-configurator. + They allow to interact with the Unfolded Circle remote-core service and take full control of its features. + + The Core-APIs may also be used by other external systems and integration drivers, if specific configuration or + interaction features are required, which are not present in the [UCR Integration-API](https://github.com/unfoldedcircle/core-api/tree/main/integration-api). + + ## Authentication + + All API endpoints besides `/api/pub` are secured. Available authentication methods are: + - `Basic Auth` for every request. + This should only be used for simple testing. At the moment there's only a single user account available for the + web-configurator. + - User: `web-configurator` + - Password: generated pin shown in the remote-UI. + - `Bearer Token` for every request. + This is the preferred authentication method for external systems communicating with the UCR REST Core-API. + - See `/auth/api_keys` endpoints on how to create and manage API keys. + - Only the `admin` role is supported at the moment. More roles will be added in the future. + - Example for a curl request: + `curl 'http://$IP/api/system' --header 'Authorization: Bearer $API_KEY'` + - `Cookie` based session login with the `/api/pub/login` endpoint. + This is the preferred method for web frontends like the web-configurator. + + ## 🚧 Missing Features + + The following features will be continuously added (in no particular order): + + - Upload of custom certificate + - Static network configuration + + Please check the [core-api GitHub issues](https://github.com/unfoldedcircle/core-api/issues) for the current state. + + ## API Versioning + + The API is versioned according to [SemVer](https://semver.org/). + 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! + We try avoiding it, but it might still happen... servers: - url: /api - - url: 'http://localhost:8080/api' - - url: 'https://localhost:8443/api' - - url: 'http://unfolded-simulator.local:8080/api' - - url: 'https://unfolded-simulator.local:8443/api' + - url: http://localhost:8080/api + - url: https://localhost:8443/api + - url: http://unfolded-simulator.local:8080/api + - url: https://unfolded-simulator.local:8443/api security: - basicAuth: [] - cookieAuth: [] tags: - name: info - description: "\U0001F481 Public status information and health checks" + description: 💁 Public status information and health checks - name: auth - description: "\U0001F510 Session authentication" + description: 🔐 Session authentication - name: api-keys - description: "\U0001F511 API keys for authentication." + description: 🔑 API keys for authentication. - name: external-token - description: "\U0001F48E Access token handling for external systems." + description: 💎 Credential management for external systems, including generic tokens and OAuth2 credentials. - name: resources - description: "\U0001F508 Media files handling, e.g. manage background images, icons or sound effects." + description: 🔈 Media files handling, e.g. manage background images, icons or sound effects. - name: integrations - description: "\U0001F9E9 Integration handling" + description: 🧩 Integration handling - name: entities - description: "\U0001F4FA Common handling of configured entities like sending commands and modifying editable properties. \nEntities are usually provided by integrations, except the special activity, macro and infrared-remote entities.\n" + description: | + 📺 Common handling of configured entities like sending commands and modifying editable properties. + Entities are usually provided by integrations, except the special activity, macro and infrared-remote entities. - name: activities - description: "\U0001F39B️ Combine multiple entities into an activity with optional on- & off-sequences, physical button mappings and a\ncustom user interface.\n" + description: | + 🎛️ Combine multiple entities into an activity with optional on- & off-sequences, physical button mappings and a + custom user interface. - name: macros - description: "\U0001F522 Macros execute a sequence of commands which is exposed as an entity command. Macros don't have a custom user\ninterface.\n" + description: | + 🔢 Macros execute a sequence of commands which is exposed as an entity command. Macros don't have a custom user + interface. - name: infrared - description: "\U0001F308 Infrared code set lookup, custom IR code management and IR emitter devices.\n" + description: | + 🌈 Infrared code set lookup, custom IR code management and IR emitter devices. - name: remotes - description: "\U0001F3AE Create BT- and IR-remote-entities. Customize user interface and button mappings for all remote-entities types\nincluding external remote-entities from integrations.\n" + description: | + 🎮 Create BT- and IR-remote-entities. Customize user interface and button mappings for all remote-entities types + including external remote-entities from integrations. - name: profiles - description: "\U0001F464 User profile configuration with profiles, groups, pages" + description: 👤 User profile configuration with profiles, groups, pages - name: cfg - description: "\U0001F4DD Configuration settings" + description: 📝 Configuration settings - name: dock - description: "\U0001F6F0 Docking station management, discovery and infrared testing functions" + description: 🛰 Docking station management, discovery and infrared testing functions - name: system description: ⚙️ System information and commands +externalDocs: + description: Find out more about the Remotes + url: https://www.unfoldedcircle.com/ paths: /pub/version: get: @@ -175,7 +236,8 @@ paths: Set-Cookie: schema: type: string - example: id=abcde12345; Path=/; HttpOnly + examples: + - id=abcde12345; Path=/; HttpOnly content: application/json: schema: @@ -209,7 +271,8 @@ paths: Set-Cookie: schema: type: string - example: 'id=; HttpOnly; Path=/; Max-Age=0; Expires=Sat, 26 Jun 2021 12:05:09 GMT' + examples: + - id=; HttpOnly; Path=/; Max-Age=0; Expires=Sat, 26 Jun 2021 12:05:09 GMT '500': $ref: '#/components/responses/Err500InternalServerError' /auth/api_keys: @@ -293,10 +356,12 @@ paths: application/json: schema: $ref: '#/components/schemas/ApiKeyRequest' - example: - name: My integration - scopes: - - admin + examples: + default: + value: + name: My integration + scopes: + - admin required: true responses: '201': @@ -328,7 +393,7 @@ paths: $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/auth/api_keys/{apiKeyId}': + /auth/api_keys/{apiKeyId}: get: tags: - api-keys @@ -428,33 +493,194 @@ paths: application/json: schema: $ref: '#/components/schemas/Scopes' - /auth/external: + /auth/callback: get: tags: - external-token - summary: "\U0001F9EA Get registered external systems." + summary: 🧪 Public callback endpoint for OAuth2 authorization responses. description: | - External systems cannot be created manually. They are automatically being created if a custom integration driver - requests to use the "external tokens" feature. This is enabled with the driver feature `auth.external_tokens`. + OAuth2 authorization callback endpoint for the Authorization Code grant. + + This endpoint is intended to be used as the redirect URI target for external systems that support OAuth2 + authorization code flow. After the user authorizes the client at the external authorization server, the + authorization server redirects the user agent back with either: + + - a successful authorization response containing `code` and typically `state`, or + - an error response containing `error` and optional error details. + + A successful callback contains `code`. Error callbacks contain `error` instead and do not include a usable + authorization code. + + The callback is processed by the Remote to continue the OAuth2 flow and store the resulting OAuth2 token data for + the corresponding external system or integration driver. - ⚠️ External integration drivers cannot use this feature. + Clients should not call this endpoint directly except for development or testing of OAuth2 flows. - If the expected system name is not returned by this call, all operations on the `/auth/external/{system}` endpoints - with that system name will fail. - Therefore, it's advisable to either call this method first or react on the 404 error while providing or updating an - external system token, to inform the client user, that the integration is not available on the remote. + The `state` parameter should be treated as an opaque value used for request correlation and CSRF protection. + If a `state` value was included in the authorization request, the authorization server must return that exact value + in the callback response. + + This endpoint implements the authorization response handling defined by OAuth 2.0, RFC 6749: + - [Section 4.1: Authorization Code Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1) + - [Section 4.1.2: Authorization Response](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2) + - [Section 4.1.2.1: Error Response](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1) + - [Section 10.12: Cross-Site Request Forgery](https://datatracker.ietf.org/doc/html/rfc6749#section-10.12) + + ### 🚧 Unfolded Circle OAuth redirect service + + The Remote does not have a web browser for the OAuth2 authorization flow, and it is usually not reachable on a + public address. To solve this, Unfolded Circle offers a static redirect page on a public address. + + In practice, the authorization server redirects the user agent to the public Unfolded Circle redirect page first. + That page then forwards the callback parameters to the target Remote on the local network through the browser + running on the user's device. + + The redirect service is only responsible for browser-side forwarding of the callback. The Remote address is not + stored server-side by Unfolded Circle; it is only kept in the user's browser. + operationId: oauth2Callback + parameters: + - name: code + in: query + description: Authorization code returned by the OAuth2 authorization server on successful user authorization. + schema: + type: string + - name: state + in: query + description: Opaque state value returned by the authorization server. Used for request correlation and CSRF protection. + schema: + type: string + - name: error + in: query + description: OAuth2 authorization error code returned by the authorization server instead of an authorization code. + schema: + type: string + - name: error_description + in: query + description: Human-readable error description returned by the authorization server. + schema: + type: string + - name: error_uri + in: query + description: URI identifying a human-readable web page with additional information about the error. + schema: + type: string + responses: + '200': + description: HTML response shown in the user's browser after the OAuth2 authorization callback has been processed or forwarded. + content: + text/html: + schema: + type: string + security: [] + /auth/external: + get: + tags: + - external-token + summary: 🧪 List registered external systems. + description: | + An external system is a device or service that requires authentication. Integration drivers use external systems to + authenticate with services or devices that require either a long-lived token or an OAuth2 authorization code flow. + + External systems cannot be created manually. They are created automatically when an integration driver requests one of + the following driver features: + + - `auth.external_tokens`: enables generic token support for a local or custom integration driver. + - The provided secret is made available to the integration driver runtime as a credential file. This is typically a + long-lived access token. + - ⚠️ External integration drivers cannot use this feature. + - `auth.oauth2.authorization_code`: enables OAuth2 authorization code flow support for an integration driver. + - 🚧 under development + - Only one OAuth2 application credential is supported per integration driver (token type `OAUTH2_APP`). + For example, a Spotify integration driver requires one OAuth2 application credential. + - Multiple OAuth2 token entries can be stored per integration driver (token type `OAUTH2_TOKEN`). + For example, multiple Spotify accounts can be linked to the same integration driver. + + If an external system is associated with an integration driver, the returned `intg_driver_id` field contains the + integration driver ID. + + Clients must not infer semantics from the `system` field value. It is an opaque external system identifier and may + change in the future. + + If an expected external system identifier is not returned by this operation, requests to + `/auth/external/{system}` using that identifier will return `404 Not Found`. + A client should therefore either call this method before creating or updating credentials, or handle `404` responses + accordingly to inform the user that the integration is not available on the Remote. + + The `type`, `state`, and `intg` query parameters can be used to filter the returned external systems. + - `type`: only external systems having at least one credential of the specified type are returned. This implies + `state=ACTIVE`. + - `TOKEN`: generic token, for example a long-lived access token. + - `OAUTH2_APP`: OAuth2 application credentials. Requires an associated integration driver and implies `intg=true`. + - `OAUTH2_TOKEN`: OAuth2 token data, typically including access token, refresh token, and related metadata. + - `state`: filters external systems based on whether they currently have stored credentials. + - `ALL`: no filtering is performed. This is the default. + - `NEW`: only external systems without any stored credentials. + - `ACTIVE`: only external systems with at least one stored credential. + - `intg`: only external systems associated with an integration driver are returned. + + The `token_count` value reflects the applied `type` filter. If no `type` filter is specified, it contains the total + number of stored credentials for the external system. + + Please note that not all filter combinations are currently supported. Common use cases are: + - Return all external systems: no query parameters, or `state=ALL` + - Return external systems associated with an integration driver: `intg=true` + - List external systems associated with an integration driver that do not yet have stored credentials: `intg=true&state=NEW` + - List all OAuth2 application credentials: `type=OAUTH2_APP`. This implies `intg=true&state=ACTIVE` + - List all generic tokens: `type=TOKEN`. This implies `state=ACTIVE` operationId: getExternalSystems + parameters: + - $ref: '#/components/parameters/token_type' + - name: state + in: query + description: Filter external systems by credential state. + required: false + schema: + $ref: '#/components/schemas/ExtSystemState' + - name: intg + in: query + description: Only return external systems associated with an integration driver. + required: false + schema: + type: boolean responses: '200': description: Successful operation content: application/json: schema: - $ref: '#/components/schemas/ExternalSystems' + $ref: '#/components/schemas/ExternalSystemInfos' + examples: + OAuth2 App Credentials (type=OAUTH2_APP): + value: + - system: uc_spotify_driver + name: Household Account + token_count: 1 + token_id: 1234.... + intg_driver_id: uc_spotify_driver + intg_name: + en: Spotify + icon: uc:music + New External Systems (state=NEW): + value: + - system: test-driver + name: Foobar + token_count: 0 + - system: uc_spotify_driver-dev + name: Spotify + token_count: 0 + External Systems for Integration Drivers with Generic Tokens (type=TOKEN&intg=true): + value: + - system: hass + name: Home Assistant + token_count: 1 + intg_driver_id: hass + intg_name: + en: Home Assistant + icon: uc:integration delete: tags: - external-token - summary: Remove all external access tokens. + summary: Remove all external authentication credentials. description: | Management operation to delete all external access tokens. Attention: this cannot be reverted! operationId: deleteAllExternalAccessTokens @@ -465,52 +691,92 @@ paths: application/json: schema: $ref: '#/components/schemas/ApiResponse' - '/auth/external/{system}': + /auth/external/{system}: post: tags: - external-token - summary: "\U0001F9EA Provide an access token of an external system." + summary: 🧪 Create an external authentication credential. description: | - An access token is usually required to connect to external systems like Home Assistant. - This method allows the external system to automatically provide the access token for the corresponding Remote - integration instead of forcing the user to type it in. If the token name already exists for the given system, - error `422` is returned. - Use the PUT method to update an existing token. + This endpoint stores credentials for an external system, for example a generic access token, OAuth2 application + credentials, or OAuth2 token data. + + It can be used by a client or integration workflow to provide credentials for the corresponding integration driver + instead of requiring the user to enter them manually. + + If a credential with the same `name` already exists for the given system, the server returns `422 Unprocessable Entity`. + To replace an existing credential, use `PUT /auth/external/{system}/{tokenId}`. + + ### Token type `TOKEN` + + This is the default generic token type. Required fields are: - - `token_id`: the main identifier for a given system. It must be unique within that system and may not end in - `-DATA` or `-URL`. - - `name`: a friendly name to show in a user interface. It must be unique within that system. + - `token_id`: the primary identifier within the external system. It must be unique within that system and must not end + in `-DATA` or `-URL`. + - `name`: a friendly name to display in a user interface. It must be unique within that system. - `token`: the secret credential. - The format of the access token depends on the external system and the involved Remote integration. - It could be a UUID, a JWT, a PEM certificate or any other representation required for the integration to communicate - with the external system. + The `token` format depends on the external system and the integration driver. It can be a UUID, JWT, PEM + certificate, or any other representation required for authentication or communication with the external system. - ⚠️ External access tokens can be used by the pre-installed integrations and the custom integrations installable by - the user. External integrations cannot access the secret token value. + ⚠️ `TOKEN` credentials can be used by built-in and custom integration drivers. External integration drivers cannot + access the secret token value. - ⚠️ The secret token value cannot be retrieved anymore with the API and is only available in the corresponding driver - runtime as a credential file. + ⚠️ The secret token value cannot be retrieved through the API after creation. It is only made available to the + corresponding integration driver runtime as a credential file. - To use the "external tokens" feature an integration driver has to request the driver feature `auth.external_tokens`. - If enabled, an external system is automatically created with the `system` identifier matching the `driver_id`. + To use generic external tokens, an integration driver must request the `auth.external_tokens` driver feature. + If enabled, an external system is created automatically with the `system` identifier matching the `driver_id`. - Use the `GET /auth/external` method the retrieve the registered systems. + Use `GET /auth/external` to retrieve the registered external systems. - Mapped credential files are automatically created in the corresponding integration driver runtime for the new token: - - Environment variable `UC_TOKENS_HOME` specifies the directory containing the credential files. - - The `token_id` value is used as credential file name for the secret token. - - For example: for `token_id: foobar`, the credential file is accessible at the `${UC_TOKENS_HOME}/foobar` path. - - The credential file contains the `token` field value in plain text. + Credential files are created automatically in the corresponding integration driver runtime for a new `TOKEN` entry: + - The `UC_TOKENS_HOME` environment variable specifies the directory containing the credential files. + - The `token_id` value is used as the file name for the secret token. + - Example: for `token_id: foobar`, the secret token is available at `${UC_TOKENS_HOME}/foobar`. + - The file contains the `token` field value in plain text. - Optional files are created for the `url` and `data` fields: - `{token_id}-URL` contains the `url` value. Example: `${UC_TOKENS_HOME}/foobar-URL` - `{token_id}-DATA` contains the `data` value. Example: `${UC_TOKENS_HOME}/foobar-DATA` + + ### Token type `OAUTH2_APP` + + This token type stores OAuth2 application credentials consisting of the client ID and client secret. + + Required fields are: + - `name`: a friendly name to display in a user interface. It must be unique within that system. + This is typically the linked integration name or another identifier for the target application, for example an + account name. + - `token_id`: OAuth2 client ID + - `token`: OAuth2 client secret + + The `url` and `data` fields are not used for OAuth2 application credentials. + + ⚠️ The secret token value cannot be retrieved through the API after creation. It is only made available to the + corresponding integration driver runtime through the OAuth2-specific Integration API messages. + + To use OAuth2 application credentials, an integration driver must request the + `auth.oauth2.authorization_code` driver feature. + If enabled, an external system is created automatically with the `system` identifier matching the `driver_id`. + + ### 🚧 Token type `OAUTH2_TOKEN` + + This token type stores OAuth2 token data returned by the authorization code flow, typically including an access token, + refresh token, and related metadata such as expiration information. + + `OAUTH2_TOKEN` entries are normally created automatically after a successful OAuth2 authorization code flow. For + development and testing purposes, they can also be created manually. + + Multiple `OAUTH2_TOKEN` entries can be stored for the same OAuth2 application. For example, multiple Spotify accounts + can be linked to the same integration driver. + + 🚧 For manual creation of `OAUTH2_TOKEN` entries, the request payload format is not yet finalized and should + currently be treated as implementation-specific. It will be documented later. operationId: addExternalAccessToken parameters: - $ref: '#/components/parameters/system' requestBody: - description: Access token that needs to be added to the remote. + description: Credential to store for the external system. content: application/json: schema: @@ -518,7 +784,7 @@ paths: required: true responses: '201': - description: Successful operation returning the token identifier in the response. + description: Credential created successfully. Returns the token identifier. content: application/json: schema: @@ -536,10 +802,14 @@ paths: head: tags: - external-token - summary: "\U0001F9EA Get total number of available tokens for an external system." + summary: 🧪 Get total number of available credentials for an external system. + description: | + Returns the total number of stored credentials for the specified external system. + Use the optional `type` query parameter to restrict the count to a single credential type. operationId: getExternalAccessTokenCount parameters: - $ref: '#/components/parameters/system' + - $ref: '#/components/parameters/token_type' responses: '200': description: Successful operation @@ -557,10 +827,16 @@ paths: get: tags: - external-token - summary: "\U0001F9EA List available tokens for an external system." + summary: 🧪 List available credentials for an external system. + description: | + Lists stored credentials for the specified external system. + + Use the optional `type` query parameter to restrict the result to a single credential type. + The returned objects contain public metadata only. Secret credential values are never returned by the API. operationId: getExternalAccessTokens parameters: - $ref: '#/components/parameters/system' + - $ref: '#/components/parameters/token_type' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' responses: @@ -594,12 +870,21 @@ paths: delete: tags: - external-token - summary: Remove all access tokens of an external system. + summary: Remove all credentials of an external system. description: | - All mapped credential files of the corresponding integration driver are also deleted. + Stored runtime credential material for the corresponding integration driver is also removed. + For `TOKEN` credentials, this includes the mapped credential files. + + ⚠️ The `delete_system` parameter is only intended for testing and development. This can put your system in an unstable state! operationId: deleteExternalAccessTokensBySystem parameters: - $ref: '#/components/parameters/system' + - name: delete_system + in: query + description: Also delete the external system entry after removing all associated credentials. + required: false + schema: + type: boolean responses: '200': description: Successful operation @@ -609,24 +894,24 @@ paths: $ref: '#/components/schemas/ApiResponse' '404': $ref: '#/components/responses/Err404NotFound' - '/auth/external/{system}/{tokenId}': + /auth/external/{system}/{tokenId}: get: tags: - external-token - summary: "\U0001F9EA Get external access token." + summary: 🧪 Get an external authentication credential. description: | - Retrieve an external access token by system and token identifiers. + Retrieve a stored credential for the specified external system and token identifier. - ⚠️ Only the public information of the token is returned, the secret token value itself cannot be retrieved anymore - with the API. + ⚠️ Only the public metadata of the credential is returned. The secret credential value cannot be retrieved through + the API after creation. - The secret token values are automatically mapped to credential files in the corresponding integration driver - runtime. The `token_id` value is used as file name for the token, with additional files for the optional `url` and - `data` fields. + For `TOKEN` credentials, the secret value is made available to the corresponding integration driver runtime as a + credential file. For OAuth2-related credential types, secret values are made available through the corresponding + OAuth2-specific integration mechanisms. operationId: getExternalAccessToken parameters: - $ref: '#/components/parameters/system' - - $ref: '#/components/parameters/token_id' + - $ref: '#/components/parameters/tokenId' responses: '200': description: Successful operation @@ -645,19 +930,26 @@ paths: put: tags: - external-token - summary: "\U0001F9EA Replace an existing access token of an external system." + summary: 🧪 Replace an existing credential of an external system. description: | - This methods allows an already provided token of an external system to be updated. The token is identified by - the system name and the token identification. + Replace an existing credential identified by the external system identifier and `tokenId`. - The token, url and data values are also updated in the mapped credential files of the corresponding running - integration driver. + The request body uses the same schema as credential creation. The path parameter `tokenId` identifies the existing + credential to replace. + + For `TOKEN` credentials, updated secret values are also propagated to the corresponding credential files in the + integration driver runtime. For OAuth2-related credential types, updated secret values are propagated through the + corresponding OAuth2-specific integration mechanisms. + + Notes: + - The `token_id` field in the request body is ignored. + - If `name` is changed, it needs to be unique within the `system`. operationId: replaceExternalAccessToken parameters: - $ref: '#/components/parameters/system' - - $ref: '#/components/parameters/token_id' + - $ref: '#/components/parameters/tokenId' requestBody: - description: Access token to update + description: Credential data used to replace the existing external system credential. content: application/json: schema: @@ -677,15 +969,15 @@ paths: delete: tags: - external-token - summary: Remove an external access token. + summary: Remove an external authentication credential. description: | - No error is returned if the `tokenId` doesn't exist. `404` is only returned it the `system` is not found. + No error is returned if the `tokenId` does not exist. `404` is only returned if the external system is not found. The mapped credential files of the corresponding integration driver are also deleted. operationId: deleteExternalAccessToken parameters: - $ref: '#/components/parameters/system' - - $ref: '#/components/parameters/token_id' + - $ref: '#/components/parameters/tokenId' responses: '200': description: Successful operation @@ -708,87 +1000,89 @@ paths: application/json: schema: $ref: '#/components/schemas/SupportedResources' - example: - - type: Icon - name: - en: Icon - de: Icon - description: - en: User interface icons for entities and integrations. Icons must be of size 90x90 pixels and either in PNG or JPG format. Maximum size is 32 KB. - de: Icons für die Benutzeroberfläche von Objekten und Integrationen. Die Icons müssen 90x90 Pixel gross und im PNG oder JPG Format sein. Maximale Grösse ist 32 KB. - file_formats: - - png - - jpg - max_file_size: 32768 - max_count: 100 - image: - sizes: - - width: 90 - height: 90 - - type: TvChannelIcon - name: - en: TV channel icon - de: TV Sender Icon - description: - en: User interface icons for TV channels. Icons must be of size 90x90 pixels and either in PNG or JPG format. Maximum size is 32 KB. - de: TV Sender Icons für die Benutzeroberfläche. Die Icons müssen 90x90 Pixel gross und im PNG oder JPG Format sein. Maximale Grösse ist 32 KB. - file_formats: - - png - - jpg - max_file_size: 32768 - max_count: 256 - image: - sizes: - - width: 90 - height: 90 - - type: BackgroundImage - name: - en: Background image - de: Hintergrund Bild - description: - en: Background image for user interface profile pages. Images must be of size 275x480 pixels and either in PNG or JPG format. Maximum size is 1 MB. - de: Hintergrund Bild für Profil Seiten. Die Bilder müssen 275x480 Pixel gross und im PNG oder JPG Format sein. Maximale Grösse ist 1 MB. - file_formats: - - png - - jpg - max_file_size: 1048576 - max_count: 30 - image: - sizes: - - width: 275 - height: 480 - - type: Sound - name: - en: Sound effect - de: Klangeffekt - description: - en: User interface sound effects. Maximum size is 1 MB. - de: Klangeffekte für die Benutzeroberfläche. Maximale Grösse ist 1 MB. - file_formats: - - wav - max_file_size: 1048576 - max_count: 50 - sound: - bits: - - 8 - - 16 - channels: - - 1 - - 2 - sampling_rates: - - 11025 - - 22050 - - 44100 - - type: BtDeviceProfile - name: - en: Bluetooth device profile - de: Bluetooth Geräteprofil - description: - en: Bluetooth peripheral device profile. Defines available HID commands like keyboard keys and consumer codes. Maximum size is 64 KB. - file_formats: - - json - max_file_size: 65536 - max_count: 100 + examples: + default: + value: + - type: Icon + name: + en: Icon + de: Icon + description: + en: User interface icons for entities and integrations. Icons must be of size 90x90 pixels and either in PNG or JPG format. Maximum size is 32 KB. + de: Icons für die Benutzeroberfläche von Objekten und Integrationen. Die Icons müssen 90x90 Pixel gross und im PNG oder JPG Format sein. Maximale Grösse ist 32 KB. + file_formats: + - png + - jpg + max_file_size: 32768 + max_count: 100 + image: + sizes: + - width: 90 + height: 90 + - type: TvChannelIcon + name: + en: TV channel icon + de: TV Sender Icon + description: + en: User interface icons for TV channels. Icons must be of size 90x90 pixels and either in PNG or JPG format. Maximum size is 32 KB. + de: TV Sender Icons für die Benutzeroberfläche. Die Icons müssen 90x90 Pixel gross und im PNG oder JPG Format sein. Maximale Grösse ist 32 KB. + file_formats: + - png + - jpg + max_file_size: 32768 + max_count: 256 + image: + sizes: + - width: 90 + height: 90 + - type: BackgroundImage + name: + en: Background image + de: Hintergrund Bild + description: + en: Background image for user interface profile pages. Images must be of size 275x480 pixels and either in PNG or JPG format. Maximum size is 1 MB. + de: Hintergrund Bild für Profil Seiten. Die Bilder müssen 275x480 Pixel gross und im PNG oder JPG Format sein. Maximale Grösse ist 1 MB. + file_formats: + - png + - jpg + max_file_size: 1048576 + max_count: 30 + image: + sizes: + - width: 275 + height: 480 + - type: Sound + name: + en: Sound effect + de: Klangeffekt + description: + en: User interface sound effects. Maximum size is 1 MB. + de: Klangeffekte für die Benutzeroberfläche. Maximale Grösse ist 1 MB. + file_formats: + - wav + max_file_size: 1048576 + max_count: 50 + sound: + bits: + - 8 + - 16 + channels: + - 1 + - 2 + sampling_rates: + - 11025 + - 22050 + - 44100 + - type: BtDeviceProfile + name: + en: Bluetooth device profile + de: Bluetooth Geräteprofil + description: + en: Bluetooth peripheral device profile. Defines available HID commands like keyboard keys and consumer codes. Maximum size is 64 KB. + file_formats: + - json + max_file_size: 65536 + max_count: 100 delete: tags: - resources @@ -805,7 +1099,7 @@ paths: application/json: schema: $ref: '#/components/schemas/ApiResponse' - '/resources/{type}': + /resources/{type}: head: tags: - resources @@ -933,7 +1227,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/resources/{type}/{id}': + /resources/{type}/{id}: get: tags: - resources @@ -1091,7 +1385,7 @@ paths: maximum: 300 - name: new in: query - description: 'Only return new devices, filter out already configured integrations.' + description: Only return new devices, filter out already configured integrations. required: false schema: type: boolean @@ -1129,7 +1423,7 @@ paths: $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/intg/discover/{driverId}': + /intg/discover/{driverId}: get: tags: - integrations @@ -1155,7 +1449,7 @@ paths: put: tags: - integrations - summary: "\U0001F9EA Execute connection test and fetch metadata from discovered integration driver." + summary: 🧪 Execute connection test and fetch metadata from discovered integration driver. description: | Perform a driver connection test with a discovered driver. If the driver requires a token, it must be specified in the request body. @@ -1212,7 +1506,7 @@ paths: Connection test with custom driver url: value: connection: - driver_url: 'ws://my-integration.local:8080' + driver_url: ws://my-integration.local:8080 responses: '200': description: Command response @@ -1273,7 +1567,7 @@ paths: name: $ref: '#/components/schemas/LanguageText' driver_url: - description: 'Custom WebSocket URL of the driver, otherwise the discovered driver address is used.' + description: Custom WebSocket URL of the driver, otherwise the discovered driver address is used. type: string format: uri maxLength: 2048 @@ -1287,7 +1581,7 @@ paths: value: {} Configure driver with custom url: value: - driver_url: 'ws://my-integration.local:8080' + driver_url: ws://my-integration.local:8080 Configure driver with default name & url and custom token: value: token: '0000' @@ -1319,7 +1613,7 @@ paths: post: tags: - integrations - summary: "\U0001F9EA Upload and install a custom integration." + summary: 🧪 Upload and install a custom integration. description: | Install a custom integration driver from an integration driver installation archive. @@ -1469,9 +1763,11 @@ paths: application/json: schema: $ref: '#/components/schemas/IntegrationSetupInfo' - example: - id: sim-test - state: SETUP + examples: + default: + value: + id: sim-test + state: SETUP '400': $ref: '#/components/responses/Err400BadRequest' '401': @@ -1503,7 +1799,7 @@ paths: $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/intg/setup/{driverId}': + /intg/setup/{driverId}: get: tags: - integrations @@ -1701,7 +1997,7 @@ paths: post: tags: - integrations - summary: "\U0001F9EA Manually register a new integration driver." + summary: 🧪 Manually register a new integration driver. description: | A driver provides the connection parameters and optional setup configuration for an integration driver. @@ -1744,7 +2040,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/intg/drivers/{driverId}': + /intg/drivers/{driverId}: get: tags: - integrations @@ -1865,10 +2161,8 @@ paths: examples: Connection test: value: - driver_url: 'ws://192.168.1.200:8000/ws' + driver_url: ws://192.168.1.200:8000/ws token: '0000' - Other: - value: null responses: '200': description: | @@ -2049,7 +2343,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/intg/instances/{intgId}': + /intg/instances/{intgId}: get: tags: - integrations @@ -2164,7 +2458,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/intg/instances/{intgId}/entities': + /intg/instances/{intgId}/entities: get: tags: - integrations @@ -2279,7 +2573,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/intg/instances/{intgId}/entities/{entityId}': + /intg/instances/{intgId}/entities/{entityId}: post: tags: - integrations @@ -2326,7 +2620,7 @@ paths: operationId: getEntityCount parameters: - $ref: '#/components/parameters/entity_types' - - $ref: '#/components/parameters/intg_ids' + - $ref: '#/components/parameters/integration_ids' - $ref: '#/components/parameters/exclude' - $ref: '#/components/parameters/query' responses: @@ -2365,7 +2659,7 @@ paths: operationId: getEntities parameters: - $ref: '#/components/parameters/entity_types' - - $ref: '#/components/parameters/intg_ids' + - $ref: '#/components/parameters/integration_ids' - $ref: '#/components/parameters/exclude' - $ref: '#/components/parameters/query' - $ref: '#/components/parameters/page' @@ -2444,7 +2738,7 @@ paths: $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/entities/{entityId}': + /entities/{entityId}: get: tags: - entities @@ -2523,7 +2817,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/entities/{entityId}/command': + /entities/{entityId}/command: put: tags: - entities @@ -2555,11 +2849,11 @@ paths: $ref: '#/components/responses/Err404NotFound' '422': $ref: '#/components/responses/Err422UnprocessableEntity' - '/entities/{entityId}/media/browse': + /entities/{entityId}/media/browse: get: tags: - entities - summary: "\U0001F50D Browse media containers." + summary: 🔍 Browse media containers. description: | This endpoint allows browsing media containers within supported media-player entities. @@ -2640,11 +2934,11 @@ paths: $ref: '#/components/responses/Err500InternalServerError' '503': $ref: '#/components/responses/Err503ServiceUnavailable' - '/entities/{entityId}/media/search': + /entities/{entityId}/media/search: get: tags: - entities - summary: "\U0001F50D Search for media items." + summary: 🔍 Search for media items. description: | This endpoint allows searching for media within supported media-player entities. @@ -2860,7 +3154,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ActivityRequest' + $ref: '#/components/schemas/ActivityCreate' examples: simple: value: @@ -2870,7 +3164,7 @@ paths: value: name: en: My new activity - icon: 'uc:bell' + icon: uc:bell description: en: Testing the activity feature clone: @@ -2908,12 +3202,25 @@ paths: $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/activities/{entityId}': + /activities/{entityId}: get: tags: - activities summary: Get an activity by its entity_id. - description: "Returns all the information required to manage an existing activity. The included entities are enriched with `name`,\n`icon`, `entity_type`, available commands and if the entity is still available or has been removed since the\nactivity was defined.\n\nThe available entity commands are divided into:\n- `entity_commands`: regular entity commands as defined in the [entity documentation](https://github.com/unfoldedcircle/core-api/tree/main/doc/entities).\n The identifier refers to the common entity command definitions, which describe all required parameters for \n defining a command. This includes the mandatory `cmd_id` name and optional parameters.\n\n \U0001F477 TODO endpoint to retrieve entity command definitions.\n- `simple_commands`: additional, simple dynamic commands of an entity. Like infrared code commands of a\n remote-entity. A simple command relates directly to the `cmd_id` attribute when executing a command and there's\n no further mapping as for _entity_commands_.\n" + description: | + Returns all the information required to manage an existing activity. The included entities are enriched with `name`, + `icon`, `entity_type`, available commands and if the entity is still available or has been removed since the + activity was defined. + + The available entity commands are divided into: + - `entity_commands`: regular entity commands as defined in the [entity documentation](https://github.com/unfoldedcircle/core-api/tree/main/doc/entities). + The identifier refers to the common entity command definitions, which describe all required parameters for + defining a command. This includes the mandatory `cmd_id` name and optional parameters. + + 👷 TODO endpoint to retrieve entity command definitions. + - `simple_commands`: additional, simple dynamic commands of an entity. Like infrared code commands of a + remote-entity. A simple command relates directly to the `cmd_id` attribute when executing a command and there's + no further mapping as for _entity_commands_. operationId: getActivity parameters: - $ref: '#/components/parameters/entity_id' @@ -2992,7 +3299,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/activities/{entityId}/buttons': + /activities/{entityId}/buttons: get: tags: - activities @@ -3101,7 +3408,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/activities/{entityId}/buttons/{buttonId}': + /activities/{entityId}/buttons/{buttonId}: get: tags: - activities @@ -3193,7 +3500,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/activities/{entityId}/buttons/{buttonId}/{buttonPress}': + /activities/{entityId}/buttons/{buttonId}/{buttonPress}: get: tags: - remotes @@ -3210,8 +3517,10 @@ paths: application/json: schema: $ref: '#/components/schemas/EntityCommand' - example: - cmd_id: HOME + examples: + default: + value: + cmd_id: HOME '400': $ref: '#/components/responses/Err400BadRequest' '401': @@ -3240,7 +3549,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/activities/{entityId}/ui': + /activities/{entityId}/ui: get: tags: - activities @@ -3289,7 +3598,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/activities/{entityId}/ui/pages': + /activities/{entityId}/ui/pages: post: tags: - activities @@ -3412,7 +3721,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/activities/{entityId}/ui/pages/{pageId}': + /activities/{entityId}/ui/pages/{pageId}: get: tags: - activities @@ -3595,7 +3904,7 @@ paths: $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/activity_groups/{groupId}': + /activity_groups/{groupId}: get: tags: - activities @@ -3775,7 +4084,7 @@ paths: value: name: en: My new macro - icon: 'uc:bell' + icon: uc:bell description: en: Testing the macro feature clone: @@ -3813,7 +4122,7 @@ paths: $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/macros/{entityId}': + /macros/{entityId}: get: tags: - macros @@ -3907,7 +4216,9 @@ paths: schema: type: string minLength: 2 - example: Lucky Goldstar + examples: + default: + value: Lucky Goldstar - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' responses: @@ -3945,14 +4256,16 @@ paths: required: - id - name - example: - - id: lg - name: LG + examples: + default: + value: + - id: lg + name: LG '401': $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/ir/codes/manufacturers/{manufacturerId}': + /ir/codes/manufacturers/{manufacturerId}: get: tags: - infrared @@ -4011,27 +4324,29 @@ paths: required: - id - name - example: - - id: '1' - name: Generic TV 1 - custom: false - - id: '2' - name: Generic TV 2 - custom: false - - id: '3' - name: Generic TV 3 - custom: false - - id: '4' - name: Generic Projector - custom: false - - id: '5' - name: My BluRay Player - custom: true - '401': - $ref: '#/components/responses/Err401Unauthorized' - '403': - $ref: '#/components/responses/Err403Forbidden' - '/ir/codes/manufacturers/{manufacturerId}/{codeSetId}': + examples: + default: + value: + - id: '1' + name: Generic TV 1 + custom: false + - id: '2' + name: Generic TV 2 + custom: false + - id: '3' + name: Generic TV 3 + custom: false + - id: '4' + name: Generic Projector + custom: false + - id: '5' + name: My BluRay Player + custom: true + '401': + $ref: '#/components/responses/Err401Unauthorized' + '403': + $ref: '#/components/responses/Err403Forbidden' + /ir/codes/manufacturers/{manufacturerId}/{codeSetId}: get: tags: - infrared @@ -4059,36 +4374,38 @@ paths: type: array items: type: string - example: - - POWER_ON - - POWER_OFF - - POWER_TOGGLE - - VOLUME_UP - - VOLUME_DOWN - - MUTE - - CHANNEL_UP - - CHANNEL_DOWN - - DPAD_LEFT - - DPAD_RIGHT - - DPAD_UP - - DPAD_DOWN - - ENTER - - OSD - - SETUP - - NUMPAD_0 - - NUMPAD_1 - - NUMPAD_2 - - NUMPAD_3 - - NUMPAD_4 - - NUMPAD_5 - - NUMPAD_6 - - NUMPAD_7 - - NUMPAD_8 - - NUMPAD_9 - - HDMI_1 - - HDMI_2 - - HDMI_3 - - HDMI_4 + examples: + default: + value: + - POWER_ON + - POWER_OFF + - POWER_TOGGLE + - VOLUME_UP + - VOLUME_DOWN + - MUTE + - CHANNEL_UP + - CHANNEL_DOWN + - DPAD_LEFT + - DPAD_RIGHT + - DPAD_UP + - DPAD_DOWN + - ENTER + - OSD + - SETUP + - NUMPAD_0 + - NUMPAD_1 + - NUMPAD_2 + - NUMPAD_3 + - NUMPAD_4 + - NUMPAD_5 + - NUMPAD_6 + - NUMPAD_7 + - NUMPAD_8 + - NUMPAD_9 + - HDMI_1 + - HDMI_2 + - HDMI_3 + - HDMI_4 '401': $ref: '#/components/responses/Err401Unauthorized' '403': @@ -4140,7 +4457,7 @@ paths: maxLength: 1 responses: '200': - description: 'Successful operation, either with paginated JSON or CSV response.' + description: Successful operation, either with paginated JSON or CSV response. headers: Pagination-Count: description: Total number of code sets. @@ -4163,15 +4480,17 @@ paths: text/csv: schema: type: string - example: | - manufacturer,device,key,format,code - custom,My AVR,CURSOR_DOWN,HEX,3;0x20F0827D;32;0 - custom,My AVR,CURSER_ENTER,HEX,3;0x20F022DD;32;0 - custom,My AVR,CURSOR_LEFT,HEX,3;0x20F0E01F;32;0 - custom,My AVR,CURSOR_RIGHT,HEX,3;0x20F0609F;32;0 - custom,My AVR,CURSOR_UP,HEX,3;0x20F002FD;32;0 - Foobar,TV,POWER_ON,PRONTO,0000 006d 0000 0024 0157 00ac 0015 0015 0015 0015 0015 0040 0015 0015 0015 0015 0015 0015 0015 0015 0015 0015 0015 0040 0015 0040 0015 0015 0015 0040 0015 0040 0015 0040 0015 0040 0015 0040 0015 0015 0015 0015 0015 0040 0015 0015 0015 0015 0015 0015 0015 0040 0015 0040 0015 0040 0015 0040 0015 0015 0015 0040 0015 0040 0015 0040 0015 0015 0015 0015 0015 0689 0157 0056 0015 0e94 - Foobar,TV,POWER_OFF,PRONTO,0000 006d 0000 0024 0157 00ab 0015 0015 0016 0015 0016 003f 0016 0015 0015 0016 0015 0015 0016 0015 0016 0015 0015 0040 0015 0040 0015 0015 0016 003f 0016 003f 0016 003f 0016 003f 0016 003f 0016 003f 0016 0015 0016 003f 0016 0015 0015 0015 0016 0015 0016 003f 0016 003f 0016 0015 0015 0040 0015 0015 0016 003f 0016 003f 0016 003f 0016 0015 0016 0015 0015 05fd 0156 0055 0016 0ee1 + examples: + default: + value: | + manufacturer,device,key,format,code + custom,My AVR,CURSOR_DOWN,HEX,3;0x20F0827D;32;0 + custom,My AVR,CURSER_ENTER,HEX,3;0x20F022DD;32;0 + custom,My AVR,CURSOR_LEFT,HEX,3;0x20F0E01F;32;0 + custom,My AVR,CURSOR_RIGHT,HEX,3;0x20F0609F;32;0 + custom,My AVR,CURSOR_UP,HEX,3;0x20F002FD;32;0 + Foobar,TV,POWER_ON,PRONTO,0000 006d 0000 0024 0157 00ac 0015 0015 0015 0015 0015 0040 0015 0015 0015 0015 0015 0015 0015 0015 0015 0015 0015 0040 0015 0040 0015 0015 0015 0040 0015 0040 0015 0040 0015 0040 0015 0040 0015 0015 0015 0015 0015 0040 0015 0015 0015 0015 0015 0015 0015 0040 0015 0040 0015 0040 0015 0040 0015 0015 0015 0040 0015 0040 0015 0040 0015 0015 0015 0015 0015 0689 0157 0056 0015 0e94 + Foobar,TV,POWER_OFF,PRONTO,0000 006d 0000 0024 0157 00ab 0015 0015 0016 0015 0016 003f 0016 0015 0015 0016 0015 0015 0016 0015 0016 0015 0015 0040 0015 0040 0015 0015 0016 003f 0016 003f 0016 003f 0016 003f 0016 003f 0016 003f 0016 0015 0016 003f 0016 0015 0015 0015 0016 0015 0016 003f 0016 003f 0016 0015 0015 0040 0015 0015 0016 003f 0016 003f 0016 003f 0016 0015 0016 0015 0015 05fd 0156 0055 0016 0ee1 '401': $ref: '#/components/responses/Err401Unauthorized' '403': @@ -4224,7 +4543,7 @@ paths: $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/ir/codes/custom/{codeSetId}': + /ir/codes/custom/{codeSetId}: get: tags: - infrared @@ -4252,7 +4571,7 @@ paths: maxLength: 1 responses: '200': - description: 'Successful operation, either with paginated JSON or CSV response.' + description: Successful operation, either with paginated JSON or CSV response. headers: Pagination-Count: description: Total number of items. @@ -4273,13 +4592,15 @@ paths: text/csv: schema: type: string - example: | - key,format,code - CURSOR_DOWN,HEX,3;0x20F0827D;32;0 - CURSER_ENTER,HEX,3;0x20F022DD;32;0 - CURSOR_LEFT,HEX,3;0x20F0E01F;32;0 - CURSOR_RIGHT,HEX,3;0x20F0609F;32;0 - CURSOR_UP,HEX,3;0x20F002FD;32;0 + examples: + default: + value: | + key,format,code + CURSOR_DOWN,HEX,3;0x20F0827D;32;0 + CURSER_ENTER,HEX,3;0x20F022DD;32;0 + CURSOR_LEFT,HEX,3;0x20F0E01F;32;0 + CURSOR_RIGHT,HEX,3;0x20F0609F;32;0 + CURSOR_UP,HEX,3;0x20F002FD;32;0 '401': $ref: '#/components/responses/Err401Unauthorized' '403': @@ -4433,7 +4754,7 @@ paths: $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/ir/codes/custom/{codeSetId}/{key}': + /ir/codes/custom/{codeSetId}/{key}: get: tags: - infrared @@ -4549,7 +4870,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/ir/convert/{format}': + /ir/convert/{format}: get: tags: - infrared @@ -4668,7 +4989,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/ir/emitters/{emitterId}': + /ir/emitters/{emitterId}: get: tags: - infrared @@ -4691,7 +5012,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/ir/emitters/{emitterId}/send': + /ir/emitters/{emitterId}/send: put: tags: - infrared @@ -4829,7 +5150,7 @@ paths: port_id: '4' PRONTO code on default output: value: - code: '0000,0068,0000,0010,0060,0018,0030,0018,0018,0018,0030,0018,0018,0018,0018,0018,0030,0018,0018,0018,0030,0018,0030,0018,0030,0018,0018,0018,0030,0018,0018,0018,0018,0018,0030,0318' + code: 0000,0068,0000,0010,0060,0018,0030,0018,0018,0018,0030,0018,0018,0018,0018,0018,0030,0018,0018,0018,0030,0018,0030,0018,0030,0018,0018,0018,0030,0018,0018,0018,0018,0018,0030,0318 format: PRONTO PRONTO code on default output and repeat count: value: @@ -4854,7 +5175,7 @@ paths: $ref: '#/components/responses/Err404NotFound' '503': $ref: '#/components/responses/Err503ServiceUnavailable' - '/ir/emitters/{emitterId}/stop_send': + /ir/emitters/{emitterId}/stop_send: put: tags: - infrared @@ -4889,7 +5210,7 @@ paths: $ref: '#/components/responses/Err404NotFound' '503': $ref: '#/components/responses/Err503ServiceUnavailable' - '/ir/emitters/{emitterId}/learn': + /ir/emitters/{emitterId}/learn: get: tags: - infrared @@ -5104,11 +5425,11 @@ paths: en: My custom remote custom_codeset: device_name: My device - 'IR-remote with icon, description and custom code set': + IR-remote with icon, description and custom code set: value: name: en: My custom remote - icon: 'uc:movie' + icon: uc:movie description: en: Testing the custom code set feature custom_codeset: @@ -5119,7 +5440,7 @@ paths: value: name: en: My BT remote - icon: 'uc:tv' + icon: uc:tv description: en: Using the default device profile kind: BT @@ -5167,7 +5488,7 @@ paths: $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/remotes/{entityId}': + /remotes/{entityId}: get: tags: - remotes @@ -5214,11 +5535,11 @@ paths: schema: $ref: '#/components/schemas/RemoteUpdate' examples: - 'Name, icon and description': + Name, icon and description: value: name: en: New remote name - icon: 'uc:tv' + icon: uc:tv description: en: Updated description Output emitter: @@ -5268,7 +5589,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/remotes/{entityId}/ir': + /remotes/{entityId}/ir: get: tags: - remotes @@ -5291,7 +5612,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/remotes/{entityId}/ir/{cmdId}': + /remotes/{entityId}/ir/{cmdId}: post: tags: - remotes @@ -5425,11 +5746,11 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/remotes/{entityId}/bt': + /remotes/{entityId}/bt: get: tags: - remotes - summary: "\U0001F9EA Get information about a Bluetooth remote-entity." + summary: 🧪 Get information about a Bluetooth remote-entity. description: | Retrieve information of this BT-remote entity. @@ -5458,8 +5779,8 @@ paths: profile: 1 dev_profile_id: my_device peer: - address: 'AE:35:DC:88:AA:11' - addr_type: LePublic + address: AE:35:DC:88:AA:11 + addr_type: LE_PUBLIC peripherals: keyboard: true mouse: false @@ -5469,11 +5790,11 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/remotes/{entityId}/bt/pairing': + /remotes/{entityId}/bt/pairing: get: tags: - remotes - summary: "\U0001F9EA Get pairing information of a Bluetooth remote-entity." + summary: 🧪 Get pairing information of a Bluetooth remote-entity. description: | Retrieve pairing specific information of this BT-remote entity. @@ -5497,19 +5818,10 @@ paths: Paired peripheral: value: paired: true - peer: - address: 'AE:35:DC:88:AA:11' - addr_type: LePublic - Bonding request: - value: - bonding_request: - profile: 1 - peer: - address: 'AE:35:DC:88:AA:11' - addr_type: LePublic - kind: PasskeyInput - paired: false pairing_enabled: true + peer: + address: AE:35:DC:88:AA:11 + addr_type: LE_PUBLIC '400': $ref: '#/components/responses/Err400BadRequest' '401': @@ -5521,7 +5833,7 @@ paths: put: tags: - remotes - summary: "\U0001F9EA Enable or disable BT-remote pairing." + summary: 🧪 Enable or disable BT-remote pairing. description: | Once a BT-remote entity is paired with a central, it will no longer accept pairing requests from a central. For example if the user removed the pairing information (usually through a "forget this Bluetooth device" action). @@ -5558,7 +5870,7 @@ paths: post: tags: - remotes - summary: "\U0001F9EA Send a pairing response." + summary: 🧪 Send a pairing response. description: | Send the displayed pairing passkey on the central or decline a pairing request. @@ -5576,12 +5888,15 @@ paths: examples: Passkey entry: value: + id: 11 passkey: '012345' Decline passkey pairing request: value: + id: 11 confirm: false Accept non-passkey pairing request: value: + id: 12 confirm: true required: true responses: @@ -5597,7 +5912,7 @@ paths: $ref: '#/components/responses/Err404NotFound' '503': $ref: '#/components/responses/Err503ServiceUnavailable' - '/remotes/{entityId}/buttons': + /remotes/{entityId}/buttons: get: tags: - remotes @@ -5612,24 +5927,26 @@ paths: application/json: schema: $ref: '#/components/schemas/DeviceButtonMappings' - example: - - button: DPAD_DOWN - short_press: - cmd_id: CURSOR_DOWN - long_press: - cmd_id: BACK - - button: DPAD_MIDDLE - short_press: - cmd_id: CURSOR_ENTER - - button: DPAD_LEFT - short_press: - cmd_id: CURSOR_LEFT - - button: DPAD_RIGHT - short_press: - cmd_id: CURSOR_RIGHT - - button: DPAD_UP - short_press: - cmd_id: CURSOR_UP + examples: + default: + value: + - button: DPAD_DOWN + short_press: + cmd_id: CURSOR_DOWN + long_press: + cmd_id: BACK + - button: DPAD_MIDDLE + short_press: + cmd_id: CURSOR_ENTER + - button: DPAD_LEFT + short_press: + cmd_id: CURSOR_LEFT + - button: DPAD_RIGHT + short_press: + cmd_id: CURSOR_RIGHT + - button: DPAD_UP + short_press: + cmd_id: CURSOR_UP '401': $ref: '#/components/responses/Err401Unauthorized' '403': @@ -5717,32 +6034,34 @@ paths: application/json: schema: $ref: '#/components/schemas/DeviceButtonMappings' - example: - - button: BACK - short_press: - cmd_id: BACK - - button: DPAD_DOWN - short_press: - cmd_id: CURSOR_DOWN - - button: DPAD_MIDDLE - short_press: - cmd_id: CURSOR_ENTER - - button: DPAD_LEFT - short_press: - cmd_id: CURSOR_LEFT - - button: DPAD_RIGHT - short_press: - cmd_id: CURSOR_RIGHT - - button: DPAD_UP - short_press: - cmd_id: CURSOR_UP + examples: + default: + value: + - button: BACK + short_press: + cmd_id: BACK + - button: DPAD_DOWN + short_press: + cmd_id: CURSOR_DOWN + - button: DPAD_MIDDLE + short_press: + cmd_id: CURSOR_ENTER + - button: DPAD_LEFT + short_press: + cmd_id: CURSOR_LEFT + - button: DPAD_RIGHT + short_press: + cmd_id: CURSOR_RIGHT + - button: DPAD_UP + short_press: + cmd_id: CURSOR_UP '401': $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/remotes/{entityId}/buttons/{buttonId}': + /remotes/{entityId}/buttons/{buttonId}: get: tags: - remotes @@ -5758,12 +6077,14 @@ paths: application/json: schema: $ref: '#/components/schemas/DeviceButtonMapping' - example: - button: DPAD_DOWN - short_press: - cmd_id: HOME - long_press: - cmd_id: MENU + examples: + default: + value: + button: DPAD_DOWN + short_press: + cmd_id: HOME + long_press: + cmd_id: MENU '400': $ref: '#/components/responses/Err400BadRequest' '401': @@ -5819,10 +6140,12 @@ paths: application/json: schema: $ref: '#/components/schemas/DeviceButtonMapping' - example: - button: DPAD_DOWN - short_press: - cmd_id: HOME + examples: + default: + value: + button: DPAD_DOWN + short_press: + cmd_id: HOME '400': $ref: '#/components/responses/Err400BadRequest' '401': @@ -5848,19 +6171,21 @@ paths: application/json: schema: $ref: '#/components/schemas/DeviceButtonMappings' - example: - - button: DPAD_MIDDLE - short_press: - cmd_id: CURSOR_ENTER - - button: DPAD_LEFT - short_press: - cmd_id: CURSOR_LEFT - - button: DPAD_RIGHT - short_press: - cmd_id: CURSOR_RIGHT - - button: DPAD_UP - short_press: - cmd_id: CURSOR_UP + examples: + default: + value: + - button: DPAD_MIDDLE + short_press: + cmd_id: CURSOR_ENTER + - button: DPAD_LEFT + short_press: + cmd_id: CURSOR_LEFT + - button: DPAD_RIGHT + short_press: + cmd_id: CURSOR_RIGHT + - button: DPAD_UP + short_press: + cmd_id: CURSOR_UP '400': $ref: '#/components/responses/Err400BadRequest' '401': @@ -5869,7 +6194,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/remotes/{entityId}/buttons/{buttonId}/{buttonPress}': + /remotes/{entityId}/buttons/{buttonId}/{buttonPress}: get: tags: - remotes @@ -5886,8 +6211,10 @@ paths: application/json: schema: $ref: '#/components/schemas/EntityCommand' - example: - cmd_id: HOME + examples: + default: + value: + cmd_id: HOME '400': $ref: '#/components/responses/Err400BadRequest' '401': @@ -5916,7 +6243,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/remotes/{entityId}/ui': + /remotes/{entityId}/ui: get: tags: - remotes @@ -5965,7 +6292,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/remotes/{entityId}/ui/pages': + /remotes/{entityId}/ui/pages: post: tags: - remotes @@ -6091,7 +6418,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/remotes/{entityId}/ui/pages/{pageId}': + /remotes/{entityId}/ui/pages/{pageId}: get: tags: - remotes @@ -6207,11 +6534,11 @@ paths: Profile with an icon: value: name: My profile - icon: 'uc:star' + icon: uc:star Restricted profile: value: name: Guests - icon: 'uc:lock' + icon: uc:lock restricted: true required: true responses: @@ -6307,7 +6634,7 @@ paths: $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/profiles/{profileId}': + /profiles/{profileId}: get: tags: - profiles @@ -6386,7 +6713,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/profiles/{profileId}/pages': + /profiles/{profileId}/pages: post: tags: - profiles @@ -6415,7 +6742,7 @@ paths: - entity_id: switch1 - entity_id: mediaplayer1 - entity_id: blind1 - - group_id: 'def:g2' + - group_id: def:g2 required: true responses: '201': @@ -6476,7 +6803,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/profiles/{profileId}/pages/{pageId}': + /profiles/{profileId}/pages/{pageId}: get: tags: - profiles @@ -6522,7 +6849,7 @@ paths: value: items: - entity_id: mediaplayer1 - - group_id: 'def:g2' + - group_id: def:g2 - entity_id: blind1 - entity_id: switch1 required: true @@ -6562,7 +6889,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/profiles/{profileId}/groups': + /profiles/{profileId}/groups: post: tags: - profiles @@ -6636,7 +6963,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/profiles/{profileId}/groups/{groupId}': + /profiles/{profileId}/groups/{groupId}: get: tags: - profiles @@ -6753,7 +7080,7 @@ paths: get: tags: - cfg - summary: "\U0001F9EA Get Bluetooth settings." + summary: 🧪 Get Bluetooth settings. description: | Retrieve Bluetooth settings @@ -6781,7 +7108,7 @@ paths: patch: tags: - cfg - summary: "\U0001F9EA Modify Bluetooth settings." + summary: 🧪 Modify Bluetooth settings. description: | Change one or multiple Bluetooth settings. The remote must be restarted after a configuration change. @@ -6826,34 +7153,36 @@ paths: application/json: schema: $ref: '#/components/schemas/BtDeviceProfileInfos' - example: - - id: default - name: - en: Default - version: 1 - peripherals: - keyboard: true - mouse: true - - id: generic_android - name: - en: Generic Android - version: 1 - peripherals: - keyboard: true - mouse: true - - id: my_device - name: - en: My custom device - user_profile: true - version: 2 - peripherals: - keyboard: true - mouse: false - '401': - $ref: '#/components/responses/Err401Unauthorized' - '403': - $ref: '#/components/responses/Err403Forbidden' - '/cfg/bt/profiles/{id}': + examples: + default: + value: + - id: default + name: + en: Default + version: 1 + peripherals: + keyboard: true + mouse: true + - id: generic_android + name: + en: Generic Android + version: 1 + peripherals: + keyboard: true + mouse: true + - id: my_device + name: + en: My custom device + user_profile: true + version: 2 + peripherals: + keyboard: true + mouse: false + '401': + $ref: '#/components/responses/Err401Unauthorized' + '403': + $ref: '#/components/responses/Err403Forbidden' + /cfg/bt/profiles/{id}: get: tags: - cfg @@ -7034,10 +7363,12 @@ paths: type: object additionalProperties: type: string - example: - cool: uE91E - heat: uE91F - home: uE900 + examples: + default: + value: + cool: uE91E + heat: uE91F + home: uE900 '401': $ref: '#/components/responses/Err401Unauthorized' '403': @@ -7131,96 +7462,98 @@ paths: type: array items: $ref: '#/components/schemas/EntityCommandMetadata' - example: - - id: button.press - cmd_id: press - name: - en: Press - de: Betätigen - - id: switch.on - cmd_id: 'on' - name: - en: 'On' - de: Ein - - id: switch.off - cmd_id: 'off' - name: - en: 'Off' - de: Aus - - id: switch.toggle - cmd_id: toggle - name: - en: Toggle - de: Umschalten - - id: light.on - cmd_id: 'on' - name: - en: Turn on - de: Einschalten - - id: light.off - cmd_id: 'off' - name: - en: Turn off - de: Ausschalten - - id: light.toggle - cmd_id: toggle - name: - en: Toggle state - de: Umschalten - - id: light.dim - cmd_id: 'on' - name: - en: Set brightness - de: Setze Helligkeit - params: - - name: - en: brightness - de: Helligkeit - param: brightness - type: int - min: 0 - max: 100 - step: 1 - unit: '%' - - id: light.color_temperature - cmd_id: 'on' - name: - en: Set color temperature - de: Setze Farbtemperatur - params: - - name: - en: Color temperature - de: Farbtemperatur - param: color_temperature - type: int - min: 0 - max: 100 - step: 1 - unit: '%' - - id: light.color - cmd_id: 'on' - name: - en: Set color - de: Setze Farbe - params: - - name: - en: Hue - de: Farbton - param: hue - type: int - min: 0 - max: 360 - step: 1 - unit: ° - - name: - en: saturation - de: Farbsättigung - param: saturation - type: int - min: 0 - max: 100 - step: 1 - unit: '%' + examples: + default: + value: + - id: button.press + cmd_id: press + name: + en: Press + de: Betätigen + - id: switch.on + cmd_id: 'on' + name: + en: 'On' + de: Ein + - id: switch.off + cmd_id: 'off' + name: + en: 'Off' + de: Aus + - id: switch.toggle + cmd_id: toggle + name: + en: Toggle + de: Umschalten + - id: light.on + cmd_id: 'on' + name: + en: Turn on + de: Einschalten + - id: light.off + cmd_id: 'off' + name: + en: Turn off + de: Ausschalten + - id: light.toggle + cmd_id: toggle + name: + en: Toggle state + de: Umschalten + - id: light.dim + cmd_id: 'on' + name: + en: Set brightness + de: Setze Helligkeit + params: + - name: + en: brightness + de: Helligkeit + param: brightness + type: number + min: 0 + max: 100 + step: 1 + unit: '%' + - id: light.color_temperature + cmd_id: 'on' + name: + en: Set color temperature + de: Setze Farbtemperatur + params: + - name: + en: Color temperature + de: Farbtemperatur + param: color_temperature + type: number + min: 0 + max: 100 + step: 1 + unit: '%' + - id: light.color + cmd_id: 'on' + name: + en: Set color + de: Setze Farbe + params: + - name: + en: Hue + de: Farbton + param: hue + type: number + min: 0 + max: 360 + step: 1 + unit: ° + - name: + en: saturation + de: Farbsättigung + param: saturation + type: number + min: 0 + max: 100 + step: 1 + unit: '%' '401': $ref: '#/components/responses/Err401Unauthorized' '403': @@ -7424,24 +7757,26 @@ paths: required: - code - name_en - example: - - code: CH - name_de: Schweiz - name_en: Switzerland - name_fr: Suisse - name_it: Svizzera - - code: DE - name_de: Deutschland - name_en: Germany - - code: DK - name_dk: Danmark - name_en: Denmark - - code: HU - name_en: Hungary - name_hu: Magyarország - - code: NL - name_en: Netherlands - name_nl: Nederland + examples: + default: + value: + - code: CH + name_de: Schweiz + name_en: Switzerland + name_fr: Suisse + name_it: Svizzera + - code: DE + name_de: Deutschland + name_en: Germany + - code: DK + name_dk: Danmark + name_en: Denmark + - code: HU + name_en: Hungary + name_hu: Magyarország + - code: NL + name_en: Netherlands + name_nl: Nederland '401': $ref: '#/components/responses/Err401Unauthorized' '403': @@ -7480,23 +7815,25 @@ paths: required: - version - translations - example: - version: default - translations: - - code: da_DK - name: Dansk - - code: de_DE - name: Deutsch - - code: de_CH - name: Schwiizertüütsch - - code: fr_CH - name: Français (Suisse) - - code: it_CH - name: Italiano (Svizzera) - - code: hu_HU - name: Magyar - - code: nl_NL - name: Nederlands + examples: + default: + value: + version: default + translations: + - code: da_DK + name: Dansk + - code: de_DE + name: Deutsch + - code: de_CH + name: Schwiizertüütsch + - code: fr_CH + name: Français (Suisse) + - code: it_CH + name: Italiano (Svizzera) + - code: hu_HU + name: Magyar + - code: nl_NL + name: Nederlands '401': $ref: '#/components/responses/Err401Unauthorized' '403': @@ -7538,7 +7875,7 @@ paths: band: auto ipv4_type: DHCP bt: - address: 'AA:BB:CC:DD:EE:FF' + address: AA:BB:CC:DD:EE:FF '401': $ref: '#/components/responses/Err401Unauthorized' '403': @@ -7709,6 +8046,9 @@ paths: examples: Default configuration: value: + bands: + - a + - b band: auto '401': $ref: '#/components/responses/Err401Unauthorized' @@ -7876,11 +8216,13 @@ paths: application/json: schema: $ref: '#/components/schemas/CfgSoftwareUpdate' - example: - check_for_updates: true - auto_update: false - ota_window_start: '02:15:00' - ota_window_end: '05:00:00' + examples: + default: + value: + check_for_updates: true + auto_update: false + ota_window_start: '02:15:00' + ota_window_end: '05:00:00' required: true responses: '200': @@ -8216,24 +8558,26 @@ paths: application/json: schema: $ref: '#/components/schemas/DockDiscoveryStatus' - example: - active: true - docks: - - id: UC-Dock-E831CDD012A8 - configured: false - friendly_name: Living room - address: '192.168.1.106:946' - model: UCD2 - version: 0.1.0 - discovery_type: NET - timestamp: '2022-11-07T07:46:04.370629Z' - - id: sim.1 - configured: false - friendly_name: Simulated dock - address: '127.0.0.1:946' - version: 0.1.2 - discovery_type: NET - timestamp: '2022-11-07T07:46:05.245759Z' + examples: + default: + value: + active: true + docks: + - id: UC-Dock-E831CDD012A8 + configured: false + friendly_name: Living room + address: 192.168.1.106:946 + model: UCD2 + version: 0.1.0 + discovery_type: NET + timestamp: '2022-11-07T07:46:04.370629Z' + - id: sim.1 + configured: false + friendly_name: Simulated dock + address: 127.0.0.1:946 + version: 0.1.2 + discovery_type: NET + timestamp: '2022-11-07T07:46:05.245759Z' '401': $ref: '#/components/responses/Err401Unauthorized' '403': @@ -8283,7 +8627,7 @@ paths: default: true - name: new in: query - description: 'Only return new devices, filter out already configured docks.' + description: Only return new devices, filter out already configured docks. required: false schema: type: boolean @@ -8322,7 +8666,7 @@ paths: $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/docks/discover/{dockId}': + /docks/discover/{dockId}: get: tags: - dock @@ -8480,7 +8824,7 @@ paths: discovery: id: UC-Dock-E831CDD012A8 friendly_name: Living room - address: '192.168.1.106:946' + address: 192.168.1.106:946 model: UCD2 version: 0.1.0 discovery_type: NET @@ -8507,11 +8851,13 @@ paths: application/json: schema: $ref: '#/components/schemas/DockSetupInfo' - example: - id: UC-Dock-E831CDD012A8 - name: Living room - discovery_type: NET - state: NEW + examples: + default: + value: + id: UC-Dock-E831CDD012A8 + name: Living room + discovery_type: NET + state: NEW '400': $ref: '#/components/responses/Err400BadRequest' '401': @@ -8536,7 +8882,7 @@ paths: $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/docks/setup/{dockId}': + /docks/setup/{dockId}: get: tags: - dock @@ -8561,12 +8907,14 @@ paths: application/json: schema: $ref: '#/components/schemas/DockSetupInfo' - example: - id: UC-Dock-E831CDD012A8 - name: Living room - model: UCD2_VIRTUAL - discovery_type: NET - state: OK + examples: + default: + value: + id: UC-Dock-E831CDD012A8 + name: Living room + model: UCD2_VIRTUAL + discovery_type: NET + state: OK '400': $ref: '#/components/responses/Err400BadRequest' '401': @@ -8594,13 +8942,15 @@ paths: application/json: schema: $ref: '#/components/schemas/DockSetup' - example: - name: Living room - token: '123' - description: Setup test - wifi: - ssid: My Network - password: 0123456789 + examples: + default: + value: + name: Living room + token: '123' + description: Setup test + wifi: + ssid: My Network + password: '0123456789' required: true responses: '200': @@ -8609,12 +8959,14 @@ paths: application/json: schema: $ref: '#/components/schemas/DockSetupInfo' - example: - id: UC-Dock-E831CDD012A8 - name: Living room - model: UCD2 - discovery_type: NET - state: CONFIGURING + examples: + default: + value: + id: UC-Dock-E831CDD012A8 + name: Living room + model: UCD2 + discovery_type: NET + state: CONFIGURING '400': $ref: '#/components/responses/Err400BadRequest' '401': @@ -8648,7 +9000,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/docks/devices/{dockId}': + /docks/devices/{dockId}: get: tags: - dock @@ -8665,18 +9017,20 @@ paths: application/json: schema: $ref: '#/components/schemas/DockConfiguration' - example: - dock_id: UC-Dock-E831CDD012A8 - name: Living room - resolved_ws_url: 'ws://192.168.1.23:946' - active: true - model: UCD2 - revision: '5.4' - led_brightness: 88 - state: CONNECTED - version: 0.9.2 - learning_active: false - description: Setup test + examples: + default: + value: + dock_id: UC-Dock-E831CDD012A8 + name: Living room + resolved_ws_url: ws://192.168.1.23:946 + active: true + model: UCD2 + revision: '5.4' + led_brightness: 88 + state: ACTIVE + version: 0.9.2 + learning_active: false + description: Setup test '401': $ref: '#/components/responses/Err401Unauthorized' '403': @@ -8700,7 +9054,7 @@ paths: parameters: - $ref: '#/components/parameters/dock_id' requestBody: - description: 'Fields to update, omit the ones without change.' + description: Fields to update, omit the ones without change. content: application/json: schema: @@ -8770,7 +9124,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/docks/devices/{dockId}/command': + /docks/devices/{dockId}/command: post: tags: - dock @@ -8846,7 +9200,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/docks/devices/{dockId}/update': + /docks/devices/{dockId}/update: get: tags: - dock @@ -8954,7 +9308,7 @@ paths: delete: tags: - dock - summary: "\U0001F6A7 Abort the dock firmware update." + summary: 🚧 Abort the dock firmware update. description: | Stop the firmware update process at the next possible operation and remove the update process information. @@ -8971,7 +9325,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/docks/devices/{dockId}/update/{id}': + /docks/devices/{dockId}/update/{id}: get: tags: - dock @@ -9004,7 +9358,7 @@ paths: $ref: '#/components/responses/Err404NotFound' '503': $ref: '#/components/responses/Err503ServiceUnavailable' - '/docks/devices/{dockId}/ir/send': + /docks/devices/{dockId}/ir/send: get: tags: - dock @@ -9039,18 +9393,18 @@ paths: type: boolean - name: pronto in: query - description: 'Pronto IR code, values separated by comma' + description: Pronto IR code, values separated by comma required: false schema: type: string - pattern: '^[a-fA-F0-9]{4}(,[a-fA-F0-9]{4}){3,}$' + pattern: ^[a-fA-F0-9]{4}(,[a-fA-F0-9]{4}){3,}$ - name: hex in: query description: Hex IR code required: false schema: type: string - pattern: '^[\d]{1,3};0x[a-fA-F0-9]{1,16};[\d]{1,2};[\d]{1,2}$' + pattern: ^[\d]{1,3};0x[a-fA-F0-9]{1,16};[\d]{1,2};[\d]{1,2}$ - name: repeat in: query description: | @@ -9107,13 +9461,13 @@ paths: description: External IR blaster 2 type: boolean pronto: - description: 'Pronto IR code, values separated by space or comma' + description: Pronto IR code, values separated by space or comma type: string - pattern: '^0000((, )[a-fA-F0-9]{4}){5,}$' + pattern: ^0000((, )[a-fA-F0-9]{4}){5,}$ hex: description: Hex IR code type: string - pattern: '^[\d]{1,3};0x[a-fA-F0-9]{1,16};[\d]{1,2};[\d]{1,2}$' + pattern: ^[\d]{1,3};0x[a-fA-F0-9]{1,16};[\d]{1,2};[\d]{1,2}$ repeat: description: | Optional repeat value for sending continuous IR repeat signals (depending on IR protocol). @@ -9131,11 +9485,11 @@ paths: $ref: '#/components/responses/Err403Forbidden' '404': $ref: '#/components/responses/Err404NotFound' - '/docks/devices/{dockId}/ports': + /docks/devices/{dockId}/ports: get: tags: - dock - summary: "\U0001F9EA Get all external port configurations." + summary: 🧪 Get all external port configurations. description: | This operation returns the configuration of all external ports. A connection to the dock must have been established before, to retrieve the current configuration. @@ -9162,7 +9516,7 @@ paths: delete: tags: - dock - summary: "\U0001F9EA Reset all external ports to their default mode." + summary: 🧪 Reset all external ports to their default mode. description: | This feature only works on supported docks. All external dock ports are configured to their default operation mode: - Dock Two: output ports cannot be reconfigured. This operation has no effect. @@ -9183,11 +9537,11 @@ paths: $ref: '#/components/responses/Err404NotFound' '503': $ref: '#/components/responses/Err503ServiceUnavailable' - '/docks/devices/{dockId}/ports/{portId}': + /docks/devices/{dockId}/ports/{portId}: get: tags: - dock - summary: "\U0001F9EA Get external dock port configuration." + summary: 🧪 Get external dock port configuration. description: | This operation returns the configuration of a given port. A connection to the dock must have been established before, to retrieve the current configuration. @@ -9215,8 +9569,32 @@ paths: patch: tags: - dock - summary: "\U0001F9EA Configure an external dock port." - description: "An external dock port is usually a 3.5 mm jack port for connecting IR-extenders and -blasters. Depending on the dock\nmodel, other operation modes are also supported. Use the `GET` operation to retrieve supported modes.\n\nThis feature only works on supported docks:\n- Dock Two: output ports cannot be reconfigured and this operation is not supported.\n- Dock 3: multiple modes are supported:\n - `NONE`: The output port is disabled and has no function.\n - `AUTO`: The official IR-Blaster and IR-emitter are automatically detected.\n - `IR_BLASTER`: Infrared-blaster with a stereo-plug.\n - `IR_EMITTER_MONO_PLUG`: Infrared-emitter from Dock Two with a mono-plug.\n - `IR_EMITTER_STEREO_PLUG`: Infrared-emitter from Dock 3 with a stereo-plug.\n - `TRIGGER_5V`: \U0001F6A7 trigger support is not yet implemented.\n - `RS232`: \U0001F6A7 RS232 communication is not yet implemented.\n\nThe dock must be connected to the Remote to change its configuration. A manually created dock will show no supported\nmodes until a connection has been established and the supported modes retrieved.\n\nOnce a port has been reconfigured, the WebSocket event `dock_port_mode` is sent in the `docks` channel.\n\nResponse codes:\n- `201`: port configuration has been accepted. Depending on the mode, this operation might take a few seconds.\n- `400`: bad request, for example an unsupported or unknown mode.\n- `404`: either the dock identifier or port number is not valid.\n- `503`: dock connection is not available, configuration cannot be changed at the moment.\n" + summary: 🧪 Configure an external dock port. + description: | + An external dock port is usually a 3.5 mm jack port for connecting IR-extenders and -blasters. Depending on the dock + model, other operation modes are also supported. Use the `GET` operation to retrieve supported modes. + + This feature only works on supported docks: + - Dock Two: output ports cannot be reconfigured and this operation is not supported. + - Dock 3: multiple modes are supported: + - `NONE`: The output port is disabled and has no function. + - `AUTO`: The official IR-Blaster and IR-emitter are automatically detected. + - `IR_BLASTER`: Infrared-blaster with a stereo-plug. + - `IR_EMITTER_MONO_PLUG`: Infrared-emitter from Dock Two with a mono-plug. + - `IR_EMITTER_STEREO_PLUG`: Infrared-emitter from Dock 3 with a stereo-plug. + - `TRIGGER_5V`: 🚧 trigger support is not yet implemented. + - `RS232`: 🚧 RS232 communication is not yet implemented. + + The dock must be connected to the Remote to change its configuration. A manually created dock will show no supported + modes until a connection has been established and the supported modes retrieved. + + Once a port has been reconfigured, the WebSocket event `dock_port_mode` is sent in the `docks` channel. + + Response codes: + - `201`: port configuration has been accepted. Depending on the mode, this operation might take a few seconds. + - `400`: bad request, for example an unsupported or unknown mode. + - `404`: either the dock identifier or port number is not valid. + - `503`: dock connection is not available, configuration cannot be changed at the moment. operationId: updateDockPortConfiguration parameters: - $ref: '#/components/parameters/dock_id' @@ -9248,7 +9626,7 @@ paths: delete: tags: - dock - summary: "\U0001F9EA Reset external port configuration to its default mode." + summary: 🧪 Reset external port configuration to its default mode. description: | This feature only works on supported docks. The specified dock port is configured to its default operation mode: - Dock Two: output ports cannot be reconfigured. This operation has no effect. @@ -9284,7 +9662,7 @@ paths: tags: - system summary: Get system information. - description: 'Get hardware information about the device like serial number, model number and hardware revision.' + description: Get hardware information about the device like serial number, model number and hardware revision. operationId: getSystemInfo responses: '200': @@ -9456,7 +9834,7 @@ paths: get: tags: - system - summary: "\U0001F477 Get information about available system backup snapshots." + summary: 👷 Get information about available system backup snapshots. description: | _Work in progress, might still change!_ @@ -9478,7 +9856,7 @@ paths: post: tags: - system - summary: "\U0001F477 Create a new system backup snapshot." + summary: 👷 Create a new system backup snapshot. description: | _Work in progress, might still change!_ @@ -9509,7 +9887,7 @@ paths: delete: tags: - system - summary: "\U0001F477 Remove all system backups." + summary: 👷 Remove all system backups. description: | _Work in progress, might still change!_ @@ -9526,11 +9904,11 @@ paths: $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/system/backup/snapshots/{id}': + /system/backup/snapshots/{id}: get: tags: - system - summary: "\U0001F477 Get information about a system backup snapshot or download archive." + summary: 👷 Get information about a system backup snapshot or download archive. description: | _Work in progress, might still change!_ @@ -9568,7 +9946,7 @@ paths: put: tags: - system - summary: "\U0001F477 Restore a system backup snapshot." + summary: 👷 Restore a system backup snapshot. description: | _Work in progress, might still change!_ @@ -9606,7 +9984,7 @@ paths: delete: tags: - system - summary: "\U0001F477 Remove a system backup snapshot." + summary: 👷 Remove a system backup snapshot. description: | _Work in progress, might still change!_ operationId: deleteBackupSnapshot @@ -9627,7 +10005,7 @@ paths: put: tags: - system - summary: "\U0001F9EA Perform a Bluetooth operation." + summary: 🧪 Perform a Bluetooth operation. description: | Change the Bluetooth controller power mode or clear all bonding information. @@ -9665,7 +10043,7 @@ paths: delete: tags: - system - summary: "\U0001F9EA Perform a Bluetooth subsystem reset." + summary: 🧪 Perform a Bluetooth subsystem reset. description: | A BT subsystem reset removes all bonding information and removes the BT-remote entity associations to BT connection profiles. @@ -9750,33 +10128,35 @@ paths: type: array items: $ref: '#/components/schemas/CustomInstall' - example: - - component: ui - installed: true - active: true - installation_date: '2023-07-24T09:57:33+02:00' - release: - name: - en: Remote UI - version: 0.27.10 - description: - en: Custom remote UI App for testing. - developer: - name: Unfolded Circle ApS - url: 'https://www.unfoldedcircle.com' - email: hello@unfoldedcircle.com - home_page: 'https://www.unfoldedcircle.com' - release_date: '2023-07-19' - requirements: - firmware_version: '>=0.13.0, <1.0.0' - - component: web_configurator - installed: false - active: false - '401': - $ref: '#/components/responses/Err401Unauthorized' - '403': - $ref: '#/components/responses/Err403Forbidden' - '/system/install/{customComponent}': + examples: + default: + value: + - component: ui + installed: true + active: true + installation_date: '2023-07-24T09:57:33+02:00' + release: + name: + en: Remote UI + version: 0.27.10 + description: + en: Custom remote UI App for testing. + developer: + name: Unfolded Circle ApS + url: https://www.unfoldedcircle.com + email: hello@unfoldedcircle.com + home_page: https://www.unfoldedcircle.com + release_date: '2023-07-19' + requirements: + firmware_version: '>=0.13.0, <1.0.0' + - component: web_configurator + installed: false + active: false + '401': + $ref: '#/components/responses/Err401Unauthorized' + '403': + $ref: '#/components/responses/Err403Forbidden' + /system/install/{customComponent}: get: tags: - system @@ -9985,7 +10365,7 @@ paths: default: 5 - name: s in: query - description: 'One or more service identifiers, separated by comma' + description: One or more service identifiers, separated by comma required: false schema: type: string @@ -10020,7 +10400,7 @@ paths: type: string - name: boot_ids in: query - description: 'One or more boot identifiers, separated by comma' + description: One or more boot identifiers, separated by comma required: false schema: type: string @@ -10032,10 +10412,12 @@ paths: text/plain: schema: type: string - example: | - 2023-07-27T09:11:44.584555+00:00 ui WARN A warning message - 2023-07-27T08:52:54.609843+00:00 ui INFO An information message - 2023-07-27T08:52:53.609143+00:00 ui DEBUG Application is starting + examples: + default: + value: | + 2023-07-27T09:11:44.584555+00:00 ui WARN A warning message + 2023-07-27T08:52:54.609843+00:00 ui INFO An information message + 2023-07-27T08:52:53.609143+00:00 ui DEBUG Application is starting application/json: schema: type: array @@ -10256,7 +10638,7 @@ paths: put: tags: - system - summary: "\U0001F477 Enable or disable wireless charging." + summary: 👷 Enable or disable wireless charging. description: | This operation is only supported on devices with wireless charging. operationId: updateBatteryCharger @@ -10352,7 +10734,7 @@ paths: $ref: '#/components/responses/Err401Unauthorized' '403': $ref: '#/components/responses/Err403Forbidden' - '/system/power/standby_inhibitors/{id}': + /system/power/standby_inhibitors/{id}: delete: tags: - system @@ -10388,7 +10770,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/AmbientLightResponse' + $ref: '#/components/schemas/AmbientLight' '401': $ref: '#/components/responses/Err401Unauthorized' '403': @@ -10439,7 +10821,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '503': $ref: '#/components/responses/Err503ServiceUnavailable' - '/system/update/{updateId}': + /system/update/{updateId}: post: tags: - system @@ -10765,7 +11147,7 @@ paths: $ref: '#/components/responses/Err403Forbidden' '503': $ref: '#/components/responses/Err503ServiceUnavailable' - '/system/wifi/networks/{wifiId}': + /system/wifi/networks/{wifiId}: get: tags: - system @@ -10874,136 +11256,49 @@ paths: $ref: '#/components/responses/Err503ServiceUnavailable' components: parameters: - api_key_id: - name: apiKeyId - in: path - description: API key identification - required: true - schema: - $ref: '#/components/schemas/ApiKeyId' - backup_id: - name: id - in: path - description: Backup snapshot identifier - required: true + active: + name: active + in: query + description: Filter by active flag + required: false schema: - type: string - button_id: - name: buttonId - in: path - description: Button identification. - required: true - schema: - $ref: '#/components/schemas/ButtonId' - button_press: - name: buttonPress - in: path - description: Button press type. - required: true - schema: - type: string - enum: - - short_press - - long_press - cmd_id: - name: cmdId - in: path - description: IR command identification. - required: true - schema: - $ref: '#/components/schemas/IrCodeKey' - custom_component: - name: customComponent - in: path - description: Custom system component. - required: true - schema: - $ref: '#/components/schemas/CustomComponent' - dock_id: - name: dockId - in: path - description: Dock identification - required: true - schema: - $ref: '#/components/schemas/DockId' - driver_id: - name: driverId - in: path - description: Integration driver identification - required: true - schema: - $ref: '#/components/schemas/DriverId' - emitter_id: - name: emitterId - in: path - description: Emitter device id. - required: true - schema: - $ref: '#/components/schemas/SimpleId' - entity_id: - name: entityId - in: path - description: Entity identification. - required: true - schema: - $ref: '#/components/schemas/EntityId' - group_id: - name: groupId - in: path - description: Group identification - required: true - schema: - $ref: '#/components/schemas/SimpleId' - integration_id: - name: intgId - in: path - description: Integration identification - required: true - schema: - $ref: '#/components/schemas/IntegrationId' - ir_key: - name: key - in: path - description: IR command key - required: true - schema: - $ref: '#/components/schemas/IrCodeKey' - page_id: - name: pageId - in: path - description: Page identification - required: true - schema: - $ref: '#/components/schemas/SimpleId' - port_id: - name: portId - in: path - description: Dock port number - required: true + type: boolean + page: + name: page + in: query + description: Current page number. 1-based. + required: false schema: type: integer + format: int32 + default: 1 minimum: 1 - profile_id: - name: profileId - in: path - description: Profile identification - required: true + limit: + name: limit + in: query + description: Limits the number of returned items. + required: false schema: - $ref: '#/components/schemas/SimpleId' - resource_id: - name: id + type: integer + format: int32 + default: 10 + minimum: 10 + maximum: 100 + multipleOf: 10 + api_key_id: + name: apiKeyId in: path - description: Resource identifier + description: API key identification required: true schema: - type: string - resource_type: + $ref: '#/components/schemas/ApiKeyId' + token_type: name: type - in: path - description: Resource type - required: true + in: query + description: Token type. + required: false schema: - $ref: '#/components/schemas/ResourceType' + $ref: '#/components/schemas/ExtTokenType' system: name: system in: path @@ -11011,28 +11306,50 @@ components: required: true schema: $ref: '#/components/schemas/ExternalSystemId' - token_id: + tokenId: name: tokenId in: path description: Access token identification required: true schema: $ref: '#/components/schemas/AccessTokenId' - wifi_id: - name: wifiId + resource_type_query: + name: type + in: query + description: Resource type. + required: false + schema: + $ref: '#/components/schemas/ResourceType' + resource_type: + name: type in: path - description: WiFi network identification + description: Resource type required: true schema: - type: integer - minimum: 0 - active: - name: active + $ref: '#/components/schemas/ResourceType' + query: + name: q in: query - description: Filter by active flag + description: Text search required: false schema: - type: boolean + type: string + minLength: 1 + maxLength: 50 + resource_id: + name: id + in: path + description: Resource identifier + required: true + schema: + type: string + driver_id: + name: driverId + in: path + description: Integration driver identification + required: true + schema: + $ref: '#/components/schemas/DriverId' enabled: name: enabled in: query @@ -11040,20 +11357,26 @@ components: required: false schema: type: boolean - entity_types: - name: entity_types + instantiable: + name: instantiable in: query - description: 'Filter by multiple entity types, separated by comma.' + description: | + Filter if a driver is instantiable or not: + - true = only consider drivers which allow new integration instances to be created from. Either single-device drivers + without an instance, or multi-device drivers. + - false = only drivers which allow no more instances + - NONE = any. required: false schema: - type: string - exclude: - name: exclude + type: boolean + single_device: + name: single_device in: query - description: 'Exclude entities from activity, macro, profile page and group identifiers, separated by comma.' + description: | + true = only consider single-device drivers, false = only multi-device drivers, NONE = all. required: false schema: - type: string + type: boolean has_instances: name: has_instances in: query @@ -11065,22 +11388,38 @@ components: required: false schema: type: boolean - instantiable: - name: instantiable + integration_id: + name: intgId + in: path + description: Integration identification + required: true + schema: + $ref: '#/components/schemas/IntegrationId' + entity_types: + name: entity_types in: query - description: | - Filter if a driver is instantiable or not: - - true = only consider drivers which allow new integration instances to be created from. Either single-device drivers - without an instance, or multi-device drivers. - - false = only drivers which allow no more instances - - NONE = any. + description: Filter by multiple entity types, separated by comma. required: false schema: - type: boolean - intg_ids: + type: string + entity_id: + name: entityId + in: path + description: Entity identification. + required: true + schema: + $ref: '#/components/schemas/EntityId' + integration_ids: name: intg_ids in: query - description: 'Filter by multiple integration identifiers, separated by comma.' + description: Filter by multiple integration identifiers, separated by comma. + required: false + schema: + type: string + exclude: + name: exclude + in: query + description: Exclude entities from activity, macro, profile page and group identifiers, separated by comma. required: false schema: type: string @@ -11098,39 +11437,108 @@ components: required: false schema: type: string - merge: - name: merge + stable_ids: + name: stable_ids in: query - description: Merge data. + description: Use stable media identifiers. required: false schema: type: boolean - query: - name: q - in: query - description: Text search - required: false + button_id: + name: buttonId + in: path + description: Button identification. + required: true schema: - type: string - minLength: 1 - maxLength: 50 - resource_type_query: - name: type - in: query - description: Resource type. - required: false + $ref: '#/components/schemas/ButtonId' + button_press: + name: buttonPress + in: path + description: Button press type. + required: true schema: - $ref: '#/components/schemas/ResourceType' - page: - name: page - in: query - description: Current page number. 1-based. - required: false + type: string + enum: + - short_press + - long_press + page_id: + name: pageId + in: path + description: Page identification + required: true + schema: + $ref: '#/components/schemas/SimpleId' + group_id: + name: groupId + in: path + description: Group identification + required: true + schema: + $ref: '#/components/schemas/SimpleId' + ir_key: + name: key + in: path + description: IR command key + required: true + schema: + $ref: '#/components/schemas/IrCodeKey' + emitter_id: + name: emitterId + in: path + description: Emitter device id. + required: true + schema: + $ref: '#/components/schemas/SimpleId' + cmd_id: + name: cmdId + in: path + description: IR command identification. + required: true + schema: + $ref: '#/components/schemas/IrCodeKey' + profile_id: + name: profileId + in: path + description: Profile identification + required: true + schema: + $ref: '#/components/schemas/SimpleId' + dock_id: + name: dockId + in: path + description: Dock identification + required: true + schema: + $ref: '#/components/schemas/DockId' + port_id: + name: portId + in: path + description: Dock port number + required: true schema: type: integer - format: int32 - default: 1 minimum: 1 + merge: + name: merge + in: query + description: Merge data. + required: false + schema: + type: boolean + backup_id: + name: id + in: path + description: Backup snapshot identifier + required: true + schema: + type: string + custom_component: + name: customComponent + in: path + description: Custom system component. + required: true + schema: + $ref: '#/components/schemas/CustomComponent' power_mode: name: power_mode in: query @@ -11138,521 +11546,202 @@ components: required: true schema: $ref: '#/components/schemas/PowerMode' - limit: - name: limit - in: query - description: Limits the number of returned items. - required: false + wifi_id: + name: wifiId + in: path + description: WiFi network identification + required: true schema: type: integer - format: int32 - default: 10 - minimum: 10 - maximum: 100 - multipleOf: 10 - single_device: - name: single_device - in: query - description: | - true = only consider single-device drivers, false = only multi-device drivers, NONE = all. - required: false - schema: - type: boolean - stable_ids: - name: stable_ids - in: query - description: Use stable media identifiers. - required: false - schema: - type: boolean + minimum: 0 + token_id: + $ref: '#/components/parameters/tokenId' + intg_ids: + $ref: '#/components/parameters/integration_ids' schemas: - AccessTokenId: - type: string - format: '^[a-zA-Z0-9\-_]+$' - minLength: 1 - maxLength: 36 - description: Unique token identifier. Usually a UUID. - Activities: - type: array - items: - $ref: '#/components/schemas/ActivityOverview' - Activity: - description: | - The activity entity executes a sequence of commands and at the end displays a user interface (similar to remote entity) - to the user. If the entity has an off sequence, it can be turned off. + VersionInfo: type: object - allOf: - - $ref: '#/components/schemas/Entity' - - properties: - entity_type: - type: string - enum: - - activity - features: - description: | - Supported features of the activity. If the activity has an `off` sequence, it supports the common `on_off` - feature, otherwise only `start`. - type: array - items: - $ref: '#/components/schemas/ActivityFeature' - options: - type: object - properties: - editable: - description: | - - `true` / property missing: activity was created by UC Remote and can be edited. - - `false`: activity was provided by an integration and cannot be edited. - type: boolean - default: true - activity_group: - description: | - Minimal activity group information to use in a user interface with it's friendly name and icon. - type: object - properties: - group_id: - $ref: '#/components/schemas/EntityId' - name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' - required: - - group_id - - name - prevent_sleep: - description: Prevent the device to go to sleep while activity is on. - type: boolean - ready_check: - description: | - Readiness check when turning the activity on or off. - Checks if entities in the on- or off-sequence are available before running the sequence. - type: boolean - default: true - touch_slider: - $ref: '#/components/schemas/TouchSliderUiCfg' - voice_assistant: - $ref: '#/components/schemas/VoiceAssistantUiCfg' - included_entities: - $ref: '#/components/schemas/IncludedEntities' - sequences: - $ref: '#/components/schemas/ActivitySequences' - button_mapping: - $ref: '#/components/schemas/DeviceButtonMappings' - user_interface: - $ref: '#/components/schemas/ActivityUserInterface' - attributes: - type: object - properties: - state: - $ref: '#/components/schemas/SequenceState' - required: - - options - - attributes - ActivityFeature: - description: | - Supported features of the activity. If the activity has an `off` sequence, it supports the common `on_off` - feature, otherwise only `start`. + properties: + model: + description: | + Short model identifier of the remote (UCR2 for Remote Two, UCR3 for Remote 3). + type: string + device_name: + description: Custom name of the remote + type: string + hostname: + description: Hostname of the remote + type: string + address: + description: MAC address of the remote + type: string + api: + description: API version + type: string + core: + description: Core service version + type: string + ui: + description: Frontend app version + type: string + os: + description: Operating system version + type: string + integrations: + description: Versions of the available integrations. Map of (integration_name, version). + type: object + additionalProperties: + type: string + HealthStatus: type: string enum: - - on_off - - start - ActivityId: - type: string - format: '^[a-zA-Z0-9\-_]+$' - minLength: 1 - maxLength: 36 - description: Activity identifier - ActivityOverview: - description: | - The activity entity executes a sequence of commands and at the end displays a user interface (similar to remote entity) - to the user. If the entity has an off sequence, it can be turned off. + - Healthy + - Degraded + - Unhealthy + ApiResponse: type: object - allOf: - - $ref: '#/components/schemas/Entity' - - properties: - entity_type: - type: string - enum: - - activity - features: - description: | - Supported features of the activity. If the activity has an `off` sequence, it supports the common `on_off` - feature, otherwise only `start`. - type: array - items: - $ref: '#/components/schemas/ActivityFeature' - options: - type: object - properties: - editable: - description: | - - `true` / property missing: activity was created by UC Remote and can be edited. - - `false`: activity was provided by an integration and cannot be edited. - type: boolean - default: true - activity_group: - $ref: '#/components/schemas/EntityId' - ActivityRequest: - description: | - Dedicated request object to create a new activity. - type: object - allOf: - - properties: - name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' - description: - $ref: '#/components/schemas/LanguageText' - - oneOf: - - type: object - properties: - clone_from: - $ref: '#/components/schemas/EntityId' - required: - - clone_from - - type: object - properties: - options: - type: object - properties: - entity_ids: - type: array - items: - $ref: '#/components/schemas/EntityId' - required: - - entity_ids - required: - - name - ActivitySequences: + properties: + code: + type: string + description: Status code + message: + type: string + description: Status message describing the result or error. This message is intended for error analysis and should not directly shown to the end user. + LoginRequest: type: object properties: - 'on': - $ref: '#/components/schemas/CommandSequence' - 'off': - $ref: '#/components/schemas/CommandSequence' - ActivityUpdate: - description: | - Dedicated request object to update an existing activity. - All root properties are optional and only the provided objects are updated in the activity. Omitted objects are - ignored and not deleted from the activity. - - The `entity_ids` object must be managed by the client and is persisted when updating an activity. - - Notes: - - Entities can be included in `entity_ids` without being used in `sequences`. - This allows to edit the activity in multiple sessions without having to reselect the desired entities. - - Every referenced entity in `sequences` must be included in `entity_ids`, otherwise the activity cannot be saved. - - If the client removes a configured entity from the system which is included in an activity, it must make sure to - also remove all references in the activity. See `IncludedEntity.available` property in the included entities - object when retrieving an activity. - - Remote 3: The `touch_slider` configuration requires an entity included in `entity_ids`. + username: + type: string + password: + type: string + required: + - username + - password + examples: + - username: admin + password: '1234' + FieldValidationError: type: object properties: - name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' - description: - $ref: '#/components/schemas/LanguageText' - options: + code: + description: | + Validation error code. This can be a custom code or one of the common pre-defined codes: + - `LENGTH`: String is either too short or too long. + - `RANGE`: Number is not in valid range. + - `REGEX`: Regex validation failed. + - `INVALID_FORMAT`: value is in an invalid format. + type: string + message: + description: Validation rule message. + type: string + params: + description: Optional code related parameters. E.g. `min`, `max` for string-length or number-range validation. type: object - properties: - prevent_sleep: - description: Prevent the device to go to sleep while activity is on. - type: boolean - ready_check: - description: | - Readiness check when turning the activity on or off. - Checks if entities in the on- or off-sequence are available before running the sequence. - type: boolean - touch_slider: - $ref: '#/components/schemas/TouchSliderUiCfg' - voice_assistant: - $ref: '#/components/schemas/VoiceAssistantUiCfg' - entity_ids: - type: array - items: - $ref: '#/components/schemas/EntityId' - sequences: - $ref: '#/components/schemas/ActivitySequences' - ActivityUserInterface: + required: + - message + ValidationError: type: object properties: - pages: + field: + description: Field identifier with an invalid value. + type: string + field_errors: + description: | + Optional field validation error descriptions. A field can have multiple validation rules with an error. type: array items: - $ref: '#/components/schemas/ActivityUserInterfacePage' - ActivityUserInterfacePage: + $ref: '#/components/schemas/FieldValidationError' + required: + - field + ValidationErrorResponse: type: object properties: - page_id: - $ref: '#/components/schemas/SimpleId' - name: - description: Optional page name + code: type: string - grid: - $ref: '#/components/schemas/DeviceButtonLayout/properties/grid' - items: + description: Error code + message: + type: string + description: Message describing the validation error. This message is intended for error analysis and should not directly shown to the end user. + errors: + description: Optional validation errors type: array items: - $ref: '#/components/schemas/UserInterfaceItem' - required: - - page_id - - grid - - items - ActivityUserInterfacePageUpdate: + $ref: '#/components/schemas/ValidationError' + ApiKeyId: + type: string + format: ^[a-zA-Z0-9\-_]+$ + minLength: 1 + maxLength: 36 + description: Unique key identifier. Usually a UUID. + ApiKeyName: + type: string + minLength: 1 + maxLength: 50 + description: Friendly API key name to show in the app + ScopeName: + type: string + format: ^[a-zA-Z\-:]+$ + minLength: 1 + maxLength: 36 + description: Permission scope name + Description: + type: string + maxLength: 255 + description: Optional description + ApiKey: type: object properties: + key_id: + $ref: '#/components/schemas/ApiKeyId' name: - description: Optional page name + $ref: '#/components/schemas/ApiKeyName' + prefix: + description: Prefix of the API key for identification purposes. type: string - grid: - $ref: '#/components/schemas/DeviceButtonLayout/properties/grid' - items: - description: | - Updated user interface items. An empty array will REMOVE all items, if the property is omitted the existing - configuration is not changed. + active: + type: boolean + description: Only activated keys are valid for API access. + valid_to: + type: string + format: date-time + description: Optional expiration timestamp. If not set, the API key is valid until revoked. + scopes: type: array items: - $ref: '#/components/schemas/UserInterfaceItem' - ActivityGroup: - description: | - An activity group creates a dependency between multiple activities. Switching between activities will consider - the current state of the included entities and only turn-on or -off the required entities. + $ref: '#/components/schemas/ScopeName' + description: + $ref: '#/components/schemas/Description' + creation_date: + type: string + format: date-time + ApiKeys: + type: array + items: + $ref: '#/components/schemas/ApiKey' + ApiKeyRequest: type: object properties: - group_id: - $ref: '#/components/schemas/EntityId' name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' - description: - $ref: '#/components/schemas/LanguageText' - options: - $ref: '#/components/schemas/ActivityGroupOptions' - activities: - description: Included activities in the group. + $ref: '#/components/schemas/ApiKeyName' + scopes: type: array items: - $ref: '#/components/schemas/IncludedActivity' - required: - - group_id - - name - - options - - activities - ActivityGroups: - type: array - items: - $ref: '#/components/schemas/ActivityGroupOverview' - ActivityGroupState: - description: | - - `OFF`: No included activity is running. - - `ACTIVE`: An included activity is running. - - `RUNNING`: An included activity is currently running, e.g. either switching activities, or turning off. - - `ERROR`: An included activity is in an error state. - type: string - enum: - - 'OFF' - - ACTIVE - - RUNNING - - ERROR - ActivityGroupOverview: - description: | - Minimal activity group object intended for an overview page, which is returned when retrieving all activities. - type: object - properties: - group_id: - $ref: '#/components/schemas/EntityId' - name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' - activity_count: - description: Number of included activities. - type: integer - state: - $ref: '#/components/schemas/ActivityGroupState' - required: - - group_id - - name - - activity_count - ActivityGroupUpdate: - description: | - Dedicated request object to update an existing activity group. - All root properties are optional and only the provided objects are updated in the activity group. Omitted objects are - ignored and not deleted from the activity group. - - Referenced activities must exist, an empty `activity_ids` array will remove all included activities from the group. - type: object - properties: - name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' - description: - $ref: '#/components/schemas/LanguageText' - options: - $ref: '#/components/schemas/ActivityGroupOptions' - activity_ids: - description: Entity identifiers of included activities in group. - type: array - items: - $ref: '#/components/schemas/EntityId' - IncludedActivity: - description: | - Minimal activity object to show the activity in a user interface with it's friendly name and icon. - type: object - properties: - entity_id: - $ref: '#/components/schemas/EntityId' - name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' - state: - $ref: '#/components/schemas/SequenceState' - required: - - entity_id - - name - SequenceState: - description: | - State of an Activity or Macro sequence: - - `RUNNING`: Sequence is currently running - - `COMPLETED`: Final state for a macro - - `ON`: Final activity state for the `on` sequence - - `OFF`: Final activity state for the `off` sequence - - `STOPPED`: The sequence was aborted with a stop request - - `TIMEOUT`: The sequence timed out and was aborted - - `ERROR`: There was an error running the sequence and did not complete - type: string - enum: - - RUNNING - - COMPLETED - - 'ON' - - 'OFF' - - STOPPED - - TIMEOUT - - ERROR - ActivityGroupOptions: - description: "\U0001F477Not yet finalized!\n\nActivity group specific options, e.g. how delays are handled when switching between activities.\n" - type: object - properties: - remove_turn_on_delays: - $ref: '#/components/schemas/RemoveTurnOnDelays' - turn_off_unused_entities: - $ref: '#/components/schemas/TurnOffUnusedEntities' - RemoveTurnOnDelays: - description: | - - `previous_cmd_skipped`: Only remove delay steps if the previous step is skipped, because the entity is in a - power-on state. - - `between_skipped_cmds`: Only remove delay steps if the previous and next power-on steps are skipped, because - the entity is already in a power-on state. - - `never`: Never remove delay steps in the on-sequence of the new activity. - type: string - enum: - - previous_cmd_skipped - - between_skipped_cmds - - never - TurnOffUnusedEntities: - description: | - - `always`: Always turn off unused entities in the previous activity. - All included entities are considered, not just the ones used in the on-sequence of the new activity. - - `in_off_sequence`: Only turn off unused entities which are included in the off-sequence of the previous activity. - - `run_off_sequence`: Run the original off-sequence of the old activity and dynamically filter out power-off commands. - All power-off commands from entities used in the new activity's power-on sequence will be filtered out. - - `never`: Never turn off entities in the previous activity. - type: string - enum: - - always - - in_off_sequence - - run_off_sequence - - never - AdminPin: - type: string - maxLength: 20 - description: Optional administrator pin - AmbientLight: - type: object - properties: - intensity: - description: 'Light intensity. 0 = pitch black, 65535 = very bright.' - type: integer - minimum: 0 - maximum: 65535 - required: - - intensity - AmbientLightResponse: - type: object - properties: - intensity: - description: 'Light intensity. 0 = pitch black, 65535 = very bright.' - type: integer - minimum: 0 - maximum: 65535 - required: - - intensity - ApiKey: - type: object - properties: - key_id: - $ref: '#/components/schemas/ApiKeyId' - name: - $ref: '#/components/schemas/ApiKeyName' - prefix: - description: Prefix of the API key for identification purposes. - type: string - active: - type: boolean - description: Only activated keys are valid for API access. - valid_to: - type: string - format: date-time - description: 'Optional expiration timestamp. If not set, the API key is valid until revoked.' - scopes: - type: array - items: - $ref: '#/components/schemas/ScopeName' - description: - $ref: '#/components/schemas/Description' - creation_date: - type: string - format: date-time - ApiKeyId: - type: string - format: '^[a-zA-Z0-9\-_]+$' - minLength: 1 - maxLength: 36 - description: Unique key identifier. Usually a UUID. - ApiKeyName: - type: string - minLength: 1 - maxLength: 50 - description: Friendly API key name to show in the app - ApiKeyRequest: - type: object - properties: - name: - $ref: '#/components/schemas/ApiKeyName' - scopes: - type: array - items: - type: string - description: Requested access scopes for the API key. - active: - type: boolean - default: false - description: | - Only activated keys are valid for API access. - This might be overridden if the requestor doesn't have sufficient rights. In this case the key will not be active - until a user with appropriate rights will set it active. The assigned `active` state will be returned in the - response. - valid_to: - type: string - format: date-time - description: 'Optional expiration timestamp. If not set, the API key is valid until revoked.' - description: - $ref: '#/components/schemas/Description' + type: string + description: Requested access scopes for the API key. + active: + type: boolean + default: false + description: | + Only activated keys are valid for API access. + This might be overridden if the requestor doesn't have sufficient rights. In this case the key will not be active + until a user with appropriate rights will set it active. The assigned `active` state will be returned in the + response. + valid_to: + type: string + format: date-time + description: Optional expiration timestamp. If not set, the API key is valid until revoked. + description: + $ref: '#/components/schemas/Description' required: - name - scopes @@ -11670,7 +11759,7 @@ components: valid_to: type: string format: date-time - description: 'Optional expiration timestamp. If not set, the API key is valid until revoked.' + description: Optional expiration timestamp. If not set, the API key is valid until revoked. scopes: type: array items: @@ -11680,10 +11769,6 @@ components: - api_key - active - scopes - ApiKeys: - type: array - items: - $ref: '#/components/schemas/ApiKey' ApiKeyUpdate: type: object properties: @@ -11695,1750 +11780,1834 @@ components: valid_to: type: string format: date-time - description: 'Optional expiration timestamp. If not set, the API key is valid until revoked.' + description: Optional expiration timestamp. If not set, the API key is valid until revoked. description: $ref: '#/components/schemas/Description' - ApiResponse: - type: object - properties: - code: - type: string - description: Status code - message: - type: string - description: Status message describing the result or error. This message is intended for error analysis and should not directly shown to the end user. - AvailableEntity: - description: | - Provided entity from an integration which can be configured to be used in the remote. - - See [entity documentation](https://github.com/unfoldedcircle/core-api/blob/main/doc/entities/) - for more information. - - If no icon identifier is specified, the default icon for the entity type is used. + Scope: type: object properties: - entity_id: - $ref: '#/components/schemas/AvailableEntityId' - entity_type: - $ref: '#/components/schemas/EntityType' - integration_id: - $ref: '#/components/schemas/IntegrationId' - device_id: - $ref: '#/components/schemas/DeviceId' - device_class: - description: | - Optional device type. This can be used by the UI to represent the entity with a different - icon, behaviour etc. See entity documentation for available device classes. - type: string name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' + $ref: '#/components/schemas/ScopeName' description: - $ref: '#/components/schemas/LanguageText' - features: - description: | - Supported features of the entity. See entity documentation for available features. - type: array - items: - type: string - options: - description: | - Feature options. See entity documentation for available options. - type: object - area: - description: Optional area if supported by the integration. E.g. `Living room`. type: string + description: Permission scope description required: - - entity_id - - entity_type - - integration_id - name - - features - AvailableEntityId: + Scopes: + type: array + items: + $ref: '#/components/schemas/Scope' + ExtTokenType: + description: | + Type of the access token: + - `TOKEN`: generic token, for example a long-lived access token. + - `OAUTH2_APP`: OAuth2 application credentials. + - `OAUTH2_TOKEN`: OAuth2 token (access and refresh tokens). type: string - format: '^[a-zA-Z0-9\-_\.]+$' - minLength: 1 + enum: + - TOKEN + - OAUTH2_APP + - OAUTH2_TOKEN + ExtSystemState: + description: | + State of the external system: + - `ALL`: all external systems. + - `NEW`: external systems that have no stored credentials yet. + - `ACTIVE`: external systems that have at least one stored credential. + type: string + enum: + - ALL + - NEW + - ACTIVE + ExternalSystemId: + type: string + format: ^[a-zA-Z0-9\-_]+$ + minLength: 1 + maxLength: 50 + description: Unique external system identifier registered by an R2 integration to interact with the API. + ExtSystemName: + type: string + minLength: 1 + maxLength: 50 + description: | + Friendly name of the external system to display to the user within the app. This name must be unique for an external + system and should be as short and concise as possible. + TokenId: + type: string + format: ^[a-zA-Z0-9\-_]+$ + minLength: 1 maxLength: 36 description: | - Entity identifier used in an integration driver (= available entities). - BackupReports: - type: array - items: - type: object - properties: - item: - type: string - enum: - - db - - integration_driver - - integration - - activity - - macro - - remote - - profile - - dock - - resource - available: - type: integer - format: int32 - ok: - type: integer - format: int32 - required: - - item - - available - - ok - BackupSnapshot: + Unique token identifier, used for later token management through the external system or management ui. + DriverId: + type: string + format: ^[a-zA-Z0-9\-_]+$ + minLength: 1 + maxLength: 36 + description: Unique integration driver identifier, e.g. `homeassistant`, `homey`, etc. + LanguageText: + type: object + description: | + Key value pairs of language texts. Key: ISO 639-1 code with optional country suffix to represent a `culture code`. + Examples: `en`, `en_UK`, `en_US`, `de`, `de_CH`. + + If we need to support more regional differences within a country, then the + [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) might be a solution. This would even + support the various Swiss German dialects! + additionalProperties: + type: string + IconIdentifier: + type: string + format: ^[a-z][a-z0-9]+:[a-zA-Z0-9\-_\.]+$ + maxLength: 255 + description: | + Optional icon identifier. The identifier consists of a prefix and a resource identifier, separated by `:`. + Available prefixes: + - `uc:` - integrated icon font + - `custom:` - custom icon resource + - `ctv:` - custom TV icon resource + + Other prefixes might be rejected by the service. + + An empty identifier, while updating the object, removes the existing icon. + ExternalSystemInfo: + description: | + Information about an external system. + - The `token_id` field is only returned for `token_type: OAUTH2_APP`. + - The `intg_driver_id` and `intg_name` fields are only returned if the system is associated with an integration driver. type: object properties: - id: - description: Backup identifier - type: string - creation_date: - description: Creation date of the backup snapshot - type: string - format: date-time - size: - description: Archive size in bytes + system: + $ref: '#/components/schemas/ExternalSystemId' + name: + $ref: '#/components/schemas/ExtSystemName' + token_count: + description: | + Number of tokens associated with this external system. + The count reflects the requested token type, or the overall token count if no token type is specified. type: integer - format: int32 + token_id: + $ref: '#/components/schemas/TokenId' + intg_driver_id: + $ref: '#/components/schemas/DriverId' + intg_name: + $ref: '#/components/schemas/LanguageText' + icon: + $ref: '#/components/schemas/IconIdentifier' required: - - id - - creation_date - - size - example: - id: UCR2_2023-09-17_145305 - creation_date: '2023-09-17T14:53:05+02:00' - size: 2370274 - BackupMetadata: + - system + - name + ExternalSystemInfos: + type: array + items: + $ref: '#/components/schemas/ExternalSystemInfo' + ExtAccessTokenDescription: + type: string + maxLength: 2048 + description: Optional description of the external access token. + ExtAccessTokenUrl: + type: string + maxLength: 2048 + description: Optional URL of the external system. + ExtAccessTokenData: + type: string + maxLength: 32768 + description: | + Optional data from the external system for the Remote integration. + ⚠️ Attention: this data is not protected and retrievable by API clients! + ExternalAccessToken: type: object properties: - id: - description: Backup identifier - type: string + system: + $ref: '#/components/schemas/ExternalSystemId' + token_id: + $ref: '#/components/schemas/TokenId' + token_type: + $ref: '#/components/schemas/ExtTokenType' + name: + $ref: '#/components/schemas/ExtSystemName' + description: + $ref: '#/components/schemas/ExtAccessTokenDescription' + url: + $ref: '#/components/schemas/ExtAccessTokenUrl' + data: + $ref: '#/components/schemas/ExtAccessTokenData' creation_date: - description: Creation date of the backup snapshot type: string format: date-time - version: - $ref: '#/components/schemas/BackupMetadataVersion' - report: - $ref: '#/components/schemas/BackupReports/items' required: - - id + - system + - token_id + - token_type + - name - creation_date - - version - example: - id: UCR2_2023-09-17_145305 - creation_date: '2023-09-17T14:53:05+00:00' - version: - backup: 1.0.0 - core: 0.34.5-beta - os: 1.2.0 - BackupMetadataVersion: + ExternalAccessTokens: + type: array + items: + $ref: '#/components/schemas/ExternalAccessToken' + ExtAccessToken: + type: string + minLength: 1 + maxLength: 32768 + description: | + The token to access the external system with the corresponding Remote integration. + This could be a UUID, a JWT, a PEM certificate or any other representation required for the integration to + authenticate on the system. + ExternalAccessTokenRequest: type: object + description: | + - The `token_type` is set to `TOKEN` if not provided. + - For `token_type: OAUTH2_APP`, the `token_id` field is required and corresponds to the OAuth client ID. + - For `token_type: TOKEN`, the `token_id` is optional and can be provided by the external system. + - If omitted, an UUID is generated and returned in the `ExternalAccessToken` response. + - The `token_id` may not end in `-DATA` or `-URL`. properties: - backup: - description: 'Version of the backup data model in [SemVer](https://semver.org/) format.' - type: string - core: - description: Core app version - type: string - os: - description: Operating system version - type: string + token_type: + $ref: '#/components/schemas/ExtTokenType' + token_id: + $ref: '#/components/schemas/TokenId' + name: + $ref: '#/components/schemas/ExtSystemName' + token: + $ref: '#/components/schemas/ExtAccessToken' + description: + $ref: '#/components/schemas/ExtAccessTokenDescription' + url: + $ref: '#/components/schemas/ExtAccessTokenUrl' + data: + $ref: '#/components/schemas/ExtAccessTokenData' required: - - backup - BatteryStatusResponse: + - name + - token + examples: + - token_id: 1-2-3 + name: My smart home + token: secret-sauce-42! + description: Any other informative message about the external system + url: ws://smart.home + data: 'optional: true, foo: bar, free: text' + ExternalAccessTokenResponse: type: object + description: | + If the token identifier has been provided in the request, then then same identifier is returned, otherwise a + UUID is generated. properties: - capacity: - description: Current battery charge in % - type: integer - minimum: 0 - maximum: 100 - status: - $ref: '#/components/schemas/PowerStatus' - power_supply: - description: 'A power supply is online, device doesn''t run on battery.' - type: boolean + token_id: + $ref: '#/components/schemas/TokenId' required: - - capacity - - status - BatteryCharger: + - token_id + AccessTokenId: + type: string + format: ^[a-zA-Z0-9\-_]+$ + minLength: 1 + maxLength: 36 + description: Unique token identifier. Usually a UUID. + ResourceType: + type: string + format: ^[a-zA-Z]+$ + minLength: 1 + maxLength: 32 + SupportedResource: type: object properties: - features: + type: + $ref: '#/components/schemas/ResourceType' + name: + $ref: '#/components/schemas/LanguageText' + description: + $ref: '#/components/schemas/LanguageText' + file_formats: + description: Allowed file format extensions, e.g. `png`. type: array items: type: string - power_supply: - description: 'A power supply is online, device doesn''t run on battery.' - type: boolean - wireless_charging: - description: Wireless charging is active. Only returned on devices with wireless charging. - type: boolean - wireless_charging_enabled: - description: Wireless charging is enabled. Only returned on devices with wireless charging. - type: boolean + max_file_size: + description: Maximum file size in bytes. + type: integer + max_count: + description: Maximum number of custom resources. + type: integer + image: + description: Image specific restrictions. Only set for image resources. + type: object + properties: + sizes: + description: Allowed image sizes. + type: array + items: + type: object + properties: + width: + type: integer + height: + type: integer + required: + - width + - height + required: + - sizes + sound: + type: object + description: Sound file specific restrictions. Only set for sound resources. + properties: + bits: + type: array + items: + type: integer + channels: + type: array + items: + type: integer + sampling_rates: + type: array + items: + type: integer required: - - features - - power_supply - BatteryChargerUpdate: + - type + - name + - file_formats + - max_file_size + - max_count + SupportedResources: + type: array + items: + $ref: '#/components/schemas/SupportedResource' + ResourceItem: type: object properties: - wireless_charging_enabled: - description: Enable or disable wireless charging. Only supported on devices with wireless charging. - type: boolean - PowerStatus: + type: + $ref: '#/components/schemas/ResourceType' + id: + type: string + description: Resource identifier (normalized filename) + size: + type: integer + format: int32 + description: Size in bytes + ResourceItems: + type: array + items: + $ref: '#/components/schemas/ResourceItem' + IntegrationId: + type: string + format: ^[a-zA-Z0-9\-_\.]+$ + minLength: 1 + maxLength: 73 + description: | + Unique integration instance identifier. Automatically created by the system when creating a new instance from a driver. + IntegrationDriverType: type: string + description: | + - `LOCAL`: pre-installed integration driver in the firmware. + - `CUSTOM`: user-installed custom integration driver on the remote. + - `EXTERNAL`: external integration driver on the network. enum: - - CHARGING - - DISCHARGING - - NOT_CHARGING - - FULL - ButtonId: + - LOCAL + - CUSTOM + - EXTERNAL + IntegrationState: type: string - format: '^[A-Z0-9_]+$' - minLength: 1 - maxLength: 20 - description: Physical button identification - CfgAll: + enum: + - NOT_CONFIGURED + - UNKNOWN + - IDLE + - CONNECTING + - CONNECTED + - DISCONNECTED + - RECONNECTING + - ACTIVE + - ERROR + IntegrationStatus: type: object + description: | + Integration status information. Intended to be used in a general overview of the integration drivers and instances. properties: - bt: - $ref: '#/components/schemas/CfgBt' - button: - $ref: '#/components/schemas/CfgButtons' - device: - $ref: '#/components/schemas/CfgRemoteDevice' - display: - $ref: '#/components/schemas/CfgDisplay' - features: - $ref: '#/components/schemas/CfgFeatures' - haptic: - $ref: '#/components/schemas/CfgHaptic' - localization: - $ref: '#/components/schemas/CfgLocalization' - network: - $ref: '#/components/schemas/CfgNetwork' - power_saving: - $ref: '#/components/schemas/CfgPowerSaving' - profile: - $ref: '#/components/schemas/CfgProfile' - software_update: - $ref: '#/components/schemas/CfgSoftwareUpdate' - sound: - $ref: '#/components/schemas/CfgSound' - voice: - $ref: '#/components/schemas/CfgVoiceControl' - restart_required: - description: A configuration change requires a restart. - type: boolean - CfgBt: + driver_id: + $ref: '#/components/schemas/DriverId' + integration_id: + $ref: '#/components/schemas/IntegrationId' + name: + $ref: '#/components/schemas/LanguageText' + icon: + $ref: '#/components/schemas/IconIdentifier' + driver_type: + $ref: '#/components/schemas/IntegrationDriverType' + state: + $ref: '#/components/schemas/IntegrationState' + required: + - name + - driver_type + IntegrationDiscovery: type: object properties: - peripheral_connections: - description: Maximum number of peripheral connections at the same time. - type: integer - minimum: 1 - advertisement_name: - description: Advertisement name of the Remote. - type: string - enable_hci_log: - description: Enable HCI logging. + id: + $ref: '#/components/schemas/DriverId' + configured: + description: | + Integration configuration flag: + - true: driver has already been configured + - false: driver has not yet been configured type: boolean - enable_debug_port: - description: Enable BT subsystem debug TCP-port for remote control. + name: + type: string + developer_name: + type: string + icon: + $ref: '#/components/schemas/IconIdentifier' + driver_url: + description: Resolved driver url. + type: string + pwd_protected: + description: Driver requires a connection password. type: boolean version: - description: BT subsystem version. + description: Detected driver version. type: string + timestamp: + description: Timestamp of integration discovery. + type: string + format: date-time required: - - peripheral_connections - - advertisement_name - - enable_hci_log - - enable_debug_port - CfgBtUpdate: - type: object - properties: - peripheral_connections: - description: Maximum number of peripheral connections at the same time. - type: integer - minimum: 1 - enable_hci_log: - description: Enable HCI logging. - type: boolean - enable_debug_port: - description: Enable BT subsystem debug TCP-port for remote control. - type: boolean - CfgButtons: + - id + - configured + - name + - driver_url + IntegrationDiscoveryStatus: type: object properties: - brightness: - description: 'Button backlight brightness. 0 = off, 100 = max.' - type: integer - minimum: 0 - maximum: 100 - static_color: - $ref: '#/components/schemas/StaticButtonColor' - auto_brightness: - description: 'When enabled, button backlight will automatically turn on in a dark room.' + active: + description: | + Integration discovery still active or not. type: boolean - features: - description: Supported features by the device. + integrations: type: array items: - type: string + $ref: '#/components/schemas/IntegrationDiscovery' required: - - brightness - - auto_brightness - CfgButtonsUpdate: - description: Button configuration model to update settings. Missing properties are not changed. - type: object - properties: - brightness: - description: 'Overall button backlight brightness. 0 = off, 100 = max.' - type: integer - minimum: 0 - maximum: 100 - static_color: - $ref: '#/components/schemas/StaticButtonColor' - auto_brightness: - description: 'When enabled, button backlight will automatically turn on in a dark room.' - type: boolean - StaticButtonColor: - description: 'Static color settings for given zones, if supported by the device.' + - active + - integrations + IntgAuthMethod: + type: string + description: | + 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. + enum: + - HEADER + - MESSAGE + DriverDeveloper: type: object + description: Optional information about the integration developer. properties: - rgb: - description: 'The overall rgb color value for the specified zones [int, int, int].' - type: array - items: - type: integer - minimum: 0 - maximum: 255 - minItems: 3 - maxItems: 3 - zones: - description: The enabled backlight zones. All zones are enabled if no zones are set. - type: array - items: - type: string - minimum: 1 - maximum: 50 - maxItems: 32 - required: - - rgb - CfgDisplay: + name: + description: Optional developer information to display in UI / web-configurator. + type: string + maxLength: 100 + url: + description: Optional developer home page. + type: string + format: uri + maxLength: 255 + email: + description: Optional developer contact email. + type: string + format: email + maxLength: 100 + SettingTypeNumber: + description: | + 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 `unit`, which will be displayed next to + the input field. type: object properties: - brightness: - description: Display brightness. - type: integer - minimum: 0 - maximum: 100 - auto_brightness: - description: Automatically adjust the display brightness based on ambient lighting conditions. - type: boolean + number: + type: object + properties: + value: + description: Default value for input field. + type: number + min: + description: 'Optional validation: minimum allowed value (inclusive).' + type: number + max: + description: 'Optional validation: maximum allowed value (inclusive).' + type: number + steps: + description: | + Optional validation: allowed step increment between values. Might also be used in the UI for input helpers. + type: number + decimals: + description: Number of decimal places. 0 = integer value + type: integer + minimum: 0 + default: 0 + unit: + $ref: '#/components/schemas/LanguageText' + required: + - value required: - - brightness - - auto_brightness - CfgFeatures: - type: array - items: - $ref: '#/components/schemas/CfgFeature' - CfgFeature: + - number + SettingTypeText: + description: | + Single line of text input. + + TODO: format specifier for e.g. email, url, date, datetime etc.? type: object properties: - id: - type: string - enabled: - type: boolean - title: - $ref: '#/components/schemas/LanguageText' - description: - $ref: '#/components/schemas/LanguageText' - help_url: - type: string - format: url + text: + type: object + properties: + value: + description: Optional default value. + type: string + regex: + description: Optional regex validation pattern for the input value. + type: string required: - - id - - enabled - - title - - description - CfgFeatureUpdate: + - text + SettingTypeTextArea: + description: Multi-line text input, e.g. for providing a description. type: object properties: - id: - type: string - enabled: - type: boolean + textarea: + type: object + properties: + value: + description: Optional default value. + type: string required: - - id - - enabled - CfgHaptic: + - textarea + SettingTypePassword: + description: | + Password or pin entry field with the input text hidden from the user. Otherwise the same as text input. type: object properties: - enabled: - description: Haptic feedback enabled. - type: boolean + password: + type: object + properties: + value: + description: Optional default value. + type: string + format: password + regex: + description: Optional regex validation pattern for the input value. + type: string required: - - enabled - CfgLocalization: + - password + SettingTypeCheckbox: + description: Checkbox setting with `true` / `false` values. type: object properties: - language_code: - $ref: '#/components/schemas/LanguageCode' - country_code: - $ref: '#/components/schemas/CountryCode' - time_zone: - description: 'Time zone name according to IANA , e.g. `Europe/Copenhagen`.' - type: string - time_format_24h: - type: boolean - measurement_unit: - $ref: '#/components/schemas/MeasurementUnit' + checkbox: + type: object + properties: + value: + description: Initial setting. + type: boolean + required: + - value required: - - language_code - - country_code - - time_zone - - time_format_24h - - measurement_unit - CfgNetwork: - description: | - `wake_on_wlan` is deprecated, please use `wifi.wake_on_wlan` + - checkbox + SettingTypeDropdown: + description: Dropdown setting to pick a single value from a list. All values must be strings. type: object properties: - bt_enabled: - description: Enable Bluetooth. - type: boolean - wifi_enabled: - description: Enable WiFi. - type: boolean - wake_on_wlan: - $ref: '#/components/schemas/CfgNetworkWoWlan' - wifi: - $ref: '#/components/schemas/CfgNetworkWifi' - bt: - description: Temporary read-only Bluetooth information until dedicated BT management endpoint is provided. + dropdown: type: object properties: - address: - description: Bluetooth MAC address + value: + description: Pre-selected dropdown id type: string - ws: - $ref: '#/components/schemas/CfgNetworkWs' + items: + type: array + items: + type: object + properties: + id: + description: Selection identifier. + type: string + label: + $ref: '#/components/schemas/LanguageText' + required: + - id + - label + required: + - items required: - - bt_enabled - - wifi_enabled - CfgNetworkUpdate: - description: | - `wake_on_wlan` is deprecated, please use `wifi.wake_on_wlan` - type: object - properties: - bt_enabled: - description: Enable Bluetooth. - type: boolean - wifi_enabled: - description: Enable WiFi. - type: boolean - wake_on_wlan: - $ref: '#/components/schemas/CfgNetworkWoWlan' - wifi: - $ref: '#/components/schemas/CfgNetworkWifiUpdate' - ws: - $ref: '#/components/schemas/CfgNetworkWs' - CfgNetworkWs: + - dropdown + SettingTypeLabel: description: | - Optional expert settings for WebSocket (re-)connection handling. - These settings are only intended for support issues and might change any time. Changed values are not supported - and might make the system unstable! + Additional read-only text for information purpose between other settings. Supports Markdown formatting. type: object properties: - dock: - type: object - integration: + label: type: object - CfgNetworkWoWlan: - description: Wake on WLAN settings + properties: + value: + $ref: '#/components/schemas/LanguageText' + required: + - value + required: + - label + Setting: + description: | + 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](https://apps.developer.homey.app/the-basics/devices/settings) concept. type: object properties: - enabled: - description: Enable Wake on WLAN. - type: boolean + id: + description: Unique identifier of the setting to be returned with the entered value. + type: string + maximum: 50 + label: + $ref: '#/components/schemas/LanguageText' + field: + oneOf: + - $ref: '#/components/schemas/SettingTypeNumber' + - $ref: '#/components/schemas/SettingTypeText' + - $ref: '#/components/schemas/SettingTypeTextArea' + - $ref: '#/components/schemas/SettingTypePassword' + - $ref: '#/components/schemas/SettingTypeCheckbox' + - $ref: '#/components/schemas/SettingTypeDropdown' + - $ref: '#/components/schemas/SettingTypeLabel' required: - - enabled - CfgNetworkWifi: + - id + - label + - field + SettingsPage: + description: Settings definition page, e.g. to configure an integration driver. type: object properties: - wake_on_wlan: - $ref: '#/components/schemas/CfgNetworkWoWlan' - bands: - description: Available WiFi bands + title: + $ref: '#/components/schemas/LanguageText' + settings: + description: One or multiple input field definitions, with optional pre-set values. type: array items: - $ref: '#/components/schemas/WifiBand' - band: - $ref: '#/components/schemas/WifiBand' - scan_interval_sec: - description: | - Active WiFi scan interval in seconds. A value of 0 disables active scanning. Minimal interval is 10 seconds. - minimum: 0 - type: integer - ipv4_type: - $ref: '#/components/schemas/CfgIpv4Type' - ipv4: - $ref: '#/components/schemas/CfgIpv4' + $ref: '#/components/schemas/Setting' required: - - bands - - band - CfgNetworkWifiUpdate: - type: object - properties: - wake_on_wlan: - $ref: '#/components/schemas/CfgNetworkWoWlan' - band: - $ref: '#/components/schemas/WifiBand' - scan_interval_sec: - $ref: '#/components/schemas/CfgNetworkWifi/properties/scan_interval_sec' - CfgIpv4Type: + - title + - settings + DriverState: type: string enum: - - DHCP - CfgIpv4: - type: object - CfgPowerSaving: - type: object - properties: - wakeup_sensitivity: - description: 'Amount of movement needed to wake up the remote. 0 = disabled, 1 = min, 2 = medium, 3 = max.' - type: integer - minimum: 0 - maximum: 3 - display_off_sec: - type: integer - minimum: 0 - maximum: 60 - description: Turn off display after given seconds. - standby_sec: - type: integer - minimum: 0 - maximum: 10800 - description: Activate standby after given seconds. 0 disables standby mode. - required: - - wakeup_sensitivity - - display_off_sec - - standby_sec - CfgProfile: - type: object - properties: - has_admin_pin: - description: An administrator pin has been set to use restricted profiles. - type: boolean - required: - - has_admin_pin - CfgProfileUpdate: - type: object - properties: - admin_pin: - $ref: '#/components/schemas/AdminPin' - CfgRemoteDevice: + - NOT_CONFIGURED + - IDLE + - CONNECTING + - ACTIVE + - RECONNECTING + - ERROR + IntegrationDriver: type: object + description: | + Integration driver model. + + A driver represents the communication aspect of an integration. E.g. how one can connect to it + and which API version it supports. + + One driver can provide multiple `Integration` instances. In the integration API they are + referred to as `multi-device integrations` and use the optional `device_id` property where + required. If a driver only provides a single instance, which is usually the default use case, + then the `device_id` is not used (or set to the default value `main`). properties: + driver_id: + $ref: '#/components/schemas/DriverId' name: - description: Custom name of the remote + $ref: '#/components/schemas/LanguageText' + driver_type: + $ref: '#/components/schemas/IntegrationDriverType' + driver_url: + description: WebSocket URL of the driver. Only optional for integration driver metadata. type: string - minimum: 1 - maximum: 50 - required: - - name - CfgSoftwareUpdate: - type: object - properties: - check_for_updates: - description: | - Automatically check for updates. If `auto_update` is enabled, the updates are automatically installed, - otherwise the user is only notified about the updates. - - The time window when to check for new updates can be specified in `ota_window_start` and `ota_window_end`. - Update checks are performed daily. - type: boolean - auto_update: - description: | - Automatically update the remote when new software is available. Requires `check_for_updates` to be enabled. - - Auto-installation of new firmwares will usually happen over 2 update checks: the first check finds a new - update, downloads the metadata and schedules the firmware file to be downloaded. The next check will find the - downloaded firmware file and installs it. - type: boolean - ota_window_start: + format: uri + maxLength: 2048 + token: description: | - OTA update window start time: automatic update checks will only be performed during this time window. - Furthermore, the remote needs to be in the docking station and have enough battery charge. + Optional driver authentication token. - Format: time of day - as defined by `partial-time` in RFC3339 + Note: the token will not be returned to external clients! type: string - pattern: '^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$' - ota_window_end: - description: | - OTA update window end time. - - - If the end time is before the start time, the window will spawn over midnight, e.g. `23:00:00` - `01:00:00`. - - Both start and end times are required, otherwise a default will be used. + maxLength: 2048 + auth_method: + $ref: '#/components/schemas/IntgAuthMethod' + pwd_protected: + description: Driver requires a connection password. + type: boolean + version: + description: Driver version, [SemVer](https://semver.org/) preferred. type: string - pattern: '^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$' - channel: + maxLength: 20 + min_core_api: description: | - Software update channels: - - `DEFAULT`: release channel - - `TESTING`: new test and beta versions which might become the next release if successfully tested. - - `DEVELOPMENT`: untested alpha versions from the developers. - ⚠️ High chance of breaking changes, bugs and loosing data! - - Other channels than `DEFAULT` might require an access token in `channel_token`, since they are intended for - a closed user group. + Optional version check: minimum required core API version in the remote. type: string - anyOf: - - enum: - - DEFAULT - - TESTING - - DEVELOPMENT - - {} - channel_token: + maxLength: 20 + icon: + $ref: '#/components/schemas/IconIdentifier' + enabled: description: | - Optional access token which might be required for non-default software update channels. - - This token is write only and cannot be retrieved anymore. - - If omitted when updating settings: the stored token will be used. - - If the `default` channel is selected when updating settings: the token will be ignored. + Enables or disables driver communication. For development use only! + If disabled, all integration instances won't be activated, even if the instance is enabled. + type: boolean + description: + $ref: '#/components/schemas/LanguageText' + developer: + $ref: '#/components/schemas/DriverDeveloper' + home_page: + description: Optional home page url for more information. type: string - pattern: '^[-a-zA-Z0-9._~+/]{1,256}=?$' - restart_required: - description: 'Optional response field only: a configuration change requires a restart.' + format: uri + maxLength: 255 + device_discovery: + description: Driver supports multi-device discovery. **Not yet supported**. type: boolean + setup_data_schema: + $ref: '#/components/schemas/SettingsPage' + release_date: + description: Release date of the driver. + type: string + format: date + driver_state: + $ref: '#/components/schemas/DriverState' required: - - check_for_updates - - auto_update - CfgSound: + - driver_id + - name + - version + IntegrationDriverInfo: type: object + description: | + Summary data of an integration driver intended for overview screens. properties: + driver_id: + $ref: '#/components/schemas/DriverId' + name: + $ref: '#/components/schemas/LanguageText' + developer_name: + type: string + driver_type: + $ref: '#/components/schemas/IntegrationDriverType' + driver_url: + description: WebSocket URL of external driver + type: string + format: uri + maxLength: 255 + version: + type: string + icon: + $ref: '#/components/schemas/IconIdentifier' enabled: - description: Sound effects enabled. type: boolean - volume: - description: Sound effects volume. - type: integer - minimum: 0 - maximum: 100 + driver_state: + $ref: '#/components/schemas/DriverState' required: + - driver_id + - name + - driver_type + - version - enabled - - volume - CfgVoiceControl: + SettingsValues: description: | - Voice control settings with enriched voice assistant configuration. - No voice assistant is enabled if the `voice_assistant.active` object is missing. + User input result of a SettingsPage as key values. + - key: id of the field + - value: entered user value as string. This is either the entered text or number, selected checkbox state or the + selected dropdown item id. + ⚠️ Non native string values as numbers or booleans are represented as string values! type: object - properties: - microphone: - description: | - Enable microphone. Disabling the microphone will completely turn it off. Voice control and dictation won't work - with the remote or integrations. - type: boolean - voice_assistant: - $ref: '#/components/schemas/CfgVoiceAssistant' - required: - - microphone - - voice_assistant - CfgVoiceAssistant: - description: | - The main voice assistant to use for voice control, if no other voice assistant is configured for a specific - screen, for example, in an activity. + additionalProperties: + type: string + CreateIntegrationSetup: type: object properties: - active: - $ref: '#/components/schemas/VoiceAssistant' - profile_id: - $ref: '#/components/schemas/SimpleId' - speech_response: - description: Enable speech response if supported by the voice assistant. Disabled by default. + driver_id: + $ref: '#/components/schemas/DriverId' + name: + $ref: '#/components/schemas/LanguageText' + setup_data: + $ref: '#/components/schemas/SettingsValues' + reconfigure: + description: Reconfigure an already configured integration. type: boolean - default: false - CfgVoiceControlUpdate: - description: | - Update object for voice control settings. A missing field will keep the old value. - type: object - properties: - microphone: - description: | - Enable microphone. Disabling the microphone will completely turn it off. Voice control and dictation won't work - with the remote or integrations. - type: boolean - voice_assistant: - $ref: '#/components/schemas/CfgVoiceAssistantUpdate' - CfgVoiceAssistantUpdate: + required: + - driver_id + IntegrationSetupState: + type: string + enum: + - SETUP + - WAIT_USER_ACTION + - OK + - ERROR + IntegrationSetupError: + type: string + enum: + - NONE + - NOT_FOUND + - CONNECTION_REFUSED + - AUTHORIZATION_ERROR + - TIMEOUT + - OTHER + ConfirmationPage: description: | - The main voice assistant to use for voice control, if no other voice assistant is configured for a specific - screen, for example, in an activity. + Confirmation screen. + - `message1`: Message to display between title and image (if supplied). Supports Markdown formatting. + - `message2`: Message to display below message1 or image (if supplied). Supports Markdown formatting. type: object properties: - entity_id: - description: 'Voice assistant entity id to use, empty for removing a configured voice assistant.' + title: + $ref: '#/components/schemas/LanguageText' + message1: + $ref: '#/components/schemas/LanguageText' + image: + description: | + Optional base64-encoded image. + + TODO maximum encoded length to avoid WebSocket continuation frames, supported image formats + (png & svg?), max height & width type: string - profile_id: - $ref: '#/components/schemas/SimpleId' - speech_response: - description: Enable speech response if supported by the voice assistant. Disabled by default. - type: boolean + format: byte + maxLength: 32768 + message2: + $ref: '#/components/schemas/LanguageText' required: - - entity_id - CommandSequence: - description: Sequence of commands to execute. - type: array - items: - oneOf: - - $ref: '#/components/schemas/CommandSequenceEntity' - - $ref: '#/components/schemas/CommandSequenceDelay' - discriminator: - propertyName: type - mapping: - command: '#/components/schemas/CommandSequenceEntity' - delay: '#/components/schemas/CommandSequenceDelay' - CommandSequenceEntity: - description: Entity command step in a command sequence. + - title + IntegrationSetupInfo: type: object + description: Integration setup state properties: - type: + id: type: string - command: - $ref: '#/components/schemas/EntityCommand' + state: + $ref: '#/components/schemas/IntegrationSetupState' + error: + $ref: '#/components/schemas/IntegrationSetupError' + require_user_action: + description: If set, the setup process waits for the specified user action. + oneOf: + - type: object + properties: + input: + $ref: '#/components/schemas/SettingsPage' + required: + - input + - type: object + properties: + confirmation: + $ref: '#/components/schemas/ConfirmationPage' + required: + - confirmation required: - - type - - command - example: - type: command - command: - entity_id: hass.main.light.living-room - cmd_id: 'on' - params: - brightness: 75 - CommandSequenceDelay: - description: Delay step in a command sequence. + - id + - state + IntegrationDrivers: + type: array + items: + $ref: '#/components/schemas/IntegrationDriverInfo' + IntegrationDriverRequest: type: object + description: | + Integration driver creation model. + + - The only required property is `driver_url` to contact the driver and fetch all driver data. + - If the driver requires an access token, the `token` needs to be specified and optionally the authentication method + in `auth_method`. + - The `driver_id` identifier can be specified by the client, but it needs to be unique among + all drivers. If omitted, the driver identifier returned by the driver will be used. + A manually assigned, short, human-readable identifier is recommended for better recognizability. properties: - type: + driver_id: + $ref: '#/components/schemas/DriverId' + name: + $ref: '#/components/schemas/LanguageText' + driver_url: + description: WebSocket URL of the driver type: string - delay: - description: Delay in milliseconds. - type: integer - minimum: 1 + format: uri + maxLength: 2048 + token: + description: Optional driver authentication token. + type: string + maxLength: 2048 + auth_method: + $ref: '#/components/schemas/IntgAuthMethod' + icon: + $ref: '#/components/schemas/IconIdentifier' + enabled: + description: | + Enables or disables driver communication. For development use only! + If disabled, all integration instances won't be activated, even if the instance is enabled. + type: boolean required: - - type - - delay - example: - type: delay - delay: 100 - CountryCode: - description: 'Two letter country code according to [ISO-3166-1-alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).' + - driver_url + DeviceId: type: string - format: iso-3166 - CustomInstall: - description: Information about an installed custom component. The `installed` flag reports if a custom installation + format: ^[a-zA-Z0-9\-_]+$ + minLength: 1 + maxLength: 36 + description: Device identifier for multi-device integrations only. + IntegrationUpdate: type: object + description: | + Integration instance update model. This model corresponds to the `Integration` model except there are no required + properties to allow patch updates. + + - Specified properties will update the current values. + - An empty value will delete a set property. + - `device_id` is only required for multi-device integrations. properties: - component: - $ref: '#/components/schemas/CustomComponent' - installed: - description: | - Custom component has been installed. When `installed: true` is set, more information is returned in `release`. - type: boolean - active: - description: Custom component is active and replacing the default component. + device_id: + $ref: '#/components/schemas/DeviceId' + name: + $ref: '#/components/schemas/LanguageText' + icon: + $ref: '#/components/schemas/IconIdentifier' + enabled: + description: Enable / disable flag. For development use only! type: boolean - installation_date: - description: 'Installation date of the component. Only provided when `installed: true` is set.' - type: string - format: date-time - release: - $ref: '#/components/schemas/CustomRelease' - required: - - component - - installed - - active - CustomComponent: - description: Type of custom component. + setup_data: + description: Instance configuration object. + type: object + DeviceState: type: string enum: - - ui - - web_configurator - CustomRelease: + - UNKNOWN + - CONNECTING + - CONNECTED + - DISCONNECTED + - ERROR + Integration: type: object + description: | + Integration instance model. properties: + integration_id: + $ref: '#/components/schemas/IntegrationId' + driver_id: + $ref: '#/components/schemas/DriverId' + device_id: + $ref: '#/components/schemas/DeviceId' name: $ref: '#/components/schemas/LanguageText' - version: - type: string - maxLength: 40 - description: + icon: + $ref: '#/components/schemas/IconIdentifier' + enabled: + description: Enable / disable flag. For development use only! + type: boolean + setup_data: + description: Instance configuration object + type: object + device_state: + $ref: '#/components/schemas/DeviceState' + required: + - integration_id + - driver_id + - name + - enabled + IntegrationDriverUpdate: + type: object + description: | + Integration driver update model. This model corresponds to the `IntegrationDriverRequest` model except there are + no required properties to allow patch updates. + + - Specified properties will update the current values. + - An empty value will delete the currently set property. + properties: + name: $ref: '#/components/schemas/LanguageText' - developer: - $ref: '#/components/schemas/DriverDeveloper' - home_page: - description: Optional home page url for more information. + driver_url: + description: WebSocket URL of the driver type: string format: uri - maxLength: 255 - release_date: - description: Release date of the component. + maxLength: 2048 + token: + description: Optional driver authentication token. type: string - format: date - requirements: - type: object - properties: - firmware_version: - description: | - [SemVer](https://semver.org/) version requirement, describing the intersection of some version comparators to - match the installed UC Remote firmware. - - - `>=1.0`: requires at least version 1.0.0 - - `>=0.9.0, <0.10.0`: only works with minor version 0.9.* - - Follows the Cargo's SemVer support documented in the [Specifying Dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html) - chapter of the Cargo reference. - type: string - Description: + maxLength: 2048 + auth_method: + $ref: '#/components/schemas/IntgAuthMethod' + icon: + $ref: '#/components/schemas/IconIdentifier' + enabled: + description: | + Enables or disables driver communication. + If disabled, all integration instances won't be activated, even if the instance is enabled. + type: boolean + Integrations: + type: array + items: + $ref: '#/components/schemas/Integration' + AvailableEntityId: type: string - maxLength: 255 - description: Optional description - DeviceButtonGroup: + format: ^[a-zA-Z0-9\-_\.]+$ + minLength: 1 + maxLength: 36 description: | - Button group type, either physical buttons or button backlight zones: - - `keypad`: physical keypad buttons. - - `keypad_backlight`: button backlight zones. + Entity identifier used in an integration driver (= available entities). + EntityType: type: string + description: Entity type enum: - - keypad - - keypad_backlight - DeviceButtonLayout: + - button + - climate + - cover + - light + - media_player + - sensor + - switch + - activity + - macro + - remote + - ir_emitter + - select + - voice_assistant + AvailableEntity: description: | - Button group definitions with layout placement, size, icon and language specific names. + Provided entity from an integration which can be configured to be used in the remote. - The grid width & height definitions do not need to be proportional! To get the correct size, the grid has to be - placed over the physical dimensions of the button group. For example if buttons in a row can be placed in the middle - of another button row, the width value can be doubled, with the button width set to 2. + See [entity documentation](https://github.com/unfoldedcircle/core-api/blob/main/doc/entities/) + for more information. + + If no icon identifier is specified, the default icon for the entity type is used. type: object properties: - type: - $ref: '#/components/schemas/DeviceButtonGroup' - grid: - description: Grid layout size. - type: object - properties: - width: - type: integer - minimum: 1 - height: - type: integer - minimum: 1 - required: - - width - - height - buttons: + entity_id: + $ref: '#/components/schemas/AvailableEntityId' + entity_type: + $ref: '#/components/schemas/EntityType' + integration_id: + $ref: '#/components/schemas/IntegrationId' + device_id: + $ref: '#/components/schemas/DeviceId' + device_class: + description: | + Optional device type. This can be used by the UI to represent the entity with a different + icon, behaviour etc. See entity documentation for available device classes. + type: string + name: + $ref: '#/components/schemas/LanguageText' + icon: + $ref: '#/components/schemas/IconIdentifier' + description: + $ref: '#/components/schemas/LanguageText' + features: + description: | + Supported features of the entity. See entity documentation for available features. type: array items: - type: object - properties: - button: - description: Unique button identifier over all button groups. - type: string - icon: - $ref: '#/components/schemas/IconIdentifier' - name: - $ref: '#/components/schemas/LanguageText' - location: - $ref: '#/components/schemas/GridLocation' - size: - $ref: '#/components/schemas/GridItemSize' - required: - - button - - icon - - name - - location - required: - - type - - grid - - buttons - DeviceScreenLayout: - description: Screen layout definitions with usable grid sizes for custom UI pages. - type: object - properties: - grid: + type: string + options: + description: | + Feature options. See entity documentation for available options. type: object - properties: - default: - $ref: '#/components/schemas/DeviceButtonLayout/properties/grid' - min: - $ref: '#/components/schemas/DeviceButtonLayout/properties/grid' - max: - $ref: '#/components/schemas/DeviceButtonLayout/properties/grid' - required: - - default - - min - - max + area: + description: Optional area if supported by the integration. E.g. `Living room`. + type: string required: - - grid - DeviceButtonMapping: + - entity_id + - entity_type + - integration_id + - name + - features + EntityId: + type: string + format: ^[a-zA-Z0-9\-_\.]+$ + minLength: 5 + maxLength: 110 + description: Unique UC Remote identifier over all entities and integrations. + EntityUpdateRequest: type: object - properties: - button: - $ref: '#/components/schemas/ButtonId' - short_press: - $ref: '#/components/schemas/EntityCommand' - long_press: - $ref: '#/components/schemas/EntityCommand' - required: - - button - DeviceButtonMappings: description: | - Physical button mapping to entity commands. The `entity_id` in the EntityCommand object is a required - property for an activity and ignored for a remote-entity. - type: array - items: - $ref: '#/components/schemas/DeviceButtonMapping' - DeviceId: - type: string - format: '^[a-zA-Z0-9\-_]+$' - minLength: 1 - maxLength: 36 - description: Device identifier for multi-device integrations only. - DeviceState: - type: string - enum: - - UNKNOWN - - CONNECTING - - CONNECTED - - DISCONNECTED - - ERROR - DeviceType: - type: string - enum: - - audio - - radio - - cd_player - - receiver - - soundbar - - hdmi_switch - - television - - projector - - set_top_box - - media_player - - dvd_player - - bluray_player - - climate - - light - - various - DiscoveryType: - type: string + Update model for an entity. + + - Specified properties will update the current values. + - An empty value will delete the currently set property. + properties: + name: + $ref: '#/components/schemas/LanguageText' + icon: + $ref: '#/components/schemas/IconIdentifier' + description: + $ref: '#/components/schemas/LanguageText' + Entity: description: | - Device discovery type: - - `BT`: Bluetooth - - `NET`: LAN or WAN network - enum: - - BT - - NET - DockConfiguration: + Configured entity in the remote to be used in one or more user profiles. + + See [entity documentation](https://github.com/unfoldedcircle/core-api/blob/main/doc/entities/) + for more information. type: object properties: - dock_id: - $ref: '#/components/schemas/DockId' - name: - $ref: '#/components/schemas/DockName' - custom_ws_url: - $ref: '#/components/schemas/DockUrl' - resolved_ws_url: - type: string - maxLength: 64 - description: Resolved WebSocket URL from the service name in `dock_id` if no `custom_ws_url` is used. - active: - type: boolean + entity_id: + $ref: '#/components/schemas/EntityId' + entity_type: + $ref: '#/components/schemas/EntityType' + integration_id: + $ref: '#/components/schemas/IntegrationId' + device_class: description: | - Enable flag: active docks are automatically connected when network is available. - model: - type: string - description: Dock model number. - revision: - type: string - description: Dock revision. - serial: - type: string - description: Dock serial number. - led_brightness: - type: integer - minimum: 0 - maximum: 100 - eth_led_brightness: - type: integer - minimum: 0 - maximum: 100 - connection_type: + Optional device type. This can be used by the UI to represent the entity with a different + icon, behaviour etc. See entity documentation for available device classes. type: string + name: + $ref: '#/components/schemas/LanguageText' + icon: + $ref: '#/components/schemas/IconIdentifier' + features: description: | - Network connection of the dock: `Ethernet` or `WiFi`. - version: - type: string - description: Firmware version - state: - $ref: '#/components/schemas/DockState' - learning_active: - type: boolean - description: Dock is in IR learning mode. - port_count: - type: integer - minimum: 0 - ports: - description: 3️⃣ External port mode configuration. + Supported features of the entity. See entity documentation for available features. type: array items: - $ref: '#/components/schemas/ExternalPortConfiguration' - volume: - description: 3️⃣ Speaker volume. - type: integer - minimum: 0 - maximum: 100 + type: string + options: + description: | + Feature options. See entity documentation for available options. + type: object description: - $ref: '#/components/schemas/Description' + $ref: '#/components/schemas/LanguageText' + attributes: + description: | + Dynamic entity attributes set by the integration driver. These are key/value pairs, see [integration entity + documentation](https://github.com/unfoldedcircle/core-api/tree/main/doc/entities) for detailed information. + type: object required: - - dock_id - - active - DockConfigurations: + - entity_id + - entity_type + - integration_id + - name + Entities: type: array items: - $ref: '#/components/schemas/DockConfiguration' - DockConfigurationRequest: + $ref: '#/components/schemas/Entity' + EntityDeleteRequest: type: object + description: | + Delete request model for multiple entities. Either specify `integration_id` or `entity_ids`. properties: - dock_id: - $ref: '#/components/schemas/DockId' - name: - $ref: '#/components/schemas/DockName' - custom_ws_url: - $ref: '#/components/schemas/DockUrl' - token: - $ref: '#/components/schemas/DockToken' - active: - type: boolean - description: | - Enable flag: active docks are automatically connected when network is available. - model: + integration_id: type: string - description: Dock model number. - description: - $ref: '#/components/schemas/Description' - required: - - dock_id - - active - DockUpdateRequest: + entity_ids: + type: array + items: + type: string + EntityCommand: + description: | + Entity command object. The `entity_id` only has to be specified if it's not already included as a parameter in the URL. type: object properties: - name: - type: string - maxLength: 40 - description: User assignable friendly name to use instead of dock_id (service name). - custom_ws_url: - $ref: '#/components/schemas/DockUrl' - token: - type: string - maxLength: 40 - description: Access token to connect to the dock. - active: - type: boolean - description: Auto connect to dock when network is available. - description: + entity_id: + $ref: '#/components/schemas/EntityId' + cmd_id: + description: | + Entity command identifier, as returned in the entity command metadata. + + This identifier may change at any time and may not be used for logic decisions in a client! + If entity specific information is required, the entity object must be loaded from the `entity_id`. type: string - description: Optional description. - wifi: + params: + description: | + Optional command parameters as key / value pairs. See entity documentation for available parameters. type: object - properties: - ssid: - description: Network name (Service Set IDentifier) - type: string - maxLength: 32 - password: - type: string - maxLength: 63 - DockDiscovery: + required: + - cmd_id + examples: + - entity_id: hass.main.light.living-room + cmd_id: light.on + params: + hue: 180 + saturation: 90 + MediaClass: + description: | + The media class is for browser/structure semantics. + It represents how a media item should be presented and organized in the media browser hierarchy. + + - Common values are defined as enum variants. Using these values is recommended, so the UI can show media type + specific information like icons. + - Integrations can use their custom values. Short identifiers like URIs are recommended. + type: string + maxLength: 255 + anyOf: + - enum: + - album + - app + - artist + - channel + - composer + - directory + - episode + - game + - genre + - image + - movie + - music + - playlist + - podcast + - radio + - season + - track + - tv_show + - url + - video + - {} + MediaContentType: + description: | + The media content type is for playback/content semantics. + It represents the type of the media content to play or that is currently playing. + + Notes: + - Common values are defined as enum variants. Using these values is recommended, so the UI can show media type + specific information like icons. + - Integrations can use their custom values. Short identifiers like URIs are recommended. + type: string + maxLength: 255 + anyOf: + - enum: + - album + - app + - apps + - artist + - channel + - channels + - composer + - episode + - game + - genre + - image + - movie + - music + - playlist + - podcast + - radio + - season + - track + - tv_show + - url + - video + - {} + BrowseMediaItem: type: object properties: - id: - $ref: '#/components/schemas/DockId' - configured: + media_id: description: | - Dock configuration flag for this remote: - - true: device has already been configured - - false: device has not yet been configured - type: boolean - friendly_name: - $ref: '#/components/schemas/DockName' - address: - description: Resolved device network address. + Unique identifier of the media item. Integration dependent. + Use an empty value only for special non-playable media items, for example, a root directory in a media library or search result. type: string - model: - description: Detected dock model. + maxLength: 255 + title: + description: Display name. type: string - version: - description: Detected firmware version. + minLength: 1 + maxLength: 255 + subtitle: + description: Optional subtitle. type: string - discovery_type: - $ref: '#/components/schemas/DiscoveryType' - timestamp: - description: Timestamp of dock discovery. + minLength: 1 + maxLength: 255 + artist: + description: Optional artist name. type: string - format: date-time - bt: - type: object - description: Optional Bluetooth discovery information. Not present for network device. - properties: - signal: - description: 'Bluetooth signal strength. 0 = min, 5 = max.' - type: integer - minimum: 0 - maximum: 5 - last_seen_sec: - description: | - Last time the device was seen on a Bluetooth scan. Values over 15 sec indicate that the device is no longer - reachable. - type: integer - format: int32 - required: - - id - - configured - - discovery_type - DockDiscoveryStatus: - type: object - properties: - active: + minLength: 1 + maxLength: 255 + album: + description: Optional album name. + type: string + minLength: 1 + maxLength: 255 + media_class: + $ref: '#/components/schemas/MediaClass' + media_type: + $ref: '#/components/schemas/MediaContentType' + can_browse: + description: If `true`, the item can be browsed (is a container) by using `media_id` and `media_type`. + type: boolean + default: false + can_play: description: | - Dock discovery still active or not. + If `true`, the item can be played directly using the `play_media` command with `media_id` and `media_type`. type: boolean - docks: + default: false + can_search: + description: | + If `true`, a search can be performed on the item using `search_media` with `media_id` and `media_type`. + type: boolean + default: false + thumbnail: + description: | + URL to download the media artwork, or a base64 encoded PNG or JPG image. + The preferred size is 480x480 pixels. + Use the following URI prefix to use a provided icon: `icon://uc:`, for example, `icon://uc:music`. + Please use a URL whenever possible. Encoded images should be as small as possible. + type: string + minLength: 1 + maxLength: 32768 + duration: + description: Duration in seconds. + type: integer + items: + description: | + Child items if this item is a container. Child items may not contain further child items (only one level + of nesting is supported). A new browse request must be sent for deeper levels. type: array items: - $ref: '#/components/schemas/DockDiscovery' + $ref: '#/components/schemas/BrowseMediaItem' required: - - discovery_active - - docks - DockFirmwareUpdate: + - media_id + - title + MediaBrowseResponse: type: object - description: Dock firmware information properties: - model: - description: Dock model - type: string - description: - $ref: '#/components/schemas/LanguageText' - version: - type: string - channel: - $ref: '#/components/schemas/UpdateChannel' - release_date: - type: string - format: date - size: - type: integer - format: int64 - release_notes_url: - type: string - format: uri - download: - $ref: '#/components/schemas/UpdateDownloadState' - required: - - model - - description - - version - DockId: + media: + $ref: '#/components/schemas/BrowseMediaItem' + SearchMediaItem: + description: | + A media item that was found by a search. Currently identical in shape to `BrowseMediaItem`. + Defined as a composition to allow search-specific fields (e.g. relevance score) to be added in the future + without a breaking change. + + A search media item may not contain any child `items`. + allOf: + - $ref: '#/components/schemas/BrowseMediaItem' + MediaSearchResponse: + type: array + items: + $ref: '#/components/schemas/SearchMediaItem' + SimpleId: type: string - format: '^[a-zA-Z0-9\-\.]+$' + format: ^[a-zA-Z0-9\-_\.]+$ minLength: 1 - maxLength: 64 - description: Dock identifier - DockName: + maxLength: 36 + description: Simple string identifier, also usable as URL parameter or file identifier + ActivityFeature: + description: | + Supported features of the activity. If the activity has an `off` sequence, it supports the common `on_off` + feature, otherwise only `start`. type: string - minLength: 1 - maxLength: 40 - description: User assignable friendly name to use instead of dock_id (service name). - DockSystemInfo: + enum: + - on_off + - start + ActivityOverview: + description: | + The activity entity executes a sequence of commands and at the end displays a user interface (similar to remote entity) + to the user. If the entity has an off sequence, it can be turned off. type: object - properties: - name: - type: string - hostname: - type: string - model: - type: string - revision: - type: string - version: - type: string - serial: - type: string - ir_learning: - type: boolean - ethernet: - type: boolean - wifi: - type: boolean - ssid: - description: Network name (Service Set IDentifier) - type: string - CreateDockSetup: + allOf: + - $ref: '#/components/schemas/Entity' + - properties: + entity_type: + type: string + enum: + - activity + features: + description: | + Supported features of the activity. If the activity has an `off` sequence, it supports the common `on_off` + feature, otherwise only `start`. + type: array + items: + $ref: '#/components/schemas/ActivityFeature' + options: + type: object + properties: + editable: + description: | + - `true` / property missing: activity was created by UC Remote and can be edited. + - `false`: activity was provided by an integration and cannot be edited. + type: boolean + default: true + activity_group: + $ref: '#/components/schemas/EntityId' + Activities: + type: array + items: + $ref: '#/components/schemas/ActivityOverview' + ActivityCreate: + description: | + Dedicated request object to create a new activity. type: object - oneOf: - - type: object - properties: - discovery: - $ref: '#/components/schemas/DockSetupFromDiscovery' - required: - - discovery - - type: object - properties: - manually: - $ref: '#/components/schemas/DockSetup' - required: - - manual - DockSetup: + allOf: + - properties: + name: + $ref: '#/components/schemas/LanguageText' + icon: + $ref: '#/components/schemas/IconIdentifier' + description: + $ref: '#/components/schemas/LanguageText' + - oneOf: + - type: object + properties: + clone_from: + $ref: '#/components/schemas/EntityId' + required: + - clone_from + - type: object + properties: + clone_from: false + options: + type: object + properties: + entity_ids: + type: array + items: + $ref: '#/components/schemas/EntityId' + required: + - entity_ids + required: + - name + ActivityGroupInfo: + description: | + Minimal activity group information to use in a user interface with it's friendly name and icon. type: object - description: Dock setup data properties: + group_id: + $ref: '#/components/schemas/EntityId' name: - $ref: '#/components/schemas/DockName' - token: - $ref: '#/components/schemas/DockToken' - custom_ws_url: - $ref: '#/components/schemas/DockUrl' - description: - $ref: '#/components/schemas/Description' - wifi: - description: | - Optional WiFi information if the dock should connect to (or be prepared for) WiFi instead of Ethernet. - type: object - properties: - ssid: - description: Network name (Service Set IDentifier) - type: string - password: - type: string - format: password - required: - - ssid - - password + $ref: '#/components/schemas/LanguageText' + icon: + $ref: '#/components/schemas/IconIdentifier' required: + - group_id - name - DockSetupFromDiscovery: + TouchSliderTarget: + description: The target entity feature to control. type: object properties: - id: - $ref: '#/components/schemas/DockId' - friendly_name: - $ref: '#/components/schemas/DockName' - address: - description: Resolved device network address. - type: string - model: - description: Detected dock model. - type: string - version: - description: Detected firmware version. + entity_id: + $ref: '#/components/schemas/EntityId' + feature: + description: | + The feature to control. One of the listed entity features. + The default slider feature is controlled if not specified. type: string - discovery_type: - $ref: '#/components/schemas/DiscoveryType' required: - - id - - discovery_type - DockSetupError: - type: string - enum: - - NONE - - NOT_FOUND - - CONNECTION_ERROR - - CONNECTION_REFUSED - - AUTHORIZATION_ERROR - - TIMEOUT - - ABORT - - PERSISTENCE_ERROR - - OTHER - DockSetupInfo: - type: object - description: Dock setup state - properties: - id: - type: string - name: - $ref: '#/components/schemas/DockName' - discovery_type: - $ref: '#/components/schemas/DiscoveryType' - state: - $ref: '#/components/schemas/DockSetupState' - error: - $ref: '#/components/schemas/DockSetupError' - required: - - id - - state - DockSetupState: - type: string - enum: - - NEW - - CONFIGURING - - UPLOADING - - RESTARTING - - OK - - ERROR - DockState: - type: string - description: Dock connection state - enum: - - IDLE - - CONNECTING - - ACTIVE - - RECONNECTING - - ERROR - DockToken: - type: string - format: password - minLength: 1 - maxLength: 40 - description: Access token - DockUpdateCheck: + - entity_id + TouchSliderUiCfg: + description: | + Remote 3 touch slider configuration. Assign the touch slider to a specific entity feature on a UI screen. + + If no target is specified, the default slider feature is active, unless disabled with the `enabled` property. + + - `enabled: false`: disables the touch slider on the UI screen. Any `target` configuration is removed during update. + - `enabled: true` and no `target`: the default slider feature is active on the UI screen. + - `enabled: true` and `target`: the `target` entity feature is active on the UI screen. type: object - description: Dock firmware update check information. properties: - dock_id: - type: string - version: - description: Installed firmware version. - type: string - update_available: - description: Whether or not an update is available. An available update is set in the `firmware_update` object. - type: boolean - update_check_enabled: + enabled: description: | - Whether or not the online update check is enabled or not. If disabled, `update_available` will always be false. + Enables or disables the touch slider. If set to false the slider is not active. + This affects the optional `target` configuration and the default slider feature. type: boolean - firmware_update: - $ref: '#/components/schemas/DockFirmwareUpdate' - update_id: - description: Update identifier if an update is currently in progress. - type: string + default: true + target: + $ref: '#/components/schemas/TouchSliderTarget' required: - - dock_id - - version - - update_available - - update_check_enabled - DockUpdateProgress: + - enabled + VoiceAssistantTarget: + description: The specific voice assistant to use. type: object - description: Dock firmware update progress properties: - dock_id: - type: string - update_id: - description: Update identifier - type: string - version: - description: Firmware version being installed - type: string - progress: - description: Update progress in percent - type: integer - format: int32 - minimum: 0 - maximum: 100 - state: - $ref: '#/components/schemas/DockSetupState' - error: - $ref: '#/components/schemas/DockSetupError' + entity_id: + $ref: '#/components/schemas/EntityId' + available: + description: | + Flag indicating if the referenced `entity_id` is still available or is a dangling reference. + type: boolean + profile_id: + $ref: '#/components/schemas/SimpleId' required: - - dock_id - - update_id - - version - - state - DockUrl: - type: string - maxLength: 64 - description: Dock WebSocket URL to override auto-discovery from the service name in `dock_id`. - ExternalPortConfigurations: - type: array - items: - $ref: '#/components/schemas/ExternalPortConfiguration' - ExternalPortConfiguration: + - entity_id + VoiceAssistantUiCfg: description: | - External port configuration. - - `mode`: configured operation mode. - - `active_mode`: active operation mode, usually only set with the detected peripheral for `mode: AUTO`. + UI-specific voice assistant configuration. Overrides the global voice assistant. + + - The default voice assistant is used if no target is specified. + - The voice assistant is activated with the voice button. + - A custom voice button command mapping is ignored if a global or a UI-specific voice assistant is configured. type: object properties: - port: - $ref: '#/components/schemas/ExternalPortNumber' - readOnly: true - mode: - $ref: '#/components/schemas/ExternalPortMode' - active_mode: - $ref: '#/components/schemas/ExternalPortActiveMode' - readOnly: true - supported_modes: - description: Supported modes of the port. + target: + $ref: '#/components/schemas/VoiceAssistantTarget' + IncludedEntity: + description: | + When saving an activity only the `entity_id` is persisted. When retrieving an activity all other fields + will be retrieved from the real entities to make sure they are up to date. I.e. the entity name or icon + might change between saving an activity and retrieving it again! + type: object + properties: + entity_id: + $ref: '#/components/schemas/EntityId' + entity_type: + $ref: '#/components/schemas/EntityType' + name: + $ref: '#/components/schemas/LanguageText' + icon: + $ref: '#/components/schemas/IconIdentifier' + integration: + description: | + Optional integration information. Regular entities will have at least the integration name. Special + entities like activities and macros might omit the integration object. + type: object + properties: + name: + $ref: '#/components/schemas/LanguageText' + icon: + $ref: '#/components/schemas/IconIdentifier' + entity_commands: + description: | + Supported entity command identifiers. A command identifier refers to the common entity command + definitions, which describe all required parameters to set for calling the entity command. This + includes the mandatory `cmd_id` attribute and optional parameters. type: array items: - $ref: '#/components/schemas/ExternalPortMode' - readOnly: true - uart: - $ref: '#/components/schemas/UartConfiguration' + type: string + simple_commands: + description: | + Simple commands are additional commands supported by the entity, which are not included in the + common entity command definitions. A typical example are remote-entity commands like `VOLUME_UP` etc + which don't have additional parameters. A simple command relates directly to the `cmd_id` attribute + when calling a command. + type: array + items: + type: string + available: + description: | + State of the entity: True / missing = entity is available as configured entity and can be used. + False = entity has been removed and must be corrected by the user. + + If an entity is no longer available then all usages in the sequences are still present in case the + entity is re-configured. The execution of the on- or off-sequence will then simply skip the actions + of the no longer available entity. + type: boolean required: - - port - - mode - ExternalPortConfigurationRequest: + - entity_id + IncludedEntities: + description: | + Included entities in an activity or macro. This object is writable from the client and persisted when saving. + + Notes: + - Entities can be included without being used in a sequence. + This allows to edit the activity or macro in multiple sessions without having to reselect the desired entities. + - Every used entity in a sequence must be included, otherwise the activity or macro cannot be saved. + - If the client removes an entity which is included in an activity or macro, it must make sure to also remove all + entity references the sequence(s), button mapping and user interface. + type: array + items: + $ref: '#/components/schemas/IncludedEntity' + CommandSequenceEntity: + description: Entity command step in a command sequence. type: object properties: - mode: - $ref: '#/components/schemas/ExternalPortMode' - uart: - $ref: '#/components/schemas/UartConfiguration' + type: + const: command + command: + $ref: '#/components/schemas/EntityCommand' required: - - mode - ExternalPortNumber: - description: 1-based port index number. - type: integer - minimum: 1 - ExternalPortMode: - type: string - enum: - - AUTO - - NONE - - INFRARED - - IR_BLASTER - - IR_EMITTER_MONO_PLUG - - IR_EMITTER_STEREO_PLUG - - TRIGGER_5V - - RS232 - ExternalPortActiveMode: - type: string - enum: - - UNKNOWN - - NONE - - ERROR - - INFRARED - - IR_BLASTER - - IR_EMITTER_MONO_PLUG - - IR_EMITTER_STEREO_PLUG - - TRIGGER_5V - - RS232 - UartConfiguration: + - type + - command + examples: + - type: command + command: + entity_id: hass.main.light.living-room + cmd_id: 'on' + params: + brightness: 75 + CommandSequenceDelay: + description: Delay step in a command sequence. type: object properties: - baud_rate: - $ref: '#/components/schemas/UartBaudRate' - data_bits: - $ref: '#/components/schemas/UartDataBits' - stop_bits: - $ref: '#/components/schemas/UartStopBits' - parity: - $ref: '#/components/schemas/UartParity' + type: + const: delay + delay: + description: Delay in milliseconds. + type: integer + minimum: 1 required: - - baud_rate - - data_bits - - stop_bits - - parity - UartBaudRate: - description: | - Common baud rate values: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200 - type: integer - minimum: 300 - maximum: 115200 - default: 9600 - UartDataBits: - type: integer - minimum: 5 - maximum: 8 - default: 8 - UartStopBits: - description: 'Stop bits must be set as string, number format is not supported!' - type: string - enum: - - '1' - - '1.5' - - '2' - default: '1' - UartParity: - type: string - enum: - - none - - even - - odd - default: none - DriverDeveloper: + - type + - delay + examples: + - type: delay + delay: 100 + CommandSequence: + description: Sequence of commands to execute. + type: array + items: + oneOf: + - $ref: '#/components/schemas/CommandSequenceEntity' + - $ref: '#/components/schemas/CommandSequenceDelay' + discriminator: + propertyName: type + mapping: + command: '#/components/schemas/CommandSequenceEntity' + delay: '#/components/schemas/CommandSequenceDelay' + ActivitySequences: type: object - description: Optional information about the integration developer. properties: - name: - description: Optional developer information to display in UI / web-configurator. - type: string - maxLength: 100 - url: - description: Optional developer home page. - type: string - format: uri - maxLength: 255 - email: - description: Optional developer contact email. - type: string - format: email - maxLength: 100 - DriverId: + 'on': + $ref: '#/components/schemas/CommandSequence' + 'off': + $ref: '#/components/schemas/CommandSequence' + ButtonId: type: string - format: '^[a-zA-Z0-9\-_]+$' + format: ^[A-Z0-9_]+$ minLength: 1 - maxLength: 36 - description: 'Unique integration driver identifier, e.g. `homeassistant`, `homey`, etc.' - DriverState: - type: string - enum: - - NOT_CONFIGURED - - IDLE - - CONNECTING - - ACTIVE - - RECONNECTING - - ERROR - Entities: + maxLength: 20 + description: Physical button identification + DeviceButtonMapping: + type: object + properties: + button: + $ref: '#/components/schemas/ButtonId' + short_press: + $ref: '#/components/schemas/EntityCommand' + long_press: + $ref: '#/components/schemas/EntityCommand' + required: + - button + DeviceButtonMappings: + description: | + Physical button mapping to entity commands. The `entity_id` in the EntityCommand object is a required + property for an activity and ignored for a remote-entity. type: array items: - $ref: '#/components/schemas/Entity' - Entity: - description: | - Configured entity in the remote to be used in one or more user profiles. - - See [entity documentation](https://github.com/unfoldedcircle/core-api/blob/main/doc/entities/) - for more information. + $ref: '#/components/schemas/DeviceButtonMapping' + GridSize: + description: Grid layout size. type: object properties: - entity_id: - $ref: '#/components/schemas/EntityId' - entity_type: - $ref: '#/components/schemas/EntityType' - integration_id: - $ref: '#/components/schemas/IntegrationId' - device_class: - description: | - Optional device type. This can be used by the UI to represent the entity with a different - icon, behaviour etc. See entity documentation for available device classes. - type: string - name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' - features: - description: | - Supported features of the entity. See entity documentation for available features. - type: array - items: - type: string - options: - description: | - Feature options. See entity documentation for available options. - type: object - description: - $ref: '#/components/schemas/LanguageText' - attributes: - description: | - Dynamic entity attributes set by the integration driver. These are key/value pairs, see [integration entity - documentation](https://github.com/unfoldedcircle/core-api/tree/main/doc/entities) for detailed information. - type: object + width: + type: integer + minimum: 1 + height: + type: integer + minimum: 1 required: - - entity_id - - entity_type - - integration_id - - name - EntityId: + - width + - height + UserInterfaceItemType: + description: | + Type of the user interface item: + - `icon`: show an icon, either a UC icon or a custom icon. Field `icon` must contain the icon identifier. + - `text`: show text only from field `text`. + - `media_player`: show media information from the specified media-player entity specified in `media_player_id`. + The specified entity_id must be part of the included entities in the activity and of type media-player. + - `select`: show a select box with the specified options from the select entity's `options` attribute. + - `sensor`: show sensor value from the specified sensor entity specified in the `sensor` configuration object. type: string - format: '^[a-zA-Z0-9\-_\.]+$' - minLength: 5 - maxLength: 110 - description: Unique UC Remote identifier over all entities and integrations. - EntityCommand: + enum: + - icon + - text + - numpad + - media_player + - select + - sensor + UserInterfaceItemSelect: description: | - Entity command object. The `entity_id` only has to be specified if it's not already included as a parameter in the URL. + Select item configuration. + By default, only the selected option value in the `current_option` attribute is shown from the specified + select-entity. + If the user interface `text` field is set, it is used as a widget label, except if `show_name` is set to true. + If no widget label should be shown, omit the item's `text` field and set `show_name` to false. type: object properties: - entity_id: + select_id: $ref: '#/components/schemas/EntityId' - cmd_id: - description: | - Entity command identifier, as returned in the entity command metadata. - - This identifier may change at any time and may not be used for logic decisions in a client! - If entity specific information is required, the entity object must be loaded from the `entity_id`. - type: string - params: - description: | - Optional command parameters as key / value pairs. See entity documentation for available parameters. - type: object + show_name: + description: Show the select-entity name as widget label instead of the user interface item's `text` field. + type: boolean + default: false required: - - cmd_id - example: - entity_id: hass.main.light.living-room - cmd_id: light.on - params: - hue: 180 - saturation: 90 - EntityCmdParamBool: - type: object - description: Boolean value parameter. - EntityCmdParamNumber: - type: object + - select_id + UserInterfaceItemSensor: description: | - Number value parameter with optional limits. - properties: - default: - description: 'Default value to use, e.g. in a UI editor.' - min: - description: Minimal allowed value (inclusive). - type: number - default: 0 - max: - description: Maximal allowed value (inclusive). - type: number - step: - description: Step size between values. - type: number - default: 1 - unit: - description: Optional unit label of the value. - type: string - example: - default: 22 - min: 0 - max: 100 - step: 1 - unit: '%' - EntityCmdParamRegex: + Sensor item configuration. + By default, only the sensor value and unit is shown from the specified sensor entity. + If the user interface `text` field is set, it is used as sensor label, except if `show_label` is set to true. + If no widget label should be shown, omit the item's `text` field and set `show_label` to false. type: object - description: Text value parameter with optional regex validation. properties: - regex: - description: Validation regex. - type: string - EntityCmdParamEnum: + sensor_id: + $ref: '#/components/schemas/EntityId' + show_label: + description: Show the sensor label instead of the user interface item's `text` field. + type: boolean + default: false + show_unit: + description: Show sensor unit if available. Not shown for binary sensors. + type: boolean + default: true + required: + - sensor_id + GridLocation: + description: Button placement in the grid with 0-based coordinates. type: object - description: Enumeration parameter. Only the defined values are allowed as parameter value. properties: - values: - type: array - items: - type: string - default: - description: Default value for a new command. Must be a value defined in `values` - type: string + x: + type: integer + minimum: 0 + 'y': + type: integer + minimum: 0 required: - - values - example: - values: - - Option 1 - - Option 2 - - Option 3 - default: Option 1 - EntityCmdParamSelection: + - x + - 'y' + GridItemSize: + description: 'Item size in the button grid. Default size if not specified: 1 x 1' type: object - description: Text value parameter with a selection list from another entity field. properties: - items: - description: Validation regex. - type: object - properties: - source: - description: Where to load the selection list from. - type: string - enum: - - attributes - - options - field: - description: | - Field name in the source object containing an array of strings for the parameter selection - type: string - required: - - source - - field - required: - - items - example: - items: - source: attributes - field: source_list - EntityCommandMetadata: + width: + type: integer + minimum: 1 + default: 1 + height: + type: integer + minimum: 1 + default: 1 + UserInterfaceItem: + description: | + A user interface item is either an icon, text, sensor value or media information from a media-player entity. + - Icon and text items can be static or linked to a command specified in the `command` field. + - The command object can only be used for `icon` and `text` items. + - Default size is 1x1 if not specified. type: object properties: - id: - description: | - Entity command identifier to be used in activity and macro commands (button mappings, UI elements and sequences). - - This identifier may change at any time and may not be used for logic decisions in a client! - If entity specific information is required, the entity object must be used. - type: string - cmd_id: - description: | - Entity command as specified in the [entity documentation](https://github.com/unfoldedcircle/core-api/tree/main/doc/entities). - This is the command identifier being sent to integration drivers. + type: + $ref: '#/components/schemas/UserInterfaceItemType' + icon: + $ref: '#/components/schemas/IconIdentifier' + text: type: string + minLength: 1 + maxLength: 50 + media_player_id: + $ref: '#/components/schemas/EntityId' + select: + $ref: '#/components/schemas/UserInterfaceItemSelect' + sensor: + $ref: '#/components/schemas/UserInterfaceItemSensor' + command: + $ref: '#/components/schemas/EntityCommand' + location: + $ref: '#/components/schemas/GridLocation' + size: + $ref: '#/components/schemas/GridItemSize' + required: + - type + - location + ActivityUserInterfacePage: + type: object + properties: + page_id: + $ref: '#/components/schemas/SimpleId' name: - $ref: '#/components/schemas/LanguageText' - params: - description: | - Metadata describing the optional parameters of the command. Simple "button like" commands - don't have any parameters, whereas e.g. a light entity can also dim the light, change color or color - temperature. + description: Optional page name + type: string + grid: + $ref: '#/components/schemas/GridSize' + items: type: array items: - type: object - allOf: - - properties: - name: - $ref: '#/components/schemas/LanguageText' - param: - description: Parameter name. - type: string - type: - description: Parameter type. - type: string - enum: - - number - - bool - - regex - - enum - required: - - name - - param - - type - - oneOf: - - $ref: '#/components/schemas/EntityCmdParamNumber' - - $ref: '#/components/schemas/EntityCmdParamBool' - - $ref: '#/components/schemas/EntityCmdParamRegex' - - $ref: '#/components/schemas/EntityCmdParamEnum' - - $ref: '#/components/schemas/EntityCmdParamSelection' - discriminator: - propertyName: type - mapping: - number: '#/components/schemas/EntityCmdParamNumber' - bool: '#/components/schemas/EntityCmdParamBool' - regex: '#/components/schemas/EntityCmdParamRegex' - enum: '#/components/schemas/EntityCmdParamEnum' - selection: '#/components/schemas/EntityCmdParamSelection' + $ref: '#/components/schemas/UserInterfaceItem' required: - - id - - cmd_id - - name - EntityUpdateRequest: + - page_id + - grid + - items + ActivityUserInterface: type: object + properties: + pages: + type: array + items: + $ref: '#/components/schemas/ActivityUserInterfacePage' + SequenceState: description: | - Update model for an entity. + State of an Activity or Macro sequence: + - `RUNNING`: Sequence is currently running + - `COMPLETED`: Final state for a macro + - `ON`: Final activity state for the `on` sequence + - `OFF`: Final activity state for the `off` sequence + - `STOPPED`: The sequence was aborted with a stop request + - `TIMEOUT`: The sequence timed out and was aborted + - `ERROR`: There was an error running the sequence and did not complete + type: string + enum: + - RUNNING + - COMPLETED + - 'ON' + - 'OFF' + - STOPPED + - TIMEOUT + - ERROR + Activity: + description: | + The activity entity executes a sequence of commands and at the end displays a user interface (similar to remote entity) + to the user. If the entity has an off sequence, it can be turned off. + type: object + allOf: + - $ref: '#/components/schemas/Entity' + - properties: + entity_type: + type: string + enum: + - activity + features: + description: | + Supported features of the activity. If the activity has an `off` sequence, it supports the common `on_off` + feature, otherwise only `start`. + type: array + items: + $ref: '#/components/schemas/ActivityFeature' + options: + type: object + properties: + editable: + description: | + - `true` / property missing: activity was created by UC Remote and can be edited. + - `false`: activity was provided by an integration and cannot be edited. + type: boolean + default: true + activity_group: + $ref: '#/components/schemas/ActivityGroupInfo' + prevent_sleep: + description: Prevent the device to go to sleep while activity is on. + type: boolean + ready_check: + description: | + Readiness check when turning the activity on or off. + Checks if entities in the on- or off-sequence are available before running the sequence. + type: boolean + default: true + touch_slider: + $ref: '#/components/schemas/TouchSliderUiCfg' + voice_assistant: + $ref: '#/components/schemas/VoiceAssistantUiCfg' + included_entities: + $ref: '#/components/schemas/IncludedEntities' + sequences: + $ref: '#/components/schemas/ActivitySequences' + button_mapping: + $ref: '#/components/schemas/DeviceButtonMappings' + user_interface: + $ref: '#/components/schemas/ActivityUserInterface' + attributes: + type: object + properties: + state: + $ref: '#/components/schemas/SequenceState' + required: + - options + - attributes + ActivityUpdate: + description: | + Dedicated request object to update an existing activity. + All root properties are optional and only the provided objects are updated in the activity. Omitted objects are + ignored and not deleted from the activity. - - Specified properties will update the current values. - - An empty value will delete the currently set property. + The `entity_ids` object must be managed by the client and is persisted when updating an activity. + + Notes: + - Entities can be included in `entity_ids` without being used in `sequences`. + This allows to edit the activity in multiple sessions without having to reselect the desired entities. + - Every referenced entity in `sequences` must be included in `entity_ids`, otherwise the activity cannot be saved. + - If the client removes a configured entity from the system which is included in an activity, it must make sure to + also remove all references in the activity. See `IncludedEntity.available` property in the included entities + object when retrieving an activity. + - Remote 3: The `touch_slider` configuration requires an entity included in `entity_ids`. + type: object properties: name: $ref: '#/components/schemas/LanguageText' @@ -13446,989 +13615,624 @@ components: $ref: '#/components/schemas/IconIdentifier' description: $ref: '#/components/schemas/LanguageText' - EntityDeleteRequest: + options: + type: object + properties: + prevent_sleep: + description: Prevent the device to go to sleep while activity is on. + type: boolean + ready_check: + description: | + Readiness check when turning the activity on or off. + Checks if entities in the on- or off-sequence are available before running the sequence. + type: boolean + touch_slider: + $ref: '#/components/schemas/TouchSliderUiCfg' + voice_assistant: + $ref: '#/components/schemas/VoiceAssistantUiCfg' + entity_ids: + type: array + items: + $ref: '#/components/schemas/EntityId' + sequences: + $ref: '#/components/schemas/ActivitySequences' + ActivityUserInterfacePageUpdate: type: object - description: | - Delete request model for multiple entities. Either specify `integration_id` or `entity_ids`. properties: - integration_id: + name: + description: Optional page name type: string - entity_ids: + grid: + $ref: '#/components/schemas/GridSize' + items: + description: | + Updated user interface items. An empty array will REMOVE all items, if the property is omitted the existing + configuration is not changed. type: array items: - type: string - EntityType: + $ref: '#/components/schemas/UserInterfaceItem' + ActivityGroupState: + description: | + - `OFF`: No included activity is running. + - `ACTIVE`: An included activity is running. + - `RUNNING`: An included activity is currently running, e.g. either switching activities, or turning off. + - `ERROR`: An included activity is in an error state. type: string - description: Entity type enum: - - button - - climate - - cover - - light - - media_player - - sensor - - switch - - activity - - macro - - remote - - ir_emitter - - select - - voice_assistant - ExternalSystems: - type: array - items: - $ref: '#/components/schemas/ExternalSystem' - ExternalSystem: + - 'OFF' + - ACTIVE + - RUNNING + - ERROR + ActivityGroupOverview: + description: | + Minimal activity group object intended for an overview page, which is returned when retrieving all activities. type: object properties: - system: - $ref: '#/components/schemas/ExternalSystemId' - name: - $ref: '#/components/schemas/ExtSystemName' + group_id: + $ref: '#/components/schemas/EntityId' + name: + $ref: '#/components/schemas/LanguageText' + icon: + $ref: '#/components/schemas/IconIdentifier' + activity_count: + description: Number of included activities. + type: integer + state: + $ref: '#/components/schemas/ActivityGroupState' required: - - system + - group_id - name - ExternalSystemId: - type: string - format: '^[a-zA-Z0-9\-_]+$' - minLength: 1 - maxLength: 50 - description: Unique external system identifier registered by an R2 integration to interact with the API. - TokenId: - type: string - format: '^[a-zA-Z0-9\-_]+$' - minLength: 1 - maxLength: 36 + - activity_count + ActivityGroups: + type: array + items: + $ref: '#/components/schemas/ActivityGroupOverview' + RemoveTurnOnDelays: description: | - Unique token identifier, used for later token management through the external system or management ui. - ExtSystemName: + - `previous_cmd_skipped`: Only remove delay steps if the previous step is skipped, because the entity is in a + power-on state. + - `between_skipped_cmds`: Only remove delay steps if the previous and next power-on steps are skipped, because + the entity is already in a power-on state. + - `never`: Never remove delay steps in the on-sequence of the new activity. type: string - minLength: 1 - maxLength: 50 + enum: + - previous_cmd_skipped + - between_skipped_cmds + - never + TurnOffUnusedEntities: description: | - Friendly name of the external system to display to the user within the app. This name must be unique for an external - system and should be as short and concise as possible. - ExtAccessToken: + - `always`: Always turn off unused entities in the previous activity. + All included entities are considered, not just the ones used in the on-sequence of the new activity. + - `in_off_sequence`: Only turn off unused entities which are included in the off-sequence of the previous activity. + - `run_off_sequence`: Run the original off-sequence of the old activity and dynamically filter out power-off commands. + All power-off commands from entities used in the new activity's power-on sequence will be filtered out. + - `never`: Never turn off entities in the previous activity. type: string - minLength: 1 - maxLength: 32768 + enum: + - always + - in_off_sequence + - run_off_sequence + - never + ActivityGroupOptions: description: | - The token to access the external system with the corresponding Remote integration. - This could be a UUID, a JWT, a PEM certificate or any other representation required for the integration to - authenticate on the system. - ExtAccessTokenDescription: - type: string - maxLength: 2048 - description: Optional description of the external access token. - ExtAccessTokenUrl: - type: string - maxLength: 2048 - description: Optional URL of the external system. - ExtAccessTokenData: - type: string - maxLength: 32768 + 👷Not yet finalized! + + Activity group specific options, e.g. how delays are handled when switching between activities. + type: object + properties: + remove_turn_on_delays: + $ref: '#/components/schemas/RemoveTurnOnDelays' + turn_off_unused_entities: + $ref: '#/components/schemas/TurnOffUnusedEntities' + ActivityGroupUpdate: description: | - Optional data from the external system for the Remote integration. - ⚠️ Attention: this data is not protected and retrievable by API clients! - ExternalAccessTokens: - type: array - items: - $ref: '#/components/schemas/ExternalAccessToken' - ExternalAccessToken: + Dedicated request object to update an existing activity group. + All root properties are optional and only the provided objects are updated in the activity group. Omitted objects are + ignored and not deleted from the activity group. + + Referenced activities must exist, an empty `activity_ids` array will remove all included activities from the group. type: object properties: - system: - $ref: '#/components/schemas/ExternalSystemId' - token_id: - $ref: '#/components/schemas/TokenId' name: - $ref: '#/components/schemas/ExtSystemName' + $ref: '#/components/schemas/LanguageText' + icon: + $ref: '#/components/schemas/IconIdentifier' description: - $ref: '#/components/schemas/ExtAccessTokenDescription' - url: - $ref: '#/components/schemas/ExtAccessTokenUrl' - data: - $ref: '#/components/schemas/ExtAccessTokenData' - creation_date: - type: string - format: date-time - required: - - system - - token_id - - name - - creation_date - ExternalAccessTokenRequest: - type: object + $ref: '#/components/schemas/LanguageText' + options: + $ref: '#/components/schemas/ActivityGroupOptions' + activity_ids: + description: Entity identifiers of included activities in group. + type: array + items: + $ref: '#/components/schemas/EntityId' + IncludedActivity: description: | - The token_id can be provided by the external system. If omitted, an UUID is generated and returned in the - ExternalAccessToken response. It may not end in `-DATA` or `-URL`. + Minimal activity object to show the activity in a user interface with it's friendly name and icon. + type: object properties: - token_id: - $ref: '#/components/schemas/TokenId' + entity_id: + $ref: '#/components/schemas/EntityId' name: - $ref: '#/components/schemas/ExtSystemName' - token: - $ref: '#/components/schemas/ExtAccessToken' - description: - $ref: '#/components/schemas/ExtAccessTokenDescription' - url: - $ref: '#/components/schemas/ExtAccessTokenUrl' - data: - $ref: '#/components/schemas/ExtAccessTokenData' + $ref: '#/components/schemas/LanguageText' + icon: + $ref: '#/components/schemas/IconIdentifier' + state: + $ref: '#/components/schemas/SequenceState' required: + - entity_id - name - - token - example: - token_id: 1-2-3 - name: My smart home - token: secret-sauce-42! - description: Any other informative message about the external system - url: 'ws://smart.home' - data: 'optional: true, foo: bar, free: text' - ExternalAccessTokenResponse: - type: object + ActivityGroup: description: | - If the token identifier has been provided in the request, then then same identifier is returned, otherwise a - UUID is generated. - properties: - token_id: - $ref: '#/components/schemas/TokenId' - required: - - token_id - FriendlyName: - type: string - maxLength: 64 - GridItemSize: - description: 'Item size in the button grid. Default size if not specified: 1 x 1' - type: object - properties: - width: - type: integer - minimum: 1 - default: 1 - height: - type: integer - minimum: 1 - default: 1 - GridLocation: - description: Button placement in the grid with 0-based coordinates. - type: object - properties: - x: - type: integer - minimum: 0 - 'y': - type: integer - minimum: 0 - required: - - x - - 'y' - Group: + An activity group creates a dependency between multiple activities. Switching between activities will consider + the current state of the included entities and only turn-on or -off the required entities. type: object - description: | - The shown group switch in the UI is automatically determined by the capabilities of the group's entities. properties: group_id: - $ref: '#/components/schemas/SimpleId' - profile_id: - $ref: '#/components/schemas/SimpleId' + $ref: '#/components/schemas/EntityId' name: - $ref: '#/components/schemas/Name' + $ref: '#/components/schemas/LanguageText' icon: $ref: '#/components/schemas/IconIdentifier' - entities: + description: + $ref: '#/components/schemas/LanguageText' + options: + $ref: '#/components/schemas/ActivityGroupOptions' + activities: + description: Included activities in the group. type: array - description: Entity identifiers belonging to the group items: - $ref: '#/components/schemas/EntityId' - description: - $ref: '#/components/schemas/Description' + $ref: '#/components/schemas/IncludedActivity' required: - group_id - - profile_id - name - - entities - GroupUpdate: - type: object - properties: - name: - $ref: '#/components/schemas/Name' - icon: - $ref: '#/components/schemas/IconIdentifier' - entities: - type: array - description: | - Changed or re-ordered group entities. - An empty array remove all entities. - If the property is not specified the defined entities will not be changed. - items: - $ref: '#/components/schemas/EntityId' - description: - $ref: '#/components/schemas/Description' - Groups: - type: array - items: - $ref: '#/components/schemas/Group' - HealthStatus: + - options + - activities + MacroFeature: type: string enum: - - Healthy - - Degraded - - Unhealthy - IconIdentifier: - type: string - format: '^[a-z][a-z0-9]+:[a-zA-Z0-9\-_\.]+$' - maxLength: 255 + - start + MacroOverview: description: | - Optional icon identifier. The identifier consists of a prefix and a resource identifier, separated by `:`. - Available prefixes: - - `uc:` - integrated icon font - - `custom:` - custom icon resource - - `ctv:` - custom TV icon resource - - Other prefixes might be rejected by the service. - - An empty identifier, while updating the object, removes the existing icon. - ImageIdentifier: - type: string - format: '^[a-z][a-z0-9]+:[a-zA-Z0-9\-_\.]+$' - maxLength: 255 + The macro entity executes a sequence of commands. + type: object + allOf: + - $ref: '#/components/schemas/Entity' + - properties: + entity_type: + type: string + enum: + - macro + features: + description: | + Supported features of the macro. + type: array + items: + $ref: '#/components/schemas/MacroFeature' + options: + type: object + properties: + editable: + description: | + - `true` / property missing: macro was created by UC Remote and can be edited. + - `false`: macro was provided by an integration and cannot be edited. + type: boolean + default: true + Macros: + type: array + items: + $ref: '#/components/schemas/MacroOverview' + MacroCreate: description: | - Optional image identifier. The identifier consists of a prefix and a resource identifier, separated by `:`. - Available prefixes: - - `custom:` - custom image resource - - Other prefixes might be rejected by the service. - - An empty identifier, while updating the object, removes the existing image. - IncludedEntities: + Dedicated request object to create a new macro. + type: object + allOf: + - properties: + name: + $ref: '#/components/schemas/LanguageText' + icon: + $ref: '#/components/schemas/IconIdentifier' + description: + $ref: '#/components/schemas/LanguageText' + - oneOf: + - type: object + properties: + clone_from: + $ref: '#/components/schemas/EntityId' + required: + - clone_from + - type: object + properties: + clone_from: false + options: + type: object + properties: + entity_ids: + type: array + items: + $ref: '#/components/schemas/EntityId' + required: + - entity_ids + required: + - name + Macro: description: | - Included entities in an activity or macro. This object is writable from the client and persisted when saving. + The macro entity executes a sequence of commands. + type: object + allOf: + - $ref: '#/components/schemas/Entity' + - properties: + entity_type: + type: string + enum: + - macro + features: + description: | + Supported features of the macro. + type: array + items: + $ref: '#/components/schemas/MacroFeature' + options: + type: object + properties: + editable: + description: | + - `true` / property missing: macro was created by UC Remote and can be edited. + - `false`: macro was provided by an integration and cannot be edited. + type: boolean + default: true + included_entities: + $ref: '#/components/schemas/IncludedEntities' + sequence: + $ref: '#/components/schemas/CommandSequence' + required: + - options + MacroUpdate: + description: | + Dedicated request object to update an existing macro. + All root properties are optional and only the provided objects are updated in the macro. Omitted objects are + ignored and not deleted from the macro. + + The `entity_ids` object must be managed by the client and is persisted when updating a macro. Notes: - - Entities can be included without being used in a sequence. - This allows to edit the activity or macro in multiple sessions without having to reselect the desired entities. - - Every used entity in a sequence must be included, otherwise the activity or macro cannot be saved. - - If the client removes an entity which is included in an activity or macro, it must make sure to also remove all - entity references the sequence(s), button mapping and user interface. - type: array - items: - $ref: '#/components/schemas/IncludedEntity' - IncludedEntity: - description: | - When saving an activity only the `entity_id` is persisted. When retrieving an activity all other fields - will be retrieved from the real entities to make sure they are up to date. I.e. the entity name or icon - might change between saving an activity and retrieving it again! + - Entities can be included in `entity_ids` without being used in `sequence`. + This allows to edit the macro in multiple sessions without having to reselect the desired entities. + - Every referenced entity in `sequence` must be included in `entity_ids`, otherwise the macro cannot be saved. + - If the client removes a configured entity from the system which is included in a macro, it must make sure to also + remove all references in the macro. See `available` property in the included entities object when retrieving a macro. type: object properties: - entity_id: - $ref: '#/components/schemas/EntityId' - entity_type: - $ref: '#/components/schemas/EntityType' name: $ref: '#/components/schemas/LanguageText' icon: $ref: '#/components/schemas/IconIdentifier' - integration: - description: | - Optional integration information. Regular entities will have at least the integration name. Special - entities like activities and macros might omit the integration object. + description: + $ref: '#/components/schemas/LanguageText' + options: type: object properties: - name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' - entity_commands: - description: | - Supported entity command identifiers. A command identifier refers to the common entity command - definitions, which describe all required parameters to set for calling the entity command. This - includes the mandatory `cmd_id` attribute and optional parameters. - type: array - items: - type: string - simple_commands: - description: | - Simple commands are additional commands supported by the entity, which are not included in the - common entity command definitions. A typical example are remote-entity commands like `VOLUME_UP` etc - which don't have additional parameters. A simple command relates directly to the `cmd_id` attribute - when calling a command. - type: array - items: - type: string - available: - description: | - State of the entity: True / missing = entity is available as configured entity and can be used. - False = entity has been removed and must be corrected by the user. - - If an entity is no longer available then all usages in the sequences are still present in case the - entity is re-configured. The execution of the on- or off-sequence will then simply skip the actions - of the no longer available entity. - type: boolean - required: - - entity_id - IntgAuthMethod: - type: string - description: | - 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. - enum: - - HEADER - - MESSAGE - InhibitMode: - type: string - enum: - - BLOCK - - DELAY - Inhibitor: + entity_ids: + type: array + items: + $ref: '#/components/schemas/EntityId' + sequence: + $ref: '#/components/schemas/CommandSequence' + CodeSetInfo: type: object properties: - id: - description: Unique identifier - type: string - who: - description: A descriptive string who is inhibiting + manufacturer_id: type: string - why: - description: A descriptive string why is being inhibited + manufacturer: type: string - mode: - $ref: '#/components/schemas/InhibitMode' - delay: - description: 'Delay value in seconds for mode: DELAY' - type: integer - minimum: 0 - created: - description: Duration in seconds when this inhibitor was created - type: integer - minimum: 0 - required: - - id - - who - - mode - Inhibitors: - type: array - items: - $ref: '#/components/schemas/Inhibitor' - CreateStandbyInhibitor: - type: object - properties: - id: - description: 'Unique identifier, automatically crated if not specified.' + device_id: type: string - minLength: 1 - maxLength: 64 - who: - description: A descriptive string who is inhibiting + device: type: string - minLength: 1 - maxLength: 64 - why: - description: A descriptive string why is being inhibited + device_type: type: string - maxLength: 64 - delay: - description: 'Delay standby for given seconds, otherwise block indefinitely until inhibitor is removed.' - type: integer - minimum: 1 - required: - - who - CreateIntegrationSetup: - type: object - properties: - driver_id: - $ref: '#/components/schemas/DriverId' - name: - $ref: '#/components/schemas/LanguageText' - setup_data: - $ref: '#/components/schemas/SettingsValues' - reconfigure: - description: Reconfigure an already configured integration. - type: boolean required: - - driver_id - IntegrationSetupError: - type: string - enum: - - NONE - - NOT_FOUND - - CONNECTION_REFUSED - - AUTHORIZATION_ERROR - - TIMEOUT - - OTHER - IntegrationSetupInfo: - type: object - description: Integration setup state - properties: - id: - type: string - state: - $ref: '#/components/schemas/IntegrationSetupState' - error: - $ref: '#/components/schemas/IntegrationSetupError' - require_user_action: - description: 'If set, the setup process waits for the specified user action.' - oneOf: - - type: object - properties: - input: - $ref: '#/components/schemas/SettingsPage' - required: - - input - - type: object - properties: - confirmation: - $ref: '#/components/schemas/ConfirmationPage' - required: - - confirmation - required: - - id - - state - IntegrationSetupState: + - manufacturer_id + - manufacturer + - device_id + - device + - device_type + DeviceType: type: string enum: - - SETUP - - WAIT_USER_ACTION - - OK - - ERROR - IntegrationDiscovery: + - audio + - radio + - cd_player + - receiver + - soundbar + - hdmi_switch + - television + - projector + - set_top_box + - media_player + - dvd_player + - bluray_player + - climate + - light + - various + IrCodeFormat: + description: | + Supported IR code formats: + - `HEX`: Unfolded Circle HEX codes, `;;;` (based on + [IRremoteESP8266 Hex](https://github.com/unfoldedcircle/IRremoteESP8266) format). + - protocol: numeric value from supported and enabled protocols. See: [decode_type_t](https://github.com/unfoldedcircle/IRremoteESP8266/blob/v2.8.5-ucd2.2/src/IRremoteESP8266.h#L1011) + - hex-ir-code: HEX value prefixed with `0x` + - bits: number of bits in hex value + - repeat-count: number of repeats + - `PRONTO`: PRONTO hex codes + - Only raw codes are supported. First number must be `0000`. + type: string + enum: + - HEX + - PRONTO + IrCodeKey: + description: IR command key identifier + type: string + format: ^[a-zA-Z0-9\-_\.:+#*°@%/()?]{1,50}$ + IrCodeValue: + description: | + IR code value, either in HEX or PRONTO format as defined in the format field. + + - Multiple IR codes in a sequence can be specified with a plus character `+` as divider. + - For example: `3;0x20F0A956;32;0 + 3;0x20F02956;32;0` + - This works for HEX and PRONTO + - PRONTO only: 2 toggling codes can be specified with a pipe character `|` as divider. + - Only two toggling codes are valid. + - For example: `0000 0068 0001 0000 0002 0800 | 0000 0068 0001 0000 8002 0800` + - ⚠️ Sequence and toggle divider cannot be mixed. + type: string + format: ^(?:(?:\d{1,3};0x[a-fA-F0-9]{1,16};\d{1,2};\d{1,2}(?:\s*\+\s*\d{1,3};0x[a-fA-F0-9]{1,16};\d{1,2};\d{1,2})*)|(?:0000(?:[, ][a-fA-F0-9]{4}){5,}(?:(?:\s*\+\s*0000(?:[, ][a-fA-F0-9]{4}){5,})*|\s*\|\s*0000(?:[, ][a-fA-F0-9]{4}){5,})))$ + IrCodeCreate: type: object properties: - id: - $ref: '#/components/schemas/DriverId' - configured: - description: | - Integration configuration flag: - - true: driver has already been configured - - false: driver has not yet been configured - type: boolean - name: - type: string - developer_name: - type: string - icon: - $ref: '#/components/schemas/IconIdentifier' - driver_url: - description: Resolved driver url. - type: string - pwd_protected: - description: Driver requires a connection password. - type: boolean - version: - description: Detected driver version. - type: string - timestamp: - description: Timestamp of integration discovery. - type: string - format: date-time + key: + $ref: '#/components/schemas/IrCodeKey' + value: + $ref: '#/components/schemas/IrCodeValue' required: - - id - - configured - - name - - driver_url - IntegrationDiscoveryStatus: + - key + - value + CodeSetCreate: type: object properties: - active: + manufacturer: description: | - Integration discovery still active or not. - type: boolean - integrations: + Optional manufacturer name. If not specified: the codeset will be linked to the custom manufacturer entry + for self learned codes. + type: string + minLength: 1 + maxLength: 100 + device: + type: string + minLength: 1 + maxLength: 100 + device_type: + $ref: '#/components/schemas/DeviceType' + code_format: + $ref: '#/components/schemas/IrCodeFormat' + codes: type: array items: - $ref: '#/components/schemas/IntegrationDiscovery' + $ref: '#/components/schemas/IrCodeCreate' required: - - discovery_active - - integrations - IntegrationDriver: + - device + - device_type + IrCode: type: object - description: | - Integration driver model. - - A driver represents the communication aspect of an integration. E.g. how one can connect to it - and which API version it supports. - - One driver can provide multiple `Integration` instances. In the integration API they are - referred to as `multi-device integrations` and use the optional `device_id` property where - required. If a driver only provides a single instance, which is usually the default use case, - then the `device_id` is not used (or set to the default value `main`). properties: - driver_id: - $ref: '#/components/schemas/DriverId' - name: - $ref: '#/components/schemas/LanguageText' - driver_type: - $ref: '#/components/schemas/IntegrationDriverType' - driver_url: - description: WebSocket URL of the driver. Only optional for integration driver metadata. + key: type: string - format: uri - maxLength: 2048 - token: - description: | - Optional driver authentication token. - - Note: the token will not be returned to external clients! + format: + $ref: '#/components/schemas/IrCodeFormat' + value: type: string - maxLength: 2048 - auth_method: - $ref: '#/components/schemas/IntgAuthMethod' - pwd_protected: - description: Driver requires a connection password. - type: boolean - version: - description: 'Driver version, [SemVer](https://semver.org/) preferred.' + required: + - key + - format + - value + CodeSet: + type: object + properties: + manufacturer_id: type: string - maxLength: 20 - min_core_api: - description: | - Optional version check: minimum required core API version in the remote. + manufacturer: type: string - maxLength: 20 - icon: - $ref: '#/components/schemas/IconIdentifier' - enabled: - description: | - Enables or disables driver communication. For development use only! - If disabled, all integration instances won't be activated, even if the instance is enabled. - type: boolean - description: - $ref: '#/components/schemas/LanguageText' - developer: - $ref: '#/components/schemas/DriverDeveloper' - home_page: - description: Optional home page url for more information. + device_id: type: string - format: uri - maxLength: 255 - device_discovery: - description: Driver supports multi-device discovery. **Not yet supported**. - type: boolean - setup_data_schema: - $ref: '#/components/schemas/SettingsPage' - release_date: - description: Release date of the driver. + device: type: string - format: date - driver_state: - $ref: '#/components/schemas/DriverState' + device_type: + type: string + codes: + type: array + items: + $ref: '#/components/schemas/IrCode' required: - - driver_id - - name - - version - IntegrationDriverInfo: + - manufacturer + - manufacturer_id + - device_id + - device + - device_type + - codes + CodeSetUploadResult: type: object - description: | - Summary data of an integration driver intended for overview screens. properties: - driver_id: - $ref: '#/components/schemas/DriverId' - name: - $ref: '#/components/schemas/LanguageText' - developer_name: - type: string - driver_type: - $ref: '#/components/schemas/IntegrationDriverType' - driver_url: - description: WebSocket URL of external driver - type: string - format: uri - maxLength: 255 - version: + processed: + type: integer + added: + type: integer + updated: + type: integer + CodeSetUpdate: + type: object + properties: + device: type: string - icon: - $ref: '#/components/schemas/IconIdentifier' - enabled: - type: boolean - driver_state: - $ref: '#/components/schemas/DriverState' + minLength: 1 + maxLength: 100 + device_type: + $ref: '#/components/schemas/DeviceType' + IrCodeUpdate: + type: object + properties: + format: + $ref: '#/components/schemas/IrCodeFormat' + value: + $ref: '#/components/schemas/IrCodeValue' required: - - driver_id - - name - - driver_type - - version - - enabled - IntegrationDrivers: - type: array - items: - $ref: '#/components/schemas/IntegrationDriverInfo' - IntegrationDriverRequest: + - format + - value + IrRawCode: type: object + properties: + raw: + type: array + items: + type: integer + minimum: 0 + frequency: + type: integer + minimum: 0 + duty_cycle: + type: integer + minimum: 0 + maximum: 100 + required: + - raw + - frequency + IrEmitterType: + type: string description: | - Integration driver creation model. - - - The only required property is `driver_url` to contact the driver and fetch all driver data. - - If the driver requires an access token, the `token` needs to be specified and optionally the authentication method - in `auth_method`. - - The `driver_id` identifier can be specified by the client, but it needs to be unique among - all drivers. If omitted, the driver identifier returned by the driver will be used. - A manually assigned, short, human-readable identifier is recommended for better recognizability. + The type of the IR emitter device: + - `DOCK`: an Unfolded Circle docking station + - `INTERNAL`: internal IR + - `IR_BLASTER`: a network based IR blaster + - `OTHER`: something else + enum: + - DOCK + - INTERNAL + - IR_BLASTER + - OTHER + IrEmitterLearningCapability: + type: object + description: Emitter can also be used for learning IR codes. properties: - driver_id: - $ref: '#/components/schemas/DriverId' - name: - $ref: '#/components/schemas/LanguageText' - driver_url: - description: WebSocket URL of the driver + description: type: string - format: uri - maxLength: 2048 - token: - description: Optional driver authentication token. + instruction: type: string - maxLength: 2048 - auth_method: - $ref: '#/components/schemas/IntgAuthMethod' - icon: - $ref: '#/components/schemas/IconIdentifier' - enabled: - description: | - Enables or disables driver communication. For development use only! - If disabled, all integration instances won't be activated, even if the instance is enabled. + formats: + type: array + items: + type: string + send_while_learn: + description: Emitter is able to send IR codes while in learn mode. type: boolean + default: false required: - - driver_url - IntegrationDriverType: + - formats + IrEmitterPortMode: type: string description: | - - `LOCAL`: pre-installed integration driver in the firmware. - - `CUSTOM`: user-installed custom integration driver on the remote. - - `EXTERNAL`: external integration driver on the network. + Optional IR-emitter output port mode, default is `INFRARED`. Specifies what kind of output it is. + - `NONE`: port is not active or disabled + - `UNKNOWN`: output is not known, for example if auto-detection is active + - `INFRARED`: generic infrared output + - `IR_BLASTER`: IR-blaster output + - `IR_EMITTER`: IR-emitter output + - `OTHER`: port is not configured for infrared output enum: - - LOCAL - - CUSTOM - - EXTERNAL - IntegrationDriverUpdate: - type: object + - NONE + - UNKNOWN + - INFRARED + - IR_BLASTER + - IR_EMITTER + - OTHER + IrEmitterPortState: + type: string description: | - Integration driver update model. This model corresponds to the `IntegrationDriverRequest` model except there are - no required properties to allow patch updates. - - - Specified properties will update the current values. - - An empty value will delete the currently set property. + Optional IR-emitter output port state, default is `ACTIVE`. + - `ACTIVE`: IR output is enabled + - `ERROR`: output is in error state + - `DISABLED`: output is disabled + - `OTHER`: output port is not configured for infrared + enum: + - ACTIVE + - ERROR + - DISABLED + - OTHER + IrEmitterPort: + description: | + IR emitter output port definition. The optional `mode` and `state` fields can be used for dynamic output ports, + if the port can be become unavailable, or re-configured to a non-infrared mode. This allows the UI to show more + information in the port selection. + type: object properties: - name: - $ref: '#/components/schemas/LanguageText' - driver_url: - description: WebSocket URL of the driver + port_id: + description: IR emitter output port identifier. type: string - format: uri - maxLength: 2048 - token: - description: Optional driver authentication token. + name: + description: Friendly name of the output port. type: string - maxLength: 2048 - auth_method: - $ref: '#/components/schemas/IntgAuthMethod' - icon: - $ref: '#/components/schemas/IconIdentifier' - enabled: - description: | - Enables or disables driver communication. - If disabled, all integration instances won't be activated, even if the instance is enabled. - type: boolean - Integration: + mode: + $ref: '#/components/schemas/IrEmitterPortMode' + state: + $ref: '#/components/schemas/IrEmitterPortState' + required: + - port_id + - name + IrEmitter: type: object - description: | - Integration instance model. properties: - integration_id: - $ref: '#/components/schemas/IntegrationId' - driver_id: - $ref: '#/components/schemas/DriverId' device_id: - $ref: '#/components/schemas/DeviceId' + description: IR emitter device identifier. + type: string + type: + $ref: '#/components/schemas/IrEmitterType' name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' - enabled: - description: Enable / disable flag. For development use only! + description: Friendly name of the IR emitter device. + type: string + active: + description: Emitter device is active or currently not available. type: boolean - setup_data: - description: Instance configuration object + capabilities: + description: Optional capabilities of the emitter. type: object - device_state: - $ref: '#/components/schemas/DeviceState' + properties: + learning: + $ref: '#/components/schemas/IrEmitterLearningCapability' + ports: + description: | + Available output ports of the emitter. + A simple emitter might only have one IR output, whereas the Remote Two dock has 4 individual outputs. + type: array + items: + $ref: '#/components/schemas/IrEmitterPort' required: - - integration_id - - driver_id + - device_id + - type - name - - enabled - IntegrationId: - type: string - format: '^[a-zA-Z0-9\-_\.]+$' - minLength: 1 - maxLength: 73 - description: | - Unique integration instance identifier. Automatically created by the system when creating a new instance from a driver. - Integrations: + - active + - ports + IrEmitters: type: array items: - $ref: '#/components/schemas/Integration' - IntegrationUpdate: + $ref: '#/components/schemas/IrEmitter' + LearnedIrCode: type: object - description: | - Integration instance update model. This model corresponds to the `Integration` model except there are no required - properties to allow patch updates. - - - Specified properties will update the current values. - - An empty value will delete a set property. - - `device_id` is only required for multi-device integrations. properties: - device_id: - $ref: '#/components/schemas/DeviceId' - name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' - enabled: - description: Enable / disable flag. For development use only! - type: boolean - setup_data: - description: Instance configuration object. - type: object - IntegrationState: - type: string - enum: - - NOT_CONFIGURED - - UNKNOWN - - IDLE - - CONNECTING - - CONNECTED - - DISCONNECTED - - RECONNECTING - - ACTIVE - - ERROR - IntegrationStatus: - type: object - description: | - Integration status information. Intended to be used in a general overview of the integration drivers and instances. - properties: - driver_id: - $ref: '#/components/schemas/DriverId' - integration_id: - $ref: '#/components/schemas/IntegrationId' - name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' - driver_type: - $ref: '#/components/schemas/IntegrationDriverType' - state: - $ref: '#/components/schemas/IntegrationState' - required: - - name - - driver_type - CodeSet: - type: object - properties: - manufacturer_id: - type: string - manufacturer: - type: string - device_id: - type: string - device: - type: string - device_type: - type: string - codes: - type: array - items: - $ref: '#/components/schemas/IrCode' - required: - - manufacturer - - manufacturer_id - - device_id - - device - - device_type - - codes - CodeSetCreate: - type: object - properties: - manufacturer: - description: | - Optional manufacturer name. If not specified: the codeset will be linked to the custom manufacturer entry - for self learned codes. - type: string - minLength: 1 - maxLength: 100 - device: - type: string - minLength: 1 - maxLength: 100 - device_type: - $ref: '#/components/schemas/DeviceType' - code_format: - $ref: '#/components/schemas/IrCodeFormat' - codes: - type: array - items: - $ref: '#/components/schemas/IrCodeCreate' - required: - - device - - device_type - CodeSetInfo: - type: object - properties: - manufacturer_id: - type: string - manufacturer: - type: string - device_id: - type: string - device: - type: string - device_type: - type: string - required: - - manufacturer_id - - manufacturer - - device_id - - device - - device_type - CodeSetUpdate: - type: object - properties: - device: - type: string - minLength: 1 - maxLength: 100 - device_type: - $ref: '#/components/schemas/DeviceType' - CodeSetUploadResult: - type: object - properties: - processed: - type: integer - added: - type: integer - updated: - type: integer - IrCode: - type: object - properties: - key: - type: string - format: - $ref: '#/components/schemas/IrCodeFormat' - value: + code: type: string - required: - - key - - format - - value - IrCodeCreate: - type: object - properties: - key: - $ref: '#/components/schemas/IrCodeKey' - value: - $ref: '#/components/schemas/IrCodeValue' - required: - - key - - value - IrCodeFormat: - description: | - Supported IR code formats: - - `HEX`: Unfolded Circle HEX codes, `;;;` (based on - [IRremoteESP8266 Hex](https://github.com/unfoldedcircle/IRremoteESP8266) format). - - protocol: numeric value from supported and enabled protocols. See: [decode_type_t](https://github.com/unfoldedcircle/IRremoteESP8266/blob/v2.8.5-ucd2.2/src/IRremoteESP8266.h#L1011) - - hex-ir-code: HEX value prefixed with `0x` - - bits: number of bits in hex value - - repeat-count: number of repeats - - `PRONTO`: PRONTO hex codes - - Only raw codes are supported. First number must be `0000`. - type: string - enum: - - HEX - - PRONTO - IrCodeKey: - description: IR command key identifier - type: string - format: '^[a-zA-Z0-9\-_\.:+#*°@%/()?]{1,50}$' - IrCodeSetType: - description: 'Type of codeset, either a manufacturer codeset or a custom codeset.' - type: string - enum: - - manufacturer - - custom - IrCodeUpdate: - type: object - properties: format: $ref: '#/components/schemas/IrCodeFormat' - value: - $ref: '#/components/schemas/IrCodeValue' - required: - - format - - value - IrCodeValue: - description: | - IR code value, either in HEX or PRONTO format as defined in the format field. - - - Multiple IR codes in a sequence can be specified with a plus character `+` as divider. - - For example: `3;0x20F0A956;32;0 + 3;0x20F02956;32;0` - - This works for HEX and PRONTO - - PRONTO only: 2 toggling codes can be specified with a pipe character `|` as divider. - - Only two toggling codes are valid. - - For example: `0000 0068 0001 0000 0002 0800 | 0000 0068 0001 0000 8002 0800` - - ⚠️ Sequence and toggle divider cannot be mixed. - type: string - format: '^(?:(?:\d{1,3};0x[a-fA-F0-9]{1,16};\d{1,2};\d{1,2}(?:\s*\+\s*\d{1,3};0x[a-fA-F0-9]{1,16};\d{1,2};\d{1,2})*)|(?:0000(?:[, ][a-fA-F0-9]{4}){5,}(?:(?:\s*\+\s*0000(?:[, ][a-fA-F0-9]{4}){5,})*|\s*\|\s*0000(?:[, ][a-fA-F0-9]{4}){5,})))$' - IrRawCode: - type: object - properties: - raw: - type: array - items: - type: integer - minimum: 0 - frequency: - type: integer - minimum: 0 - duty_cycle: - type: integer - minimum: 0 - maximum: 100 - required: - - raw - - frequency - IrEmitter: - type: object - properties: - device_id: - description: IR emitter device identifier. - type: string - type: - $ref: '#/components/schemas/IrEmitterType' - name: - description: Friendly name of the IR emitter device. + timestamp: type: string - active: - description: Emitter device is active or currently not available. - type: boolean - capabilities: - description: Optional capabilities of the emitter. - type: object - properties: - learning: - $ref: '#/components/schemas/IrEmitterLearningCapability' - ports: - description: | - Available output ports of the emitter. - A simple emitter might only have one IR output, whereas the Remote Two dock has 4 individual outputs. - type: array - items: - $ref: '#/components/schemas/IrEmitterPort' - required: - - device_id - - type - - name - - active - - ports + format: date-time IrEmitterLearnStatus: type: object properties: @@ -14447,150 +14251,24 @@ components: - device_id - learning_active - codes - IrEmitterLearningCapability: - type: object - description: Emitter can also be used for learning IR codes. - properties: - description: - type: string - instruction: - type: string - formats: - type: array - items: - type: string - send_while_learn: - description: Emitter is able to send IR codes while in learn mode. - type: boolean - default: false - required: - - formats - IrEmitters: - type: array - items: - $ref: '#/components/schemas/IrEmitter' - IrEmitterType: - type: string - description: | - The type of the IR emitter device: - - `DOCK`: an Unfolded Circle docking station - - `INTERNAL`: internal IR - - `IR_BLASTER`: a network based IR blaster - - `OTHER`: something else - enum: - - DOCK - - INTERNAL - - IR_BLASTER - - OTHER - IrEmitterPort: + RemoteKind: description: | - IR emitter output port definition. The optional `mode` and `state` fields can be used for dynamic output ports, - if the port can be become unavailable, or re-configured to a non-infrared mode. This allows the UI to show more - information in the port selection. - type: object - properties: - port_id: - description: IR emitter output port identifier. - type: string - name: - description: Friendly name of the output port. - type: string - mode: - $ref: '#/components/schemas/IrEmitterPortMode' - state: - $ref: '#/components/schemas/IrEmitterPortState' - required: - - port_id - - name - IrEmitterPortMode: + Type of remote-entity: + - `BT`: Bluetooth remote + - `IR`: Infrared remote + - `EXTERNAL`: Remote-entity provided from an integration to control a single device. type: string - description: | - Optional IR-emitter output port mode, default is `INFRARED`. Specifies what kind of output it is. - - `NONE`: port is not active or disabled - - `UNKNOWN`: output is not known, for example if auto-detection is active - - `INFRARED`: generic infrared output - - `IR_BLASTER`: IR-blaster output - - `IR_EMITTER`: IR-emitter output - - `OTHER`: port is not configured for infrared output enum: - - NONE - - UNKNOWN - - INFRARED - - IR_BLASTER - - IR_EMITTER - - OTHER - IrEmitterPortState: + - BT + - IR + - EXTERNAL + default: IR + RemoteFeature: type: string - description: | - Optional IR-emitter output port state, default is `ACTIVE`. - - `ACTIVE`: IR output is enabled - - `ERROR`: output is in error state - - `DISABLED`: output is disabled - - `OTHER`: output port is not configured for infrared enum: - - ACTIVE - - ERROR - - DISABLED - - OTHER - IrStatus: - type: object - properties: - dock_id: - $ref: '#/components/schemas/DockId' - learning_active: - description: Dock is in IR learning mode - type: boolean - state: - $ref: '#/components/schemas/DockState' - codes: - type: array - items: - $ref: '#/components/schemas/LearnedIrCode' - LanguageCode: - description: | - Language culture code: starting with the two-letter [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) - code, followed by an optional [ISO-3166 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes), - separated by an underscore. - Examples: `en`, `en_UK`, `en_US`, `de`, `de_DE`, `de_CH` etc. - type: string - pattern: '^[a-z]{2}(_\w+)?$' - LanguageText: - type: object - description: | - Key value pairs of language texts. Key: ISO 639-1 code with optional country suffix to represent a `culture code`. - Examples: `en`, `en_UK`, `en_US`, `de`, `de_CH`. - - If we need to support more regional differences within a country, then the - [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) might be a solution. This would even - support the various Swiss German dialects! - additionalProperties: - type: string - LearnedIrCode: - type: object - properties: - code: - type: string - format: - $ref: '#/components/schemas/IrCodeFormat' - timestamp: - type: string - format: date-time - LoginRequest: - type: object - properties: - username: - type: string - password: - type: string - required: - - username - - password - example: - username: admin - password: '1234' - Macro: - description: | - The macro entity executes a sequence of commands. + - on_off + - send + RemoteOverview: type: object allOf: - $ref: '#/components/schemas/Entity' @@ -14598,39 +14276,37 @@ components: entity_type: type: string enum: - - macro + - remote features: description: | - Supported features of the macro. + Supported features of the remote. type: array items: - $ref: '#/components/schemas/MacroFeature' + $ref: '#/components/schemas/RemoteFeature' options: type: object properties: editable: description: | - - `true` / property missing: macro was created by UC Remote and can be edited. - - `false`: macro was provided by an integration and cannot be edited. + - `true` / property missing: remote was created by UC Remote and can be edited. + - `false`: remote was provided by an integration and cannot be edited. type: boolean default: true - included_entities: - $ref: '#/components/schemas/IncludedEntities' - sequence: - $ref: '#/components/schemas/CommandSequence' - required: - - options - MacroFeature: - type: string - enum: - - start - Macros: + Remotes: type: array items: - $ref: '#/components/schemas/MacroOverview' - MacroCreate: + $ref: '#/components/schemas/RemoteOverview' + BtRemoteCreateOptions: + description: Options for creating a Bluetooth peripheral remote-entity. + type: object + properties: + dev_profile_id: + description: | + Bluetooth device profile identifier to customize available commands, button mappings and default UI screens. + type: string + RemoteCreate: description: | - Dedicated request object to create a new macro. + Dedicated request object to create a new remote. type: object allOf: - properties: @@ -14649,20 +14325,57 @@ components: - clone_from - type: object properties: - options: + codeset_id: + $ref: '#/components/schemas/SimpleId' + required: + - codeset_id + - type: object + properties: + custom_codeset: type: object properties: - entity_ids: - type: array - items: - $ref: '#/components/schemas/EntityId' + manufacturer_id: + type: string + default: custom + device_name: + type: string + device_type: + $ref: '#/components/schemas/DeviceType' required: - - entity_ids + - device_name + required: + - custom_codeset + - type: object + properties: + kind: + $ref: '#/components/schemas/RemoteKind' + bt: + $ref: '#/components/schemas/BtRemoteCreateOptions' + required: + - kind + - bt required: - name - MacroOverview: + BtDevicePeripherals: + description: Supported device peripherals. A device can support a single mode or act as a composite device. + type: object + properties: + keyboard: + description: Device is a HID keyboard + type: boolean + mouse: + description: Device is a mouse keyboard + type: boolean + IrCodeSetType: + description: Type of codeset, either a manufacturer codeset or a custom codeset. + type: string + enum: + - manufacturer + - custom + Remote: description: | - The macro entity executes a sequence of commands. + The remote entity executes a sequence of commands and at the end displays a user interface (similar to remote entity) + to the user. If the entity has an off sequence, it can be turned off. type: object allOf: - $ref: '#/components/schemas/Entity' @@ -14670,40 +14383,107 @@ components: entity_type: type: string enum: - - macro + - remote features: description: | - Supported features of the macro. + Supported features of the remote. If the remote has an `off` sequence, it supports the common `on_off` + feature, otherwise only `start`. type: array items: - $ref: '#/components/schemas/MacroFeature' + $ref: '#/components/schemas/RemoteFeature' options: type: object properties: editable: description: | - - `true` / property missing: macro was created by UC Remote and can be edited. - - `false`: macro was provided by an integration and cannot be edited. + - `true` / property missing: remote was created by UC Remote and can be edited. + - `false`: remote was provided by an integration and cannot be edited. type: boolean default: true - MacroUpdate: - description: | - Dedicated request object to update an existing macro. - All root properties are optional and only the provided objects are updated in the macro. Omitted objects are - ignored and not deleted from the macro. - - The `entity_ids` object must be managed by the client and is persisted when updating a macro. - - Notes: - - Entities can be included in `entity_ids` without being used in `sequence`. - This allows to edit the macro in multiple sessions without having to reselect the desired entities. - - Every referenced entity in `sequence` must be included in `entity_ids`, otherwise the macro cannot be saved. - - If the client removes a configured entity from the system which is included in a macro, it must make sure to also - remove all references in the macro. See `available` property in the included entities object when retrieving a macro. - type: object - properties: - name: - $ref: '#/components/schemas/LanguageText' + kind: + $ref: '#/components/schemas/RemoteKind' + bt: + type: object + properties: + dev_profile_id: + description: BT device profile identifier + type: boolean + peripherals: + $ref: '#/components/schemas/BtDevicePeripherals' + profile: + description: BT peripheral connection profile + type: integer + ir: + description: | + Infrared settings: codeset name und used infrared emitter to send commands. + type: object + properties: + cmd_delay: + description: | + Delay in milliseconds between sending IR commands, if a command contains multiple IR codes. + type: integer + minimum: 0 + repeat: + description: | + Repeat each IR command in the dataset n times. Defaults to 0 (no repeat) if not specified. + This setting is intended mainly for PRONTO codes with certain devices requiring the same command being + sent twice (e.g. Sony and Epson devices). + type: integer + minimum: 0 + maximum: 20 + codeset: + description: | + Read-only information about the infrared codeset. 👷 **TODO** Use `/remotes/entities/:entityId/ir` + endpoints to manage infrared codes. + type: object + properties: + id: + description: | + Codeset identifier, either a custom codeset id or a manufacturer codeset id depending on `type`. + type: string + name: + description: | + User friendly name of the used codeset (custom or manufacturer) to show in a user interface. + type: string + type: + $ref: '#/components/schemas/IrCodeSetType' + output: + description: | + Infrared output device settings. Use `/ir/emitter` endpoints to retrieve further information. + type: object + properties: + device_id: + description: | + IR emitter device identifier. + type: string + port_id: + description: | + IR emitter output port identifier. + type: string + simple_commands: + description: | + All available commands of the infrared codeset for the button mapping and user interface. + These simple commands relate directly to the `cmd_id` attribute when defining or calling an entity command. + + The commands are read-only and updated automatically based on the infrared codeset. + type: array + items: + type: string + button_mapping: + $ref: '#/components/schemas/DeviceButtonMappings' + user_interface: + $ref: '#/components/schemas/ActivityUserInterface' + required: + - options + RemoteUpdate: + description: | + Dedicated request object to update an existing remote. + All root properties are optional and only the provided objects are updated in the remote-entity. Omitted objects are + ignored and not deleted from the remote-entity. + type: object + properties: + name: + $ref: '#/components/schemas/LanguageText' icon: $ref: '#/components/schemas/IconIdentifier' description: @@ -14711,261 +14491,286 @@ components: options: type: object properties: - entity_ids: - type: array - items: - $ref: '#/components/schemas/EntityId' - sequence: - $ref: '#/components/schemas/CommandSequence' - MediaBrowseResponse: + ir: + type: object + properties: + cmd_delay: + description: | + Delay in milliseconds between sending IR commands, if a command contains multiple IR codes. + type: integer + minimum: 0 + repeat: + description: | + Repeat each IR command in the dataset n times. Defaults to 0 (no repeat) if not specified. + This setting is intended mainly for PRONTO codes with certain devices requiring the same command being + sent twice (e.g. Sony and Epson devices). + type: integer + minimum: 0 + maximum: 20 + codeset: + type: object + properties: + id: + type: string + required: + - id + output: + type: object + properties: + device_id: + type: string + port_id: + type: string + required: + - device_id + - port_id + RemoteIrCode: type: object properties: - media: - $ref: '#/components/schemas/BrowseMediaItem' - MediaSearchResponse: - type: array - items: - $ref: '#/components/schemas/SearchMediaItem' - MediaClass: - description: | - The media class is for browser/structure semantics. - It represents how a media item should be presented and organized in the media browser hierarchy. - - - Common values are defined as enum variants. Using these values is recommended, so the UI can show media type - specific information like icons. - - Integrations can use their custom values. Short identifiers like URIs are recommended. - type: string - maxLength: 255 - anyOf: - - enum: - - album - - app - - artist - - channel - - composer - - directory - - episode - - game - - genre - - image - - movie - - music - - playlist - - podcast - - radio - - season - - track - - tv_show - - url - - video - - {} - MediaContentType: - description: | - The media content type is for playback/content semantics. - It represents the type of the media content to play or that is currently playing. - - Notes: - - Common values are defined as enum variants. Using these values is recommended, so the UI can show media type - specific information like icons. - - Integrations can use their custom values. Short identifiers like URIs are recommended. - type: string - maxLength: 255 - anyOf: - - enum: - - album - - app - - apps - - artist - - channel - - channels - - composer - - episode - - game - - genre - - image - - movie - - music - - playlist - - podcast - - radio - - season - - track - - tv_show - - url - - video - - {} - MediaPlayerRepeatMode: - type: string - enum: - - 'OFF' - - ALL - - ONE - MediaPlayAction: - description: | - The media play action is used to specify how the media item should be played. - - Notes: - - Common values are defined as enum variants. Using these values is recommended, so the UI can show locale aware commands. - - Integrations can use their custom values, but they might not be available in the UI. - type: string - maxLength: 20 - anyOf: - - enum: - - PLAY_NOW - - PLAY_NEXT - - ADD_TO_QUEUE - - { } # extensible enum: integration can define additional values - default: PLAY_NOW - BrowseMediaItem: + cmd_id: + $ref: '#/components/schemas/SimpleId' + code: + description: | + Custom infrared code. Only set for custom codeset or if a manufacturer codeset has been modified or enhanced. + type: object + properties: + value: + type: string + format: + $ref: '#/components/schemas/IrCodeFormat' + custom: + description: | + Flag indicating if this code is a custom code in a manufacturer codeset. This is a manually added code which + was not present in the codeset. Custom codes can be deleted or edited by the user. The modified code is + stored in the `code` object. + type: boolean + modified: + description: | + Flag indicating if a manufacturer code has been replaced with a user code. The modified code is stored in + the `code` object. Modified codes can be edited by the user. + type: boolean + required: + - cmd_id + RemoteIrDataSet: type: object properties: - media_id: + id: description: | - Unique identifier of the media item. Integration dependent. - Use an empty value only for special non-playable media items, for example, a root directory in a media library or search result. + Codeset identifier, either a custom codeset id or a manufacturer codeset id depending on `type`. type: string - maxLength: 255 - title: - description: Display name. + name: + description: User friendly name of the codeset (custom or manufacturer). type: string - minLength: 1 - maxLength: 255 - subtitle: - description: Optional subtitle. - type: string - minLength: 1 - maxLength: 255 - artist: - description: Optional artist name. - type: string - minLength: 1 - maxLength: 255 - album: - description: Optional album name. - type: string - minLength: 1 - maxLength: 255 - media_class: - $ref: '#/components/schemas/MediaClass' - media_type: - $ref: '#/components/schemas/MediaContentType' - can_browse: - description: 'If `true`, the item can be browsed (is a container) by using `media_id` and `media_type`.' - type: boolean - default: false - can_play: - description: | - If `true`, the item can be played directly using the `play_media` command with `media_id` and `media_type`. - type: boolean - default: false - can_search: - description: | - If `true`, a search can be performed on the item using `search_media` with `media_id` and `media_type`. - type: boolean - default: false - thumbnail: - description: | - URL to download the media artwork, or a base64 encoded PNG or JPG image. - The preferred size is 480x480 pixels. - Use the following URI prefix to use a provided icon: `icon://uc:`, for example, `icon://uc:music`. - Please use a URL whenever possible. Encoded images should be as small as possible. - type: string - minLength: 1 - maxLength: 32768 - duration: - description: Duration in seconds. - type: integer - items: - description: | - Child items if this item is a container. Child items may not contain further child items (only one level - of nesting is supported). A new browse request must be sent for deeper levels. + type: + $ref: '#/components/schemas/IrCodeSetType' + codes: type: array items: - $ref: '#/components/schemas/BrowseMediaItem' + $ref: '#/components/schemas/RemoteIrCode' + BtAddressType: + description: | + Address type: + - `LE_PUBLIC`: Public device address + - `LE_RANDOM`: Random device address + - `LE_PUBLIC_IDENTITY`: Public identity address (corresponds to resolved private address) + - `LE_RANDOM_IDENTITY`: Random (static) identity address (corresponds to resolved private address) + - `UNKNOWN`: Address could not be determined, or an error occurred + type: string + enum: + - LE_PUBLIC + - LE_RANDOM + - LE_PUBLIC_IDENTITY + - LE_RANDOM_IDENTITY + - UNKNOWN + BtPeer: + description: Information about the (paired) peer. + type: object + properties: + address: + description: BT address in 00:00:00:00:00:00 format. + type: string + addr_type: + $ref: '#/components/schemas/BtAddressType' required: - - media_id - - title - SearchMediaItem: + - address + - addr_type + BtRemoteInfo: description: | - A media item that was found by a search. Currently identical in shape to `BrowseMediaItem`. - Defined as a composition to allow search-specific fields (e.g. relevance score) to be added in the future - without a breaking change. - - A search media item may not contain any child `items`. - allOf: - - $ref: '#/components/schemas/BrowseMediaItem' - MediaQueueResponse: - description: "\U0001F6A7 initial draft, do not use!" + BT-remote information. type: object properties: - items: - type: array - items: - $ref: '#/components/schemas/QueueItem' - current_index: + profile: + description: BT peripheral connection profile type: integer - description: Absolute index of the currently playing item within the full queue. + dev_profile_id: + description: Bluetooth device profile identifier. + type: string + dev_profile_version: + description: Bluetooth device profile version. + type: integer + minimum: 0 + peer: + $ref: '#/components/schemas/BtPeer' + peripherals: + $ref: '#/components/schemas/BtDevicePeripherals' required: - - items - MeasurementUnit: + - profile + BtSecurityType: + description: | + Bonding security type: + - `JustWorks`: Automatic pairing, peripheral only needs to confirm pairing request from central. + - `DisplayNumber`: Peripheral must display number for the central to confirm. + - `NumericComparison`: Peripheral must confirm or declined if the numeric value matches the displayed number on the central. + - `PasskeyInput`: Peripheral must enter displayed passkey on central. type: string enum: - - METRIC - - US - - UK + - JUST_WORKS + - DISPLAY_NUMBER + - NUMERIC_COMPARISON + - PASSKEY_INPUT + BtPairingRequest: + description: | + A central requests pairing with the peripheral. + ‼️ Only `kind: PasskeyInput` is currently implemented. + type: object + properties: + id: + description: Pairing request identifier + type: integer + profile: + description: BT peripheral connection profile to associate the pairing request. + type: integer + peer: + $ref: '#/components/schemas/BtPeer' + kind: + $ref: '#/components/schemas/BtSecurityType' + passkey: + description: | + Only set for `kind: DisplayNumber | NumericComparison` + type: integer + minimum: 0 + required: + - profile + - peer + - kind + BtRemotePairingInfo: + description: | + BT-remote pairing information. The `pairing_request` field is set if a pairing request is active, `peer` is only + set if the remote has been paired with a central device. + type: object + properties: + pairing_request: + $ref: '#/components/schemas/BtPairingRequest' + paired: + description: Indicates if BT-remote entity peripheral is paired with a central device. + type: boolean + pairing_enabled: + description: Indicates if a central can pair with this BT-remote peripheral. + type: boolean + advertisement_name: + description: Advertisement name of the peripheral. Usually only set when `pairing_enabled` is true. + type: string + peer: + $ref: '#/components/schemas/BtPeer' + required: + - paired + - pairing_enabled + BtPairingResponse: + description: | + Response to a BtPairingRequest. + - `Passkey` request: either provide the passkey entered by the user, decline it with `confirm: false`. + - `NumericComparison` request: confirm or decline with `confirm: true | false`. + type: object + allOf: + - properties: + id: + description: Pairing request identifier. + type: integer + required: + - id + - oneOf: + - type: object + properties: + passkey: + description: 6-digit passkey displayed on the central, sent as text. Leading zero(s) can be included or omitted. + type: string + minLength: 1 + maxLength: 6 + required: + - passkey + - type: object + properties: + confirm: + description: Confirm or decline a pairing request. + type: boolean + required: + - confirm Name: type: string minLength: 1 maxLength: 50 - Page: + Profile: type: object properties: - page_id: - $ref: '#/components/schemas/SimpleId' profile_id: $ref: '#/components/schemas/SimpleId' name: $ref: '#/components/schemas/Name' - image: - type: string - description: Optional image identifier - items: - type: array - description: Page items - items: - $ref: '#/components/schemas/PageItem' - pos: - type: integer - format: int32 - minimum: 0 - description: Position of the page within the profile + icon: + $ref: '#/components/schemas/IconIdentifier' + restricted: + description: A restricted profile cannot change settings and switching profiles requires the admin PIN. + type: boolean + description: + $ref: '#/components/schemas/Description' required: - - page_id - profile_id - name - - items - - pos - PageCreate: + - restricted + Profiles: + type: array + items: + $ref: '#/components/schemas/Profile' + AdminPin: + type: string + maxLength: 20 + description: Optional administrator pin + ProfileRequest: type: object properties: + profile_id: + $ref: '#/components/schemas/SimpleId' name: $ref: '#/components/schemas/Name' - image: - $ref: '#/components/schemas/ImageIdentifier' - items: - type: array - description: | - Optional page items. - items: - $ref: '#/components/schemas/PageItem' - pos: - type: integer - format: int32 - minimum: 1 - description: | - Optional 1-based position of the page within the profile. Default: last position + icon: + $ref: '#/components/schemas/IconIdentifier' + restricted: + description: Create a restricted profile which cannot change settings. Switching profiles requires the admin pin. + type: boolean + description: + $ref: '#/components/schemas/Description' required: - name + ProfileUpdate: + type: object + properties: + name: + $ref: '#/components/schemas/Name' + icon: + $ref: '#/components/schemas/IconIdentifier' + restricted: + description: A restricted profile cannot change settings. Switching profiles requires the admin pin. + type: boolean + description: + $ref: '#/components/schemas/Description' + pages: + description: | + Used for update only: modify page order or delete pages in profile. + - An empty `pages` array will delete all pages and containing groups! + - If the property is missing, the existing page configuration will not be changed. + type: array + items: + $ref: '#/components/schemas/SimpleId' PageItem: type: object properties: @@ -14985,588 +14790,642 @@ components: - entity_id - required: - group_id - PageUpdate: + Page: type: object properties: + page_id: + $ref: '#/components/schemas/SimpleId' + profile_id: + $ref: '#/components/schemas/SimpleId' name: $ref: '#/components/schemas/Name' image: - $ref: '#/components/schemas/ImageIdentifier' + type: string + description: Optional image identifier items: type: array - description: | - Changed or re-ordered page items. - An empty array removes all items. - If the property is not specified the defined items will not be changed. + description: Page items items: $ref: '#/components/schemas/PageItem' - Pages: - type: array - items: - $ref: '#/components/schemas/Page' - PowerMode: + pos: + type: integer + format: int32 + minimum: 0 + description: Position of the page within the profile + required: + - page_id + - profile_id + - name + - items + - pos + ImageIdentifier: type: string - enum: - - NORMAL - - IDLE - - LOW_POWER - - SUSPEND - PowerModeResponse: + format: ^[a-z][a-z0-9]+:[a-zA-Z0-9\-_\.]+$ + maxLength: 255 + description: | + Optional image identifier. The identifier consists of a prefix and a resource identifier, separated by `:`. + Available prefixes: + - `custom:` - custom image resource + + Other prefixes might be rejected by the service. + + An empty identifier, while updating the object, removes the existing image. + PageCreate: type: object properties: - mode: - $ref: '#/components/schemas/PowerMode' - power_supply: - description: 'A power supply is online, device doesn''t enter standby while connected.' - type: boolean - standby_timeout_sec: + name: + $ref: '#/components/schemas/Name' + image: + $ref: '#/components/schemas/ImageIdentifier' + items: + type: array description: | - Time in seconds until the system goes into standby. - This is the max value of the regular standby and the longest active standby inhibitor. + Optional page items. + items: + $ref: '#/components/schemas/PageItem' + pos: type: integer - minimum: 0 - standby_inhibitors: + format: int32 + minimum: 1 description: | - There are active standby inhibitors preventing system standby. - - A blocking inhibitor will return a constant `standby_timeout_sec` value of `86400` (1 day). - type: boolean + Optional 1-based position of the page within the profile. Default: last position required: - - mode - - power_supply - - standby_inhibitors - Profile: + - name + PageUpdate: type: object properties: - profile_id: - $ref: '#/components/schemas/SimpleId' name: $ref: '#/components/schemas/Name' - icon: - $ref: '#/components/schemas/IconIdentifier' - restricted: - description: A restricted profile cannot change settings and switching profiles requires the admin PIN. - type: boolean - description: - $ref: '#/components/schemas/Description' - required: - - profile_id - - name - - restricted - ProfileRequest: + image: + $ref: '#/components/schemas/ImageIdentifier' + items: + type: array + description: | + Changed or re-ordered page items. + An empty array removes all items. + If the property is not specified the defined items will not be changed. + items: + $ref: '#/components/schemas/PageItem' + Group: type: object + description: | + The shown group switch in the UI is automatically determined by the capabilities of the group's entities. properties: + group_id: + $ref: '#/components/schemas/SimpleId' profile_id: $ref: '#/components/schemas/SimpleId' name: $ref: '#/components/schemas/Name' icon: $ref: '#/components/schemas/IconIdentifier' - restricted: - description: Create a restricted profile which cannot change settings. Switching profiles requires the admin pin. - type: boolean + entities: + type: array + description: Entity identifiers belonging to the group + items: + $ref: '#/components/schemas/EntityId' description: $ref: '#/components/schemas/Description' required: + - group_id + - profile_id - name - ProfileUpdate: + - entities + Groups: + type: array + items: + $ref: '#/components/schemas/Group' + GroupUpdate: type: object properties: name: $ref: '#/components/schemas/Name' icon: $ref: '#/components/schemas/IconIdentifier' - restricted: - description: A restricted profile cannot change settings. Switching profiles requires the admin pin. - type: boolean - description: - $ref: '#/components/schemas/Description' - pages: - description: | - Used for update only: modify page order or delete pages in profile. - - An empty `pages` array will delete all pages and containing groups! - - If the property is missing, the existing page configuration will not be changed. + entities: type: array + description: | + Changed or re-ordered group entities. + An empty array remove all entities. + If the property is not specified the defined entities will not be changed. items: - $ref: '#/components/schemas/SimpleId' - Profiles: - type: array - items: - $ref: '#/components/schemas/Profile' - QueueItem: - description: "\U0001F6A7 initial draft, do not use!" + $ref: '#/components/schemas/EntityId' + description: + $ref: '#/components/schemas/Description' + CfgBt: type: object properties: - queue_item_id: - type: string - description: Unique identifier for the item within this queue instance. - media_id: - type: string - description: Unique identifier for the item (opaque to Core-API). - title: + peripheral_connections: + description: Maximum number of peripheral connections at the same time. + type: integer + minimum: 1 + advertisement_name: + description: Advertisement name of the Remote. type: string - description: Display name. - media_class: - $ref: '#/components/schemas/MediaClass' - media_type: - $ref: '#/components/schemas/MediaContentType' - can_browse: + enable_hci_log: + description: Enable HCI logging. type: boolean - description: 'If `true`, the item can be browsed (is a container).' - can_play: + enable_debug_port: + description: Enable BT subsystem debug TCP-port for remote control. type: boolean - description: 'If `true`, the item can be played directly.' - thumbnail: - type: string - description: 'URL to download the image, or a base64 encoded data.' - artist: - type: string - description: Artist name. - album: + version: + description: BT subsystem version. type: string - description: Album name. - duration: - type: integer - description: Duration in seconds. required: - - queue_item_id - - media_id - - title - Remote: - description: | - The remote entity executes a sequence of commands and at the end displays a user interface (similar to remote entity) - to the user. If the entity has an off sequence, it can be turned off. + - peripheral_connections + - advertisement_name + - enable_hci_log + - enable_debug_port + StaticButtonColor: + description: Static color settings for given zones, if supported by the device. type: object - allOf: - - $ref: '#/components/schemas/Entity' - - properties: - entity_type: - type: string - enum: - - remote - features: - description: | - Supported features of the remote. If the remote has an `off` sequence, it supports the common `on_off` - feature, otherwise only `start`. - type: array - items: - $ref: '#/components/schemas/RemoteFeature' - options: - type: object - properties: - editable: - description: | - - `true` / property missing: remote was created by UC Remote and can be edited. - - `false`: remote was provided by an integration and cannot be edited. - type: boolean - default: true - kind: - $ref: '#/components/schemas/RemoteKind' - bt: - type: object - properties: - dev_profile_id: - description: BT device profile identifier - type: boolean - peripherals: - $ref: '#/components/schemas/BtDevicePeripherals' - profile: - description: BT peripheral connection profile - type: integer - ir: - description: | - Infrared settings: codeset name und used infrared emitter to send commands. - type: object - properties: - cmd_delay: - description: | - Delay in milliseconds between sending IR commands, if a command contains multiple IR codes. - type: integer - minimum: 0 - repeat: - description: | - Repeat each IR command in the dataset n times. Defaults to 0 (no repeat) if not specified. - This setting is intended mainly for PRONTO codes with certain devices requiring the same command being - sent twice (e.g. Sony and Epson devices). - type: integer - minimum: 0 - maximum: 20 - codeset: - description: "Read-only information about the infrared codeset. \U0001F477 **TODO** Use `/remotes/entities/:entityId/ir`\nendpoints to manage infrared codes.\n" - type: object - properties: - id: - description: | - Codeset identifier, either a custom codeset id or a manufacturer codeset id depending on `type`. - type: string - name: - description: | - User friendly name of the used codeset (custom or manufacturer) to show in a user interface. - type: string - type: - $ref: '#/components/schemas/IrCodeSetType' - output: - description: | - Infrared output device settings. Use `/ir/emitter` endpoints to retrieve further information. - type: object - properties: - device_id: - description: | - IR emitter device identifier. - type: string - port_id: - description: | - IR emitter output port identifier. - type: string - simple_commands: - description: | - All available commands of the infrared codeset for the button mapping and user interface. - These simple commands relate directly to the `cmd_id` attribute when defining or calling an entity command. - - The commands are read-only and updated automatically based on the infrared codeset. - type: array - items: - type: string - button_mapping: - $ref: '#/components/schemas/DeviceButtonMappings' - user_interface: - $ref: '#/components/schemas/ActivityUserInterface' - required: - - options - Remotes: + properties: + rgb: + description: The overall rgb color value for the specified zones [int, int, int]. + type: array + items: + type: integer + minimum: 0 + maximum: 255 + minItems: 3 + maxItems: 3 + zones: + description: The enabled backlight zones. All zones are enabled if no zones are set. + type: array + items: + type: string + minimum: 1 + maximum: 50 + maxItems: 32 + required: + - rgb + CfgButtons: + type: object + properties: + brightness: + description: Button backlight brightness. 0 = off, 100 = max. + type: integer + minimum: 0 + maximum: 100 + static_color: + $ref: '#/components/schemas/StaticButtonColor' + auto_brightness: + description: When enabled, button backlight will automatically turn on in a dark room. + type: boolean + features: + description: Supported features by the device. + type: array + items: + type: string + required: + - brightness + - auto_brightness + CfgRemoteDevice: + type: object + properties: + name: + description: Custom name of the remote + type: string + minimum: 1 + maximum: 50 + required: + - name + CfgDisplay: + type: object + properties: + brightness: + description: Display brightness. + type: integer + minimum: 0 + maximum: 100 + auto_brightness: + description: Automatically adjust the display brightness based on ambient lighting conditions. + type: boolean + required: + - brightness + - auto_brightness + CfgFeature: + type: object + properties: + id: + type: string + enabled: + type: boolean + title: + $ref: '#/components/schemas/LanguageText' + description: + $ref: '#/components/schemas/LanguageText' + help_url: + type: string + format: url + required: + - id + - enabled + - title + - description + CfgFeatures: type: array items: - $ref: '#/components/schemas/RemoteOverview' - RemoteCreate: + $ref: '#/components/schemas/CfgFeature' + CfgHaptic: + type: object + properties: + enabled: + description: Haptic feedback enabled. + type: boolean + required: + - enabled + LanguageCode: description: | - Dedicated request object to create a new remote. + Language culture code: starting with the two-letter [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) + code, followed by an optional [ISO-3166 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes), + separated by an underscore. + Examples: `en`, `en_UK`, `en_US`, `de`, `de_DE`, `de_CH` etc. + type: string + pattern: ^[a-z]{2}(_\w+)?$ + CountryCode: + description: Two letter country code according to [ISO-3166-1-alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). + type: string + format: iso-3166 + MeasurementUnit: + type: string + enum: + - METRIC + - US + - UK + CfgLocalization: type: object - allOf: - - properties: - name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' - description: - $ref: '#/components/schemas/LanguageText' - - oneOf: - - type: object - properties: - clone_from: - $ref: '#/components/schemas/EntityId' - required: - - clone_from - - type: object - properties: - codeset_id: - $ref: '#/components/schemas/SimpleId' - required: - - codeset_id - - type: object - properties: - custom_codeset: - type: object - properties: - manufacturer_id: - type: string - default: custom - device_name: - type: string - device_type: - $ref: '#/components/schemas/DeviceType' - required: - - device_name - required: - - custom_codeset - - type: object - properties: - kind: - $ref: '#/components/schemas/RemoteKind' - bt: - $ref: '#/components/schemas/BtRemoteCreateOptions' - required: - - kind - - bt + properties: + language_code: + $ref: '#/components/schemas/LanguageCode' + country_code: + $ref: '#/components/schemas/CountryCode' + time_zone: + description: Time zone name according to IANA , e.g. `Europe/Copenhagen`. + type: string + time_format_24h: + type: boolean + measurement_unit: + $ref: '#/components/schemas/MeasurementUnit' + required: + - language_code + - country_code + - time_zone + - time_format_24h + - measurement_unit + CfgNetworkWoWlan: + description: Wake on WLAN settings + type: object + properties: + enabled: + description: Enable Wake on WLAN. + type: boolean + required: + - enabled + WifiBand: + description: | + WiFi band: + - `auto`: auto-configuration + - `a`: 5 GHz + - `b`: 2.4 GHz + type: string + enum: + - auto + - a + - b + WifiScanInterval: + description: | + Active WiFi scan interval in seconds. A value of 0 disables active scanning. Minimal interval is 10 seconds. + minimum: 0 + type: integer + CfgIpv4Type: + type: string + enum: + - DHCP + CfgIpv4: + type: object + CfgNetworkWifi: + type: object + properties: + wake_on_wlan: + $ref: '#/components/schemas/CfgNetworkWoWlan' + bands: + description: Available WiFi bands + type: array + items: + $ref: '#/components/schemas/WifiBand' + band: + $ref: '#/components/schemas/WifiBand' + scan_interval_sec: + $ref: '#/components/schemas/WifiScanInterval' + ipv4_type: + $ref: '#/components/schemas/CfgIpv4Type' + ipv4: + $ref: '#/components/schemas/CfgIpv4' required: - - name - RemoteFeature: - type: string - enum: - - on_off - - send - RemoteOverview: + - bands + - band + CfgNetworkWs: + description: | + Optional expert settings for WebSocket (re-)connection handling. + These settings are only intended for support issues and might change any time. Changed values are not supported + and might make the system unstable! type: object - allOf: - - $ref: '#/components/schemas/Entity' - - properties: - entity_type: - type: string - enum: - - remote - features: - description: | - Supported features of the remote. - type: array - items: - $ref: '#/components/schemas/RemoteFeature' - options: - type: object - properties: - editable: - description: | - - `true` / property missing: remote was created by UC Remote and can be edited. - - `false`: remote was provided by an integration and cannot be edited. - type: boolean - default: true - RemoteUpdate: + properties: + dock: + type: object + integration: + type: object + CfgNetwork: description: | - Dedicated request object to update an existing remote. - All root properties are optional and only the provided objects are updated in the remote-entity. Omitted objects are - ignored and not deleted from the remote-entity. + `wake_on_wlan` is deprecated, please use `wifi.wake_on_wlan` type: object properties: - name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' - description: - $ref: '#/components/schemas/LanguageText' - options: + bt_enabled: + description: Enable Bluetooth. + type: boolean + wifi_enabled: + description: Enable WiFi. + type: boolean + wake_on_wlan: + $ref: '#/components/schemas/CfgNetworkWoWlan' + wifi: + $ref: '#/components/schemas/CfgNetworkWifi' + bt: + description: Temporary read-only Bluetooth information until dedicated BT management endpoint is provided. type: object properties: - ir: - type: object - properties: - cmd_delay: - description: | - Delay in milliseconds between sending IR commands, if a command contains multiple IR codes. - type: integer - minimum: 0 - repeat: - description: | - Repeat each IR command in the dataset n times. Defaults to 0 (no repeat) if not specified. - This setting is intended mainly for PRONTO codes with certain devices requiring the same command being - sent twice (e.g. Sony and Epson devices). - type: integer - minimum: 0 - maximum: 20 - codeset: - type: object - properties: - id: - type: string - required: - - id - output: - type: object - properties: - device_id: - type: string - port_id: - type: string - required: - - device_id - - port_id - RemoteIrDataSet: + address: + description: Bluetooth MAC address + type: string + ws: + $ref: '#/components/schemas/CfgNetworkWs' + required: + - bt_enabled + - wifi_enabled + CfgPowerSaving: type: object properties: - id: - description: | - Codeset identifier, either a custom codeset id or a manufacturer codeset id depending on `type`. - type: string - name: - description: User friendly name of the codeset (custom or manufacturer). - type: string - type: - $ref: '#/components/schemas/IrCodeSetType' - codes: - type: array - items: - $ref: '#/components/schemas/RemoteIrCode' - RemoteIrCode: + wakeup_sensitivity: + description: Amount of movement needed to wake up the remote. 0 = disabled, 1 = min, 2 = medium, 3 = max. + type: integer + minimum: 0 + maximum: 3 + display_off_sec: + type: integer + minimum: 0 + maximum: 60 + description: Turn off display after given seconds. + standby_sec: + type: integer + minimum: 0 + maximum: 10800 + description: Activate standby after given seconds. 0 disables standby mode. + required: + - wakeup_sensitivity + - display_off_sec + - standby_sec + CfgProfile: type: object properties: - cmd_id: - $ref: '#/components/schemas/SimpleId' - code: + has_admin_pin: + description: An administrator pin has been set to use restricted profiles. + type: boolean + required: + - has_admin_pin + CfgSoftwareUpdate: + type: object + properties: + check_for_updates: description: | - Custom infrared code. Only set for custom codeset or if a manufacturer codeset has been modified or enhanced. - type: object - properties: - value: - type: string - format: - $ref: '#/components/schemas/IrCodeFormat' - custom: + Automatically check for updates. If `auto_update` is enabled, the updates are automatically installed, + otherwise the user is only notified about the updates. + + The time window when to check for new updates can be specified in `ota_window_start` and `ota_window_end`. + Update checks are performed daily. + type: boolean + auto_update: description: | - Flag indicating if this code is a custom code in a manufacturer codeset. This is a manually added code which - was not present in the codeset. Custom codes can be deleted or edited by the user. The modified code is - stored in the `code` object. + Automatically update the remote when new software is available. Requires `check_for_updates` to be enabled. + + Auto-installation of new firmwares will usually happen over 2 update checks: the first check finds a new + update, downloads the metadata and schedules the firmware file to be downloaded. The next check will find the + downloaded firmware file and installs it. type: boolean - modified: + ota_window_start: description: | - Flag indicating if a manufacturer code has been replaced with a user code. The modified code is stored in - the `code` object. Modified codes can be edited by the user. + OTA update window start time: automatic update checks will only be performed during this time window. + Furthermore, the remote needs to be in the docking station and have enough battery charge. + + Format: time of day - as defined by `partial-time` in RFC3339 + type: string + pattern: ^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$ + ota_window_end: + description: | + OTA update window end time. + + - If the end time is before the start time, the window will spawn over midnight, e.g. `23:00:00` - `01:00:00`. + - Both start and end times are required, otherwise a default will be used. + type: string + pattern: ^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$ + channel: + description: | + Software update channels: + - `DEFAULT`: release channel + - `TESTING`: new test and beta versions which might become the next release if successfully tested. + - `DEVELOPMENT`: untested alpha versions from the developers. + ⚠️ High chance of breaking changes, bugs and loosing data! + + Other channels than `DEFAULT` might require an access token in `channel_token`, since they are intended for + a closed user group. + type: string + anyOf: + - enum: + - DEFAULT + - TESTING + - DEVELOPMENT + - {} + channel_token: + description: | + Optional access token which might be required for non-default software update channels. + - This token is write only and cannot be retrieved anymore. + - If omitted when updating settings: the stored token will be used. + - If the `default` channel is selected when updating settings: the token will be ignored. + type: string + pattern: ^[-a-zA-Z0-9._~+/]{1,256}=?$ + restart_required: + description: 'Optional response field only: a configuration change requires a restart.' type: boolean required: - - cmd_id - RemoteKind: + - check_for_updates + - auto_update + CfgSound: + type: object + properties: + enabled: + description: Sound effects enabled. + type: boolean + volume: + description: Sound effects volume. + type: integer + minimum: 0 + maximum: 100 + required: + - enabled + - volume + VoiceAssistantFeature: + description: | + Supported voice assistant or profile features. + - transcription: Supports voice command transcription. + - response_text: Supports textual response about the performed action. + - response_speech: Supports speech response about the performed action. + type: string + enum: + - transcription + - response_text + - response_speech + VoiceAssistantFeatures: + type: array + items: + $ref: '#/components/schemas/VoiceAssistantFeature' + VoiceAssistantProfile: description: | - Type of remote-entity: - - `BT`: Bluetooth remote - - `IR`: Infrared remote - - `EXTERNAL`: Remote-entity provided from an integration to control a single device. - type: string - enum: - - BT - - IR - - EXTERNAL - default: IR - BtRemoteCreateOptions: - description: Options for creating a Bluetooth peripheral remote-entity. + Profiles are optional and allow parameterizing voice input. A regular voice-capable device usually just accepts voice + input without additional parameters. Home automation systems can offer multi-language support or an option to use + local or cloud processing. + + For example, Home Assistant allows configuring multiple Assist pipelines for voice commands. + These pipelines can offer different languages or speech recognition engines. + + - `language` is an optional language code if the profile represents a specific language for speech recognition. + - `features` is optional and overwrites the voice assistant features, for example, if a profile has less or more features. + - An empty `features` array means "no features". type: object properties: - dev_profile_id: - description: | - Bluetooth device profile identifier to customize available commands, button mappings and default UI screens. + id: + $ref: '#/components/schemas/SimpleId' + name: + description: Friendly name to show in UI. type: string - BtRemoteInfo: + minLength: 1 + maxLength: 50 + language: + $ref: '#/components/schemas/LanguageCode' + features: + $ref: '#/components/schemas/VoiceAssistantFeatures' + required: + - id + - name + VoiceAssistantProfiles: + type: array + items: + $ref: '#/components/schemas/VoiceAssistantProfile' + VoiceAssistant: description: | - BT-remote information. + Voice assistant definition. + + This is a tailored representation of the voice_assistant entity, which can be used to display voice assistant + information to users. + + - `profiles` specify optional parameters that can be used by starting a voice command. + - `features` are the default features supported by the voice assistant. + If multiple profiles are supported, this should be the feature list of the preferred profile. + - `preferred_profile` is the preferred profile specified by the integration. + The user can select another default profile in the voice assistant settings. type: object properties: - profile: - description: BT peripheral connection profile - type: integer - dev_profile_id: - description: Bluetooth device profile identifier. + entity_id: + $ref: '#/components/schemas/EntityId' + name: + $ref: '#/components/schemas/LanguageText' + icon: + $ref: '#/components/schemas/IconIdentifier' + state: type: string - dev_profile_version: - description: Bluetooth device profile version. - type: integer - minimum: 0 - peer: - $ref: '#/components/schemas/BtPeer' - peripherals: - $ref: '#/components/schemas/BtDevicePeripherals' + features: + $ref: '#/components/schemas/VoiceAssistantFeatures' + profiles: + $ref: '#/components/schemas/VoiceAssistantProfiles' + preferred_profile: + $ref: '#/components/schemas/SimpleId' required: - - profile - BtRemotePairingInfo: + - entity_id + - name + CfgVoiceAssistant: description: | - BT-remote pairing information. The `pairing_request` field is set if a pairing request is active, `peer` is only - set if the remote has been paired with a central device. + The main voice assistant to use for voice control, if no other voice assistant is configured for a specific + screen, for example, in an activity. type: object properties: - pairing_request: - $ref: '#/components/schemas/BtPairingRequest' - paired: - description: Indicates if BT-remote entity peripheral is paired with a central device. - type: boolean - pairing_enabled: - description: Indicates if a central can pair with this BT-remote peripheral. + active: + $ref: '#/components/schemas/VoiceAssistant' + profile_id: + $ref: '#/components/schemas/SimpleId' + speech_response: + description: Enable speech response if supported by the voice assistant. Disabled by default. type: boolean - advertisement_name: - description: Advertisement name of the peripheral. Usually only set when `pairing_enabled` is true. - type: string - peer: - $ref: '#/components/schemas/BtPeer' - required: - - paired - - pairing_enabled - BtPairingRequest: + default: false + CfgVoiceControl: description: | - A central requests pairing with the peripheral. - ‼️ Only `kind: PasskeyInput` is currently implemented. + Voice control settings with enriched voice assistant configuration. + No voice assistant is enabled if the `voice_assistant.active` object is missing. type: object properties: - id: - description: Pairing request identifier - type: integer - profile: - description: BT peripheral connection profile to associate the pairing request. - type: integer - peer: - $ref: '#/components/schemas/BtPeer' - kind: - $ref: '#/components/schemas/BtSecurityType' - passkey: + microphone: description: | - Only set for `kind: DisplayNumber | NumericComparison` - type: integer - minimum: 0 + Enable microphone. Disabling the microphone will completely turn it off. Voice control and dictation won't work + with the remote or integrations. + type: boolean + voice_assistant: + $ref: '#/components/schemas/CfgVoiceAssistant' required: - - profile - - peer - - kind - BtPairingResponse: - description: | - Response to a BtPairingRequest. - - `Passkey` request: either provide the passkey entered by the user, decline it with `confirm: false`. - - `NumericComparison` request: confirm or decline with `confirm: true | false`. + - microphone + - voice_assistant + CfgAll: type: object - allOf: - - properties: - id: - description: Pairing request identifier. - type: integer - required: - - id - - oneOf: - - type: object - properties: - passkey: - description: '6-digit passkey displayed on the central, sent as text. Leading zero(s) can be included or omitted.' - type: string - minLength: 1 - maxLength: 6 - required: - - passkey - - type: object - properties: - confirm: - description: Confirm or decline a pairing request. - type: boolean - required: - - confirm - BtPeer: - description: Information about the (paired) peer. + properties: + bt: + $ref: '#/components/schemas/CfgBt' + button: + $ref: '#/components/schemas/CfgButtons' + device: + $ref: '#/components/schemas/CfgRemoteDevice' + display: + $ref: '#/components/schemas/CfgDisplay' + features: + $ref: '#/components/schemas/CfgFeatures' + haptic: + $ref: '#/components/schemas/CfgHaptic' + localization: + $ref: '#/components/schemas/CfgLocalization' + network: + $ref: '#/components/schemas/CfgNetwork' + power_saving: + $ref: '#/components/schemas/CfgPowerSaving' + profile: + $ref: '#/components/schemas/CfgProfile' + software_update: + $ref: '#/components/schemas/CfgSoftwareUpdate' + sound: + $ref: '#/components/schemas/CfgSound' + voice: + $ref: '#/components/schemas/CfgVoiceControl' + restart_required: + description: A configuration change requires a restart. + type: boolean + CfgBtUpdate: type: object properties: - address: - description: 'BT address in 00:00:00:00:00:00 format.' - type: string - addr_type: - $ref: '#/components/schemas/BtAddressType' - required: - - address - - addr_type - BtAddressType: - description: | - Address type: - - `LE_PUBLIC`: Public device address - - `LE_RANDOM`: Random device address - - `LE_PUBLIC_IDENTITY`: Public identity address (corresponds to resolved private address) - - `LE_RANDOM_IDENTITY`: Random (static) identity address (corresponds to resolved private address) - - `UNKNOWN`: Address could not be determined, or an error occurred - type: string - enum: - - LE_PUBLIC - - LE_RANDOM - - LE_PUBLIC_IDENTITY - - LE_RANDOM_IDENTITY - - UNKNOWN - BtSecurityType: - description: | - Bonding security type: - - `JustWorks`: Automatic pairing, peripheral only needs to confirm pairing request from central. - - `DisplayNumber`: Peripheral must display number for the central to confirm. - - `NumericComparison`: Peripheral must confirm or declined if the numeric value matches the displayed number on the central. - - `PasskeyInput`: Peripheral must enter displayed passkey on central. - type: string - enum: - - JUST_WORKS - - DISPLAY_NUMBER - - NUMERIC_COMPARISON - - PASSKEY_INPUT + peripheral_connections: + description: Maximum number of peripheral connections at the same time. + type: integer + minimum: 1 + enable_hci_log: + description: Enable HCI logging. + type: boolean + enable_debug_port: + description: Enable BT subsystem debug TCP-port for remote control. + type: boolean BtDeviceProfileInfo: description: | BT device profile overview information. Contains all required device information to make a device selection. @@ -15645,569 +15504,812 @@ components: - peripherals - commands - command_mapping - BtDevicePeripherals: - description: Supported device peripherals. A device can support a single mode or act as a composite device. + CfgButtonsUpdate: + description: Button configuration model to update settings. Missing properties are not changed. type: object properties: - keyboard: - description: Device is a HID keyboard - type: boolean - mouse: - description: Device is a mouse keyboard + brightness: + description: Overall button backlight brightness. 0 = off, 100 = max. + type: integer + minimum: 0 + maximum: 100 + static_color: + $ref: '#/components/schemas/StaticButtonColor' + auto_brightness: + description: When enabled, button backlight will automatically turn on in a dark room. type: boolean - ResourceType: + DeviceButtonGroup: + description: | + Button group type, either physical buttons or button backlight zones: + - `keypad`: physical keypad buttons. + - `keypad_backlight`: button backlight zones. type: string - format: '^[a-zA-Z]+$' - minLength: 1 - maxLength: 32 - ResourceItems: - type: array - items: - $ref: '#/components/schemas/ResourceItem' - ResourceItem: - type: object - properties: - type: - $ref: '#/components/schemas/ResourceType' - id: - type: string - description: Resource identifier (normalized filename) - size: - type: integer - format: int32 - description: Size in bytes - ConfirmationPage: + enum: + - keypad + - keypad_backlight + DeviceButtonLayout: description: | - Confirmation screen. - - `message1`: Message to display between title and image (if supplied). Supports Markdown formatting. - - `message2`: Message to display below message1 or image (if supplied). Supports Markdown formatting. - type: object - properties: - title: - $ref: '#/components/schemas/LanguageText' - message1: - $ref: '#/components/schemas/LanguageText' - image: - description: | - Optional base64-encoded image. + Button group definitions with layout placement, size, icon and language specific names. - TODO maximum encoded length to avoid WebSocket continuation frames, supported image formats - (png & svg?), max height & width - type: string - format: byte - maxLength: 32768 - message2: - $ref: '#/components/schemas/LanguageText' - required: - - title - SettingsPage: - description: 'Settings definition page, e.g. to configure an integration driver.' + The grid width & height definitions do not need to be proportional! To get the correct size, the grid has to be + placed over the physical dimensions of the button group. For example if buttons in a row can be placed in the middle + of another button row, the width value can be doubled, with the button width set to 2. type: object properties: - title: - $ref: '#/components/schemas/LanguageText' - settings: - description: 'One or multiple input field definitions, with optional pre-set values.' + type: + $ref: '#/components/schemas/DeviceButtonGroup' + grid: + $ref: '#/components/schemas/GridSize' + buttons: type: array items: - $ref: '#/components/schemas/Setting' - required: - - title - - settings - Setting: - description: | - 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](https://apps.developer.homey.app/the-basics/devices/settings) concept. - type: object - properties: - id: - description: Unique identifier of the setting to be returned with the entered value. - type: string - maximum: 50 - label: - $ref: '#/components/schemas/LanguageText' - field: - oneOf: - - $ref: '#/components/schemas/SettingTypeNumber' - - $ref: '#/components/schemas/SettingTypeText' - - $ref: '#/components/schemas/SettingTypeTextArea' - - $ref: '#/components/schemas/SettingTypePassword' - - $ref: '#/components/schemas/SettingTypeCheckbox' - - $ref: '#/components/schemas/SettingTypeDropdown' - - $ref: '#/components/schemas/SettingTypeLabel' + type: object + properties: + button: + description: Unique button identifier over all button groups. + type: string + icon: + $ref: '#/components/schemas/IconIdentifier' + name: + $ref: '#/components/schemas/LanguageText' + location: + $ref: '#/components/schemas/GridLocation' + size: + $ref: '#/components/schemas/GridItemSize' + required: + - button + - icon + - name + - location required: - - id - - label - - field - SettingTypeNumber: - description: | - 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 `unit`, which will be displayed next to - the input field. + - type + - grid + - buttons + DeviceScreenLayout: + description: Screen layout definitions with usable grid sizes for custom UI pages. type: object properties: - number: + grid: type: object properties: - value: - description: Default value for input field. + default: + $ref: '#/components/schemas/GridSize' + min: + $ref: '#/components/schemas/GridSize' + max: + $ref: '#/components/schemas/GridSize' + required: + - default + - min + - max + required: + - grid + EntityCmdParamNumber: + type: object + description: | + Number value parameter with optional limits. + allOf: + - $ref: '#/components/schemas/EntityCmdParamCommon' + - properties: + default: + description: Default value to use, e.g. in a UI editor. type: number min: - description: 'Optional validation: minimum allowed value (inclusive).' + description: Minimal allowed value (inclusive). type: number + default: 0 max: - description: 'Optional validation: maximum allowed value (inclusive).' + description: Maximal allowed value (inclusive). type: number - steps: - description: | - Optional validation: allowed step increment between values. Might also be used in the UI for input helpers. + step: + description: Step size between values. type: number - decimals: - description: Number of decimal places. 0 = integer value - type: integer - minimum: 0 - default: 0 + default: 1 unit: - $ref: '#/components/schemas/LanguageText' + description: Optional unit label of the value. + type: string + examples: + - name: + en: Brightness + param: brightness + type: number + default: 22 + min: 0 + max: 100 + step: 1 + unit: '%' + EntityCmdParamBool: + type: object + description: Boolean value parameter. + allOf: + - $ref: '#/components/schemas/EntityCmdParamCommon' + EntityCmdParamRegex: + type: object + description: Text value parameter with optional regex validation. + allOf: + - $ref: '#/components/schemas/EntityCmdParamCommon' + - properties: + regex: + description: Validation regex. + type: string + default: + description: Default value to use, e.g. in a UI editor. + type: string + examples: + - name: + en: Text + param: text + type: regex + regex: ^.{0,255}$ + default: foobar + EntityCmdParamEnum: + type: object + description: Enumeration parameter. Only the defined values are allowed as parameter value. + allOf: + - $ref: '#/components/schemas/EntityCmdParamCommon' + - properties: + values: + type: array + items: + type: string + default: + description: Default value for a new command. Must be a value defined in `values` + type: string required: - - value + - values + examples: + - name: + en: Mode + param: mode + type: enum + values: + - Option 1 + - Option 2 + - Option 3 + default: Option 1 + EntityCmdParamSelection: + type: object + description: Text value parameter with a selection list from another entity field. + allOf: + - $ref: '#/components/schemas/EntityCmdParamCommon' + - properties: + items: + description: Validation regex. + type: object + properties: + source: + description: Where to load the selection list from. + type: string + enum: + - attributes + - options + field: + description: | + Field name in the source object containing an array of strings for the parameter selection + type: string + required: + - source + - field + required: + - items + examples: + - name: + en: Input + param: input + type: selection + items: + source: attributes + field: source_list + EntityCmdParamCommon: + type: object + properties: + name: + $ref: '#/components/schemas/LanguageText' + param: + description: Parameter name. + type: string + type: + description: Parameter type. + type: string + enum: + - number + - bool + - regex + - enum + - selection + optional: + description: Parameter is optional. + type: boolean + default: false required: - - number - SettingTypeText: - description: | - Single line of text input. - - TODO: format specifier for e.g. email, url, date, datetime etc.? + - name + - param + - type + EntityCommandMetadata: type: object properties: - text: - type: object - properties: - value: - description: Optional default value. - type: string - regex: - description: Optional regex validation pattern for the input value. - type: string + id: + description: | + Entity command identifier to be used in activity and macro commands (button mappings, UI elements and sequences). + + This identifier may change at any time and may not be used for logic decisions in a client! + If entity specific information is required, the entity object must be used. + type: string + cmd_id: + description: | + Entity command as specified in the [entity documentation](https://github.com/unfoldedcircle/core-api/tree/main/doc/entities). + This is the command identifier being sent to integration drivers. + type: string + name: + $ref: '#/components/schemas/LanguageText' + params: + description: | + Metadata describing the optional parameters of the command. Simple "button like" commands + don't have any parameters, whereas e.g. a light entity can also dim the light, change color or color + temperature. + type: array + items: + oneOf: + - $ref: '#/components/schemas/EntityCmdParamNumber' + - $ref: '#/components/schemas/EntityCmdParamBool' + - $ref: '#/components/schemas/EntityCmdParamRegex' + - $ref: '#/components/schemas/EntityCmdParamEnum' + - $ref: '#/components/schemas/EntityCmdParamSelection' + discriminator: + propertyName: type + mapping: + number: '#/components/schemas/EntityCmdParamNumber' + bool: '#/components/schemas/EntityCmdParamBool' + regex: '#/components/schemas/EntityCmdParamRegex' + enum: '#/components/schemas/EntityCmdParamEnum' + selection: '#/components/schemas/EntityCmdParamSelection' required: - - text - SettingTypeTextArea: - description: 'Multi-line text input, e.g. for providing a description.' + - id + - cmd_id + - name + CfgFeatureUpdate: type: object properties: - textarea: - type: object - properties: - value: - description: Optional default value. - type: string + id: + type: string + enabled: + type: boolean required: - - textarea - SettingTypePassword: - description: | - Password or pin entry field with the input text hidden from the user. Otherwise the same as text input. + - id + - enabled + CfgNetworkWifiUpdate: type: object properties: - password: - type: object - properties: - value: - description: Optional default value. - type: string - format: password - regex: - description: Optional regex validation pattern for the input value. - type: string - required: - - password - SettingTypeCheckbox: - description: Checkbox setting with `true` / `false` values. + wake_on_wlan: + $ref: '#/components/schemas/CfgNetworkWoWlan' + band: + $ref: '#/components/schemas/WifiBand' + scan_interval_sec: + $ref: '#/components/schemas/WifiScanInterval' + CfgNetworkUpdate: + description: | + `wake_on_wlan` is deprecated, please use `wifi.wake_on_wlan` type: object properties: - checkbox: - type: object - properties: - value: - description: Initial setting. - type: boolean - required: - - value - required: - - checkbox - SettingTypeDropdown: - description: Dropdown setting to pick a single value from a list. All values must be strings. + bt_enabled: + description: Enable Bluetooth. + type: boolean + wifi_enabled: + description: Enable WiFi. + type: boolean + wake_on_wlan: + $ref: '#/components/schemas/CfgNetworkWoWlan' + wifi: + $ref: '#/components/schemas/CfgNetworkWifiUpdate' + ws: + $ref: '#/components/schemas/CfgNetworkWs' + CfgProfileUpdate: type: object properties: - dropdown: - type: object - properties: - value: - description: Pre-selected dropdown id - type: string - items: - type: array - items: - type: object - properties: - id: - description: Selection identifier. - type: string - label: - $ref: '#/components/schemas/LanguageText' - required: - - id - - label - required: - - items - required: - - dropdown - SettingTypeLabel: + admin_pin: + $ref: '#/components/schemas/AdminPin' + CfgVoiceAssistantUpdate: description: | - Additional read-only text for information purpose between other settings. Supports Markdown formatting. + The main voice assistant to use for voice control, if no other voice assistant is configured for a specific + screen, for example, in an activity. type: object properties: - label: - type: object - properties: - value: - $ref: '#/components/schemas/LanguageText' - required: - - value + entity_id: + description: Voice assistant entity id to use, empty for removing a configured voice assistant. + type: string + profile_id: + $ref: '#/components/schemas/SimpleId' + speech_response: + description: Enable speech response if supported by the voice assistant. Disabled by default. + type: boolean required: - - label - SettingsValues: + - entity_id + CfgVoiceControlUpdate: description: | - User input result of a SettingsPage as key values. - - key: id of the field - - value: entered user value as string. This is either the entered text or number, selected checkbox state or the - selected dropdown item id. - ⚠️ Non native string values as numbers or booleans are represented as string values! + Update object for voice control settings. A missing field will keep the old value. type: object - additionalProperties: - type: string - Scopes: + properties: + microphone: + description: | + Enable microphone. Disabling the microphone will completely turn it off. Voice control and dictation won't work + with the remote or integrations. + type: boolean + voice_assistant: + $ref: '#/components/schemas/CfgVoiceAssistantUpdate' + VoiceAssistants: type: array items: - $ref: '#/components/schemas/Scope' - Scope: - type: object - properties: - name: - $ref: '#/components/schemas/ScopeName' - description: - type: string - description: Permission scope description - required: - - name - ScopeName: + $ref: '#/components/schemas/VoiceAssistant' + DockId: type: string - format: '^[a-zA-Z\-:]+$' + format: ^[a-zA-Z0-9\-\.]+$ minLength: 1 - maxLength: 36 - description: Permission scope name - SimpleId: + maxLength: 64 + description: Dock identifier + DockName: type: string - format: '^[a-zA-Z0-9\-_\.]+$' minLength: 1 - maxLength: 36 - description: 'Simple string identifier, also usable as URL parameter or file identifier' - SupportedResource: + maxLength: 40 + description: User assignable friendly name to use instead of dock_id (service name). + DockUrl: + type: string + maxLength: 64 + description: Dock WebSocket URL to override auto-discovery from the service name in `dock_id`. + DockState: + type: string + description: Dock connection state + enum: + - IDLE + - CONNECTING + - ACTIVE + - RECONNECTING + - ERROR + ExternalPortNumber: + description: 1-based port index number. + type: integer + minimum: 1 + ExternalPortMode: + type: string + enum: + - AUTO + - NONE + - INFRARED + - IR_BLASTER + - IR_EMITTER_MONO_PLUG + - IR_EMITTER_STEREO_PLUG + - TRIGGER_5V + - RS232 + ExternalPortActiveMode: + type: string + enum: + - UNKNOWN + - NONE + - ERROR + - INFRARED + - IR_BLASTER + - IR_EMITTER_MONO_PLUG + - IR_EMITTER_STEREO_PLUG + - TRIGGER_5V + - RS232 + UartBaudRate: + description: | + Common baud rate values: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200 + type: integer + minimum: 300 + maximum: 115200 + default: 9600 + UartDataBits: + type: integer + minimum: 5 + maximum: 8 + default: 8 + UartStopBits: + description: Stop bits must be set as string, number format is not supported! + type: string + enum: + - '1' + - '1.5' + - '2' + default: '1' + UartParity: + type: string + enum: + - none + - even + - odd + default: none + UartConfiguration: type: object properties: - type: - $ref: '#/components/schemas/ResourceType' - name: - $ref: '#/components/schemas/LanguageText' - description: - $ref: '#/components/schemas/LanguageText' - file_formats: - description: 'Allowed file format extensions, e.g. `png`.' + baud_rate: + $ref: '#/components/schemas/UartBaudRate' + data_bits: + $ref: '#/components/schemas/UartDataBits' + stop_bits: + $ref: '#/components/schemas/UartStopBits' + parity: + $ref: '#/components/schemas/UartParity' + required: + - baud_rate + - data_bits + - stop_bits + - parity + ExternalPortConfiguration: + description: | + External port configuration. + - `mode`: configured operation mode. + - `active_mode`: active operation mode, usually only set with the detected peripheral for `mode: AUTO`. + type: object + properties: + port: + $ref: '#/components/schemas/ExternalPortNumber' + readOnly: true + mode: + $ref: '#/components/schemas/ExternalPortMode' + active_mode: + $ref: '#/components/schemas/ExternalPortActiveMode' + readOnly: true + supported_modes: + description: Supported modes of the port. type: array items: - type: string - max_file_size: - description: Maximum file size in bytes. - type: integer - max_count: - description: Maximum number of custom resources. - type: integer - image: - description: Image specific restrictions. Only set for image resources. - type: object - properties: - sizes: - description: Allowed image sizes. - type: array - items: - type: object - properties: - width: - type: integer - height: - type: integer - required: - - width - - height - required: - - sizes - sound: - type: object - description: Sound file specific restrictions. Only set for sound resources. - properties: - bits: - type: array - items: - type: integer - channels: - type: array - items: - type: integer - sampling_rates: - type: array - items: - type: integer + $ref: '#/components/schemas/ExternalPortMode' + readOnly: true + uart: + $ref: '#/components/schemas/UartConfiguration' required: - - type - - name - - file_formats - - max_file_size - - max_count - SupportedResources: - type: array - items: - $ref: '#/components/schemas/SupportedResource' - SystemInfo: + - port + - mode + DockConfiguration: type: object properties: - model_name: - description: Friendly name of the device model. + dock_id: + $ref: '#/components/schemas/DockId' + name: + $ref: '#/components/schemas/DockName' + custom_ws_url: + $ref: '#/components/schemas/DockUrl' + resolved_ws_url: type: string - model_number: + maxLength: 64 + description: Resolved WebSocket URL from the service name in `dock_id` if no `custom_ws_url` is used. + active: + type: boolean description: | - Full model number of the remote: - - `ucr2` for Remote Two - - `ucr3-##` for Remote 3, ## suffix indicates color variant + Enable flag: active docks are automatically connected when network is available. + model: type: string - serial_number: + description: Dock model number. + revision: type: string - hw_revision: + description: Dock revision. + serial: type: string - SystemLogBoot: - type: object - properties: - index: + description: Dock serial number. + led_brightness: type: integer - boot_id: - description: Boot identifier usable for querying logs. - type: string - first_entry: + minimum: 0 + maximum: 100 + eth_led_brightness: + type: integer + minimum: 0 + maximum: 100 + connection_type: type: string - format: date-time - last_entry: + description: | + Network connection of the dock: `Ethernet` or `WiFi`. + version: type: string - format: date-time - SystemLogService: + description: Firmware version + state: + $ref: '#/components/schemas/DockState' + learning_active: + type: boolean + description: Dock is in IR learning mode. + port_count: + type: integer + minimum: 0 + ports: + description: 3️⃣ External port mode configuration. + type: array + items: + $ref: '#/components/schemas/ExternalPortConfiguration' + volume: + description: 3️⃣ Speaker volume. + type: integer + minimum: 0 + maximum: 100 + description: + $ref: '#/components/schemas/Description' + required: + - dock_id + - active + DockConfigurations: + type: array + items: + $ref: '#/components/schemas/DockConfiguration' + DockToken: + type: string + format: password + minLength: 1 + maxLength: 40 + description: Access token + DockConfigurationRequest: type: object properties: - service: - description: Service identifier usable for querying logs. - type: string + dock_id: + $ref: '#/components/schemas/DockId' + name: + $ref: '#/components/schemas/DockName' + custom_ws_url: + $ref: '#/components/schemas/DockUrl' + token: + $ref: '#/components/schemas/DockToken' active: - description: Service is active type: boolean - name: - description: Human readable service name + description: | + Enable flag: active docks are automatically connected when network is available. + model: type: string - SystemLogEntry: + description: Dock model number. + description: + $ref: '#/components/schemas/Description' + required: + - dock_id + - active + DiscoveryType: + type: string + description: | + Device discovery type: + - `BT`: Bluetooth + - `NET`: LAN or WAN network + enum: + - BT + - NET + DockDiscovery: type: object properties: - ts: - description: Timestamp of log entry + id: + $ref: '#/components/schemas/DockId' + configured: + description: | + Dock configuration flag for this remote: + - true: device has already been configured + - false: device has not yet been configured + type: boolean + friendly_name: + $ref: '#/components/schemas/DockName' + address: + description: Resolved device network address. type: string - format: date-time - service: - description: Service identifier + model: + description: Detected dock model. type: string - prio: - description: 'Priority, corresponds to [Syslog levels](https://en.wikipedia.org/wiki/Syslog#Severity_level)' - type: integer - msg: - description: Log message + version: + description: Detected firmware version. type: string - SystemLogWebAppCfg: - type: object - properties: - autostart: - description: Automatically run web-app after system start - type: boolean - enabled: - description: State of web-app - type: boolean - password: - description: | - Web-app password. The password can only be set and not retrieved. - An empty value will disable the password, a missing field doesn't change an existing password. + discovery_type: + $ref: '#/components/schemas/DiscoveryType' + timestamp: + description: Timestamp of dock discovery. type: string - pattern: '^[\w*@^(){}\[\]:,.=-]{6,30}$' - TouchSliderUiCfg: - description: | - Remote 3 touch slider configuration. Assign the touch slider to a specific entity feature on a UI screen. - - If no target is specified, the default slider feature is active, unless disabled with the `enabled` property. - - - `enabled: false`: disables the touch slider on the UI screen. Any `target` configuration is removed during update. - - `enabled: true` and no `target`: the default slider feature is active on the UI screen. - - `enabled: true` and `target`: the `target` entity feature is active on the UI screen. + format: date-time + bt: + type: object + description: Optional Bluetooth discovery information. Not present for network device. + properties: + signal: + description: Bluetooth signal strength. 0 = min, 5 = max. + type: integer + minimum: 0 + maximum: 5 + last_seen_sec: + description: | + Last time the device was seen on a Bluetooth scan. Values over 15 sec indicate that the device is no longer + reachable. + type: integer + format: int32 + required: + - id + - configured + - discovery_type + DockDiscoveryStatus: type: object properties: - enabled: + active: description: | - Enables or disables the touch slider. If set to false the slider is not active. - This affects the optional `target` configuration and the default slider feature. + Dock discovery still active or not. type: boolean - default: true - target: - $ref: '#/components/schemas/TouchSliderTarget' + docks: + type: array + items: + $ref: '#/components/schemas/DockDiscovery' required: - - enabled - TouchSliderTarget: - description: The target entity feature to control. + - active + - docks + DockSystemInfo: type: object properties: - entity_id: - $ref: '#/components/schemas/EntityId' - feature: - description: | - The feature to control. One of the listed entity features. - The default slider feature is controlled if not specified. + name: type: string - required: - - entity_id - UiId: - type: string - format: '^[a-zA-Z0-9\-_]+$' - minLength: 1 - maxLength: 36 - description: Unique user interface identifier. - UserInterfaceItem: - description: | - A user interface item is either an icon, text, sensor value or media information from a media-player entity. - - Icon and text items can be static or linked to a command specified in the `command` field. - - The command object can only be used for `icon` and `text` items. - - Default size is 1x1 if not specified. + hostname: + type: string + model: + type: string + revision: + type: string + version: + type: string + serial: + type: string + ir_learning: + type: boolean + ethernet: + type: boolean + wifi: + type: boolean + ssid: + description: Network name (Service Set IDentifier) + type: string + DockSetupFromDiscovery: type: object properties: - type: - $ref: '#/components/schemas/UserInterfaceItemType' - icon: - $ref: '#/components/schemas/IconIdentifier' - text: + id: + $ref: '#/components/schemas/DockId' + friendly_name: + $ref: '#/components/schemas/DockName' + address: + description: Resolved device network address. type: string - minLength: 1 - maxLength: 50 - media_player_id: - $ref: '#/components/schemas/EntityId' - select: - $ref: '#/components/schemas/UserInterfaceItemSelect' - sensor: - $ref: '#/components/schemas/UserInterfaceItemSensor' - command: - $ref: '#/components/schemas/EntityCommand' - location: - $ref: '#/components/schemas/GridLocation' - size: - $ref: '#/components/schemas/GridItemSize' + model: + description: Detected dock model. + type: string + version: + description: Detected firmware version. + type: string + discovery_type: + $ref: '#/components/schemas/DiscoveryType' required: - - type - - location - UserInterfaceItemType: - description: | - Type of the user interface item: - - `icon`: show an icon, either a UC icon or a custom icon. Field `icon` must contain the icon identifier. - - `text`: show text only from field `text`. - - `media_player`: show media information from the specified media-player entity specified in `media_player_id`. - The specified entity_id must be part of the included entities in the activity and of type media-player. - - `select`: show a select box with the specified options from the select entity's `options` attribute. - - `sensor`: show sensor value from the specified sensor entity specified in the `sensor` configuration object. - type: string - enum: - - icon - - text - - numpad - - media_player - - select - - sensor - UserInterfaceItemSelect: - description: | - Select item configuration. - By default, only the selected option value in the `current_option` attribute is shown from the specified - select-entity. - If the user interface `text` field is set, it is used as a widget label, except if `show_name` is set to true. - If no widget label should be shown, omit the item's `text` field and set `show_name` to false. + - id + - discovery_type + DockSetup: type: object + description: Dock setup data properties: - select_id: - $ref: '#/components/schemas/EntityId' - show_name: - description: Show the select-entity name as widget label instead of the user interface item's `text` field. - type: boolean - default: false + name: + $ref: '#/components/schemas/DockName' + token: + $ref: '#/components/schemas/DockToken' + custom_ws_url: + $ref: '#/components/schemas/DockUrl' + description: + $ref: '#/components/schemas/Description' + wifi: + description: | + Optional WiFi information if the dock should connect to (or be prepared for) WiFi instead of Ethernet. + type: object + properties: + ssid: + description: Network name (Service Set IDentifier) + type: string + password: + type: string + format: password + required: + - ssid + - password required: - - select_id - UserInterfaceItemSensor: - description: | - Sensor item configuration. - By default, only the sensor value and unit is shown from the specified sensor entity. - If the user interface `text` field is set, it is used as sensor label, except if `show_label` is set to true. - If no widget label should be shown, omit the item's `text` field and set `show_label` to false. + - name + CreateDockSetup: + type: object + oneOf: + - type: object + properties: + discovery: + $ref: '#/components/schemas/DockSetupFromDiscovery' + required: + - discovery + - type: object + properties: + manually: + $ref: '#/components/schemas/DockSetup' + required: + - manually + DockSetupState: + type: string + enum: + - NEW + - CONFIGURING + - UPLOADING + - RESTARTING + - OK + - ERROR + DockSetupError: + type: string + enum: + - NONE + - NOT_FOUND + - CONNECTION_ERROR + - CONNECTION_REFUSED + - AUTHORIZATION_ERROR + - TIMEOUT + - ABORT + - PERSISTENCE_ERROR + - OTHER + DockSetupInfo: type: object + description: Dock setup state properties: - sensor_id: - $ref: '#/components/schemas/EntityId' - show_label: - description: Show the sensor label instead of the user interface item's `text` field. - type: boolean - default: false - show_unit: - description: Show sensor unit if available. Not shown for binary sensors. - type: boolean - default: true + id: + type: string + name: + $ref: '#/components/schemas/DockName' + model: + type: string + description: Dock model number. + discovery_type: + $ref: '#/components/schemas/DiscoveryType' + state: + $ref: '#/components/schemas/DockSetupState' + error: + $ref: '#/components/schemas/DockSetupError' required: - - sensor_id - AvailableSystemUpdateResponse: + - id + - state + DockUpdateRequest: type: object properties: - update_in_progress: - type: boolean - last_check_date: - description: Last update check timestamp. + name: type: string - format: date-time - next_check_date: - description: Next scheduled update check timestamp. + maxLength: 40 + description: User assignable friendly name to use instead of dock_id (service name). + custom_ws_url: + $ref: '#/components/schemas/DockUrl' + token: type: string - format: date-time - update_check_enabled: + maxLength: 40 + description: Access token to connect to the dock. + active: type: boolean - installed_version: - description: Installed system version. + description: Auto connect to dock when network is available. + description: type: string - available: - type: array - items: - $ref: '#/components/schemas/AvailableSystemUpdate' - required: - - update_check_enabled - - installed_version - - available - AvailableSystemUpdate: + description: Optional description. + wifi: + type: object + properties: + ssid: + description: Network name (Service Set IDentifier) + type: string + maxLength: 32 + password: + type: string + maxLength: 63 + UpdateChannel: + type: string + enum: + - STABLE + - TESTING + - DEVELOPMENT + UpdateDownloadState: + description: | + Download status: + - `PENDING`: update is scheduled to download + - `DOWNLOADING`: update is currently downloading + - `DOWNLOADED`: update has been downloaded and is ready to be installed + - `ERROR`: download failed + type: string + enum: + - PENDING + - DOWNLOADING + - DOWNLOADED + - ERROR + DockFirmwareUpdate: type: object + description: Dock firmware information properties: - id: - description: Update identifier - type: string - title: + model: + description: Dock model type: string description: $ref: '#/components/schemas/LanguageText' @@ -16227,318 +16329,588 @@ components: download: $ref: '#/components/schemas/UpdateDownloadState' required: - - id - - title + - model - description - version - - release_date - - size - UpdateChannel: - type: string - enum: - - STABLE - - TESTING - - DEVELOPMENT - UpdateDownloadState: - description: | - Download status: - - `PENDING`: update is scheduled to download - - `DOWNLOADING`: update is currently downloading - - `DOWNLOADED`: update has been downloaded and is ready to be installed - - `ERROR`: download failed - type: string - enum: - - PENDING - - DOWNLOADING - - DOWNLOADED - - ERROR - UploadSystemImageResponse: + DockUpdateCheck: type: object + description: Dock firmware update check information. properties: - id: - description: Update identifier + dock_id: + type: string + version: + description: Installed firmware version. + type: string + update_available: + description: Whether or not an update is available. An available update is set in the `firmware_update` object. + type: boolean + update_check_enabled: + description: | + Whether or not the online update check is enabled or not. If disabled, `update_available` will always be false. + type: boolean + firmware_update: + $ref: '#/components/schemas/DockFirmwareUpdate' + update_id: + description: Update identifier if an update is currently in progress. type: string required: - - id - SystemUpdateResponse: + - dock_id + - version + - update_available + - update_check_enabled + DockUpdateProgress: type: object + description: Dock firmware update progress properties: - state: - $ref: '#/components/schemas/SystemUpdateState' + dock_id: + type: string update_id: description: Update identifier type: string + version: + description: Firmware version being installed + type: string + progress: + description: Update progress in percent + type: integer + format: int32 + minimum: 0 + maximum: 100 + state: + $ref: '#/components/schemas/DockSetupState' + error: + $ref: '#/components/schemas/DockSetupError' required: - - state + - dock_id - update_id - SystemUpdateProgress: + - version + - state + ExternalPortConfigurations: + type: array + items: + $ref: '#/components/schemas/ExternalPortConfiguration' + ExternalPortConfigurationRequest: type: object properties: - state: - $ref: '#/components/schemas/SystemUpdateState' - update_id: - description: Update identifier + mode: + $ref: '#/components/schemas/ExternalPortMode' + uart: + $ref: '#/components/schemas/UartConfiguration' + required: + - mode + SystemInfo: + type: object + properties: + model_name: + description: Friendly name of the device model. type: string - download_percent: - description: Percent of download - type: integer - download_bytes: - description: Total of bytes to be downloaded - type: integer - format: int64 - total_steps: - description: Total number of update steps + model_number: + description: | + Full model number of the remote: + - `ucr2` for Remote Two + - `ucr3-##` for Remote 3, ## suffix indicates color variant + type: string + serial_number: + type: string + hw_revision: + type: string + BackupReportItem: + type: string + enum: + - db + - integration_driver + - integration + - activity + - macro + - remote + - profile + - dock + - resource + BackupReport: + type: object + properties: + item: + $ref: '#/components/schemas/BackupReportItem' + available: type: integer - current_step: - description: Current installation step index + format: int32 + ok: type: integer - current_percent: - description: Percent in current step + format: int32 + required: + - item + - available + - ok + BackupReports: + type: array + items: + $ref: '#/components/schemas/BackupReport' + BackupSnapshot: + type: object + properties: + id: + description: Backup identifier + type: string + creation_date: + description: Creation date of the backup snapshot + type: string + format: date-time + size: + description: Archive size in bytes type: integer + format: int32 required: - - state - - update_id - SystemUpdateState: + - id + - creation_date + - size + examples: + - id: UCR2_2023-09-17_145305 + creation_date: '2023-09-17T14:53:05+02:00' + size: 2370274 + BackupMetadataVersion: + type: object + properties: + backup: + description: Version of the backup data model in [SemVer](https://semver.org/) format. + type: string + core: + description: Core app version + type: string + os: + description: Operating system version + type: string + required: + - backup + BackupMetadata: + type: object + properties: + id: + description: Backup identifier + type: string + creation_date: + description: Creation date of the backup snapshot + type: string + format: date-time + version: + $ref: '#/components/schemas/BackupMetadataVersion' + report: + $ref: '#/components/schemas/BackupReport' + required: + - id + - creation_date + - version + examples: + - id: UCR2_2023-09-17_145305 + creation_date: '2023-09-17T14:53:05+00:00' + version: + backup: 1.0.0 + core: 0.34.5-beta + os: 1.2.0 + CustomComponent: + description: Type of custom component. type: string enum: - - IDLE - - START - - RUN - - SUCCESS - - FAILURE - - DOWNLOAD - - DONE - - SUB_PROCESS - - PROGRESS - ValidationErrorResponse: + - ui + - web_configurator + ReleaseRequirements: type: object properties: - code: - type: string - description: Error code - message: + firmware_version: + description: | + [SemVer](https://semver.org/) version requirement, describing the intersection of some version comparators to + match the installed UC Remote firmware. + + - `>=1.0`: requires at least version 1.0.0 + - `>=0.9.0, <0.10.0`: only works with minor version 0.9.* + + Follows the Cargo's SemVer support documented in the [Specifying Dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html) + chapter of the Cargo reference. type: string - description: Message describing the validation error. This message is intended for error analysis and should not directly shown to the end user. - errors: - description: Optional validation errors - type: array - items: - $ref: '#/components/schemas/ValidationError' - ValidationError: + CustomRelease: type: object properties: - field: - description: Field identifier with an invalid value. + name: + $ref: '#/components/schemas/LanguageText' + version: + type: string + maxLength: 40 + description: + $ref: '#/components/schemas/LanguageText' + developer: + $ref: '#/components/schemas/DriverDeveloper' + home_page: + description: Optional home page url for more information. type: string - field_errors: - description: | - Optional field validation error descriptions. A field can have multiple validation rules with an error. - type: array - items: - $ref: '#/components/schemas/FieldValidationError' - required: - - field - FieldValidationError: + format: uri + maxLength: 255 + release_date: + description: Release date of the component. + type: string + format: date + requirements: + $ref: '#/components/schemas/ReleaseRequirements' + CustomInstall: + description: Information about an installed custom component. The `installed` flag reports if a custom installation type: object properties: - code: + component: + $ref: '#/components/schemas/CustomComponent' + installed: description: | - Validation error code. This can be a custom code or one of the common pre-defined codes: - - `LENGTH`: String is either too short or too long. - - `RANGE`: Number is not in valid range. - - `REGEX`: Regex validation failed. - - `INVALID_FORMAT`: value is in an invalid format. - type: string - message: - description: Validation rule message. + Custom component has been installed. When `installed: true` is set, more information is returned in `release`. + type: boolean + active: + description: Custom component is active and replacing the default component. + type: boolean + installation_date: + description: 'Installation date of the component. Only provided when `installed: true` is set.' type: string - params: - description: 'Optional code related parameters. E.g. `min`, `max` for string-length or number-range validation.' - type: object + format: date-time + release: + $ref: '#/components/schemas/CustomRelease' required: - - message - VersionInfo: + - component + - installed + - active + SystemLogEntry: type: object properties: - model: - description: | - Short model identifier of the remote (UCR2 for Remote Two, UCR3 for Remote 3). + ts: + description: Timestamp of log entry type: string - device_name: - description: Custom name of the remote + format: date-time + service: + description: Service identifier type: string - hostname: - description: Hostname of the remote + prio: + description: Priority, corresponds to [Syslog levels](https://en.wikipedia.org/wiki/Syslog#Severity_level) + type: integer + msg: + description: Log message type: string - address: - description: MAC address of the remote + SystemLogBoot: + type: object + properties: + index: + type: integer + boot_id: + description: Boot identifier usable for querying logs. type: string - api: - description: API version + first_entry: type: string - core: - description: Core service version + format: date-time + last_entry: type: string - ui: - description: Frontend app version + format: date-time + SystemLogService: + type: object + properties: + service: + description: Service identifier usable for querying logs. type: string - os: - description: Operating system version + active: + description: Service is active + type: boolean + name: + description: Human readable service name type: string - integrations: - description: 'Versions of the available integrations. Map of (integration_name, version).' - type: object - additionalProperties: - type: string - VoiceAssistantUiCfg: - description: | - UI-specific voice assistant configuration. Overrides the global voice assistant. - - - The default voice assistant is used if no target is specified. - - The voice assistant is activated with the voice button. - - A custom voice button command mapping is ignored if a global or a UI-specific voice assistant is configured. + SystemLogWebAppCfg: type: object properties: - target: - $ref: '#/components/schemas/VoiceAssistantTarget' - VoiceAssistantTarget: - description: The specific voice assistant to use. + autostart: + description: Automatically run web-app after system start + type: boolean + enabled: + description: State of web-app + type: boolean + password: + description: | + Web-app password. The password can only be set and not retrieved. + An empty value will disable the password, a missing field doesn't change an existing password. + type: string + pattern: ^[\w*@^(){}\[\]:,.=-]{6,30}$ + PowerMode: + type: string + enum: + - NORMAL + - IDLE + - LOW_POWER + - SUSPEND + PowerModeResponse: type: object properties: - entity_id: - $ref: '#/components/schemas/EntityId' - available: + mode: + $ref: '#/components/schemas/PowerMode' + power_supply: + description: A power supply is online, device doesn't enter standby while connected. + type: boolean + standby_timeout_sec: description: | - Flag indicating if the referenced `entity_id` is still available or is a dangling reference. + Time in seconds until the system goes into standby. + This is the max value of the regular standby and the longest active standby inhibitor. + type: integer + minimum: 0 + standby_inhibitors: + description: | + There are active standby inhibitors preventing system standby. + - A blocking inhibitor will return a constant `standby_timeout_sec` value of `86400` (1 day). type: boolean - profile_id: - $ref: '#/components/schemas/SimpleId' required: - - entity_id - VoiceAssistants: - type: array - items: - $ref: '#/components/schemas/VoiceAssistant' - VoiceAssistant: - description: | - Voice assistant definition. - - This is a tailored representation of the voice_assistant entity, which can be used to display voice assistant - information to users. - - - `profiles` specify optional parameters that can be used by starting a voice command. - - `features` are the default features supported by the voice assistant. - If multiple profiles are supported, this should be the feature list of the preferred profile. - - `preferred_profile` is the preferred profile specified by the integration. - The user can select another default profile in the voice assistant settings. + - mode + - power_supply + - standby_inhibitors + PowerStatus: + type: string + enum: + - CHARGING + - DISCHARGING + - NOT_CHARGING + - FULL + BatteryStatusResponse: + type: object + properties: + capacity: + description: Current battery charge in % + type: integer + minimum: 0 + maximum: 100 + status: + $ref: '#/components/schemas/PowerStatus' + power_supply: + description: A power supply is online, device doesn't run on battery. + type: boolean + required: + - capacity + - status + BatteryCharger: type: object properties: - entity_id: - $ref: '#/components/schemas/EntityId' - name: - $ref: '#/components/schemas/LanguageText' - icon: - $ref: '#/components/schemas/IconIdentifier' - state: - type: string features: - $ref: '#/components/schemas/VoiceAssistantFeatures' - profiles: - $ref: '#/components/schemas/VoiceAssistantProfiles' - preferred_profile: - $ref: '#/components/schemas/SimpleId' + type: array + items: + type: string + power_supply: + description: A power supply is online, device doesn't run on battery. + type: boolean + wireless_charging: + description: Wireless charging is active. Only returned on devices with wireless charging. + type: boolean + wireless_charging_enabled: + description: Wireless charging is enabled. Only returned on devices with wireless charging. + type: boolean required: - - entity_id - - name - VoiceAssistantFeatures: - type: array - items: - $ref: '#/components/schemas/VoiceAssistantFeature' - VoiceAssistantFeature: - description: | - Supported voice assistant or profile features. - - transcription: Supports voice command transcription. - - response_text: Supports textual response about the performed action. - - response_speech: Supports speech response about the performed action. + - features + - power_supply + BatteryChargerUpdate: + type: object + properties: + wireless_charging_enabled: + description: Enable or disable wireless charging. Only supported on devices with wireless charging. + type: boolean + InhibitMode: type: string enum: - - transcription - - response_text - - response_speech - VoiceAssistantProfiles: + - BLOCK + - DELAY + Inhibitor: + type: object + properties: + id: + description: Unique identifier + type: string + who: + description: A descriptive string who is inhibiting + type: string + why: + description: A descriptive string why is being inhibited + type: string + mode: + $ref: '#/components/schemas/InhibitMode' + delay: + description: 'Delay value in seconds for mode: DELAY' + type: integer + minimum: 0 + created: + description: Duration in seconds when this inhibitor was created + type: integer + minimum: 0 + required: + - id + - who + - mode + Inhibitors: type: array items: - $ref: '#/components/schemas/VoiceAssistantProfile' - VoiceAssistantProfile: - description: | - Profiles are optional and allow parameterizing voice input. A regular voice-capable device usually just accepts voice - input without additional parameters. Home automation systems can offer multi-language support or an option to use - local or cloud processing. - - For example, Home Assistant allows configuring multiple Assist pipelines for voice commands. - These pipelines can offer different languages or speech recognition engines. - - - `language` is an optional language code if the profile represents a specific language for speech recognition. - - `features` is optional and overwrites the voice assistant features, for example, if a profile has less or more features. - - An empty `features` array means "no features". + $ref: '#/components/schemas/Inhibitor' + CreateStandbyInhibitor: type: object properties: id: - $ref: '#/components/schemas/SimpleId' - name: - description: Friendly name to show in UI. + description: Unique identifier, automatically crated if not specified. type: string minLength: 1 - maxLength: 50 - language: - $ref: '#/components/schemas/LanguageCode' - features: - $ref: '#/components/schemas/VoiceAssistantFeatures' + maxLength: 64 + who: + description: A descriptive string who is inhibiting + type: string + minLength: 1 + maxLength: 64 + why: + description: A descriptive string why is being inhibited + type: string + maxLength: 64 + delay: + description: Delay standby for given seconds, otherwise block indefinitely until inhibitor is removed. + type: integer + minimum: 1 + required: + - who + AmbientLight: + type: object + properties: + intensity: + description: Light intensity. 0 = pitch black, 65535 = very bright. + type: integer + minimum: 0 + maximum: 65535 + required: + - intensity + AvailableSystemUpdate: + type: object + properties: + id: + description: Update identifier + type: string + title: + type: string + description: + $ref: '#/components/schemas/LanguageText' + version: + type: string + channel: + $ref: '#/components/schemas/UpdateChannel' + release_date: + type: string + format: date + size: + type: integer + format: int64 + release_notes_url: + type: string + format: uri + download: + $ref: '#/components/schemas/UpdateDownloadState' required: - id - - name - ApScanStatus: + - title + - description + - version + - release_date + - size + AvailableSystemUpdateResponse: type: object properties: - active: + update_in_progress: type: boolean - scan: + last_check_date: + description: Last update check timestamp. + type: string + format: date-time + next_check_date: + description: Next scheduled update check timestamp. + type: string + format: date-time + update_check_enabled: + type: boolean + installed_version: + description: Installed system version. + type: string + available: type: array items: - $ref: '#/components/schemas/AccessPointScan' + $ref: '#/components/schemas/AvailableSystemUpdate' required: - - active - - scan - AccessPointScan: + - update_check_enabled + - installed_version + - available + SystemUpdateState: + type: string + enum: + - IDLE + - START + - RUN + - SUCCESS + - FAILURE + - DOWNLOAD + - DONE + - SUB_PROCESS + - PROGRESS + SystemUpdateProgress: type: object properties: - bssid: - description: MAC physical address of the access point (basic service set identifier) - type: string - frequency: - description: 'Frequency of the channel in MHz (e.g., 2412 = channel 1)' + state: + $ref: '#/components/schemas/SystemUpdateState' + update_id: + description: Update identifier type: string - signal_level: - description: Signal level (dBm) + download_percent: + description: Percent of download type: integer - auth: - description: Authentication method - type: string - ssid: - description: | - SSID network name as friendly UTF-8 representation. Use this name to present the network to users, but not for - adding a new network configuration. This is a lossy conversion from the native SSID byte array. - type: string - ssid_hex: - description: | - Hex encoded string of the native SSID byte array. - - Always use this representation, when connecting to a network from a scan result. + download_bytes: + description: Total of bytes to be downloaded + type: integer + format: int64 + total_steps: + description: Total number of update steps + type: integer + current_step: + description: Current installation step index + type: integer + current_percent: + description: Percent in current step + type: integer + required: + - state + - update_id + SystemUpdateResponse: + type: object + properties: + state: + $ref: '#/components/schemas/SystemUpdateState' + update_id: + description: Update identifier type: string required: - - bssid - - ssid - - ssid_hex + - state + - update_id + WpaState: + description: | + - `UNKNOWN`: Unknown state. The driver returned a state which could not be handled. + - `ERROR`: Error retrieving state information. + - `DISCONNECTED`: This state indicates that client is not associated, but is likely to start looking for an access point. This state is entered when a connection is lost. + - `INTERFACE_DISABLED`: This state is entered if the network interface is disabled. The driver refuses any new operations that would use the radio until the interface has been enabled. + - `INACTIVE`: This state is entered if there are no enabled networks in the configuration. The driver is not trying to associate with a new network and external interaction (e.g. add or enable a network) is needed to start association. + - `SCANNING`: Scanning for a network. + - `AUTHENTICATED`: Trying to authenticate with a BSS/SSID. + - `ASSOCIATING`: Trying to associate with a BSS/SSID. + - `ASSOCIATED`: Association completed. + - `FOUR_WAY_HANDSHAKE`: WPA 4-Way Key Handshake in progress. + - `GROUP_HANDSHAKE`: WPA Group Key Handshake in progress. + - `COMPLETED`: All authentication completed. + type: string + enum: + - UNKNOWN + - ERROR + - DISCONNECTED + - INTERFACE_DISABLED + - INACTIVE + - SCANNING + - AUTHENTICATED + - ASSOCIATING + - ASSOCIATED + - FOUR_WAY_HANDSHAKE + - GROUP_HANDSHAKE + - COMPLETED WifiStatus: type: object properties: @@ -16562,7 +16934,7 @@ components: description: Hex encoded string of the native SSID byte array. type: string freq: - description: 'Frequency of the channel in MHz (e.g., 2412 = channel 1)' + description: Frequency of the channel in MHz (e.g., 2412 = channel 1) type: integer address: description: MAC physical address of the WiFi adapter @@ -16595,18 +16967,91 @@ components: description: Link speed (Mbps) type: integer required: - - wpa_state - WifiBand: - description: | - WiFi band: - - `auto`: auto-configuration - - `a`: 5 GHz - - `b`: 2.4 GHz + - wpa_state + WifiCmd: + type: string + enum: + - DISCONNECT + - RECONNECT + - REASSOCIATE + - ENABLE_ALL_NETWORKS + - DISABLE_ALL_NETWORKS + AccessPointScan: + type: object + properties: + bssid: + description: MAC physical address of the access point (basic service set identifier) + type: string + frequency: + description: Frequency of the channel in MHz (e.g., 2412 = channel 1) + type: string + signal_level: + description: Signal level (dBm) + type: integer + auth: + description: Authentication method + type: string + ssid: + description: | + SSID network name as friendly UTF-8 representation. Use this name to present the network to users, but not for + adding a new network configuration. This is a lossy conversion from the native SSID byte array. + type: string + ssid_hex: + description: | + Hex encoded string of the native SSID byte array. + + Always use this representation, when connecting to a network from a scan result. + type: string + required: + - bssid + - ssid + - ssid_hex + ApScanStatus: + type: object + properties: + active: + type: boolean + scan: + type: array + items: + $ref: '#/components/schemas/AccessPointScan' + required: + - active + - scan + NetworkState: type: string enum: - - auto - - a - - b + - CONNECTED + - OUT_OF_RANGE + - DISABLED + - TEMPORARY_DISABLED + SavedNetwork: + description: A saved network configuration (known network) + type: object + properties: + id: + description: Network identification, used for further operations on this network + type: integer + ssid: + description: Network name (service set identifier) + type: string + ssid_hex: + description: Hex encoded string of the native SSID byte array. + type: string + secured: + description: Secured or unsecured network + type: boolean + state: + $ref: '#/components/schemas/NetworkState' + required: + - id + - ssid + - ssid_hex + - secured + SavedNetworks: + type: array + items: + $ref: '#/components/schemas/SavedNetwork' CreateWifiNetwork: type: object properties: @@ -16629,6 +17074,12 @@ components: type: string minLength: 1 maxLength: 63 + WifiNetworkCmd: + type: string + enum: + - ENABLE + - DISABLE + - SELECT ModifyWifiNetwork: type: object properties: @@ -16638,83 +17089,128 @@ components: maxLength: 63 required: - password - SavedNetworks: - type: array - items: - $ref: '#/components/schemas/SavedNetwork' - SavedNetwork: - description: A saved network configuration (known network) + ActivityId: + type: string + format: ^[a-zA-Z0-9\-_]+$ + minLength: 1 + maxLength: 36 + description: Activity identifier + FriendlyName: + type: string + maxLength: 64 + IrStatus: type: object properties: - id: - description: 'Network identification, used for further operations on this network' - type: integer - ssid: - description: Network name (service set identifier) - type: string - ssid_hex: - description: Hex encoded string of the native SSID byte array. - type: string - secured: - description: Secured or unsecured network + dock_id: + $ref: '#/components/schemas/DockId' + learning_active: + description: Dock is in IR learning mode type: boolean state: - type: string - enum: - - CONNECTED - - OUT_OF_RANGE - - DISABLED - - TEMPORARY_DISABLED - required: - - id - - ssid - - ssid_hex - - secured - WpaState: - description: | - - `UNKNOWN`: Unknown state. The driver returned a state which could not be handled. - - `ERROR`: Error retrieving state information. - - `DISCONNECTED`: This state indicates that client is not associated, but is likely to start looking for an access point. This state is entered when a connection is lost. - - `INTERFACE_DISABLED`: This state is entered if the network interface is disabled. The driver refuses any new operations that would use the radio until the interface has been enabled. - - `INACTIVE`: This state is entered if there are no enabled networks in the configuration. The driver is not trying to associate with a new network and external interaction (e.g. add or enable a network) is needed to start association. - - `SCANNING`: Scanning for a network. - - `AUTHENTICATED`: Trying to authenticate with a BSS/SSID. - - `ASSOCIATING`: Trying to associate with a BSS/SSID. - - `ASSOCIATED`: Association completed. - - `FOUR_WAY_HANDSHAKE`: WPA 4-Way Key Handshake in progress. - - `GROUP_HANDSHAKE`: WPA Group Key Handshake in progress. - - `COMPLETED`: All authentication completed. + $ref: '#/components/schemas/DockState' + codes: + type: array + items: + $ref: '#/components/schemas/LearnedIrCode' + MediaPlayerRepeatMode: type: string enum: - - UNKNOWN - - ERROR - - DISCONNECTED - - INTERFACE_DISABLED - - INACTIVE - - SCANNING - - AUTHENTICATED - - ASSOCIATING - - ASSOCIATED - - FOUR_WAY_HANDSHAKE - - GROUP_HANDSHAKE - - COMPLETED - WifiCmd: + - 'OFF' + - ALL + - ONE + MediaPlayAction: + description: | + The media play action is used to specify how the media item should be played. + + Notes: + - Common values are defined as enum variants. Using these values is recommended, so the UI can show locale aware commands. + - Integrations can use their custom values, but they might not be available in the UI. type: string - enum: - - DISCONNECT - - RECONNECT - - REASSOCIATE - - ENABLE_ALL_NETWORKS - - DISABLE_ALL_NETWORKS - WifiNetworkCmd: + maxLength: 20 + anyOf: + - enum: + - PLAY_NOW + - PLAY_NEXT + - ADD_TO_QUEUE + - {} + default: PLAY_NOW + QueueItem: + description: 🚧 initial draft, do not use! + type: object + properties: + queue_item_id: + type: string + description: Unique identifier for the item within this queue instance. + media_id: + type: string + description: Unique identifier for the item (opaque to Core-API). + title: + type: string + description: Display name. + media_class: + $ref: '#/components/schemas/MediaClass' + media_type: + $ref: '#/components/schemas/MediaContentType' + can_browse: + type: boolean + description: If `true`, the item can be browsed (is a container). + can_play: + type: boolean + description: If `true`, the item can be played directly. + thumbnail: + type: string + description: URL to download the image, or a base64 encoded data. + artist: + type: string + description: Artist name. + album: + type: string + description: Album name. + duration: + type: integer + description: Duration in seconds. + required: + - queue_item_id + - media_id + - title + MediaQueueResponse: + description: 🚧 initial draft, do not use! + type: object + properties: + items: + type: array + items: + $ref: '#/components/schemas/QueueItem' + current_index: + type: integer + description: Absolute index of the currently playing item within the full queue. + required: + - items + Pages: + type: array + items: + $ref: '#/components/schemas/Page' + UiId: type: string - enum: - - ENABLE - - DISABLE - - SELECT + format: ^[a-zA-Z0-9\-_]+$ + minLength: 1 + maxLength: 36 + description: Unique user interface identifier. + UploadSystemImageResponse: + type: object + properties: + id: + description: Update identifier + type: string + required: + - id + ActivityRequest: + $ref: '#/components/schemas/ActivityCreate' + AmbientLightResponse: + $ref: '#/components/schemas/AmbientLight' responses: - SuccessMessage: - description: Successful operation + Err500InternalServerError: + description: The server has encountered a situation it does not know how to handle. Retrying the same request will most likely result in the same error. content: application/json: schema: @@ -16732,7 +17228,7 @@ components: schema: $ref: '#/components/schemas/ApiResponse' Err403Forbidden: - description: 'The request is understood, but the client does not have access rights to the content.' + description: The request is understood, but the client does not have access rights to the content. content: application/json: schema: @@ -16743,56 +17239,56 @@ components: application/json: schema: $ref: '#/components/schemas/ApiResponse' - Err408RequestTimeout: - description: The request timed out. + Err422UnprocessableEntity: + description: The request was well-formed but cannot be processed. Used for already existing data which cannot be re-created. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' - Err409Conflict: - description: The request conflicts with the current state of the target resource. + SuccessMessage: + description: Successful operation content: application/json: schema: $ref: '#/components/schemas/ApiResponse' - Err413PayloadTooLarge: - description: Request entity is too large and not supported. + Err507InsufficientStorage: + description: There is insufficient storage to store the resource. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' - Err415UnsupportedMediaType: - description: The media format of the requested data is not supported. + Err503ServiceUnavailable: + description: The server is not ready to handle the request. Try again later. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' - Err422UnprocessableEntity: - description: The request was well-formed but cannot be processed. Used for already existing data which cannot be re-created. + Err409Conflict: + description: The request conflicts with the current state of the target resource. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' - Err429TooManyRequests: - description: The client has sent too many requests in a given amount of time. + Err413PayloadTooLarge: + description: Request entity is too large and not supported. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' - Err500InternalServerError: - description: The server has encountered a situation it does not know how to handle. Retrying the same request will most likely result in the same error. + Err408RequestTimeout: + description: The request timed out. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' - Err503ServiceUnavailable: - description: The server is not ready to handle the request. Try again later. + Err415UnsupportedMediaType: + description: The media format of the requested data is not supported. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' - Err507InsufficientStorage: - description: There is insufficient storage to store the resource. + Err429TooManyRequests: + description: The client has sent too many requests in a given amount of time. content: application/json: schema: diff --git a/core-api/rest/redocly.yaml b/core-api/rest/redocly.yaml new file mode 100644 index 0000000..008fb0e --- /dev/null +++ b/core-api/rest/redocly.yaml @@ -0,0 +1,7 @@ +extends: + - recommended +rules: + # our service runs on localhost! + no-server-example.com: off + # TODO check later + operation-4xx-response: off