Remote Two/3 WebSocket Core-API 0.33.0-beta

The Unfolded Circle WebSocket Core-API for Remote Two/3 (UCR WS Core-API in short) allows to interact with the Unfolded Circle remote-core service and take control of most of its features. It is a subset of the UCR REST Core-API, but provides additional asynchronous event messages.

API message status legend:

Icon Description
💡 Idea, not yet official part of API definition.
🚧 Planned feature and most likely not (fully) implemented in the initial release.
👷 API definition is work in progress, not ready yet for implementation.
🔍 API definition review & implementation.
🧪 API has been implemented in the UC Remote and is currently being tested.
🚀 Ready to use - feedback welcomed.

Overview

The Unfolded Circle Remote Core-APIs consist of:

The remote-core service acts as WebSocket server. Whenever the remote enters standby it may choose to disconnect client connections.

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.

🚧 Missing Features

This API is a work-in-progress and does not yet contain all functionality of the REST API.

The following features will be continuously added (in no particular order):

  • Matching features of the REST Core-API (except file up & download):
    • Activity management
    • Infrared code management
  • Static network configuration

Please check the core-api GitHub issues for the current state.

API Versioning

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

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

WebSocket Connection

Authentication

Interaction with the API requires an API-key, user account or a session cookie (see login operation in the REST Core-API).

If the session cookie is sent with the WebSocket upgrade request, the connection is automatically authenticated. This is recommended when using a web browser as client.

Basic authentication

A user account can be used with basic authentication in the WebSocket upgrade.

  • Header name: Authentication.
  • Value: Basic + base64 encoded value of ${username}:${password}

API-key authentication

If the session based login is not possible or the client needs to use an API-key, then the preferred way to establish an authenticated WebSocket connection is to provide the API-key in the header of the WebSocket connection.

  • Header name: API-KEY.
  • Value: API key

API keys can be created with the REST API and the auth/api_keys endpoints.

Message based authentication

If the client cannot provide the API-key in the connection setup (e.g. a web browser), the server will send the auth_required message right after the connection is established.

  • The client must reply with the auth message containing the API-key.

    • All other messages will be ignored, until the client successfully authenticates itself.
    • The server will close an unauthenticated connection after a timeout of 15 seconds.

  • The server replies with the authentication event including the result code of the authentication.

    • 200: authentication succeeded, API can be used.
    • 401: invalid authentication and the connection will be closed.
  • #integration
  • #entity
  • #profile
  • #dock
  • #wifi

Servers

  • localhost:8080wstest

    Local test server.

    Security:
    • HTTP API key
      • Name: API-KEY
      • In: header

      The API-key can be provided in header key API-KEY.

      • If this header is not provided, the server will send the auth_required event after connection and the client must authenticate with the auth message.
    • HTTP
      • Scheme: basic

      To login with a user account, basic authentication can be used for the WebSocket upgrade. As an alternative, a session based login with the REST API can be performed. The session cookie will automatically authenticate the Websocket connection.

  • localhost:8443wsstest-wss

    Local test server.

    Security:
    • HTTP API key
      • Name: API-KEY
      • In: header

      The API-key can be provided in header key API-KEY.

      • If this header is not provided, the server will send the auth_required event after connection and the client must authenticate with the auth message.
    • HTTP
      • Scheme: basic

      To login with a user account, basic authentication can be used for the WebSocket upgrade. As an alternative, a session based login with the REST API can be performed. The session cookie will automatically authenticate the Websocket connection.

Operations

  • PUB /ws

    Core-API for clients to interact with the remote.

    Operation IDpubRemoteMessage
    • #core

    Accepts one of the following messages:

    • #0auth

      🧪 Authenticate a connection.

      Sent by the client right after establishing a connection if header authentication cannot be used, or after an auth_required request by the server.

      object allOf
      uid: authRequestMsg

      Examples

    • #1ping

      🚀 Application level based ping to determine whether connection is alive.

      Client can ping the server to determine whether connection is alive. Server responds with pong.

      This is an application level ping as opposed to the standard WebSocket ping frames. This is only required if a client framework doesn't support WebSocket ping frames!
      Additional payload data may be included in msg_data which will be echoed by the server. E.g. a client timestamp to calculate round trip times.

      object allOf
      uid: ping

      Examples

    • #2version

      🚀 Get version information.

      object allOf
      uid: versionMsg

      Examples

    • #3system

      🚀 Get system information.

      Get hardware information about the device like serial number, model number and hardware revision.

      object allOf
      uid: getSystemInfoMsg

      Examples

    • #4system_cmd

      🧪 Perform a system command like reboot or power-off.

      The following system commands can be executed:

      • STANDBY: Put the device into standby mode.
      • REBOOT: Reboot the device.
      • POWER_OFF: Switch off the device
      • RESTART: Restart all applications.
      • RESTART_UI: Restart the ui application.
      • RESTART_CORE: Restart the core service application.

      The server will respond with a result message and a status code of the request.
      For status code 200 the WebSocket connection will be closed and the command executed.

      object allOf
      uid: systemCmdMsg

      Examples

    • #5get_factory_reset_token

      Get factory reset token.

      Get a factory reset token to perform a complete factory reset of the remote.

      The token will be valid for 60 seconds. Afterwards, a new token must be requested.
      Whenever a new token is requested, any old tokens will be invalidated.

      object allOf
      uid: getFactoryResetTokenMsg

      Examples

    • #6factory_reset

      Perform a factory reset.

      A factory reset removes all configuration data and puts the device into a clean state.

      ⚠️ Warning: All user data will be erased and won't be recoverable!

      A reset token must be requested first and provided to perform a factory reset.

      object allOf
      uid: factoryResetMsg

      Examples

    • #7set_api_access

      Enable or disable API access.

      Enable / disable API access for web-configurator. If the account gets disabled, all active sessions are closed and WebSocket connections disconnected.
      The server will respond with a result message and a status code of the request.

      object allOf
      uid: setApiAccessMsg

      Examples

    • #8get_api_access

      Get API access status.

      The server will respond with an api_access message.

      object allOf
      uid: getApiAccessMsg

      Examples

    • #9check_system_update

      🧪 Check if system update is available.

      Returns the known available system updates.

      System update checks are run automatically (if not disabled in settings). Use the force_update flag to force an update check.

      object allOf
      uid: checkSystemUpdateMsg

      Examples

    • #10update_system

      🧪 Perform system update.

      Start a system update with the given update_id parameter. Use latest to use the latest available system update.

      The system update will be started if:

      • the system update has been downloaded already (download state is DOWNLOADED).
      • the device has at least 50% battery charge.

      If the system update is started, the response message contains state: START. In case there's not enough battery, 503 service unavailable is returned. It is recommended to perform the update while the remote is charging in the docking station.

      The progress of the system update can be retrieved with the get_system_update_progress message, or by listening to the software_update event messages.

      If the system update hasn't been downloaded yet (download state is PENDING or ERROR), this operation will only start the download and return state: DOWNLOAD. Once successfully downloaded, it can be installed by this request message again.

      The download process emits software_update progress event messages with event_type: PROGRESS and state: DOWNLOAD. The payload fields download_bytes, download_percent and update_id are set.

      • A successful download is indicated with download_percent: 100, without the download_bytes field.
      • The state is set to FAILURE if a download fails.
      • Depending on download speed, download_percent might skip certain values or report the same value multiple times.
      • The famous last percent will take longer due to image validation.

      Example download progress events:

      • Download progress event:
      {
  "kind": "event",
  "msg": "software_update",
  "cat": "REMOTE",
  "ts": "2024-09-30T16:25:18.668395688Z",
  "msg_data": {
    "event_type": "PROGRESS",
    "progress": {
      "download_bytes": 256734720,
      "download_percent": 97,
      "state": "DOWNLOAD",
      "update_id": "some-id"
    },
    "update_id": "some-id"
  }
}
      • Final success event:
      {
  "kind": "event",
  "msg": "software_update",
  "cat": "REMOTE",
  "ts": "2024-09-30T16:25:34.229442566Z",
  "msg_data": {
    "event_type": "PROGRESS",
    "progress": {
      "download_percent": 100,
      "state": "DOWNLOAD",
      "update_id": "some-id"
    },
    "update_id": "some-id"
  }
}
      object allOf
      uid: updateSystemMsg

      Examples

    • #11get_system_update_progress

      🧪 Get system update progress.

      This is a manual request for the update progress if the system update event messages cannot be used.

      object allOf
      uid: getSystemUpdateProgressMsg

      Examples

    • #12get_power_mode

      🧪 Get current power mode, battery information and duration to enter standby.

      Returns the current power mode of the device, if a power-supply is connected and the duration in seconds until the the device will enter standby.

      • standby_timeout_sec is not returned if standby is disabled or the device is currently in the process of entering or exiting standby.
      • standby_timeout_sec can return 0 without the device going into standby.
        This is the case if power_supply: true is set. As soon as the power supply is offline, the device will enter standby after a few seconds if no input activity is registered.
      object allOf
      uid: getPowerModeMsg

      Examples

    • #13set_power_mode

      🧪 Change the current power mode.

      object allOf
      uid: setPowerModeMsg

      Examples

    • #14get_battery_charger

      🔍 Get battery charger information.

      Device features:

      • DOCK_CHARGING: device can be charged in docking station (UCR2, UCR3).
      • WIRELESS_CHARGING: device has wireless charging support (UCR3).
      object allOf
      uid: getBatteryChargerMsg

      Examples

    • #15update_battery_charger

      🔍 Enable or disable wireless charging.

      object allOf
      uid: updateBatteryChargerMsg

      Examples

    • #16get_standby_inhibitors

      🧪 Get standby inhibitors.

      Automatic system standby can be prevented with "standby inhibitors". For example during integration setup or as a user option for activities.

      There are two types of inhibitors:

      • Temporary inhibitors set a delay value for which the device doesn't go into standby. After the delay and the idle timeouts have expired, the remote goes into standby and the temporary inhibitor will be removed.
      • Blocking inhibitors will prevent the device to go into standby until the inhibitor is removed by the client.
      object allOf
      uid: getStandbyInhibitorsMsg

      Examples

    • #17create_standby_inhibitor

      🧪 Create a standby inhibitor.

      object allOf
      uid: createStandbyInhibitorMsg

      Examples

    • #18del_standby_inhibitor

      🧪 Remove a standby inhibitor.

      object allOf
      uid: delStandbyInhibitorMsg

      Examples

    • #19del_all_standby_inhibitors

      🧪 Remove all standby inhibitors.

      object allOf
      uid: delAllStandbyInhibitorsMsg

      Examples

    • #20get_ambient_light

      🔍 Get current ambient light intensity.

      object allOf
      uid: getAmbientLightMsg

      Examples

    • #21reset_configuration

      🧪 Reset all settings to default values.

      object allOf
      uid: resetConfigurationMsg

      Examples

    • #22get_configuration

      🧪 Get all system settings.

      object allOf
      uid: getConfigurationMsg

      Examples

    • #23get_button_cfg

      🧪 Get button settings.

      object allOf
      uid: getButtonCfgMsg

      Examples

    • #24set_button_cfg

      🧪 Modify button settings.

      object allOf
      uid: setButtonCfgMsg

      Examples

    • #25get_device_cfg

      🧪 Get remote device settings.

      object allOf
      uid: getDeviceCfgMsg

      Examples

    • #26set_device_cfg

      🧪 Modify remote device settings.

      object allOf
      uid: setDeviceCfgMsg

      Examples

    • #27get_display_cfg

      🧪 Get display settings.

      object allOf
      uid: getDisplayCfgMsg

      Examples

    • #28set_display_cfg

      🧪 Modify display settings.

      object allOf
      uid: setDisplayCfgMsg

      Examples

    • #29get_features_cfg

      🧪 Get feature flag settings.

      object allOf
      uid: getFeaturesCfgMsg

      Examples

    • #30set_features_cfg

      🧪 Modify a feature flag.

      object allOf
      uid: setFeaturesCfgMsg

      Examples

    • #31get_haptic_cfg

      🧪 Get haptic settings.

      object allOf
      uid: getHapticCfgMsg

      Examples

    • #32set_haptic_cfg

      🧪 Modify haptic settings.

      object allOf
      uid: setHapticCfgMsg

      Examples

    • #33get_localization_cfg

      🧪 Get localization settings.

      object allOf
      uid: getLocalizationCfgMsg

      Examples

    • #34set_localization_cfg

      🧪 Modify localization settings.

      object allOf
      uid: setLocalizationCfgMsg

      Examples

    • #35get_timezone_names

      🧪 Get all available time zone names.

      object allOf
      uid: getTimezoneNamesMsg

      Examples

    • #36get_localization_countries

      🧪 Get available countries for the localization configuration.

      object allOf
      uid: getLocalizationCountriesMsg

      Examples

    • #37get_localization_languages

      🧪 Get stored translations or request available translations from the UI.

      The available translations are provided from the UI application.
      Future UI versions might provide new or updated translations.

      If this request is sent to the UI application, the response is stored in the remote-core until new information is available from the UI.

      If this request is received, the stored configuration from the UI application is returned. E.g. the web-configurator requires the available translations.

      object allOf
      uid: getLocalizationLanguagesMsg

      Examples

    • #38localization_languages

      🧪 Available translations response.

      object allOf
      uid: localizationLanguagesMsg

      Examples

    • #39get_network_cfg

      🧪 Get network settings.

      object allOf
      uid: getNetworkCfgMsg

      Examples

    • #40set_network_cfg

      🧪 Modify network settings.

      Change one or multiple network settings.

      ⚠️ The ws configuration object is an expert setting intended for support issues. Those settings may not be exposed in a user frontend.

      • The ws object is only returned, after it has been set manually.
      • Settings stay persisted for PATCH requests not containing the ws key.
      • Return and apply current system settings: send a PATCH request with an empty object: `"ws": {}".
      • The ws settings can be removed with a network configuration reset reset_network_cfg or through a full configuration reset: reset_configuration
      • Modifying any ws settings requires a system reboot.
      object allOf
      uid: setNetworkCfgMsg

      Examples

    • #41reset_network_cfg

      🧪 Reset network settings.

      Reset all network settings to their defaults.

      The expert settings in the ws configuration object will be removed.

      object allOf
      uid: resetNetworkCfgMsg

      Examples

    • #42get_software_update_cfg

      🧪 Get software update settings.

      object allOf
      uid: getSoftwareUpdateCfgMsg

      Examples

    • #43set_software_update_cfg

      🧪 Modify software update settings.

      Change one or multiple software update settings.

      If check_for_updates is enabled:

      • the device automatically checks for new updates daily. The check happens during a random time within the OTA window time frame ota_window_start - ota_window_end.
      • if a new update is available, the update metadata is immediately downloaded and the firmware update file is scheduled to download.
      • the firmware file will only download if the remote has at least 50% battery charge.
      • if the remote is not in the dock and suspended, the remote will not automatically wake up and the check will be skipped.

      If auto_update is enabled:

      • once the firmware file is downloaded it will be automatically installed in the next OTA check window.
      • the installation will only start if the remote has at least 50% battery charge.

      OTA window fields:

      • the stored values are used if omitted.
      • default values are set if not configured.
      • the time of day corresponds to the configured timezone.
      • for changing the update window, both start and end times are required, otherwise a default will be used.
      • if the end time is before the start time, the window will spawn over midnight, e.g. 23:00:00 - 01:00:00.

      Optional software update channel & token:

      • the default release channel is used if not configured.
      • the stored values are used if omitted.
      • changing the update channel is intended for closed user groups only.
        ⚠️ High chance of breaking changes, bugs and loosing data!
      • other channels than default might require an access token in channel_token.
      • ⚠️ Changing the update channel or token requires a device restart, otherwise the automated updates will not use the new channel!
      object allOf
      uid: setSoftwareUpdateCfgMsg

      Examples

    • #44reset_software_update_cfg

      🧪 Reset software update settings.

      Set all software update settings to default values and use the default release update channel.

      object allOf
      uid: resetSoftwareUpdateCfgMsg

      Examples

    • #45get_power_saving_cfg

      🧪 Get power saving settings.

      object allOf
      uid: getPowerSavingCfgMsg

      Examples

    • #46set_power_saving_cfg

      🧪 Modify power saving settings.

      object allOf
      uid: setPowerSavingCfgMsg

      Examples

    • #47get_profile_cfg

      🧪 Get profile settings.

      object allOf
      uid: getProfileCfgMsg

      Examples

    • #48set_profile_cfg

      🧪 Modify profile settings.

      object allOf
      uid: setProfileCfgMsg

      Examples

    • #49get_sound_cfg

      🧪 Get sound settings.

      object allOf
      uid: getSoundCfgMsg

      Examples

    • #50set_sound_cfg

      🧪 Modify sound settings.

      object allOf
      uid: setSoundCfgMsg

      Examples

    • #51get_voice_control_cfg

      🔍 Get voice control settings.

      object allOf
      uid: getVoiceControlCfgMsg

      Examples

    • #52set_voice_control_cfg

      🔍 Modify voice control settings.

      Change one or multiple voice control settings. A missing field will in the request object will keep the old value.

      If the specified voice control entity does not exist, the voice assistant configuration will be removed.

      object allOf
      uid: setVoiceControlCfgMsg

      Examples

    • #53get_voice_assistants

      🔍 Get available voice assistants.

      object allOf
      uid: getVoiceAssistantsMsg

      Examples

    • #54get_entity_types

      🧪 Retrieve supported entity types.

      object allOf
      uid: getEntityTypesMsg
      • #entity

      Examples

    • #55get_entity

      🧪 Retrieve a configured entity.

      object allOf
      uid: getEntityMsg
      • #entity

      Examples

    • #56get_entities

      🧪 Search and retrieve configured entities.

      Returns all configured entities, optionally filtered by one or multiple entity types or integrations.

      The text search searches in the entity name, entity identifier and integration name.

      The exclude query parameter allows to exclude entities defined in an activity, macro, profile page or group. Supported exclusions:

      • activity- or macro-entity ID: all included entities
      • profile page_id: defined entities in the page
      • profile group_id: defined entities in the group

      Notes:

      • Mixing activity/macro and page/group identifiers is not supported!
      • All non-command entities are also filtered out if an activity or macro identifier is specified.

      Attention: pagination is active and can be parameterized to return more items per page if required.

      object allOf
      uid: getEntitiesMsg
      • #entity

      Examples

    • #57get_available_entities

      🧪 Retrieve the available entities provided by an integration.

      ⚠️ At the moment it's only possible to retrieve available entities from one integration at a time.

      • filter.integration_id must be specified!
      • available entities can be filtered by one or multiple entity types.
      • the text search searches in the entity name, entity identifier and area.

      Attention: pagination is active and can be parameterized to return more items per page if required.

      object allOf
      uid: getAvailableEntitiesMsg

      Retrieve the available entities provided by the integration instance.

      • #entity

      Examples

    • #58get_entity_commands

      🧪 Retrieve the available commands of an entity or entity type.

      The commands can either be retrieved from a specific entity or from an entity type:

      • entity_id: only available commands for the given entity are returned. This depends on the entity's features.
      • entity_type: all commands for the given entity type are returned.

      The returned command identifiers are not the standard command identifiers like on or off, but mapping identifiers like light.on and light.color_temperature for the command structure information returned with get_entity_command_metadata or GET /api/cfg/entity/commands.

      This then allows to build a full command request execute_entity_command message with or without parameters.

      object allOf
      uid: getEntityCommandsMsg
      • #entity

      Examples

    • #59get_entity_command_metadata

      🔍 Get entity command definitions.

      Meta-information about the entity commands.

      object allOf
      uid: getEntityCommandMetadataMsg
      • #entity

      Examples

    • #60execute_entity_command

      🧪 Execute an entity command.

      Optional command data can be provided in attribute params.

      object allOf
      uid: executeEntityCommandMsg
      • #entity

      Examples

    • #61update_entity

      🧪 Update an entity.

      Update one or multiple properties of an entity.

      The updated entity object is returned if the entity could be updated.
      In case of an error the default result message is returned with an error code.

      object allOf
      uid: updateEntityMsg
      • #entity

      Examples

    • #62delete_entity

      🧪 Remove a configured entity.

      Delete the configured entity and remove it from all profile pages and groups.

      object allOf
      uid: deleteEntityMsg
      • #entity

      Examples

    • #63delete_entities

      🧪 Remove configured entities.

      Unloads and deletes multiple configured entities, either by integration identifier or by entity identifiers. If a deleted entity is still provided from an integration, it can be reused and will show up again as available entity from its integration.

      ⚠️ An empty request body array will delete all configured entities!

      All references to the configured entities will be removed from profile pages and groups.

      This is a best effort operation:

      • unknown entity identifiers are ignored, no error is returned

      Deleted entities will trigger an entity_change event with event_type: DELETE. If a large amount of entities are deleted, a single, generic entity_change event might be sent instead (without an entity_id field).

      object allOf
      uid: deleteEntitiesMsg
      • #entity

      Examples

    • #64get_dock_count

      🧪 Get total number of configured docks.

      By default only active docks are counted. This can be changed with the active query parameter.

      object allOf
      uid: getDockCountMsg
      • #dock

      Examples

    • #65get_docks

      🧪 List configured docks and their connection state.

      Returns all dock configuration with paging. The configuration data is enriched with current connection information. Use the get_dock_count operation to retrieve the total number of defined docking stations.

      By default only active docks are returned. This can be changed with the active query parameter.

      object allOf
      uid: getDocksMsg
      • #dock

      Examples

    • #66create_dock

      🧪 Create a new dock configuration.

      Manually create and persist a new dock configuration. This is a low-level operation without configuring and setting up the dock as with the setup operations! To establish a session to the dock, the connect operation must be called afterwards.

      • Error 422 is returned if the given service name in dock_id already exists.
      • If custom_ws_url is not specified, the dock address is resolved through an mDNS service name lookup in dock_id.
      • The active flag specifies if the dock will react to connection requests.
      • Non-active docks will not auto-connect and must be enabled first to be used.
      • Non-active docks won't be visible in the web-configurator.
      • If no token is provided the default token is used! The token is used to authenticate the WebSocket connection once a connection to the dock is established.
      • If model is provided it must be one of the known dock model identifiers: UCD2 or YIO1DOCK.
      object allOf
      uid: createDockMsg
      • #dock

      Examples

    • #67delete_all_docks

      🧪 Delete all dock configurations.

      ⚠️ All defined dock configurations will be irrevocably deleted!

      Active dock sessions will be disconnected and the persisted dock configurations removed.

      object allOf
      uid: deleteAllDocksMsg
      • #dock

      Examples

    • #68get_dock

      🧪 Get dock configuration.

      Returns the dock configuration, enriched with the current session information if a dock connection is established.

      object allOf
      uid: getDockMsg
      • #dock

      Examples

    • #69update_dock

      🧪 Change dock configuration like auto-connect or access token.

      Update one or more dock fields.

      • If the dock is in an active connection state, then the name, token and wifi values are persisted in the dock if provided in the request. The request fails with 503 service unavailable if the configuration can't be set in the docking station.
      • An empty custom_ws_url value will remove the custom URL.
      • If the dock is not active, the values are only stored in the remote. A changed token will be used for the next connection attempt.
      object allOf
      uid: updateDockMsg
      • #dock

      Examples

    • #70dock_connection_command

      🧪 Start or stop a dock connection.

      Establish or stop a session to a specific or all active docks.

      object allOf
      uid: dockConnectionCommandMsg
      • #dock

      Examples

    • #71delete_dock

      🧪 Delete dock configuration.

      ⚠️ The dock configuration will be irrevocably deleted!

      An active dock session will be disconnected and the persisted dock configuration removed.

      object allOf
      uid: deleteDockMsg
      • #dock

      Examples

    • #72dock_command

      🧪 Send a dock command.

      The following command values are defined:

      • SET_LED_BRIGHTNESS: set the maximum brightness of the front indicator LED. Set the 0..100 percentage as string parameter in the value field.
      • SET_VOLUME: 3️⃣ set the speaker volume. Set the 0..100 percentage as string parameter in the value field.
      • IDENTIFY: identify the dock with blinking the indicator LED.
      • REMOTE_LOW_BATTERY: trigger the low battery status indicator on the dock.
      • REMOTE_CHARGED: trigger the remote charged indicator on the dock.
      • REMOTE_NORMAL: trigger the normal remote operation mode on the dock.
      • REBOOT: reboot the dock.
      • RESET: ⚠️ factory reset the dock. Requires administrator privileges.
        The dock configuration will be deleted from the remote.
      object allOf
      uid: dockCommandMsg
      • #dock

      Examples

    • #73get_dock_discovery_status

      🧪 Get docking station discovery status.

      Returns the current discovery status and any discovered docks.

      object allOf
      uid: getDockDiscoveryStatusMsg
      • #dock

      Examples

    • #74start_dock_discovery

      🧪 Start discovery of new docking stations.

      Start device discovery over Bluetooth and mDNS. Bluetooth or network discovery can be disabled with a query parameter. By default the discovery automatically stops after 30 seconds. Use the get_dock_discovery_status status request to check on discovered devices or stop_dock_discovery to stop discovery.

      By default only new network devices are returned. If a dock is already configured it will be omitted from the results, unless the query parameter new=false is set. Docks with Bluetooth enabled are always returned, since this usually means that the dock needs to be re-configured.

      • If BT is disabled in the remote, the bt parameter is ignored.
      • Emits the WebSocket event dock_discovery with event_type: START when discovery starts.
      • For each discovered device the WebSocket event dock_discovery with event_type: DISCOVER is emitted.
      • This operation clears any old discovered devices and won't be accessible anymore with the GET operation.
      object allOf
      uid: startDockDiscoveryMsg
      • #dock

      Examples

    • #75stop_dock_discovery

      🧪 Stop discovery of new docking stations.

      Stops the device discovery. The current discovery status is returned in the response. Already discovered devices won't be returned and can still be retrieved with the get_dock_discovery_status operation.

      Emits the WebSocket event dock_discovery with event_type: STOP.

      object allOf
      uid: stopDockDiscoveryMsg
      • #dock

      Examples

    • #76get_dock_discovery_device

      🧪 Get docking station discovery device status.

      Returns the discovered docking station device.

      object allOf
      uid: getDockDiscoveryDeviceMsg
      • #dock

      Examples

    • #77exec_cmd_on_discovered_dock

      🧪 Execute command on a discovered docking station.

      Perform a WebSocket connection test with a discovered docking station. If the dock requires an API token, it must be specified in the request body.
      The IDENTIFY command also blinks the status LED on the dock.

      Response status codes:

      • 200: successful operation: the connection test was successful and docking station metadata could be retrieved.
      • 404: discovered dock with dock_id not found. Check if the discovery result is still available and has not been deleted. This can happen after a timeout since the discovery, or if the discovery result has been cleared with DELETE /docks/discover.
      • 503: docking station connection could not be established.
      object allOf
      uid: execCmdOnDiscoveredDockMsg
      • #dock

      Examples

    • #78get_dock_setup_processes

      🧪 Get current dock setup processes.

      Return a list of all active setup process identifiers.

      object allOf
      uid: getDockSetupProcessesMsg
      • #dock

      Examples

    • #79create_dock_setup

      🧪 Start setting up a new docking station.

      Create a new setup process from a discovered dock or from a manually provided dock address.

      • If there's already a setup process running for the given dock id, status code 409 is returned.
      • Emits the WebSocket event dock_setup_change with event_type: START when this operation returns 201.

      Start setup from dock discovery:

      • The required request data can be obtained from the /api/docks/discover endpoints when searching for docking stations over Bluetooth or Ethernet. Simply provide the returned DockDiscovery data object (which is a super set of the required data to start a setup process).
      • The returned id in the DockSetupInfo response will be the identifier for the next PUT /docks/setup/:id call to provide additional data.

      Manual setup:

      • A dock identifier will automatically be created and returned in DockSetupInfo.
      • The dock must be reachable on the network with the provided custom_ws_url and optional token. Otherwise, status code 503 is returned.
      • The setup process is automatically started after a successful POST request, no call to PUT /docks/setup/:id is required.

      Response status codes:

      • 201: setup process successfully started. Use GET /docks/setup/:id to poll for status updates, or listen to WebSocket dock_setup_change event messages.
      • 400: invalid data in request body.
      • 409: a setup process is already running. Either wait until finished, or abort it.
      • 503: service not available to setup docking station.
        E.g. Bluetooth is disabled and therefore the docking station cannot be setup over Bluetooth. Either enable Bluetooth or setup the dock over Ethernet.
      object allOf
      uid: createDockSetupMsg
      • #dock

      Examples

    • #80stop_all_dock_setups

      🧪 Abort and remove all setup processes.

      Stop all setup processes at the next possible operation and remove all setup process information.

      object allOf
      uid: stopAllDockSetupsMsg
      • #dock

      Examples

    • #81get_dock_setup_status

      🧪 Get docking station setup status.

      Poll operation to retrieve the current docking station setup state. See the state and error fields in the response message. There are also WebSocket dock_setup_change event messages for state changes to avoid polling.

      Defined setup states:

      • NEW: setup has not yet been started. Use the PUT operation to provide the required data and to start setting up the dock.
      • CONFIGURING: setup data is currently being transferred to the dock.
      • RESTARTING: dock has been configured and is restarting to integrate into the network.
      • OK: setup process has been completed successfully, the dock can now be used.
      • ERROR: the setup process failed. Check the error field for more information.
      object allOf
      uid: getDockSetupStatusMsg
      • #dock

      Examples

    • #82start_dock_setup

      🧪 Setup docking station.

      Set required data to start the setup process and configure the docking station. When using Bluetooth the WiFi network name and credentials must be provided to connect the dock to the WiFi network.

      The state field in the response message indicate the current state of the setup process. Use the GET operation to poll for state updates or listen to the corresponding WebSocket dock_setup_change event messages with event_type: SETUP.

      object allOf
      uid: startDockSetupMsg
      • #dock

      Examples

    • #83stop_dock_setup

      🧪 Abort the dock setup process.

      Stop the setup process at the next possible operation and remove the setup process information.
      To start a new setup process, use the POST /docks/setup operation again.

      Emits the WebSocket event dock_setup_change with event_type: STOP.

      object allOf
      uid: stopDockSetupMsg
      • #dock

      Examples

    • #84get_wifi_status

      🧪 Get WiFi status.

      object allOf
      uid: wifiGetStatusMsg
      • #wifi

      Examples

    • #85wifi_command

      🧪 WiFi connection handling.

      Perform one of the following commands on the WLAN interface:

      • DISCONNECT: Disconnect and wait for REASSOCIATE or RECONNECT command before connecting again.
      • RECONNECT: Connect if disconnected (i.e. like REASSOCIATE, but only connect if in disconnected state).
      • REASSOCIATE: Force reassociation.
      • ENABLE_ALL_NETWORKS: Enable all network connections and start connecting to a network if in disconnected state.
      • DISABLE_ALL_NETWORKS: Disable all network connections and disconnect if in connected state.

      ⚠️Attention: ENABLE_ALL_NETWORKS and DISABLE_ALL_NETWORKS will persist the state! I.e. if all networks are disabled and the device is restarted afterwards, no WiFi connection will be established.

      object allOf
      uid: wifiCommandMsg
      • #wifi

      Examples

    • #86wifi_scan_start

      🧪 Start discovery of WiFi access points.

      Request a new BSS scan. A scan usually takes a few seconds and the current state is returned with the get_wifi_scan_status operation, together with the already found access points.

      object allOf
      uid: wifiScanStartMsg
      • #wifi

      Examples

    • #87wifi_scan_stop

      🧪 Stop discovery of WiFi access points.

      Stops the access point discovery. The current discovery status is returned in the response.

      object allOf
      uid: wifiScanStopMsg
      • #wifi

      Examples

    • #88get_wifi_scan_status

      🧪 Get discovered WiFi access points.

      Returns the current discovery status and any discovered access points.

      object allOf
      uid: wifiGetScanStatusMsg
      • #wifi

      Examples

    • #89get_all_wifi_networks

      🧪 Get configured WiFi networks.

      object allOf
      uid: wifiGetAllNetworksMsg
      • #wifi

      Examples

    • #90add_wifi_network

      🧪 Create a new WiFi network configuration.

      Add a new network configuration for the given SSID.
      For an open network without password the password field must be omitted (do not send an empty password value).

      ⚠️ Only WPA-PSK (pre shared keys) and open networks are supported!

      object allOf
      uid: wifiAddNetworkMsg
      • #wifi

      Examples

    • #91del_all_wifi_networks

      🧪 Delete all configured WiFi networks.

      Disconnects the WiFi network and removes all network configurations.

      ⚠️ Attention: the network configuration is automatically persisted and the network configuration cannot be retrieved anymore!

      object allOf
      uid: wifiDelAllNetworksMsg
      • #wifi

      Examples

    • #92get_wifi_network

      🧪 Get WiFi network configuration.

      object allOf
      uid: wifiGetNetworkMsg
      • #wifi

      Examples

    • #93update_wifi_network

      🧪 Change WiFi network configuration.

      Set a new WiFi network password.

      object allOf
      uid: wifiUpdateNetworkMsg
      • #wifi

      Examples

    • #94wifi_network_command

      🧪WiFi network connection handling.

      Perform one of the following commands on a network configuration:

      • ENABLE: Enable a network. If no network is connected, it will be tried to connect to this network.
      • DISABLE: Disable a network. If the network is currently connected it will be disconnected.
      • SELECT: Select the given network and disable all others.

      ⚠️ Attention: all network changes (enabled or disabled) are persisted!

      object allOf
      uid: wifiNetworkCommandMsg
      • #wifi

      Examples

    • #95del_wifi_network

      🧪 Delete a configured WiFi network.

      The given network is removed from the configuration and disconnected if currently connected.

      ⚠️ Attention: the network configuration is automatically persisted and the removed network configuration cannot be retrieved anymore!

      object allOf
      uid: wifiDelNetworkMsg
      • #wifi

      Examples

    • #96bt_pairing_response

      🔍 Action to bt_pairing_auth_request event.

      This request needs to be sent for a bt_pairing_auth_request event:

      • Passkey request: either provide the passkey entered by the user, or decline it with confirm: false.
      • NumericComparison request: confirm or decline with confirm: true | false.
      object allOf
      uid: btPairingResponseMsg
      • #event

      Examples

  • SUB /ws

    Core-API for clients to receive messages from the remote.

    Operation IDsubRemoteMessage
    • #core

    Accepts one of the following messages:

    • #0auth_required

      🧪 Authentication request event after connection is established.

      This event is only sent if the client didn't provide authentication during connection setup.
      The client must then authenticate with the auth request message.

      object allOf
      uid: authRequiredEvent

      Examples

    • #1authentication

      🧪 Authentication response.

      The authentication result is provided in the code attribute:

      • 200: success, API can be used and message requests are accepted.
      • 401: authentication failed, the provided API-key is not valid. The server will close the connection.
      object allOf
      uid: authMsg

      Examples

    • #2pong

      🚀 Pong is a response to ping message

      Server pong response to a ping to determine whether connection is alive. This is an application level pong as opposed to default pong in websockets standard which is sent by client in response to a ping.

      object allOf
      uid: pong

      Examples

    • #3result

      🚀 Command result message

      object
      uid: commonResp

      Common response message properties.

      Examples

    • #4version_info

      🧪 Version information response.

      object allOf
      uid: versionInfoMsg

      Examples

    • #5system_info

      🧪 System information response.

      object allOf
      uid: systemInfoMsg

      Examples

    • #6factory_reset_token

      Factory reset token response.

      object allOf
      uid: factoryResetTokenMsg

      Examples

    • #7api_access

      API access status response.

      object allOf
      uid: apiAccessMsg

      Examples

    • #8system_update_info

      🧪 Available system update response.

      object allOf
      uid: systemUpdateInfoMsg

      Examples

    • #9power_mode

      🧪 Current power mode response.

      object allOf
      uid: powerModeMsg

      Examples

    • #10battery_charger

      🔍 Battery charger response.

      object allOf
      uid: batteryChargerMsg

      Examples

    • #11ambient_light

      🔍 Current ambient light response.

      object allOf
      uid: ambientLightMsg

      Examples

    • #12configuration

      🧪 All system settings response.

      object allOf
      uid: configurationMsg

      Examples

    • #13button_cfg

      🧪 Button settings response.

      Button backlight configuration.

      Device features:

      • BACKLIGHT: buttons have backlight (UCR2, UCR3).
      • RGB_COLOR: RGB color backlight support (UCR3).
      • ZONES: backlight can be controlled with individual zones (UCR3).

      ⚠️ Individual color per zone is not yet supported.

      object allOf
      uid: buttonCfgMsg

      Examples

    • #14device_cfg

      🧪 Remote device settings response.

      object allOf
      uid: deviceCfgMsg

      Examples

    • #15display_cfg

      🧪 Display settings response.

      object allOf
      uid: displayCfgMsg

      Examples

    • #16haptic_cfg

      🧪 Haptic settings response.

      object allOf
      uid: hapticCfgMsg

      Examples

    • #17localization_cfg

      🧪 Localization settings response.

      object allOf
      uid: localizationCfgMsg

      Examples

    • #18timezone_names

      🧪 Available time zone names response.

      object allOf
      uid: timezoneNamesMsg

      Examples

    • #19localization_countries

      🧪 Available localization countries response.

      object allOf
      uid: localizationCountriesMsg

      Examples

    • #20get_localization_languages

      🧪 Get stored translations or request available translations from the UI.

      The available translations are provided from the UI application.
      Future UI versions might provide new or updated translations.

      If this request is sent to the UI application, the response is stored in the remote-core until new information is available from the UI.

      If this request is received, the stored configuration from the UI application is returned. E.g. the web-configurator requires the available translations.

      object allOf
      uid: getLocalizationLanguagesMsg

      Examples

    • #21localization_languages

      🧪 Available translations response.

      object allOf
      uid: localizationLanguagesMsg

      Examples

    • #22network_cfg

      🔍 Network settings response.

      object allOf
      uid: networkCfgMsg

      Examples

    • #23software_update_cfg

      🧪 Software update settings response.

      object allOf
      uid: softwareUpdateCfgMsg

      Examples

    • #24power_saving_cfg

      🧪 Power saving settings response.

      object allOf
      uid: powerSavingCfgMsg

      Examples

    • #25profile_cfg

      🧪 Profile settings response.

      object allOf
      uid: profileCfgMsg

      Examples

    • #26sound_cfg

      🧪 Sound settings response.

      object allOf
      uid: soundCfgMsg

      Examples

    • #27voice_control_cfg

      🔍 Voice control settings response.

      object allOf
      uid: voiceControlCfgMsg

      Examples

    • #28voice_assistants

      🔍 Voice assistants response.

      object allOf
      uid: voiceAssistantsMsg

      Examples

    • #29entity_types

      🧪 List of supported entity types response.

      object allOf
      uid: entityTypesMsg
      • #entity

      Examples

    • #30entities

      🧪 List of configured entities response.

      object allOf
      uid: entitiesMsg
      • #entity

      Examples

    • #31available_entities

      🧪 List of available entities response.

      object allOf
      uid: availableEntitiesMsg
      • #entity

      Examples

    • #32entity_commands

      🧪 Available commands of an entity response.

      object allOf
      uid: entityCommandsMsg
      • #entity

      Examples

    • #33entity

      🧪 Entity information response.

      object allOf
      uid: entityMsg
      • #entity

      Examples

    • #34dock_count

      🧪 Total number of configured docks response.

      object allOf
      uid: dockCountMsg
      • #dock

      Examples

    • #35docks

      🧪 Configured docks and their connection state response.

      object allOf
      uid: docksMsg
      • #dock

      Examples

    • #36dock

      🧪 Configured dock response.

      object allOf
      uid: dockMsg
      • #dock

      Examples

    • #37dock_discovery_status

      🧪 Docking station discovery status response.

      object allOf
      uid: dockDiscoveryStatusMsg
      • #dock

      Examples

    • #38dock_discovery_device

      🧪 Docking station discovery device status response.

      object allOf
      uid: dockDiscoveryDeviceMsg
      • #dock

      Examples

    • #39dock_system_info

      🧪 Dock system information response.

      object allOf
      uid: dockSystemInfoMsg
      • #dock

      Examples

    • #40dock_setup_processes

      🧪 Current dock setup processes response.

      object allOf
      uid: dockSetupProcessesMsg
      • #dock

      Examples

    • #41dock_setup_status

      🧪 Dock setup information response.

      object allOf
      uid: dockSetupStatusMsg
      • #dock

      Examples

    • #42wifi_status

      🧪 WiFi status.

      object allOf
      uid: wifiStatusMsg
      • #wifi

      Examples

    • #43wifi_scan_status

      🧪 Discovered WiFi access points.

      object allOf
      uid: wifiScanStatusMsg
      • #wifi

      Examples

    • #44wifi_networks

      🧪 Configured WiFi networks.

      object allOf
      uid: wifiNetworksMsg
      • #wifi

      Examples

    • #45wifi_network

      🧪 WiFi network configuration.

      object allOf
      uid: wifiNetworkMsg
      • #wifi

      Examples

    • #46bt_pairing_started

      🔍 Inform user that pairing has started.

      Emitted if a central started pairing with the Remote.

      object allOf
      uid: btPairingStartedEventMsg
      • #event

      Examples

    • #47bt_pairing_auth_request

      🔍 Request pairing authorization from the user.

      Depending on authentication requirements, IO capabilities, etc. a different type of authentication is requested. The client must respond with the bt_pairing_response event.

      object allOf
      uid: btPairingAuthRequestEventMsg
      • #event

      Examples

    • #48bt_pairing_complete

      🔍 Bonding process has finished.

      This event is emitted after the bonding process, either with a success state or an error code if bonding failed.

      object allOf
      uid: btPairingCompleteEventMsg
      • #event

      Examples

  • PUB /intg

    Integration driver and instance management.

    ⚠️ Attention: this is NOT a different WebSocket endpoint! It is purely used for logical grouping of all integration driver and instance related messages in the documentation! These messages are all available in the core /ws endpoint.

    Operation IDpubIntegrationMessage
    • #integrations

    Accepts one of the following messages:

    • #0get_integration_status

      🧪 Retrieve an overview of the integration instances and their current connection state.

      object allOf
      uid: getIntegrationStatusMsg
      • #integration

      Examples

    • #1integration_cmd

      🧪 Execute an integration command.

      Connect or disconnect integration instances.

      If integration_id is specified, then the command only applies to the given integration, otherwise to all integration instances.

      object allOf
      uid: integrationCmdMsg
      • #integration

      Examples

    • #2integration_driver_cmd

      🧪 Execute an integration driver command.

      Start or stop integration drivers.

      If driver_id is specified, then the command only applies to the given driver, otherwise to all integration drivers.

      object allOf
      uid: integrationDriverCmdMsg
      • #integration

      Examples

    • #3get_integration_driver_count

      🧪 Get total number of registered integration drivers.

      object allOf
      uid: getIntegrationDriverCountMsg
      • #integration

      Examples

    • #4get_integration_drivers

      🧪 Retrieve all registered integration drivers.

      object allOf
      uid: getIntegrationDriversMsg
      • #integration

      Examples

    • #5register_integration_driver

      🧪 Register a new integration driver.

      object allOf
      uid: registerIntegrationDriverMsg
      • #integration

      Examples

    • #6get_integration_driver

      🧪 Retrieve detail information of an integration driver.

      object allOf
      uid: getIntegrationDriverMsg
      • #integration

      Examples

    • #7update_integration_driver

      🧪 Modify a configured integration driver.

      object allOf
      uid: updateIntegrationDriverMsg
      • #integration

      Examples

    • #8delete_integration_driver

      🧪 Remove an integration driver.

      Unloads and deletes an integration driver with all instances and provided entities.

      Attention: all references to the integration driver will be removed! This includes all driver instances, provided entities and their references in profile pages and groups.

      object allOf
      uid: deleteIntegrationDriverMsg
      • #integration

      Examples

    • #9get_integration_count

      🧪 Get total number of integration instances.

      object allOf
      uid: getIntegrationCountMsg
      • #integration

      Examples

    • #10get_integrations

      🧪 Retrieve all loaded integrations.

      Returns all integration instances, optionally filtered by type or enabled state.

      object allOf
      uid: getIntegrationsMsg
      • #integration

      Examples

    • #11create_integration

      🧪 Create a new integration instance from driver.

      Create an integration driver instance and associate it with the driver. For simple integration drivers there's a 1:1 relationship only between an instance and driver. For multi-device drivers, each device corresponds to an integration instance.

      • the integration_id is automatically created by the system to make it unique over all integrations.
      • for multi-device drivers the device_id must be specified and may not already exist in another instance of the same driver.
      • the driver's name is used by default if name isn't specified.
      • the instance is active by default if enabled isn't specified.
      object allOf
      uid: createIntegrationMsg
      • #integration

      Examples

    • #12get_integration

      🧪 Get an integration instance.

      object allOf
      uid: getIntegrationMsg
      • #integration

      Examples

    • #13update_integration

      🧪 Modify a configured integration instance.

      Modify one or several properties of an integration instance.
      See update model description on how to update or delete an existing property.

      The integration driver of an instance cannot be changed and will be ignored if provided in the request.

      object allOf
      uid: updateIntegrationMsg
      • #integration

      Examples

    • #14delete_integration

      🧪 Remove an integration instance.

      Unloads and deletes an integration instance.

      Attention: all references to the integration instance will be removed! This includes configured entities and their references in profile pages and groups.

      object allOf
      uid: deleteIntegrationMsg
      • #integration

      Examples

    • #15configure_entity_from_integration

      🧪 Configure an available entity.

      Configure a new UC Remote entity from an available integration entity. Once configured, the entity will no longer show up as available entity (unless the all filter is set).

      The entity name, icon and description fields may be changed. If not specified in the request the values from the available entity are used.

      In case of an error the default result message is returned with an error code.

      object allOf
      uid: configureEntityFromIntegrationMsg
      • #integration

      Examples

    • #16configure_entities_from_integration

      🧪 Configure multiple available entities.

      Configure multiple new UC Remote entities from available integration entities. Once configured, the entities will no longer show up as an available entity (unless the filter=ALL query parameter is set).

      If entity_ids is not provided or is empty, all entities from the integration are configured.

      Use message configure_entity_from_integration to configure a single entity and optionally rename it or change its icon.

      This is a best effort operation:

      • if an entity is already configured, it is ignored and not returned in the response.
      • unknown entity identifiers are ignored, no error is returned.

      Every newly configured entity will trigger an entity_change event.

      object allOf
      uid: configureEntitiesFromIntegrationMsg
      • #integration

      Examples

    • #17get_integration_discovery_status

      🧪 Get external integration driver discovery status.

      Returns the current discovery status and the discovered integration drivers.

      Use start_integration_discovery to clear old results and start a new discovery.

      object allOf
      uid: getIntegrationDiscoveryStatusMsg
      • #integration

      Examples

    • #18start_integration_discovery

      🧪 Start discovery of external integration drivers.

      Start integration driver discovery on the network with mDNS. By default the discovery automatically stops after 30 seconds. Use the get_integration_discovery_status request to check on discovered devices or stop_integration_discovery to stop discovery.

      By default only new integration drivers are returned. If a driver is already configured it will be omitted from the results, unless the query parameter new=false is set.

      • Previously discovered integrations are removed, only newly discovered integrations will be returned.
      • Emits the WebSocket event integration_discovery with event_type: START when discovery starts.
      • For each discovered driver the WebSocket event integration_discovery with event_type: DISCOVER is emitted.
      object allOf
      uid: startIntegrationDiscoveryMsg
      • #integration

      Examples

    • #19stop_integration_discovery

      🧪 Stop discovery of external integration drivers.

      Stops the driver discovery and returns the current discovery status in the response.

      Emits the WebSocket event integration_discovery with event_type: STOP.

      object allOf
      uid: stopIntegrationDiscoveryMsg
      • #integration

      Examples

    • #20get_discovered_integration_driver

      🧪 Get integration driver discovery information.

      Returns the discovered integration driver.

      object allOf
      uid: getDiscoveredIntegrationDriverMsg
      • #integration

      Examples

    • #21get_discovered_intg_driver_metadata

      👷 Execute connection test and fetch metadata from discovered integration driver.

      Perform a driver connection test with a discovered driver. If the driver requires a token, it must be specified in the request data.

      Response status codes:

      • 200: successful operation: the connection test was successful and driver metadata could be retrieved.
      • 404: discovered driver with driver_id not found. Check if the discovery result is still available and has not been deleted. This can happen after a timeout since the discovery, or if the discovery result has been cleared with starting a new discovery.
      • 503: integration driver connection could not be established.
      object allOf
      uid: getDiscoveredIntgDriverMetadataMsg
      • #integration

      Examples

    • #22configure_discovered_integration_driver

      🧪 Register a discovered integration driver.

      Register a discovered integration driver:

      • establish communication with the driver.
        • if the driver requires a password, it must be provided in the request.
        • the discovered driver name and url can be overridden.
      • fetch metadata from the driver.
      • check compatability.
      • register the driver and connection parameters in the remote.

      After a successful registration the setup process of the driver can be started to configure the integration. The required setup data is described in the returned setup_data_schema and the provided values by the user must be passed to the setup_integration request.

      Response status codes:

      • 400: invalid data in request body.
      • 404: no discovered driver found for given driver_id.
      • 409: integration driver is already registered.
      • 503: integration driver communication error. Either driver is not reachable or communication failed.
      object allOf
      uid: configureDiscoveredIntegrationDriverMsg
      • #integration

      Examples

    • #23get_integration_setup_processes

      🧪 Get current integration setup processes.

      Return a list of all active setup process identifiers. The returned ids can be used with the set_integration_user_data and stop_integration_setup messages to continue or abort a setup process.

      object allOf
      uid: getIntegrationSetupProcessesMsg
      • #integration

      Examples

    • #24setup_integration

      🧪 Start setting up a new integration driver.

      Start a new setup process for the given integration driver and provided setup data, or reconfigure an existing driver.

      • This operation immediately starts the driver communication and setup process.
      • There may only be one active setup process per driver, otherwise status code 409 is returned.

      The returned id in the IntegrationSetupInfo response will be the identifier for the further setup operations with the set_integration_user_data and stop_integration_setup requests. Once the setup process is successfully finished, an integration instance is created. A setup process can be simple and fully automatic, but may also require user interaction and further communication with the set_integration_user_data message.

      Emits the WebSocket event integration_setup_change with event_type: START.

      Request body:

      • name: optional integration name. If not specified the name of the integration driver is used.
      • setup_data: optional driver setting values corresponding to the driver's setup_data_schema object.
      • reconfigure: set to true to reconfigure an already configured driver. The configuration options and behaviour is driver dependent.

      Response status codes:

      • 400: invalid data in request body. E.g. setting the reconfigure flag for a new driver which is not yet configured.
      • 404: specified driver_id in request body does not exist.
      • 409: a setup process for the given driver_id already exists. Either continue or abort existing process.
      • 422: the setup process cannot be used: either the integration is already configured or doesn't allow to be set up again.
      • 503: integration driver communication error. Either driver is not reachable or communication failed.
      object allOf
      uid: setupIntegrationMsg
      • #integration

      Examples

    • #25stop_all_integration_setups

      🧪 Abort and remove all setup processes.

      Stop all setup processes at the next possible operation and remove all setup process information.
      Depending on the integration driver, a started setup process cannot be aborted.

      ⚠️ This stops all setup processes, not just for the current session!

      object allOf
      uid: stopAllIntegrationSetupsMsg
      • #integration

      Examples

    • #26get_integration_setup_status

      🧪 Get integration driver setup status.

      Poll operation to retrieve the current integration driver setup state. See the state and error fields in the response message. There are also WebSocket integration_setup_change event messages for state changes to avoid polling.

      Defined setup states:

      • SETUP: setup is running and configuring the integration.
      • WAIT_USER_ACTION: user input is required to continue the setup process. See require_user_action in response for the required user input. Provide the requested data with the PUT operation.
      • OK: setup process has been completed successfully, the integration driver can now be used.
      • ERROR: the setup process failed. Check the error field for more information.
      object allOf
      uid: getIntegrationSetupStatusMsg
      • #integration

      Examples

    • #27set_integration_user_data

      🧪 Provide requested integration setup data.

      Set required data to configure the integration driver or continue the setup process.

      Defined user actions to set in the request body action field:

      • input_values: if the user was requested to enter settings, e.g. connection or credential parameters to a device or service.
      • confirm: response to the user action confirmation. Set to true if the user had to perform an action like pressing a button on a device and then confirms the action with continuing the setup process.
        The false value is prepared for yes / no choices.

      The state field in the response message indicate the current state of the setup process. Use the get_integration_setup_status message to poll for state updates or listen to the corresponding WebSocket integration_setup_change event messages with event_type: SETUP.

      object allOf
      uid: setIntegrationUserDataMsg
      • #integration

      Examples

    • #28stop_integration_setup

      🧪 Abort the integration driver setup process.

      Stop the setup process at the next possible operation and remove the setup process information.
      To start a new setup process, use the setup_integration request again.

      Depending on the integration driver, a started setup process cannot be aborted.

      Emits the WebSocket event integration_setup_change with event_type: STOP.

      object allOf
      uid: stopIntegrationSetupMsg
      • #integration

      Examples

  • SUB /intg

    ⚠️ Attention: this is NOT a different WebSocket endpoint! It is purely used for logical grouping of all integration driver and instance related messages in the documentation! These messages are all available in the core /ws endpoint.

    Operation IDsubIntegrationMessage
    • #integrations

    Accepts one of the following messages:

    • #0integration_status

      🧪 Summary information of the integration instances.

      object allOf
      uid: integrationStatusMsg
      • #integration

      Examples

    • #1integration_driver_count

      🧪 Total number of registered integration drivers response.

      object allOf
      uid: integrationDriverCountMsg
      • #integration

      Examples

    • #2integration_drivers

      🧪 List of registered integration drivers response.

      object allOf
      uid: integrationDriversMsg
      • #integration

      Examples

    • #3integration_driver

      🧪 Detail information of an integration driver response.

      object allOf
      uid: integrationDriverMsg
      • #integration

      Examples

    • #4integration_count

      🧪 Total number of integration instances response.

      object allOf
      uid: integrationCountMsg
      • #integration

      Examples

    • #5integrations

      🧪 List of loaded integrations response.

      object allOf
      uid: integrationsMsg
      • #integration

      Examples

    • #6integration

      🧪 Integration instance information response.

      object allOf
      uid: integrationMsg
      • #integration

      Examples

    • #7integration_discovery_status

      🧪 External integration driver discovery status response.

      object allOf
      uid: integrationDiscoveryStatusMsg
      • #integration

      Examples

    • #8discovered_integration_driver

      🧪 Integration driver discovery information.

      object allOf
      uid: discoveredIntegrationDriverMsg
      • #integration

      Examples

    • #9integration_setup_processes

      🧪 Current integration setup processes response.

      Return a list of all active setup process identifiers.

      object allOf
      uid: integrationSetupProcessesMsg
      • #integration

      Examples

    • #10integration_setup_info

      🧪 Integration setup information response.

      object allOf
      uid: integrationSetupInfoMsg
      • #integration

      Examples

  • PUB /profiles

    Profile management.

    ⚠️ Attention: this is NOT a different WebSocket endpoint! It is purely used for logical grouping of all profile related messages in the documentation! These messages are all available in the core /ws endpoint.

    Operation IDpubProfileMessage
    • #profiles

    Accepts one of the following messages:

    • #0get_profiles

      🧪 Retrieve all profiles.

      object allOf
      uid: getProfilesMsg
      • #profile

      Examples

    • #1get_profile

      🧪 Retrieve the specified profile.

      object allOf
      uid: getProfileMsg
      • #profile

      Examples

    • #2get_active_profile

      🧪 Retrieve the active profile.

      If no profile exists, or no profile is set active, 404 is returned.

      object allOf
      uid: getActiveProfileMsg
      • #profile

      Examples

    • #3switch_profile

      🧪 Switch active profile.

      The administrator PIN in admin_pin is required to switch from a restricted to a normal profile. If the current profile is a restricted profile and the pin is missing, error 401 is returned.

      object allOf
      uid: switchProfileMsg
      • #profile

      Examples

    • #4add_profile

      🧪 Add a new profile.

      There are two different types of profiles:

      • Normal profile (default): can do anything, change settings, add pages, entities, integrations, etc.
      • Restricted profile: intended for guests or children, who can only use the remote, but cannot change settings.

      The admin PIN is required to switch from a restricted to a normal profile. It can be defined in settings.

      • Switching away from a restricted profile will prompt the user to enter the admin PIN.
      • Switching to a restricted profile can be done without entering the admin PIN.

      Profile request object:

      • profile_id is optional and auto-generated if not specified. Otherwise it needs to be a unique profile identifier.
      • name is mandatory and must be unique.
      • if the first profile is added, it is automatically set as the active profile.
      object allOf
      uid: addProfileMsg
      • #profile

      Examples

    • #5update_profile

      🧪 Update a profile.

      Update one or multiple properties of a profile. A missing property will not update its current value.

      • profile_id is mandatory and can't be changed.
      • an empty icon value removes an existing icon identifier.
      • a missing pages property will not change the page order.
      • ⚠️ an empty pages array removes all pages and groups in the profile!
      • ⚠️ missing page identifiers in the pages array will remove the page configuration!
      object allOf
      uid: updateProfileMsg
      • #profile

      Examples

    • #6delete_profile

      🧪 Delete the specified profile.

      All profile related pages and groups are also deleted.

      object allOf
      uid: deleteProfileMsg
      • #profile

      Examples

    • #7delete_all_profiles

      🧪 Delete all profiles.

      This also deletes all pages and groups.

      object allOf
      uid: deleteAllProfilesMsg
      • #profile

      Examples

    • #8get_pages

      🧪 Retrieve all UI pages of a profile.

      object allOf
      uid: getPagesMsg
      • #profile

      Examples

    • #9get_page

      🧪 Retrieve the specified UI page.

      object allOf
      uid: getPageMsg
      • #profile

      Examples

    • #10add_page

      🧪 Create a new UI page and add to profile.

      • profile_id is mandatory.
      • page_id is not required and is created automatically.
      • name is mandatory and must be unique within the profile.
      object allOf
      uid: addPageMsg
      • #profile

      Examples

    • #11update_page

      🧪 Update a UI page.

      • profile_id and page_id are mandatory.
      object allOf
      uid: updatePageMsg
      • #profile

      Examples

    • #12delete_page

      🧪 Delete a UI page.

      object allOf
      uid: deletePageMsg
      • #profile

      Examples

    • #13delete_pages_in_profile

      🧪 Delete all pages of a profile

      object allOf
      uid: deletePagesInProfileMsg
      • #profile

      Examples

    • #14get_groups

      🧪 Retrieve all UI groups of a profile.

      object allOf
      uid: getGroupsMsg
      • #profile

      Examples

    • #15get_group

      🧪 Retrieve the specified UI group.

      object allOf
      uid: getGroupMsg
      • #profile

      Examples

    • #16add_group

      🧪 Create a new UI group and add to profile.

      • profile_id is mandatory.
      • group_id is not required and is created automatically.
      • name is mandatory and must be unique within the profile.
      object allOf
      uid: addGroupMsg
      • #profile

      Examples

    • #17update_group

      🧪 Update a UI group.

      • profile_id and group_id are mandatory.
      object allOf
      uid: updateGroupMsg
      • #profile

      Examples

    • #18delete_group

      🧪 Delete a UI group.

      object allOf
      uid: deleteGroupMsg
      • #profile

      Examples

    • #19delete_groups_in_profile

      🧪 Delete all groups in a profile.

      object allOf
      uid: deleteGroupsInProfileMsg
      • #profile

      Examples

  • SUB /profiles

    ⚠️ Attention: this is NOT a different WebSocket endpoint! It is purely used for logical grouping of all profile related messages in the documentation! These messages are all available in the core /ws endpoint.

    Operation IDsubProfileMessage
    • #profiles

    Accepts one of the following messages:

    • #0profile

      🧪 Profile data response.

      object allOf
      uid: profileMsg
      • #profile

      Examples

    • #1profiles

      🧪 List of available profiles response.

      object allOf
      uid: profilesMsg
      • #profile

      Examples

    • #2page

      🧪 UI page data response.

      object allOf
      uid: pageMsg
      • #profile

      Examples

    • #3pages

      🧪 List of defined UI pages response.

      object allOf
      uid: pagesMsg
      • #profile

      Examples

    • #4group

      🧪 UI group data response.

      object allOf
      uid: groupMsg
      • #profile

      Examples

    • #5groups

      🧪 List of defined UI groups response.

      object allOf
      uid: groupsMsg
      • #profile

      Examples

  • PUB /events

    Notification signup for the client to receive event messages.

    ⚠️ Attention: this is NOT a different WebSocket endpoint! It is purely used for logical grouping of event messages in the documentation! These messages are all available in the core /ws endpoint.

    Operation IDpubEventMessage
    • #events

    Accepts one of the following messages:

    • #0get_event_channels

      🧪 Retrieve available event channels for the current session.

      Depending on the security role not all event subscriptions may be available.

      object allOf
      uid: getEventChannelsMsg
      • #event

      Examples

    • #1subscribe_events

      🧪 Subscribe to event channels.

      Subscribe to one or multiple event channels.

      • The special all channel will deliver all available events and clear all other subscriptions for the session.
      • If the session is already subscribed to the all channel, any other channels are ignored.
      • The special entities channel will deliver all entity and activity-group related events. This includes all entity-type channels (entity_###) and the activity_group channel.
      • Depending on the security role not all event subscriptions may be available.
      object allOf
      uid: subscribeEventsMsg
      • #event

      Examples

    • #2get_event_subscriptions

      🧪 Retrieve the active event channel subscriptions.

      object allOf
      uid: getEventSubscriptionsMsg
      • #event

      Examples

    • #3unsubscribe_events

      🧪 Unsubscribe from event channels.

      object allOf
      uid: unsubscribeEventsMsg
      • #event

      Examples

  • SUB /events

    Event messages for signed up channels.

    ⚠️ Attention: this is NOT a different WebSocket endpoint! It is purely used for logical grouping of event messages in the documentation! These messages are all available in the core /ws endpoint.

    Operation IDsubEventMessage
    • #events

    Accepts one of the following messages:

    • #0event_channels

      🧪 Available subscriptions for the current session.

      Returns all subscribed event channels.

      object allOf
      uid: eventChannelsMsg
      • #event

      Examples

    • #1event_subscriptions

      🧪 Event channel subscription status.

      Response to subscribe_events, unsubscribe_events and get_event_subscriptions.

      object allOf
      uid: eventSubscriptionsMsg
      • #event

      Examples

    • #2warning

      🔍 System warning event.

      Emitted for important system events like low battery or shutdown events.

      object allOf
      uid: warningEventMsg
      • #event

      Examples

    • #3entity_change

      🧪 Entity change event.

      Emitted if an entity has changed, a new entity has been added or a configured entity has been deleted.

      If an entity state or dynamic attribute has changed (through notification of an integration driver), then only the attributes object is included within new_state. This happens after an entity_command or if the entity is updated manually through a user or an external system, e.g. if it has been switched off.

      If the entity definition has changed, e.g. the name, description or icon has been modified with the web configurator, the full entity data is included within new_state.

      If a complete integration is removed then only an integration_change event is sent, i.e. there won't be individual entity_change events for every removed entity!

      ⚠️ This event is also used to indicate the client to reload all entities. This is the case if only event_type: change is set and the entity_id field is missing.

      object allOf
      uid: entityChangeEventMsg
      • #entity
      • #event

      Examples

    • #4activity_group_change

      🧪 Activity group change event.

      Emitted if an activity group has changed, a new group has been added or a group has been deleted.

      ⚠️ This event is also used to indicate the client to reload all activity groups. This is the case if only event_type: change is set and the group_id field is missing.

      object allOf
      uid: activityGroupChangeEventMsg
      • #entity
      • #event

      Examples

    • #5wifi_change

      🧪 WiFi change event.

      Emitted if the WiFi status changed, e.g. connected or disconnected to an access point, or if a WiFi network scan finished.

      object allOf
      uid: wifiChangeEventMsg
      • #event

      Examples

    • #6integration_driver_change

      🧪 Integration driver change event.

      Emitted if an integration driver has changed, a new driver has been added or a configured driver has been deleted.

      object allOf
      uid: integrationDriverChangeEventMsg
      • #integration
      • #event

      Examples

    • #7integration_change

      🧪 Integration change event.

      Emitted if an integration instance has changed, a new instance has been added or a configured instance has been deleted.

      object allOf
      uid: integrationChangeEventMsg
      • #integration
      • #event

      Examples

    • #8integration_state

      🧪 Integration state event.

      Emitted if the connection state of an integration driver or instance has changed.

      object allOf
      uid: integrationStateEventMsg
      • #integration
      • #event

      Examples

    • #9active_profile_change

      🧪 Active profile change event.

      Emitted if the active profile changed.

      object allOf
      uid: activeProfileChangeEventMsg
      • #profile
      • #event

      Examples

    • #10profile_change

      🧪 Profile change event.

      Emitted if a profile configuration, related profile page or group has been changed, added or deleted.

      object allOf
      uid: profileChangeEventMsg
      • #profile
      • #event

      Examples

    • #11configuration_change

      🧪 System configuration change event.

      Emitted if a system setting has changed.

      The msg_data.new_state object only contains the configuration object of the setting that has changed and not the full system configuration.

      object allOf
      uid: configurationChangeEventMsg
      • #event

      Examples

    • #12ir_learning

      🧪 IR code learn event.

      Emitted if learning mode is started, stopped or a new IR code was learned from an IR emitter device.

      object allOf
      uid: irLearningEventMsg
      • #event

      Examples

    • #13dock_change

      🧪 Dock change event.

      Emitted if a dock configuration has changed.

      object allOf
      uid: dockChangeEventMsg
      • #event

      Examples

    • #14dock_state

      🧪 Dock state event.

      Emitted if the connection state of a dock has changed.

      object allOf
      uid: dockStateEventMsg
      • #event

      Examples

    • #15dock_port_mode

      🧪 Dock port mode change event.

      Emitted if the external port mode of a dock has changed.

      object allOf
      uid: dockPortModeEventMsg
      • #event

      Examples

    • #16dock_discovery

      🧪 Docking station discovery event.

      Emitted if dock discovery is started, stopped or a new dock was discovered on the network or via Bluetooth.

      object allOf
      uid: dockDiscoveryEventMsg
      • #event

      Examples

    • #17dock_setup_change

      🧪 Docking station setup state change event.

      Emitted for all dock setup flow state changes.

      object allOf
      uid: dockSetupChangeEventMsg
      • #event

      Examples

    • #18dock_update_change

      🧪 Docking station firmware update change event.

      Emitted for firmware update and progress state changes.

      object allOf
      uid: dockUpdateChangeEventMsg
      • #event

      Examples

    • #19integration_discovery

      🧪 Integration discovery event.

      Emitted if integration discovery is started, stopped or a new integration was discovered on the network.

      object allOf
      uid: integrationDiscoveryEventMsg
      • #event

      Examples

    • #20integration_setup_change

      🧪 Integration setup state change event.

      Emitted for all integration setup flow state changes.

      object allOf
      uid: integrationSetupChangeEventMsg
      • #event

      Examples

    • #21software_update

      🧪 Software update event.

      Emitted during a system update to receive start, stop and progress events.

      object allOf
      uid: softwareUpdateEventMsg
      • #event

      Examples

    • #22power_mode_change

      🧪 Power mode change event.

      Emitted when the power saving mode changes.

      object allOf
      uid: powerModeChangeEventMsg
      • #event

      Examples

    • #23battery_status

      🧪 Battery status event.

      Emitted when the battery status changes.

      object allOf
      uid: batteryStatusEventMsg
      • #event

      Examples

    • #24ambient_light_change

      🔍 Ambient light change event.

      Emitted when the ambient light changes during normal power mode.

      object allOf
      uid: ambientLightChangeEventMsg
      • #event

      Examples

    • #25assistant_event

      🔍 Assistant event.

      The assistant_event message must be emitted by the integration driver to start the audio stream and for providing optional feedback about the voice command processing and outcome.

      object allOf
      uid: assistantEventMsg
      • #event

      Examples

Messages

  • #1request

    🚀 Generic request message.

    object
    uid: commonReq

    Common request message properties.

  • #2response

    🚀 Generic response message.

    object
    uid: commonResp

    Common response message properties.

  • #3event

    🚀 Generic event message of a subscribed channel.

    object
    uid: commonEvent

    Common event message properties.

  • #4auth_required

    🧪 Authentication request event after connection is established.

    This event is only sent if the client didn't provide authentication during connection setup.
    The client must then authenticate with the auth request message.

    object allOf
    uid: authRequiredEvent
  • #5auth

    🧪 Authenticate a connection.

    Sent by the client right after establishing a connection if header authentication cannot be used, or after an auth_required request by the server.

    object allOf
    uid: authRequestMsg
  • #6authentication

    🧪 Authentication response.

    The authentication result is provided in the code attribute:

    • 200: success, API can be used and message requests are accepted.
    • 401: authentication failed, the provided API-key is not valid. The server will close the connection.
    object allOf
    uid: authMsg
  • #7ping

    🚀 Application level based ping to determine whether connection is alive.

    Client can ping the server to determine whether connection is alive. Server responds with pong.

    This is an application level ping as opposed to the standard WebSocket ping frames. This is only required if a client framework doesn't support WebSocket ping frames!
    Additional payload data may be included in msg_data which will be echoed by the server. E.g. a client timestamp to calculate round trip times.

    object allOf
    uid: ping
  • #8pong

    🚀 Pong is a response to ping message

    Server pong response to a ping to determine whether connection is alive. This is an application level pong as opposed to default pong in websockets standard which is sent by client in response to a ping.

    object allOf
    uid: pong
  • #9result

    🚀 Command result message

    object
    uid: commonResp

    Common response message properties.

  • #10version

    🚀 Get version information.

    object allOf
    uid: versionMsg
  • #11version_info

    🧪 Version information response.

    object allOf
    uid: versionInfoMsg
  • #12system

    🚀 Get system information.

    Get hardware information about the device like serial number, model number and hardware revision.

    object allOf
    uid: getSystemInfoMsg
  • #13system_info

    🧪 System information response.

    object allOf
    uid: systemInfoMsg
  • #14system_cmd

    🧪 Perform a system command like reboot or power-off.

    The following system commands can be executed:

    • STANDBY: Put the device into standby mode.
    • REBOOT: Reboot the device.
    • POWER_OFF: Switch off the device
    • RESTART: Restart all applications.
    • RESTART_UI: Restart the ui application.
    • RESTART_CORE: Restart the core service application.

    The server will respond with a result message and a status code of the request.
    For status code 200 the WebSocket connection will be closed and the command executed.

    object allOf
    uid: systemCmdMsg
  • #15get_factory_reset_token

    Get factory reset token.

    Get a factory reset token to perform a complete factory reset of the remote.

    The token will be valid for 60 seconds. Afterwards, a new token must be requested.
    Whenever a new token is requested, any old tokens will be invalidated.

    object allOf
    uid: getFactoryResetTokenMsg
  • #16factory_reset_token

    Factory reset token response.

    object allOf
    uid: factoryResetTokenMsg
  • #17factory_reset

    Perform a factory reset.

    A factory reset removes all configuration data and puts the device into a clean state.

    ⚠️ Warning: All user data will be erased and won't be recoverable!

    A reset token must be requested first and provided to perform a factory reset.

    object allOf
    uid: factoryResetMsg
  • #18set_api_access

    Enable or disable API access.

    Enable / disable API access for web-configurator. If the account gets disabled, all active sessions are closed and WebSocket connections disconnected.
    The server will respond with a result message and a status code of the request.

    object allOf
    uid: setApiAccessMsg
  • #19get_api_access

    Get API access status.

    The server will respond with an api_access message.

    object allOf
    uid: getApiAccessMsg
  • #20api_access

    API access status response.

    object allOf
    uid: apiAccessMsg
  • #21check_system_update

    🧪 Check if system update is available.

    Returns the known available system updates.

    System update checks are run automatically (if not disabled in settings). Use the force_update flag to force an update check.

    object allOf
    uid: checkSystemUpdateMsg
  • #22system_update_info

    🧪 Available system update response.

    object allOf
    uid: systemUpdateInfoMsg
  • #23update_system

    🧪 Perform system update.

    Start a system update with the given update_id parameter. Use latest to use the latest available system update.

    The system update will be started if:

    • the system update has been downloaded already (download state is DOWNLOADED).
    • the device has at least 50% battery charge.

    If the system update is started, the response message contains state: START. In case there's not enough battery, 503 service unavailable is returned. It is recommended to perform the update while the remote is charging in the docking station.

    The progress of the system update can be retrieved with the get_system_update_progress message, or by listening to the software_update event messages.

    If the system update hasn't been downloaded yet (download state is PENDING or ERROR), this operation will only start the download and return state: DOWNLOAD. Once successfully downloaded, it can be installed by this request message again.

    The download process emits software_update progress event messages with event_type: PROGRESS and state: DOWNLOAD. The payload fields download_bytes, download_percent and update_id are set.

    • A successful download is indicated with download_percent: 100, without the download_bytes field.
    • The state is set to FAILURE if a download fails.
    • Depending on download speed, download_percent might skip certain values or report the same value multiple times.
    • The famous last percent will take longer due to image validation.

    Example download progress events:

    • Download progress event:
    {
  "kind": "event",
  "msg": "software_update",
  "cat": "REMOTE",
  "ts": "2024-09-30T16:25:18.668395688Z",
  "msg_data": {
    "event_type": "PROGRESS",
    "progress": {
      "download_bytes": 256734720,
      "download_percent": 97,
      "state": "DOWNLOAD",
      "update_id": "some-id"
    },
    "update_id": "some-id"
  }
}
    • Final success event:
    {
  "kind": "event",
  "msg": "software_update",
  "cat": "REMOTE",
  "ts": "2024-09-30T16:25:34.229442566Z",
  "msg_data": {
    "event_type": "PROGRESS",
    "progress": {
      "download_percent": 100,
      "state": "DOWNLOAD",
      "update_id": "some-id"
    },
    "update_id": "some-id"
  }
}
    object allOf
    uid: updateSystemMsg
  • #24update_system_result

    🧪 System update response.

    Returns the state of the system update request.

    object allOf
    uid: updateSystemResultMsg
  • #25get_system_update_progress

    🧪 Get system update progress.

    This is a manual request for the update progress if the system update event messages cannot be used.

    object allOf
    uid: getSystemUpdateProgressMsg
  • #26system_update_progress

    🧪 System update progress response.

    object allOf
    uid: systemUpdateProgressMsg
  • #27get_power_mode

    🧪 Get current power mode, battery information and duration to enter standby.

    Returns the current power mode of the device, if a power-supply is connected and the duration in seconds until the the device will enter standby.

    • standby_timeout_sec is not returned if standby is disabled or the device is currently in the process of entering or exiting standby.
    • standby_timeout_sec can return 0 without the device going into standby.
      This is the case if power_supply: true is set. As soon as the power supply is offline, the device will enter standby after a few seconds if no input activity is registered.
    object allOf
    uid: getPowerModeMsg
  • #28power_mode

    🧪 Current power mode response.

    object allOf
    uid: powerModeMsg
  • #29set_power_mode

    🧪 Change the current power mode.

    object allOf
    uid: setPowerModeMsg
  • #30get_battery_charger

    🔍 Get battery charger information.

    Device features:

    • DOCK_CHARGING: device can be charged in docking station (UCR2, UCR3).
    • WIRELESS_CHARGING: device has wireless charging support (UCR3).
    object allOf
    uid: getBatteryChargerMsg
  • #31battery_charger

    🔍 Battery charger response.

    object allOf
    uid: batteryChargerMsg
  • #32update_battery_charger

    🔍 Enable or disable wireless charging.

    object allOf
    uid: updateBatteryChargerMsg
  • #33get_standby_inhibitors

    🧪 Get standby inhibitors.

    Automatic system standby can be prevented with "standby inhibitors". For example during integration setup or as a user option for activities.

    There are two types of inhibitors:

    • Temporary inhibitors set a delay value for which the device doesn't go into standby. After the delay and the idle timeouts have expired, the remote goes into standby and the temporary inhibitor will be removed.
    • Blocking inhibitors will prevent the device to go into standby until the inhibitor is removed by the client.
    object allOf
    uid: getStandbyInhibitorsMsg
  • #34standby_inhibitors

    🧪 Standby inhibitors response.

    object allOf
    uid: inhibitorsMsg
  • #35create_standby_inhibitor

    🧪 Create a standby inhibitor.

    object allOf
    uid: createStandbyInhibitorMsg
  • #36standby_inhibitor

    🧪 Standby inhibitor response.

    object allOf
    uid: inhibitorMsg
  • #37del_standby_inhibitor

    🧪 Remove a standby inhibitor.

    object allOf
    uid: delStandbyInhibitorMsg
  • #38del_all_standby_inhibitors

    🧪 Remove all standby inhibitors.

    object allOf
    uid: delAllStandbyInhibitorsMsg
  • #39get_ambient_light

    🔍 Get current ambient light intensity.

    object allOf
    uid: getAmbientLightMsg
  • #40ambient_light

    🔍 Current ambient light response.

    object allOf
    uid: ambientLightMsg
  • #41reset_configuration

    🧪 Reset all settings to default values.

    object allOf
    uid: resetConfigurationMsg
  • #42get_configuration

    🧪 Get all system settings.

    object allOf
    uid: getConfigurationMsg
  • #43configuration

    🧪 All system settings response.

    object allOf
    uid: configurationMsg
  • #44get_button_cfg

    🧪 Get button settings.

    object allOf
    uid: getButtonCfgMsg
  • #45set_button_cfg

    🧪 Modify button settings.

    object allOf
    uid: setButtonCfgMsg
  • #46button_cfg

    🧪 Button settings response.

    Button backlight configuration.

    Device features:

    • BACKLIGHT: buttons have backlight (UCR2, UCR3).
    • RGB_COLOR: RGB color backlight support (UCR3).
    • ZONES: backlight can be controlled with individual zones (UCR3).

    ⚠️ Individual color per zone is not yet supported.

    object allOf
    uid: buttonCfgMsg
  • #47get_device_cfg

    🧪 Get remote device settings.

    object allOf
    uid: getDeviceCfgMsg
  • #48set_device_cfg

    🧪 Modify remote device settings.

    object allOf
    uid: setDeviceCfgMsg
  • #49device_cfg

    🧪 Remote device settings response.

    object allOf
    uid: deviceCfgMsg
  • #50get_display_cfg

    🧪 Get display settings.

    object allOf
    uid: getDisplayCfgMsg
  • #51set_display_cfg

    🧪 Modify display settings.

    object allOf
    uid: setDisplayCfgMsg
  • #52display_cfg

    🧪 Display settings response.

    object allOf
    uid: displayCfgMsg
  • #53get_features_cfg

    🧪 Get feature flag settings.

    object allOf
    uid: getFeaturesCfgMsg
  • #54set_features_cfg

    🧪 Modify a feature flag.

    object allOf
    uid: setFeaturesCfgMsg
  • #55features_cfg

    🧪 Feature flag settings response.

    object allOf
    uid: featuresCfgMsg
  • #56get_haptic_cfg

    🧪 Get haptic settings.

    object allOf
    uid: getHapticCfgMsg
  • #57set_haptic_cfg

    🧪 Modify haptic settings.

    object allOf
    uid: setHapticCfgMsg
  • #58haptic_cfg

    🧪 Haptic settings response.

    object allOf
    uid: hapticCfgMsg
  • #59get_localization_cfg

    🧪 Get localization settings.

    object allOf
    uid: getLocalizationCfgMsg
  • #60set_localization_cfg

    🧪 Modify localization settings.

    object allOf
    uid: setLocalizationCfgMsg
  • #61localization_cfg

    🧪 Localization settings response.

    object allOf
    uid: localizationCfgMsg
  • #62get_timezone_names

    🧪 Get all available time zone names.

    object allOf
    uid: getTimezoneNamesMsg
  • #63timezone_names

    🧪 Available time zone names response.

    object allOf
    uid: timezoneNamesMsg
  • #64get_localization_countries

    🧪 Get available countries for the localization configuration.

    object allOf
    uid: getLocalizationCountriesMsg
  • #65localization_countries

    🧪 Available localization countries response.

    object allOf
    uid: localizationCountriesMsg
  • #66get_localization_languages

    🧪 Get stored translations or request available translations from the UI.

    The available translations are provided from the UI application.
    Future UI versions might provide new or updated translations.

    If this request is sent to the UI application, the response is stored in the remote-core until new information is available from the UI.

    If this request is received, the stored configuration from the UI application is returned. E.g. the web-configurator requires the available translations.

    object allOf
    uid: getLocalizationLanguagesMsg
  • #67localization_languages

    🧪 Available translations response.

    object allOf
    uid: localizationLanguagesMsg
  • #68get_network_cfg

    🧪 Get network settings.

    object allOf
    uid: getNetworkCfgMsg
  • #69set_network_cfg

    🧪 Modify network settings.

    Change one or multiple network settings.

    ⚠️ The ws configuration object is an expert setting intended for support issues. Those settings may not be exposed in a user frontend.

    • The ws object is only returned, after it has been set manually.
    • Settings stay persisted for PATCH requests not containing the ws key.
    • Return and apply current system settings: send a PATCH request with an empty object: `"ws": {}".
    • The ws settings can be removed with a network configuration reset reset_network_cfg or through a full configuration reset: reset_configuration
    • Modifying any ws settings requires a system reboot.
    object allOf
    uid: setNetworkCfgMsg
  • #70reset_network_cfg

    🧪 Reset network settings.

    Reset all network settings to their defaults.

    The expert settings in the ws configuration object will be removed.

    object allOf
    uid: resetNetworkCfgMsg
  • #71network_cfg

    🔍 Network settings response.

    object allOf
    uid: networkCfgMsg
  • #72get_software_update_cfg

    🧪 Get software update settings.

    object allOf
    uid: getSoftwareUpdateCfgMsg
  • #73set_software_update_cfg

    🧪 Modify software update settings.

    Change one or multiple software update settings.

    If check_for_updates is enabled:

    • the device automatically checks for new updates daily. The check happens during a random time within the OTA window time frame ota_window_start - ota_window_end.
    • if a new update is available, the update metadata is immediately downloaded and the firmware update file is scheduled to download.
    • the firmware file will only download if the remote has at least 50% battery charge.
    • if the remote is not in the dock and suspended, the remote will not automatically wake up and the check will be skipped.

    If auto_update is enabled:

    • once the firmware file is downloaded it will be automatically installed in the next OTA check window.
    • the installation will only start if the remote has at least 50% battery charge.

    OTA window fields:

    • the stored values are used if omitted.
    • default values are set if not configured.
    • the time of day corresponds to the configured timezone.
    • for changing the update window, both start and end times are required, otherwise a default will be used.
    • if the end time is before the start time, the window will spawn over midnight, e.g. 23:00:00 - 01:00:00.

    Optional software update channel & token:

    • the default release channel is used if not configured.
    • the stored values are used if omitted.
    • changing the update channel is intended for closed user groups only.
      ⚠️ High chance of breaking changes, bugs and loosing data!
    • other channels than default might require an access token in channel_token.
    • ⚠️ Changing the update channel or token requires a device restart, otherwise the automated updates will not use the new channel!
    object allOf
    uid: setSoftwareUpdateCfgMsg
  • #74reset_software_update_cfg

    🧪 Reset software update settings.

    Set all software update settings to default values and use the default release update channel.

    object allOf
    uid: resetSoftwareUpdateCfgMsg
  • #75software_update_cfg

    🧪 Software update settings response.

    object allOf
    uid: softwareUpdateCfgMsg
  • #76get_power_saving_cfg

    🧪 Get power saving settings.

    object allOf
    uid: getPowerSavingCfgMsg
  • #77set_power_saving_cfg

    🧪 Modify power saving settings.

    object allOf
    uid: setPowerSavingCfgMsg
  • #78power_saving_cfg

    🧪 Power saving settings response.

    object allOf
    uid: powerSavingCfgMsg
  • #79get_profile_cfg

    🧪 Get profile settings.

    object allOf
    uid: getProfileCfgMsg
  • #80set_profile_cfg

    🧪 Modify profile settings.

    object allOf
    uid: setProfileCfgMsg
  • #81profile_cfg

    🧪 Profile settings response.

    object allOf
    uid: profileCfgMsg
  • #82get_sound_cfg

    🧪 Get sound settings.

    object allOf
    uid: getSoundCfgMsg
  • #83set_sound_cfg

    🧪 Modify sound settings.

    object allOf
    uid: setSoundCfgMsg
  • #84sound_cfg

    🧪 Sound settings response.

    object allOf
    uid: soundCfgMsg
  • #85get_voice_control_cfg

    🔍 Get voice control settings.

    object allOf
    uid: getVoiceControlCfgMsg
  • #86set_voice_control_cfg

    🔍 Modify voice control settings.

    Change one or multiple voice control settings. A missing field will in the request object will keep the old value.

    If the specified voice control entity does not exist, the voice assistant configuration will be removed.

    object allOf
    uid: setVoiceControlCfgMsg
  • #87voice_control_cfg

    🔍 Voice control settings response.

    object allOf
    uid: voiceControlCfgMsg
  • #88get_voice_assistants

    🔍 Get available voice assistants.

    object allOf
    uid: getVoiceAssistantsMsg
  • #89voice_assistants

    🔍 Voice assistants response.

    object allOf
    uid: voiceAssistantsMsg
  • #90get_entity_types

    🧪 Retrieve supported entity types.

    object allOf
    uid: getEntityTypesMsg
    • #entity
  • #91entity_types

    🧪 List of supported entity types response.

    object allOf
    uid: entityTypesMsg
    • #entity
  • #92get_entity

    🧪 Retrieve a configured entity.

    object allOf
    uid: getEntityMsg
    • #entity
  • #93get_entities

    🧪 Search and retrieve configured entities.

    Returns all configured entities, optionally filtered by one or multiple entity types or integrations.

    The text search searches in the entity name, entity identifier and integration name.

    The exclude query parameter allows to exclude entities defined in an activity, macro, profile page or group. Supported exclusions:

    • activity- or macro-entity ID: all included entities
    • profile page_id: defined entities in the page
    • profile group_id: defined entities in the group

    Notes:

    • Mixing activity/macro and page/group identifiers is not supported!
    • All non-command entities are also filtered out if an activity or macro identifier is specified.

    Attention: pagination is active and can be parameterized to return more items per page if required.

    object allOf
    uid: getEntitiesMsg
    • #entity
  • #94entities

    🧪 List of configured entities response.

    object allOf
    uid: entitiesMsg
    • #entity
  • #95get_available_entities

    🧪 Retrieve the available entities provided by an integration.

    ⚠️ At the moment it's only possible to retrieve available entities from one integration at a time.

    • filter.integration_id must be specified!
    • available entities can be filtered by one or multiple entity types.
    • the text search searches in the entity name, entity identifier and area.

    Attention: pagination is active and can be parameterized to return more items per page if required.

    object allOf
    uid: getAvailableEntitiesMsg

    Retrieve the available entities provided by the integration instance.

    • #entity
  • #96available_entities

    🧪 List of available entities response.

    object allOf
    uid: availableEntitiesMsg
    • #entity
  • #97get_entity_commands

    🧪 Retrieve the available commands of an entity or entity type.

    The commands can either be retrieved from a specific entity or from an entity type:

    • entity_id: only available commands for the given entity are returned. This depends on the entity's features.
    • entity_type: all commands for the given entity type are returned.

    The returned command identifiers are not the standard command identifiers like on or off, but mapping identifiers like light.on and light.color_temperature for the command structure information returned with get_entity_command_metadata or GET /api/cfg/entity/commands.

    This then allows to build a full command request execute_entity_command message with or without parameters.

    object allOf
    uid: getEntityCommandsMsg
    • #entity
  • #98entity_commands

    🧪 Available commands of an entity response.

    object allOf
    uid: entityCommandsMsg
    • #entity
  • #99get_entity_command_metadata

    🔍 Get entity command definitions.

    Meta-information about the entity commands.

    object allOf
    uid: getEntityCommandMetadataMsg
    • #entity
  • #100entity_command_metadata

    🔍 Entity command definitions.

    object allOf
    uid: entityCommandMetadataMsg
    • #entity
  • #101execute_entity_command

    🧪 Execute an entity command.

    Optional command data can be provided in attribute params.

    object allOf
    uid: executeEntityCommandMsg
    • #entity
  • #102entity

    🧪 Entity information response.

    object allOf
    uid: entityMsg
    • #entity
  • #103entity_change

    🧪 Entity change event.

    Emitted if an entity has changed, a new entity has been added or a configured entity has been deleted.

    If an entity state or dynamic attribute has changed (through notification of an integration driver), then only the attributes object is included within new_state. This happens after an entity_command or if the entity is updated manually through a user or an external system, e.g. if it has been switched off.

    If the entity definition has changed, e.g. the name, description or icon has been modified with the web configurator, the full entity data is included within new_state.

    If a complete integration is removed then only an integration_change event is sent, i.e. there won't be individual entity_change events for every removed entity!

    ⚠️ This event is also used to indicate the client to reload all entities. This is the case if only event_type: change is set and the entity_id field is missing.

    object allOf
    uid: entityChangeEventMsg
    • #entity
    • #event
  • #104activity_group_change

    🧪 Activity group change event.

    Emitted if an activity group has changed, a new group has been added or a group has been deleted.

    ⚠️ This event is also used to indicate the client to reload all activity groups. This is the case if only event_type: change is set and the group_id field is missing.

    object allOf
    uid: activityGroupChangeEventMsg
    • #entity
    • #event
  • #105update_entity

    🧪 Update an entity.

    Update one or multiple properties of an entity.

    The updated entity object is returned if the entity could be updated.
    In case of an error the default result message is returned with an error code.

    object allOf
    uid: updateEntityMsg
    • #entity
  • #106delete_entity

    🧪 Remove a configured entity.

    Delete the configured entity and remove it from all profile pages and groups.

    object allOf
    uid: deleteEntityMsg
    • #entity
  • #107delete_entities

    🧪 Remove configured entities.

    Unloads and deletes multiple configured entities, either by integration identifier or by entity identifiers. If a deleted entity is still provided from an integration, it can be reused and will show up again as available entity from its integration.

    ⚠️ An empty request body array will delete all configured entities!

    All references to the configured entities will be removed from profile pages and groups.

    This is a best effort operation:

    • unknown entity identifiers are ignored, no error is returned

    Deleted entities will trigger an entity_change event with event_type: DELETE. If a large amount of entities are deleted, a single, generic entity_change event might be sent instead (without an entity_id field).

    object allOf
    uid: deleteEntitiesMsg
    • #entity
  • #108get_dock_count

    🧪 Get total number of configured docks.

    By default only active docks are counted. This can be changed with the active query parameter.

    object allOf
    uid: getDockCountMsg
    • #dock
  • #109dock_count

    🧪 Total number of configured docks response.

    object allOf
    uid: dockCountMsg
    • #dock
  • #110get_docks

    🧪 List configured docks and their connection state.

    Returns all dock configuration with paging. The configuration data is enriched with current connection information. Use the get_dock_count operation to retrieve the total number of defined docking stations.

    By default only active docks are returned. This can be changed with the active query parameter.

    object allOf
    uid: getDocksMsg
    • #dock
  • #111docks

    🧪 Configured docks and their connection state response.

    object allOf
    uid: docksMsg
    • #dock
  • #112create_dock

    🧪 Create a new dock configuration.

    Manually create and persist a new dock configuration. This is a low-level operation without configuring and setting up the dock as with the setup operations! To establish a session to the dock, the connect operation must be called afterwards.

    • Error 422 is returned if the given service name in dock_id already exists.
    • If custom_ws_url is not specified, the dock address is resolved through an mDNS service name lookup in dock_id.
    • The active flag specifies if the dock will react to connection requests.
    • Non-active docks will not auto-connect and must be enabled first to be used.
    • Non-active docks won't be visible in the web-configurator.
    • If no token is provided the default token is used! The token is used to authenticate the WebSocket connection once a connection to the dock is established.
    • If model is provided it must be one of the known dock model identifiers: UCD2 or YIO1DOCK.
    object allOf
    uid: createDockMsg
    • #dock
  • #113dock

    🧪 Configured dock response.

    object allOf
    uid: dockMsg
    • #dock
  • #114delete_all_docks

    🧪 Delete all dock configurations.

    ⚠️ All defined dock configurations will be irrevocably deleted!

    Active dock sessions will be disconnected and the persisted dock configurations removed.

    object allOf
    uid: deleteAllDocksMsg
    • #dock
  • #115get_dock

    🧪 Get dock configuration.

    Returns the dock configuration, enriched with the current session information if a dock connection is established.

    object allOf
    uid: getDockMsg
    • #dock
  • #116update_dock

    🧪 Change dock configuration like auto-connect or access token.

    Update one or more dock fields.

    • If the dock is in an active connection state, then the name, token and wifi values are persisted in the dock if provided in the request. The request fails with 503 service unavailable if the configuration can't be set in the docking station.
    • An empty custom_ws_url value will remove the custom URL.
    • If the dock is not active, the values are only stored in the remote. A changed token will be used for the next connection attempt.
    object allOf
    uid: updateDockMsg
    • #dock
  • #117dock_connection_command

    🧪 Start or stop a dock connection.

    Establish or stop a session to a specific or all active docks.

    object allOf
    uid: dockConnectionCommandMsg
    • #dock
  • #118delete_dock

    🧪 Delete dock configuration.

    ⚠️ The dock configuration will be irrevocably deleted!

    An active dock session will be disconnected and the persisted dock configuration removed.

    object allOf
    uid: deleteDockMsg
    • #dock
  • #119dock_command

    🧪 Send a dock command.

    The following command values are defined:

    • SET_LED_BRIGHTNESS: set the maximum brightness of the front indicator LED. Set the 0..100 percentage as string parameter in the value field.
    • SET_VOLUME: 3️⃣ set the speaker volume. Set the 0..100 percentage as string parameter in the value field.
    • IDENTIFY: identify the dock with blinking the indicator LED.
    • REMOTE_LOW_BATTERY: trigger the low battery status indicator on the dock.
    • REMOTE_CHARGED: trigger the remote charged indicator on the dock.
    • REMOTE_NORMAL: trigger the normal remote operation mode on the dock.
    • REBOOT: reboot the dock.
    • RESET: ⚠️ factory reset the dock. Requires administrator privileges.
      The dock configuration will be deleted from the remote.
    object allOf
    uid: dockCommandMsg
    • #dock
  • #120get_dock_discovery_status

    🧪 Get docking station discovery status.

    Returns the current discovery status and any discovered docks.

    object allOf
    uid: getDockDiscoveryStatusMsg
    • #dock
  • #121dock_discovery_status

    🧪 Docking station discovery status response.

    object allOf
    uid: dockDiscoveryStatusMsg
    • #dock
  • #122start_dock_discovery

    🧪 Start discovery of new docking stations.

    Start device discovery over Bluetooth and mDNS. Bluetooth or network discovery can be disabled with a query parameter. By default the discovery automatically stops after 30 seconds. Use the get_dock_discovery_status status request to check on discovered devices or stop_dock_discovery to stop discovery.

    By default only new network devices are returned. If a dock is already configured it will be omitted from the results, unless the query parameter new=false is set. Docks with Bluetooth enabled are always returned, since this usually means that the dock needs to be re-configured.

    • If BT is disabled in the remote, the bt parameter is ignored.
    • Emits the WebSocket event dock_discovery with event_type: START when discovery starts.
    • For each discovered device the WebSocket event dock_discovery with event_type: DISCOVER is emitted.
    • This operation clears any old discovered devices and won't be accessible anymore with the GET operation.
    object allOf
    uid: startDockDiscoveryMsg
    • #dock
  • #123stop_dock_discovery

    🧪 Stop discovery of new docking stations.

    Stops the device discovery. The current discovery status is returned in the response. Already discovered devices won't be returned and can still be retrieved with the get_dock_discovery_status operation.

    Emits the WebSocket event dock_discovery with event_type: STOP.

    object allOf
    uid: stopDockDiscoveryMsg
    • #dock
  • #124get_dock_discovery_device

    🧪 Get docking station discovery device status.

    Returns the discovered docking station device.

    object allOf
    uid: getDockDiscoveryDeviceMsg
    • #dock
  • #125dock_discovery_device

    🧪 Docking station discovery device status response.

    object allOf
    uid: dockDiscoveryDeviceMsg
    • #dock
  • #126exec_cmd_on_discovered_dock

    🧪 Execute command on a discovered docking station.

    Perform a WebSocket connection test with a discovered docking station. If the dock requires an API token, it must be specified in the request body.
    The IDENTIFY command also blinks the status LED on the dock.

    Response status codes:

    • 200: successful operation: the connection test was successful and docking station metadata could be retrieved.
    • 404: discovered dock with dock_id not found. Check if the discovery result is still available and has not been deleted. This can happen after a timeout since the discovery, or if the discovery result has been cleared with DELETE /docks/discover.
    • 503: docking station connection could not be established.
    object allOf
    uid: execCmdOnDiscoveredDockMsg
    • #dock
  • #127dock_system_info

    🧪 Dock system information response.

    object allOf
    uid: dockSystemInfoMsg
    • #dock
  • #128get_dock_setup_processes

    🧪 Get current dock setup processes.

    Return a list of all active setup process identifiers.

    object allOf
    uid: getDockSetupProcessesMsg
    • #dock
  • #129dock_setup_processes

    🧪 Current dock setup processes response.

    object allOf
    uid: dockSetupProcessesMsg
    • #dock
  • #130create_dock_setup

    🧪 Start setting up a new docking station.

    Create a new setup process from a discovered dock or from a manually provided dock address.

    • If there's already a setup process running for the given dock id, status code 409 is returned.
    • Emits the WebSocket event dock_setup_change with event_type: START when this operation returns 201.

    Start setup from dock discovery:

    • The required request data can be obtained from the /api/docks/discover endpoints when searching for docking stations over Bluetooth or Ethernet. Simply provide the returned DockDiscovery data object (which is a super set of the required data to start a setup process).
    • The returned id in the DockSetupInfo response will be the identifier for the next PUT /docks/setup/:id call to provide additional data.

    Manual setup:

    • A dock identifier will automatically be created and returned in DockSetupInfo.
    • The dock must be reachable on the network with the provided custom_ws_url and optional token. Otherwise, status code 503 is returned.
    • The setup process is automatically started after a successful POST request, no call to PUT /docks/setup/:id is required.

    Response status codes:

    • 201: setup process successfully started. Use GET /docks/setup/:id to poll for status updates, or listen to WebSocket dock_setup_change event messages.
    • 400: invalid data in request body.
    • 409: a setup process is already running. Either wait until finished, or abort it.
    • 503: service not available to setup docking station.
      E.g. Bluetooth is disabled and therefore the docking station cannot be setup over Bluetooth. Either enable Bluetooth or setup the dock over Ethernet.
    object allOf
    uid: createDockSetupMsg
    • #dock
  • #131dock_setup_status

    🧪 Dock setup information response.

    object allOf
    uid: dockSetupStatusMsg
    • #dock
  • #132stop_all_dock_setups

    🧪 Abort and remove all setup processes.

    Stop all setup processes at the next possible operation and remove all setup process information.

    object allOf
    uid: stopAllDockSetupsMsg
    • #dock
  • #133get_dock_setup_status

    🧪 Get docking station setup status.

    Poll operation to retrieve the current docking station setup state. See the state and error fields in the response message. There are also WebSocket dock_setup_change event messages for state changes to avoid polling.

    Defined setup states:

    • NEW: setup has not yet been started. Use the PUT operation to provide the required data and to start setting up the dock.
    • CONFIGURING: setup data is currently being transferred to the dock.
    • RESTARTING: dock has been configured and is restarting to integrate into the network.
    • OK: setup process has been completed successfully, the dock can now be used.
    • ERROR: the setup process failed. Check the error field for more information.
    object allOf
    uid: getDockSetupStatusMsg
    • #dock
  • #134start_dock_setup

    🧪 Setup docking station.

    Set required data to start the setup process and configure the docking station. When using Bluetooth the WiFi network name and credentials must be provided to connect the dock to the WiFi network.

    The state field in the response message indicate the current state of the setup process. Use the GET operation to poll for state updates or listen to the corresponding WebSocket dock_setup_change event messages with event_type: SETUP.

    object allOf
    uid: startDockSetupMsg
    • #dock
  • #135stop_dock_setup

    🧪 Abort the dock setup process.

    Stop the setup process at the next possible operation and remove the setup process information.
    To start a new setup process, use the POST /docks/setup operation again.

    Emits the WebSocket event dock_setup_change with event_type: STOP.

    object allOf
    uid: stopDockSetupMsg
    • #dock
  • #136get_wifi_status

    🧪 Get WiFi status.

    object allOf
    uid: wifiGetStatusMsg
    • #wifi
  • #137wifi_status

    🧪 WiFi status.

    object allOf
    uid: wifiStatusMsg
    • #wifi
  • #138wifi_command

    🧪 WiFi connection handling.

    Perform one of the following commands on the WLAN interface:

    • DISCONNECT: Disconnect and wait for REASSOCIATE or RECONNECT command before connecting again.
    • RECONNECT: Connect if disconnected (i.e. like REASSOCIATE, but only connect if in disconnected state).
    • REASSOCIATE: Force reassociation.
    • ENABLE_ALL_NETWORKS: Enable all network connections and start connecting to a network if in disconnected state.
    • DISABLE_ALL_NETWORKS: Disable all network connections and disconnect if in connected state.

    ⚠️Attention: ENABLE_ALL_NETWORKS and DISABLE_ALL_NETWORKS will persist the state! I.e. if all networks are disabled and the device is restarted afterwards, no WiFi connection will be established.

    object allOf
    uid: wifiCommandMsg
    • #wifi
  • #139wifi_scan_start

    🧪 Start discovery of WiFi access points.

    Request a new BSS scan. A scan usually takes a few seconds and the current state is returned with the get_wifi_scan_status operation, together with the already found access points.

    object allOf
    uid: wifiScanStartMsg
    • #wifi
  • #140wifi_scan_stop

    🧪 Stop discovery of WiFi access points.

    Stops the access point discovery. The current discovery status is returned in the response.

    object allOf
    uid: wifiScanStopMsg
    • #wifi
  • #141get_wifi_scan_status

    🧪 Get discovered WiFi access points.

    Returns the current discovery status and any discovered access points.

    object allOf
    uid: wifiGetScanStatusMsg
    • #wifi
  • #142wifi_scan_status

    🧪 Discovered WiFi access points.

    object allOf
    uid: wifiScanStatusMsg
    • #wifi
  • #143get_all_wifi_networks

    🧪 Get configured WiFi networks.

    object allOf
    uid: wifiGetAllNetworksMsg
    • #wifi
  • #144wifi_networks

    🧪 Configured WiFi networks.

    object allOf
    uid: wifiNetworksMsg
    • #wifi
  • #145add_wifi_network

    🧪 Create a new WiFi network configuration.

    Add a new network configuration for the given SSID.
    For an open network without password the password field must be omitted (do not send an empty password value).

    ⚠️ Only WPA-PSK (pre shared keys) and open networks are supported!

    object allOf
    uid: wifiAddNetworkMsg
    • #wifi
  • #146del_all_wifi_networks

    🧪 Delete all configured WiFi networks.

    Disconnects the WiFi network and removes all network configurations.

    ⚠️ Attention: the network configuration is automatically persisted and the network configuration cannot be retrieved anymore!

    object allOf
    uid: wifiDelAllNetworksMsg
    • #wifi
  • #147get_wifi_network

    🧪 Get WiFi network configuration.

    object allOf
    uid: wifiGetNetworkMsg
    • #wifi
  • #148wifi_network

    🧪 WiFi network configuration.

    object allOf
    uid: wifiNetworkMsg
    • #wifi
  • #149update_wifi_network

    🧪 Change WiFi network configuration.

    Set a new WiFi network password.

    object allOf
    uid: wifiUpdateNetworkMsg
    • #wifi
  • #150wifi_network_command

    🧪WiFi network connection handling.

    Perform one of the following commands on a network configuration:

    • ENABLE: Enable a network. If no network is connected, it will be tried to connect to this network.
    • DISABLE: Disable a network. If the network is currently connected it will be disconnected.
    • SELECT: Select the given network and disable all others.

    ⚠️ Attention: all network changes (enabled or disabled) are persisted!

    object allOf
    uid: wifiNetworkCommandMsg
    • #wifi
  • #151del_wifi_network

    🧪 Delete a configured WiFi network.

    The given network is removed from the configuration and disconnected if currently connected.

    ⚠️ Attention: the network configuration is automatically persisted and the removed network configuration cannot be retrieved anymore!

    object allOf
    uid: wifiDelNetworkMsg
    • #wifi
  • #152wifi_change

    🧪 WiFi change event.

    Emitted if the WiFi status changed, e.g. connected or disconnected to an access point, or if a WiFi network scan finished.

    object allOf
    uid: wifiChangeEventMsg
    • #event
  • #153bt_pairing_started

    🔍 Inform user that pairing has started.

    Emitted if a central started pairing with the Remote.

    object allOf
    uid: btPairingStartedEventMsg
    • #event
  • #154bt_pairing_auth_request

    🔍 Request pairing authorization from the user.

    Depending on authentication requirements, IO capabilities, etc. a different type of authentication is requested. The client must respond with the bt_pairing_response event.

    object allOf
    uid: btPairingAuthRequestEventMsg
    • #event
  • #155bt_pairing_complete

    🔍 Bonding process has finished.

    This event is emitted after the bonding process, either with a success state or an error code if bonding failed.

    object allOf
    uid: btPairingCompleteEventMsg
    • #event
  • #156bt_pairing_response

    🔍 Action to bt_pairing_auth_request event.

    This request needs to be sent for a bt_pairing_auth_request event:

    • Passkey request: either provide the passkey entered by the user, or decline it with confirm: false.
    • NumericComparison request: confirm or decline with confirm: true | false.
    object allOf
    uid: btPairingResponseMsg
    • #event
  • #157get_profiles

    🧪 Retrieve all profiles.

    object allOf
    uid: getProfilesMsg
    • #profile
  • #158profiles

    🧪 List of available profiles response.

    object allOf
    uid: profilesMsg
    • #profile
  • #159get_profile

    🧪 Retrieve the specified profile.

    object allOf
    uid: getProfileMsg
    • #profile
  • #160profile

    🧪 Profile data response.

    object allOf
    uid: profileMsg
    • #profile
  • #161get_active_profile

    🧪 Retrieve the active profile.

    If no profile exists, or no profile is set active, 404 is returned.

    object allOf
    uid: getActiveProfileMsg
    • #profile
  • #162switch_profile

    🧪 Switch active profile.

    The administrator PIN in admin_pin is required to switch from a restricted to a normal profile. If the current profile is a restricted profile and the pin is missing, error 401 is returned.

    object allOf
    uid: switchProfileMsg
    • #profile
  • #163add_profile

    🧪 Add a new profile.

    There are two different types of profiles:

    • Normal profile (default): can do anything, change settings, add pages, entities, integrations, etc.
    • Restricted profile: intended for guests or children, who can only use the remote, but cannot change settings.

    The admin PIN is required to switch from a restricted to a normal profile. It can be defined in settings.

    • Switching away from a restricted profile will prompt the user to enter the admin PIN.
    • Switching to a restricted profile can be done without entering the admin PIN.

    Profile request object:

    • profile_id is optional and auto-generated if not specified. Otherwise it needs to be a unique profile identifier.
    • name is mandatory and must be unique.
    • if the first profile is added, it is automatically set as the active profile.
    object allOf
    uid: addProfileMsg
    • #profile
  • #164update_profile

    🧪 Update a profile.

    Update one or multiple properties of a profile. A missing property will not update its current value.

    • profile_id is mandatory and can't be changed.
    • an empty icon value removes an existing icon identifier.
    • a missing pages property will not change the page order.
    • ⚠️ an empty pages array removes all pages and groups in the profile!
    • ⚠️ missing page identifiers in the pages array will remove the page configuration!
    object allOf
    uid: updateProfileMsg
    • #profile
  • #165delete_profile

    🧪 Delete the specified profile.

    All profile related pages and groups are also deleted.

    object allOf
    uid: deleteProfileMsg
    • #profile
  • #166delete_all_profiles

    🧪 Delete all profiles.

    This also deletes all pages and groups.

    object allOf
    uid: deleteAllProfilesMsg
    • #profile
  • #167active_profile_change

    🧪 Active profile change event.

    Emitted if the active profile changed.

    object allOf
    uid: activeProfileChangeEventMsg
    • #profile
    • #event
  • #168profile_change

    🧪 Profile change event.

    Emitted if a profile configuration, related profile page or group has been changed, added or deleted.

    object allOf
    uid: profileChangeEventMsg
    • #profile
    • #event
  • #169get_pages

    🧪 Retrieve all UI pages of a profile.

    object allOf
    uid: getPagesMsg
    • #profile
  • #170pages

    🧪 List of defined UI pages response.

    object allOf
    uid: pagesMsg
    • #profile
  • #171get_page

    🧪 Retrieve the specified UI page.

    object allOf
    uid: getPageMsg
    • #profile
  • #172page

    🧪 UI page data response.

    object allOf
    uid: pageMsg
    • #profile
  • #173add_page

    🧪 Create a new UI page and add to profile.

    • profile_id is mandatory.
    • page_id is not required and is created automatically.
    • name is mandatory and must be unique within the profile.
    object allOf
    uid: addPageMsg
    • #profile
  • #174update_page

    🧪 Update a UI page.

    • profile_id and page_id are mandatory.
    object allOf
    uid: updatePageMsg
    • #profile
  • #175delete_page

    🧪 Delete a UI page.

    object allOf
    uid: deletePageMsg
    • #profile
  • #176delete_pages_in_profile

    🧪 Delete all pages of a profile

    object allOf
    uid: deletePagesInProfileMsg
    • #profile
  • #177get_groups

    🧪 Retrieve all UI groups of a profile.

    object allOf
    uid: getGroupsMsg
    • #profile
  • #178groups

    🧪 List of defined UI groups response.

    object allOf
    uid: groupsMsg
    • #profile
  • #179get_group

    🧪 Retrieve the specified UI group.

    object allOf
    uid: getGroupMsg
    • #profile
  • #180group

    🧪 UI group data response.

    object allOf
    uid: groupMsg
    • #profile
  • #181add_group

    🧪 Create a new UI group and add to profile.

    • profile_id is mandatory.
    • group_id is not required and is created automatically.
    • name is mandatory and must be unique within the profile.
    object allOf
    uid: addGroupMsg
    • #profile
  • #182update_group

    🧪 Update a UI group.

    • profile_id and group_id are mandatory.
    object allOf
    uid: updateGroupMsg
    • #profile
  • #183delete_group

    🧪 Delete a UI group.

    object allOf
    uid: deleteGroupMsg
    • #profile
  • #184delete_groups_in_profile

    🧪 Delete all groups in a profile.

    object allOf
    uid: deleteGroupsInProfileMsg
    • #profile
  • #185get_integration_status

    🧪 Retrieve an overview of the integration instances and their current connection state.

    object allOf
    uid: getIntegrationStatusMsg
    • #integration
  • #186integration_status

    🧪 Summary information of the integration instances.

    object allOf
    uid: integrationStatusMsg
    • #integration
  • #187integration_cmd

    🧪 Execute an integration command.

    Connect or disconnect integration instances.

    If integration_id is specified, then the command only applies to the given integration, otherwise to all integration instances.

    object allOf
    uid: integrationCmdMsg
    • #integration
  • #188integration_driver_cmd

    🧪 Execute an integration driver command.

    Start or stop integration drivers.

    If driver_id is specified, then the command only applies to the given driver, otherwise to all integration drivers.

    object allOf
    uid: integrationDriverCmdMsg
    • #integration
  • #189get_integration_driver_count

    🧪 Get total number of registered integration drivers.

    object allOf
    uid: getIntegrationDriverCountMsg
    • #integration
  • #190integration_driver_count

    🧪 Total number of registered integration drivers response.

    object allOf
    uid: integrationDriverCountMsg
    • #integration
  • #191get_integration_drivers

    🧪 Retrieve all registered integration drivers.

    object allOf
    uid: getIntegrationDriversMsg
    • #integration
  • #192integration_drivers

    🧪 List of registered integration drivers response.

    object allOf
    uid: integrationDriversMsg
    • #integration
  • #193register_integration_driver

    🧪 Register a new integration driver.

    object allOf
    uid: registerIntegrationDriverMsg
    • #integration
  • #194get_integration_driver

    🧪 Retrieve detail information of an integration driver.

    object allOf
    uid: getIntegrationDriverMsg
    • #integration
  • #195integration_driver

    🧪 Detail information of an integration driver response.

    object allOf
    uid: integrationDriverMsg
    • #integration
  • #196update_integration_driver

    🧪 Modify a configured integration driver.

    object allOf
    uid: updateIntegrationDriverMsg
    • #integration
  • #197delete_integration_driver

    🧪 Remove an integration driver.

    Unloads and deletes an integration driver with all instances and provided entities.

    Attention: all references to the integration driver will be removed! This includes all driver instances, provided entities and their references in profile pages and groups.

    object allOf
    uid: deleteIntegrationDriverMsg
    • #integration
  • #198get_integration_count

    🧪 Get total number of integration instances.

    object allOf
    uid: getIntegrationCountMsg
    • #integration
  • #199integration_count

    🧪 Total number of integration instances response.

    object allOf
    uid: integrationCountMsg
    • #integration
  • #200get_integrations

    🧪 Retrieve all loaded integrations.

    Returns all integration instances, optionally filtered by type or enabled state.

    object allOf
    uid: getIntegrationsMsg
    • #integration
  • #201integrations

    🧪 List of loaded integrations response.

    object allOf
    uid: integrationsMsg
    • #integration
  • #202create_integration

    🧪 Create a new integration instance from driver.

    Create an integration driver instance and associate it with the driver. For simple integration drivers there's a 1:1 relationship only between an instance and driver. For multi-device drivers, each device corresponds to an integration instance.

    • the integration_id is automatically created by the system to make it unique over all integrations.
    • for multi-device drivers the device_id must be specified and may not already exist in another instance of the same driver.
    • the driver's name is used by default if name isn't specified.
    • the instance is active by default if enabled isn't specified.
    object allOf
    uid: createIntegrationMsg
    • #integration
  • #203integration

    🧪 Integration instance information response.

    object allOf
    uid: integrationMsg
    • #integration
  • #204get_integration

    🧪 Get an integration instance.

    object allOf
    uid: getIntegrationMsg
    • #integration
  • #205update_integration

    🧪 Modify a configured integration instance.

    Modify one or several properties of an integration instance.
    See update model description on how to update or delete an existing property.

    The integration driver of an instance cannot be changed and will be ignored if provided in the request.

    object allOf
    uid: updateIntegrationMsg
    • #integration
  • #206delete_integration

    🧪 Remove an integration instance.

    Unloads and deletes an integration instance.

    Attention: all references to the integration instance will be removed! This includes configured entities and their references in profile pages and groups.

    object allOf
    uid: deleteIntegrationMsg
    • #integration
  • #207configure_entity_from_integration

    🧪 Configure an available entity.

    Configure a new UC Remote entity from an available integration entity. Once configured, the entity will no longer show up as available entity (unless the all filter is set).

    The entity name, icon and description fields may be changed. If not specified in the request the values from the available entity are used.

    In case of an error the default result message is returned with an error code.

    object allOf
    uid: configureEntityFromIntegrationMsg
    • #integration
  • #208configure_entities_from_integration

    🧪 Configure multiple available entities.

    Configure multiple new UC Remote entities from available integration entities. Once configured, the entities will no longer show up as an available entity (unless the filter=ALL query parameter is set).

    If entity_ids is not provided or is empty, all entities from the integration are configured.

    Use message configure_entity_from_integration to configure a single entity and optionally rename it or change its icon.

    This is a best effort operation:

    • if an entity is already configured, it is ignored and not returned in the response.
    • unknown entity identifiers are ignored, no error is returned.

    Every newly configured entity will trigger an entity_change event.

    object allOf
    uid: configureEntitiesFromIntegrationMsg
    • #integration
  • #209get_integration_discovery_status

    🧪 Get external integration driver discovery status.

    Returns the current discovery status and the discovered integration drivers.

    Use start_integration_discovery to clear old results and start a new discovery.

    object allOf
    uid: getIntegrationDiscoveryStatusMsg
    • #integration
  • #210integration_discovery_status

    🧪 External integration driver discovery status response.

    object allOf
    uid: integrationDiscoveryStatusMsg
    • #integration
  • #211start_integration_discovery

    🧪 Start discovery of external integration drivers.

    Start integration driver discovery on the network with mDNS. By default the discovery automatically stops after 30 seconds. Use the get_integration_discovery_status request to check on discovered devices or stop_integration_discovery to stop discovery.

    By default only new integration drivers are returned. If a driver is already configured it will be omitted from the results, unless the query parameter new=false is set.

    • Previously discovered integrations are removed, only newly discovered integrations will be returned.
    • Emits the WebSocket event integration_discovery with event_type: START when discovery starts.
    • For each discovered driver the WebSocket event integration_discovery with event_type: DISCOVER is emitted.
    object allOf
    uid: startIntegrationDiscoveryMsg
    • #integration
  • #212stop_integration_discovery

    🧪 Stop discovery of external integration drivers.

    Stops the driver discovery and returns the current discovery status in the response.

    Emits the WebSocket event integration_discovery with event_type: STOP.

    object allOf
    uid: stopIntegrationDiscoveryMsg
    • #integration
  • #213get_discovered_integration_driver

    🧪 Get integration driver discovery information.

    Returns the discovered integration driver.

    object allOf
    uid: getDiscoveredIntegrationDriverMsg
    • #integration
  • #214discovered_integration_driver

    🧪 Integration driver discovery information.

    object allOf
    uid: discoveredIntegrationDriverMsg
    • #integration
  • #215get_discovered_intg_driver_metadata

    👷 Execute connection test and fetch metadata from discovered integration driver.

    Perform a driver connection test with a discovered driver. If the driver requires a token, it must be specified in the request data.

    Response status codes:

    • 200: successful operation: the connection test was successful and driver metadata could be retrieved.
    • 404: discovered driver with driver_id not found. Check if the discovery result is still available and has not been deleted. This can happen after a timeout since the discovery, or if the discovery result has been cleared with starting a new discovery.
    • 503: integration driver connection could not be established.
    object allOf
    uid: getDiscoveredIntgDriverMetadataMsg
    • #integration
  • #216configure_discovered_integration_driver

    🧪 Register a discovered integration driver.

    Register a discovered integration driver:

    • establish communication with the driver.
      • if the driver requires a password, it must be provided in the request.
      • the discovered driver name and url can be overridden.
    • fetch metadata from the driver.
    • check compatability.
    • register the driver and connection parameters in the remote.

    After a successful registration the setup process of the driver can be started to configure the integration. The required setup data is described in the returned setup_data_schema and the provided values by the user must be passed to the setup_integration request.

    Response status codes:

    • 400: invalid data in request body.
    • 404: no discovered driver found for given driver_id.
    • 409: integration driver is already registered.
    • 503: integration driver communication error. Either driver is not reachable or communication failed.
    object allOf
    uid: configureDiscoveredIntegrationDriverMsg
    • #integration
  • #217get_integration_setup_processes

    🧪 Get current integration setup processes.

    Return a list of all active setup process identifiers. The returned ids can be used with the set_integration_user_data and stop_integration_setup messages to continue or abort a setup process.

    object allOf
    uid: getIntegrationSetupProcessesMsg
    • #integration
  • #218integration_setup_processes

    🧪 Current integration setup processes response.

    Return a list of all active setup process identifiers.

    object allOf
    uid: integrationSetupProcessesMsg
    • #integration
  • #219setup_integration

    🧪 Start setting up a new integration driver.

    Start a new setup process for the given integration driver and provided setup data, or reconfigure an existing driver.

    • This operation immediately starts the driver communication and setup process.
    • There may only be one active setup process per driver, otherwise status code 409 is returned.

    The returned id in the IntegrationSetupInfo response will be the identifier for the further setup operations with the set_integration_user_data and stop_integration_setup requests. Once the setup process is successfully finished, an integration instance is created. A setup process can be simple and fully automatic, but may also require user interaction and further communication with the set_integration_user_data message.

    Emits the WebSocket event integration_setup_change with event_type: START.

    Request body:

    • name: optional integration name. If not specified the name of the integration driver is used.
    • setup_data: optional driver setting values corresponding to the driver's setup_data_schema object.
    • reconfigure: set to true to reconfigure an already configured driver. The configuration options and behaviour is driver dependent.

    Response status codes:

    • 400: invalid data in request body. E.g. setting the reconfigure flag for a new driver which is not yet configured.
    • 404: specified driver_id in request body does not exist.
    • 409: a setup process for the given driver_id already exists. Either continue or abort existing process.
    • 422: the setup process cannot be used: either the integration is already configured or doesn't allow to be set up again.
    • 503: integration driver communication error. Either driver is not reachable or communication failed.
    object allOf
    uid: setupIntegrationMsg
    • #integration
  • #220integration_setup_info

    🧪 Integration setup information response.

    object allOf
    uid: integrationSetupInfoMsg
    • #integration
  • #221stop_all_integration_setups

    🧪 Abort and remove all setup processes.

    Stop all setup processes at the next possible operation and remove all setup process information.
    Depending on the integration driver, a started setup process cannot be aborted.

    ⚠️ This stops all setup processes, not just for the current session!

    object allOf
    uid: stopAllIntegrationSetupsMsg
    • #integration
  • #222get_integration_setup_status

    🧪 Get integration driver setup status.

    Poll operation to retrieve the current integration driver setup state. See the state and error fields in the response message. There are also WebSocket integration_setup_change event messages for state changes to avoid polling.

    Defined setup states:

    • SETUP: setup is running and configuring the integration.
    • WAIT_USER_ACTION: user input is required to continue the setup process. See require_user_action in response for the required user input. Provide the requested data with the PUT operation.
    • OK: setup process has been completed successfully, the integration driver can now be used.
    • ERROR: the setup process failed. Check the error field for more information.
    object allOf
    uid: getIntegrationSetupStatusMsg
    • #integration
  • #223set_integration_user_data

    🧪 Provide requested integration setup data.

    Set required data to configure the integration driver or continue the setup process.

    Defined user actions to set in the request body action field:

    • input_values: if the user was requested to enter settings, e.g. connection or credential parameters to a device or service.
    • confirm: response to the user action confirmation. Set to true if the user had to perform an action like pressing a button on a device and then confirms the action with continuing the setup process.
      The false value is prepared for yes / no choices.

    The state field in the response message indicate the current state of the setup process. Use the get_integration_setup_status message to poll for state updates or listen to the corresponding WebSocket integration_setup_change event messages with event_type: SETUP.

    object allOf
    uid: setIntegrationUserDataMsg
    • #integration
  • #224stop_integration_setup

    🧪 Abort the integration driver setup process.

    Stop the setup process at the next possible operation and remove the setup process information.
    To start a new setup process, use the setup_integration request again.

    Depending on the integration driver, a started setup process cannot be aborted.

    Emits the WebSocket event integration_setup_change with event_type: STOP.

    object allOf
    uid: stopIntegrationSetupMsg
    • #integration
  • #225get_event_channels

    🧪 Retrieve available event channels for the current session.

    Depending on the security role not all event subscriptions may be available.

    object allOf
    uid: getEventChannelsMsg
    • #event
  • #226event_channels

    🧪 Available subscriptions for the current session.

    Returns all subscribed event channels.

    object allOf
    uid: eventChannelsMsg
    • #event
  • #227subscribe_events

    🧪 Subscribe to event channels.

    Subscribe to one or multiple event channels.

    • The special all channel will deliver all available events and clear all other subscriptions for the session.
    • If the session is already subscribed to the all channel, any other channels are ignored.
    • The special entities channel will deliver all entity and activity-group related events. This includes all entity-type channels (entity_###) and the activity_group channel.
    • Depending on the security role not all event subscriptions may be available.
    object allOf
    uid: subscribeEventsMsg
    • #event
  • #228get_event_subscriptions

    🧪 Retrieve the active event channel subscriptions.

    object allOf
    uid: getEventSubscriptionsMsg
    • #event
  • #229unsubscribe_events

    🧪 Unsubscribe from event channels.

    object allOf
    uid: unsubscribeEventsMsg
    • #event
  • #230event_subscriptions

    🧪 Event channel subscription status.

    Response to subscribe_events, unsubscribe_events and get_event_subscriptions.

    object allOf
    uid: eventSubscriptionsMsg
    • #event
  • #231warning

    🔍 System warning event.

    Emitted for important system events like low battery or shutdown events.

    object allOf
    uid: warningEventMsg
    • #event
  • #232integration_driver_change

    🧪 Integration driver change event.

    Emitted if an integration driver has changed, a new driver has been added or a configured driver has been deleted.

    object allOf
    uid: integrationDriverChangeEventMsg
    • #integration
    • #event
  • #233integration_change

    🧪 Integration change event.

    Emitted if an integration instance has changed, a new instance has been added or a configured instance has been deleted.

    object allOf
    uid: integrationChangeEventMsg
    • #integration
    • #event
  • #234integration_state

    🧪 Integration state event.

    Emitted if the connection state of an integration driver or instance has changed.

    object allOf
    uid: integrationStateEventMsg
    • #integration
    • #event
  • #235configuration_change

    🧪 System configuration change event.

    Emitted if a system setting has changed.

    The msg_data.new_state object only contains the configuration object of the setting that has changed and not the full system configuration.

    object allOf
    uid: configurationChangeEventMsg
    • #event
  • #236ir_learning

    🧪 IR code learn event.

    Emitted if learning mode is started, stopped or a new IR code was learned from an IR emitter device.

    object allOf
    uid: irLearningEventMsg
    • #event
  • #237dock_change

    🧪 Dock change event.

    Emitted if a dock configuration has changed.

    object allOf
    uid: dockChangeEventMsg
    • #event
  • #238dock_state

    🧪 Dock state event.

    Emitted if the connection state of a dock has changed.

    object allOf
    uid: dockStateEventMsg
    • #event
  • #239dock_port_mode

    🧪 Dock port mode change event.

    Emitted if the external port mode of a dock has changed.

    object allOf
    uid: dockPortModeEventMsg
    • #event
  • #240dock_discovery

    🧪 Docking station discovery event.

    Emitted if dock discovery is started, stopped or a new dock was discovered on the network or via Bluetooth.

    object allOf
    uid: dockDiscoveryEventMsg
    • #event
  • #241dock_setup_change

    🧪 Docking station setup state change event.

    Emitted for all dock setup flow state changes.

    object allOf
    uid: dockSetupChangeEventMsg
    • #event
  • #242dock_update_change

    🧪 Docking station firmware update change event.

    Emitted for firmware update and progress state changes.

    object allOf
    uid: dockUpdateChangeEventMsg
    • #event
  • #243integration_discovery

    🧪 Integration discovery event.

    Emitted if integration discovery is started, stopped or a new integration was discovered on the network.

    object allOf
    uid: integrationDiscoveryEventMsg
    • #event
  • #244integration_setup_change

    🧪 Integration setup state change event.

    Emitted for all integration setup flow state changes.

    object allOf
    uid: integrationSetupChangeEventMsg
    • #event
  • #245software_update

    🧪 Software update event.

    Emitted during a system update to receive start, stop and progress events.

    object allOf
    uid: softwareUpdateEventMsg
    • #event
  • #246power_mode_change

    🧪 Power mode change event.

    Emitted when the power saving mode changes.

    object allOf
    uid: powerModeChangeEventMsg
    • #event
  • #247battery_status

    🧪 Battery status event.

    Emitted when the battery status changes.

    object allOf
    uid: batteryStatusEventMsg
    • #event
  • #248ambient_light_change

    🔍 Ambient light change event.

    Emitted when the ambient light changes during normal power mode.

    object allOf
    uid: ambientLightChangeEventMsg
    • #event
  • #249assistant_event

    🔍 Assistant event.

    The assistant_event message must be emitted by the integration driver to start the audio stream and for providing optional feedback about the voice command processing and outcome.

    object allOf
    uid: assistantEventMsg
    • #event

Schemas

  • object
    uid: commonReq

    Common request message properties.

  • object
    uid: commonResp

    Common response message properties.

  • object
    uid: commonEvent

    Common event message properties.

  • object allOf
    uid: authRequiredEvent
  • object allOf
    uid: authRequestMsg
  • object allOf
    uid: authMsg
  • object allOf
    uid: versionMsg
  • object allOf
    uid: versionInfoMsg
  • object allOf
    uid: systemCmdMsg
  • object allOf
    uid: getSystemInfoMsg
  • object allOf
    uid: systemInfoMsg
  • object allOf
    uid: getFactoryResetTokenMsg
  • object allOf
    uid: factoryResetTokenMsg
  • object allOf
    uid: factoryResetMsg
  • object allOf
    uid: setApiAccessMsg
  • object allOf
    uid: getApiAccessMsg
  • object allOf
    uid: apiAccessMsg
  • object allOf
    uid: checkSystemUpdateMsg
  • object allOf
    uid: systemUpdateInfoMsg
  • object allOf
    uid: updateSystemMsg
  • object allOf
    uid: updateSystemResultMsg
  • object allOf
    uid: getSystemUpdateProgressMsg
  • object allOf
    uid: systemUpdateProgressMsg
  • object allOf
    uid: getPowerModeMsg
  • object allOf
    uid: powerModeMsg
  • object allOf
    uid: setPowerModeMsg
  • object allOf
    uid: getBatteryChargerMsg
  • object allOf
    uid: batteryChargerMsg
  • object allOf
    uid: updateBatteryChargerMsg
  • object allOf
    uid: getStandbyInhibitorsMsg
  • object allOf
    uid: inhibitorsMsg
  • object allOf
    uid: createStandbyInhibitorMsg
  • object allOf
    uid: inhibitorMsg
  • object allOf
    uid: delStandbyInhibitorMsg
  • object allOf
    uid: delAllStandbyInhibitorsMsg
  • object allOf
    uid: getAmbientLightMsg
  • object allOf
    uid: ambientLightMsg
  • object allOf
    uid: resetConfigurationMsg
  • object allOf
    uid: getConfigurationMsg
  • object allOf
    uid: configurationMsg
  • object allOf
    uid: getButtonCfgMsg
  • object allOf
    uid: setButtonCfgMsg
  • object allOf
    uid: buttonCfgMsg
  • object allOf
    uid: getDeviceCfgMsg
  • object allOf
    uid: setDeviceCfgMsg
  • object allOf
    uid: deviceCfgMsg
  • object allOf
    uid: getDisplayCfgMsg
  • object allOf
    uid: setDisplayCfgMsg
  • object allOf
    uid: displayCfgMsg
  • object allOf
    uid: getFeaturesCfgMsg
  • object allOf
    uid: setFeaturesCfgMsg
  • object allOf
    uid: featuresCfgMsg
  • object allOf
    uid: getHapticCfgMsg
  • object allOf
    uid: setHapticCfgMsg
  • object allOf
    uid: hapticCfgMsg
  • object allOf
    uid: getLocalizationCfgMsg
  • object allOf
    uid: setLocalizationCfgMsg
  • object allOf
    uid: localizationCfgMsg
  • object allOf
    uid: getTimezoneNamesMsg
  • object allOf
    uid: timezoneNamesMsg
  • object allOf
    uid: getLocalizationCountriesMsg
  • object allOf
    uid: localizationCountriesMsg
  • object allOf
    uid: getLocalizationLanguagesMsg
  • object allOf
    uid: localizationLanguagesMsg
  • object allOf
    uid: getNetworkCfgMsg
  • object allOf
    uid: setNetworkCfgMsg
  • object allOf
    uid: resetNetworkCfgMsg
  • object allOf
    uid: networkCfgMsg
  • object allOf
    uid: getSoftwareUpdateCfgMsg
  • object allOf
    uid: setSoftwareUpdateCfgMsg
  • object allOf
    uid: resetSoftwareUpdateCfgMsg
  • object allOf
    uid: softwareUpdateCfgMsg
  • object allOf
    uid: getPowerSavingCfgMsg
  • object allOf
    uid: setPowerSavingCfgMsg
  • object allOf
    uid: powerSavingCfgMsg
  • object allOf
    uid: getProfileCfgMsg
  • object allOf
    uid: setProfileCfgMsg
  • object allOf
    uid: profileCfgMsg
  • object allOf
    uid: getSoundCfgMsg
  • object allOf
    uid: setSoundCfgMsg
  • object allOf
    uid: soundCfgMsg
  • object allOf
    uid: getVoiceControlCfgMsg
  • object allOf
    uid: setVoiceControlCfgMsg
  • object allOf
    uid: voiceControlCfgMsg
  • object allOf
    uid: getVoiceAssistantsMsg
  • object allOf
    uid: voiceAssistantsMsg
  • object allOf
    uid: getEntityTypesMsg
  • object allOf
    uid: entityTypesMsg
  • object allOf
    uid: getEntityMsg
  • object allOf
    uid: getEntitiesMsg
  • object allOf
    uid: entitiesMsg
  • object allOf
    uid: getAvailableEntitiesMsg

    Retrieve the available entities provided by the integration instance.

  • object allOf
    uid: availableEntitiesMsg
  • object allOf
    uid: getEntityCommandsMsg
  • object allOf
    uid: entityCommandsMsg
  • object allOf
    uid: getEntityCommandMetadataMsg
  • object allOf
    uid: entityCommandMetadataMsg
  • object allOf
    uid: executeEntityCommandMsg
  • object allOf
    uid: entityMsg
  • object allOf
    uid: entityChangeEventMsg
  • object allOf
    uid: activityGroupChangeEventMsg
  • object allOf
    uid: updateEntityMsg
  • object allOf
    uid: deleteEntityMsg
  • object allOf
    uid: deleteEntitiesMsg
  • object allOf
    uid: getDockCountMsg
  • object allOf
    uid: dockCountMsg
  • object allOf
    uid: getDocksMsg
  • object allOf
    uid: docksMsg
  • object allOf
    uid: createDockMsg
  • object allOf
    uid: dockMsg
  • object allOf
    uid: deleteAllDocksMsg
  • object allOf
    uid: getDockMsg
  • object allOf
    uid: updateDockMsg
  • object allOf
    uid: dockConnectionCommandMsg
  • object allOf
    uid: deleteDockMsg
  • object allOf
    uid: dockCommandMsg
  • object allOf
    uid: getDockDiscoveryStatusMsg
  • object allOf
    uid: dockDiscoveryStatusMsg
  • object allOf
    uid: startDockDiscoveryMsg
  • object allOf
    uid: stopDockDiscoveryMsg
  • object allOf
    uid: getDockDiscoveryDeviceMsg
  • object allOf
    uid: dockDiscoveryDeviceMsg
  • object allOf
    uid: execCmdOnDiscoveredDockMsg
  • object allOf
    uid: dockSystemInfoMsg
  • object allOf
    uid: getDockSetupProcessesMsg
  • object allOf
    uid: dockSetupProcessesMsg
  • object allOf
    uid: createDockSetupMsg
  • object allOf
    uid: dockSetupStatusMsg
  • object allOf
    uid: stopAllDockSetupsMsg
  • object allOf
    uid: getDockSetupStatusMsg
  • object allOf
    uid: startDockSetupMsg
  • object allOf
    uid: stopDockSetupMsg
  • object allOf
    uid: wifiGetStatusMsg
  • object allOf
    uid: wifiStatusMsg
  • object allOf
    uid: wifiCommandMsg
  • object allOf
    uid: wifiScanStartMsg
  • object allOf
    uid: wifiScanStopMsg
  • object allOf
    uid: wifiGetScanStatusMsg
  • object allOf
    uid: wifiScanStatusMsg
  • object allOf
    uid: wifiGetAllNetworksMsg
  • object allOf
    uid: wifiNetworksMsg
  • object allOf
    uid: wifiAddNetworkMsg
  • object allOf
    uid: wifiDelAllNetworksMsg
  • object allOf
    uid: wifiGetNetworkMsg
  • object allOf
    uid: wifiNetworkMsg
  • object allOf
    uid: wifiUpdateNetworkMsg
  • object allOf
    uid: wifiNetworkCommandMsg
  • object allOf
    uid: wifiDelNetworkMsg
  • object allOf
    uid: wifiChangeEventMsg
  • object allOf
    uid: btPairingStartedEventMsg
  • object allOf
    uid: btPairingAuthRequestEventMsg
  • object allOf
    uid: btPairingCompleteEventMsg
  • object allOf
    uid: btPairingResponseMsg
  • object allOf
    uid: getProfilesMsg
  • object allOf
    uid: profilesMsg
  • object allOf
    uid: getProfileMsg
  • object allOf
    uid: profileMsg
  • object allOf
    uid: getActiveProfileMsg
  • object allOf
    uid: switchProfileMsg
  • object allOf
    uid: addProfileMsg
  • object allOf
    uid: updateProfileMsg
  • object allOf
    uid: deleteProfileMsg
  • object allOf
    uid: deleteAllProfilesMsg
  • object allOf
    uid: activeProfileChangeEventMsg
  • object allOf
    uid: profileChangeEventMsg
  • object allOf
    uid: getPagesMsg
  • object allOf
    uid: pagesMsg
  • object allOf
    uid: getPageMsg
  • object allOf
    uid: pageMsg
  • object allOf
    uid: addPageMsg
  • object allOf
    uid: updatePageMsg
  • object allOf
    uid: deletePageMsg
  • object allOf
    uid: deletePagesInProfileMsg
  • object allOf
    uid: getGroupsMsg
  • object allOf
    uid: groupsMsg
  • object allOf
    uid: getGroupMsg
  • object allOf
    uid: groupMsg
  • object allOf
    uid: addGroupMsg
  • object allOf
    uid: updateGroupMsg
  • object allOf
    uid: deleteGroupMsg
  • object allOf
    uid: deleteGroupsInProfileMsg
  • object allOf
    uid: getIntegrationStatusMsg
  • object allOf
    uid: integrationStatusMsg
  • object allOf
    uid: integrationCmdMsg
  • object allOf
    uid: integrationDriverCmdMsg
  • object allOf
    uid: getIntegrationDriverCountMsg
  • object allOf
    uid: integrationDriverCountMsg
  • object allOf
    uid: getIntegrationDriversMsg
  • object allOf
    uid: integrationDriversMsg
  • object allOf
    uid: registerIntegrationDriverMsg
  • object allOf
    uid: getIntegrationDriverMsg
  • object allOf
    uid: integrationDriverMsg
  • object allOf
    uid: updateIntegrationDriverMsg
  • object allOf
    uid: deleteIntegrationDriverMsg
  • object allOf
    uid: getIntegrationCountMsg
  • object allOf
    uid: integrationCountMsg
  • object allOf
    uid: getIntegrationsMsg
  • object allOf
    uid: integrationsMsg
  • object allOf
    uid: createIntegrationMsg
  • object allOf
    uid: integrationMsg
  • object allOf
    uid: getIntegrationMsg
  • object allOf
    uid: updateIntegrationMsg
  • object allOf
    uid: deleteIntegrationMsg
  • object allOf
    uid: configureEntityFromIntegrationMsg
  • object allOf
    uid: configureEntitiesFromIntegrationMsg
  • object allOf
    uid: getIntegrationDiscoveryStatusMsg
  • object allOf
    uid: integrationDiscoveryStatusMsg
  • object allOf
    uid: startIntegrationDiscoveryMsg
  • object allOf
    uid: stopIntegrationDiscoveryMsg
  • object allOf
    uid: getDiscoveredIntegrationDriverMsg
  • object allOf
    uid: discoveredIntegrationDriverMsg
  • object allOf
    uid: getDiscoveredIntgDriverMetadataMsg
  • object allOf
    uid: configureDiscoveredIntegrationDriverMsg
  • object allOf
    uid: getIntegrationSetupProcessesMsg
  • object allOf
    uid: integrationSetupProcessesMsg
  • object allOf
    uid: setupIntegrationMsg
  • object allOf
    uid: integrationSetupInfoMsg
  • object allOf
    uid: stopAllIntegrationSetupsMsg
  • object allOf
    uid: getIntegrationSetupStatusMsg
  • object allOf
    uid: setIntegrationUserDataMsg
  • object allOf
    uid: stopIntegrationSetupMsg
  • object allOf
    uid: getEventChannelsMsg
  • object allOf
    uid: eventChannelsMsg
  • object allOf
    uid: subscribeEventsMsg
  • object allOf
    uid: getEventSubscriptionsMsg
  • object allOf
    uid: unsubscribeEventsMsg
  • object allOf
    uid: eventSubscriptionsMsg
  • string anyOf
    uid: eventChannel

    The name of the event channel.

  • object allOf
    uid: warningEventMsg
  • object allOf
    uid: integrationDriverChangeEventMsg
  • object allOf
    uid: integrationChangeEventMsg
  • object allOf
    uid: integrationStateEventMsg
  • object allOf
    uid: configurationChangeEventMsg
  • object allOf
    uid: irLearningEventMsg
  • object allOf
    uid: dockChangeEventMsg
  • object allOf
    uid: dockStateEventMsg
  • object allOf
    uid: dockPortModeEventMsg
  • object allOf
    uid: dockDiscoveryEventMsg
  • object allOf
    uid: dockSetupChangeEventMsg
  • object allOf
    uid: dockUpdateChangeEventMsg
  • object allOf
    uid: integrationDiscoveryEventMsg
  • object allOf
    uid: integrationSetupChangeEventMsg
  • object allOf
    uid: softwareUpdateEventMsg
  • object allOf
    uid: powerModeChangeEventMsg
  • object allOf
    uid: batteryStatusEventMsg
  • object allOf
    uid: ambientLightChangeEventMsg
  • object allOf
    uid: assistantEventMsg
  • object
    uid: error
  • object allOf
    uid: ping
  • object allOf
    uid: pong
  • object allOf
    uid: warningEvent
  • msgId
    integer
    >= 0uid: msgId

    Request message ID which is reflected in response message.

    Default value:0
  • object
    uid: paging

    Paging information for returned items.

  • object
    uid: pagination

    Returned pagination information.

  • object
    uid: versionInfo
  • object
    uid: systemInfo
  • object
    uid: enabledFilter

    Simple filter by enabled flag.

  • object
    uid: intgDriverFilter

    Filter for integration drivers.

  • object
    uid: availableEntityFilter

    Optional filters

  • availEntitiesFilter
    string
    uid: availEntitiesFilter

    Filter available entities

      Allowed values:
    • "NEW"
    • "CONFIGURED"
    • "ALL"
  • object
    uid: entityFilter

    Optional filters

  • object
    uid: entity

    Configured entity in the remote to be used in one or more profiles.

    See entity documentation for more information.

  • object
    uid: entityUpdate

    Entity update data.

    If used in an update operation:

    • Omitted properties will not change the configured value.
    • An empty icon value will remove the icon identifier.
    • entity_id, entity_type and integration_id cannot be changed.

    If returned in an entity_change event:

    • Additional properties from the regular entity object might be included as well.
  • object
    uid: available_entity

    Provided entity from an integration which can be configured to be used in the remote.

    See entity documentation for more information.

    If no icon identifier is specified, the default icon for the entity type is used.

  • array<string>
    uid: entityFeatures
  • entityFeature
    string
    uid: entityFeature
  • entityCommand
    string
    uid: entityCommand

    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.

  • entityType
    string
    uid: entityType

    Entity type.

      Allowed values:
    • "button"
    • "climate"
    • "cover"
    • "light"
    • "media_player"
    • "sensor"
    • "switch"
    • "activity"
    • "macro"
    • "remote"
    • "ir_emitter"
    • "voice_assistant"
  • object
    uid: ActivityGroup

    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.

  • object
    uid: IncludedActivity

    Minimal activity object to show the activity in a user interface with it's friendly name and icon.

  • SequenceState
    string
    uid: SequenceState

    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
      Allowed values:
    • "RUNNING"
    • "COMPLETED"
    • "ON"
    • "OFF"
    • "STOPPED"
    • "TIMEOUT"
    • "ERROR"
  • object
    uid: ActivityGroupOptions

    Activity group specific options, e.g. how delays are handled when switching between activities.

  • languageCode
    string
    must match: ^[a-z]{2}(_\w+)?$uid: languageCode

    Language culture code: starting with the two-letter ISO-639-1 code, followed by an optional ISO-3166 country code, separated by an underscore. Examples: en, en_UK, en_US, de, de_DE, de_CH etc.

  • countryCode
    string
    format: iso-3166uid: countryCode

    Two letter country code according to ISO-3166-1-alpha-2.

  • object
    uid: languageText

    Display text in the UI. An english text should always be provided as fallback option.

  • object
    uid: getConfigurationOptions

    Optional request parameters.

  • object
    uid: configuration
  • object
    uid: cfgButton
  • object
    uid: cfgButtonUpdate

    Button configuration model to update settings. Missing properties are not changed.

  • object
    uid: staticButtonColor

    Static color settings for all zones, if supported by the device.

  • object
    uid: cfgDevice
  • object
    uid: cfgDisplay
  • array<object>
    uid: cfgFeatures
  • object
    uid: cfgFeature
  • object
    uid: cfgFeatureUpdate
  • object
    uid: cfgHaptic
  • object
    uid: cfgLocalization
  • measurementUnit
    string
    uid: measurementUnit
      Allowed values:
    • "METRIC"
    • "US"
    • "UK"
  • object
    uid: cfgNetwork

    wake_on_wlan is deprecated, please use wifi.wake_on_wlan

  • object
    uid: cfgNetworkUpdate

    wake_on_wlan is deprecated, please use wifi.wake_on_wlan

  • object
    uid: cfgNetworkWs

    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!

  • object
    uid: cfgNetworkWoWlan

    Wake on WLAN settings

  • object
    uid: CfgNetworkWifi
  • object
    uid: CfgNetworkWifiUpdate
  • WifiScanInterval
    integer
    >= 0uid: WifiScanInterval

    Active WiFi scan interval in seconds. A value of 0 disables active scanning. Minimal interval is 10 seconds.

  • CfgIpv4Type
    string
    uid: CfgIpv4Type
      Allowed values:
    • "DHCP"
  • object
    uid: CfgIpv4
  • object
    uid: cfgPowerSaving
  • object
    uid: cfgProfile
  • object
    uid: cfgProfileUpdate
  • object
    uid: cfgSoftwareUpdate
  • object
    uid: cfgSound
  • object
    uid: CfgVoiceControl

    Voice control settings with enriched voice assistant configuration. No voice assistant is enabled if the voice_assistant.active object is missing.

  • object
    uid: CfgVoiceAssistant

    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.

  • object
    uid: CfgVoiceControlUpdate

    Update object for voice control settings. A missing field will keep the old value.

  • object
    uid: CfgVoiceAssistantUpdate

    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.

  • array<object>
    uid: VoiceAssistants
  • object
    uid: VoiceAssistant

    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.
  • array<string>
    uid: VoiceAssistantFeatures
  • VoiceAssistantFeature
    string
    uid: VoiceAssistantFeature

    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.
      Allowed values:
    • "transcription"
    • "response_text"
    • "response_speech"
  • array<object>
    uid: VoiceAssistantProfiles
  • object
    uid: VoiceAssistantProfile

    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".
  • object oneOf
    uid: AssistantEvent
  • object
    uid: AssistantSttResponse
  • object
    uid: AssistantTextResponse
  • object
    uid: AssistantSpeechResponse
  • object
    uid: AssistantError
  • AssistantErrorCode
    string
    uid: AssistantErrorCode
      Allowed values:
    • "SERVICE_UNAVAILABLE"
    • "INVALID_AUDIO"
    • "NO_TEXT_RECOGNIZED"
    • "INTENT_FAILED"
    • "TTS_FAILED"
    • "TIMEOUT"
    • "UNEXPECTED_ERROR"
  • object
    uid: integrationStatus

    Integration instance status information. Intended to be used in a general overview of the integration drivers.

  • deviceState
    string
    uid: deviceState
      Allowed values:
    • "UNKNOWN"
    • "CONNECTING"
    • "CONNECTED"
    • "DISCONNECTED"
    • "ERROR"
  • driverState
    string
    uid: driverState
      Allowed values:
    • "NOT_CONFIGURED"
    • "IDLE"
    • "CONNECTING"
    • "ACTIVE"
    • "RECONNECTING"
    • "ERROR"
  • integrationState
    string
    uid: integrationState
      Allowed values:
    • "NOT_CONFIGURED"
    • "UNKNOWN"
    • "IDLE"
    • "CONNECTING"
    • "CONNECTED"
    • "DISCONNECTED"
    • "RECONNECTING"
    • "ACTIVE"
    • "ERROR"
  • integrationDriverType
    string
    uid: integrationDriverType
      Allowed values:
    • "LOCAL"
    • "EXTERNAL"
  • object
    uid: integrationDriverInfo

    Summary data of an integration driver intended for overview screens.

  • object
    uid: integrationDriver

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

  • object
    uid: driverDeveloper

    Optional information about the integration developer.

  • object
    uid: integrationDriverUpdate

    Integration driver update model. This model corresponds to the IntegrationDriver 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.
    • For the create operation, the driver_id identifier can be specified by the client, but it needs to be unique among all drivers. If omitted, a UUID will be assigned.
      A manually assigned, short, human-readable identifier is recommended for better recognizability.
  • object
    uid: integration

    An integration instance represents a configured integration driver.

    TODO add connection state?

  • object
    uid: integrationUpdate

    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.
  • object
    uid: IntegrationDiscoveryStatus
  • object
    uid: CreateIntegrationSetup
  • object
    uid: IntegrationSetupInfo

    Integration setup state

  • object
    uid: entityChange

    The new_state property is omitted for event_type = delete.
    The client should reload all entity data, if only event_type is present.

  • object
    uid: activityGroupChange

    The new_state property is omitted for event_type = delete.
    The client should reload all activity group data, if only event_type is present.

  • object
    uid: activeProfileChange

    The new_state.profile object contains additional profile data of the new active profile_id.

  • object
    uid: profileChange

    The new_state property is omitted for event_type = delete.

  • object
    uid: integrationDriverChange

    The new_state property is omitted for event_type = delete.

  • object
    uid: integrationChange

    The new_state property is omitted for event_type = delete.

  • object
    uid: integrationStateData
  • defaultChangeEventType
    string
    uid: defaultChangeEventType
      Allowed values:
    • "change"
    • "new"
    • "delete"
  • object
    uid: configurationChange
  • object
    uid: irLearning
  • object
    uid: irLearningCode
  • dockId
    string
    format: ^[a-zA-Z0-9\-\.]+$[ 1 .. 64 ] charactersuid: dockId

    Dock identifier

  • dockName
    string
    [ 1 .. 40 ] charactersuid: dockName

    User assignable friendly name to use instead of dock_id (service name).

  • dockUrl
    string
    <= 64 charactersuid: dockUrl

    Dock WebSocket URL to override auto-discovery from the service name in dock_id.

  • dockToken
    string
    format: password[ 1 .. 40 ] charactersuid: dockToken

    Access token

  • object
    uid: dockFilter

    Optional filters

  • object
    uid: dockChangeData

    The new_state property is omitted for event_type = delete.

  • object
    uid: dockConfiguration
  • object
    uid: dockConfigurationRequest
  • object
    uid: dockUpdateRequest
  • object
    uid: dockSystemInfo
  • object
    uid: dockStateData
  • dockState
    string
    uid: dockState
      Allowed values:
    • "IDLE"
    • "CONNECTING"
    • "ACTIVE"
    • "RECONNECTING"
    • "ERROR"
  • object
    uid: dockPortMode
  • object
    uid: dockDiscovery
  • object
    uid: dockDiscoveryInformation
  • discoveryType
    string
    uid: discoveryType

    Device discovery type:

    • BT: Bluetooth
    • NET: LAN or WAN network
      Allowed values:
    • "BT"
    • "NET"
  • object oneOf
    uid: createDockSetup
  • object
    uid: dockSetup

    Dock setup data

  • object
    uid: dockSetupFromDiscovery
  • object
    uid: dockSetupInfo

    Dock setup state

  • object
    uid: dockSetupChange
  • dockSetupState
    string
    uid: dockSetupState
      Allowed values:
    • "NEW"
    • "CONFIGURING"
    • "UPLOADING"
    • "RESTARTING"
    • "OK"
    • "ERROR"
  • dockSetupError
    string
    uid: dockSetupError
      Allowed values:
    • "NONE"
    • "NOT_FOUND"
    • "CONNECTION_ERROR"
    • "CONNECTION_REFUSED"
    • "AUTHORIZATION_ERROR"
    • "TIMEOUT"
    • "ABORT"
    • "PERSISTENCE_ERROR"
    • "OTHER"
  • object
    uid: dockUpdateChange
  • object
    uid: AvailableSystemUpdateResponse
  • object
    uid: AvailableSystemUpdate
  • UpdateChannel
    string
    uid: UpdateChannel
      Allowed values:
    • "STABLE"
    • "TESTING"
    • "DEVELOPMENT"
  • UpdateDownloadState
    string
    uid: UpdateDownloadState

    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
      Allowed values:
    • "PENDING"
    • "DOWNLOADING"
    • "DOWNLOADED"
    • "ERROR"
  • object
    uid: SystemUpdateResponse
  • object
    uid: softwareUpdateEvent
  • object
    uid: powerModeChangeEvent
  • object
    uid: batteryStatus
  • object
    uid: SystemUpdateProgress
  • SystemUpdateState
    string
    uid: SystemUpdateState
      Allowed values:
    • "IDLE"
    • "START"
    • "RUN"
    • "SUCCESS"
    • "FAILURE"
    • "DOWNLOAD"
    • "DONE"
    • "SUB_PROCESS"
    • "PROGRESS"
  • object
    uid: integrationDiscoveryEvent
  • object
    uid: integrationDiscoveryInformation
  • object
    uid: integrationSetupChange
  • integrationSetupState
    string
    uid: integrationSetupState
    • SETUP: setup in progress
    • WAIT_USER_ACTION: setup flow is waiting for user input. See require_user_action for requested input.
    • OK: setup finished successfully
    • ERROR: setup error
      Allowed values:
    • "SETUP"
    • "WAIT_USER_ACTION"
    • "OK"
    • "ERROR"
  • integrationSetupError
    string
    uid: integrationSetupError

    More detailed error reason for state: ERROR condition.

      Allowed values:
    • "NONE"
    • "NOT_FOUND"
    • "CONNECTION_REFUSED"
    • "AUTHORIZATION_ERROR"
    • "TIMEOUT"
    • "OTHER"
  • object
    uid: ConfirmationPage

    Confirmation screen

  • object
    uid: SettingsPage

    Settings definition page, e.g. to configure an integration driver.

  • object
    uid: Setting

    An input setting is of a specific type defined in field.type which defines how it is presented to the user.

    Inspired by the Homey SDK settings concept.

  • object
    uid: SettingTypeNumber

    Number input with optional min, max, steps and decimals properties. The default value must be specified in value. An optional unit of the number setting can be specified in units, which will be displayed next to the input field.

  • object
    uid: SettingTypeText

    Single line of text input.

    TODO: format specifier for e.g. email, url, date, datetime etc.?

  • object
    uid: SettingTypeTextArea

    Multi-line text input, e.g. for providing a description.

  • object
    uid: SettingTypePassword

    Password or pin entry field with the input text hidden from the user. Otherwise the same as text input.

  • object
    uid: SettingTypeCheckbox

    Checkbox setting with true / false values.

  • object
    uid: SettingTypeDropdown

    Dropdown setting to pick a single value from a list. All values must be strings.

  • object
    uid: SettingTypeLabel

    Additional read-only text for information purpose between other settings. Supports Markdown formatting.

  • object
    uid: SettingsValues

    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!
  • description
    string
    <= 255 charactersuid: description

    Optional description

  • array<object>
    uid: groups
  • object
    uid: group

    The shown group switch in the UI is automatically determined by the capabilities of the group's entities.

  • object
    uid: groupData
  • iconIdentifier
    string
    format: ^[a-z][a-z0-9]+:[a-zA-Z0-9\-_\.]+$<= 255 charactersuid: iconIdentifier

    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
    string
    format: ^[a-z][a-z0-9]+:[a-zA-Z0-9\-_\.]+$<= 255 charactersuid: imageIdentifier

    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.

  • name
    string
    [ 1 .. 50 ] charactersuid: name
  • array<object>
    uid: pages
  • object
    uid: page
  • object oneOf
    uid: pageItem
  • object
    uid: pageData

    Profile page data to create or update an existing page.

  • array<object>
    uid: profiles
  • object
    uid: profile
  • object
    uid: profileData

    Profile data to create or modify a profile. Missing properties are not updated when modifying an existing profile.

  • adminPin
    string
    <= 20 charactersuid: adminPin

    Optional administrator pin.

  • simpleId
    string
    format: ^[a-zA-Z0-9\-_\.]+$[ 1 .. 36 ] charactersuid: simpleId

    Simple string identifier, also usable as URL parameter or file identifier.

  • driverId
    string
    format: ^[a-zA-Z0-9\-_]+$[ 1 .. 36 ] charactersuid: driverId

    Unique integration driver identifier, e.g. hass, homey, etc.

  • integrationId
    string
    format: ^[a-zA-Z0-9\-_\.]+$[ 1 .. 73 ] charactersuid: integrationId

    Unique integration instance identifier. Automatically created by the system when creating a new instance from a driver.

  • deviceId
    string
    format: ^[a-zA-Z0-9\-_]+$[ 1 .. 36 ] charactersuid: deviceId

    Device identifier for multi-device integrations only.

  • entityId
    string
    format: ^[a-zA-Z0-9\-_\.]+$[ 1 .. 110 ] charactersuid: entityId

    UC remote entity identifier.

  • intgAuthMethod
    string
    uid: intgAuthMethod

    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.

      Allowed values:
    • "HEADER"
    • "MESSAGE"
  • object
    uid: ApScanStatus
  • object
    uid: AccessPointScan
  • object
    uid: WifiStatus
  • WifiBand
    string
    uid: WifiBand

    WiFi band:

    • auto: auto-configuration
    • a: 5 GHz
    • b: 2.4 GHz
      Allowed values:
    • "auto"
    • "a"
    • "b"
  • object
    uid: CreateWifiNetwork
  • object
    uid: ModifyWifiNetwork
  • array<object>
    uid: SavedNetworks
  • object
    uid: SavedNetwork

    A saved network configuration (known network)

  • WpaState
    string
    uid: WpaState
    • 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.
      Allowed values:
    • "UNKNOWN"
    • "ERROR"
    • "DISCONNECTED"
    • "INTERFACE_DISABLED"
    • "INACTIVE"
    • "SCANNING"
    • "AUTHENTICATED"
    • "ASSOCIATING"
    • "ASSOCIATED"
    • "FOUR_WAY_HANDSHAKE"
    • "GROUP_HANDSHAKE"
    • "COMPLETED"
  • WifiCmd
    string
    uid: WifiCmd
      Allowed values:
    • "DISCONNECT"
    • "RECONNECT"
    • "REASSOCIATE"
    • "ENABLE_ALL_NETWORKS"
    • "DISABLE_ALL_NETWORKS"
  • WifiNetworkCmd
    string
    uid: WifiNetworkCmd
      Allowed values:
    • "ENABLE"
    • "DISABLE"
    • "SELECT"
  • NetworkState
    string
    uid: NetworkState
      Allowed values:
    • "CONNECTED"
    • "OUT_OF_RANGE"
    • "DISABLED"
    • "TEMPORARY_DISABLED"
  • object
    uid: WifiChange
  • WifiEvent
    string
    uid: WifiEvent

    WiFi event:

    • CONNECTED: Authentication completed successfully and data connection enabled.
    • DISCONNECTED: Disconnected from access point and data connection not available.
    • SCAN_STARTED: Network scan started.
    • SCAN_COMPLETED: New network scan results available.
    • SCAN_FAILED: Network scanning failed.
    • NETWORK_NOT_FOUND: No suitable network was found.
    • WRONG_KEY: Authentication failure due to an invalid pre-shared key.
    • NETWORK_ADDED: A new network profile was added.
    • NETWORK_REMOVED: A network profile was removed.
      Allowed values:
    • "CONNECTED"
    • "DISCONNECTED"
    • "SCAN_STARTED"
    • "SCAN_COMPLETED"
    • "SCAN_FAILED"
    • "NETWORK_NOT_FOUND"
    • "WRONG_KEY"
    • "NETWORK_ADDED"
    • "NETWORK_REMOVED"
  • object
    uid: BtPairingStarted
  • object
    uid: BtPairingAuthRequest
  • object
    uid: BtPairingComplete
  • object
    uid: ExternalPortConfiguration

    External port configuration.

    • mode: configured operation mode.
    • active_mode: active operation mode, usually only set with the detected peripheral for mode: AUTO.
  • ExternalPortNumber
    integer
    >= 1uid: ExternalPortNumber

    1-based port index number.

  • ExternalPortMode
    string
    uid: ExternalPortMode
      Allowed values:
    • "AUTO"
    • "NONE"
    • "INFRARED"
    • "IR_BLASTER"
    • "IR_EMITTER_MONO_PLUG"
    • "IR_EMITTER_STEREO_PLUG"
    • "TRIGGER_5V"
    • "RS232"
  • ExternalPortActiveMode
    string
    uid: ExternalPortActiveMode
      Allowed values:
    • "UNKNOWN"
    • "NONE"
    • "ERROR"
    • "INFRARED"
    • "IR_BLASTER"
    • "IR_EMITTER_MONO_PLUG"
    • "IR_EMITTER_STEREO_PLUG"
    • "TRIGGER_5V"
    • "RS232"
  • object
    uid: UartConfiguration
  • UartBaudRate
    integer
    [ 300 .. 115200 ]uid: UartBaudRate

    Common baud rate values: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200

    Default value:9600
  • UartDataBits
    integer
    [ 5 .. 8 ]uid: UartDataBits
    Default value:8
  • UartStopBits
    string
    uid: UartStopBits

    Stop bits must be set as string, number format is not supported!

    Default value:"1"
      Allowed values:
    • "1"
    • "1.5"
    • "2"
  • UartParity
    string
    uid: UartParity
    Default value:"none"
      Allowed values:
    • "none"
    • "even"
    • "odd"
  • BtBondingSecurityType
    string
    uid: BtBondingSecurityType

    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.
      Allowed values:
    • "JUST_WORKS"
    • "DISPLAY_NUMBER"
    • "NUMERIC_COMPARISON"
    • "PASSKEY_INPUT"
  • object allOf
    uid: BtPairingResponse

    Response to a pairing request.

    • Passkey request: either provide the passkey entered by the user, decline it with confirm: false.
    • NumericComparison request: confirm or decline with confirm: true | false.
  • object
    uid: BtPeer

    Information about the (paired) peer.

  • BtAddressType
    string
    uid: BtAddressType

    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
      Allowed values:
    • "LE_PUBLIC"
    • "LE_RANDOM"
    • "LE_PUBLIC_IDENTITY"
    • "LE_RANDOM_IDENTITY"
    • "UNKNOWN"
  • PowerMode
    string
    uid: PowerMode
      Allowed values:
    • "NORMAL"
    • "IDLE"
    • "LOW_POWER"
    • "SUSPEND"
  • PowerStatus
    string
    uid: PowerStatus
      Allowed values:
    • "CHARGING"
    • "DISCHARGING"
    • "NOT_CHARGING"
    • "FULL"
  • object
    uid: BatteryCharger
  • object
    uid: BatteryChargerUpdate
  • object
    uid: AmbientLight
  • array<object>
    uid: Inhibitors
  • object
    uid: Inhibitor
  • InhibitMode
    string
    uid: InhibitMode
      Allowed values:
    • "BLOCK"
    • "DELAY"
  • object
    uid: CreateStandbyInhibitor