Implement native ESP-IDF radar firmware

main/audio_service.h

@@ -0,0 +1,61 @@
+#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