diff --git a/source/_integrations/icloud.markdown b/source/_integrations/icloud.markdown index d70e5aa4a1d..609c633bdea 100644 --- a/source/_integrations/icloud.markdown +++ b/source/_integrations/icloud.markdown @@ -7,44 +7,58 @@ ha_category: ha_release: "0.10" --- - -The `icloud` platform allows you to detect presence using the [iCloud](https://www.icloud.com/) service. iCloud allows users to track their location on iOS devices. +The `icloud` integration allows you to detect presence using the [iCloud](https://www.icloud.com/) service. iCloud allows users to track their location on iOS devices. It does require that your device is registered with "Find My iPhone". -To integrate iCloud in Home Assistant, add the following section to your `configuration.yaml` file: +## Setup the integration + +There is two ways to integrate iCloud in Home Assistant + +### Via the frontend + +Menu: *Configuration* -> *Integrations*. Search for "iCloud", add your credentials, click submit. + +If you add the integration for the first time for an account: +1. Choose a trusted device from the list and submit. +2. It will send you a text message on your trusted device, add the received code to the next form and submit (if you missed the right code, you will be back to the previous step, and retry). +3. You are done! + +If you already added the integration before, you are done! + +### Via the configuration file + +Add the following section to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry -device_tracker: - - platform: icloud - username: USERNAME +icloud: + - username: USERNAME password: PASSWORD - account_name: accountname ``` {% configuration %} username: - description: The username for the iCloud account. + description: Your iCloud account email. required: true type: string password: - description: The password for your given username. + description: Your iCloud account password. required: true type: string account_name: - description: The friendly name for the account_name. If this isn't given, it will use the account_name of the username (so the part before the `@` in the email address). + description: A friendly name for your iCloud account. If this isn't given, it will use the part before the `@` of the username. required: false type: string max_interval: - description: Maximum interval in minutes between subsequent location upates. This tracker uses dynamic intervals for requesting location updates. When iphone is stationary, interval will eventually be set to `max_interval` to save battery. When iphone starts moving again interval will be dynamically updated to 1 min. Note that updating interval to 1 min might be delayed by maximum `max_interval` minutes. Minimum value is 1 min. + description: Maximum interval in minutes between subsequent location updates. This tracker uses dynamic intervals for requesting location updates. When the iPhone is stationary, the interval will eventually be set to `max_interval` to save battery. When the iPhone starts moving again, the interval will be dynamically updated to 1 min. Note that updating interval to 1 min might be delayed by maximum `max_interval` minutes. Minimum value is 1 min. required: false default: 30 type: integer gps_accuracy_threshold: - description: iCloud location updates come with some gps_accuracy varying from 10 to 5000 meters. This setting defines the accuracy threshold in meters for a location update. Less accurate updates will be discarded by this tracker. This allows more precise location monitoring and fewer false positive zone changes. + description: iCloud location updates come with some gps_accuracy varying from 10 to 5000 meters. This setting defines the accuracy threshold in meters for a location update. Less accurate updates will be discarded by this tracker. This allows for more precise location monitoring and fewer false-positive zone changes. required: false - default: 1000 + default: 500 type: integer {% endconfiguration %} @@ -55,16 +69,26 @@ Low `max_interval` may cause battery drainage as it wakes up your device to get
-You may receive an email from Apple stating that someone has logged into your account. +You may receive an email and a notification from Apple saying that someone has logged into your account. + +For the notification, press "Allow", then "OK".
To disable the drainage of the battery, a dynamic interval is being used for each individual device instead of a fixed interval for all devices linked to one account. The dynamic interval is based on the current zone of a device, the distance towards home and the battery level of the device. -If 2 Step Authentication is enabled for your iCloud account. The integration will ask which device you want to use as Trusted Device and integration will send a prompt to that device with the code which you can enter in Home Assistant. The duration of this authentication is determined by Apple, but is now at 2 months, so you will only need to verify your account each two months. -2 Factor Authentication is the improved version of 2 Step Authentication, this is still not supported by the pyicloud library. Therefore it's not possible to use it with the device_tracker yet. +If 2 Step Authentication is enabled for your iCloud account. The integration will ask which device you want to use as a trusted device. The integration will send a prompt to that device with the code which you have to enter in Home Assistant. The duration of this authentication is determined by Apple. +2 Factor Authentication is the improved version of 2 Step Authentication, this is still not supported by the pyicloud library. Therefore it's not possible to use it yet. -4 services are available for this component: -- **update**: This service can be used to ask for an update of a certain iDevice. The `account_name` and `device_name` are optional. Request will result in new Home Assistant [state_changed](/docs/configuration/events/#event-state_changed) event describing current iphone location. Can be used in automations when manual location update is needed, e.g., to check if anyone is home when door's been opened. -- **lost_iphone**: This service will play the Lost iPhone sound on a certain iDevice. The `account_name` and `device_name` are optional. -- **set_interval**: This service will change the dynamic interval of an iDevice. The `account_name` and `device_name` are optional. If `interval` is used in the service_data, the iDevice will be updated with that new interval. That interval will be fixed until the iDevice changes zone or if this service is called again. If `interval` isn't used in the service_data, the interval for that iDevice will revert back to its default dynamic interval based on its current zone, its distance towards home and its battery level. -- **reset_account**: This service can be used to reset an iCloud account. This is helpful when not all devices are found by the integration or if you have added a new iDevice to your account. The `account_name` is optional. + +## In case of troubleshooting + +Go into your Home Assistant configuration `.storage` folder and delete the "icloud" folder, then retry. + +## Services + +4 services are available: + +- **update**: This service can be used to ask an update of a certain iDevice or all devices linked to an iCloud account. Request will result in new Home Assistant [state_changed](/docs/configuration/events/#event-state_changed) event describing current iPhone location. Can be used in automations when manual location update is needed, e.g., to check if anyone is home when door's been opened. +- **play_sound**: This service will play the Lost iPhone sound on your iDevice. It will still ring if you are on "Mute" or "Do not disturb" mode. +- **display_message**: This service will display a message on your iDevice. It can also ring your device. +- **lost_device**: This service will put your iDevice on "lost" mode (compatible devices only). You have to provide a phone number with a suffixed [country code](https://en.wikipedia.org/wiki/List_of_country_calling_codes) and a message.