Remote Two/3 API Documentation

Visit the core-api GitHub project site where this documentation was built from and where you can find further technical information.

Introduction

• Remote Two user interface
• Remote Two entities
• Bluetooth HID peripheral support
• Remote Two DNS-SD lookup

Core API

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

The focus of the Core-APIs is to provide all functionality for the UI application and the web-configurator. The APIs are specialized for certain tasks, but otherwise contain the same functionality and data models.

• The UCR REST Core-API adds:
  • Custom resource handling for uploading icons, images etc.
  • Installing custom remote-ui and web-configurator components.
  • Installing custom integration drivers.
  • User management and authentication handling.
• The UCR WS Core-API adds:
  • Event subscription with asynchronous notifications.

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.

The API specifications are defined with OpenAPI & AsyncAPI in YAML format.

• REST Core-API documentation viewer
  • REST Core-API YAML definition
• WebSocket Core-API documentation viewer
  • WebSocket Core-API YAML definition

Dock API

The Remote Two/3 WebSocket Dock-API allows you to directly interact with the Unfolded Circle smart charging docks and take full control of its features.

The API specification is defined with AsyncAPI in YAML format. The WebSocket communication is using text messages with JSON payload.

• Dock AsyncAPI documentation viewer
  • Dock AsyncAPI YAML definition
  • View with the AsyncAPI Studio online tool.
    The link will directly load the yaml definition file from GitHub and display it together with the HTML documentation in the browser.

Integration API

The Unfolded Circle WebSocket Integration-API allows writing device integration drivers for the Unfolded Circle Remotes.

The API specification is defined with AsyncAPI in YAML format. The WebSocket communication is using text messages with JSON payload.

• Integration AsyncAPI viewer
  • Integration AsyncAPI YAML definition
  • View with AsyncAPI Studio online tool.
    The link will directly load the yaml definition file from GitHub and display it together with the HTML documentation in the browser.

Integration Driver

• How to write an integration driver
• WebSockets handling
• Driver registration
• Driver setup
• Install integration driver on the device

Contact us

There are a few different ways to reach us:

• Visit our GitHub site
• Reach out to us on X
• Visit our community forum
• Chat with us in our Discord channel
• Send us a message on our website

Contributions

Please read our contribution guidelines before opening a pull request.

License

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

Remote Two User Interface

The user interface was designed to be easy to use by anyone, who can use a smart home app. Similar principles were applied to the touch interface, enhanced with button navigation and control.

Home/page screen

Profiles

A profile can contain customised settings and UI configurations, including pages, groups and entities.

A profile can be changed by tapping on the current profile in settings.

Pages

A page can contain entities or groups. Pages can be selected by swiping left and right or using the left and right buttons on the D-pad. Tapping the page's name will bring up the page selector, where pages can be also added, deleted or renamed. Pages can have an image header and contain entities or groups. Multiple pages can contain the same entity.

A page can be used to segment rooms, areas, a specific purpose or anything else that makes sense to you.

Groups

Groups are a set of entities that can be defined by the user. Groups are another way of organising entities. A group can be configured to have a group switch, that can turn on/off every entity within the group at once. A group can be collapsed or expanded.

Example of a group containing two lights in expanded mode.

Remote Two DNS-SD lookup

The Remote Two will announce itself as service type _uc-remote._tcp.

The service lookup will return IP address and port number and other information in the TXT record data like model number and API version of the remote.

Model numbers

The model key specifies the physical device or the core-simulator:

Examples

macOS:

dns-sd -Z _uc-remote._tcp

For a UI tool, see Discovery.

Linux:

avahi-browse -d local --resolve _uc-remote._tcp -t

Entities

Entities represent devices by describing features and exposing controls. An integration can offer available entities for control. The user might select and configure entities, that will be available for the user interface.

Based on the entity type, device class and features, a specific user interface is shown. These features and other entity characteristics are set by the integration.

An integration driver provides entity definitions to the remote which then can be used in profiles and pages for the user to interact with the device.

Whenever the user interacts with an entity from an integration driver, the remote sends command requests to the integration driver. Once the entity or physical device has been updated the integration driver sends a change event message back to the remote to notify it about the updated state or attribute(s).

Supported entities:

• Button
• Switch
• Climate
• Cover
• Light
• Media Player
• Remote
• Sensor
• IR-Emitter

The 🚧 icon within the entity descriptions indicates a planned feature.

Integration API

To make entities available to the remote, an integration driver needs to provide entity definition for each entity instance, filled with entity type specific data.

The remote retrieves the available entities from the integration driver with the get_available_entities request message:

{
  "kind": "req",
  "id": 11,
  "msg": "get_available_entities"
}

The integration driver then responds with the available_entities message containing all entity definitions:

{
  "kind": "resp",
  "req_id": 11,
  "msg": "available_entities",
  "code": 200,
  "msg_data": {
    "available_entities": [
      {
        "entity_id": "button-1",
        "entity_type": "button",
        "name": {
          "en": "Ring dinner bell"
        }
      },
      {
        "entity_id": "blind-1",
        "entity_type": "cover",
        "device_class": "blind",
        "features": [
          "open",
          "close",
          "stop",
          "position"
        ],
        "name": {
          "en": "Living room blinds",
          "de": "Wohnzimmer Jalousien"
        }
      },
      {
        "entity_id": "light-1",
        "entity_type": "light",
        "features": [
          "on_off",
          "dim",
          "colour"
        ],
        "name": {
          "en": "Living room"
        }
      }
    ]
  }
}

All entities share a set of common attributes like name and the UNAVAILABLE, UNKNOWN states. An entity implementation defines additional features, attributes, states and options which need to be handled in the driver implementation.

Please see Integration AsyncAPI definition for more information and additional options.

Common entity definition

All entities share the following properties in the entity structure:

Features

The entity features define the controllable properties of an entity. They also influence how an entity is shown in the UI, e.g. if there are dimmer and colour selection controls for a lamp, or blind position controls.

Attributes

Entity attributes are controlled or influenced by features. A features can act on multiple attributes, e.g. the open command for a cover entity will set the state and if supported, also the current position of the cover.

An attribute value should represent the correct state of the physical device being controlled whenever possible. An integration driver might simulate intermediate states and position values, if the current state is either not readable from the device or involves expensive operations. E.g. if it's known that opening a window blind takes 30 seconds, the integration driver can start a timer and send approximated status updates during the opening time frame.
This will show a nice animation in the remote UI instead of immediately jumping from closed to open while the physical blind is still opening.

States

The entity state attribute holds the following common values which an integration driver can choose to support:

Device classes

An entity type can be further classified by an optional device class. This has mainly an influence on the UI representation how an entity is presented to a user. E.g. a cover entity has multiple device classes like blind or garage.

Options

Options are feature modifiers to customize certain behaviour, e.g. the default on_off feature for a switch expects the current state to be retrievable. If a switch can't provide its current state, it becomes a toggle switch with setting the readable option to false.

Commands

For all user or scene interactions with an entity, like switching it on or changing an attribute, the remote sends an entity_command message to the integration driver. This message contains the entity command with optional parameters to execute by the driver:

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "$TYPE",
    "entity_id": "$ID",
    "cmd_id": "$COMMAND",
    "params": {
      "$ParameterName1": "$ParameterValue1",
      "$ParameterName2": "$ParameterValue2",
      "$ParameterNameN": "$ParameterValueN"
    }
  }
}

• The command is specified in msg_data.cmd_id.
  • Optional command parameters are passed as key / value pairs under msg_data.params.
  • The available commands and parameters are specified in the corresponding entity documentation.
• The command request must be acknowledged with a result response message.
  • If at the time of receiving the command the driver already knows that it can't execute the command, it can send back an error to notify that the command execution is not possible.
    Otherwise, the remote assumes that the command is executed.
• Once the value has been set or confirmed by the physical device, an entity_change event message must be sent by the integration driver with the new value(s). Of course, this only applies to stateful attributes and not to buttons or "fire and forget" commands.

Events

The entity_change event must be emitted by the integration driver if the state of the entity changes. Either after an entity_command or if the entity has been updated otherwise, e.g. externally through a user or another system.
This keeps the remote in sync with the real state of the entity without the need of constant polling.

Event message structure:

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "$TYPE",
    "entity_id": "$ID",
    "attributes": {
      "$Attribute1": "$Value1",
      "$Attribute2": "$Value2",
      "$AttributeN": "$ValueN"
    }
  }
}

The available $Attribute(s) and their $Value(s) are specified in the entity documentation.

Common event attributes available for all entities:

At least one attribute must be specified in the entity_change message. If the common entity state and an addition attribute changed at the same time, they may both be included in the same message. It's also valid to always send every entity attribute. The remote will filter out non-changed attributes and only update changes in the UI.

Button Entity

A button entity can fire an event or start an action which cannot be further controlled once started.

This can be used for "fire and forget" commands, e.g. running a system command, sending an IR code, restart a device, reset something etc.

A button is stateless. To represent something that can be turned on and off, the switch entity should be used.

Features

States

The button entity only supports the ON state and the common entity states.

Device Classes

None.

Options

None: the button entity doesn't support additional options.

Integration API

Commands

The integration driver has to implement a handler for the entity_command message to process the following command requests in msg_data.cmd_id.

Events

None: the button entity is stateless and the remote doesn't need to be notified when the button was pressed externally.

Command examples

push

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "button",
    "entity_id": "button-1",
    "command_id": "push"
  }
}

Switch Entity

A switch entity can turn something on or off and the current state should be readable by the integration driver.

If the state can't be read, the readable option property can be set to false. This should be avoided whenever possible, because the remote either has to assume the current state, or the UI needs to ask the user for the current state.

If the switch controls a light source, then the light entity is usually a better choice.

Features

Attributes

Entity attributes are controlled by features. Multiple features can act on the same attribute. See Events on how to notify the remote about an updated attribute. The attributes have to be listed as properties under attributes with their current value.

States

The switch entity provides the following entity state values:

See common entity states.

Device classes

Optional switch type. This can be used by the UI to represent the entity with a different icon, behaviour etc.

Options

Integration API

Commands

The integration driver has to implement a handler for the entity_command message to process the following command requests in msg_data.cmd_id.

Events

The entity_change event must be emitted by the integration driver if the state or an attribute of the switch changes.

The following attributes must be included:

Command examples

on

{
  "kind": "req",
  "id": 124,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "switch",
    "entity_id": "switch-1",
    "cmd_id": "on"
  }
}

off

{
  "kind": "req",
  "id": 124,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "switch",
    "entity_id": "switch-1",
    "cmd_id": "off"
  }
}

toggle

{
  "kind": "req",
  "id": 124,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "switch",
    "entity_id": "switch-1",
    "cmd_id": "toggle"
  }
}

Event examples

Switched on

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "switch",
    "entity_id": "switch-1",
    "attributes": {
      "state": "on"
    }
  }
}

Switched off

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "switch",
    "entity_id": "switch-1",
    "attributes": {
      "state": "off"
    }
  }
}

Climate Entity

A climate entity controls heating, ventilation and air conditioning (HVAC) devices. This can range from simple fans to personal air conditioning units to integrated building devices.

Features

Attributes

Entity attributes are controlled by features. Multiple features can act on the same attribute.

See entity options for temperature unit and ranges.

States

The climate entity provides the following entity state values and represents the currently set HVAC mode of the device:

Note: the current mode may not be the active state of the device. E.g. if the mode is set to AUTO the climate unit may be heating, cooling, idle, etc. at a specific point in time.

See common entity states.

Device Classes

None.

Options

🚧 Planned feature.

Integration API

Commands

The integration driver has to implement a handler for the entity_command message to process the following command requests within msg_data.cmd_id.

• The command request must be acknowledged with a result response message.
• Once the value has been set or confirmed by the physical device, an entity_change event message with the new value(s) must be sent.

Events

The entity_change event must be emitted by the integration driver if the state or an attribute of the climate device changes. Either after anentity_command or if the climate device has been updated externally through a user or another system. This keeps the remote in sync with the real state of the entity without the need of constant polling.

The following attributes are supported:

At least one attribute must be specified in the entity_change message. If the entity state and a climate attribute changed at the same time, they may both be included in the same message. It's also valid to always send every attribute.

Command examples

on

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "climate",
    "entity_id": "climate-1",
    "cmd_id": "on"
  }
}

off

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "climate",
    "entity_id": "climate-1",
    "cmd_id": "off"
  }
}

hvac_mode

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "climate",
    "entity_id": "climate-1",
    "cmd_id": "hvac_mode",
    "params": {
      "hvac_mode": "COOL"
    }
  }
}

Combined with target temperature

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "climate",
    "entity_id": "climate-1",
    "cmd_id": "hvac_mode",
    "params": {
      "hvac_mode": "COOL",
      "temperature": 23
    }
  }
}

target_temperature

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "climate",
    "entity_id": "climate-1",
    "cmd_id": "target_temperature",
    "params": {
      "temperature": 23
    }
  }
}

Event examples

State change event

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "climate",
    "entity_id": "climate-1",
    "attributes": {
      "hvac_mode": "HEAT",
      "current_temperature": 19.5,
      "target_temperature": 21.0
    }
  }
}

Cover Entity

Entity for covering or opening things like blinds, window covers, curtains, etc. The entity features specify the abilities of the cover and the controllable properties, whereas the device class specifies the UI representation.

Features

🚧 Planned feature.

If no tilt* features are specified in the cover entity, the remote UI will not show the tilt support and the integration driver does not need to support the required tilt commands and events.

Attributes

States

The cover entity provides the following entity state values:

See common entity states.

Device classes

Optional cover type. This can be used by the UI to represent the cover with a different icon, behaviour etc.

Options

None: the cover entity doesn't support additional options.

Integration API

Commands

The integration driver has to implement a handler for the entity_command message to process the following command requests in msg_data.cmd_id.

Events

The entity_change event must be emitted by the integration driver if the state or an attribute of the cover changes.

The following attributes are supported:

At least one attribute must be specified in the entity_change message. If the entity state and a position attribute changed at the same time, they may both be included in the same message. It's also valid to always send every attribute.

Command examples

open

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "cover",
    "entity_id": "blind-1",
    "cmd_id": "open"
  }
}

close

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "cover",
    "entity_id": "blind-1",
    "cmd_id": "close"
  }
}

stop

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "cover",
    "entity_id": "blind-1",
    "cmd_id": "stop"
  }
}

position

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "cover",
    "entity_id": "blind-1",
    "cmd_id": "position",
    "params": {
      "position": 70
    }
  }
}

tilt

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "cover",
    "entity_id": "blind-1",
    "cmd_id": "tilt",
    "params": {
      "tilt_position": 45
    }
  }
}

tilt_down

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "cover",
    "entity_id": "blind-1",
    "cmd_id": "tilt_down"
  }
}

tilt_up

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "cover",
    "entity_id": "blind-1",
    "cmd_id": "tilt_up"
  }
}

tilt_stop

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "cover",
    "entity_id": "blind-1",
    "cmd_id": "tilt_stop"
  }
}

Event examples

State change event

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "cover",
    "entity_id": "blind-1",
    "attributes": {
      "state": "OPENING",
      "position": 72
    }
  }
}

Cover position change event

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "cover",
    "entity_id": "blind-1",
    "attributes": {
      "position": 72
    }
  }
}

Cover tilt position change event

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "cover",
    "entity_id": "blind-1",
    "attributes": {
      "tilt_position": 50
    }
  }
}

Light Entity

A light entity can be switched on and off and depending on its features, the light source can be further controlled like setting brightness, hue, color saturation and color temperature.

The HSV color model is used for adjusting color and brightness.

Features

Attributes

States

The light entity provides the following entity state values:

See common entity states.

Device Classes

None.

Options

Integration API

Commands

The integration driver has to implement a handler for the entity_command message to process the following command requests in msg_data.cmd_id.

Events

The entity_change event must be emitted by the integration driver if the state or an attribute of the light changes.

The following attributes are supported:

Command examples

on

Default request:

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "light",
    "entity_id": "light-1",
    "cmd_id": "on"
  }
}

Request with setting brightness value:

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "light",
    "entity_id": "light-1",
    "cmd_id": "on",
    "params": {
      "brightness": 140
    }
  }
}

Request with setting color temperature:

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "light",
    "entity_id": "light-1",
    "cmd_id": "on",
    "params": {
      "color_temperature": 70
    }
  }
}

Request with setting light color:

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "light",
    "entity_id": "light-1",
    "cmd_id": "on",
    "params": {
      "hue": 180,
      "saturation": 200
    }
  }
}

off

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "light",
    "entity_id": "light-1",
    "cmd_id": "off"
  }
}

toggle

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "light",
    "entity_id": "light-1",
    "cmd_id": "toggle"
  }
}

Event examples

Switched on

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "light",
    "entity_id": "light-1",
    "attributes": {
      "state": "ON"
    }
  }
}

The additional brightness and color attributes can be added as well:

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "light",
    "entity_id": "light-1",
    "attributes": {
      "state": "ON",
      "brightness": 180,
      "hue": 180,
      "saturation": 150
    }
  }
}

Switched off

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "light",
    "entity_id": "light-1",
    "attributes": {
      "state": "OFF"
    }
  }
}

Media Player Entity

• Features
  • Attributes
  • States
  • Device Classes
  • Options
• Integration API
  • Commands
  • Simple Commands
    • Command Name Patterns
  • Events
    • Media types
    • Media images
  • Command examples
    • on
    • play_pause
    • volume
    • seek
    • repeat
    • shuffle
    • select_sound_mode
    • Custom simple command
  • Event examples
    • State change event
• Open issues and missing features

A media player entity controls playback of media on a device. This could be an online music streaming service, a TV, a stereo or a video player.

Features

Media-player features define the capabilities of the controlled device. For example the dpad feature will enable the four directional commands and the enter command. Furthermore, certain features control the appearance and functionality of the media-player UI on the Remote Two.

• R: readable
  • ✅ Feature has a readable attribute to retrieve the current or available values.
  • ❌ Feature value(s) cannot be read.
• W: writeable
  • ✅ Feature has one or multiple commands to trigger an action or set a value.
  • ❌ No corresponding command(s), only the current value(s) of the feature can be read.

🚧 Planned features are playlist handling, media browsing and searching.

🧑‍💻 Integration driver developers:

• If certain features or commands are missing for your device, they can be defined with "simple commands".
• If a feature doesn't fully match your device, for example it only has a record function but no my_recordings or live functions, then the desired command(s) should also be defined as a "simple command".
  • For the command name use the corresponding cmd_id in uppercase to keep any command related automations.
    (This would be RECORD for the record-only feature example).

Attributes

Entity attributes are enabled by features and hold the current value of a feature or provide available options. Multiple features can act on the same attribute.

States

The entity state attribute holds the following values:

See also common entity states.

Device Classes

Optional: the media player can be classified what kind of device it represents. This can be used by the UI to represent the media player with a different icon, behaviour etc.

Options

Optional features of the media-player entity.

Integration API

Commands

The integration driver has to implement a handler for the entity_command message to process the following command requests in msg_data.cmd_id.

Simple Commands

Additional commands can be enabled with the simple_commands options. A device exposing a media-player entity can support all additional device commands, not covered with the standard features, as so-called "simple commands". These commands are comparable with the infrared remote-entity commands, where keys trigger an action on the device:

• The command is fully defined by its name and doesn't have any further arguments or related attributes.
• Command names must be upper case and may not contain spaces.
  • The upper case restriction makes them distinguishable from the pre-defined feature commands.
  • Only a subset of the 7-bit ASCII printable characters are allowed: -/_.:+#*°@%()?
  • Maximum length is 20 characters.
  • Command name regex: ^[A-Z0-9\/_.:+#*°@%()?-]{1,20}$
• 🚧 Simple commands cannot be translated yet. In the web-configurator they show up as defined.

Command Name Patterns

Even though command names can be freely defined with the allowed characters, the following prefixes should be used. This allows better integration into Remote Two, like default UI mappings and grouping of similar commands.

• INPUT_: source inputs, e.g. INPUT_AUX1, INPUT_TV, INPUT_RADIO
• APP_: applications, e.g. APP_MY_TV_STREAMING, APP_INTERNET
• MODE_: mode changing functions, e.g. MODE_16/9, MODE_SURROUND, MODE_FOOTBALL
• MENU_: additional menus, e.g. MENU_SMART_HOME, MENU_QUICK
• DIGIT_: additional input digits besides the pre-defined numpad digits, e.g. DIGIT_10, DIGIT_10+
• ZONE_: multi-room functions, e.g. ZONE_A, ZONE_MULTIROOM

Events

The entity_change event must be emitted by the integration driver if the state or an attribute of the media player changes.

The following attributes are supported:

At least one attribute must be specified in the entity_change message. If the entity state and another attribute changed at the same time, for example if a new track starts playing, they may both be included in the same message. It's also valid to always send every attribute.

Media types

The media_type attribute specifies the media being played:

• MUSIC
• RADIO
• TVSHOW
• MOVIE
• VIDEO

The integration may return other values, but the UI will most likely handle them as an "unknown media".

Media images

• Supported image formats: jpg and png.
• The album art image can either be provided as a single image or as three matching image sizes.
  • Images will automatically be resized to the required sizes.
    Either from the single image in media_image_url or from the individual sizes.
  • Images too large in pixel or file size will be rejected due to resource constraints on the remote.
• Preferred image sizes in pixel:
  • Large, for full screen album art: 420 x 420
  • Medium: 100 x 100
  • Small, for thumbnails: 60 x 60

Command examples

on

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "on"
  }
}

play_pause

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "play_pause"
  }
}

volume

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "volume",
    "params": {
      "volume": 40
    }
  }
}

seek

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "seek",
    "params": {
      "media_position": 180
    }
  }
}

repeat

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "repeat",
    "params": {
      "repeat": "ALL"
    }
  }
}

shuffle

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "shuffle",
    "params": {
      "shuffle": true
    }
  }
}

select_sound_mode

Specify a sound mode value contained in the sound_mode_list attribute array.

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "select_sound_mode",
    "params": {
      "mode": "MOVIE"
    }
  }
}

Custom simple command

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "cmd_id": "THUMBS_UP"
  }
}

Event examples

State change event

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "media_player",
    "entity_id": "media-1",
    "attributes": {
      "state": "PLAYING",
      "media_duration": 245,
      "media_position": 1,
      "media_position_updated_at": "2025-03-18T07:30:00.000Z",
      "media_title": "Some title",
      "media_artist": "My artist",
      "media_album": "Best of",
      "media_image_url_large": "http://192.168.1.100/player/current/album_l.png",
      "media_image_url_medium": "http://192.168.1.100/player/current/album_m.png",
      "media_image_url_small": "http://192.168.1.100/player/current/album_s.png"
    }
  }
}

Open issues and missing features

• Define album art image limits
• Define media types
• Playlist handling
• Media browsing
• Searching

Remote Entity

A remote entity can send commands to a controllable device.

ℹ️ Supported in remote-core / Core Simulator from version 0.43.0.

Features

• R: readable
  • ✅ Feature has a readable attribute to retrieve the current or available values.
  • ❌ Feature value(s) cannot be read.
• W: writeable
  • ✅ Feature has one or multiple commands to trigger an action or set a value.
  • ❌ No corresponding command(s), only the current value(s) of the feature can be read.

Attributes

Entity attributes are controlled by features. Multiple features can act on the same attribute. See Events on how to notify the remote about an updated attribute. The attributes have to be listed as properties under attributes with their current value.

States

The remote entity provides the following entity state values:

See common entity states.

Device classes

None.

Options

Optional features of the remote entity.

If the available commands are known by the integration driver, they should be made available in the simple_commands option. This allows the Remote Two configuration in the web-configurator to show all supported commands to the user. Otherwise, the user has to know the command names and has to enter them manually for each command.

If button_mapping or user_interface options are not provided, an automatic mapping is attempted based on the command names in simple_commands. The mapping logic is similar to the infrared codesets in the internal IR-remotes. See Command name patterns below on how commands should be named.

The automatic button and user interface creation is only done once at the initial entity configuration. From that point on the user can independently modify the UI and button mapping. Only changes in the simple_commands list will be applied to the configured entities in Remote Two, if the available entities are reloaded from the integration driver.

Simple commands

A simple command is fully defined by its name and doesn't have any further arguments or related attributes. It's comparable to the simple commands in the media-player entity, with fewer naming restrictions.

Restrictions:

• A command name may not include whitespace characters.
• The maximum length of a command name is 20 characters.
• A command name may not be any of the defined cmd_id commands: on, off, toggle, send_cmd, send_cmd_sequence.
• Commands cannot have any further parameters. For example, it's not possible to have a switch_channel command with the channel number as parameter.

Command naming recommendations:

• Command names should be short and follow naming patterns.
• Uppercase naming is preferred.
• Dedicated power on/off or toggle commands should not be added. Use the on_off and toggle features with the defined on, off and toggle commands.

Command Name Patterns

Even though command names can be freely defined, it's highly recommended to follow a naming pattern and use the recommended names for common commands. This allows better integration into Remote Two, like default UI mappings and grouping of similar commands.

• Navigation: CURSOR_UP, CURSOR_DOWN, CURSOR_LEFT, CURSOR_RIGHT, CURSOR_ENTER, BACK, EXIT
• Menus: HOME, MENU, CONTEXT_MENU, GUIDE, INFO, SETTINGS
• Volume control: VOLUME_UP, VOLUME_DOWN, MUTE_TOGGLE, MUTE, UNMUTE
• Media playback: PLAY_PAUSE, STOP, PREVIOUS, NEXT, FAST_FORWARD, REWIND

See media-player entity commands for further commands.

Prefixes for other common functions:

• INPUT_: source inputs, e.g. INPUT_AUX1, INPUT_TV, INPUT_RADIO
• APP_: applications, e.g. APP_MY_TV_STREAMING, APP_INTERNET
• MODE_: mode changing functions, e.g. MODE_16/9, MODE_SURROUND, MODE_FOOTBALL
• MENU_: additional menus, e.g. MENU_SMART_HOME, MENU_QUICK
• DIGIT_: additional input digits besides the pre-defined numpad digits, e.g. DIGIT_10, DIGIT_10+
• ZONE_: multi-room functions, e.g. ZONE_A, ZONE_MULTIROOM

Button mapping

A default button mapping can be provided in options.button_mapping.

The DeviceButtonMapping object is defined in the Integration-API and is based on the same definition in the Core-API.

Example of entity.options object:

{
  "simple_commands": [
    "VOLUME_UP",
    "VOLUME_DOWN",
    "HOME",
    "CURSOR_UP",
    "CURSOR_DOWN",
    "CURSOR_LEFT",
    "CURSOR_RIGHT",
    "CURSOR_ENTER"
  ],
  "button_mapping": [
    {
      "button": "POWER",
      "short_press": {
        "cmd_id": "remote.toggle"
      }
    },
    {
      "button": "RED",
      "short_press": {
        "cmd_id": "remote.send_cmd",
        "params": {
          "command": "VOLUME_DOWN",
          "repeat": 10
        }
      }
    },
    {
      "button": "DPAD_UP",
      "short_press": {
        "cmd_id": "CURSOR_UP"
      }
    },
    {
      "button": "DPAD_MIDDLE",
      "short_press": {
        "cmd_id": "CURSOR_ENTER"
      },
      "long_press": {
        "cmd_id": "MENU"
      }
    },
    {
      "button": "DPAD_DOWN",
      "short_press": {
        "cmd_id": "CURSOR_DOWN"
      }
    },
    {
      "button": "BLUE",
      "short_press": {
        "cmd_id": "remote.send_cmd_sequence",
        "params": {
          "sequence": "HOME,CURSOR_DOWN,CURSOR_RIGHT,CURSOR_ENTER",
          "delay": 200
        }
      }
    }
  ]
}

See Commands about entity commands and their short vs fully qualified syntax. For example on and off vs remote.on and remote.off.

Button identifiers for Remote Two:

• BACK
• HOME
• VOICE
• VOLUME_UP, VOLUME_DOWN, MUTE
• DPAD_UP, DPAD_DOWN, DPAD_LEFT, DPAD_RIGHT, DPAD_MIDDLE
• GREEN, YELLOW, RED, BLUE
• CHANNEL_UP, CHANNEL_DOWN
• PREV, PLAY, NEXT
• POWER

A detailed button mapping can be retrieved with the Core-API: GET /api/cfg/device/button_layout.

User interface

A default user interface can be provided in options.user_interface.

The UserInterface object is defined in the Integration-API and is based on the Core-API ActivityUserInterface definition.

UI page example

entity.options object:

{
  "simple_commands": [
    "MY_RECORDINGS",
    "MY_APPS",
    "REVERSE",
    "PLAY",
    "PAUSE",
    "FORWARD",
    "RECORD"
  ],
  "user_interface": {
    "pages": [
      {
        "page_id": "media",
        "name": "Media",
        "grid": { "width": 4, "height": 6 },
        "items": [
          {
            "type": "text",
            "text": "Recordings",
            "command": {
              "cmd_id": "MY_RECORDINGS"
            },
            "location": { "x": 0, "y": 2 },
            "size": { "width": 2, "height": 1 }
          },
          {
            "type": "text",
            "text": "Apps",
            "command": {
              "cmd_id": "MY_APPS"
            },
            "location": { "x": 2, "y": 2 },
            "size": { "width": 2, "height": 1 }
          },
          {
            "type": "icon",
            "icon": "uc:bw",
            "command": {
              "cmd_id": "REVERSE"
            },
            "location": { "x": 0, "y": 5 }
          },
          {
            "type": "icon",
            "icon": "uc:play",
            "command": {
              "cmd_id": "PLAY"
            },
            "location": { "x": 1, "y": 5 }
          },
          {
            "type": "icon",
            "icon": "uc:pause",
            "command": {
              "cmd_id": "PAUSE"
            },
            "location": { "x": 2, "y": 5 }
          },
          {
            "type": "icon",
            "icon": "uc:ff",
            "command": {
              "cmd_id": "FORWARD"
            },
            "location": { "x": 3, "y": 5 }
          },
          {
            "type": "icon",
            "icon": "uc:rec",
            "command": {
              "cmd_id": "RECORD"
            },
            "location": { "x": 2, "y": 4 }
          }
        ]
      }
    ]
  }
}

Screen grid sizes for Remote Two:

• Minimal size: 1 x 1
• Maximum size: 8 x 12
• Default: 4 x 6

The screen layout grid definition can be retrieved with the Core-API: GET /api/cfg/device/screen_layout.

Integration API

Commands

The integration driver has to implement a handler for the entity_command WebSocket message to process the following command requests in msg_data.cmd_id. See Command examples and Integration-API for the full message structure.

• The command and sequence parameters will either contain a simple command (if specified in entity options) or a freetext command. It is up to the integration driver to verify and validate commands.
• A command name may not include whitespace characters.
• The maximum length of a command name is 20 characters.
• A command name may not be any of the defined cmd_id commands: on, off, toggle, send_cmd, send_cmd_sequence
• If no delay parameter is included, the integration driver has to choose an appropriate delay based on the command and controlled device.

Using commands for button mappings and UI elements

‼️ Attention: the cmd_id for button mapping and UI item commands is slightly different than the remote-entity Commands!

• Core-API button mapping and UI item commands:
  • The cmd_id value is either a simple command or an entity command with the entity type prefix.
• Integration-API entity commands:
  • The cmd_id value refers to the defined Commands without the entity type prefix.
  • A simple command will always be wrapped into the remote-entity command send_cmd.

When defining commands in button mappings or UI elements, either entity commands or simple commands can be used.

• Entity commands are all the commands an entity defines (see cmd_id column in Commands above). Example:

{
  "cmd_id": "toggle"
}

• If the integration driver provides the simple_commands option, the specified commands can be directly used in cmd_id. Example:

{
  "cmd_id": "PLAY"
}

• Specified simple commands can also be used in the send_cmd entity command.
• The command parameter of send_cmd allows any command name ("free-text") and it's up to the integration driver to validate the received commands.
  Example of a simple command used in send_cmd:

{
  "cmd_id": "send_cmd",
  "params": {
    "command": "PLAY"
  }
}

• If an entity command is used it's recommended to prefix it with the entity type to use the same naming convention as in the Core-API.
  • Using the fully qualified command name might make it easier in the integration driver to distinguish the commands.
  • A missing entity type prefix is automatically added when an available remote-entity is configured in Remote Two.
  • When working with the Core-API, for example reconfiguring a button mapping, the fully qualified command name is required.

Recommended fully-qualified entity command name:

{
  "cmd_id": "remote.send_cmd",
  "params": {
    "command": "PLAY"
  }
}

Events

The entity_change event must be emitted by the integration driver if the state or an attribute of the remote device changes.

The following attributes must be included:

Command examples

Remote-entity examples of received entity_command WebSocket messages in an integration driver.

on

{
  "kind": "req",
  "id": 124,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "remote",
    "entity_id": "remote-1",
    "cmd_id": "on"
  }
}

off

{
  "kind": "req",
  "id": 124,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "remote",
    "entity_id": "remote-1",
    "cmd_id": "off"
  }
}

toggle

{
  "kind": "req",
  "id": 124,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "remote",
    "entity_id": "remote-1",
    "cmd_id": "toggle"
  }
}

send command

{
  "kind": "req",
  "id": 124,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "remote",
    "entity_id": "remote-1",
    "cmd_id": "send_cmd",
    "params": {
      "command": "DPAD_UP"
    }
  }
}

send long-press command

{
  "kind": "req",
  "id": 124,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "remote",
    "entity_id": "remote-1",
    "cmd_id": "send_cmd",
    "params": {
      "command": "CURSOR_ENTER",
      "hold": 800
    }
  }
}

send repeated command

{
  "kind": "req",
  "id": 124,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "remote",
    "entity_id": "remote-1",
    "cmd_id": "send_cmd",
    "params": {
      "command": "VOLUME_DOWN",
      "repeat": 5
    }
  }
}

send sequence

{
  "kind": "req",
  "id": 124,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "remote",
    "entity_id": "remote-1",
    "cmd_id": "send_cmd_sequence",
    "params": {
      "sequence": ["1", "2", "3", "ENTER"],
      "delay": 100
    }
  }
}

Event examples

device was turned on

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "remote",
    "entity_id": "remote-1",
    "attributes": {
      "state": "on"
    }
  }
}

device was turned off

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "remote",
    "entity_id": "remote-1",
    "attributes": {
      "state": "off"
    }
  }
}

Sensor Entity

A sensor entity provides measured values from devices or dedicated hardware sensors.
The device class specifies the type of sensor and links it with a default unit of measurement to display in the user interface.

• The custom device class allows arbitrary text values and unit labels.
• The temperature device class performs automatic conversion between °C and °F.

Features

The sensor entity has no features.

Attributes

The unit attribute can be specified in the entity_change event and takes precedence over the associated default unit in the device_class or the specified custom_unit in the options.

If an integration driver gets the current unit from an external system together with the current value, it's recommended to pass it on.
If the integration driver is in control of the unit, and it can't change at runtime, the unit can be specified in the available entity definition as options.custom_unit and then omitted in entity_change events.

States

The state attribute is optional for a sensor.

The sensor entity only supports the ON state and the common entity states.

Device Classes

The device class specifies the type of sensor. Default if not specified: custom.

Binary Device Class

The binary device class allows specifying a binary sensor with two states in the value attribute: on and off.

These values can mean different things depending on the unit attribute. For example, a binary sensor with the unit attribute set to sound: on means sound detected and off means no sound detected. For unit set to window: on means the window is open and off means the window is closed.

If the unit attribute is not specified, the binary sensor is a generic on/off sensor.

🚧 Supported unit values are the Home Assistant binary sensor device classes: https://www.home-assistant.io/integrations/binary_sensor/#device-class

Options

Integration API

Commands

The sensor entity doesn't support any commands.

Events

The entity_change event must be emitted by the integration driver if the state or an attribute of a sensor changes.

The following attributes are supported:

• At least one attribute must be specified in the entity_change message.
  • If the sensor value and unit attributes change at the same time, both must be included in the same message.
  • It's also valid to always send every attribute.
• Only sending the unit attribute is not valid.
• If the state is never sent, the sensor is considered available (ON).

Event Examples

State Change Event

Sensor with a number value:

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "sensor",
    "entity_id": "sensor-1",
    "attributes": {
      "value": 21.2,
      "unit": "°C"
    }
  }
}

Sensor with a string value:

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "sensor",
    "entity_id": "sensor-2",
    "attributes": {
      "value": "231",
      "unit": "V"
    }
  }
}

Sensor coming online with the current value:

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "sensor",
    "entity_id": "sensor-1",
    "attributes": {
      "state": "ON",
      "value": 21.5,
      "unit": "°C"
    }
  }
}

Binary sensor event:

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "sensor",
    "entity_id": "sensor-bin1",
    "attributes": {
      "state": "ON",
      "value": "off",
      "unit": "running"
    }
  }
}

IR-emitter Entity

An IR-emitter entity allows to send IR commands in PRONTO hex format.

This entity allows to integrate external IR blasters and emitters. Once added to a Remote, a new IR-emitter output is registered which can be used for IR-remote entities. Similar as adding a new dock.

An IR-emitter device must support the PRONTO hex format. Other IR formats are optional. Currently only the IR protocols and data values of the IRremoteESP8266 library are supported as additional format (see options below for more information).

ℹ️ Supported in UC Remote firmware from version 1.9.3, Core Simulator from version 0.48.0.

Features

• R: readable
  • ✅ Feature has a readable attribute to retrieve the current or available values.
  • ❌ Feature value(s) cannot be read.
• W: writeable
  • ✅ Feature has one or multiple commands to trigger an action or set a value.
  • ❌ No corresponding command(s), only the current value(s) of the feature can be read.

Attributes

Entity attributes are controlled by features. Multiple features can act on the same attribute.

States

The IR-emitter entity only supports the ON state and the common entity states.

Device Classes

None.

Options

Optional features of the IR-emitter entity.

• The ports option can be omitted, if the emitter only supports a single output port.
  EmitterPort format:

  {
    "id": "unique-id",
    "name": "Friendly port name"
  }
  

• The PRONTO hex format is the default and must be supported by the IR-emitter driver.

• The HEX IR format refers to the learned IR codes with the Unfolded Circle Dock.

  • Format: <protocol>;<hex-ir-code>;<bits>;<repeat-count> from the IRremoteESP8266 library.
  • protocol: numeric value from supported and enabled protocols. See: decode_type_t
  • hex-ir-code: HEX value prefixed with 0x.
  • bits: number of bits in hex value.
  • repeat-count: number of repeats.

• Specifying additional formats like HEX allows the Remote to send these formats when available, e.g. learned codes from the dock. It does not mean, that all codes are transformed into this format!

• If the emitter device doesn't support the HEX format, the learned codes from the dock are automatically converted and sent as PRONTO codes.

  • ⚠️ The PRONTO-conversion is a best effort process only and certain IR protocols might lose the native auto-repeat functionality!

• ℹ️ Raw and Global Caché sendir formats are planned in the future.

Integration API

Commands

The integration driver has to implement a handler for the entity_command message to process the following command requests in msg_data.cmd_id.

send_ir

The send_ir command is used to send an IR code on the specified output port.

Long button presses on the Remote will trigger continuous send_ir requests with a repeat count set to 3 or higher. Once the button is released, a stop_ir request is sent. This allows to implement a continuous IR repeat feature:

• If no transmission is active: start sending the IR command.
• If transmission is active:
  1. check if the same IR code is being transmitted. If other code: abort and respond with error code 409.
  2. reset repeat count of the active transmission to prolong the command.

Queuing IR send requests should be avoided to prevent "ghost actions" when the user doesn't expect it. New IR commands should be executed within 1 second.

ℹ️ The HEX format already contains a repeat field. This value is relevant, if the send_ir.repeat parameter is not set. For continuous IR repeat, the send_ir.repeat parameter is set and overrides the embedded repeat field in the IR code.

stop_ir

The stop_ir command signals to stop an active IR transmission on the specified output port.

The IR transmission should be stopped no later than at the start of the next repeat sequence. (This also depends on the IR protocol, some have a specific repeat sequence, others need to be fully retransmitted).

Events

The entity_change event must be emitted by the integration driver if the state or an attribute of the IR-emitter changes.

The following attributes must be included:

Command examples

IR-emitter entity examples of received entity_command WebSocket messages in an integration driver.

send_ir with PRONTO code on default output

Sending a single PRONTO code (without repeat) on an IR-emitter with only one output port (options.ports not specified or empty):

{
  "kind": "req",
  "id": 122,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "ir_emitter",
    "entity_id": "emitter-1",
    "cmd_id": "send_ir",
    "params": {
      "code": "0000 006D 0004 0002 0155 00AB 0015 0015 0015 0015 0015 0015 0155 0055 0015 0E4C"
    }
  }
}

send_ir with PRONTO code on specific output and repeat

Sending a PRONTO code three times on a specific output port:

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "ir_emitter",
    "entity_id": "emitter-2",
    "cmd_id": "send_ir",
    "params": {
      "code": "0000 006D 0004 0002 0155 00AB 0015 0015 0015 0015 0015 0015 0155 0055 0015 0E4C",
      "port": "port1",
      "repeat": 3
    }
  }
}

stop_ir

Stop an active IR transmission on a specific output port:

{
  "kind": "req",
  "id": 124,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "ir_emitter",
    "entity_id": "emitter-2",
    "cmd_id": "stop_ir",
    "params": {
      "port": "port1"
    }
  }
}

Event examples

State change event

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "msg_data": {
    "entity_type": "ir_emitter",
    "entity_id": "emitter-1",
    "attributes": {
      "state": "on"
    }
  }
}

Integration Drivers

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

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

See examples below for integration libraries and existing open source integrations.

• How to write an integration driver
• WebSockets handling
• Driver mDNS advertisement
• Driver registration
• Driver setup
• Install integration driver on the device

WebSocket Integration API

The Unfolded Circle WebSocket Integration-API allows writing device integration drivers for the Unfolded Circle Remotes.

The API specification is defined with AsyncAPI in YAML format. The WebSocket communication is using text messages with JSON payload.

• Integration AsyncAPI viewer
  • Integration AsyncAPI YAML definition
  • View with AsyncAPI Studio online tool.
    The link will directly load the yaml definition file from GitHub and display it together with the HTML documentation in the browser.

Examples

Node.js

• Node.js API wrapper for the UC Integration API

Integrations using the Node.js API wrapper:

• Global Caché IR integration
• Roon integration

Python

• Python API wrapper library for the UC Integration API

Integrations using the Python API wrapper:

• Android TV integration
• Apple TV integration
• Denon AVR integration

Rust

• API models in Rust
• Home Assistant integration written in Rust

How to write an integration driver

The Integration-API allows to develop external integration drivers in any programming language capable of running a WebSockets server. Custom integration drivers require Node.js or a statically linked binary.

• External integration driver: a driver running on an external device, reachable by the Remote.
• Custom integration driver: a driver running on the Remote in a restricted, sandboxed environment.

ℹ️ Beta release 1.9.0 allows to install custom integration drivers on the Remote.
This is a developer preview feature to test integrations. See Driver installation on the Remote for more information.

ℹ️ See NodeJS API wrapper for a quick start in JavaScript, or the Python API wrapper if using Python.

When writing a driver from scratch without using a wrapper library:

1. Choose your programming language.
2. Choose a WebSockets server library or framework for your language.
3. Choose a JSON framework for your language.
4. Choose which entities and features the driver should expose.
5. Implement the required WebSockets text messages in the WebSocket Integration API.

❗️ Using a wrapper library or one of the existing open source drivers as a start will greatly simplify driver development. Node.js should be preferred when developing a custom integration driver.

Integration Driver Types

The API defines two different driver types: a simple single-device driver or a multi-device instance driver.

⚠️ Only the single device instance driver is supported. The multi-device driver type will most likely not be implemented in the near future!

Single Device Instance Driver

The single-device instance driver is the default and easiest driver to develop:

• There is no concept of different or individual devices, just entities that the driver provides.
• The driver offers a list of available entities to the remote. This can be a single media player entity, or a large list of different entities from a home automation hub.
• The optional device_id property must be omitted in all messages.
• The driver may still control multiple physical devices, but from the Remote's point of view, these are just different entities provided from the same integration driver.

E.g. if smart WiFi light bulbs can be discovered by the driver and then each bulb can be provided as a light entity to the remote.

Authentication

⚠️ Custom integrations running on the remote do not support authentication.

An external integration driver can choose if the Remote Two requires authentication or not to connect to the driver.
Supported are header based token authentication during connection setup or with an application level message after the connection has been established.

See WebSocket authentication for more information.

Connection Handling

• Support multiple Remote sessions
  • An external driver should support multiple, independent WebSocket connections at the same time.
• Keep alive
  • The driver must support WebSocket Ping Pong control frames.
    Please check your WebSocket library, most libraries support this out of the box.
  • The Remote Two continuously sends ping frames and automatically closes the connection if it doesn't receive a pong within a certain time frame. The driver may also send ping frames to check if the connection is still alive.

Driver Registration

⚠️ Custom integrations running on the remote are automatically registered during installation.

An external integration driver should advertise itself over mDNS for auto-discovery and allow user configuration with the web-configurator. See mDNS advertisement for more information.

An external integration driver can optionally register itself at a remote and provide its authentication token.

See driver registration for more information.

Discover Remote Two Devices

The Remote Two can be discovered with DNS-SD. It announces itself with service type _uc-remote._tcp.

See remote DNS-SD lookup for more information.

JSON Messages

Message Format

• Only WebSockets Text message are supported at the moment.
  Binary support might be added in the future.
• All messages are serialized in JSON format.
• Text encoding is UTF-8.
• The application level protocol defines two message interactions with three different message types:
  • Request / response messages
  • Event messages

Request Messages

• A request message is of kind req.
• Every request message must include a unique id value, which must be increased for every new request.
• The request message type is specified in property msg.
• An optional msg_data object holds the request specific data.
• A request message is usually answered by a response message if not otherwise stated in the documentation.
  Exceptions are event responses, e.g. if the event can be triggered independently of the request message.

Example of a request message:

{
  "kind": "req",
  "id": 123,
  "msg": "entity_command",
  "msg_data": {
    "entity_type": "button",
    "entity_id": "button-1",
    "cmd_id": "push"
  }
}

Response Messages

• A response message is of kind resp.
• The corresponding id of the request message is given in property req_id.
• The response message type is specified in property msg.
• The status of the request operation is given in code.
• The msg_data object holds the response specific data.

Example of a response message:

{
  "kind": "resp",
  "req_id": 11,
  "msg": "available_entities",
  "code": 200,
  "msg_data": {
    "available_entities": [
      {
        "entity_id": "button-1",
        "entity_type": "button",
        "name": {
          "en": "Ring dinner bell"
        }
      }
    ]
  }
}

Event Messages

• An event message is of kind event.
• The event type is specified in property msg.
• The optional cat property denotes the event category.
• The optional ts property holds the timestamp when the event occurred.
• The msg_data object holds the event specific data.

Example of an event message:

{
  "kind": "event",
  "msg": "entity_change",
  "cat": "ENTITY",
  "ts": "2021-04-24T14:15:22Z",
  "msg_data": {
    "entity_type": "cover",
    "entity_id": "blind-1",
    "attributes": {
      "position": 72
    }
  }
}

Required Messages

For a functioning integration driver not all defined messages and optional features in the integration API have to be implemented. The mandatory messages are tagged with a pizza 🍕 emoji in the WebSocket Integration AsyncAPI definition.

Required request messages which must be processed and answered by a driver:

Required event messages which must be sent by the driver:

Common Message Flow

The basic message flow between an integration and the remote is as follows:

• The integration driver acts as server and the Remote Two initiates the connection.
• After the WebSocket connection is established to the integration driver, the remote subscribes to events of all configured entities.
• Whenever the state of the integration driver changes, the driver sends a device state event.
  This is usually the device which the driver represents or connects / communicates with. E.g. a smart device, home automation hub, cloud service, etc.
• Whenever an entity attribute of a subscribed entity changes, the driver sends an entity state event.
• The remote announces when it goes into and out of standby, so the integration driver can act accordingly.
  Note: the WebSocket connection might get disconnected during remote standby!

Establish Connection

sequenceDiagram
    participant I as Integration
    participant R as Remote

    R-)+R:     create integration driver session

    critical Establish WS connection
      R-)+I:     connect         
      alt header token
        I->>I:    authentication & version check etc
        I--)R:    authentication (OK)
      else message based auth
        I--)R:    auth_required
        R-)I:   auth
        I--)R:    authentication (OK)
      end
      Note over I,R: Authenticated WS session
      R-)R:    wait for messages
      Note over I,R: Message exchange until disconnected
      R-->-I:     disconnect
    option Authentication timeout
      R-->I:     disconnect
    option Credentials rejected
      I--)R:    authentication (401)
      R-->I:     disconnect
    end
    

Integration Driver Setup

See driver setup.

Integration Instance Configuration

After the driver has been registered and configured, the provided entities can be configured in the Remote Two.

This consists of requesting all available entities from the driver and subscribing to entity events of the chosen entities by the user.

• The subscribe_events message is only sent for entities which are configured in the Remote. I.e. only for entities which are used in a profile and placed on a page or group.
• For simplicity reasons the driver may choose to always send events for all entities. The Remote will ignore unnecessary events. However, it's recommended to limit the message exchange to entities which are actually used to save network & processing resources.
• The configured entities from the user(s) are stored in the remote-core application.
  Whenever the Remote (re)connects to the driver, only those entity identifiers are submitted in the subscribe_events message.
• The driver can use the get_version message to retrieve version and model information of the Remote.
• The driver can use the get_localization_cfg message to retrieve localization information from the remote if it deals with localized labels, values etc.

sequenceDiagram
    participant D as Device(s)
    participant I as Integration
    participant R as Remote
    participant U as UI
    participant C as configurator
    actor User

    User->>+C: setup new integration
    C->>-R:  enable integration instance

    critical Establish a connection. See normal operation.
        R-)I: connect
    end

    R-)+I:   get_driver_version
    I--)-R:  driver_version
    
    C-)+R:   get_available_entities(integration)
    R-)-I:   get_available_entities
    I--)+R:  available_entities 
    R->>R:   cache entities
    R--)-C:  available entities

    loop
        User->>+C: configure entity 
        C-)+R:   add entity
        R->>R:   store entity cfg
        R-)-I:   subscribe_events
    end

Normal Operation

During normal operation there are only a few different message exchanged between the Remote and the integration driver:

• authentication: sent by the driver after WebSocket connection is established
• subscribe_events: sent by the Remote after the WebSocket connection is authenticated
• entity_command: instruct the driver to perform an action on an entity
• entity_change: inform the Remote that an entity changed
• get_device_state: request the device state from the driver
• get_entity_states: request the current entity attributes and states

sequenceDiagram
    participant D as Device(s)
    participant I as Integration
    participant R as Remote
    participant U as UI
    actor User

    R->>R:  startup: lookup enabled integration

    R-)+I:  [WS connection] 
    I->>I:  authentication & version check etc
    I--)-R:  authentication

    R-)+I:  connect
    loop until connected
      opt
          I-->>D:  connect / initialize
      end
      I--)-R:  device_state
    end

    opt
        I-)+R:  get_version
        R--)-I: version

        I-)+R:  get_localization_cfg
        R--)-I: localization_cfg
    end
    

    R-)I:   subscribe_events

    R-)I:   get_entity_states

    D-->>I:  external state change
    I--)+R:  entity_change 
    R->>R:   store event
    R-)+U:   entity change event
    opt
        U-)-R:   get entity
        R--)-U:  entity
    end

    User->>+U: interact with entity
    U-)-R:     entity action
    R-)+I:     entity_command
    opt
        I-->>D:  update
    end
    I--)-R:    result

    opt
        D-->>+I:  state change
    end
    I-)-R:   entity_change
    R->>+R:  store event
    R-)-U:   entity change event

    R-)I:    enter_standby
    R-)I:    exit_standby
    R-)+I:   get_device_state
    I--)-R:  device_state
    R-)+I:   get_entity_states
    I--)-R:  entity_states
    R-)I:    [disconnect]

WebSocket

WebSocket is a bidirectional communication channel to exchange messages.
These messages are all events, which can be sent by the client or server at any time.
There's no support for synchronous calls or transactions. Message relations must be handled in the application level protocol and are designed with message exchange patterns.

Authentication

⚠️ Custom integrations running on the remote do not support authentication.

An external integration driver may require a token for authentication, or no authentication at all.

• During driver registration the preferred authentication type and the token can be specified.
• Default authentication method: message based if a token has been set.

Header Authentication

If header based authentication has been specified for the integration driver in the remote configuration, the remote will send the token in the auth-token header field while establishing the connection.

The WebSocket connection should then only be established by the driver if the token matches. Otherwise, the integration driver (which is the WebSocket server) must respond with http status code 401 Unauthorized and not upgrading the connection to WebSockets.

If the integration driver upgrades the WebSocket connection, the remote assumes the connection as authenticated.

Message Authentication

For integration drivers not able to use header based authentication with WebSockets (due to framework or runtime restrictions), a fallback option with text messages exists. See AsyncAPI specification for the message definitions.

1. Right after the WebSocket connection is established, the integration driver must send the auth_required event as first message:

{
  "kind": "event",
  "msg": "auth_required",
  "msg_data": {
    "name": "my-integration",
    "version": {
      "api": "0.5.0",
      "driver": "1.0.0"
    }
  }
}

2. The remote sends an authentication message:

{
  "kind": "req",
  "id": 1,
  "msg": "auth",
  "msg_data": {
    "token": "$TOKEN"
  }
}

3. The integration driver replies with the authentication event including the result code of the authentication:

   • 200: authentication succeeded, driver can be used, all API messages are accepted.
   • 401: invalid token and the driver must close the connection. The remote will mark the integration as unauthorized and stop auto-reconnect.

{
  "kind": "resp",
  "req_id": 1,
  "msg": "authentication",
  "code": 200
}

The remote will close the connection if the integration sends any other code than 200 or 401.

No Authentication

If the driver doesn't support authentication tokens, it still needs to send the authentication message with code 200 right after a connection has been established by a client.

Keep Alive

The integration should automatically close idle connections.
In order to keep a connection open, the remote sends WebSocket Ping Pong control frames at least every 60 seconds. Furthermore, an integration should also send pings to the remote to detect stale connections and handle the standby events from the remote.

Error Handling

• All response messages include a status code property.
  This code corresponds to the standard http status codes as main success / error indication.

TODO Disconnection standard status code in WebSockets: rfc6455

Integration Driver mDNS advertisement

The Remote Two uses mDNS discovery to look for local integration drivers on the same network.

If an integration driver shall be discoverable, it needs to advertise the driver service using multicast DNS:

• Service type: _uc-integration._tcp
• Instance name: unique identifier of the integration driver (driver_id in the API model).

TXT Record

Additional information is published in the TXT record.

Examples

Node.js

Using bonjour-service:

const { Bonjour } = require('bonjour-service');
const bonjour = new Bonjour();

bonjour.publish({
    name: 'my-driver',
    type: 'uc-integration',
    port: 1234,
    txt: {
        name: 'My Driver',
        ver: '1.0.0',
        developer: 'Foobar Inc',
        ws_path: '/ws',
        pwd: 'true'
    }
});

Driver Registration

An external integration driver can optionally register itself in a remote if the driver advertisement for auto-discovery is not sufficient.
This is a convenience feature if a driver would like to provide its access token without the user requiring to manually enter it, or if the driver cannot be automatically be discovered by the remote due to network setup (non-local servers, firewalls, VLAN etc.).

sequenceDiagram
    participant I as Integration
    participant mDNS
    participant R as Remote
    participant U as UI / web-configurator
    R-)mDNS: publish service
    I-)mDNS: lookup remote
    I->>+R:  register integration driver
    R-->>-I: result
    rect rgb(118, 153, 144)
    Note right of R: Integration setup
    U->>R:  get integration drivers
    U->>R:  create integration instance
    U->>R:  enable integration instance
    end
    rect rgb(51, 82, 102)
    R-)I:   start communication
    Note right of I: See integration message flow
    end

Registration REST API

Driver registration is only possible through the Remote core REST API.

See: https://github.com/unfoldedcircle/core-api/tree/main/core-api

Example

Register the simulated-light driver using the Core-Simulator Docker setup. This also works using the Simulator VM running with bridge networking:

• The integration driver is accessible at 192.168.1.115 and listens on port 9988. Adapt to your environment!
• Register driver with "driver_url:" "ws://192.168.1.115:9988"
• Use the predefined Postman collection to interact with the Simulator from the host, or use a curl call:

curl --location 'http://localhost:8080/api/intg/drivers' \
--user "web-configurator:1234" \
--header 'Content-Type: application/json' \
--data '
{
  "driver_id": "unique-driver-id or omit for auto generated uuid",
  "name": {
    "en": "Nodejs Test driver"
  },
  "driver_url": "ws://192.168.1.115:9988",
  "version": "0.0.1",
  "icon": "uc:test",
  "enabled": true,
  "description": {
    "en": "This is the way"
  },
  "device_discovery": false,
  "setup_data_schema": {},
  "release_date": "2023-04-02"
}
'

• Note: using localhost:8080 when running from the host where the Simulator service is running in a container.

After a successful registration the driver will show up in the web-configurator:

Click on the driver and start the setup:

The above example has an empty setup_data_schema, so there won't be a user interaction and the setup only consists of connecting to the driver and fetching the driver information.

The driver is now registered and the available entities will show up in the driver configuration:

Driver Setup

An integration driver can support a settings page and an interactive setup flow with the Remote Two app or web-configurator to configure the driver.

The integration driver can specify a setup_data_schema for the initial setup screen for the user to fill out. This can be as simple as an information text or a confirmation button without any further interactions. It also allows to define more sophisticated user interactions where the integration driver sends dynamic setup screens to the user, e.g. offer choices or asking for more input data.

Driver Registration

The following sequence diagram shows the happy message flow of a driver registration. Note that driver registration can be aborted at every stage with an error response or timeout.

sequenceDiagram
    participant I as Integration X
    participant M as mDNS
    participant R as Remote
    participant C as UI configurator
    actor User

    I--)M:     advertise service X

    User->>C:  Start integration discovery
    C-)+R:     start_discovery
    R--)C:     event: integration_discovery (START)
    R-)M:      lookup service
    loop
        M--)R: service(n) 
        opt Not yet registered
            R--)C: event: integration_discovery (DISCOVER) [n] 
        end
    end 
    R--)-C:    event: integration_discovery (STOP) 
    
    User->>C:  Choose integration X
    
    loop
      opt
        User->>+C: Enter access token    
      end
      opt
        User->>+C: Change driver URL   
      end
   

      opt
        User->>C: Connection test
        C-)+R:    get_discovered_intg_driver_metadata
        rect rgb(51, 82, 102)
            R-)+I:           [temporary connection]
            Note right of I: See Establish Connection
        end
        R-)I:    get_driver_metadata 
        I--)-R:  driver_metadata
        R-->I:   disconnect 
        R--)-C:  integration_driver
      end
    end
    
    User->>+C: Confirm
    C-)+R:   configure_discovered_integration_driver
    rect rgb(51, 82, 102)
        R-)+I:           [temporary connection]
        Note right of I: See Establish Connection
    end
    R-)I:    get_driver_metadata 
    I--)-R:  driver_metadata
    R-->I:   disconnect 
    R->>R:   create driver
    R--)C:   integration_driver
    R--)C:  event: integration_driver_change (NEW)

    rect rgb(51, 82, 102)
        R-)+I:           [start communication]
        Note right of I: See Establish Connection
    end

    R--)C:   event: integration_state (CONNECTING)
    R--)-C:   event: integration_state (ACTIVE)
    Note over I,R: Configured driver

Driver Setup Flow

The following sequence diagram shows the message flow after the driver registration above. Again, the happy flow is shown. An error response or timeout can occur at any step in the process.

sequenceDiagram
    participant I as Integration
    participant R as Remote
    participant C as UI configurator
    actor User

    Note over I,R: Configured driver
    R-->+I:           connection

    User->>C: Configure new integration

    User->>C: Provide settings value

    C-)+R:   setup_integration
    R->>R:   verify setup session not running & driver connected
    R--)C:   event: integration_setup_change<br>START (SETUP)
    R->>R:   create new setup session
    R--)C:   integration_setup_info (SETUP)

    R-)+I:    setup_driver
    I--)R:    result (OK)
    R--)C:   event: integration_setup_change<br>SETUP (SETUP)
    Note right of I: setup started, updates with `driver_setup_change`
    loop
      alt setup progress
        I--)R:    event: driver_setup_change<br>(`event_type: SETUP, state: PROGRESS?`)
        R--)C:    event: integration_setup_change<br>SETUP (PROGRESS)
      else user interaction
        I--)R:    event: driver_setup_change<br>(`event_type: SETUP, state: WAIT_USER_ACTION?`)
        R--)+C:   event: integration_setup_change<br>SETUP (WAIT_USER_ACTION)
        User->>C: Provide input  
        C-)+R:    set_integration_user_data
        R-)+I:    set_driver_user_data
        I--)-R:   result (OK)
        R--)-C:    integration_setup_info
      end
    end
    I--)-R: driver_setup_change<br>(`event_type: STOP, state: OK`
    R-)R:   create integration
    R--)C:  event: integration_change<br>(NEW)
    R--)C:  event: integration_state<br>(CONNECTED)
    R--)C:  event: integration_setup_change<br>SETUP (OK)
    R--)C: event: integration_setup_change<br>STOP (OK)
    R-)-R:   remove setup session

    Note over I,R: Configured integration
    R-)R:    wait for messages
    Note over I,R: Message exchange until disconnected
    I-->-R:     disconnect

Driver installation on the Remote

Starting with firmware v1.9.0, custom installation drivers can be installed on the Remote.

‼️ Custom integration drivers is a developer preview and not all features are implemented yet. See missing features.

Installation archive format

Integration driver archive requirements:

• TAR GZip archive (either .tgz or .tar.gz file suffix) with a maximum size of 100 MB.
• In the root of the archive, there must be a driver.json metadata file describing the custom integration driver.
• The driver binary must be in the ./bin subdirectory.
  • Either a statically linked aarch64 executable named driver.
  • Or a Node.js file named driver.js.
• All application files must be in one of the following subdirectories, other locations are not accessible at runtime:
  • ./bin: application binary folder.
  • ./config: optional configuration data. Path is accessible with UC_CONFIG_HOME environment variable.
  • ./data: optional application data. Path is accessible with UC_DATA_HOME environment variable.

Metadata file

The driver.json metadata file in the root of the archive describes the integration driver.

‼️ The data schema is not yet included in the Core-API, the full object is shown below. It is a reduced version of the IntegrationDriver object, without driver connection fields like driver_url, token etc.

{
  "driver_id": "foobar",
  "version": "1.0.0",
  "min_core_api": "0.20.0",
  "name": {
    "en": "Foobar special"
  },
  "icon": "custom:foobar.png",
  "description": {
    "en": "Control Foobar products",
    "de": "Steuere Foobar Produkte"
  },
  "features": [
    {
      "name": "auth.external_tokens",
      "required": true
    }
  ],
  "developer": {
    "name": "Unfolded Circle ApS",
    "email": "hello@unfoldedcircle.com",
    "url": "https://www.unfoldedcircle.com"
  },
  "home_page": "https://www.unfoldedcircle.com",
  "setup_data_schema": {
    "title": {
      "en": "Integration setup",
      "de": "Integrationssetup"
    },
    "settings": [
      {
        "id": "info",
        "label": {
          "en": "Setup process",
          "de": "Setup Fortschritt"
        },
        "field": {
          "label": {
            "value": {
              "en": "The integration will discover your Foobar products on your network. This process is automatic and can take a few minutes.",
              "de": "Diese Integration wird Foobar Produkte im Netzwerk finden. Dies ist ein Automatischer Prozess der ein paar Minuten dauern kann."
            }
          }
        }
      }
    ]
  },
  "release_date": "2024-07-21"
}

• driver_id must be at least 5 characters long and start with a lower-case letter.
  • Only lower-case letters, digits and -, _ are allowed.
  • Common system identifiers are not allowed and will be rejected (e.g. daemon, backup, etc.).
  • The uc_ prefix should not be used. This is reserved for pre-installed integrations. Any custom integrations using this prefix might get removed during a future firmware update.
• Multiple language fields are not required, but recommended.
  • If only a single language is provided, it should use the en key.
• setup_data_schema is optional if the driver provides a setup flow.
  • This is the first screen of the setup, all further screens are dynamically provided by the driver.
• ⚠️ min_core_api is not yet used.

Driver icon

A driver icon can either use a predefined icon or a custom icon. Predefined icons are prefixed with uc:, followed by the icon identifier in lowercase.

A custom driver icon can be installed automatically as custom icon resource.

1. In driver.json set the icon field to custom:$ICON_FILENAME
2. Include $ICON_FILENAME in the root of the archive.

Example driver.json (other fields omitted for simplicity):

{
  "icon": "custom:foobar.png"
}

The icon file called foobar.png must be added to the root of the archive. Icons must be of size 90x90 pixels and either in PNG or JPG format. Maximum size is 32 KB.

Installation archive example

Example of a Node.js based integration driver archive (contents of bin/node_modules are not shown for a clearer overview):

.
├── bin
│   ├── driver.js
│   ├── node_modules
│   │   ├── ...
│   │   ├── foobar
│   │   ├── uc-integration-api
│   │   ├── ws
│   │   └── ...
│   └── foobar.js
├── config
├── data
├── driver.json
└── foobar.png

• If the driver doesn't require any data or configuration files, the ./data and ./config directories can be omitted from the archive.
  • During the installation, the data and config directories are automatically created and can be accessed by the driver at runtime, no matter if they were provided in the installation archive or not.
• The driver.json file in the root folder is automatically copied to the ./bin folder during installation if it is missing.
  • If the driver requires a different driver.json file, simply include a file in the ./bin folder.
    The one in the root folder won't be copied anymore.

Restrictions

• Maximum 10 custom integrations can be installed.
• Only Node.js is supported besides a statically linked binary. Other runtimes are not supported at the moment.
  • Python integrations must pack the Python runtime into the archive.
• The integration driver runs in a sandbox. Access to devices and the filesystem is restricted.
• No symlinks are allowed. They are automatically removed during the installation.
• Executable files are only allowed in the ./bin directory.
  • No other tools are provided in the runtime environment. E.g. there is no shell available and no other tools like cp or mv.

Missing features

• Resource restrictions for integration drivers: limit maximum amount of memory and CPU usage.
• Update an installed integrations.
  • Workaround: remove and re-install.
• Resource usage: provide memory and CPU usage per integration.
  • Only the overall resource usage can be monitored with GET /api/pub/status.
• Web-Configurator support: install custom integration drivers.
  • Custom integration drivers can already be deleted in the web-configurator.

Runtime environment

The driver runs in a sandbox with limited access to the host system.

• Environment variables for the Websocket integration-API server:
  • UC_INTEGRATION_INTERFACE: network interface to bind to.
  • UC_INTEGRATION_HTTP_PORT: port number.
• The working directory is set to the binary directory.
• The binary directory is read-only.
• Node.js version: v20.16 (firmware release 1.9.3 and newer).
  • There are no pre-installed node modules.
  • An integration driver must include all required modules in the installation archive, including uc-integration-api (if used).
• File access with relative paths between bin, config, and data is not possible.
  • Environment variables must be used to retrieve the full path of these directories.
    • UC_CONFIG_HOME and HOME: configuration directory.
    • UC_DATA_HOME: data directory.
  • The returned path may not be stored, it may change with future software updates.
• Only the $UC_CONFIG_HOME and $UC_DATA_HOME directories are writeable and persisted between restarts.
  • The /tmp directory can be used for small temporary files.
    • This is a RAM file system and limited by the available free memory.
    • Temporary files are not persisted between restarts.
• A dynamic user and group is allocated when the driver is started.
  • The user and group IDs may change between driver restarts.
  • Write access to the $UC_CONFIG_HOME, $UC_DATA_HOME and /tmp directories is ensured.

⚠️ CPU and memory restrictions are not yet in place but will be enforced in a future firmware update!

• A single integration driver should not use more than 100 MB of memory.

TODO more details about sandbox environment

Network

The integration runs on the same network environment as the Remote. There is no network bridge or firewall.

• Binding ports below 1024 is not possible.

⚠️ A port-binding filter might be added in the future to prevent integrations to steal away ports of other integrations. The port range 8000-9200 and port 13333 are not allowed to be used!

Native integration drivers

TODO sysroot, available dynamic libraries

The Remote Two Cross Compile Toolchain can be used to cross-compile a native binary for the Remote.

• The driver must be compiled as a static binary for libc.
• Most dynamic libraries in the cross-compile sysroot are NOT available in the custom integration runtime environment!

Install driver

curl --location 'http://$IP/api/intg/install' \
--user 'web-configurator:$PIN' \
--form 'file=@"custom-intg.tar.gz"'

See REST Core API for more details.

Delete driver

To delete a custom integration, use the regular endpoints to delete an integration instance and driver. These are the same endpoints as for an external network integration driver:

• Delete integration instance DELETE /api/intg/instances/:intgId.
• Delete driver and installation files: DELETE /api/intg/drivers/:driverId.

See REST Core API for more details.

The instance and driver can also be deleted in the web-configurator.

Log access

Output to stdout and stderr are automatically stored with a timestamp and accessible as the other system logs:

• Get log services: GET /api/system/logs/services.
• Query logs: GET /api/system/logs?....

See REST Core API for more details.

Log files can also be downloaded in the web-configurator: Settings, Development: Logs

Web-app log viewer

⚠️ Available from firmware release v2.1.0

The Logdy web application is installed on the device to monitor integration driver log events in near real time.

• URL: http://$IP/log/
• This function is deactivated by default and the endpoint returns 503.
• The log viewer must be started using the REST Core API with the /api/system/logs/web endpoint:
  • GET request returns the current state.
  • PUT request allows to start, stop or to permanently enable the log app. A password can be set to restrict access to the web app.
• Available logs:
  • Remote core service
  • All pre-installed and custom integrations
  • Custom remote-ui service if installed
• ❗️The log processing and logdy daemon require around 170 MB of the custom integration memory pool.

Using curl to start the app:

curl --request PUT 'http://$IP/api/system/logs/web' \
  --header 'Content-Type: application/json' \
  --user web-configurator:$PIN \
  --data '{"enabled": true}'

Start and permanently enable the app, even after a reboot:

curl --request PUT 'http://$IP/api/system/logs/web' \
  --header 'Content-Type: application/json' \
  --user web-configurator:$PIN \
  --data '{"enabled": true; "autostart": true}'

Recommendations

• Node.js should be preferred for writing integration drivers.
• If using Python:
  • Use PyInstaller to create a binary distribution.
  • Use the default one-folder bundle containing an executable (--onedir). Avoid the one-file bundled executable, since it will easily use an additional 100 MB of memory!
  • See Android TV integration or Apple TV integration as an example.
• An integration driver should be limited to one process and not launch other processes.
• Use ports above 10000 if the integration needs to create an IPv4 or IPv6 server socket (besides the required WebSocket server for the integration-API).
• Preserve resources, use as little memory and CPU as possible.
• Use stdout & stderr for logging.
• Only use /tmp for small, temporary files since it is a RAM file system.

Example integrations

The following Python based integration drivers create a custom integration installation archive during build with a GitHub action:

• Android TV
• Apple TV
• Denon AVR

Bluetooth HID peripheral

‼️ This is currently a beta feature released in the v1.8.0 beta firmware.

• Restrictions and missing features
• Known issues
• BT suspend / wakeup patterns

Support articles:

• How to pair with a Bluetooth LE device

Virtual Keyboard

The virtual keyboard defines the following HID report descriptors:

• Regular keycodes (Keyboard Keypad Page (0x07))
• Consumer codes (Consumer Page (0x0C))
• System Controls (Generic Desktop Page (0x01))

The upper-case Key name in the above usage tables is used for the remote-entity commands.

HID key codes reference: https://usb.org/sites/default/files/hut1_2.pdf

Devices

Consumer devices usually only support a small subset of the HID usage definitions. Furthermore, the HID usage tables leave room for interpretation and contain multiple functions with different commands (for example media and volume control).

The device test reports are located in the ./devices folder. They are used to create the device profiles.

The template document can be used to submit pull requests for additional devices.

Device Profiles

Devices might use different commands or accept different key presses to perform certain actions. Therefore, a universal button configuration or UI screen layout would not work the same way.

Devices profiles are device specific configurations that contain default button mapping and UI configuration for a specific device.

These configurations are tested to make sure it works with the specific device.

For Android TV based streaming boxes and TV devices, try the generic Android profile if there's not a specific profile for your device.

Use the default profile if nothing else matches.

See BT device profile list for pre-defined profiles and BT device test reports for tested HID commands.
The existing device profiles are stored in GitHub at https://github.com/unfoldedcircle/core-api/tree/main/doc/bt/profiles.

Send commands with Core-API

send_cmd

The BT-remote entity supports the same remote.send_cmd command as an external remote-entity.

The command parameter supports:

• UPPER_CASE HID usage key names: regular key codes, consumer key codes, system key codes depending on prefix.
  • Regular key codes support up to 6 simultaneous keys.
    Separate key names or codes with +, e.g. KEY_A+KEY_B+KEY_C
  • Regular key codes support the following modifiers:
    LSHIFT, LALT, LCTRL, LGUI, RSHIFT, RALT, RCTRL, RGUI.
    For example: LCTRL+KEY_C or LCTRL+LALT+KEY_DELETE
• Mouse commands if starting with MOUSE_:
  • Buttons: MOUSE_BTN_1, MOUSE_BTN_2, MOUSE_BTN_3
  • X-movement: MOUSE_X_# where # is the amount of movement within: MOUSE_X_-128 .. MOUSE_X_127
  • Y-movement: MOUSE_Y_# where # is the amount of movement within: MOUSE_Y_-128 .. MOUSE_Y_127
  • Scroll-wheel: MOUSE_WHEEL_# where # is the amount of movement within: MOUSE_WHEEL_-128 .. MOUSE_WHEEL_127
• Hex-codes allow to send an arbitrary usage code, even for keys which are not defined.
  This is intended to simplify testing and for proprietary manufacturer commands.
  • 2-digit hex-code starting with 0x: regular key code, for example 0x66 for KEY_POWER.
  • 4-digit hex-code starting with 0x: consumer key code, for example 0x0030 for CONSUMER_POWER.
• Text: single character or ASCII 7-Bit text (limited to ~ 20 characters).
  • Attention: only US layout is supported (as defined in the USB HID specification), there is no support yet for different character maps.
• ‼️The repeat, delay, and hold parameters are not supported and are ignored.

Curl example:

curl --location --request PUT 'http://$IP/api/entities/$ENTITY_ID/command' \
--header 'Content-Type: application/json' \
--user 'web-configurator:$PIN' \
--data '{
  "cmd_id": "remote.send_cmd",
  "params": {
    "command": "LSHIFT+KEY_A"
  }
}'

send_key

The BT-remote entity supports an additional command remote.send_key for sending a single, predefined key code oder ASCII character. Optionally, the GUI / meta key modifier can be enabled.

The key parameter supports:

• A predefined regular key code, consumer key code, or system key code depending on prefix (KEY_, KEYPAD_, CONSUMER_, SYSTEM_).
• Mouse commands if starting with MOUSE_: see send_cmd.
• Single character (US layout).

For a regular key code, the GUI / meta key modifier can be set in the gui parameter.

Curl example:

curl --location --request PUT 'http://$IP/api/entities/$ENTITY_ID/command' \
--header 'Content-Type: application/json' \
--user 'web-configurator:$PIN' \
--data '{
  "cmd_id": "remote.send_key",
  "params": {
    "key": "KEY_E",
    "gui": true
  }
}'

Restrictions and missing features

• Number of BT connections / devices is restricted to 1 by default. Multiple Bluetooth LE connections can be enabled under "Settings, Development: Preview features".
• The Bluetooth controller is put to sleep in system standby and re-initialized at wakeup.
  • Some devices will show a disconnect & connect message or popup when the remote wakes up.
  • Different sleep behaviour can only be configured with the REST Core-API at the moment. Instructions will be published.
• Dock Bluetooth setup is not yet implemented with the new Bluetooth stack.
• Only US-ASCII character map (other languages will likely have KEY_Z / KEY_Y switched and non-letter & digit keys mapped to something else).
• Entity state handling is not yet fully implemented, only UNAVAILABLE (if not connected) and UNKNOWN (when connected) are currently used.
• Power state handling is not yet implemented if the device supports dedicated power on & off commands. Command mapping is prepared in the BT device profile files.
• Native key repeat is not yet implemented. Pressing & holding a button will send individual key presses.
  • BT remote-entity send_cmd command parameters repeat, delay, hold are ignored.
• Web-configurator requires manual refresh:
  • after the pairing confirmation, otherwise it still shows as not paired.
  • after deleting a paired device, otherwise it still shows paired.
• Pairing information is not included in backup archive.

See known device issues for more information.

Fixed in v1.9.0 beta:

• Entity command validation issue in send_cmd & send_key commands with negative mouse movement values.

Known Device Issues

• Shield TV: occasional "bonding lost" issues, under investigation
• LG TV, Samsung smart monitor M7: cannot be powered-on with Bluetooth. Most likely this applies to many other devices as well.

Not Supported Devices

• Playstation 4 & 5 do not support BLE keyboards.

BT suspend / wakeup patterns

When the remote goes into deep sleep mode, the Bluetooth controller is put to sleep and re-initialized at wakeup.

• Some devices will show a disconnect & connect message or popup when the remote wakes up.
• Different sleep behaviour can only be configured with the REST Core-API at the moment.
• Default suspend actions if not defined (empty array): disable advertisements, then put BT controller to sleep
• Default wakeup actions if not defined (empty array): restart BT controller

curl --location --request PATCH 'http://$IP/api/cfg/bt' \
--header 'Content-Type: application/json' \
--user 'web-configurator:$PIN' \
--data '{
    "suspend_actions": ["DISABLE_ADVERTISEMENTS", "SLEEP"],
    "wakeup_actions": ["RESTART"]
}'

Do nothing, best effort

{
  "suspend_actions": ["NONE"],
  "wakeup_actions": ["NONE"]
}

• keeps connection during sleep
• fastest way to send key commands after wakeup (if connection is still alive)
• least reliable with certain devices
• connection might hang after wakeup: R2 shows connected, no error while sending keys, but central shows disconnected
• does not work if central is restarted while R2 is suspended

Disconnect connections at wakeup

{
  "suspend_actions": ["NONE"],
  "wakeup_actions": ["DISCONNECT"]
}

• trigger central reconnection at wakeup
• more reliable than best effort
• some devices will show "connected" & "disconnected" popups after wakeup

Restart at wakeup

{
  "suspend_actions": ["NONE"],
  "wakeup_actions": ["RESTART"]
}

• keeps connection during sleep
• restart at wakeup to cleanly reconnect centrals
• small chance that central considers connection as non-working
• some devices will show "connected" & "disconnected" popups after wakeup

HCI sleep mode, restart at wakeup

{
  "suspend_actions": ["DISABLE_ADVERTISEMENTS", "SLEEP"],
  "wakeup_actions": ["RESTART"]
}

• disconnect central before HCI sleep mode
• restart at wakeup to cleanly reconnect centrals
• seems to be the most reliable option that centrals reconnect
• some devices will show "connected" popup at sleep & "disconnected" popup after wakeup

HCI sleep mode & resume at wakeup

About 1 sec faster than restart (~ 3sec).

{
  "suspend_actions": ["DISABLE_ADVERTISEMENTS", "SLEEP"],
  "wakeup_actions": ["ENABLE", "ENABLE_ADVERTISEMENTS"]
}

• disconnect central before HCI sleep mode
• startup BT controller at wakeup and re-enable advertisements for centrals to reconnect
• some devices will show "connected" popup at sleep & "disconnected" popup after wakeup

Virtual BLE Keyboard

The virtual keyboard defines the following HID report descriptors:

• Regular keycodes (Keyboard Keypad Page (0x07))
• Consumer codes (Consumer Page (0x0C))
• System Controls (Generic Desktop Page (0x01))

The upper-case Key name in the above usage tables is used for the remote-entity commands.

HID key codes reference: https://usb.org/sites/default/files/hut1_2.pdf

Regular keycodes (Keyboard Keypad Page (0x07))

• HID usage table: chapter 10 https://usb.org/sites/default/files/hut1_2.pdf

Consumer codes (Consumer Page (0x0C))

• Consumer Control. HID usage table: chapter 15 https://usb.org/sites/default/files/hut1_2.pdf

System Controls (Generic Desktop Page (0x01))

• System Control. HID usage table: chapter 4 https://usb.org/sites/default/files/hut1_2.pdf

BT Device Profiles

Bluetooth device profiles are tailored device configurations with ready-to-use key-mappings and prepared default UI screens. The known working key codes are defined as simple commands and directly usable in the web-configurator.

All other commands can still be used manually with the send_cmd command. Only the filtered simple commands in the profile are visible.

The remote firmware includes a set of device profiles. New profiles will be included with firmware updates. It's also possible to load custom profiles without waiting for firmware updates. Custom profiles can be uploaded with the resource endpoint in the REST Core-API. Support in the web-configurator will be added in the future.

Available device profiles:

• Default profile
• Apple TV HD & 4K
• Generic Android
• Google Chromecast
• LG WebOS TV
• onn. Streaming Device 4K pro
• Samsung Smart Monitor M7

Support articles:

• Device profiles
• How to change a device profile for a Bluetooth remote

Upload Custom Device Profiles

Custom profiles can be uploaded and managed with the existing /resources REST Core-API endpoints.

• New resource type: BtDeviceProfile
• Upload: POST /api/resources/BtDeviceProfile
  • The filename should be the value of the id field and will automatically be renamed.
  • Included profiles can be overwritten when using the same id.
• Retrieve custom profiles: GET /api/resources/BtDeviceProfile?page=1&limit=100
• Delete: DELETE /api/resources/BtDeviceProfile/:resourceId

See REST Core-API for more information.

BT Device Test Reports

• Android
• AppleTV
• Google Chromecast
• LG WebOS
• onn. Streaming Device
• Samsung Smart Monitor

Android

Notes:

• Use Button Mapper: Remap your keys to assign unused keys to commands or to launch an app. For example set the function keys to launch specific apps.
• It might make sense to filter codes according to supported Android key code names listed in:
  • https://source.android.com/docs/core/interaction/input/keyboard-devices#hid-keyboard-and-keypad-page-0x07
  • https://android.googlesource.com/kernel/msm.git/+/refs/tags/android-14.0.0_r0.78/drivers/hid/hid-input.c#875
• Key layout files show consumer codes: https://cs.android.com/android/platform/superproject/+/master:frameworks/base/data/keyboards/Vendor_0957_Product_0001.kl

Regular keycodes (Keyboard Keypad Page (0x07))

Source: https://android.googlesource.com/kernel/msm.git/+/refs/tags/android-14.0.0_r0.78/drivers/hid/hid-input.c#39