feat: implement sensor calibration flow

lib/data/repositories/phoenix_sensor_repository.dart

@@ -59,4 +59,36 @@ class PhoenixSensorRepository implements SensorRepository {
   Stream<Map<String, dynamic>> sensorEvents() => realtime
       .channelMessages('sensors')
       .map((m) => {'event': m.event, ...m.payload});
+
+  @override
+  Future<int> beginCalibration(int id) async {
+    final json = await client.beginCalibration(id);
+    return json['samples_needed'] as int;
+  }
+
+  @override
+  Future<void> startStage(int id, double distance) =>
+      client.startStage(id, distance);
+
+  @override
+  Future<({double rssiRef, double pathLossExp})> finishCalibration(
+      int id) async {
+    final json = await client.finishCalibration(id);
+    return (
+      rssiRef: (json['rssi_ref'] as num).toDouble(),
+      pathLossExp: (json['path_loss_exp'] as num).toDouble(),
+    );
+  }
+
+  @override
+  Future<void> cancelCalibration(int id) => client.cancelCalibration(id);
+
+  @override
+  Stream<({String event, Map<String, dynamic> payload})> calibrationEvents(
+          String sensorDeviceId) =>
+      realtime.channelMessages('calibration:$sensorDeviceId');
+
+  @override
+  void leaveCalibrationChannel(String sensorDeviceId) =>
+      realtime.leaveChannel('calibration:$sensorDeviceId');
 }

lib/data/repositories/sensor_repository.dart

@@ -16,4 +16,30 @@ abstract class SensorRepository {
   /// Stream of raw SensorsChannel messages. Each map contains an `event` key
   /// (`sensor_announced` or `sensor_enrollment_timeout`) plus the payload.
   Stream<Map<String, dynamic>> sensorEvents();
+
+  // ---------------------------------------------------------------------------
+  // Calibration
+  // ---------------------------------------------------------------------------
+
+  /// Enters calibration mode on the sensor. Returns the number of samples the
+  /// server will collect per stage.
+  Future<int> beginCalibration(int id);
+
+  /// Starts a collection stage at [distance] metres.
+  Future<void> startStage(int id, double distance);
+
+  /// Runs least-squares regression over all completed stages and persists the
+  /// result. Returns the fitted (rssiRef, pathLossExp) pair.
+  Future<({double rssiRef, double pathLossExp})> finishCalibration(int id);
+
+  /// Aborts calibration and discards all accumulated stage data.
+  Future<void> cancelCalibration(int id);
+
+  /// Real-time events from the server's CalibrationChannel.
+  /// Topic: `calibration:{sensorDeviceId}` (the string BLE device ID).
+  Stream<({String event, Map<String, dynamic> payload})> calibrationEvents(
+      String sensorDeviceId);
+
+  /// Leaves the calibration Phoenix channel for [sensorDeviceId].
+  void leaveCalibrationChannel(String sensorDeviceId);
 }

lib/data/sources/localiser/realtime_data_client.dart

@@ -78,6 +78,12 @@ class RealtimeDataClient {
         .map((msg) => (event: msg.event.value, payload: msg.payload ?? const {}));
   }
 
+  /// Leaves [topic] and removes it from the channel cache.
+  void leaveChannel(String topic) {
+    final ch = _channels.remove(topic);
+    ch?.leave();
+  }
+
   /// Pushes [event] on [topic] and waits for the server reply.
   /// The channel must have been joined first via [channel].
   Future<Map<String, dynamic>> push(

lib/data/sources/localiser/sensor_client.dart

@@ -38,17 +38,22 @@ class SensorClient extends LocaliserdClient {
           })
           as Map<String, dynamic>;
 
-  Future<Map<String, dynamic>> startCalibration(
-    int id,
-    double referenceDistance,
-  ) async =>
-      await post('/api/sensors/$id/calibration/start', {
-            'reference_distance': referenceDistance,
+  Future<Map<String, dynamic>> beginCalibration(int id) async =>
+      await post('/api/sensors/$id/calibration/begin') as Map<String, dynamic>;
+
+  Future<Map<String, dynamic>> startStage(int id, double distance) async =>
+      await post('/api/sensors/$id/calibration/stage', {
+            'distance': distance,
           })
           as Map<String, dynamic>;
 
-  Future<Map<String, dynamic>> stopCalibration(int id) async =>
-      await post('/api/sensors/$id/calibration/stop') as Map<String, dynamic>;
+  Future<Map<String, dynamic>> finishCalibration(int id) async =>
+      await post(
+        '/api/sensors/$id/calibration/finish',
+      ) as Map<String, dynamic>;
+
+  Future<void> cancelCalibration(int id) =>
+      delete('/api/sensors/$id/calibration');
 
   Future<String> getVersion(int id) async {
     final response =

lib/domain/models/calibration.dart

@@ -0,0 +1,71 @@
+enum CalibrationPhase { idle, ready, collecting, done, error }
+
+const calibrationDistances = [0.5, 1.0, 2.0, 3.0];
+
+class CalibrationState {
+  const CalibrationState({
+    this.phase = CalibrationPhase.idle,
+    this.samplesNeeded = 0,
+    this.samplesCollected = 0,
+    this.selectedDistance,
+    this.completedDistances = const {},
+    this.waveform = const [],
+    this.latestRssi,
+    this.avgRssi,
+    this.resultRssiRef,
+    this.resultPathLossExp,
+    this.error,
+  });
+
+  final CalibrationPhase phase;
+  final int samplesNeeded;
+  final int samplesCollected;
+  final double? selectedDistance;
+  final Set<double> completedDistances;
+  /// Circular buffer of recent RSSI readings for the waveform, max 30.
+  final List<double> waveform;
+  final double? latestRssi;
+  final double? avgRssi;
+  final double? resultRssiRef;
+  final double? resultPathLossExp;
+  final String? error;
+
+  bool get canFinish =>
+      completedDistances.length >= 2 && phase != CalibrationPhase.collecting;
+
+  double get progress =>
+      samplesNeeded == 0 ? 0 : samplesCollected / samplesNeeded;
+
+  CalibrationState copyWith({
+    CalibrationPhase? phase,
+    int? samplesNeeded,
+    int? samplesCollected,
+    double? selectedDistance,
+    Set<double>? completedDistances,
+    List<double>? waveform,
+    double? latestRssi,
+    double? avgRssi,
+    double? resultRssiRef,
+    double? resultPathLossExp,
+    String? error,
+    bool clearSelectedDistance = false,
+    bool clearLatestRssi = false,
+    bool clearAvgRssi = false,
+    bool clearError = false,
+  }) =>
+      CalibrationState(
+        phase: phase ?? this.phase,
+        samplesNeeded: samplesNeeded ?? this.samplesNeeded,
+        samplesCollected: samplesCollected ?? this.samplesCollected,
+        selectedDistance: clearSelectedDistance
+            ? null
+            : selectedDistance ?? this.selectedDistance,
+        completedDistances: completedDistances ?? this.completedDistances,
+        waveform: waveform ?? this.waveform,
+        latestRssi: clearLatestRssi ? null : latestRssi ?? this.latestRssi,
+        avgRssi: clearAvgRssi ? null : avgRssi ?? this.avgRssi,
+        resultRssiRef: resultRssiRef ?? this.resultRssiRef,
+        resultPathLossExp: resultPathLossExp ?? this.resultPathLossExp,
+        error: clearError ? null : error ?? this.error,
+      );
+}

lib/features/sensors/calibration_notifier.dart

@@ -0,0 +1,177 @@
+import 'dart:async';
+
+import 'package:flutter/services.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../../data/repositories/sensor_repository.dart';
+import '../../domain/models/calibration.dart';
+
+const _waveformCapacity = 30;
+
+class CalibrationNotifier extends StateNotifier<CalibrationState> {
+  CalibrationNotifier({
+    required this.sensorId,
+    required this.sensorDeviceId,
+    required this.repo,
+  }) : super(const CalibrationState());
+
+  final int sensorId;
+  final String sensorDeviceId;
+  final SensorRepository repo;
+
+  StreamSubscription<({String event, Map<String, dynamic> payload})>? _sub;
+
+  /// Joins the calibration Phoenix channel and calls the begin REST endpoint.
+  /// Channel subscription is set up first to guarantee no reading events are
+  /// dropped before the server acknowledges the stage start.
+  Future<void> beginCalibration() async {
+    // Subscribe first, then call REST.
+    _sub = repo
+        .calibrationEvents(sensorDeviceId)
+        .listen(_onEvent, onError: _onError);
+
+    try {
+      final samplesNeeded = await repo.beginCalibration(sensorId);
+      final firstUncompleted = calibrationDistances.first;
+      state = state.copyWith(
+        phase: CalibrationPhase.ready,
+        samplesNeeded: samplesNeeded,
+        samplesCollected: 0,
+        selectedDistance: firstUncompleted,
+        completedDistances: {},
+        waveform: [],
+        clearLatestRssi: true,
+      );
+    } catch (e) {
+      _sub?.cancel();
+      _sub = null;
+      state = state.copyWith(
+        phase: CalibrationPhase.error,
+        error: e.toString(),
+      );
+    }
+  }
+
+  void selectDistance(double distance) {
+    if (state.phase != CalibrationPhase.ready) return;
+    if (state.completedDistances.contains(distance)) return;
+    state = state.copyWith(selectedDistance: distance);
+  }
+
+  Future<void> startStage() async {
+    final distance = state.selectedDistance;
+    if (distance == null || state.phase != CalibrationPhase.ready) return;
+    state = state.copyWith(
+      phase: CalibrationPhase.collecting,
+      samplesCollected: 0,
+      waveform: [],
+      clearLatestRssi: true,
+      clearAvgRssi: true,
+    );
+    try {
+      await repo.startStage(sensorId, distance);
+    } catch (e) {
+      state = state.copyWith(
+        phase: CalibrationPhase.error,
+        error: e.toString(),
+      );
+    }
+  }
+
+  Future<void> finishCalibration() async {
+    try {
+      final result = await repo.finishCalibration(sensorId);
+      _sub?.cancel();
+      _sub = null;
+      repo.leaveCalibrationChannel(sensorDeviceId);
+      state = state.copyWith(
+        phase: CalibrationPhase.done,
+        resultRssiRef: result.rssiRef,
+        resultPathLossExp: result.pathLossExp,
+      );
+    } catch (e) {
+      state = state.copyWith(
+        phase: CalibrationPhase.error,
+        error: e.toString(),
+      );
+    }
+  }
+
+  Future<void> cancelCalibration() async {
+    _sub?.cancel();
+    _sub = null;
+    repo.leaveCalibrationChannel(sensorDeviceId);
+    try {
+      await repo.cancelCalibration(sensorId);
+    } catch (_) {
+      // Best-effort: ignore errors on cancel (sensor may already be idle).
+    }
+    state = const CalibrationState();
+  }
+
+  void _onEvent(({String event, Map<String, dynamic> payload}) msg) {
+    switch (msg.event) {
+      case 'reading':
+        _handleReading(msg.payload);
+      case 'stage_complete':
+        _handleStageComplete(msg.payload);
+      case 'cancelled':
+        state = const CalibrationState();
+      default:
+        break;
+    }
+  }
+
+  void _handleReading(Map<String, dynamic> payload) {
+    final rssi = (payload['rssi'] as num).toDouble();
+    final progress = payload['stage_progress'] as Map<String, dynamic>;
+    final current = progress['current'] as int;
+
+    final newWaveform = List<double>.from(state.waveform);
+    if (newWaveform.length >= _waveformCapacity) newWaveform.removeAt(0);
+    newWaveform.add(rssi);
+
+    final avg = newWaveform.reduce((a, b) => a + b) / newWaveform.length;
+
+    state = state.copyWith(
+      latestRssi: rssi,
+      samplesCollected: current,
+      waveform: newWaveform,
+      avgRssi: avg,
+    );
+  }
+
+  void _handleStageComplete(Map<String, dynamic> payload) {
+    final distance = (payload['distance'] as num).toDouble();
+    final meanRssi = (payload['mean_rssi'] as num).toDouble();
+
+    final completed = {...state.completedDistances, distance};
+    final nextDistance = calibrationDistances
+        .where((d) => !completed.contains(d))
+        .firstOrNull;
+
+    HapticFeedback.mediumImpact();
+
+    state = state.copyWith(
+      phase: CalibrationPhase.ready,
+      completedDistances: completed,
+      avgRssi: meanRssi,
+      selectedDistance: nextDistance,
+      samplesCollected: 0,
+      waveform: [],
+    );
+  }
+
+  void _onError(Object error) {
+    state = state.copyWith(
+      phase: CalibrationPhase.error,
+      error: error.toString(),
+    );
+  }
+
+  @override
+  void dispose() {
+    _sub?.cancel();
+    super.dispose();
+  }
+}

lib/features/sensors/sensor_detail_sheet.dart

@@ -4,6 +4,7 @@ import 'package:go_router/go_router.dart';
 
 import '../../domain/models/sensor.dart';
 import '../../providers.dart';
+import 'calibration_sheet.dart';
 
 void showSensorDetailSheet(BuildContext context, int sensorId) {
   showModalBottomSheet<void>(
@@ -125,6 +126,10 @@ class _SensorDetailSheetState extends ConsumerState<SensorDetailSheet> {
           }),
           onSaveName: () => _saveName(sensor),
           onPlace: () => _placeOnFloorPlan(context, sensor),
+          onCalibrate: () {
+            Navigator.of(context, rootNavigator: true).pop();
+            showCalibrationSheet(context, sensor.id, sensor.sensorId);
+          },
           onDelete: () => _delete(context, sensor),
         );
       },
@@ -142,6 +147,7 @@ class _SheetBody extends StatelessWidget {
     required this.onEditToggle,
     required this.onSaveName,
     required this.onPlace,
+    required this.onCalibrate,
     required this.onDelete,
   });
 
@@ -153,6 +159,7 @@ class _SheetBody extends StatelessWidget {
   final VoidCallback onEditToggle;
   final VoidCallback onSaveName;
   final VoidCallback onPlace;
+  final VoidCallback onCalibrate;
   final VoidCallback onDelete;
 
   @override
@@ -226,6 +233,12 @@ class _SheetBody extends StatelessWidget {
               onPressed: onPlace,
             ),
             const SizedBox(height: 12),
+            OutlinedButton.icon(
+              icon: const Icon(Icons.radar),
+              label: const Text('Calibrate'),
+              onPressed: onCalibrate,
+            ),
+            const SizedBox(height: 8),
             OutlinedButton.icon(
               icon: const Icon(Icons.bluetooth),
               label: const Text('Reprovision'),

lib/providers.dart

@@ -2,6 +2,8 @@ import 'package:flutter_riverpod/flutter_riverpod.dart';
 
 import 'domain/models/server_config.dart';
 import 'domain/models/sensor.dart';
+import 'domain/models/calibration.dart';
+import 'features/sensors/calibration_notifier.dart';
 import 'domain/models/floor.dart';
 import 'domain/models/tag.dart';
 import 'domain/models/particle.dart';
@@ -208,3 +210,18 @@ final particleSnapshotProvider =
     StreamProvider.autoDispose.family<ParticleSnapshot, String>((ref, tagId) {
   return ref.watch(tagRepositoryProvider).watchParticleCloud(tagId);
 });
+
+// ---------------------------------------------------------------------------
+// Calibration state - keyed by sensor DB id
+// ---------------------------------------------------------------------------
+
+/// Interactive calibration state machine for a specific sensor.
+/// Auto-disposed when no widget is watching (e.g. after the sheet closes).
+final calibrationProvider = StateNotifierProvider.autoDispose
+    .family<CalibrationNotifier, CalibrationState, ({int id, String deviceId})>(
+  (ref, sensor) => CalibrationNotifier(
+    sensorId: sensor.id,
+    sensorDeviceId: sensor.deviceId,
+    repo: ref.watch(sensorRepositoryProvider),
+  ),
+);