GT-3032, step 3: draft for use of bitmasks as proposed by Marco Residori at 15-Oct

4 files changed, 100 insertions, 135 deletions

diff --git a/enhanced-position-service/api/genivi-positioning-constants.xml b/enhanced-position-service/api/genivi-positioning-constants.xml
index 8712181..60f9f59 100644
--- a/enhanced-position-service/api/genivi-positioning-constants.xml
+++ b/enhanced-position-service/api/genivi-positioning-constants.xml
@@ -15,81 +15,54 @@
   <version>3.0.0 (xx-10-2014)</version>
   <doc>
     <line>This document defines the constants that are used in the EnhancedPositionService APIs</line>
+    <line>Constants for "Keys" are always individual bits within a 64 bit unsigned integer and are unique within the EnhancedPositionService</line>
+    <line>Constants for "Enums" increment consecutively and are only unique within the context of the specific enum</line>
   </doc>
 
-  <!-- special values -->
-  <id name="INVALID" value="0x0000" />
-  <id name="TIMESTAMP" value="0x0001" />
-  <id name="ALL" value="0xffff" />
-
-  <!-- Position -->
-  <id name="LATITUDE" value="0x0020" />
-  <id name="LONGITUDE" value="0x0021" />
-  <id name="ALTITUDE" value="0x0022" />
-
-  <!-- Course -->
-  <id name="HEADING" value="0x0030" />
-  <id name="SPEED" value="0x0031" />
-  <id name="CLIMB" value="0x0032" />
-
-  <!-- Address -->
-  <id name="COUNTRY" value="0x0040" />
-  <id name="CITY" value="0x0041" />
-  <id name="STREET" value="0x0042" />
-  <id name="NUMBER" value="0x0043" />
-  <id name="CROSSING" value="0x0044" />
-  <id name="DISTRICT" value="0x0045" />
-  <id name="TIMEZONE_OFFSET" value="0x0046" />
-  <id name="DAYLIGHT_OFFSET" value="0x0047" />
-  <id name="MATCH_TYPE" value="0x0048" />
-
-  <!-- RotationRate -->
-  <id name="ROLL_RATE" value="0x0060" />
-  <id name="PITCH_RATE" value="0x0061" />
-  <id name="YAW_RATE" value="0x0062" />
-
-  <!-- EnhancedPositionStatus -->
-  <id name="GNSS_FIX_STATUS" value="0x0070" />
-  <id name="DR_STATUS" value="0x0071" />
-
-  <!-- MapMatchedPositionStatus -->
-  <id name="MM_STATUS" value="0x0072" />
-
-  <!-- PositionFeedback -->
-  <id name="RELIABILTY_INDEX" value="0x0073" />
-  <id name="MAP_MATCHED_FEEDBACK" value="0x0074" />
-  <id name="TEST_FEEDBACK" value="0x0075" />
-
-  <!-- Accuracy -->
-  <id name="PDOP" value="0x0080" />
-  <id name="HDOP" value="0x0081" />
-  <id name="VDOP" value="0x0082" />
-  <id name="SIGMA_ALTITUDE" value="0x0085" />
-  <id name="SIGMA_HEADING" value="0x0086" />
-  <id name="SIGMA_HPOSITION" value="0x0087" />
-  
-
-  <!-- Time -->
-  <id name="YEAR" value="0x00a0" />
-  <id name="MONTH" value="0x00a1" />
-  <id name="DAY" value="0x00a2" />
-  <id name="HOUR" value="0x00a3" />
-  <id name="MINUTE" value="0x00a4" />
-  <id name="SECOND" value="0x00a5" />
-  <id name="MS" value="0x00a6" />
-
-  <!-- SatelliteSystem -->
-  <id name="GPS" value="0x00b0" />
-  <id name="GLONASS" value="0x00b1" />
-  <id name="GALILEO" value="0x00b2" />
-  <id name="COMPASS" value="0x00b3" />
-
-  <!-- SatelliteStatus -->
-
-  <id name="USED_SATELLITES"  value="0x00c0" />
-  <id name="TRACKED_SATELLITES"  value="0x00c1" />
-  <id name="VISIBLE_SATELLITES"  value="0x00c2" />
-  <id name="SATELLITE_DETAILS"  value="0x00c3" />
+  <!-- PositionInfo and PositionFeedback Keys - for use in bit mask -->
+  <id name="LATITUDE"               value="0x00000001" />
+  <id name="LONGITUDE"              value="0x00000002" />
+  <id name="ALTITUDE"               value="0x00000004" />
+  <id name="HEADING"                value="0x00000008" />
+  <id name="SPEED"                  value="0x00000010" />
+  <id name="CLIMB"                  value="0x00000020" />
+  <id name="ROLL_RATE"              value="0x00000040" />
+  <id name="PITCH_RATE"             value="0x00000080" />
+  <id name="YAW_RATE"               value="0x00000100" />
+  <id name="PDOP"                   value="0x00000200" />
+  <id name="HDOP"                   value="0x00000400" />
+  <id name="VDOP"                   value="0x00000800" />
+  <id name="USED_SATELLITES"        value="0x00001000" />
+  <id name="TRACKED_SATELLITES"     value="0x00002000" />
+  <id name="VISIBLE_SATELLITES"     value="0x00004000" />
+  <id name="SIGMA_ALTITUDE"         value="0x00008000" />
+  <id name="SIGMA_HEADING"          value="0x00010000" />
+  <id name="SIGMA_HPOSITION"        value="0x00020000" />
+  <id name="GNSS_FIX_STATUS"        value="0x00040000" />
+  <id name="DR_STATUS"              value="0x00080000" />
+  <id name="RELIABILTY_INDEX"       value="0x00100000" />
+
+  <!-- Time Keys - for use in bit mask -->
+  <id name="YEAR"                   value="0x01000000" />
+  <id name="MONTH"                  value="0x02000000" />
+  <id name="DAY"                    value="0x04000000" />
+  <id name="HOUR"                   value="0x08000000" />
+  <id name="MINUTE"                 value="0x10000000" />
+  <id name="SECOND"                 value="0x20000000" />
+  <id name="MS"                     value="0x40000000" />
+
+  <!-- Generic "Enum" values -->
+  <id name="INVALID"                value="0x00000000" />
+
+  <!-- SatelliteSystem "Enum" -->
+  <id name="GPS"                    value="0x00000001" />
+  <id name="GLONASS"                value="0x00000002" />
+  <id name="GALILEO"                value="0x00000003" />
+  <id name="COMPASS"                value="0x00000004" />
+
+  <!-- PositionFeedback "Enum" -->
+  <id name="MAP_MATCHED_FEEDBACK"   value="0x00000001" />
+  <id name="TEST_FEEDBACK"          value="0x00000002" />
 
   <!-- ... --> 
 </constants>
diff --git a/enhanced-position-service/api/genivi-positioning-enhancedposition.xml b/enhanced-position-service/api/genivi-positioning-enhancedposition.xml
index 1e99d5e..d17205c 100644
--- a/enhanced-position-service/api/genivi-positioning-enhancedposition.xml
+++ b/enhanced-position-service/api/genivi-positioning-enhancedposition.xml
@@ -40,21 +40,32 @@
         <line>GetPositionInfo = This method returns a given set of positioning data (e.g. Position, Course, Accuracy, Status, ... )</line>
       </doc>
 
-      <arg name="valuesToReturn" type="aq" direction="in">
+      <arg name="valuesToReturn" type="t" direction="in">
         <doc>
-          <line>valuesToReturn= array[fieldType]</line>
-          <line>key = enum(INVALID,TIMESTAMP,LATITUDE,LONGITUDE,ALTITUDE,HEADING,SPEED,CLIMB,ROLL_RATE,PITCH_RATE,YAW_RATE,...,ALL)</line>
+          <line>valuesToReturn = Bit mask: Keys corresponding to requested values in one 64 unsigned bit integer, bitwise or'ed </line>
+          <line>Supported Keys:             LATITUDE,LONGITUDE,ALTITUDE,...</line>
+          <line>Supported Keys (continued): HEADING,SPEED,CLIMB,...</line>
+          <line>Supported Keys (continued): ROLL_RATE,PITCH_RATE,YAW_RATE,...</line>
+          <line>Supported Keys (continued): PDOP,HDOP,VDOP,...</line>
+          <line>Supported Keys (continued): USED_SATELLITES,TRACKED_SATELLITES,VISIBLE_SATELLITES,...</line>
+          <line>Supported Keys (continued): SIGMA_HPOSITION,SIGMA_ALTITUDE,SIGMA_HEADING,...</line>
+          <line>Supported Keys (continued): GNSS_FIX_STATUS,DR_STATUS</line>
         </doc>
       </arg>
 
-      <arg name="data" type="a{qv}" direction="out">
+      <arg name="timestamp" type="t" direction="out">
+        <doc>
+          <line>Timestamp of the acquisition of the position data [ms]</line>
+        </doc>
+      </arg>
+      
+      <arg name="data" type="a{tv}" direction="out">
         <doc>
           <line>data = dictionary[key,value]</line>
           <line>dictionary = array of tuples (key,value)</line>
           <line>Invalid data is not be returned to the client application</line>
           <line>The vehicle axis system is defined by ISO 8855: In short, the X-axis pointing is forwards, the Y-axis is pointing left, the Z-axis is pointing upwards</line>
-          <line>key = enum(INVALID,TIMESTAMP,LATITUDE,LONGITUDE,ALTITUDE,HEADING,SPEED,CLIMB,ROLL_RATE,PITCH_RATE,YAW_RATE,PDOP,HDOP,VDOP,USED_SATELLITES,TRACKED_SATELLITES,VISIBLE_SATELLITES,SIGMA_HPOSITION,SIGMA_ALTITUDE,SIGMA_HEADING,GNSS_FIX_STATUS,DR_STATUS,... ,ALL</line>
-          <line>key = TIMESTAMP, value = value of type 't', that represents a timestamp in ms</line>
+          <line>key = enum(LATITUDE,LONGITUDE,ALTITUDE,HEADING,SPEED,CLIMB,ROLL_RATE,PITCH_RATE,YAW_RATE,PDOP,HDOP,VDOP,USED_SATELLITES,TRACKED_SATELLITES,VISIBLE_SATELLITES,SIGMA_HPOSITION,SIGMA_ALTITUDE,SIGMA_HEADING,GNSS_FIX_STATUS,DR_STATUS,... ,ALL</line>
           <line>key = LATITUDE, value = value of type 'd', that expresses the WGS84 latitude of the current position in degrees. Range [-90:+90]. Example: 48.053250</line>
           <line>key = LONGITUDE, value = value of type 'd', that expresses the WGS84 longitude of the current position in degrees. Range [-180:+180]. Example: 8.324500</line>
           <line>key = ALTITUDE, value = value of type 'd', that expresses the altitude above the sea level of the current position in meters</line>
@@ -81,48 +92,18 @@
 
     <signal name="PositionUpdate">
       <doc>
-        <line>PositionUpdate = This signal is called to notifiy a client application of a position change. The update frequency is implementation specific. The maximal allowed frequency is 10Hz</line>
-      </doc>
-      <arg name="changedValues" type="aq">
-        <doc>
-          <line>changedValues = array[value]</line>
-          <line>value = enum(INVALID,TIMESTAMP,LATITUDE,LONGITUDE,ALTITUDE,HEADING,SPEED,CLIMB,... )</line>
-        </doc>
-      </arg>
-    </signal>
-
-    <signal name="RotationRateUpdate">
-      <doc>
-        <line>RotationRateUpdated = This signal is emitted when the rotation rate changes</line>
-      </doc>
-      <arg name="changedValues" type="aq">
-        <doc>
-          <line>changedValues = array[key]</line>
-          <line>key = enum(INVALID,TIMESTAMP,ROLL_RATE,PITCH_RATE,YAW_RATE, ... )</line>
-        </doc>
-      </arg>
-    </signal>
-
-    <signal name="GNSSAccuracyUpdate">
-      <doc>
-        <line>GNSSAccuracyUpdate = This signal is emitted when the GNSS accuracy changes</line>
+        <line>PositionUpdate = This signal is called to notifiy a client application of a position change. The update frequency is implementation specific. The maximum allowed frequency is 10Hz</line>
       </doc>
-      <arg name="changedValues" type="aq">
+      <arg name="changedValues" type="t">
         <doc>
-          <line>changedValues = array[value]</line>
-          <line>value = enum(INVALID,TIMESTAMP,PDOP,HDOP,VDOP,USED_SATELLITES,TRACKED_SATELLITES,VISIBLE_SATELLITES, ... )</line>
-        </doc>
-      </arg>
-    </signal>
-
-    <signal name="StatusUpdate">
-      <doc>
-        <line>StatusUpdate = This signal is emitted when the status of this service changes</line>
-      </doc>
-      <arg name="changedValues" type="aq">
-        <doc>
-          <line>changedValues = array[value]</line>
-          <line>key = enum(INVALID,TIMESTAMP,GNSS_FIX_STATUS,DR_STATUS, ... )</line>
+          <line>changedValues = Bit mask: Keys corresponding to changed values in one 64 unsigned bit integer, bitwise or'ed </line>
+          <line>Supported Keys:             LATITUDE,LONGITUDE,ALTITUDE,...</line>
+          <line>Supported Keys (continued): HEADING,SPEED,CLIMB,...</line>
+          <line>Supported Keys (continued): ROLL_RATE,PITCH_RATE,YAW_RATE,...</line>
+          <line>Supported Keys (continued): PDOP,HDOP,VDOP,...</line>
+          <line>Supported Keys (continued): USED_SATELLITES,TRACKED_SATELLITES,VISIBLE_SATELLITES,...</line>
+          <line>Supported Keys (continued): SIGMA_HPOSITION,SIGMA_ALTITUDE,SIGMA_HEADING,...</line>
+          <line>Supported Keys (continued): GNSS_FIX_STATUS,DR_STATUS</line>
         </doc>
       </arg>
     </signal>
@@ -131,16 +112,20 @@
       <doc>
         <line>GetSatelliteInfo = This method returns information about the current satellite constellation</line>
       </doc>
-      <arg name="satelliteInfo" type="a{qv}" direction="out">
+      <arg name="timestamp" type="t" direction="out">
         <doc>
-          <line>satelliteInfo = dictionary[key,value]</line>
-          <line>dictionary = array of tuples (key,value)</line>
-          <line>If you request for a specific value which is invalid, it's not returned in the dictionary.</line>
-          <line>key = enum(INVALID,TIMESTAMP,SATELLITE_DETAILS, ...)</line>
-          <line>key = TIMESTAMP, value = value of type 't', that represents a timestamp in ms</line>  
-          <line>key = SATELLITE_DETAILS, value = value of type 'a(qqbqqq)', that represents an array(struct(system,satelliteId,inUse,elevation,azimuth,snr).
+          <line>Timestamp of the acquisition of the satellite detail data [ms]</line>
+        </doc>
+      </arg>        
+      <arg name="satelliteInfo" type="a{qqqqqb}" direction="out">
+        <doc>
+          <line>Represents an array(struct(system,satelliteId,azimuth,elevation,snr,inUse).
                 The system field identifies the satellite system: GPS, GLONASS, GALILEO, COMPASS, ...
-                The satelliteId is only unique within one satellite system
+                The satelliteId is only unique within one satellite system.
+                Azimuth is in degrees. Value range 0..359.
+                Elevation is in degrees. Value range 0..90.
+                SNR (C/No) is in dBHz. Range 0 to 99, null when not tracking
+                inUse is set to true when the satellite is used for the fix
           </line>  
         </doc>
       </arg>
@@ -150,13 +135,17 @@
       <doc>
         <line>GetTime = This method returns UTC time and date</line>
       </doc>
-      <arg name="time" type="a{qv}" direction="out">
+      <arg name="timestamp" type="t" direction="out">
+        <doc>
+          <line>Timestamp of the acquisition of the UTC date/time [ms]</line>
+        </doc>
+      </arg>        
+      <arg name="time" type="a{tv}" direction="out">
         <doc>
           <line>time = dictionary[key,value]</line>
           <line>dictionary = array of tuples (key,value)</line>
           <line>If you request for a specific value which is invalid, it's not returned in the dictionary.</line>
-          <line>key = enum(INVALID,TIMESTAMP,YEAR,MONTH,DAY,HOUR,MINUTE,SECOND,MS, ... )</line>
-          <line>key = TIMESTAMP, value = value of type 't', that represents a timestamp in ms</line>
+          <line>key = enum(YEAR,MONTH,DAY,HOUR,MINUTE,SECOND,MS, ... )</line>
           <line>key = YEAR, value = value of type 'q', 4 digits number that indicates the year. Example: 2012</line>
           <line>key = MONTH, value = value of type 'y', 2 digits number that indicates the month. Example: 03 means March</line>
           <line>key = DAY, value = value of type 'y', 2 digits number that indicates the day. Range [0:31]. Example: 07</line>
diff --git a/enhanced-position-service/api/genivi-positioning-positionfeedback.xml b/enhanced-position-service/api/genivi-positioning-positionfeedback.xml
index 55418fd..e66bf85 100644
--- a/enhanced-position-service/api/genivi-positioning-positionfeedback.xml
+++ b/enhanced-position-service/api/genivi-positioning-positionfeedback.xml
@@ -40,12 +40,12 @@
         <line>Note: This interface is typically used by the application that implements the map-matching algorithm</line>

         <line>Such application can hand over to the EnhancedPositionService an array of map-matched positions with different values of reliability</line>

       </doc>

-      <arg name="feedback" type="aa{qv}" direction="in">

+      <arg name="feedback" type="aa{tv}" direction="in">

         <doc>

           <line>feedback = array[position]</line>

           <line>position = dictionary[key,value]</line>

           <line>dictionary = array of tuples (key,value)</line>

-          <line>key = enum(INVALID,LATITUDE,LONGITUDE,ALTITUDE,HEADING,SPEED,CLIMB,RELIABILTY_INDEX, ... )</line>

+          <line>key = enum(LATITUDE,LONGITUDE,ALTITUDE,HEADING,SPEED,CLIMB,RELIABILTY_INDEX, ... )</line>

           <line>key = LATITUDE, value = value of type 'd', that expresses the WGS84 latitude of the current position in degrees. Range [-90:+90]. Example: 48.053250</line>

           <line>key = LONGITUDE, value = value of type 'd', that expresses the WGS84 longitude of the current position in degrees. Range [-180:+180]. Example: 8.324500</line>

           <line>key = ALTITUDE, value = value of type 'd', that expresses the altitude above the sea level of the current position in meters</line>

diff --git a/gnss-service/api/gnss.h b/gnss-service/api/gnss.h
index 9c72c71..21d18a3 100644
--- a/gnss-service/api/gnss.h
+++ b/gnss-service/api/gnss.h
@@ -103,7 +103,8 @@ typedef enum {
  * Note: the uncommon numbering of day and month is chosen to be compatible with the struct tm from the standard C-Library
  */
 typedef struct {
-    uint64_t timestamp;             /**< Timestamp of the acquisition of the UTC date/time. */
+    uint64_t timestamp;             /**< Timestamp of the acquisition of the UTC date/time [ms].
+                                         All sensor/GNSS timestamps must be based on the same time source. */
     uint16_t year;                  /**< Year fraction of the UTC time. Unit: [year] Number equivalent to the year (4 digits) */
     uint8_t month;                  /**< Month fraction of the UTC time. Unit: [month] Number betweeen 0 and 11 */
     uint8_t day;                    /**< Day of month fraction of the UTC time. Unit: [day]. Number between 1 and 31 */   
@@ -162,7 +163,8 @@ typedef enum {
  * Detailed data from one GNSS satellite.
  */
 typedef struct {
-    uint64_t timestamp;             /**< Timestamp of the acquisition of the satellite detail data. */
+    uint64_t timestamp;             /**< Timestamp of the acquisition of the satellite detail data [ms].
+                                         All sensor/GNSS timestamps must be based on the same time source. */
     EGNSSSystem system;             /**< Value representing the GNSS system. */
     uint16_t satelliteId;           /**< Satellite ID.
                                          Satellite IDs are only unique within one satellite system.
@@ -224,7 +226,8 @@ typedef enum {
  * for positioning applications such as GNSS/Dead Reckoning sensor fusion.
  */
 typedef struct {
-    uint64_t timestamp;             /**< Timestamp of the acquisition of the GNSS data. [ms] */ 
+    uint64_t timestamp;             /**< Timestamp of the acquisition of the GNSS data [ms].
+                                         All sensor/GNSS timestamps must be based on the same time source. */
     //position
     double latitude;                /**< Latitude in WGS84 in degrees. */ 
     double longitude;               /**< Longitude in WGS84 in degrees. */