Features

• Distance + direction — centimeter-level distance and azimuth/elevation when the hardware supports it.
• Discovery + pairing built in — peers find each other over BLE / MultipeerConnectivity, and the plugin runs the UWB token exchange end-to-end. No QR codes, no hand-rolled signalling.
• One Dart API, two platforms — same surface for Android (androidx.core.uwb) and iOS (NearbyInteraction).
• Apple FiRa accessories — talk to Qorvo, NXP, and other certified UWB tags from iOS out of the box.
• End-to-end encrypted — every Android↔Android session uses a fresh per-pair key; iOS rides Apple's protected discovery channels.
• Production-ready — readiness checks tell you what's supported and which permissions to ask for; typed error codes tell you exactly why something failed, so apps can recover gracefully instead of showing platform stack traces.
• Streams everywhere — discovery, ranging samples, errors, and lifecycle events as Streams you can plug into any state-management solution.

What ranges against what

Platform support

isUwbAvailable() returns false on emulators, the iOS simulator, and devices without a UWB chip — always check it before calling discovery.

iOS 26 / U2 chip caveat. Apple disabled supportsDirectionMeasurement for the U2 chip on iOS 26, so iPhone 15 Pro / Pro Max and the iPhone 16 series report null for azimuthDegrees and elevationDegrees. Distance is unaffected.

Installation

flutter pub add flutter_uwb

Requires Flutter >=3.22 and Dart >=3.3.

Quick start

Both peers run the same code. Pick a unique localName for each side.

import 'package:flutter_uwb/flutter_uwb.dart';

final uwb = FlutterUwb.instance;

if (!await uwb.isUwbAvailable()) return;

// Acceptor side — auto-respond when a peer initiates pairing.
uwb.incomingRequests.listen((req) async {
  final myToken = await uwb.getLocalToken(UwbRole.controlee);
  await uwb.acceptRequest(req.device.id, myToken);
  await uwb.startRanging(req.device.id);
});

uwb.rangingSamples.listen((s) {
  print('${s.distanceMeters.toStringAsFixed(2)} m  '
        '${s.azimuthDegrees?.toStringAsFixed(1)}°');
});

await uwb.startDiscovery('phone-A');

// Initiator side — call from your UI when the user picks a peer.
Future<void> pairAndRange(UwbDevice device) async {
  // Accessories handshake via the Apple NI Accessory Protocol — skip pairWith.
  if (!device.platform.startsWith('accessory')) {
    await uwb.pairWith(device.id);
  }
  await uwb.startRanging(device.id);
}

When you're done:

await uwb.stopRanging();
await uwb.stopDiscovery();

Pairing is asymmetric: one side calls pairWith (the initiator); the other side's incomingRequests stream fires and that side calls acceptRequest. Both sides then call startRanging. Trigger the initiator from your own UI — a button, a QR scan, a server event, whatever fits.

Apple-FiRa accessories (iOS only)

To range against a Qorvo, NXP, or third-party Apple-FiRa tag, register the vendor's BLE service triplet before startDiscovery:

await uwb.registerAccessoryProfile(
  serviceUuid: '<accessory service UUID>',
  rxUuid:      '<accessory rx UUID>',
  txUuid:      '<accessory tx UUID>',
  vendorTag:   'my-tag', // optional — surfaces as `accessory:my-tag`
);

The accessory shows up in deviceFound with device.platform == 'accessory:my-tag'. The Quick Start's pairAndRange already handles it — the platform check skips pairWith and lets startRanging drive Apple's NI Accessory Protocol. Calling registerAccessoryProfile on Android throws UwbException (iOS-only in 1.0.0).

See example/lib/main.dart for a working Qorvo DWM3001CDK profile.

A complete runnable demo lives in example/.

API

RangingSample exposes distanceMeters, azimuthDegrees, elevationDegrees, elapsedRealtimeNanos and the originating deviceId. All mutating methods throw UwbException on failure.

startRanging accepts an optional RangingOptions(cameraAssist, extendedDistance) for iOS opt-ins. Use getDeviceCapabilities() to gate the toggles in your UI.

checkReadiness() returns a snapshot of the UWB radio, Bluetooth, and runtime-permission state — use it before startDiscovery / startRanging to drive an onboarding flow without trying to range first and catching the failure.

Full API docs: pub.dev/documentation/flutter_uwb/latest/

Permissions

import android.Manifest
import android.os.Build
import androidx.core.app.ActivityCompat

private val perms: Array<String> = buildList {
  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
    add(Manifest.permission.BLUETOOTH_SCAN)
    add(Manifest.permission.BLUETOOTH_ADVERTISE)
    add(Manifest.permission.BLUETOOTH_CONNECT)
  } else {
    add(Manifest.permission.ACCESS_FINE_LOCATION)
  }
  if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    add(Manifest.permission.UWB_RANGING)
  }
}.toTypedArray()

ActivityCompat.requestPermissions(this, perms, /*requestCode*/ 1)

<key>NSNearbyInteractionUsageDescription</key>
<string>Used to measure precise distance to nearby devices over UWB.</string>

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Used to discover nearby devices for UWB ranging.</string>

<!-- Required for iOS↔iOS pairing on iOS 17+ (keeps the AWDL sidechannel alive). -->
<key>NSLocalNetworkUsageDescription</key>
<string>Used to coordinate UWB ranging with nearby iPhones.</string>
<key>NSBonjourServices</key>
<array>
  <string>_flutteruwb-uwb._tcp</string>
  <string>_flutteruwb-uwb._udp</string>
</array>

Example app

A runnable demo lives in example/. It wires up discovery, pairing, and a live distance/azimuth readout for same-OS pairs and (on iOS) Apple-FiRa accessories.

Troubleshooting

import 'package:flutter_uwb/flutter_uwb.dart';

void main() {
  if (kDebugMode) UwbLog.setLevel(UwbLogLevel.debug);
  UwbLog.setHandler((level, msg) => debugPrint('[uwb] [$level] $msg'));
  runApp(const MyApp());
}

Architecture

For protocol details, token format, BLE/UWB topology, and the ECDH-keyed Provisioned STS handshake on Android, see doc/architecture.md.

License

MIT