DEV Community

Cover image for The Home Assistant companion app
Nicolas Fränkel
Nicolas Fränkel

Posted on • Originally published at blog.frankel.ch

14 1 1 1 1

The Home Assistant companion app

Besides a regular webapp and a Mac app, which uses the same endpoints as the webapp, Home Assistant also provides mobile apps. In this post, I want to describe its advantages over the former. I'll use iOS to do this: Samsung's French partner to recycle used mobiles tricked me once, and I moved away from Samsung. I decided to buy Apple for better integration since I've had Mac computers for the last few years.

Installing and configuring

The companion app is readily available at the Apple Store. Note that the app is both free as a beer and free as a bird. It's provided under the Apache v2 License. If interested, the source code is on GitHub.

Once installed, you must configure at least one Home Assistant server. At this point, you should get the same UI as the web app. The app's power lies in its widgets, though.

Widgets

Some iOS applications allow you adding widgets to the UI. I'm not a massive user of widgets. I've Google Calendar, the Weather, and a VPN on my phone.

Widgets serve a dual purpose: visualization and possibly action; if a widget doesn't offer an action, pressing it will open the associated app. That's the case with the Google Calendar and Weather apps. My VPN widget displays a button allowing you to connect and pause.

The companion app widget

The app offers two distinct kinds of widgets, each serving a specific purpose. The first kind allows opening the app on a specific "page", e.g., Overview or Developer tools. IMHO, it's not very useful.

The second kind allows calling HA commands. However, it requires significantly more effort. First, we must create action objects. Here's one to switch the light on:

actions:
  - name: OfficeLightsOn                 #1
    label:
      text: "Turn ON Office Lights"      #2
    icon:
      icon: lightbulb-on-outline         #3
      color: "#ffff00"                   #3
    show_in_carplay: false
    show_in_watch: true
Enter fullscreen mode Exit fullscreen mode
  1. Name, but you should probably think about it as a String ID
  2. The label shown in the companion app
  3. Graphic details used by the companion app

After creating the action, you must restart Home Assistant for devices to detect the new action. Once restarted, you can add a Home Assistant widget that is bound to that action.

Adding a widget to the iPhone, featuring the previously created action(s)

However, pressing the widget does nothing but a slight haptic feedback. We need to bind the action to an automation object. I explained automations when we migrated away from the Hue bridge in the previous post. At the time, we created an automation via the UI; we can also create one in the /homeassistant/configuration.yaml. We configure the action as the automation's trigger.

- alias: Turn On Office Lights On        #1
  trigger:
    - platform: event                    #2
      event_type: ios.action_fired       #2
      event_data:
        actionName: OfficeLightsOn       #3
  action:
    - service: light.turn_on             #4
      entity_id: light.all_office        #5
Enter fullscreen mode Exit fullscreen mode
  1. Friendly alias for easier maintenance
  2. Fixed payload sent to the device
  3. Configured payload sent to the device. If the payload matches, it will trigger the action
  4. Service to call
  5. Call the service on the device ID

Now, pressing the widget turns on the light as expected.

Summary

Integrating Home Assistant on your device is straightforward. The pressing on the widget is the trigger for an automation - an action. You can create the automation or reuse an existing one.

To go further:


Originally published at A Java Geek on January 12nd, 2025

Do your career a big favor. Join DEV. (The website you're on right now)

It takes one minute, it's free, and is worth it for your career.

Get started

Community matters

Top comments (1)

Collapse
 
william_woody_89523480d2d profile image
William Woody

This is far from an overview of the Home Assistant companion app. Very far.

This is perhaps merely a brief guide to creating custom widgets for controlling a device in Home Assistant in iOS.

The Home Assistant companion app, as a direct and full interface to a Home Assistant instance mirroring that of the web app page, is much more powerful than as described here in this article.

👋 Kindness is contagious

Discover a treasure trove of wisdom within this insightful piece, highly respected in the nurturing DEV Community enviroment. Developers, whether novice or expert, are encouraged to participate and add to our shared knowledge basin.

A simple "thank you" can illuminate someone's day. Express your appreciation in the comments section!

On DEV, sharing ideas smoothens our journey and strengthens our community ties. Learn something useful? Offering a quick thanks to the author is deeply appreciated.

Okay