How to control Home Assistant from the Windows system tray using HA Menu

HA Menu is a small application that will run in your Windows system tray and allow you to read and control Home Assistant entities. To celebrate its release, I will be showing you how to set up HA Menu on Windows and, once the setup is complete, how to use it.

Home Assistant users running macOS will likely already have heard of the fantastic little application called HA Menu. Using HA Menu, you can control just about anything integrated with Home Assistant and also easily display sensor information, as well as currently playing media.

Downloading and installing HA Menu

To get started, download and install the latest release of HA Menu from GitHub. There is currently support for Windows and all flavours of macOS, but none for any Linux-based distros. As an Electron app, it is possible that the latter will be added at some point in the future. I am running HA Menu on a Windows 11 machine and can confirm that it is working as intended.

Once installed, I highly recommend downloading the example file (config.bar) from HA Menu's GitHub repository, as it will give you a nice jumping off point.

Importing an example configuration in to HA Menu

With the example file downloaded, open the HA Menu settings from the Windows system tray, and click on the item labelled Preferences. Inside the preferences, select the import button, and search for the config.bar file downloaded in the previous step. With the example data added, you can finally integrate HA Menu with your Home Assistant.

I suggest you import the file before adding any of your data, as the import will overwrite everything previously set up.

Integrating HA Menu with Home Assistant

At this point, you have a decision to make: Do you only want to use HA Menu when your PC or notebook is in the same network, or connected to it using a VPN, as Home Assistant's host? Or do you want the integration of HA Menu and Home Assistant to function over the internet?

If you go with the former option, you can simply use the same IP you would use to access the dashboard. Make sure that you do not add a trailing slash to the URL. In the second input box, you simply enter the port you have configured Home Assistant to use.

The second option is to use either your custom URL or one provided by Home Assistant Cloud. In this case, you can add the URL, while once again making sure there is no trailing slash. If you are using an SSL-encrypted connection, such as the one provided by Home Assistant Cloud, enter the port 443.

You will now have to switch to the Home Assistant dashboard and click on your profile in the sidebar. In the profile, scroll all the way down to the section titled Long-Lived Access Tokens. Create a new token using the appropriate button, copy it, and paste it in to the final input field in the HA Menu preferences.

You can now check whether the data you have entered is correct and if it is, HA Menu will report that it has successfully connected to your Home Assistant.

Editing the HA Menu configuration file

As you might have guessed from reading this paragraph's title, there is bad news in store if you hate manually editing configuration files. HA Menu, be it running on Windows or macOS, uses a JSON file for its configuration. Besides being able to set up the integration of HA Menu with Home Assistant and setting the refresh interval, there are no more visual options for you to adjust.

There are two ways of editing the HA Menu configuration file on Windows. You can either use the preferences window, which I found quite an impossible task, as it doesn't support some basic functions such as the tab key for multiple spaces. Or, you can use your preferred coder editor. I'm going with Visual Studio Code.

The easiest way of finding the configuration file is by clicking the button labelled Open Icons Folder in the HA Menu preferences.

Clicking on that button will open a subfolder within the ha-menu parent folder. By moving one folder up, you are in the parent folder, where you find a file named settings.json. As the name suggests, this is where you will find the full configuration. If you are using Visual Studio Code, I recommend adding a JSON extension such as this one, which will analyse your content and highlight any errors. Additionally, by clicking shift + alt + f on your keyboard, you can format the code, making it much easier to read and edit.

Adding icons to HA Menu on Windows

Before adding any entities to your Windows system tray, you might want to download some custom icons to be displayed next to any options. Make sure your icons are 32x32 in size and using the PNG format with a transparent background.

Custom icons are completely optional, as entities are not required to have an icon. If you want to keep the look of HA Menu consistent with Home Assistant, you can download any Material Design Icons from the website. The website flaticon.com is another popular source of high-quality icons.

To use the icons in your configuration, you simply place them in the icon folder you had previously accessed. To increase the DPI of icons you add, I recommend adding one of the suffixes listed here to the filename. I went with the @2x suffix, as it produced the best quality on my system.

Customizing the HA Menu icon in the Windows system tray

At this point, we meet our first big difference between the Windows and macOS version of HA Menu. As can be seen in the screenshot at the beginning of this guide, macOS applications can display a short string in the menu bar. This ability is useful if you want to display the current temperature or any other sensor's value in a glanceable position. Unfortunately, the Windows system tray only supports icons.

Another nicety we can't make use of is the ability to use template icons. Using a template, you could have the icon change, depending on what your Home Assistant weather service is reporting. This feature is not something the developer of HA Menu can easily add, as, unfortunately, only Electron apps running on macOS support template images.

This means that we only get to customize the icon and can't make use of the titleTemplate and iconTemplate options. However, the titleTemplate or title option still has to be present in the configuration, and it will be in yours if you imported the example configuration, so you might as well leave it empty. You can use the code below to configure your custom icons.

"titleTemplate": "",
"icon": "YOUR-ICON-NAME@2x.png"

If you do not wish to customize the icon and prefer the default HA Menu icon, simply remove the line from your configuration along with the comma on what is now the final line of JSON.

"titleTemplate": ""

Adding Home Assistant entities to HA Menu running on Windows

Finally, to the fun part, adding your Home Assistant entities to HA Menu. In the example below, I have also added a few extras, besides just entities, such as the open_hass function. This function will open the Home Assistant dashboard in a browser window when clicked.

A label item without any action can be used to create headers, and separators add horizontal lines to the menu. You will also see a dropdown in my configuration, this lets you locally group any entities you add.

    "config": {
        "items": [
            {
                "type": "open_hass",
                "label": "Open Home Assistant"
            },
            {
                "type": "separator"
            },
            {
                "type": "label",
                "label": "Office"
            },
            {
                "type": "separator"
            },
            {
                "type": "dropdown",
                "label": "Lights",
                "items": [
                    {
                        "type": "label",
                        "label": "Ceiling",
                        "icon": "light-bulb@2x.png",
                        "action": {
                            "domain": "light",
                            "service": "toggle",
                            "serviceData": {
                                "entity_id": "light.office_ceiling_lamp"
                            }
                        }
                    },
                    {
                        "type": "label",
                        "label": "Desk",
                        "icon": "led-strip@2x.png",
                        "action": {
                            "domain": "light",
                            "service": "toggle",
                            "serviceData": {
                                "entity_id": "light.office_desk_led_strip"
                            }
                        }
                    }
                ]
            }
        ],
        "titleTemplate": "",
        "icon": "led-strip@2x.png"
    },

Adding currently playing media to HA Menu

Another thing HA Menu on Windows allows you to do is to display currently playing music on any of your integrated media players. To achieve this, simply add a new label, and set the labelTemplate to any of the many possibilities.

The same labelTemplate can also be used with dropdowns. In this example, I have set the dropdowns title to be the currently playing track and the options being play and stop.

{
    "type": "label",
    "labelTemplate": "{{ state_attr('media_player.bedroom_speaker', 'media_title')}}",
    "icon": "musical-notes@2x.png"
},
{
    "type": "dropdown",
    "labelTemplate": "{{ state_attr('media_player.bedroom_speaker', 'media_title')}}",
    "items": [
        {
            "type": "label",
            "label": "Play",
            "action": {
                "domain": "media_player",
                "service": "media_play",
                "serviceData": {
                    "entity_id": "media_player.bedroom_speaker"
                }
            }
        },
        {
            "type": "label",
            "label": "Stop",
            "action": {
                "domain": "media_player",
                "service": "media_stop",
                "serviceData": {
                    "entity_id": "media_player.bedroom_speaker"
                }
            }
        }
    ]
}

Wrapping up: A useful companion for Home Assistant

HA Menu will keep its place in my Windows system tray. That is how much I have come to enjoy using it. I am a bit disappointed at the extras macOS users get, but I am aware that that is purely Windows' fault and not the developers. With Microsoft's decision to strip the weather information out of the menu, a relatively new feature to Windows 10, I would love to be able to display just the temperature where I can instantly read it.

I am well aware that there is much more you can do with HA Menu on Windows, but I do hope this guide has shown you some possibilities, which might help you realize your next big idea. As always, the comments are open for your configurations and suggestions.