summaryrefslogtreecommitdiffstats
path: root/automotive
diff options
context:
space:
mode:
authorEnrico Granata <egranata@google.com>2017-07-24 18:07:04 -0700
committerEnrico Granata <egranata@google.com>2017-07-28 13:34:34 -0700
commit390ced61349eabced38504cf63218990ae46647e (patch)
tree97e28fd1209f066f61843efc140efceed39340bd /automotive
parent73363c1fe9a3edd24761eaff4d242c76ecb9db25 (diff)
downloadplatform_hardware_interfaces-390ced61349eabced38504cf63218990ae46647e.tar.gz
platform_hardware_interfaces-390ced61349eabced38504cf63218990ae46647e.tar.bz2
platform_hardware_interfaces-390ced61349eabced38504cf63218990ae46647e.zip
Improvements to the documentation for the OBD2 properties
Addition of a flag to the configuration for OBD2_FREEZE_FRAME_CLEAR to indicate support for deletion of individual freeze frames. Test: build Bug: 64024685 Change-Id: I43cc448c801a5d59095be03d8056530364860ef5
Diffstat (limited to 'automotive')
-rw-r--r--automotive/vehicle/2.1/default/impl/vhal_v2_1/DefaultConfig.h3
-rw-r--r--automotive/vehicle/2.1/types.hal129
2 files changed, 63 insertions, 69 deletions
diff --git a/automotive/vehicle/2.1/default/impl/vhal_v2_1/DefaultConfig.h b/automotive/vehicle/2.1/default/impl/vhal_v2_1/DefaultConfig.h
index d024a557f6..701317b1c9 100644
--- a/automotive/vehicle/2.1/default/impl/vhal_v2_1/DefaultConfig.h
+++ b/automotive/vehicle/2.1/default/impl/vhal_v2_1/DefaultConfig.h
@@ -86,7 +86,8 @@ const V2_0::VehiclePropConfig kVehicleProperties[] = {
{
.prop = OBD2_FREEZE_FRAME_CLEAR,
.access = V2_0::VehiclePropertyAccess::WRITE,
- .changeMode = V2_0::VehiclePropertyChangeMode::ON_CHANGE
+ .changeMode = V2_0::VehiclePropertyChangeMode::ON_CHANGE,
+ .configArray = {1}
},
{
diff --git a/automotive/vehicle/2.1/types.hal b/automotive/vehicle/2.1/types.hal
index d85ef433c2..aa62aa646f 100644
--- a/automotive/vehicle/2.1/types.hal
+++ b/automotive/vehicle/2.1/types.hal
@@ -131,33 +131,40 @@ enum VehicleProperty: @2.0::VehicleProperty {
/**
* OBD2 Live Sensor Data
*
- * This property uses COMPLEX data to send a snapshot of the current (live)
- * values of the OBD2 sensors provided by the vehicle.
- *
- * VehiclePropConfig
- * configArray[0] : number of vendor-specific integer-valued sensors
- * that can be returned in a frame.
- * configArray[1] : number of vendor-specific float-valued sensors
- * that can be returned in a frame.
- *
- * The values are to be interpreted as follows:
- * the indices defined in Obd2IntegerSensorIndex are to be used to
- * read from int32Values;
- * the indices defined in Obd2FloatSensorIndex are to be used to
- * read from floatValues.
- * the elements of bytes are to be interpreted as a bitmask, such that
- * the bits 0 thru the integer value of
- * Obd2IntegerSensorIndex.LAST_SYSTEM_INDEX + the value of configArray[0]
- * are 1 if the corresponding index is a valid sensor index whose value can
- * be read in the returned int32Values vector, 0 otherwise.
- * the bits Obd2IntegerSensorIndex.LAST_SYSTEM_INDEX+1 thru
- * Obd2FloatingSensorIndex.LAST_SYSTEM_INDEX + the value of configArray[1]
- * are 1 if the corresponding index is a valid sensor index whose value
- * can be read in the returned floatValues vector, 0 otherwise.
- *
- * For example, int32Values[0] corresponds to FUEL_SYSTEM_STATUS, and
- * floatValues[0] corresponds to CALCULATED_ENGINE_LOAD, but that mapping
- * is only valid if the corresponding bits in the bytes vector are set to 1.
+ * Reports a snapshot of the current (live) values of the OBD2 sensors available.
+ *
+ * The configArray is set as follows:
+ * configArray[0] = number of vendor-specific integer-valued sensors
+ * configArray[1] = number of vendor-specific float-valued sensors
+ *
+ * The values of this property are to be interpreted as in the following example.
+ * Considering a configArray = {2,3}
+ * int32Values must be a vector containing Obd2IntegerSensorIndex.LAST_SYSTEM_INDEX + 2
+ * elements (that is, 33 elements);
+ * floatValues must be a vector containing Obd2FloatSensorIndex.LAST_SYSTEM_INDEX + 3
+ * elements (that is, 73 elements);
+ *
+ * It is possible for each frame to contain a different subset of sensor values, both system
+ * provided sensors, and vendor-specific ones. In order to support that, the bytes element
+ * of the property value is used as a bitmask,.
+ *
+ * bytes must have a sufficient number of bytes to represent the total number of possible
+ * sensors (in this case, 14 bytes to represent 106 possible values); it is to be read as
+ * a contiguous bitmask such that each bit indicates the presence or absence of a sensor
+ * from the frame, starting with as many bits as the size of int32Values, immediately
+ * followed by as many bits as the size of floatValues.
+ *
+ * For example, should bytes[0] = 0x4C (0b01001100) it would mean that:
+ * int32Values[0 and 1] are not valid sensor values
+ * int32Values[2 and 3] are valid sensor values
+ * int32Values[4 and 5] are not valid sensor values
+ * int32Values[6] is a valid sensor value
+ * int32Values[7] is not a valid sensor value
+ * Should bytes[5] = 0x61 (0b01100001) it would mean that:
+ * int32Values[32] is a valid sensor value
+ * floatValues[0 thru 3] are not valid sensor values
+ * floatValues[4 and 5] are valid sensor values
+ * floatValues[6] is not a valid sensor value
*
* @change_mode VehiclePropertyChangeMode:ON_CHANGE
* @access VehiclePropertyAccess:READ
@@ -171,41 +178,23 @@ enum VehicleProperty: @2.0::VehicleProperty {
/**
* OBD2 Freeze Frame Sensor Data
*
- * This property uses COMPLEX data to send a snapshot of the values of the
- * OBD2 sensors provided by the vehicle at the time that a diagnostic
- * troubleshooting code (DTC) was recorded by the vehicle.
+ * Reports a snapshot of the value of the OBD2 sensors available at the time that a fault
+ * occurred and was detected.
*
- * VehiclePropConfig
- * configArray[0] : number of vendor-specific integer-valued sensors
- * that can be returned in a frame.
- * configArray[1] : number of vendor-specific float-valued sensors
- * that can be returned in a frame.
+ * A configArray must be provided with the same meaning as defined for OBD2_LIVE_FRAME.
*
- * A get of this property must take the following form:
- * int64Values[0]: timestamp of the freeze frame to retrieve.
- * Valid timestamps are given by OBD2_DTC_INFO.
+ * The values of this property are to be interpreted in a similar fashion as those for
+ * OBD2_LIVE_FRAME, with the exception that the stringValue field may contain a non-empty
+ * diagnostic troubleshooting code (DTC).
*
- * The values are to be interpreted as follows:
- * the indices defined in Obd2IntegerSensorIndex are to be used to
- * read from int32Values;
- * the indices defined in Obd2FloatSensorIndex are to be used to
- * read from floatValues;
- * the elements of bytes are to be interpreted as a bitmask, such that
- * the bits 0 thru the integer value of
- * Obd2IntegerSensorIndex.LAST_SYSTEM_INDEX + the value of configArray[0]
- * are 1 if the corresponding index is a valid sensor index whose value can
- * be read in the returned int32Values vector, 0 otherwise.
- * the bits Obd2IntegerSensorIndex.LAST_SYSTEM_INDEX+1 thru
- * Obd2FloatingSensorIndex.LAST_SYSTEM_INDEX + the value of configArray[1]
- * are 1 if the corresponding index is a valid sensor index whose value
- * can be read in the returned floatValues vector, 0 otherwise.
- * stringValue is the DTC that caused this freeze frame to be recorded.
- *
- * For example, int32Values[0] corresponds to FUEL_SYSTEM_STATUS, and
- * floatValues[0] corresponds to CALCULATED_ENGINE_LOAD, but that mapping
- * is only valid if the corresponding bits in the bytes vector are set to 1,
- * and a possible valid stringValue is "P0176" to indicate a malfunction
- * of the fuel composition sensor circuit.
+ * A IVehicle#get request of this property must provide a value for int64Values[0].
+ * This will be interpreted as the timestamp of the freeze frame to retrieve. A list of
+ * timestamps can be obtained by a IVehicle#get of OBD2_FREEZE_FRAME_INFO.
+ *
+ * Should no freeze frame be available at the given timestamp, a response of NOT_AVAILABLE
+ * must be returned by the implementation. Because vehicles may have limited storage for
+ * freeze frames, it is possible for a frame request to respond with NOT_AVAILABLE even if
+ * the associated timestamp has been recently obtained via OBD2_FREEZE_FRAME_INFO.
*
* @change_mode VehiclePropertyChangeMode:ON_CHANGE
* @access VehiclePropertyAccess:READ
@@ -223,7 +212,7 @@ enum VehicleProperty: @2.0::VehicleProperty {
* memory and available for retrieval via OBD2_FREEZE_FRAME.
*
* The values are to be interpreted as follows:
- * each element of int64Values is the timestamp at which a a fault code
+ * each element of int64Values must be the timestamp at which a a fault code
* has been detected and the corresponding freeze frame stored, and each
* such element can be used as the key to OBD2_FREEZE_FRAME to retrieve
* the corresponding freeze frame.
@@ -241,14 +230,18 @@ enum VehicleProperty: @2.0::VehicleProperty {
* OBD2 Freeze Frame Clear
*
* This property allows deletion of any of the freeze frames stored in
- * vehicle memory, as described by OBD2_DTC_INFO.
- *
- * A set of this property is to be interpreted as follows:
- * if int64Values contains no elements, then all DTCs stored will be cleared;
- * if int64Values contains one or more elements, then DTCs at the timestamps
- * stored in int64Values will be cleared, and the others not cleared, except
- * the memory will be compacted so that all remaining DTCs are stored
- * contiguously.
+ * vehicle memory, as described by OBD2_FREEZE_FRAME_INFO.
+ *
+ * The configArray is set as follows:
+ * configArray[0] = 1 if the implementation is able to clear individual freeze frames
+ * by timestamp, 0 otherwise
+ *
+ * IVehicle#set of this property is to be interpreted as follows:
+ * if int64Values contains no elements, then all frames stored must be cleared;
+ * if int64Values contains one or more elements, then frames at the timestamps
+ * stored in int64Values must be cleared, and the others not cleared. Should the
+ * vehicle not support selective clearing of freeze frames, this latter mode must
+ * return NOT_AVAILABLE.
*
* @change_mode VehiclePropertyChangeMode:ON_CHANGE
* @access VehiclePropertyAccess:WRITE