Distance Sensor Design Specification¶
This document specifies the design of the HC-SR04 distance sensor component, implementing real-time measurement processing with dual-queue architecture and EMA filtering.
Document Version: 2.0 Last Updated: 2025-11-12
Overview¶
The distance sensor component uses a dual-queue architecture to separate ISR-level timestamp capture from task-level measurement processing, ensuring real-time performance while providing filtered, validated measurements to consumers.
Architecture Specifications¶
Design: Separate ISR and task responsibilities using FreeRTOS queues for communication. Implementation:
Validation: ISR completes within microseconds, task receives raw timestamps, API consumers get processed measurements. |
Design: HC-SR04 ultrasonic sensor interface using ESP32 GPIO. Implementation:
Validation: GPIO pins configured correctly, ISR service installed, trigger pulse generated. |
Design: IRAM-resident ISR for deterministic timestamp capture. Implementation:
Validation: ISR execution time < 10µs, timestamps captured accurately, raw queue receives data. |
Design: FreeRTOS task for continuous measurement processing. Implementation:
Validation: Task created successfully, measurement loop operates at configured interval, processes raw data correctly. |
Algorithm Specifications¶
Design: Integer arithmetic for temperature-compensated distance calculation. Implementation:
Validation: Distance calculations accurate within ±1mm for known echo durations and temperatures. |
Design: Exponential Moving Average filter using integer arithmetic. Implementation:
Validation: Smoothing reduces noise while maintaining responsiveness, factor extremes (0, 1000) work correctly. |
API Specifications¶
Design: Simple blocking and monitoring API for consumers. Implementation:
Validation: Blocking API waits for new data, non-blocking API returns immediately, monitoring functions provide accurate metrics. |
Error Handling Specifications¶
Design: Comprehensive error detection and recovery. Implementation:
Validation: Error conditions produce correct status codes, overflow policy drops oldest correctly, system continues operation. |
Simulator Specification¶
Design: Provide a simulator implementation for the distance sensor that implements the
full public API declared in Implementation:
Validation: Simulator build compiles, Example Implementation Pattern: // Simulated sensor with animated distance sweep
static void distance_sensor_task(void* pvParameters) {
static uint16_t sim_distance = 50; // Start at 5cm
static int8_t direction = 1; // 1 = increasing, -1 = decreasing
while(1) {
// Animate distance: 5cm → 60cm → 5cm (1mm steps)
sim_distance += direction;
if (sim_distance >= 600) direction = -1; // 60cm
if (sim_distance <= 50) direction = 1; // 5cm
distance_measurement_t sim_data = {
.distance_mm = sim_distance,
.timestamp_us = esp_timer_get_time(),
.status = DISTANCE_SENSOR_OK
};
xQueueSend(processed_measurement_queue, &sim_data, portMAX_DELAY);
vTaskDelay(pdMS_TO_TICKS(1000)); // 1 second steps
}
}
|