Distance Sensor API

API Component: Distance Sensor API_COMP_DISTANCE_SENSOR
status: implemented
header_file: main/components/distance_sensor/distance_sensor.h
links outgoing: REQ_SNS_1, REQ_SNS_2, REQ_SNS_3, REQ_SNS_4, REQ_SNS_5, REQ_SNS_6, REQ_SNS_7, REQ_SNS_8, REQ_SNS_9, REQ_SNS_10

Brief Description

HC-SR04 ultrasonic distance sensor driver with dual-queue, interrupt-driven architecture for real-time, race-condition-safe measurement processing. Provides blocking and non-blocking APIs, queue overflow statistics, and health monitoring.

Key features:

  • Dual-queue architecture: ISR → Task (raw), Task → API (processed)

  • Real-time, race-condition-safe, no floating-point in ISR

  • Temperature compensation, range validation, EMA filtering

  • Blocking and non-blocking measurement APIs

  • Queue overflow statistics and health monitoring

Architecture:

  • ISR captures timestamps only, sends to raw queue (IRAM_ATTR, real-time safe)

  • Sensor task processes measurements, applies filtering, sends to processed queue

  • API blocks until new data is available, no shared variables

  • Queue overflow handling and statistics

  • Health monitoring for diagnostics

Lifecycle Functions

API Function: distance_sensor_init API_FUNC_DISTANCE_SENSOR_INIT
status: implemented
api_signature: esp_err_t distance_sensor_init(gpio_num_t trigger_pin, gpio_num_t echo_pin)
returns: ESP_OK on success, ESP_ERR_INVALID_STATE, ESP_ERR_INVALID_ARG, ESP_ERR_*
parameters: trigger_pin, echo_pin
component: API_COMP_DISTANCE_SENSOR
links outgoing: REQ_SNS_1, REQ_SNS_5, REQ_SNS_6, REQ_SNS_9

Initialize the distance sensor, configure GPIO, ISR, and queues. Loads configuration from config_manager.

Signature:

esp_err_t distance_sensor_init(gpio_num_t trigger_pin, gpio_num_t echo_pin);

Parameters:

  • trigger_pin - GPIO pin for HC-SR04 trigger signal

  • echo_pin - GPIO pin for HC-SR04 echo signal

Returns:

  • ESP_OK - Initialization successful

  • ESP_ERR_INVALID_STATE - Config manager not initialized

  • ESP_ERR_INVALID_ARG - Invalid pin arguments

  • ESP_ERR_* - Other configuration or hardware errors

Note

  • See requirements: REQ_SNS_1, REQ_SNS_5, REQ_SNS_6, REQ_SNS_9

  • Dual-queue, race-condition-safe, config_manager integration
API Function: distance_sensor_start API_FUNC_DISTANCE_SENSOR_START
status: implemented
api_signature: esp_err_t distance_sensor_start(void)
returns: ESP_OK on success
parameters: None
component: API_COMP_DISTANCE_SENSOR
links outgoing: REQ_SNS_2, REQ_SNS_3, REQ_SNS_4, REQ_SNS_8

Start distance measurements, create measurement task, trigger sensors, process results.

Signature:

esp_err_t distance_sensor_start(void);

Parameters:

  • None

Returns:

  • ESP_OK - Task started successfully

Note

  • See requirements: REQ_SNS_2, REQ_SNS_3, REQ_SNS_4, REQ_SNS_8

  • Dual-queue, real-time, blocking API
API Function: distance_sensor_stop API_FUNC_DISTANCE_SENSOR_STOP
status: implemented
api_signature: esp_err_t distance_sensor_stop(void)
returns: ESP_OK on success
parameters: None
component: API_COMP_DISTANCE_SENSOR
links outgoing: REQ_SNS_8

Stop distance measurements and measurement task.

Signature:

esp_err_t distance_sensor_stop(void);

Parameters:

  • None

Returns:

  • ESP_OK - Task stopped successfully

Note

  • See requirements: REQ_SNS_8

  • API blocking/read semantics

Data Access Functions

API Function: distance_sensor_get_latest API_FUNC_DISTANCE_SENSOR_GET_LATEST
status: implemented
api_signature: esp_err_t distance_sensor_get_latest(distance_measurement_t *measurement)
returns: ESP_OK on success, ESP_ERR_INVALID_ARG
parameters: measurement
component: API_COMP_DISTANCE_SENSOR
links outgoing: REQ_SNS_8, REQ_SNS_9

Get the latest distance measurement (blocking until new data is available).

Signature:

esp_err_t distance_sensor_get_latest(distance_measurement_t *measurement);

Parameters:

  • measurement - Pointer to store the measurement result

Returns:

  • ESP_OK - Measurement available

  • ESP_ERR_INVALID_ARG - Null pointer

Note

  • See requirements: REQ_SNS_8, REQ_SNS_9

  • Blocking, race-condition-safe
API Function: distance_sensor_has_new_measurement API_FUNC_DISTANCE_SENSOR_HAS_NEW_MEASUREMENT
status: implemented
api_signature: bool distance_sensor_has_new_measurement(void)
returns: true if new measurement available, false otherwise
parameters: None
component: API_COMP_DISTANCE_SENSOR
links outgoing: REQ_SNS_8

Check if a new measurement is available (non-blocking).

Signature:

bool distance_sensor_has_new_measurement(void);

Parameters:

  • None

Returns:

  • true - New measurement available

  • false - No new measurement

Note

  • See requirements: REQ_SNS_8

  • Non-blocking API

Statistics & Monitoring Functions

API Function: distance_sensor_get_queue_overflows API_FUNC_DISTANCE_SENSOR_GET_QUEUE_OVERFLOWS
status: implemented
api_signature: uint32_t distance_sensor_get_queue_overflows(void)
returns: Number of measurements discarded due to queue overflow
parameters: None
component: API_COMP_DISTANCE_SENSOR
links outgoing: REQ_SNS_6, REQ_SNS_10

Get the number of queue overflows (discarded measurements).

Signature:

uint32_t distance_sensor_get_queue_overflows(void);

Parameters:

  • None

Returns:

  • uint32_t - Number of discarded measurements

Note

  • See requirements: REQ_SNS_6, REQ_SNS_10

  • Diagnostics/statistics
API Function: distance_sensor_monitor API_FUNC_DISTANCE_SENSOR_MONITOR
status: implemented
api_signature: esp_err_t distance_sensor_monitor(void)
returns: ESP_OK on success
parameters: None
component: API_COMP_DISTANCE_SENSOR
links outgoing: REQ_SNS_7, REQ_SNS_10

Perform lightweight sensor health monitoring (queue overflow, health status).

Signature:

esp_err_t distance_sensor_monitor(void);

Parameters:

  • None

Returns:

  • ESP_OK - Monitoring successful

Note

  • See requirements: REQ_SNS_7, REQ_SNS_10

  • Health monitoring, diagnostics
API Function: distance_sensor_is_running API_FUNC_DISTANCE_SENSOR_IS_RUNNING
status: implemented
api_signature: bool distance_sensor_is_running(void)
returns: true if sensor task is running, false otherwise
parameters: None
component: API_COMP_DISTANCE_SENSOR
links outgoing: REQ_SNS_8

Check if the sensor task is running.

Signature:

bool distance_sensor_is_running(void);

Parameters:

  • None

Returns:

  • true - Sensor task running

  • false - Not running

Note

  • See requirements: REQ_SNS_8

  • API blocking/read semantics

Data Types

API Data Structure: distance_sensor_error_t API_STRUCT_DISTANCE_SENSOR_ERROR
status: implemented
component: API_COMP_DISTANCE_SENSOR
links outgoing: REQ_SNS_4

Error codes for distance sensor measurements.

Definition:

typedef enum {
    DISTANCE_SENSOR_OK = 0,
    DISTANCE_SENSOR_TIMEOUT,
    DISTANCE_SENSOR_OUT_OF_RANGE,
    DISTANCE_SENSOR_NO_ECHO,
    DISTANCE_SENSOR_INVALID_READING
} distance_sensor_error_t;

Values:

  • DISTANCE_SENSOR_OK - Measurement successful

  • DISTANCE_SENSOR_TIMEOUT - Echo not received in time

  • DISTANCE_SENSOR_OUT_OF_RANGE - Measurement out of valid range

  • DISTANCE_SENSOR_NO_ECHO - No echo detected

  • DISTANCE_SENSOR_INVALID_READING - Invalid or corrupted reading
API Data Structure: distance_raw_measurement_t API_STRUCT_DISTANCE_SENSOR_RAW_MEASUREMENT
status: implemented
component: API_COMP_DISTANCE_SENSOR
links outgoing: REQ_SNS_3

Raw measurement data from ISR (timestamps only).

Definition:

typedef struct {
    uint64_t echo_start_us;
    uint64_t echo_end_us;
    distance_sensor_error_t status;
} distance_raw_measurement_t;

Fields:

  • echo_start_us - Echo start timestamp (microseconds)

  • echo_end_us - Echo end timestamp (microseconds)

  • status - Measurement status (see distance_sensor_error_t)
API Data Structure: distance_measurement_t API_STRUCT_DISTANCE_SENSOR_MEASUREMENT
status: implemented
component: API_COMP_DISTANCE_SENSOR
links outgoing: REQ_SNS_4

Processed distance measurement.

Definition:

typedef struct {
    uint16_t distance_mm;
    uint64_t timestamp_us;
    distance_sensor_error_t status;
} distance_measurement_t;

Fields:

  • distance_mm - Calculated distance in millimeters (0-65535mm)

  • timestamp_us - Measurement timestamp (microseconds)

  • status - Measurement status (see distance_sensor_error_t)