Merge pull request #394 from rdkcentral/feature/392-sensor-doc-clarifications

docs: clarify sensor HAL timing semantics, lifecycle model, and shutdown handling (#392)

Author: Ulrond

sensor/current/com/rdk/hal/sensor/motion/IMotionSensor.aidl

@@ -24,6 +24,27 @@
  * The motion sensor can operate in a mode that reports either "motion" events
  * or "no-motion" events after an inactivity window. Sensitivity is optional:
  * if unsupported, both minSensitivity and maxSensitivity are 0.
+ *
+ * @details
+ * Lifecycle ownership:
+ * The sensor uses a single-owner lifecycle model. start() and stop()
+ * operate on the sensor instance directly — there is no per-client
+ * controller or exclusive open/close pattern. A single middleware
+ * component (e.g., a power management service) should own the sensor
+ * lifecycle, while other components register as event listeners only.
+ *
+ * Timing controls vs active windows:
+ * activeStartSeconds/activeStopSeconds (passed to start()) and active
+ * windows (configured via setActiveWindows()) are independent, layered
+ * mechanisms:
+ *   - Timing controls govern the sensor hardware lifecycle — whether
+ *     the sensor is active at all.
+ *   - Active windows govern event suppression — whether detected events
+ *     are delivered to listeners.
+ *
+ * Timing controls take precedence. Callers are responsible for ensuring
+ * sensible combinations (e.g., that activeStartSeconds does not exceed
+ * the remaining window duration).
  */
 package com.rdk.hal.sensor.motion;
 
@@ -70,9 +91,12 @@ interface IMotionSensor {
      * @param activeStopSeconds Duration in seconds after which the sensor becomes inactive.
      *        Use 0 for no automatic stop.
      *
+     * @pre Sensor must be in STOPPED state.
+     *
      * @returns Success flag indicating sensor start status.
      * @retval true Sensor accepted the start request.
-     * @retval false Sensor could not be started (e.g. invalid hw state).
+     * @retval false Sensor could not be started due to an internal or hardware initialisation failure.
+     * @exception binder::Status EX_ILLEGAL_STATE if sensor is not STOPPED.
      */
     boolean start(in OperationalMode operationalMode,
                   in int noMotionSeconds,

sensor/current/com/rdk/hal/sensor/motion/hfp-sensor-motion.yaml

@@ -41,17 +41,26 @@ sensor:
       supportsDeepSleepAutonomy: true         # Capabilities.supportsDeepSleepAutonomy
 
       # ========================================================================
-      # OPERATIONAL CONFIGURATION (Platform-specific defaults and constraints)
+      # PLATFORM DEFAULTS AND CAPABILITY DECLARATIONS
+      #
+      # These values declare the platform's factory defaults and supported
+      # modes. They are NOT runtime configuration — actual runtime parameters
+      # are set via IMotionSensor.start() and setActiveWindows().
+      #
+      # Used by:
+      #   - VTS test automation to validate against declared capabilities
+      #   - Middleware to query expected defaults without calling the HAL
+      #   - Documentation of platform-specific constraints
       # ========================================================================
-      operational_modes:
+      operational_modes:       # Supported OperationalMode values
         - MOTION
         - NO_MOTION
-      default_mode: MOTION
-      timing:
+      default_mode: MOTION     # Factory default operational mode
+      timing:                  # Factory default timing parameters for start()
         no_motion_seconds: 5     # Default inactivity window before NO_MOTION event
-        active_start_seconds: 0  # Activation delay after start()
-        active_stop_seconds: 0   # Continuous monitoring until stop()
-      active_windows:
+        active_start_seconds: 0  # Default activation delay (0 = immediate)
+        active_stop_seconds: 0   # Default auto-stop (0 = no automatic stop)
+      active_windows:          # Factory default active windows (example values)
         # Example: Monitor during business hours (9am-5pm) and evening (8pm-10pm)
         - startTimeOfDaySeconds: 32400  # 09:00:00 (9 * 3600)
           endTimeOfDaySeconds: 61200    # 17:00:00 (17 * 3600)

sensor/current/com/rdk/hal/sensor/thermal/State.aidl

@@ -44,6 +44,15 @@ enum State {
 
     /**
      * @brief Shutdown is imminent due to critical thermal breach.
+     *
+     * The HAL thermal policy service initiates the shutdown autonomously.
+     * Clients receiving this event via IThermalEventListener should
+     * perform only time-critical cleanup (flush caches, persist critical
+     * state) and must not attempt to manage the reboot themselves.
+     *
+     * The thermal HAL records the shutdown reason so that on the next boot
+     * it can be reported by the Boot HAL via IBoot.getBootReason() as
+     * BootReason.THERMAL_RESET.
      */
     CRITICAL_SHUTDOWN_IMMINENT = 3
 }