#pragma once

#include <stdbool.h>

#include "esp_err.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Initialise the CrowPanel V3 NS4168 proximity-ping output.
 *
 * The service owns I2S0 and GPIOs 42 (BCLK), 18 (LRCLK), and 17 (DOUT).
 * It starts a small worker task; no audio is emitted until a target distance is
 * supplied. Calling this function more than once after a successful start is
 * harmless.
 */
esp_err_t audio_service_init(void);

/**
 * @brief Enable or mute proximity pings.
 *
 * This call only updates service state and wakes the audio worker. It never
 * waits for I2S/DMA and is safe to call from normal application tasks.
 */
void audio_service_set_enabled(bool enabled);

/** @return The current user-visible enabled/muted setting. */
bool audio_service_is_enabled(void);

/**
 * @brief Publish the current nearest target distance in metres.
 *
 * Finite positive values are clamped to the supported 0.3--8.0 m audio range.
 * Passing a non-finite or non-positive value has the same effect as
 * audio_service_clear_target(). This call never waits for I2S/DMA.
 */
void audio_service_set_nearest_distance(float distance_m);

/**
 * @brief Indicate that the radar currently has no target.
 *
 * Any active ping is silenced by the audio worker at its next small DMA chunk.
 */
void audio_service_clear_target(void);

/** @return true if a valid nearest-target distance is currently published. */
bool audio_service_has_target(void);

/**
 * @brief Read the published nearest-target distance.
 *
 * @param[out] distance_m Receives the clamped distance when non-NULL.
 * @return true when a target is present, false otherwise.
 */
bool audio_service_get_nearest_distance(float *distance_m);

#ifdef __cplusplus
}
#endif