Add command list to Remote entity

[Drafteed]

Proposal

My suggestion is to add a command list attribute to the Remote entity to allow integrations to store commands that can be sent by remote.send_command service call.

The first time I mentioned it here: home-assistant/core#83439 (comment)

My suggestion is to do it like this:

command_list:
  [keys_layout]:
    - key: Up
      command: up
    - key: Down
      command: down
      [param]: [value] # Extra send_command params for some integrations

With such a structure we cover two cases:

When the remote entity represents a virtual device in Home Assistant that sends commands to device (ATV, Bravia, Phillips, Xbox, etc.)

command_list:
  default:
    - key: Up
      command: up
    - key: Down
      command: down
    - key: Ok
      command: confirm

Remote entity can represent a physical device that sends commands (Broadlink, Harmony, another IR blaster)

command_list:
  tv:
    - key: Up
      command: up
      device: tv
    - key: Down
      command: down
      device: tv
    - key: Ok
      command: confirm
      device: tv
  dvr:
    - key: Up
      command: up
      device: dvr
    - key: Down
      command: down
      device: dvr
    - key: Ok
      command: confirm
      device: tv

Which integrations can use it:

All integrations that use Remote entity: https://www.home-assistant.io/integrations/#remote

Why is it needed?

Using this data, we can build buttons in the UI (e.g. on a special card). I think this will greatly improve the user experience.

---

Icon variant (in this case, we probably have to add a key containing the name of the icon):

[bdraco]

I think we could standardize the key list so we have a list of Home Assistant defined keys that we can map to remote commands

So if you want to send arrow_right the integration could implement

Something like async_send_predefined_command

    async def async_send_predefined_command(self, command: Iterable[str], device: str | None = None, **kwargs: Any) -> None:
        """Send a predefined command to a device."""
        raise NotImplementedError()

And it would translate arrow_right into the correct underlying send_command call for the device.

This would allow the frontend to have a defined list of keys to send as well as integrations that consume entities (ie alexa, homekit, etc) to send the right command without the user having to figure out the command set for every remote.

[felipediel]

I like the idea of having a standardized key list. We could have one for each device type, and a "custom" type that allows users to define their own commands beyond the standard list.

Instead of introducing a separate async_send_predefined_command function, we could just use the async_send_command function. To send a raw code, we can add a prefix to the command, such as protocol://.

[mvdwetering]

I recently experimented a bit with exposing a supported commands list on the remote enitity basically as mentioned by bdraco except that I used the existing send_command service as that was easy, not neccesarily best option.

So a remote entity exposes an attribute like this:

supported_commands: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, mute, volumedown, volumeup, channeldown, channelup, directiondown, directionleft, directionright, directionup, select, stop, play, rewind, pause, fastforward, previoustrack, nexttrack, menu, back, sleep, info, home

I could then build my (crude) dashboard with buttons that applied to those remote entities so as a proof-of-concept that worked. Next to dashboard it could also be used in places where the remote entity/send_command service is used in the UI e.g. with automations.

I ran into two issues/challenges that I did not see covered here.

First, how to handle universal remotes like Harmony that control multiple devices?

For example a "mute" command can apply to multiple devices (receiver, tv, sonosses). The remote.send_command has a DeviceId option to specify the device for the command, but that would not really work with the command list appoach. You would need some kind of dictionary to have a list per device and it just got messy.

Instead I exposed a remote entity for each device supported by the Harmony so each one could have its own list. This works nicely and feels quite logical to me. Only downside is that you end up with quite some remote entities (11 in my case)

The remote-entity-per-device does make the Activity part of the remote entity a bit weird for Harmony as that actually applies to the Hub and not a device that is controlled through IR. Activating an activity e.g. Watch Movie will make the Hub send commands to all configured devices to go to the correct state. For Harmony I would even go as far as to drop it from the remote entity and just keep the also existing select entity for Activities as it does the same.

I looked mostly at Harmony as I own one, but had a quick look a the other universal remotes:

• Broadlink seems to require to learn all commands and those get stored internally, does not expose what commands are learned
• Global Cache seems to support devices, has to be specified by the user in yaml.
• Kira seems to have optional support for devices, has to be specified by the user in yaml.
• Xiaomi Miio seems to require users to specify the codes in the yaml configuration, no device separation.

For these 4 universal remotes I am not sure how standardized commands would be done. Maybe just based on the name the user gave to the code? Maybe they should just expose a list of non-standardized commands? (might be out of scope of this discussion)

They could also follow the remote-entity-per-device as suggested for Harmony, but not sure how well it fits usage scenarios of those devices.

---

Second, not all integrations can detect what commands are actually supported by the specific device. E.g. for Android TV Remote there is a list of all commands that could potentially work, but not what actually works on device that is setup as manufacturers decide what to implement.

Should such an integration expose the complete list, nothing, or a basic subset that most likely works?

Having the complete list will result in non working commands unclear why to users, nothing requires the user to figure it all out, basic subset does not expose all possible options.

---

btw I looked at this topic because I am adding a remote entity to my custom integration and I needed to write a lot of documentation to explain the commands that are supported and how to send them with the remote.send_command service.

Having a list of supported commands per entity and UI support would make it a lot easier to use for a user and require less explanation.

(the text ended up being a bit long and I might be overthinking it, sorry for that)

[albaintor]

Hi,

I also created a similar request here following a discussion with the core team :
#1063

[felipediel]

Standardizing command names to decouple the user interface from the internal logic of each integration is a smart move. It promotes consistency and reusability. However, using a YAML schema for this purpose might not be the best choice. As mentioned earlier, some integrations rely on JSON to store commands, enabling them to be dynamically learned through the user interface. This capability could be compromised by a YAML-based approach.

A more adaptable solution would involve defining these constants on the remote platform and allowing each integration to import them to compose its own schema. This approach provides a consistent reference point, without restricting integrations to a single format or schema structure.