Distance Sensor Requirements¶
This document specifies requirements for the HC-SR04 ultrasonic distance sensor component.
Document Version: 2.0 Last Updated: 2025-11-12
Overview¶
The distance sensor component provides precise distance measurement with real-time processing, noise reduction via exponential moving average filtering, and robust error handling.
Functional Requirements¶
Description: The distance sensor component SHALL provide initialization via
Rationale: Deterministic startup sequence is required for reliable sensor operation and system integration. Acceptance Criteria:
Verification: Code review of GPIO configuration and integration test validating successful initialization with NULL and custom configurations. |
Description: The sensor task SHALL generate a 10µs trigger pulse on the configured trigger GPIO pin for each measurement cycle to initiate HC-SR04 ultrasonic measurement. Rationale: HC-SR04 datasheet specifies 10µs trigger pulse requirement for reliable operation. Acceptance Criteria:
Verification: Logic analyzer capture of trigger pin or instrumented test measuring pulse width and timing accuracy. |
Description: The GPIO ISR SHALL capture rising and falling edge timestamps using
Rationale: Accurate distance calculation requires precise echo timing; ISR must remain minimal for real-time system stability. Acceptance Criteria:
Verification: Code review for ISR constraints and timing analysis showing ISR execution time < 10µs. |
Description: The sensor task SHALL calculate distance in millimeters using integer arithmetic with temperature compensation, apply exponential moving average smoothing for valid measurements, and enqueue processed results. Range validation is specified in Range Validation (REQ_SNS_13). Rationale: Separation of concerns keeps ISR minimal while providing filtered, validated measurements to consumers. Acceptance Criteria:
Verification: Unit tests with synthetic timestamps validating distance calculations and EMA filter behavior. |
Description: The component SHALL provide Rationale: Simplified consumer API that eliminates polling overhead and ensures data freshness. Acceptance Criteria:
Verification: Integration test with consumer task blocking on API and validating received measurements. |
Description: The component SHALL provide Rationale: Controlled startup and graceful shutdown enable system power management and error recovery. Acceptance Criteria:
Verification: Unit tests validating task creation, deletion, and state management across start/stop cycles. |
Description: The component SHALL provide monitoring capabilities including queue overflow metrics and health status reporting for operational visibility. Rationale: System operators need visibility into sensor health and potential overload conditions. Acceptance Criteria:
Verification: Stress test forcing queue overflows and validating counter behavior and logging output. |
Non-Functional Requirements¶
Description: The GPIO ISR SHALL execute within microsecond timeframes and comply with real-time system constraints by avoiding floating-point operations, heap allocations, and blocking calls. Rationale: ESP32 real-time stability requires deterministic ISR behavior to prevent system jitter and timing violations. Acceptance Criteria:
Verification: Static analysis for forbidden operations and timing measurement under maximum load conditions. |
Description: The distance sensor component SHALL operate within fixed memory limits using small queue sizes and bounded stack allocation to fit ESP32 memory constraints. Rationale: ESP32 has limited RAM; component must be memory-efficient while maintaining functionality. Acceptance Criteria:
Verification: Memory usage analysis and heap monitoring during component operation. |
Description: The sensor component SHALL operate at configurable measurement intervals with deterministic timing characteristics and appropriate timeout handling. Rationale: Predictable measurement timing enables system coordination and proper sensor operation. Acceptance Criteria:
Verification: Timing analysis with oscilloscope or logic analyzer measuring actual intervals and jitter. |
Description: Distance calculations SHALL use integer arithmetic with temperature compensation to achieve accurate measurements across operational temperature range. Rationale: Measurement accuracy is critical for application functionality; temperature affects sound speed significantly. Acceptance Criteria:
Verification: Calibration tests with known distances at various temperatures and EMA filter validation. |
Error Handling Requirements¶
Description: The system SHALL handle missing echo signals by generating timeout measurements with appropriate status codes when no echo is received within the configured timeout period. Rationale: Missing echoes occur due to signal absorption or reflection angles; system must continue operation. Acceptance Criteria:
Verification: Test with echo pin disconnected or sensor obstruction causing timeouts. |
Description: The system SHALL validate measurement range and flag out-of-range values without applying smoothing to preserve error information. Rationale: Out-of-range measurements indicate sensor issues or environmental conditions requiring user attention. Acceptance Criteria:
Verification: Unit tests with synthetic timestamps producing out-of-range distances and validation of status codes. |
Description: The system SHALL implement drop-oldest policy for processed queue overflow with statistics tracking to handle consumer backpressure without blocking sensor operation. Rationale: Slow consumers should not disrupt sensor measurement timing; overflow indicates system load issues. Acceptance Criteria:
Verification: Load testing with slow consumer to force overflows and validate drop-oldest behavior and statistics. |