Home Assistant and Apple Watch – Actions and Complications Guide

Posted on by

Introduction

In this guide, I’ll be going through how to make the most of the integration between Apple Watch and Home Assistant including Actions and an overview and examples of key complication types for the Apple Watch.

I’m using the new Apple Watch Series 8 and the latest watch OS 9 (as of September 2022).

If you haven’t seen my video on enabling remote access and installing and integrating the iOS app, please check it out first.

For the purposes of the video and to keep it simple, I’m going to be doing all of this via the iOS Home Assistant and Watch Apps and the Apple Watch itself.

Adding an Action

First off, let’s add an Action. Despite the name, an action is a trigger that you can use from your Apple Watch for a Home Assistant automation.

  • From the Home Assistant app on your phone, Go to Settings –> Companion app
  • Then select Actions
  • Tap on the + symbol to add a new action
  • Then select a name, display text, color and icon
  • In this example, the action will be to toggle a switch
  • Keep the name simple as you will need to use this in the next step
  • Name: Light
    • Text: Light Switch
    • And then within the Icon screen, search for an appropriate icon. I’ve searched for the toggle_switch icon.
    • The screen shows a preview of what it will look like and you can also change the background colour
    • Once you have completed this, Save, go back to the previous screen and make sure you click done in the top right to save the settings in the companion app.

Linking Action to Automation

Next we need to link the iOS action we just created, to do perform an actual action. In this example, I will link the action to toggle a switch.

  • Go to Settings –> Automations & Scenes
  • Then create a new automation
    • Event type: ios.action_fired
    • Event data: actionName: “<name of action>”. In my case, we have selected light.
  • Action:
    • Service: switch:toggle
    • Choose Entity. For example, the entity I selected was my Front Door Light Switch
  • Save and select a name for your automation. For example, ‘Watch Light Automation’.

Access Action via Apple Watch

  • To use your actions on your watch, you can access this via the Home Assistant App
  • Simple go to your app screen and find the Home Assistant App
  • The action that was just created should be visible
  • Press it to toggle and fire the automation and press again to turn it off
  • You can see that the switch turned on from the history of the automation

That’s all there is in the Apple Watch Home Assistant App, however another way to quickly access the action is through adding a Home Assistant complication to your watch face and tapping on all complications will open the same actions screen.

Complication Overview

The next functionality with Home Assistant and the Apple Watch is the use of Complications and this definitely can get complicated. Let’s take a quick complication 101.

The term ‘complication’ is historically used for mechanical timepieces and regular watches and refers to additional functionality beyond simple time.

Let’s look at the positioning and examples of an Apple Watch Face. The positioning is important to understand when you build out the complications and configure them into a watch face.

Source: Apple.com

As of the recent watchOS 9 update, a number of complication templates are no longer working. The key complication templates to note that are currently working in the Home Assistant app as of the recent iOS 9 update are:

Circular

These are useful for showing quick round shaped values for ranges and simple status on Infograph and Modular watch faces:

Corner

Corner layouts show images, text and gauges in the corners of supported watch faces such as Infograph:

Inline

The Large Inline layout can be used at the bottom of a watch face such as Utility or Motion. These allow icons and text:

Rectangular

Rectangular layouts show images, text, gauges and titles across a large rectangular region:

As of the most recent iOS update, templates which are now deemed as legacy appear to no longer work in the Home Assistant app and are no longer visible. For those with existing complications, it looks like you have no current option but to re-create using the supported templates until there is a fix. The Home Assistant community has raised a bug which is still being investigated.

The impacted templates include:

  • Circular small
  • Modular Small
  • Modular large
  • Extra Large

I’d recommend avoiding any of these as they will not be visible and you will run into compatibility issues until the app has been updated to either support or remove them.

Template GroupTemplateWorking
Circular SmallCircular SmallNo
Extra LargeExtra LargeNo
GraphicBezel–
GraphicCircularYes
GraphicCornerYes
GraphicRectangularYes
ModularLargeNo
ModularSmallNo
UtilitarianLargeYes
UtilitarianSmall–
UtilitarianSmall Flat–

Complication Limitations

  • Now there are some limitations with Complications including:
    • Automatic updates. Complications only update within a few minutes of 00, 15, 30 and 45 as Apple limits how often they are able to be updated
    • Manual Updates – You can do manual updates, however these are limited to 50 a day. Technically, you can add this as a service call, but it is limited and so complications that you want to refresh frequently might need to be reconsidered until push updates are supported.
  • App Delays – There are also app delays with complications and it takes a bit of time for the complication to reflect and be accessible in the app. You may need to play around and add/remove complications until it is visible in the Watch app. Make sure once you create, click done on the companion section of the Home Assistant app to ensure any updates get saved.

Key Complication Screens

There are three key screens that you need to get familiar with when creating complications. These are the:

  • Complication Management Screen: This is in the Home Assistant Companion App to manage created complications
  • The Face Management part of the Apple Watch app: This is to select the location of complications and build out your watch face
  • The Apple Watch Screen: To view the watch face

Complication Examples

Ok, Let’s go through each key working template using data from Home Assistant. We’ll start with the circular template.

Circular

  • Template: Closed Gauge Image
    • Gauge: {{ iif(is_state(‘switch.front_door_light’, ‘on’), 1, 0 ) }}
      In this example, I have used a binary state for the switch which will be on or off and set the formula to return 1 or 0 to add or remove the ring around the complication.
    • Icon: Light
  • Template: Open Gauge Image
    This template allows a gauge with an icon
    • Centre: {{ states(‘sensor.epson_wf_3520_series_black_ink’) }}
    • Gauge: {{ float(states(‘sensor.epson_wf_3520_series_black_ink’)) / 100 }}
      I’ve had to add in the formula to convert the status to a float to support the gauge value.
    • Icon: Printer
  • Template: Open Gauge Simple Text
    • Centre: {{ states(‘sensor.epson_wf_3520_series_black_ink’) }}
    • Bottom: BLK
    • Gauge: {{ float(states(‘sensor.epson_wf_3520_series_black_ink’)) / 100 }}
      The difference here to the previous template is that you can use text instead of an icon.
       
  • Template: Open Gauge Range Text
    • Centre: {{ states(‘sensor.epson_wf_3520_series_black_ink’) }}
    • Leading: 0
    • Trailing: 100
    • Gauge: {{ float(states(‘sensor.epson_wf_3520_series_black_ink’)) / 100 }}
      The Range template allows you to specify a different range e.g. if you wanted to show between two different values. In this case, I will still use 0 to 100.

Corner

  • Template: Gauge Text
    • Leading: 0
    • Outer:  {{ states(‘sensor.epson_wf_3520_series_black_ink’) }}
    • Trailing: 100
    • Gauge: {{ float(states(‘sensor.epson_wf_3520_series_black_ink’)) / 100 }}
    • Style
      • Fill – Shows a line completed up to the value
      • Ring – Shows a filled line with a ring on the value
  • For the corner, the values are similar to the other circular templates that we just went through and so will go through a gauge text example. This includes the leading and trailing values of the gauge with style fill showing the fill line up to the value or ring which shows a circle at the state value along a line.

Rectangular

  • The next template example is the rectangular standard. I’ve added in the Printer Ink header with the two body lines showing black and cyan ink levels
  • Template: Standard Body
    • Header: Printer Ink
    • Body 1: Black: {{ states(‘sensor.epson_wf_3520_series_black_ink’) }}
    • Body 2: Cyan: {{ states(‘sensor.epson_wf_3520_series_black_ink’) }}
    • Icon: Printer
  • Template: Text Gauge
    • Header: {{ states(‘sensor.epson_wf_3520_series’) }}
    • Body 1: {{ states(‘sensor.epson_wf_3520_series_black_ink’) }}
    • Gauge: {{ float(states(‘sensor.epson_wf_3520_series_black_ink’)) / 100 }
    • Style
      • Fill – Shows a line completed up to the value
      • Ring – Shows a filled line with a ring on the value

Inline

  • For the large inline example (Utilitarian Large), I’ll add some extra text to show PRINTER BLACK INK and the state and the % symbol at the end.
  • Template: Flat
  • Centre: PRINTER BLACK INK {{ states(‘sensor.epson_wf_3520_series_black_ink’) }}%
  • Icon: printer

Conclusion

Thanks for getting to the end of this guide. Hopefully you have a better understanding of the Apple Watch integration with Home Assistant and now have some ideas on how to build out your actions and complications based on your own setup.