Improve documentation.

Signed-off-by: Jan Kubovy <[email protected]>

Author: jankubovy

src/vss_tools/utils/vhal/property_constants.py

@@ -74,6 +74,7 @@ class VSSDatatypesToVhal:
     Mapping of vss datatypes corresponding to standard VHAL property type IDs. For those VSS datatypes, which don't
     correspond to standard VHAL properties, vendor type IDs were defined. See
     https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehiclePropertyType.aidl
+    and https://source.android.com/docs/automotive/vhal/property-configuration#property-types
     """
 
     VSS_TO_VHAL_TYPE_MAP = {

src/vss_tools/utils/vhal/vehicle_mapping.py

@@ -17,6 +17,24 @@
 class VehicleMappingItem:
     """
     Represents a single vehicle mapping item.
+
+    :param name: Android name of the vehicle property
+    :param property_id: Android area ID of the property (https://android.googlesource.com/platform/packages/services/Car/+/refs/heads/main/car-lib/src/android/car/VehicleAreaType.java)
+    :param area_id: See https://source.android.com/docs/automotive/vhal/property-configuration
+    :param access: See https://source.android.com/docs/automotive/vhal/property-configuration
+    :param change_mode: Android change mode for the property (https://developer.android.com/reference/android/car/hardware/CarPropertyConfig#VEHICLE_PROPERTY_CHANGE_MODE_ONCHANGE)
+    :param unit: Android property unit
+    :param source: Corresponding fully-qualified VSS leaf name.
+    :param formula: For mapping purpose, explains how to map a VSS property to Android property if direct correspondence wasn't found.
+    :param comment: Internal comment about current mapping.
+    :param config_string: Optional Android string to contain property specific configuration.
+    :param datatype:
+    :param type:
+    :param min:
+    :param max:
+    :param allowed:
+    :param default:
+    :param deprecation:
     """
 
     name: str
@@ -42,26 +60,37 @@ class VehicleMappingItem:
     def vhal_group(self):
         """
         VHAL group component of the property ID.
+        - https://source.android.com/docs/automotive/vhal/property-configuration
+        - https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleProperty.aidl
+        - https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehiclePropertyGroup.aidl
         """
         return (self.property_id & 0xF0000000) >> 28
 
     @property
     def vhal_area(self):
         """
         VHAL area component of the property ID.
+        - https://source.android.com/docs/automotive/vhal/property-configuration
+        - https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleProperty.aidl
+        - https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleArea.aidl
+        - https://cs.android.com/android/platform/superproject/main/+/main:packages/services/Car/car-lib/src/android/car/VehicleAreaType.java?q=vehicleareatype.java&ss=android%2Fplatform%2Fsuperproject%2Fmain
         """
         return (self.property_id & 0x0F000000) >> 24
 
     @property
     def vhal_type(self):
         """
         VHAL type component of the property ID.
+        - https://source.android.com/docs/automotive/vhal/property-configuration
+        - https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleProperty.aidl
         """
         return (self.property_id & 0x00FF0000) >> 16
 
     @property
     def vhal_id(self):
         """
         VHAL unique ID component of the property ID.
+        - https://source.android.com/docs/automotive/vhal/property-configuration
+        - https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleProperty.aidl
         """
         return self.property_id & 0x0000FFFF

src/vss_tools/utils/vhal/vhal_mapper.py

@@ -72,6 +72,9 @@ def __get_next_vhal_property_id(self, node: VSSNode) -> int:
             286277632 (0x11104000) = UniqueID (0x00004000) | VehiclePropertyType.STRING (0x00100000) |
                   VehicleArea.GLOBAL (0x01000000) | VehiclePropertyGroup.SYSTEM (0x10000000)
 
+        The ID - vspec static UID generator (https://github.com/COVESA/vss-tools/blob/master/docs/id.md) cannot be used
+        since it needs 4-bytes.
+
         :param node: VSS node that we want to generate a unique VHAL property ID for.
         :returns: 2 bytes unique ID value for the VSS node.
         """
@@ -192,7 +195,7 @@ def load_vss_tree(self, node: VSSNode):
                         r"([a-z])([A-Z])", r"\1_\2", node_name_flat.replace("Vehicle.", "").replace(".", "_")
                     ).upper(),
                     property_id=mapping.property_id if mapping else self.__get_next_vhal_property_id(node),
-                    area_id=mapping.area_id if mapping else VhalMapper.__get_vhal_vehicle_area_id(node),
+                    area_id=mapping.area_id if mapping else self.__get_vhal_vehicle_area_id(node),
                     access=mapping.access if mapping else VhalMapper.__get_vhal_access(node),
                     change_mode=mapping.change_mode if mapping else self.__get_vhal_change_mode(node),
                     unit=mapping.unit
@@ -348,21 +351,37 @@ def generate_aidl_file(self, output_filename=None) -> str:
                 file.write(aidl_class)
         return aidl_class
 
-    @staticmethod
-    def __get_vhal_vehicle_area_id(node: VSSNode) -> int:
+    def __get_vhal_vehicle_area_id(self, node: VSSNode) -> int:
         """
         Android VHAL area ID is described here:
         https://android.googlesource.com/platform/packages/services/Car/+/refs/heads/main/car-lib/src/android/car/VehicleAreaType.java
+        and
+        https://cs.android.com/android/platform/superproject/main/+/main:hardware/interfaces/automotive/vehicle/aidl_property/android/hardware/automotive/vehicle/VehicleArea.aidl
+
+        Area type is always generated as GLOBAL. As of now the resulting mapping file needs to be manually edited
+        when GLOBAL is not fitting. Consequent runs will keep those edits.
+
+        A detection of area ID based on VSS tree may be implemented in the future.
+
+        Note that for vendor properties the area type VENDOR should be used.
 
         :returns: VHAL Area ID.
         """
-        return VhalAreaType.VEHICLE_AREA_TYPE_GLOBAL.value
+        return (
+            VhalAreaType.VEHICLE_AREA_TYPE_VENDOR.value
+            if self.__group == 2
+            else VhalAreaType.VEHICLE_AREA_TYPE_GLOBAL.value
+        )
 
     @staticmethod
     def __get_vhal_access(node: VSSNode) -> int:
         """
         Get vendor property access mode as defined in Android and VSS specification
 
+        In VSS documentation attributes and sensors have READ access, actuators have READ_WRITE access. Only WRITE
+        access was not used in VSS documentation. As a result the properties in mapping will have READ access for VSS
+        attributes and sensors, and READ_WRITE for VSS actuators.
+
         :param node: VSS node (sensor, attribute or actuator).
         :returns: Read for sensor or attribute, read/write for actuator.
         """
@@ -383,8 +402,10 @@ def __get_vhal_access(node: VSSNode) -> int:
 
     def __get_vhal_change_mode(self, node: VSSNode) -> int:
         """
-        Get vendor property change mode as defined in Android specification. Assumption for VSS sensors: numeric
-        datatypes have continuous mode, boolean and string datatypes have on_change mode.
+        Get vendor property change mode as defined in Android specification. VSS attributes and actuators have
+        STATIC change mode. Most VSS sensors also to have STATIC change mode except for those sensors, which could be
+        mapped to Android properties with CONTINUOUS change mode. What properties should have CONTINUOUS change mode
+        must be provided externally.
 
         :param node: sensor, attribute or actuator
         :returns: change mode