Watch Protocol

• Flutter: the plugin’s native relays (iOS and Android), used when SynheartSession has a WatchBiosignalProvider.
• Kotlin: WatchSessionRelay (Wear OS).
• Swift: none. A native iOS app sends the commands itself with WCSession.

Transport

• The Flutter plugin sends start_session only if the watch is reachable at that moment (iOS: WCSession.isReachable; Android: at least one connected node).
• The Wearable Data Layer delivers messages only between apps with the same package name and signing certificate. A node can accept a message that no app answers; the Kotlin relay therefore gives up with a sensor_unavailable error if no event arrives within 10 seconds.
• Neither side uses transferUserInfo or DataClient.

Phone → watch

start_session

{
  "command": "start_session",
  "session_id": "abc-123",
  "mode": "focus",
  "duration_sec": 300,
  "profile": {
    "window_sec": 60,
    "emit_interval_sec": 5
  },
  "window_label": "morning-check"
}

stop_session

{ "command": "stop_session", "session_id": "abc-123" }

Watch → phone

Session events

{
  "type": "session_frame",
  "session_id": "abc-123",
  "seq": 3,
  "emitted_at_ms": 1700000015000,
  "metrics": {
    "hr_mean_bpm": 71.8,
    "sample_count": 15,
    "start_ms": 1700000000000,
    "end_ms": 1700000014000
  }
}

• Kotlin decodes events with SessionEvent.fromMap; an event that fails to decode is logged and dropped. An unknown error_code becomes INVALID_STATE.
• Flutter decodes with SessionEvent.fromJson. Its session_error decoder reads the code from code, not error_code, and its biosignal_frame decoder reads samples with timestamp_ms, bpm, rr_interval_ms, accelerometer, and spo2 (the Kotlin and Swift engines write rr_intervals_ms as a list, plus source and device_id).
• In Flutter, decoded events feed WatchBiosignalProvider as heart-rate input; they are not passed to the host stream. See Lifecycle.

Heart-rate samples (Wear OS)

{ "ts_ms": 1700000014000, "bpm": 72.0 }

Flutter channel surface

class SessionChannel {
  Future<void> startSession(SessionConfig config);   // native builds start_session
  Future<void> stopSession(String sessionId);        // native sends stop_session
  Future<SessionStatus?> getStatus();                // native returns null
  Future<WatchStatus?> getWatchStatus();
  Stream<SessionEvent> get events;                   // EventChannel-backed
}

class WatchStatus {
  final bool supported;   // iOS: WatchConnectivity supported; Android: Play services available
  final bool reachable;   // iOS: WCSession.isReachable; Android: a node is connected
  final bool paired;      // iOS: a watch is paired; Android: same as reachable
  final bool installed;   // iOS: companion app installed; Android: same as reachable
}

Ordering

• session_started precedes frames and the summary for a given session_id.
• seq increases within a session; gaps can appear if the transport drops a message.
• session_summary and session_error are mutually exclusive.
• Use emitted_at_ms and sample timestamps for chronological alignment rather than arrival order.

Privacy posture

• Raw samples are not requested over the wire.
• No PII fields are defined — session_id is a host-supplied identifier (Dart defaults to a UUID v4), and window_label is free-form; keep it free of PII.

Related

• Lifecycle — how the phone and watch sessions relate.
• Providers — WatchBiosignalProvider and how it consumes these events.
• Errors — error codes and the error_code / code key difference.