From c2259f88a0d65f190d80fa72117353a7f6cae63b Mon Sep 17 00:00:00 2001
From: jpawlowski <jpawlowski@users.noreply.github.com>
Date: Sun, 9 Feb 2014 16:54:58 +0000
Subject: [PATCH] RESIDENTS Fam: fix timers and improved documentation

git-svn-id: https://svn.fhem.de/fhem/trunk/fhem@4860 2b470e98-0d58-463d-a4d8-8e2adae1ed80
---
 FHEM/10_RESIDENTS.pm | 39 ++++++++++++++++----------
 FHEM/20_GUEST.pm     | 57 ++++++++++++++++++++++++++------------
 FHEM/20_ROOMMATE.pm  | 65 +++++++++++++++++++++++++++++++-------------
 3 files changed, 111 insertions(+), 50 deletions(-)

diff --git a/FHEM/10_RESIDENTS.pm b/FHEM/10_RESIDENTS.pm
index c7633dd96..f20c7b105 100644
--- a/FHEM/10_RESIDENTS.pm
+++ b/FHEM/10_RESIDENTS.pm
@@ -23,7 +23,7 @@
 #     along with fhem.  If not, see <http://www.gnu.org/licenses/>.
 #
 #
-# Version: 1.0.0
+# Version: 1.0.1
 #
 # Major Version History:
 # - 1.0.0 - 2014-02-08
@@ -899,7 +899,7 @@ sub RESIDENTS_TimeDiff($$) {
 
     Example:<br>
     <ul><code>
-       # Standalone
+       # Standalone<br>
        define rgr_Residents RESIDENTS
     </code></ul>
   </ul>
@@ -909,27 +909,30 @@ sub RESIDENTS_TimeDiff($$) {
   <a name="RESIDENTSset"></a>
   <b>Set</b>
   <ul>
-    <code>set &lt;rg_FirstName&gt; &lt;command&gt; [&lt;parameter&gt;]</code>
+    <code>set &lt;rgr_ResidentsName&gt; &lt;command&gt; [&lt;parameter&gt;]</code>
     <br><br>
     Currently, the following commands are defined.<br>
     <ul>
-      <li><b>location</b> &nbsp;&nbsp;-&nbsp;&nbsp; sets reading 'location'; see attribute rg_locations to adjust list shown in FHEMWEB</li>
-      <li><b>mood</b> &nbsp;&nbsp;-&nbsp;&nbsp; sets reading 'mood'; see attribute rg_moods to adjust list shown in FHEMWEB</li>
-      <li><b>state</b> &nbsp;&nbsp;home,gotosleep,asleep,awoken,absent,gone&nbsp;&nbsp; switch between states; see attribute rg_states to adjust list shown in FHEMWEB</li>
+      <li><b>addGuest</b> &nbsp;&nbsp;-&nbsp;&nbsp; creates a new GUEST device and adds it to the current RESIDENTS group. Just enter the dummy name and there you go.</li>
+      <li><b>addRoommate</b> &nbsp;&nbsp;-&nbsp;&nbsp; creates a new ROOMMATE device and adds it to the current RESIDENTS group. Just enter the first name and there you go.</li>
+      <li><b>removeGuest</b> &nbsp;&nbsp;-&nbsp;&nbsp; shows all GUEST members and allows to delete their dummy devices easily.</li>
+      <li><b>removeRoommate</b> &nbsp;&nbsp;-&nbsp;&nbsp; shows all ROOMMATE members and allows to delete their dummy devices easily.</li>
+      <li><b>state</b> &nbsp;&nbsp;home,gotosleep,asleep,awoken,absent,gone&nbsp;&nbsp; switch between states for all group members at once; see attribute rgr_states to adjust list shown in FHEMWEB</li>
     </ul>
   </ul>
 
+<br><br>
   <ul>
     <u>Possible states and their meaning</u><br><br>
     <ul>
-      This module differs 7 states:<br><br>
+      This module differs between 7 states:<br><br>
 
       <ul>
-      <li><b>home</b> - residents are present at home and awake</li>
-      <li><b>gotosleep</b> - all present residents are on it's way to bed</li>
+      <li><b>home</b> - residents are present at home and at least one of them is not asleep</li>
+      <li><b>gotosleep</b> - present residents are on their way to bed (if they are not asleep already)</li>
       <li><b>asleep</b> - all present residents are currently sleeping</li>
-      <li><b>awoken</b> - all present residents just woke up from sleep</li>
-      <li><b>absent</b> - no resident is currently at home but will be back shortly</li>
+      <li><b>awoken</b> - at least one resident just woke up from sleep</li>
+      <li><b>absent</b> - no resident is currently at home but at least one will be back shortly</li>
       <li><b>gone</b> - all residents left home for longer period</li>
       <li><b>none</b> - no active member</li>
       </ul><br>
@@ -953,6 +956,8 @@ sub RESIDENTS_TimeDiff($$) {
   <br>
   <b>Generated Readings/Events:</b><br>
   <ul><ul>
+    <li><b>lastActivity</b> - the last state change of one of the group members</li>
+    <li><b>lastActivityBy</b> - the realname of the last group member with changed state</li>
     <li><b>lastArrival</b> - timestamp of last arrival at home</li>
     <li><b>lastAwake</b> - timestamp of last sleep cycle end</li>
     <li><b>lastDeparture</b> - timestamp of last departure from home</li>
@@ -967,7 +972,7 @@ sub RESIDENTS_TimeDiff($$) {
     <li><b>residentsAwoken</b> - number of residents with state 'awoken'</li>
     <li><b>residentsGone</b> - number of residents with state 'gone'</li>
     <li><b>residentsGotosleep</b> - number of residents with state 'gotosleep'</li>
-    <li><b>residentsGuests</b> - number of active guests who are currently threated as part of the residents scope</li>
+    <li><b>residentsGuests</b> - number of active guests who are currently treated as part of the residents scope</li>
     <li><b>residentsHome</b> - number of residents with state 'home'</li>
     <li><b>residentsTotal</b> - total number of all active residents despite their current state</li>
     <li><b>residentsTotalAbsent</b> - number of all residents who are currently underway</li>
@@ -981,10 +986,16 @@ sub RESIDENTS_TimeDiff($$) {
 =end html
 
 =begin html_DE
+
+<a name="RESIDENTS"></a>
+<h3>RESIDENTS</h3>
+<ul>
 Eine deutsche Version der Dokumentation ist derzeit nicht vorhanden.
 Die englische Version ist hier zu finden: 
-
- <a href='http://fhem.de/commandref.html#RESIDENTS>'>RESIDENTS</a> &nbsp;
+</ul>
+<ul>
+<a href='http://fhem.de/commandref.html#RESIDENTS'>RESIDENTS</a>
+</ul>
 
 =end html_DE
 
diff --git a/FHEM/20_GUEST.pm b/FHEM/20_GUEST.pm
index 6448b89ee..07920efe4 100644
--- a/FHEM/20_GUEST.pm
+++ b/FHEM/20_GUEST.pm
@@ -23,7 +23,7 @@
 #     along with fhem.  If not, see <http://www.gnu.org/licenses/>.
 #
 #
-# Version: 1.0.0
+# Version: 1.0.1
 #
 # Major Version History:
 # - 1.0.0 - 2014-02-08
@@ -202,8 +202,8 @@ sub GUEST_Define($$) {
 
     readingsEndUpdate( $hash, 1 );
 
-    # run AutoGone timer
-    InternalTimer( gettimeofday() + 10, "ROOMMATE_AutoGone", $hash, 1 );
+    # run timers
+    InternalTimer( gettimeofday() + 15, "GUEST_StartInternalTimers", $hash, 0 );
 
     return undef;
 }
@@ -754,7 +754,7 @@ sub GUEST_DurationTimer($;$) {
             $diff =
               $timestampNow -
               GUEST_Datetime2Timestamp( $hash->{READINGS}{lastArrival}{VAL} );
-            $durPresence = ( $diff / 60 ) % 60;
+            $durPresence = int( $diff / 60 );
         }
     }
 
@@ -770,7 +770,7 @@ sub GUEST_DurationTimer($;$) {
             $diff =
               $timestampNow -
               GUEST_Datetime2Timestamp( $hash->{READINGS}{lastDeparture}{VAL} );
-            $durAbsence = ( $diff / 60 ) % 60;
+            $durAbsence = int( $diff / 60 );
         }
     }
 
@@ -784,7 +784,7 @@ sub GUEST_DurationTimer($;$) {
             $diff =
               $timestampNow -
               GUEST_Datetime2Timestamp( $hash->{READINGS}{lastSleep}{VAL} );
-            $durSleep = ( $diff / 60 ) % 60;
+            $durSleep = int( $diff / 60 );
         }
     }
 
@@ -883,6 +883,14 @@ sub GUEST_RemoveInternalTimer($$) {
     }
 }
 
+###################################
+sub GUEST_StartInternalTimers($$) {
+    my ($hash) = @_;
+
+    GUEST_AutoGone($hash);
+    GUEST_DurationTimer($hash);
+}
+
 1;
 
 =pod
@@ -904,38 +912,39 @@ sub GUEST_RemoveInternalTimer($$) {
 
     Example:<br>
     <ul><code>
-       # Standalone
+       # Standalone<br>
        define rg_Guest GUEST
        <br><br>
-       # Typical group member
+       # Typical group member<br>
        define rg_Guest GUEST rgr_Residents                  # to be member of resident group rgr_Residents
        <br><br>
-       # Member of multiple groups
+       # Member of multiple groups<br>
        define rg_Guest GUEST rgr_Residents,rgr_Guests       # to be member of resident group rgr_Residents and rgr_Guests
     </code></ul>
   </ul><br>
 
-  Please note the RESIDENTS group device needs to be existing before a GUEST device can become a member of it.<br>
+  <ul>Please note the RESIDENTS group device needs to be existing before a GUEST device can become a member of it.</ul><br>
   <br>
   <br>
 
   <a name="GUESTset"></a>
   <b>Set</b>
   <ul>
-    <code>set &lt;rg_FirstName&gt; &lt;command&gt; [&lt;parameter&gt;]</code>
+    <code>set &lt;rg_GuestName&gt; &lt;command&gt; [&lt;parameter&gt;]</code>
     <br><br>
     Currently, the following commands are defined.<br>
     <ul>
       <li><b>location</b> &nbsp;&nbsp;-&nbsp;&nbsp; sets reading 'location'; see attribute rg_locations to adjust list shown in FHEMWEB</li>
       <li><b>mood</b> &nbsp;&nbsp;-&nbsp;&nbsp; sets reading 'mood'; see attribute rg_moods to adjust list shown in FHEMWEB</li>
-      <li><b>state</b> &nbsp;&nbsp;home,gotosleep,asleep,awoken,absent,gone&nbsp;&nbsp; switch between states; see attribute rg_states to adjust list shown in FHEMWEB</li>
+      <li><b>state</b> &nbsp;&nbsp;home,gotosleep,asleep,awoken,absent,none&nbsp;&nbsp; switch between states; see attribute rg_states to adjust list shown in FHEMWEB</li>
     </ul>
   </ul>
 
+<br><br>
   <ul>
     <u>Possible states and their meaning</u><br><br>
     <ul>
-      This module differs 6 states:<br><br>
+      This module differs between 6 states:<br><br>
 
       <ul>
       <li><b>home</b> - individual is present at home and awake</li>
@@ -998,7 +1007,15 @@ sub GUEST_RemoveInternalTimer($$) {
       Whenever location is set to 'underway', the state is set to 'absent' if prior presence state was 'present'. If attribute rg_locationUnderway was defined, all of those locations will trigger state change to 'absent' as well. Those locations won't appear in reading 'lastLocation'.<br>
       <br>
       Whenever location is set to 'wayhome', the reading 'wayhome' is set to '1' if current presence state is 'absent'. If attribute rg_locationWayhome was defined, LEAVING one of those locations will set reading 'wayhome' to '1' as well. So you actually have implicit and explicit options to trigger wayhome.<br>
-      Arriving at home will reset the value of 'wayhome' to '0'.
+      Arriving at home will reset the value of 'wayhome' to '0'.<br>
+      <br>
+      If you are using the <a href="#GEOFANCY">GEOFANCY</a> module, you can easily have your location updated with GEOFANCY events by defining a simple NOTIFY-trigger like this:<br>
+      <br>
+      <code>
+      define n_rg_Guest.location notify geofancy:currLoc_Guest.* set rg_Guest location $EVTPART1
+      </code><br>
+      <br>
+      By defining geofencing zones called 'home', 'underway' and 'wayhome' in the iOS app, you automatically get all the features of automatic state changes described above.
     </ul>
   </ul>
   <br>
@@ -1008,7 +1025,7 @@ sub GUEST_RemoveInternalTimer($$) {
   <b>Attributes</b><br>
   <ul><ul>
     <li><b>rg_autoGoneAfter</b> - hours after which state should be auto-set to 'gone' when current state is 'absent'; defaults to 16 hours</li>
-    <li><b>rg_locationHome</b> - locations matching these will be treated as being at home; first entry reflects default value to be used with state correlation; separate entries by space; defaults to "home"</li>
+    <li><b>rg_locationHome</b> - locations matching these will be treated as being at home; first entry reflects default value to be used with state correlation; separate entries by space; defaults to 'home'</li>
     <li><b>rg_locationUnderway</b> - locations matching these will be treated as being underway; first entry reflects default value to be used with state correlation; separate entries by comma or space; defaults to "underway"</li>
     <li><b>rg_locationWayhome</b> - leaving a location matching these will set reading wayhome to 1; separate entries by space; defaults to "wayhome"</li>
     <li><b>rg_locations</b> - list of locations ot be shown in FHEMWEB; separate entries by comma only and do NOT use spaces</li>
@@ -1054,10 +1071,16 @@ sub GUEST_RemoveInternalTimer($$) {
 =end html
 
 =begin html_DE
+
+<a name="GUEST"></a>
+<h3>GUEST</h3>
+<ul>
 Eine deutsche Version der Dokumentation ist derzeit nicht vorhanden.
 Die englische Version ist hier zu finden: 
-
- <a href='http://fhem.de/commandref.html#GUEST>'>GUEST</a> &nbsp;
+</ul>
+<ul>
+<a href='http://fhem.de/commandref.html#GUEST'>GUEST</a>
+</ul>
 
 =end html_DE
 
diff --git a/FHEM/20_ROOMMATE.pm b/FHEM/20_ROOMMATE.pm
index 3ae027571..33155afae 100644
--- a/FHEM/20_ROOMMATE.pm
+++ b/FHEM/20_ROOMMATE.pm
@@ -23,7 +23,7 @@
 #     along with fhem.  If not, see <http://www.gnu.org/licenses/>.
 #
 #
-# Version: 1.0.0
+# Version: 1.0.1
 #
 # Major Version History:
 # - 1.0.0 - 2014-02-08
@@ -195,8 +195,12 @@ sub ROOMMATE_Define($$) {
 
     readingsEndUpdate( $hash, 1 );
 
-    # run AutoGone timer
-    InternalTimer( gettimeofday() + 10, "ROOMMATE_AutoGone", $hash, 1 );
+    # run timers
+    InternalTimer(
+        gettimeofday() + 15,
+        "ROOMMATE_StartInternalTimers",
+        $hash, 0
+    );
 
     return undef;
 }
@@ -742,7 +746,7 @@ sub ROOMMATE_DurationTimer($;$) {
               $timestampNow -
               ROOMMATE_Datetime2Timestamp(
                 $hash->{READINGS}{lastArrival}{VAL} );
-            $durPresence = ( $diff / 60 ) % 60;
+            $durPresence = int( $diff / 60 );
         }
     }
 
@@ -757,7 +761,7 @@ sub ROOMMATE_DurationTimer($;$) {
               $timestampNow -
               ROOMMATE_Datetime2Timestamp(
                 $hash->{READINGS}{lastDeparture}{VAL} );
-            $durAbsence = ( $diff / 60 ) % 60;
+            $durAbsence = int( $diff / 60 );
         }
     }
 
@@ -771,7 +775,7 @@ sub ROOMMATE_DurationTimer($;$) {
             $diff =
               $timestampNow -
               ROOMMATE_Datetime2Timestamp( $hash->{READINGS}{lastSleep}{VAL} );
-            $durSleep = ( $diff / 60 ) % 60;
+            $durSleep = int( $diff / 60 );
         }
     }
 
@@ -869,6 +873,14 @@ sub ROOMMATE_RemoveInternalTimer($$) {
     }
 }
 
+###################################
+sub ROOMMATE_StartInternalTimers($$) {
+    my ($hash) = @_;
+
+    ROOMMATE_AutoGone($hash);
+    ROOMMATE_DurationTimer($hash);
+}
+
 1;
 
 =pod
@@ -890,24 +902,24 @@ sub ROOMMATE_RemoveInternalTimer($$) {
 
     Example:<br>
     <ul><code>
-       # Standalone
+       # Standalone<br>
        define rr_Manfred ROOMMATE
        <br><br>
-       # Typical group member
+       # Typical group member<br>
        define rr_Manfred ROOMMATE rgr_Residents                # to be member of resident group rgr_Residents
        <br><br>
-       # Member of multiple groups
+       # Member of multiple groups<br>
        define rr_Manfred ROOMMATE rgr_Residents,rgr_Parents    # to be member of resident group rgr_Residents and rgr_Parents
        <br><br>
-       # Complex family structure
-       define rr_Manfred ROOMMATE rgr_Residents,rgr_Parents    # Parent
-       define rr_Lisa ROOMMATE rgr_Residents,rgr_Parents       # Parent
-       define rr_Rick ROOMMATE rgr_Residents,rgr_Children      # Child1
+       # Complex family structure<br>
+       define rr_Manfred ROOMMATE rgr_Residents,rgr_Parents    # Parent<br>
+       define rr_Lisa ROOMMATE rgr_Residents,rgr_Parents       # Parent<br>
+       define rr_Rick ROOMMATE rgr_Residents,rgr_Children      # Child1<br>
        define rr_Alex ROOMMATE rgr_Residents,rgr_Children      # Child2
     </code></ul>
   </ul><br>
 
-  Please note the RESIDENTS group device needs to be existing before a ROOMMATE device can become a member of it.<br>
+  <ul>Please note the RESIDENTS group device needs to be existing before a ROOMMATE device can become a member of it.</ul><br>
   <br>
   <br>
 
@@ -924,10 +936,11 @@ sub ROOMMATE_RemoveInternalTimer($$) {
     </ul>
   </ul>
 
+<br><br>
   <ul>
     <u>Possible states and their meaning</u><br><br>
     <ul>
-      This module differs 6 states:<br><br>
+      This module differs between 6 states:<br><br>
 
       <ul>
       <li><b>home</b> - individual is present at home and awake</li>
@@ -990,7 +1003,15 @@ sub ROOMMATE_RemoveInternalTimer($$) {
       Whenever location is set to 'underway', the state is set to 'absent' if prior presence state was 'present'. If attribute rr_locationUnderway was defined, all of those locations will trigger state change to 'absent' as well. Those locations won't appear in reading 'lastLocation'.<br>
       <br>
       Whenever location is set to 'wayhome', the reading 'wayhome' is set to '1' if current presence state is 'absent'. If attribute rr_locationWayhome was defined, LEAVING one of those locations will set reading 'wayhome' to '1' as well. So you actually have implicit and explicit options to trigger wayhome.<br>
-      Arriving at home will reset the value of 'wayhome' to '0'.
+      Arriving at home will reset the value of 'wayhome' to '0'.<br>
+      <br>
+      If you are using the <a href="#GEOFANCY">GEOFANCY</a> module, you can easily have your location updated with GEOFANCY events by defining a simple NOTIFY-trigger like this:<br>
+      <br>
+      <code>
+      define n_rr_Manfred.location notify geofancy:currLoc_Manfred.* set rr_Manfred location $EVTPART1
+      </code><br>
+      <br>
+      By defining geofencing zones called 'home', 'underway' and 'wayhome' in the iOS app, you automatically get all the features of automatic state changes described above.
     </ul>
   </ul>
   <br>
@@ -1000,7 +1021,7 @@ sub ROOMMATE_RemoveInternalTimer($$) {
   <b>Attributes</b><br>
   <ul><ul>
     <li><b>rr_autoGoneAfter</b> - hours after which state should be auto-set to 'gone' when current state is 'absent'; defaults to 36 hours</li>
-    <li><b>rr_locationHome</b> - locations matching these will be treated as being at home; first entry reflects default value to be used with state correlation; separate entries by space; defaults to "home"</li>
+    <li><b>rr_locationHome</b> - locations matching these will be treated as being at home; first entry reflects default value to be used with state correlation; separate entries by space; defaults to 'home'</li>
     <li><b>rr_locationUnderway</b> - locations matching these will be treated as being underway; first entry reflects default value to be used with state correlation; separate entries by comma or space; defaults to "underway"</li>
     <li><b>rr_locationWayhome</b> - leaving a location matching these will set reading wayhome to 1; separate entries by space; defaults to "wayhome"</li>
     <li><b>rr_locations</b> - list of locations ot be shown in FHEMWEB; separate entries by comma only and do NOT use spaces</li>
@@ -1043,10 +1064,16 @@ sub ROOMMATE_RemoveInternalTimer($$) {
 =end html
 
 =begin html_DE
+
+<a name="ROOMMATE"></a>
+<h3>ROOMMATE</h3>
+<ul>
 Eine deutsche Version der Dokumentation ist derzeit nicht vorhanden.
 Die englische Version ist hier zu finden: 
-
- <a href='http://fhem.de/commandref.html#ROOMMATE>'>ROOMMATE</a> &nbsp;
+</ul>
+<ul>
+<a href='http://fhem.de/commandref.html#ROOMMATE'>ROOMMATE</a>
+</ul>
 
 =end html_DE