Home Assistant Companion: How to integrate it into your device

Besides the regular web app and Mac app, which use the same endpoints as the web app, Home Assistant also offers mobile apps. In this article, I want to describe its advantages compared to the previous one. I’ll be using iOS to do this: Samsung’s French partner for recycling used cell phones once tricked me into staying away from Samsung. I decided to buy Apple for better integration since I’ve owned Mac computers for the past few years.

Installation and configuration

The companion app is readily available on the Apple Store. Note that the application is both Free like beer and Free as a bird. It is provided under the Apache v2 license. If you’re 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 strength of the app lies in its user interface elements.

Some iOS apps allow you to add widgets to the user interface. I’m not a big gadget user. I have Google Calendar, weather, and a VPN on my phone.

Tools serve a dual purpose: visualization and perhaps action; If the widget doesn’t provide any action, tapping it will open the associated app. This is the case with the Google Calendar and Weather apps. My VPN tool displays a button that allows you to connect and pause.

The app offers two different types of tools, each serving a specific purpose. The first type allows the application to be opened on a specific “page”. For exampleOr Overview or Developer Tools. IMHO, it’s not very useful.

The second type allows calling Home Assistant commands. However, it requires significantly more effort. First, we must create action Things. Here’s one to turn on the light:

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

1. name, but you should probably think of it as a string identifier.

2. The label is displayed in the companion app.

3. Graphical details used by the companion application

After creating the action, you can He should Restart Home Assistant for devices to discover the new action. Once you reboot, you can add the Home Assistant widget associated with this action.

However, pressing the tool only results in slight haptic feedback. We need to connect the work to automation goal. I explained automation when we migrated away from Hue Bridge in the previous post. At that time, we created an automated system via the user interface; We can also create one in /homeassistant/configuration.yaml. We configure the action as an automation Operator.

- 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

1. Friendly alias for easier maintenance.

2. The static payload has been sent to the device.

3. The configured payload has been sent to the device. If the payload matches, the action is run.

4. Contact service.

5. Contact service on the device ID.

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

summary

Integrating Home Assistant onto your device is easy. Pressing the widget is the driver of automation – and action. You can create automation Or reuse an existing one.

Moving forward:

Originally published in A Java Geek on January 12, 2025