v2.2.1 Documentation

docs/chapters/1-getting-started.md

@@ -70,9 +70,9 @@ When iCloud3 starts, it reads the HA Entity Registry file (*config/.storage/core
 
 ### iCloud3 Tracking Methods
 
-iCloud3 can track your phones using two methods;. You will need to decide which one makes the most sense for you based on your situation. Fortunately, It is easy to switch back and forth by changing only the iCloud3 tracking_method configuration parameter and restarting HA. The methods are:
+iCloud3 can track your phones using three methods. You will need to decide which one makes the most sense for you based on your situation. Fortunately, It is easy to switch back and forth by changing only the iCloud3 *tracking_method* configuration parameter and restarting HA. The methods are:
 
-###### Find-My-Friends (fmf) 
+###### Find-My-Friends (fmf)
 
 The Find-my-Friends tracking method lets you track people you are sharing your location with on the FindMy App.
 
@@ -98,12 +98,25 @@ The Family Sharing tracking method lets you track people on the Family Sharing l
 The Apple support web site has several articles that will help you set up your iCloud account to prepare it for using iCloud3.
 
 - Go [here](https://support.apple.com/en-us/HT210400) for *Set up Find My app*
-
 - Go [here](https://support.apple.com/en-us/HT201493) for *Set up and use Find My Friends*
-
 - Go [here](https://support.apple.com/en-us/HT201088) for *Set up Family Sharing*
 
-### Authenticating Your iCloud Account 
+###### iOS App (iosapp)
+
+The iOS App tracking method lets you track your phones without interacting with iCloud Location Services. Location requests are sent to the iOS App on the phone using the push notification method built into Home Assistant,
+
+- Pros:
+  - It can be used when you do not want to access your iCloud account from HA.
+  - It can be used when iCloud is down.
+  - It can be used when you are having problems authenticating iCloud3 access to your iCloud account because of 2fa verification issues or the *Trusted Device Certificate* keeps expiring.
+- Cons:
+  - When the iPhone goes to sleep, the iOS App may (will) not respond to location requests, even after it wakes up and you start using it. You will need to launch the iOS App, which will then issue a *Launch trigger* to iCloud3 with location information. iOS will then begin running the iOS App in the background.
+
+Information about the iOS App (Home Assistant Companion) can be found [here](https://companion.home-assistant.io/).
+
+
+
+### Authenticating Your iCloud Account
 
 Home Assistant and iCloud3 needs to be authenticated to access your iCloud account. It requests authentication by asking iCloud to send a verification code via a text message to a trusted device, which is then entered in Home Assistant. The duration of this authentication is determined by Apple, but usually several months.  
 

docs/chapters/1-installing-event-log-card.md

@@ -14,7 +14,7 @@ As iCloud3 runs, various entries are written to the iCloud3 Event Log that show:
 - Device information
 - How the device is tracked
 - Operational errors
-- Sartup information
+- Startup information
 - Waze route information
 - Tracking metrics
 
@@ -31,6 +31,45 @@ Below are some examples of the Event Log.
 
 ![event_log](../images/evlog.jpg) 
 
+### Do not Record iCloud3 Events in the HA History Database
+
+The *sensor.icloud3_event_log* entity is used to pass events from iCloud3 to the Event Log. The size of the text in this sensor can become very large after you have been running HA for a while. There is no need to record this entity in the HA database every time it changes. To prevent this, add the following to your configuration.yaml file:
+
+```
+recorder:
+  purge_keep_days: 3
+  exclude:
+    entities:
+      - sensor.icloud3_event_log
+```
+
+More information on configuration the *recorder* can be found in the HA documentation [here](https://www.home-assistant.io/integrations/recorder/).
+
+Below is an example of the error that may occur if you do not exclude the *sensor.icloud3_event_log*.
+
+```
+2020-10-31 16:11:11 ERROR (Recorder) [homeassistant.components.recorder] Error executing query: (MySQLdb._exceptions.DataError) (1406, "Data too long for column 'attributes' at row 1")
+[SQL: INSERT INTO states (domain, entity_id, state, attributes, event_id, last_changed, last_updated, created, old_state_id) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s)]
+[parameters: ('sensor', 'sensor.icloud3_event_log', ...', 13414815, datetime.datetime(2020, 10, 31, 15, 1, 10, 494582, tzinfo=datetime.timezone.utc), datetime.datetime(2020, 10, 31, 15, 1, 10, 494582, tzinfo=datetime.timezone.utc), datetime.datetime(2020, 10, 31, 15, 1, 10, 494716, tzinfo=datetime.timezone.utc), 12914612)]
+(Background on this error at: http://sqlalche.me/e/13/9h9h)
+Traceback (most recent call last):
+  File "/usr/local/lib/python3.8/site-packages/sqlalchemy/engine/base.py", line 1276, in _execute_context
+    self.dialect.do_execute(
+  File "/usr/local/lib/python3.8/site-packages/sqlalchemy/engine/default.py", line 593, in do_execute
+    cursor.execute(statement, parameters)
+  File "/usr/local/lib/python3.8/site-packages/MySQLdb/cursors.py", line 206, in execute
+    res = self._query(query)
+  File "/usr/local/lib/python3.8/site-packages/MySQLdb/cursors.py", line 319, in _query
+    db.query(q)
+  File "/usr/local/lib/python3.8/site-packages/MySQLdb/connections.py", line 259, in query
+    _mysql.connection.query(self, query)
+MySQLdb._exceptions.DataError: (1406, "Data too long for column 'attributes' at row 1")
+```
+
+
+
+
+
 ### Installing the Event Log
 
 Typically Lovelace custom cards are stored in their own directory that is within the `config/www/` directory. iCloud3 and the instructions below, use the `www/custom_cards` directory although you may be storing them in another location (e.g.,`www/community`). 

docs/chapters/2-event-log.md

@@ -24,7 +24,23 @@ Typically Lovelace custom cards are stored in their own directory that is within
 
 !>If you are not using the `www/custom_cards` directory, use your directory name (e.g., `www/community`) instead of `www/custom_cards` in the following instructions. Then specify your directory name using the *event_log_card_directory: www/yourcustomcarddirectoryname* configuration parameter.
 
-### The Actions Command 
+### Refreshing Events
+
+The date/time the events were last refreshed is displayed under the *Actions* command at the top of the screen.  Usually the events are refreshed when you display the screen but there are times when you will need to refresh them manually. This may be when:
+
+- The Event Log is displayed and the events for last Person did not automatically refresh. 
+
+- iCloud3 clears the *sensor.icloud3_event_log* that passes events from iCloud3 to the Event Log lovelace card every 15-minutes or so. Only the last 20 events, at the time the sensor is cleared, are displayed. A message informs you that the list needs to be refreshed.
+
+Click the   ![evlog-icon-refresh24](../images/evlog-icon-refresh24.png)  Refresh button in the upper right corner.
+
+### Displaying the *iCloud3 User Manual*
+
+You are reading the  *iCloud3 User Manual* now. 
+
+Click the  ![evlog-icon-help24](../images/evlog-icon-help24.png)  Help button in the upper right corner.
+
+### The Actions Command
 
 The Actions Command lets you interact with iCloud3 while it is running.