The steps below should guide you through the process of migrating from the previous app version (1.5) to 2019.1. Before going any further, please make sure you read the breaking changes listed below.
- All notifications need to be updated as the notify service is moving from
notify.mobile_app_<device_name>. In the old version the
device_idwas set in the iOS app settings, after the update the
device_nameis taken from iOS settings (see iOS Settings App>General>About).
- Your existing device tracker entity will be obsolete. The old app used
known_devices.yamlwhereas the updated app uses the
mobile_appintegration and entity storage. Your old tracker
device_tracker.device_idwill no longer update, the new tracker will be called
- The new device tracker no longer contains attributes such as "trigger: Geographic Region entered". These have all moved to sensors that will be created via the
- The new device tracker no longer supports the
- The battery level and state sensors will be change from
sensor.battery_state. When you set up additional devices, the new sensors for those device will be distinguished with an identifier on the end (i.e.
- The send manual location update button has been removed along with the footer bar. You can now send an update manually be pulling/swiping down within the app. This will refresh the page and also send a location update. You can also send a location update by tap-and-holding the app icon.
group.all_devicesgroup was maintained by the now legacy
device_trackerservice based on
known_devices.yamlused by the
iosintegration. Since this is no longer used, device running 2019.1 will not be added to the
group.all_devices. The new
device_trackerentities can be associated with
personentities however which can be grouped in a similar way.
You need to be running Home Assistant 0.95.0 or newer. The new updated iOS app requires the following integrations to be enabled in your Home Assistant instance:
If for some reason you have disabled the default config make sure your
configuration.yaml contains at least:
For some features the following integrations also need to be enabled:
cloud:is used for securely connecting to your Home Assistant via Nabu Casa subscription via Remote UI and cloud webhooks
ios:is used if you want advanced notifications like actionable notifications and categories
Updating from Home Assistant Companion 1.5
First, apologies for the breaking changes and associated manual steps required. We have provided this guide to help you get through any issues as quickly as possible so you can enjoy the new app experience!
1 - Updating the iOS app via the App Store
Given the default settings, this may already have happened to you and your app will have auto-updated via the iOS Store. If not, manually update the app and open it.
- You will be greeted by the new onboarding experience. If you are connected to your home Wi-Fi, the app will find your Home Assistant instance - or you can manually enter the URL.
- You will be prompted to log on to your Home Assistant instance.
- Please give permissions to the app.
- Watch the app set up its integration etc.
- Once onboarding is complete, restart Home Assistant, then once Home Assistant is back online, force-close the app and reopen. This step is necessary so the notify service can register.
- You should now be ready to go with the new Home Assistant iOS app. To verify:
- Check Home Assistant Configuration -> Integrations. You should now have an entry named "Mobile App: <device_name>" containing sensors.
- Check for a new
- Check for a new
- Repeat for all iOS devices connected to your Home Assistant
An illustrated description of the onboarding process can be found in the main guide.
2 - Updating notifications and device trackers
Because the app is using a new push notification backend and the new device tracker architecture, you will need to change your automations to use the new service and tracker:
- Update your automations and configuration files (e.g.
configuration.yamland additional files you may have set up) to use the new service and
device_trackerentity. This should be as simple as using search & replace with your old and new service and entity names.
3 - Cleanup of the old iOS integration
Your iOS devices are all updated and you're up and running with the new and shiny? Great! Now it's time to clean up and get rid of the now obsolete old entries.
- Use a browser to load your Home Assistant instances and go to "Configuration" (cog icon) and then "Integrations".
- Select the iOS integration for the device you wish to upgrade.
- You should see two entities listed with the sensors
<device_id>relates to the id you specified in the old version of the app for the device you wish to upgrade. If you have multiple apps/devices configured take care to only delete the entities relating to the device you are updating. Click the cog icon next to these entities and delete the each entity in turn (the order you do this in does not matter).
- If this was your only device, you can now delete the iOS integration as a whole by going back one page and using the trash can icon in the top right. You can also delete the
.ios.conffile in your configuration directory (the same directory as
configuration.yaml) to remove all traces of the old iOS integration from the user interface.
- Open the
known_devices.yamlfile and remove the entry that has the same
<device_name>as in Step 3.
- Restart Home Assistant. The connection between your old Home Assistant Companion 1.5 App and your Home Assistant Instance should now be fully removed.
4 - Common problems
During onboarding when entering the username and password, you may get an error message and Home Assistant logs
[homeassistant.components.auth.indieauth] Timeout while looking up redirect_uri https://home-assistant.io/iOS: This happens when your Home Assistant (and likely your home network) has a broken IPv6 configuration. This usually can be resolved by fixing the IPv6 on your network or disabling IPv6 on your Home Assistant host system. This is not a bug in the app.
If you receive a 405 error code when trying to sign in after the app auto discovered your Home Assistant instance, try manually entering the address of you Home Assistant instance instead.
You receive an error containing
kCLErrorwhen trying to do a manual update (pulling down). To fix this change the location permission for the Home Assistant App to "Always" in iOS Settings>Privacy>Location Services
If you get a 404 error when trying to connect to your Home Assistant by entering a Nabu Casa URL, this is not supported. While Nabu Casa is fully supported by the app for connections, the app needs a direct connection to Home Assistant to complete setup. The best solution is to set up the app while connected to the same local network as your Home Assistant instance.
Nabu Casa: While Nabu Casa Cloud is fully supported by the app for connections, the setup is a bit more involved: To use Nabu Casa, set up the app while connected to the same local network as your Home Assistant instance. Because Apple changed the iOS location permissions (which now include the WiFi SSID) with iOS 13 some additional steps are required now:
- Grant location access for Home Assistant in iOS settings
- In the app, go to App Settings -> Connection settings and copy and paste what’s in external URL to internal URL (while on your WiFi)
- Restart the app
- You should now have the checkbox for “Connect via Cloud” available, activate that. At this point external URL won't be used anymore and the app will connect via Remote UI URL.
- Starting with Home Assistant 0.103.0
cloud:no longer is loaded as a dependency of
mobile_app:. If you did not have
default_config:configured, your cloud integration might have disappeared or become disabled.- If you get a 404 error when not using Nabu Casa. Please make sure that you are not including a trailing
/when entering your URL manually or in
configuration.yamlif using the automatic discovery when on home network.
- Starting with 0.103.0, Home Assistant Cloud Remote UI gets disabled if you have an entry for a trusted proxy on
::1in your configuration.yaml.
You receive an error stating that
mobile_appis configured and have an entry in your Home Assistant logs similar to:
Invalid config The following components and platforms could not be set up:
And one or both of
cloudlisted. This is most common when you have Home Assistant installed on top of an operating system that isn't HassOS and contains out of date dependancies. To fix this, please check all your libraries are up to date (specifically
senson.BSSIDentities are not updating and/or your app does not switch to using an internal URL when on your home Wi-Fi. You can fix both of these issue by restarting your device.
5 - Known issues
- All sensors created during onboarding are only called e.g.
sensor.battery_level. If you have multiple iOS devices you may have multiple similarly named entities. If needed, you can rename the entities via Home Assistant Configuration (cog icon on sidebar) -> Integrations -> Mobile App: iOS Device Name and prefixing the sensors with the device name. This may get resolved with future updates to the
- Due to issues between China and Google Cloud Services registering the notify service from China can be hit or miss. A workaround will be added in a future update, until then please try using a VPN to tunnel outside the Great Firewall.
- iOS Location Permissions are required for the app to use Internal_URL / External_URL on iOS 13 and newer. This is due to a change in iOS which prohibits the app to access the Wi-Fi SSID name.
- You may see the following error in your logs:
The notify.ios platform was loaded but no devices exist! Please check the documentation at https://home-assistant.io/ecosystem/ios/notifications/ for more information. This can be ignored, an update to the ios component has been submitted and a future version of Home Assistant will remove this error.
Changes from 1.5 to 2019.1
- Brand new push notification engine, powered by Firebase, for even more complex notifications than ever before, including critical notifications and much much more.
- Siri Shortcuts: Now, you can interact with your Home Assistant via Siri and the Shortcuts app.
- Apple Watch: Control your home via the Apple Watch app and monitor its status with Complications.
- Widget: Quickly trigger actions at home via a widget. Also available via home screen icon.
- Nabu Casa Cloud support: Cloudhooks and remote UI are here so you can (optionally) never open a port in your router again.
- New connection engine: now you can have internal and external URLs for total customizability.
- App settings and configuration can now be accessed from the Home Assistant side menu.
- Pull-to-refresh will reload the view and also send updated location data to your Home Assistant.