added signal strength to beaconelement. fixed some minor issues in examples

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2574 4b5297f7-1745-476d-ba37-a9c6900126ab

xep-0255.xml

@@ -10,12 +10,14 @@
   <abstract>This specification defines an XMPP protocol extension for querying a compliant server for information about the geographical or physical location of an entity."</abstract>
   &LEGALNOTICE;
   <number>0255</number>
+
   <status>Experimental</status>
   <type>Standards Track</type>
   <sig>Standards</sig>
   <approver>Council</approver>
   <dependencies>
     <spec>XMPP Core</spec>
+
   </dependencies>
   <supersedes/>
   <supersededby/>
@@ -23,6 +25,7 @@
   <author>
     <firstname>Helge</firstname>
     <surname>Timenes</surname>
+
     <email>helge@buddycloud.com</email>
     <jid>helge@buddycloud.com</jid>
   </author>
@@ -30,6 +33,7 @@
     <firstname>Simon</firstname>
     <surname>Tennant</surname>
     <email>simon@buddycloud.com</email>
+
     <jid>simon@buddycloud.com</jid>
   </author>
   <author>
@@ -37,7 +41,30 @@
     <surname>Savage</surname>
     <email>ross@buddycloud.com</email>
     <jid>ross@buddycloud.com</jid>
+
   </author>
+  <revision>
+    <version>0.4</version>
+    <date>2008-12-13</date>
+    <initials>ht</initials>
+    <remark><p>
+    Updated examples to be conform with XEP-0080 (use lat and lon instead of latitude and longitude)<br/>
+    Fixed wrong closing tag for &lt;type&gt; in examples.<br/>
+    Added signal strength to beacon data.
+    </p></remark>
+  </revision>
+  <revision>
+    <version>0.3</version>
+    <date>2008-11-07</date>
+    <initials>ht</initials>
+    <remark><p>Removed &lt;error/&gt; child of geoloc element (arc minutes). <br/>Added &lt;accuracy/&gt; (meters). <br/>Updated notes on GPS data submitted in location query.<br/>Replaced language encoding 'en-UK' with 'en-US' to avoid UK/GB confusion</p></remark>
+  </revision>
+  <revision>
+    <version>0.2</version>
+    <date>2008-11-03</date>
+    <initials>ht</initials>
+    <remark><p>Corrected XML namespace<br/>Added country code reference.</p></remark>
+  </revision>
   <revision>
     <version>0.1</version>
     <date>2008-11-13</date>
@@ -45,23 +72,12 @@
     <remark><p>Initial published version.</p></remark>
   </revision>
   <revision>
-    <version>0.0.3</version>
+    <version>0.0</version>
-    <date>2008-11-07</date>
-    <initials>ht</initials>
-    <remark><p>Removed &lt;error/&gt; child of geoloc element (arc minutes). <br/>Added &lt;accuracy/&gt; (meters). <br/>Updated notes on GPS data submitted in location query.<br/>replaced language encoding 'en-UK' with 'en-US' to avoid UK/GB confusion</p></remark>
-  </revision>
-  <revision>
-    <version>0.0.2</version>
-    <date>2008-11-03</date>
-    <initials>ht</initials>
-    <remark><p>Corrected XML namespace; added country code reference.</p></remark>
-  </revision>
-  <revision>
-    <version>0.0.1</version>
     <date>2008-10-28</date>
     <initials>ht/st/rs</initials>
     <remark><p>First draft.</p></remark>
   </revision>
+
 </header>
 
 <section1 topic='Introduction' anchor='intro'>
@@ -72,12 +88,14 @@
 <section1 topic='Requirements' anchor='reqs'>
   <p>The format defined herein was designed to address the following requirements:</p>
   <ul>
+
    <li>It shall be usable on devices with no support for GPS or other geodetic positioning systems</li>
    <li>It shall be usable on devices with support for GPS or other geodetic positioning systems</li>
    <li>It shall be compatible with place-referencing systems</li>
    <li>It shall support self-learning location servers</li>
    <li>The result format shall be expressed as natural language location description</li>
    <li>The result format shall be compatible with XEP-0080</li>
+
 </ul>
 </section1>
 
@@ -106,8 +124,8 @@
     xml:lang='en-US'>
   <geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
     <timestamp>1599-10-23T01:55:21Z</timestamp>
-    <latitude>57.0501862</latitude>
+    <lat>57.0501862</lat>
-    <longitude>9.9188746</longitude>
+    <lon>9.9188746</lon>
     <accuracy>35.6</accuracy>
     <street>Jomfru Ane Gade 13</street>
     <locality>Aalborg</locality>
@@ -127,15 +145,15 @@
   <locationquery xmlns='urn:xmpp:locationquery:0'>
     <beacon>
       <id>238:02:34775:50880</id>
-      <type>cell</id>
+      <type>cell</type>
     </beacon>
     <beacon>
       <id>00:0F:3D:42:92:2A</id>
-      <type>wifi</id>
+      <type>wifi</type>
     </beacon>
     <beacon>
       <id>00:19:CB:45:50:4A</id>
-      <type>wifi</id>
+      <type>wifi</type>
     </beacon>
   </locationquery>
 <iq>
@@ -149,8 +167,8 @@
     xml:lang='en-US'>
   <geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
     <timestamp>1599-10-23T01:55:21Z</timestamp>
-    <latitude>57.050122</latitude>
+    <lat>57.050122</lat>
-    <longitude>9.918833</longitude>
+    <lon>9.918833</lon>
     <locality>Aalborg</locality>
     <street>Jomfru Ane Gade 13</street>
     <country>Denmark</country>
@@ -169,25 +187,28 @@
     xml:lang='en-US'>
   <locationquery xmlns='urn:xmpp:locationquery:0'>
     <timestamp>1599-10-23T01:55:21Z</timestamp>
-    <latitude>57.0501862</latitude>
+    <lat>57.0501862</lat>
-    <longitude>9.918874</longitude>
+    <lon>9.918874</lon>
     <accuracy>33.56</accuracy>
     <publish>true</publish>
     <beacon>
       <id>238:02:34775:50880</id>
-      <type>cell</id>
+      <type>cell</type>
+      <signalstrength>-88</signalstrength>
     </beacon>
     <beacon>
       <id>00:0F:3D:42:92:2A</id>
-      <type>wifi</id>
+      <type>wifi</type>
+      <signalstrength>-64</signalstrength>
     </beacon>
     <beacon>
       <id>00:19:CB:45:50:4A</id>
-      <type>wifi</id>
+      <type>wifi</type>
+      <signalstrength>-82</signalstrength>
     </beacon>
     <beacon>
       <id>00:18:42:E6:71:51</id>
-      <type>bluetooth</id>
+      <type>bluetooth</type>
     </beacon>
   </locationquery>
 <iq>
@@ -213,8 +234,8 @@
         <item'>
           <geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
             <timestamp>1599-10-23T01:55:21Z</timestamp>
-            <latitude>57.0501862</latitude>
+            <lat>57.0501862</lat>
-            <longitude>9.918874</longitude>
+            <lon>9.918874</lon>
             <street>Jomfru Ane Gade 13</street>
             <locality>Aalborg</locality>
             <country>Denmark</country>
@@ -236,8 +257,8 @@
       <item id='4C940F61C13A0'>
         <geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
           <timestamp>1599-10-23T01:55:21Z</timestamp>
-          <latitude>57.0501862</latitude>
+          <lat>57.0501862</lat>
-          <longitude>9.918874</longitude>
+          <lon>9.918874</lon>
           <street>Jomfru Ane Gade 13</street>
           <locality>Aalborg</locality>
           <country>Denmark</country>
@@ -256,8 +277,8 @@
       <item id='4C940F61C13A0'>
         <geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
           <timestamp>1599-10-23T01:55:21Z</timestamp>
-          <latitude>57.0501862</latitude>
+          <lat>57.0501862</lat>
-          <longitude>9.918874</longitude>
+          <lon>9.918874</lon>
           <street>Jomfru Ane Gade 13</street>
           <locality>Aalborg</locality>
           <country>Denmark</country>
@@ -282,12 +303,14 @@
          <th>Datatype</th>
          <th>Definition</th>
          <th>Example</th>
+
          <th>Notes</th>
       </tr>
       <tr class="body">
          <td>timestamp</td>
          <td>xs:datetime</td>
          <td>UTC timestamp specifying the moment when the reading was taken (MUST conform to the DateTime profile of &xep0082;.</td>
+
          <td>2004-02-19T21:12Z</td>
          <td>This is the only field that is required without exception.</td>
       </tr>
@@ -295,11 +318,13 @@
          <td>publish</td>
          <td>xs:boolean</td>
          <td>A flag specifying whether or not the server should publish the location result to subscribers of the submitting user's XEP-0080 compatible geoloc pub-sub node instead of returning it directly to the submitting user.</td>
+
          <td>true</td>
          <td>Optional. If present and "true", the server shall publish the entity's location details whenever it changes (suitable for periodic queries) and respond to the query with an empty &lt;iq&gt; stanza with type set to "result". If not specified or "false" the server shall return the location results to the submitting user in the form of a geoloc stanza (XEP-0080) embedded in a &lt;iq&gt; with type set to "result". Default is "false"</td>
       </tr>
       <tr class="body">
          <td>lat</td>
+
          <td>xs:decimal</td>
          <td>Latitude in decimal degrees
          North.</td>
@@ -308,6 +333,7 @@
       </tr>
       <tr class="body">
          <td>lon</td>
+
          <td>xs:decimal</td>
          <td>Longitude in decimal degrees
          East</td>
@@ -315,6 +341,7 @@
          <td>See notes for <i>lat</i></td>
       </tr>
       <tr class="body">
+
          <td>alt</td>
          <td>xs:decimal</td>
          <td>Altitude in meters above or
@@ -322,6 +349,7 @@
          <td>1609</td>
          <td>Optional. If present, this shall also be present in the result stanza with identical value.</td>
       </tr>
+
       <tr class="body">
          <td>bearing</td>
          <td>xs:decimal</td>
@@ -330,6 +358,7 @@
          decimal degrees relative to true north</td>
          <td> </td>
          <td>See notes for <i>alt</i></td>
+
       </tr>
       <tr class="body">
          <td>datum</td>
@@ -337,6 +366,7 @@
          <td>GPS datum (See XEP-0080)</td>
          <td> </td>
          <td>See notes for <i>alt</i></td>
+
       </tr>
       <tr class="body">
          <td>accuracy</td>
@@ -344,6 +374,7 @@
          <td>Horizontal GPS accuracy in meters</td>
          <td>10</td>
          <td>See notes for <i>lat</i></td>
+
       </tr>
       <tr class="body">
          <td>speed</td>
@@ -351,12 +382,14 @@
          <td>The speed at which the entity is
          moving, in meters per second</td>
          <td>52.69</td>
+
          <td>See notes for <i>alt</i></td>
       </tr>
       <tr class="body">
          <td>beacons</td>
          <td>locationquery:beacon</td>
          <td>A list of identifiable radio transmitters observed by the entity</td>
+
          <td> </td>
          <td>Required if no <i>lat</i> and <i>lon</i> values specified, otherwise optional. See Table 2 for type definition.</td>
       </tr>
@@ -369,11 +402,13 @@
          <th>Definition</th>
          <th>Example</th>
          <th>Notes</th>
+
       </tr>
       <tr class="body">
          <td>id</td>
          <td>xs:string</td>
          <td>A world-wide unique beacon identifier. This SHALL be composed as follows: <br/><br/>For cell towers: "MCC:MNC:LAC:CID" where MCC is the mobile country code <note>Values of Mobile Country Codes (MCC) are specified by <link url="http://www.itu.int/dms_pub/itu-t/opb/sp/T-SP-E.212A-2007-PDF-E.pdf">Annex to ITU Operational Bulletin No. 897 – 1.XII.2007</link>.</note>), MNC is the network carrier code, LAC is the area code and CID is the cell ID.<br/><br/>For wireless access points and bluetooth devices: The device MAC address.</td>
+
          <td>207:02:12643:78596</td>
          <td>Required</td>
       </tr>
@@ -381,14 +416,23 @@
          <td>type</td>
          <td>xs:string</td>
          <td>Beacon type. One of "cell", "wifi", "bluetooth", "wimax", "rfid" (?), "other"</td>
+
          <td>"cell"</td>
          <td>Required.</td>
       </tr>
+      <tr class="body">
+         <td>signalstrength</td>
+         <td>xs:int</td>
+         <td>Beacon signal strength in dBM.</td>
+         <td>-64</td>
+         <td>Optional.</td>
+      </tr>
     </table>
 
     <table caption='Location Result Child Elements (Copied from XEP-0080 with notes added)'>
       <tr class="body">
          <th>Element Name</th>
+
          <th>Datatype</th>
          <th>Definition</th>
          <th>Example</th>
@@ -396,12 +440,14 @@
       </tr>
       <tr class="body">
          <td>alt</td>
+
          <td>xs:decimal</td>
          <td>Altitude in meters above or
          below sea level</td>
          <td>1609</td>
          <td>Piped directly through from query <i>alt</i> field if set.</td>
       </tr>
+
       <tr class="body">
          <td>area</td>
          <td>xs:string</td>
@@ -409,6 +455,7 @@
          neighborhood</td>
          <td>Central Park</td>
          <td> </td>
+
       </tr>
       <tr class="body">
          <td>bearing</td>
@@ -418,6 +465,7 @@
          decimal degrees relative to true north</td>
          <td> </td>
          <td>Piped directly through from query <i>bearing</i> field if set.</td>
+
       </tr>
       <tr class="body">
          <td>building</td>
@@ -426,6 +474,7 @@
          or in an area</td>
          <td>The Empire State Building</td>
          <td> </td>
+
       </tr>
       <tr class="body">
          <td>country</td>
@@ -434,6 +483,7 @@
          located</td>
          <td>USA</td>
          <td> </td>
+
       </tr>
       <tr class="body">
          <td>datum</td>
@@ -441,6 +491,7 @@
          <td>GPS datum (See notes for XEP-0080)</td>
          <td></td>
          <td>Piped directly through from query <i>datum</i> field if set.</td>
+
       </tr>
       <tr class="body">
          <td>description</td>
@@ -449,6 +500,7 @@
          description of the location</td>
          <td>Bill's house</td>
          <td>If location is mapped to a place in a place oriented service, this should hold the place description.</td>
+
       </tr>
       <tr class="body">
          <td>accuracy</td>
@@ -456,6 +508,7 @@
          <td>Horizontal GPS accuracy in meters</td>
          <td>10</td>
          <td>Piped directly through from query <i>accuracy</i> field or estimated by location server using based on the other information in query and, if possible, differences between several queries over time.</td>
+
       </tr>
       <tr class="body">
          <td>floor</td>
@@ -463,6 +516,7 @@
          <td>A particular floor in a building</td>
          <td>102</td>
          <td> </td>
+
       </tr>
       <tr class="body">
          <td>lat</td>
@@ -471,6 +525,7 @@
          North</td>
          <td>39.75</td>
          <td>Piped directly through from query <i>lat</i> field or estimated by location server based on the other information in query and, if possible, differences between several queries over time.</td>
+
       </tr>
       <tr class="body">
          <td>locality</td>
@@ -479,6 +534,7 @@
          administrative region, such as a town or city</td>
          <td>New York City</td>
          <td> </td>
+
       </tr>
       <tr class="body">
          <td>lon</td>
@@ -487,6 +543,7 @@
          East</td>
          <td>-104.99</td>
          <td>Piped directly through from query <i>lon</i> or estimated by location server based on the other information in query and, if possible, differences between several queries over time.</td>
+
       </tr>
       <tr class="body">
          <td>postalcode</td>
@@ -494,6 +551,7 @@
          <td>A code used for postal delivery</td>
          <td>10027</td>
          <td> </td>
+
       </tr>
       <tr class="body">
          <td>region</td>
@@ -502,6 +560,7 @@
          nation, such as a state or province</td>
          <td>New York</td>
          <td> </td>
+
       </tr>
       <tr class="body">
          <td>room</td>
@@ -509,6 +568,7 @@
          <td>A particular room in a building</td>
          <td>Observatory</td>
          <td> </td>
+
       </tr>
       <tr class="body">
          <td>speed</td>
@@ -517,6 +577,7 @@
          <td>52.69</td>
          <td>xs:decimal</td>
          <td>Piped directly through from query <i>speed</i> field or estimated by location server based on the other information in query and, if possible, differences between several queries over time.</td>
+
       </tr>
       <tr class="body">
          <td>street</td>
@@ -525,6 +586,7 @@
          locality, or a crossing of two thoroughfares</td>
          <td>34th and Broadway</td>
          <td> </td>
+
       </tr>
       <tr class="body">
          <td>text</td>
@@ -533,12 +595,14 @@
          captures any other information about the location</td>
          <td>Northwest corner of the lobby</td>
          <td>Best practice tip: This field can be used by the server to combine several fields in a natural language style, suitable for simple one-line location presence text. Example: "Near Bob's place" (description + accuracy), "On the road in New York" (locality + speed)</td>
+
       </tr>
       <tr class="body">
          <td>timestamp</td>
          <td>xs:datetime</td>
          <td>UTC timestamp specifying the moment when the reading was taken (MUST conform to the DateTime profile of <cite>XEP-0082</cite>)</td>
          <td>2004-02-19T21:12Z</td>
+
          <td>Piped directly through from query <i>timestamp</i> field.</td>
       </tr>
       <tr class="body">
@@ -546,6 +610,7 @@
          <td>A URI or URL pointing to
          information about the location</td>
          <td>http://beta.plazes.com/plazes/1940:jabber_inc</td>
+
          <td>xs:anyURI</td>
          <td>Only applicable to place-oriented services</td>
       </tr>
@@ -563,12 +628,14 @@
 
   <section2 topic='Server Implementation Notes' anchor='server_impl'>
     <p>The does not have to determine a value for all fields of the &lt;geoloc&gt; stanza, but it SHOULD determine values for as many as possible.  At the very least a value for 'country' should be set.</p>
+
     <p>If no GPS coordinate and accuracy information is submitted in the query, and the server determines location coordinates from submitted beacon data, a value for the returned geoloc 'accuracy' field SHOULD be returned. The magnitude of this should be derived based on the ranges of the beacons used to determine the location. </p>
     <p>The server should make no assumptions about how often a entity submits a query. It should support occasional manually triggered queries as well as periodic automated queries. In the latter case it should analyze changes over time, as this can greatly increase the fidelity of the result. </p>
     <p>Furthermore, no assumptions should be made about the number of beacons being logged in each query. Some handset manufacturers limit the access programmers have to cell tower and access point information. Some may only offer the currently connected cell ID, such that even if the handset can "see" many cell towers, only the one to which the handset is connected at the moment can be read. In this case the cell tower readings may not be constant, even if the querying entity is not moving. Rather it may jump round-robin style to each visible cell with variable time spent on each.  The location server should account for this to avoid yielding results indicating that a user is running around in cell-sized circles when he is in fact stationary. Again, analysis of variation of submitted queries over time is recommended.</p>
     <p>As no guarantees can be made that a given radio beacon stays at one fixed physical location throughout it's lifetime, the server should implement means to detect this. Generally it can be assumed that cell towers seldom move (could happen when a network operator changes the way it allocates cell IDs or when a tower is physically moved to a different location). Wireless access points move a bit more frequently (for instance when their owners move, or if they are installed in moving vehicles such as busses or trains). Bluetooth devices can generally be assumed to be mobile and should, unless specific knowledge to the contrary exists, not be used to locate an entity to a specific physical location. Rather, bluetooth devices (and other mobile beacons) can be used to co-locate entities to other entities for which a physical location is known. An example: Entity A submits query with GPS coordinates and the ID of some bluetooth device. It is located based on its submitted coordinates. Entity B submits a query with the same bluetooth device ID, but no GPS coordinates. Given this, and the fact that bluetooth transmitters have a very limited range, the server can then derive that A and B are at the same physical location (it may add 10-20 m to the accuracy of the location of B to account for the bluetooth range).</p>
     <p>The "radio landscape" is by no means constant. New beacons are added continuously, and old ones are phased out. A location server will have to adapt to this shifting landscape, either by means of operator-supplied databases (in case of cell towers) or by means of user generated information. This standard was written with the latter in mind, and it is recommended that location servers utilize any queries with combined GPS and radio beacon information to "learn" the approximate physical location of the provided beacons. For server implementation that rely on user generated information only, it is also recommended to supply additional means for the users to feed back location context in cases where the client does not have any GPS access, or when the server produces the wrong results. One way to do this would be to let the users define "placemarks" (a name, street, city etc) that can be associated with the beacons seen by this user at the time of definition. This is however beyond the scope of this XEP. </p>
   </section2>
+
   <section2 topic='Client Implementation Notes' anchor='client_impl'>
     <p>For the reasons mentioned above, it is recommended that the client supply both GPS coordinates as well as nearby radio beacon information when possible. Also it is recommended that the client submit queries frequently enough to allow the server to analyze changes over time (or lack thereof) to obtain a better result. When possible, the client should include wifi access points in the queries, as these yield much more precise results than cell towers alone (due to the much more limited range). This must however all be weighted against the increased power consumption resulting from keeping network sockets open, scanning for access points and driving a GPS receiver.<br/><br/> For optimal results, clients SHOULD post a location query any time when the set of observed beacons change (a new beacon is seen or an old one is not seen any more)</p>
   </section2>
@@ -596,11 +663,13 @@
     <ul>
       <li>urn:xmpp:jingle:transfer:0</li>
     </ul>
+
     <p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespaces to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
   </section2>
   <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
     <p>If the protocol defined in this specification undergoes a major revision that is not fully backward-compatible with an older version, or that contains significant new features, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of <cite>XEP-0053</cite>.</p>
   </section2>
+
 </section1>
 
 <section1 topic='XML Schema' anchor='schema'>
@@ -663,6 +732,10 @@
                           minOccurs='1' 
                           maxOccurs='1' 
                           type='xs:string'/>
+              <xs:element name='signalstrength' 
+                          minOccurs='0' 
+                          maxOccurs='1' 
+                          type='xs:int'/>
             </xs:sequence>
     	  </xs:complexType>
         </xs:element>