vibe code the initial impl

main/calibration.h

@@ -0,0 +1,36 @@
+#pragma once
+#include <stdbool.h>
+#include <stdint.h>
+#include "esp_err.h"
+#include "feature_params.h"
+
+typedef enum {
+    MODE_NORMAL = 0,
+    MODE_LEARNING,
+    MODE_ADAPTING,
+    MODE_BACKGROUND_CAL,
+    MODE_TEST_CAL,          // also used by `selfcheck`
+} app_mode_t;
+
+typedef struct {
+    bool valid;
+    uint32_t n;
+    float min, p5, p50, mean, p95, p99, max;
+} score_stats_t;
+
+esp_err_t calibration_init(void);
+app_mode_t calibration_get_mode(void);      // lock-free read of an aligned word
+const char *calibration_mode_name(app_mode_t m);
+
+// Called by the processing task for every frame while mode != NORMAL.
+void calibration_on_frame(const float fp[NUM_BANDS], bool fp_valid, float rms, float score);
+
+// Blocking sessions, called from console / button tasks. The detector is paused
+// (no alerts) while a session runs. All return ESP_OK on success.
+esp_err_t calibration_run_learn(bool adapt, float weight_new);   // 60 s
+esp_err_t calibration_run_test(bool selfcheck_verdict);          // 10 s
+esp_err_t calibration_run_background(void);                      // 60 s
+esp_err_t calibration_autothresh(void);
+
+bool calibration_get_background(score_stats_t *out);
+bool calibration_get_buzz(score_stats_t *out);