12/3

docs/chapters/0.1-migrating-v2.4-to-v3-gh.md

@@ -0,0 +1,154 @@
+# Migrating iCloud3 from v2.4.x to v3
+
+iCloud3 v3 is a true Home Assistant Integration that is configured on the **HA Settings > Devices & Settings > Integration > iCloud3** screen. That means the yaml parameters in the *configuration.yaml* and *config_ic3.yaml* files are no longer used or needed. 
+
+When iCloud3 is added to HA on Integrations screen, the parameters in these files are migrated to the new internal files (*config/.storage/icloud3/configuration*). The migration should be painless but it is required that that they be reviewed before they will be used. This is done on the configuration screens using *The Configurator* described in general in the *iCloud3 Components* chapter and in detail in the *Configuration Parameters* chapter.
+
+!> MPORTANT - YOU MUST REVIEW THE MIGRATION RESULTS ON THE CONFIGURATION SCREENS - The 'old yaml' parameters will be migrated again and again until they are reviewed with The Configurator. Once the review is done, the parameters updated in the 'new' Configurator will be used. The 'old yaml' parameters can then be deleted.
+
+Do the following:
+1. Install iCloud3 from HACS (or manually).
+
+   !> BETA VERSION - Follow the Beta Install Instructions instead of using HACS.
+
+2. Add the iCloud3 integrations component (*iCloud3 Configurator*). 
+
+3. Open *The Configurator* and review each of the screens. The most important screens are:
+   - *iCloud Account Login Credentials* screen - Verify the username/password. Select *Show/Hide Username/password* in the bottom area and click *Submit* to see them.
+   - *iCloud3 Devices > iCloud3 Device Tracker Entities* - Review each of the devices you are tracking. The iCloud3 device_tracker entity name does not have to match the name on the iPhone or other device any longer. It can be anything you like. The FamShr (Family Sharing List members) are selected from a list using data returned from your iCloud account. The actual name on the *Settings App > General > About > Name* field (Gary-iPhone) is displayed in the list. 
+   - Verify the selected devices are correct and reselect it if is not. Do the same for the Find-My-Friends, the iOS App and the picture that is displayed on the device_tracker entity and the badge sensor.
+
+   - Go through the other screens, review the parameter values and change any that did not migrate correctly.
+
+4. Exit *The Configurator*. Select *Restart Now*, then click *Submit* to restart iCloud3.
+
+   The device_tracker and sensor entities will be recreated, tracking will resume and the Event Log will redisplay the startup process stages before the devices are relocated.
+
+5. If everything appears to work properly, delete (or comment out) the iCloud3 v2.4 parameters in the *configuration.yaml* file.
+
+These steps are described below.
+
+
+
+
+------
+### Step #1 - Install iCloud3
+
+- **Easy Way** -  Use HACS
+  1. Open HACS.
+  2. Select **Integrations**.
+  3. Type **iCloud3** in the Search Bar at the top of the screen. 
+  4. Select **iCloud3 Device Tracker**.
+  5. Select **Download**, then select **Download** again in the popup window.
+  6. **Restart Home Assistant**.
+
+- **Hard Way** - Manual Installation
+  1. Download the *icloud3.zip* file from the *https://github.com/gcobb321/icloud3* iCloud3 GitHub Repository.
+  2. Unzip the file into the *config/sustom_components/icloud3* directory.
+  3. **Restart Home Assistant**
+
+!> AGAIN, BETA VERSION - Follow the Beta Install Instructions instead of using HACS.
+
+
+------
+### Step #2 - Set up the iCloud3 Integration
+
+iCloud3 is a Home Assistant Integration and is configured on the Integrations screens.
+
+1. Select **☰ > HA Settings > Devices & Services > Integrations**.
+2. Select **+ Add Integration** in the lower-right hand corner.
+3. Type **iCloud3**. Then select **iCloud3** from the list of Integrations. 
+   The iCloud3 configuration entry will be added to the *Integrations* screen and the screen below is displayed with the other Integrations that have been installed.
+
+![](../images/cf-configurator.png)
+
+4. Select **Configure** to open *The Configurator* and display the menu below. 
+
+![](../images/cf-menu-1.png)
+
+
+------
+### Step #3 - Review the Configuration Parameter screens
+
+The iCloud3 parameters need to be reviewed to verify the migration was performed correctly.
+
+Open *The Configurator* to display the menu sceen if it is not already displayed.
+
+1. Select **☰ > HA  Settings > Devices & Services > Integrations**
+2. Select **iCloud3 > Configure** as shown above.
+
+
+#### iCloud Account & Login Credentials screen  {docsify-ignore}
+
+1. Select **Show/Hide Username/Password** at the bottom and click **Submit** to display them and correct their values if necessary. They are normally hidden from view for security purposes and the password is encrypted in the configuration file.
+2. Select **Login**, then select **Submit**.  The iCloud account will be logged into and the iPhones, iPads and other devices associated with the account will be loaded if you changed them.
+
+![](../images/cf-acct-login.png)
+
+
+
+#### iCloud3 Devices screen  {docsify-ignore}
+
+All of the devices being tracked are listed on this screen. 
+
+1. Select **Update Device**, then select **Next** to display the *Update Tracked iCloud3 Device* screen.
+
+![](../images/cf-device-list.png)
+
+
+#### Update Tracked iCloud3 Device screen  {docsify-ignore}
+
+This screen is used to specify various parameters used by iCloud3 to track the device. The major parameters are:
+- The Family Sharing List and the Find-my-Friends device from your iCloud account that is associated with this iCloud3 device.
+- The iOS App device tracker entity tha will be monitored for location changes, zone enter/exit triggers and battery information.
+- The picture to be displayed on the *device_tracker.[devicename]* entity and the *sensor.[devicename]_badge* entity.
+
+Verify the parameters migrated correctly and make any necessary changes.
+
+![](../images/cf-device-update.png)
+
+
+-----
+
+### Step #4 - Exit *The Configurator* and Restart iCloud3
+
+Since a tracked device was updated, iCloud3 will restart when you exit *The Configurator*.
+
+1. Select **Return**, then select **Next** to display the **Main Menu** screen.
+2. Select **Exit and Restart**, then select **Next** to exit *The Configurator* and display the *Confirm Restarting iCloud3* screen.
+
+![](../images/cf-confirm-ic3-restart.png)
+
+1. Select **Restart Now**, then select **Next**.
+2. Select **Finish** on the final *Success, Options Successfully Saved* screen.
+3. iCloud3 will restart, the device_tracker and sensor entities are created, the device will be located and tracking will begin.
+
+
+#### The Other Configuration Screens  {docsify-ignore}
+
+Review the other screens just to see what is configurable. Nothing has to be done right now to get you up and running. The your previous parameters or their default values will work fine. The other screens are shown and described in *Configuring iCloud3 using The Configurator* in the next chapter
+
+
+------
+### Step #5 - Restart Home Assistant (if necessary)
+
+***If you successfully added the Lovelace tracking and Event Log cards and the tracking data is displayed, you are done.***
+
+Otherwise, restart  Home Assistant to make sure iCloud3 starts, tracking begins and the Tracking and Event Log screens display correctly. 
+
+When iCloud3 starts, it generally does the following:
+
+- Checks the directory settings
+- Loads the configuration parameters
+- Loads the tracked and monitored devices
+- Accesses the your iCloud account to get the devices tied to your account
+- Gets the information for the devices using the HA Companion App
+- Ties everything together
+- Starts tracking. 
+
+The results of this process are shown in the Event Log and detailed in *Event Log During Startup* in the *Understanding iCloud3* chapter. If there are problems:
+
+- Check the Event Log (it should display something) for error messages.
+- Check the HA Log file (*config/home-assistant.log*)
+- Verify that the device_tracker and sensor entities are set up. The *Devices & Settings > Integrations > iCloud3* entry should show at least one device_tracker and some entities for that device.
+

docs/chapters/0.1-migrating-v2.4-to-v3.md

@@ -4,22 +4,31 @@ iCloud3 v3 is a true Home Assistant Integration that is configured on the **HA S
 
 When iCloud3 is added to HA on Integrations screen, the parameters in these files are migrated to the new internal files (*config/.storage/icloud3/configuration*). The migration should be painless but it is required that that they be reviewed before they will be used. This is done on the configuration screens using *The Configurator* described in general in the *iCloud3 Components* chapter and in detail in the *Configuration Parameters* chapter.
 
-!> IMPORTANT - The 'old yaml' parameters will be migrated again and again until they are reviewed with The Configurator. Once the review is done, the parameters updated in the 'new' Configurator will be used. The 'old yaml' parameters can then be deleted.
+!> IMPORTANT - YOU MUST REVIEW THE MIGRATION RESULTS ON THE CONFIGURATION SCREENS - The 'old yaml' parameters will be migrated again and again until they are reviewed with *The Configurator*. Once the review is done, the migrated parameters (and any changes that were made) will be used. The 'old yaml' parameters can then be deleted.
+
+Generally, you will do the following:
+1. Install iCloud3 from HACS (or manually). 
+
+   !> BETA VERSION - Follow the Beta Install Instructions instead of using HACS.
 
-Do the following:
-1. Install iCloud3 from HACS (or manually).
 2. Add the iCloud3 integrations component (*iCloud3 Configurator*). 
+
 3. Open *The Configurator* and review each of the screens. The most important screens are:
    - *iCloud Account Login Credentials* screen - Verify the username/password. Select *Show/Hide Username/password* in the bottom area and click *Submit* to see them.
-   - *iCloud3 Devices > iCloud3 Device Tracker Entities* - Review each of the devices you are tracking. The iCloud3 device_tracker entity name does not have to match the name on the iPhone or other device any longer. It can be anything you like. The FamShr (Family Sharing List members) are selected from a list using data returned from your iCloud account. The actual name on the *Settings App > General > About > Name* field (Gary-iPhone) is displayed in the list. Verify it is correct. Do the same for the Find-My-Friends and the iOS App and picture.
-   - Go through the other screens and change any parameter values that did not migrate correctly.
-4.  Exit *The Configurator*. Select *Restart Now*, then click *Submit* to restart iCloud3.
+
+   - *iCloud3 Devices > iCloud3 Device Tracker Entities* - Review each of the devices you are tracking. The iCloud3 device_tracker entity name does not have to match the name on the iPhone or other device any longer. It can be anything you like. The FamShr (Family Sharing List members) are selected from a list using data returned from your iCloud account. The actual name on the *Settings App > General > About > Name* field (Gary-iPhone) is displayed in these lists. 
+
+     Verify the selected devices are correct and reselect it if is not. Do the same for the Find-My-Friends, the iOS App and the picture that is displayed on the device_tracker entity and the badge sensor.
+
+   - Go through the other screens, review the parameter values and change any that did not migrate correctly.
+
+4. Exit *The Configurator*. Select *Restart Now*, then click *Submit* to restart iCloud3.
 
    The device_tracker and sensor entities will be recreated, tracking will resume and the Event Log will redisplay the startup process stages before the devices are relocated.
 
 5. If everything appears to work properly, delete (or comment out) the iCloud3 v2.4 parameters in the *configuration.yaml* file.
 
-These steps are described below.
+These steps are described in detail below.
 
 
 
@@ -40,7 +49,7 @@ These steps are described below.
   2. Unzip the file into the *config/sustom_components/icloud3* directory.
   3. **Restart Home Assistant**
 
-
+!> AGAIN, BETA VERSION - Follow the Beta Install Instructions instead of using HACS.
 
 
 ------
@@ -50,31 +59,35 @@ iCloud3 is a Home Assistant Integration and is configured on the Integrations sc
 
 1. Select **☰ > HA Settings > Devices & Services > Integrations**.
 2. Select **+ Add Integration** in the lower-right hand corner.
-3. Type **iCloud3**. Then select **iCloud3** from the list of Integrations. 
-   The iCloud3 configuration entry will be added to the *Integrations* screen and the screen below is displayed with the other Integrationsthat have been installed.
-
-![](../images/cf-configurator.png)
-
-4. Select **Configure** to open *The Configurator* and display the menu below. 
+3. Type **iCloud3**. Then select **iCloud3** from the list of Integrations. The iCloud3 entry will be added to the *Integrations* screen.
 
-![](../images/cf-menu-1.png)
 
 
 ------
 ### Step #3 - Review the Configuration Parameter screens
 
 The iCloud3 parameters need to be reviewed to verify the migration was performed correctly.
 
-Open *The Configurator* to display the menu sceen if it is not already displayed.
+Open *The Configurator*:
 
-1. Select **☰ > HA  Settings > Devices & Services > Integrations**
-2. Select **iCloud3 > Configure** as shown above.
+1. Select **☰ > HA  Settings > Devices & Services > Integrations** if the Integrations screen is not already displayed from Step #2.
+2. Select **iCloud3 > Configure** as shown below.
 
+![](../images/cf-configurator.png)
+
+3. The Menu screen is displayed.
+
+   ![](../images/cf-menu-1.png)
+
+​	
 
 #### iCloud Account & Login Credentials screen  {docsify-ignore}
 
-1. Select **Show/Hide Username/Password** at the bottom and click **Submit** to display them and correct their values if necessary. They are normally hidden from view for security purposes and the password is encrypted in the configuration file.
-2. Select **Login**, then select **Submit**.  The iCloud account will be logged into and the iPhones, iPads and other devices associated with the account will be loaded if you changed them.
+1. Select **Show/Hide Username/Password** at the bottom and click **Submit** to display them. Correct them if necessary. They are hidden from view for security purposes. Additionally, the password is encrypted in the configuration file.
+
+2. Select **Login**, then select **Submit**.  The iCloud account will be logged into and the lists of iPhones, iPads and other devices associated with the account will be set up. 
+
+   Note: iCloud3 will attempt to do a login when the it is loaded by HA. 
 
 ![](../images/cf-acct-login.png)
 
@@ -89,37 +102,44 @@ All of the devices being tracked are listed on this screen.
 ![](../images/cf-device-list.png)
 
 
+
 #### Update Tracked iCloud3 Device screen  {docsify-ignore}
 
 This screen is used to specify various parameters used by iCloud3 to track the device. The major parameters are:
+
 - The Family Sharing List and the Find-my-Friends device from your iCloud account that is associated with this iCloud3 device.
-- The iOS App device tracker entity tha will be monitored for location cahnges, zone enter/exit triggers and battery information.
+- The iOS App device tracker entity tha will be monitored for location changes, zone enter/exit triggers and battery information.
 - The picture to be displayed on the *device_tracker.[devicename]* entity and the *sensor.[devicename]_badge* entity.
 
 Verify the parameters migrated correctly and make any necessary changes.
 
 ![](../images/cf-device-update.png)
 
 
+
 -----
 
 ### Step #4 - Exit *The Configurator* and Restart iCloud3
 
 Since a tracked device was updated, iCloud3 will restart when you exit *The Configurator*.
 
-1. Select **Return**, then select **Next** to display the **Main Menu** screen.
-2. Select **Exit and Restart**, then select **Next** to exit *The Configurator* and display the *Confirm Restarting iCloud3* screen.
+1. Display the **Main Menu** screen. Select **Save**, or **Cancel**, or **Return** depending on the screen that is displayed and select **Submit**..
+2. Select **Exit and Restart** on the Menu screen, then select **Next** to display the *Confirm Restarting iCloud3* screen. 
 
 ![](../images/cf-confirm-ic3-restart.png)
 
-1. Select **Restart Now**, then select **Next**.
-2. Select **Finish** on the final *Success, Options Successfully Saved* screen.
-3. iCloud3 will restart, the device_tracker and sensor entities are created, the device will be located and tracking will begin.
+3. Select **Restart Now**, then select **Next**.
+4. Select **Finish** on the final *Success, Options Successfully Saved* screen.
+5. Redisplay the Lovelace screen showing iCloud3 device information you have been using and/or the Event Log.
+
+iCloud3 will restart, the device_tracker and sensor entities are created, the device will be located and tracking will begin.
+
 
 
 #### The Other Configuration Screens  {docsify-ignore}
 
-Review the other screens just to see what is configurable. Nothing has to be done right now to get you up and running. The your previous parameters or their default values will work fine. The other screens are shown and described in *Configuring iCloud3 using The Configurator* in the next chapter
+Review the other screens just to see what is configurable. Nothing has to be done right now to get you up and running. The values you were using and/or default values will work fine. The other screens are shown and described in *Configuring iCloud3 using The Configurator* in the next chapter
+
 
 
 ------
@@ -129,17 +149,17 @@ Review the other screens just to see what is configurable. Nothing has to be don
 
 Otherwise, restart  Home Assistant to make sure iCloud3 starts, tracking begins and the Tracking and Event Log screens display correctly. 
 
-When iCloud3 starts, it generally does the following:
+As usual, when iCloud3 starts, it follows a startup process to:
 
-- Checks the directory settings
-- Loads the configuration parameters
-- Loads the tracked and monitored devices
-- Accesess the your iCloud account to get the devices tied to your account
-- Gets the information for the devices using the HA Companion App
-- Ties everything together
-- Starts tracking. 
+- Check the directory settings
+- Load the configuration parameters
+- Load the tracked and monitored devices
+- Access the your iCloud account to get the devices tied to your account
+- Get the information for the devices using the HA Companion App
+- Tie everything together
+- Start tracking. 
 
-The results of this process are shown in the Event Log and detailed in *Event Log During Startup* in the *Understanding iCloud3* chapter. If there are problems:
+The results of this process are shown in the Event Log and described in *Event Log During Startup* in the *How to Configure iCloud3*  chapter. 
 
 - Check the Event Log (it should display something) for error messages.
 - Check the HA Log file (*config/home-assistant.log*)