@capgo/capacitor-uwb

Measure distance and direction between nearby devices with Ultra-Wideband in your Capacitor app, for precise finding, unlocking and proximity experiences.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-uwb in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-uwb to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Availability: isAvailable() checks UWB support on the device.
• iOS peer sessions: getDiscoveryToken() and startPeerSession() with Nearby Interaction.
• Android sessions: startControllerSession() and startControleeSession() with Jetpack UWB.
• Ranging events: rangingUpdate reports distance and direction, sessionStateChanged tracks the session.
• Stop: stopSession() ends ranging.
• Platforms: iOS and Android. Needs UWB hardware. Not available on web.

Why this plugin

This plugin wraps the native UWB ranging APIs on iOS and Android so a Capacitor app can:

• Check whether the current device supports UWB ranging.
• Run peer-to-peer ranging on iOS with Apple's Nearby Interaction framework.
• Run controller/controlee ranging sessions on Android with Jetpack androidx.core.uwb.
• Receive distance, direction, and session lifecycle updates through plugin listeners.

On iOS, peers exchange NIDiscoveryToken values out-of-band, then call startPeerSession(). On Android, the controller shares ranging parameters out-of-band before the controlee starts its session.

Platform support

Compatibility

The plugin major version follows the Capacitor major version.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-uwb` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

bun add @capgo/capacitor-uwb
bunx cap sync

Usage

import { CapacitorUwb } from '@capgo/capacitor-uwb';

const availability = await CapacitorUwb.isAvailable();
if (!availability.available) {
  return;
}

await CapacitorUwb.addListener('rangingUpdate', (update) => {
  console.log(update.distanceMeters, update.direction);
});

// iOS: exchange discovery tokens out-of-band, then start ranging
const { discoveryToken } = await CapacitorUwb.getDiscoveryToken();
await CapacitorUwb.startPeerSession({ peerDiscoveryToken: '<peer-token-base64>' });

// Android: controller shares ranging parameters out-of-band
const controller = await CapacitorUwb.startControllerSession();
await CapacitorUwb.startControleeSession({
  rangingParameters: {
    ...controller.rangingParameters,
    peerAddress: controller.localAddress,
  },
});

await CapacitorUwb.stopSession();

Notes

• Test on real UWB hardware. Simulators and most desktop browsers do not expose UWB radios.
• iOS: Add the Nearby Interaction capability in Xcode and set NSNearbyInteractionUsageDescription in Info.plist.
• Android: The plugin declares android.permission.UWB_RANGING. Exchange ranging parameters out-of-band between controller and controlee before starting sessions.
• Web: isAvailable() returns supported: false.

Full setup guides: capgo.app/docs/plugins/uwb

Example app

The example-app/ folder contains a small Vite demo for checking availability, exchanging session parameters, listening for ranging updates, and stopping sessions.

API

• isAvailable()
• getDiscoveryToken()
• startPeerSession(...)
• startControllerSession(...)
• startControleeSession(...)
• stopSession()
• addListener('rangingUpdate', ...)
• addListener('sessionStateChanged', ...)
• removeAllListeners()
• getPluginVersion()
• Interfaces
• Type Aliases

Capacitor plugin for Ultra-Wideband (UWB) ranging on iOS and Android.

iOS uses Apple's Nearby Interaction framework for peer-to-peer ranging. Android uses Jetpack androidx.core.uwb for controller/controlee sessions.

Both platforms require exchanging discovery tokens or ranging parameters out-of-band (for example over Bluetooth LE or a backend).

isAvailable()

isAvailable() => Promise<UwbAvailabilityResult>

Check whether UWB is supported and currently available on the device.

Returns: Promise<UwbAvailabilityResult>

Since: 8.0.0

getDiscoveryToken()

getDiscoveryToken() => Promise<DiscoveryTokenResult>

Get the local Nearby Interaction discovery token on iOS.

Share the returned token with a peer out-of-band, then call startPeerSession() with the peer token.

Returns: Promise<DiscoveryTokenResult>

Since: 8.0.0

startPeerSession(...)

startPeerSession(options: StartPeerSessionOptions) => Promise<void>

Start a Nearby Interaction peer session on iOS.

Since: 8.0.0

startControllerSession(...)

startControllerSession(options?: StartControllerSessionOptions | undefined) => Promise<AndroidControllerSessionResult>

Start an Android UWB controller session and return shareable parameters.

Returns: Promise<AndroidControllerSessionResult>

Since: 8.0.0

startControleeSession(...)

startControleeSession(options: StartControleeSessionOptions) => Promise<void>

Start an Android UWB controlee session with parameters from the controller.

Since: 8.0.0

stopSession()

stopSession() => Promise<void>

Stop the active UWB ranging session.

Since: 8.0.0

addListener('rangingUpdate', ...)

addListener(eventName: 'rangingUpdate', listenerFunc: (event: RangingUpdateEvent) => void) => Promise<PluginListenerHandle>

Listen for distance and direction updates from an active session.

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

addListener('sessionStateChanged', ...)

addListener(eventName: 'sessionStateChanged', listenerFunc: (event: SessionStateChangedEvent) => void) => Promise<PluginListenerHandle>

Listen for session lifecycle changes.

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all registered listeners for this plugin.

Since: 8.0.0

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Get the current native plugin version.

Returns: Promise<PluginVersionResult>

Since: 8.0.0

Interfaces

UwbAvailabilityResult

Result returned by isAvailable().

DiscoveryTokenResult

Result returned by getDiscoveryToken() on iOS.

StartPeerSessionOptions

Options for startPeerSession() on iOS.

AndroidControllerSessionResult

Parameters returned when starting an Android controller session.

AndroidRangingParameters

Android ranging parameters exchanged out-of-band between controller and controlee.

UwbComplexChannel

Android UWB complex channel exchanged out-of-band with a peer.

StartControllerSessionOptions

Options for startControllerSession() on Android.

StartControleeSessionOptions

Options for startControleeSession() on Android.

PluginListenerHandle

RangingUpdateEvent

Payload emitted by the rangingUpdate listener.

UwbDirection

3D direction vector reported by UWB ranging.

SessionStateChangedEvent

Payload emitted by the sessionStateChanged listener.

PluginVersionResult

Result returned when requesting the plugin version.

Type Aliases

UwbSessionState

Session lifecycle states reported by the plugin.

'initialized' | 'running' | 'suspended' | 'resumed' | 'invalidated' | 'stopped' | 'peerDisconnected'