[Sofabaton X2] Trigger any command on the X2 hub, from Home Assistant

Community Guides
,
1

Hello X2 users,

The official X2 integration enables communication in both directions:

  • The X2 hub can trigger automations in Home Assistant
  • Home Assistant can trigger commands/macros/favorites on the X2 hub

The following explains how to perform the latter: trigger commands/macros/favorites on the X2 hub, from Home Assistant.

This guide assumes that the official integration is successfully installed and working.

Approach

When an X2 hub is successfully configured in the integration, it adds a remote entity to Home Assistant. It appears that the default name of this entity is remote.x2_hub.

To trigger a command on the X2 hub from Home Assistant, the type, activity_id and the key_id must be known, so they can be used when we call the remote.send_command Action.

Retrieving type, activity_id and key_id

For now, the X2 integration does not make it entirely trivial to retrieve the codes needed.
Probably the easiest way currently is to enable debug logging for the integration, and then use the virtual remote UI card the integration adds to Home Assistant to click buttons/macros/favorites.
The log file then produces everything needed to replay those commands in custom UIs, automations and scripts.

  • Enable debug logging for the Integration
    • In Home Assistant: Settings -> Devices & Services. Find the Sofabaton Hub integration and click it.
    • On the Sofabaton Hub integration page: in the top-right corner, click the 3-dots button. In the menu that appears: click Enable debug logging.
  • Open the Home Assistant log file
    • While still on the Sofabaton Hub integration page, click on your X2 HUB. This leads to your hub’s “device” page. This page contains switches for each of your Activities, as well as the remote entity which also is called X2 HUB.
    • Open a second browser and open Home Assistant. You have Home Assistant open in 2 browsers at the same time now. In the second browser, go to: Settings -> System -> Logs. In the top-right corner, click the 3-dots button. In the menu that appears, click Show raw logs.
    • At the top of the screen, where it says “Search Logs”, enter precisely this:
      [custom_components.sofabaton_hub.remote] command:
      This will filter the log for any commands sent from the integration’s virtual remote. This will likely be empty for now. Stuff will appear here soon.
  • Use the integration’s virtual remote to trigger commands on the hub
    • In the first browser, that we still have open and on the hub’s device page: Switch an Activity ON with one of the provided switches. Wait a few seconds as the hub runs its Activity start macro.
    • Click on X2 HUB (remote.x2_hub), which sits somewhere in that list with the Activity switches. Do NOT click on the switch next to “X2 HUB”, click on the text itself. A popup will open containing the integration’s virtual remote.
    • Click a single button on the virtual remote (one that you’ve actually mapped a command to)
    • Go to browser 2, the one with the log. In the top-right of the screen, click the Refresh button. You will now see a log line appear that looks a lot like this:
      command: ['type:send_assigned_key', 'activity_id:101', 'key_id:184']
      Make note of this line, so that later on you remember what command this line triggers. Keep everything after “command:”, as we will need type, activity_id and key_id later on.
      Important: It may take up to 20 seconds for the Home Assistant log to actually update with the latest data.
    • Repeat this process for every command you want to capture.

Sending commands to the hub

Now that type, activity_id and key_id are logged for the required commands, the remote.send_command action can be used to trigger the command on the X2 hub.

  • Try it out

    • In Home Assistant, go to: Developer tools -> Actions. In the Action dropdown, find remote.send_command.
    • Click Add target and find X2 HUB (remote.x2_hub) and select it.
    • Uncheck all checkboxes: Repeats, Delay seconds, Hold seconds: uncheck them all.
    • In the Command field, paste exactly the line we retrieved from the log, minus “command:”. So based on the example previously used, we would enter this under Command:
      ['type:send_assigned_key', 'activity_id:101', 'key_id:184']
    • Click Perform action

    The hub will now execute the command linked to the codes we sent it.

  • Use in an automation
    What we did in Developer tools -> Actions to try it out, can be directly applied in an automation or script. If for example we want to trigger a command whenever the office light is switched on, this would be the flow:

    • In Home Assistant, go to: Settings -> Automations & Scenes.
    • Click Create automation -> Create new automation
    • Click Add trigger -> Entity -> State
    • In the panel on the right, in the Select an entity dropdown, select light.office
    • In the same panel, in the From dropdown, select Off
    • In the same panel, in the To dropdown, select On

    This completes the Trigger for this automation. We’ve instructed it to fire whenever light.office switches from Off to On. Now let’s configure the Action to perform when our Trigger fires.

    • Back in the center of the page, click Add action -> Remote -> Send command
    • In the panel on the right, you’ll recognize the exact configuration UI as in Developer tools -> Actions, when we tried out our commands. So Add target, uncheck the checkboxes and paste in the command to trigger when the office light is switched on.
    • Click Save and give the automation a name.

The configured command will now be executed by the X2 hub whenever the office lights are switched on.

Useful information

You will find that many of the codes are predictable:

  • The "key_id"s for the remote’s hard buttons (volume up, channel down etc) are always the same, across Activities. This is how they are mapped:
    # Directional keys and OK
    "up": ["key_id": 174]
    "down": ["key_id": 178]
    "left": ["key_id": 175]
    "right": ["key_id": 177]
    "ok": ["key_id": 176]
    # Function keys
    "back": ["key_id": 179]
    "home": ["key_id": 180]
    "menu": ["key_id": 181]
    # Volume and channel
    "volume_up": ["key_id": 182]
    "volume_down": ["key_id": 185]
    "channel_up": ["key_id": 183]
    "channel_down": ["key_id": 186]
    "mute": ["key_id": 184]
    "guide": ["key_id": 157]
    # Media control
    "rewind": ["key_id": 187]
    "play": ["key_id": 156]
    "fast_forward": ["key_id": 189]
    "dvr": ["key_id": 155]
    "pause": ["key_id": 188]
    "exit": ["key_id": 154]
    # Color keys
    "red": ["key_id": 190]
    "green": ["key_id": 191]
    "yellow": ["key_id": 192]
    "blue": ["key_id": 193]
    # Custom keys
    "a": ["key_id": 153]
    "b": ["key_id": 152]
    "c": ["key_id": 151]
  • The “type” is one of 3 options:
    • send_assigned_key (the “hard” buttons)
    • send_macro_key (the macros)
    • send_favorite_key (the favorites)
  • The send_favorite_key type is actually an interesting one. It allows us to send any command directly to a “Device”, at any time, regardless of the Activity that is running, or whether one is running at all.
    In the Sofabaton hub, Devices and Activities actually exist within the same ID range. Devices start at 1 and Activities start at 101. You’ll note that when you capture “assigned_keys” or “macros” that the “activity_id” is always upwards from 101.
    Favorites are different, the “activity_id” retrieved here is upwards from 1. What is shown as an activity_id is within the hub itself in reality the device_id.
    So with that knowledge, if we retrieve the “activity_id” for our devices (in reality we’re looking for the device_id), we can use remote.send_command to directly fire any command, on any device, regardless of what else is going on with the X2 hub.
2 Likes
2

Thanks for your tutorial on “Activating X2 Buttons.” I want to use this information {‘type’: ‘send_assigned_key’, ‘activity_id’: 102, ‘key_id’: 184} to activate a X2 button with a POST command (outside of Home Assistant). I’ve tried several AI suggestions, but without success.

I successfully activated a X2 activity with a POST command: https://app1.sofabaton.com/app/keypress2?node_id=[my node id]&id=[X2 activity name]&type=1

All local X2 ports appear to be closed. How to activate a X2 button with POST?

3

There is no way to do that through the Sofabaton cloud or the hub’s local API, @Amersfoort. I don’t know if it’s an option for you, but you can create an Automation in Home Assistant that triggers on a specifically crafted POST request, into Home Assistant. That automation can then relay the command that you need to the X2 hub.

4

Has anyone here pre-ordered the Sofabaton X2 and already received the product?

I bought mine directly from their website in November 2025, during the pre-sale, and they still haven’t shipped it. There’s no tracking number; it’s just showing as “processing.”

I contacted their after-sales service, and every response pushes the delivery date further back, and this has been going on since December 2025, even though Amazon has stock available for immediate delivery.

I don’t recommend buying directly from their website; they treat customers with complete disrespect, and you don’t have the support of a marketplace to appeal to.

Is anyone else experiencing this?

5

hello @fabianosan. You’ll find more active discussions on this and other Sofabaton related topics on Reddit.
https://www.reddit.com/r/SofaBaton/

1 Like
6

I’m just trying this out on my new X2. I have enabled debug logging for the Sofabaton Hub integration, and tried running an activity and pressing buttons on the virtual remote, but nothing is getting written to the HA log when I press buttons (or when I run the activity from the X2)
Any ideas?

7

Do the buttons work though, when you press them?
With debug logging enable on the Sofabaton Hub integration, i would certainly expect things to show up in your logs when you click buttons in the virtual remote. What is your goal, are you making your own buttons, or an automation?

In the Sofabaton Virtual Remote card, in the card’s settings under Automation Assist there is a feature called Key capture (as of version 0.1.0 of the card). If you enable that, any button that you press in the remote will deliver a Notification, available in your Home Assistant side bar.

8

Yes the buttons work when I press them. Thanks for the tip re. Automation Assist - that is showing me the activity id info that I was looking for.
My goal is to initiate activities on the X2 from HA automations. Ideally I would like to switch to an activity on the X2 without executing the Startup Sequence (so that the menus/buttons become available for the relevant device, but no power or source switching operations are carried out. Do you know if/how that is possible in HA?

9

Just wanted to drop a note to say thank you! These instructions were clear and worked perfectly for me on my new X2. I am a Harmony Elite refugee, and we heavily leverage Harmony’s Alexa integration. By default, Sofabaton only supports starting and stopping Activities via Alexa which meant I lost sing the ability to mute/unmute, pause/resume, change volume, etc. I’m re-adding these Alexa capabilities via HA, and these instructions are immensely helpful (and clear!).

10

Happy to hear that @SDNick484

Just so you know, since this post i’ve also released code that makes things easier.

A script that just grabs all the codes your hub knows about and delivers them as Notifications to your sidebar.

The dashboard card has a feature called Automation Assist that generates YAML for you on button presses, so you can recreate them in your own setup.

11

Hi @itm1960. There isn’t a way to start an Activity while bypassing its startup sequence. That isn’t to say that what you’re looking for cannot be achieved, but it will make your setup a bit more brittle.

If you’re feeling adventurous, what you could do is give your Activities on the hub no startup sequence at all. You’d do this by configuring your individual devices to not manage power and input settings. Then what happens is that when the hub switches Activities, it will not switch on your devices, not switch input or any of the other things you need to happen when you switch Activities.

Then in Home Assistant you create Automations that trigger from the Activity change. How to do this depends on which integration you’re using (sofabaton_x1s or sofabaton_hub). Now, whenever Home Assistant sees the Activity change, you run an Automation. Inside this Automation you can have whatever logic you need and send whatever commands to the hub. With this you’re essentially moving the startup/shutdown sequence macros into Home Assistant, allowing for smarter sequences.

This will make your startup sequence feel slower, because there is some delay between changing the Activity and for the hub to report that it has successfully transitioned into that new Activity.
You can speed this up by staying within the approach outlined above, but instead of triggering on Activity changes, what you could do is create a Wifi Device / MQTT Device (depending on hub version), and give that device a startup sequence. Then in the Activity, you include this device and ensure it’s at the top of the startup sequence of the Activity.
Now when you start the Activity, the first thing the hub does is fire the “power” command on the Wifi/MQTT device. So now you just have your Home Assistant Automation trigger off of that power command that comes from the hub.

13

Thanks - I like that approach. I’ll give it a try.