@capgo/capacitor-uwb

July 2, 2026 · View on GitHub

➡️ Get Instant updates for your App with Capgo

Missing a feature? We'll build the plugin for you 💪

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

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

Platform	Support
iOS	✅ Nearby Interaction peer ranging with distance and direction
Android	✅ Jetpack UWB controller/controlee sessions (Android 12+, UWB hardware)
Web	❌ Not available

Compatibility

Plugin version	Capacitor compatibility	Maintained
v8..	v8..	✅
v7..	v7..	On demand
v6..	v6..	On demand

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.

Param	Type
`options`	`StartPeerSessionOptions`

Since: 8.0.0

startControllerSession(...)

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

Start an Android UWB controller session and return shareable parameters.

Param	Type
`options`	`StartControllerSessionOptions`

Returns: Promise<AndroidControllerSessionResult>

Since: 8.0.0

startControleeSession(...)

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

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

Param	Type
`options`	`StartControleeSessionOptions`

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.

Param	Type
`eventName`	`'rangingUpdate'`
`listenerFunc`	`(event: RangingUpdateEvent) => void`

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

addListener('sessionStateChanged', ...)

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

Listen for session lifecycle changes.

Param	Type
`eventName`	`'sessionStateChanged'`
`listenerFunc`	`(event: SessionStateChangedEvent) => void`

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().

Prop	Type	Description	Since
`supported`	`boolean`	Whether the device hardware supports UWB ranging.	8.0.0
`available`	`boolean`	Whether UWB is currently available and ready for a ranging session.	8.0.0
`platform`	`'ios' \| 'android' \| 'web'`	Platform label returned by the native or web implementation.	8.0.0

DiscoveryTokenResult

Result returned by getDiscoveryToken() on iOS.

Prop	Type	Description	Since
`discoveryToken`	`string`	Base64-encoded `NIDiscoveryToken` to share with a peer out-of-band.	8.0.0

StartPeerSessionOptions

Options for startPeerSession() on iOS.

Prop	Type	Description	Since
`peerDiscoveryToken`	`string`	Base64-encoded peer `NIDiscoveryToken`.	8.0.0
`isCameraAssistanceEnabled`	`boolean`	Whether to enable camera assistance when supported (iOS 16+).	8.0.0

AndroidControllerSessionResult

Parameters returned when starting an Android controller session.

Prop	Type	Description	Since
`rangingParameters`	`AndroidRangingParameters`	Ranging parameters to share with the controlee out-of-band.	8.0.0
`localAddress`	`string`	Local UWB address as a base64-encoded byte array.	8.0.0

AndroidRangingParameters

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

Prop	Type	Description	Since
`sessionId`	`number`	Session identifier shared by both peers.	8.0.0
`sessionKeyInfo`	`string`	Optional base64-encoded session key info.	8.0.0
`subSessionId`	`number`	Optional sub-session identifier for provisioned STS.	8.0.0
`subSessionKeyInfo`	`string`	Optional base64-encoded sub-session key info.	8.0.0
`complexChannel`	`UwbComplexChannel`	Channel configuration for the ranging session.	8.0.0
`peerAddress`	`string`	Peer UWB address as a base64-encoded byte array.	8.0.0
`uwbConfigType`	`number`	UWB config type. Defaults to unicast DS-TWR on Android.	8.0.0
`slotDurationMillis`	`number`	Slot duration in milliseconds.	8.0.0
`updateRateType`	`number`	Ranging update rate type from `RangingParameters` on Android.	8.0.0

UwbComplexChannel

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

Prop	Type	Description	Since
`channel`	`number`	UWB channel number.	8.0.0
`preambleIndex`	`number`	Preamble index used for the ranging session.	8.0.0

StartControllerSessionOptions

Options for startControllerSession() on Android.

Prop	Type	Description	Since
`sessionId`	`number`	Session identifier shared with the controlee.	8.0.0
`sessionKeyInfo`	`string`	Optional base64-encoded session key info.	8.0.0
`subSessionId`	`number`	Optional sub-session identifier.	8.0.0
`subSessionKeyInfo`	`string`	Optional base64-encoded sub-session key info.	8.0.0
`complexChannel`	`UwbComplexChannel`	UWB channel configuration.	8.0.0
`uwbConfigType`	`number`	UWB config type. Defaults to unicast DS-TWR.	8.0.0
`slotDurationMillis`	`number`	Slot duration in milliseconds.	8.0.0
`updateRateType`	`number`	Ranging update rate type from `RangingParameters` on Android.	8.0.0
`peerAddress`	`string`	Optional controlee UWB address. When provided, ranging starts immediately.	8.0.0

StartControleeSessionOptions

Options for startControleeSession() on Android.

Prop	Type	Description	Since
`rangingParameters`	`AndroidRangingParameters`	Ranging parameters received from the controller out-of-band.	8.0.0

PluginListenerHandle

Prop	Type
`remove`	`() => Promise<void>`

RangingUpdateEvent

Payload emitted by the rangingUpdate listener.

Prop	Type	Description	Since
`distanceMeters`	`number`	Estimated distance to the peer in meters.	8.0.0
`direction`	`UwbDirection`	Direction vector toward the peer when available.	8.0.0
`azimuthRadians`	`number`	Azimuth angle in radians when available.	8.0.0
`elevationRadians`	`number`	Elevation angle in radians when available.	8.0.0
`horizontalAngleRadians`	`number`	Horizontal angle in radians when available.	8.0.0
`timestamp`	`number`	Unix timestamp in milliseconds when the update was received.	8.0.0

UwbDirection

3D direction vector reported by UWB ranging.

Prop	Type	Description	Since
`x`	`number`	X component of the direction vector.	8.0.0
`y`	`number`	Y component of the direction vector.	8.0.0
`z`	`number`	Z component of the direction vector.	8.0.0

SessionStateChangedEvent

Payload emitted by the sessionStateChanged listener.

Prop	Type	Description	Since
`state`	`UwbSessionState`	Current session state.	8.0.0
`reason`	`string`	Optional human-readable reason or error description.	8.0.0

PluginVersionResult

Result returned when requesting the plugin version.

Prop	Type	Description	Since
`version`	`string`	Native plugin version string.	8.0.0

Type Aliases

UwbSessionState

Session lifecycle states reported by the plugin.