feat: implement multidistance rssi->distance model parameter estimation

lib/localiser/web/schemas.ex

@@ -140,11 +140,49 @@ defmodule Localiser.Web.Schemas do
     require OpenApiSpex
     OpenApiSpex.schema(%{
       title: "CalibrationStatus", type: :object,
-      properties: %{status: %Schema{type: :string, enum: ["calibrating", "idle"]}},
+      properties: %{status: %Schema{type: :string, enum: ["idle"]}},
       required: [:status]
     })
   end
 
+  defmodule CalibrationBeginResponse do
+    require OpenApiSpex
+    OpenApiSpex.schema(%{
+      title: "CalibrationBeginResponse", type: :object,
+      properties: %{
+        status:         %Schema{type: :string, enum: ["calibration_mode"]},
+        samples_needed: %Schema{type: :integer}
+      },
+      required: [:status, :samples_needed]
+    })
+  end
+
+  defmodule CalibrationStageResponse do
+    require OpenApiSpex
+    OpenApiSpex.schema(%{
+      title: "CalibrationStageResponse", type: :object,
+      properties: %{
+        status:         %Schema{type: :string, enum: ["stage_active"]},
+        distance:       %Schema{type: :number, format: :float},
+        samples_needed: %Schema{type: :integer}
+      },
+      required: [:status, :distance, :samples_needed]
+    })
+  end
+
+  defmodule CalibrationFinishResponse do
+    require OpenApiSpex
+    OpenApiSpex.schema(%{
+      title: "CalibrationFinishResponse", type: :object,
+      properties: %{
+        status:          %Schema{type: :string, enum: ["idle"]},
+        rssi_ref:        %Schema{type: :integer},
+        path_loss_exp:   %Schema{type: :number, format: :float}
+      },
+      required: [:status, :rssi_ref, :path_loss_exp]
+    })
+  end
+
   # ── Request body schemas ────────────────────────────────────────────────────
 
   defmodule SetupParams do
@@ -292,17 +330,17 @@ defmodule Localiser.Web.Schemas do
     })
   end
 
-  defmodule CalibrationStartParams do
+  defmodule CalibrationStageParams do
     require OpenApiSpex
     OpenApiSpex.schema(%{
-      title: "CalibrationStartParams", type: :object,
+      title: "CalibrationStageParams", type: :object,
       properties: %{
-        reference_distance: %Schema{
+        distance: %Schema{
           type: :number, format: :float,
-          description: "Known tag-to-sensor distance in metres"
+          description: "Known tag-to-sensor distance in metres (must be > 0)"
         }
       },
-      required: [:reference_distance]
+      required: [:distance]
     })
   end