@kevindupas/capacitor-packet-loss

True UDP packet loss measurement for Capacitor apps — native DatagramSocket on Android, automatic HTTP fallback recommended on iOS/web.

iOS / Web: Raw UDP sockets are not available in WebKit. measure() throws unimplemented on iOS and web — implement an HTTP fallback in your app if needed.

How it works

1. App sends count UDP packets (4-byte sequence number) to your echo server.
2. Server echoes each packet unchanged.
3. Plugin counts received echoes within timeoutMs → computes lossPercent.

Install

npm install @kevindupas/capacitor-packet-loss
npx cap sync

UDP Echo Server

A ready-to-deploy Node.js echo server is included in server/udp-server.js.

# On your server — open UDP port 5005 first
ufw allow 5005/udp

# Run with PM2
npm install -g pm2
pm2 start server/udp-server.js --name dqos-udp
pm2 save && pm2 startup

Environment variable UDP_PORT overrides the default port 5005.

Usage

import { UdpPacketLoss } from '@kevindupas/capacitor-packet-loss';

const result = await UdpPacketLoss.measure({
  host: '197.0.0.1',   // your UDP echo server IP
  port: 5005,
  count: 50,
  timeoutMs: 3000,
  intervalMs: 20,
});

console.log(`Loss: ${result.lossPercent}%`);
// { sent: 50, received: 48, lossPercent: 4.0 }

API

• measure(...)
• Interfaces

measure(...)

measure(options: { host: string; port?: number; count?: number; timeoutMs?: number; intervalMs?: number; }) => Promise<UdpPacketLossResult>

Sends count numbered UDP packets to an echo server and counts how many echoes are received within timeoutMs. Android only — uses native DatagramSocket. Throws "unimplemented" on iOS and web.

| Param | Type | | ------------- | ------------------------------------------------------------------------------------------------------ | | options | { host: string; port?: number; count?: number; timeoutMs?: number; intervalMs?: number; } |

Returns: Promise<UdpPacketLossResult>

Interfaces

UdpPacketLossResult

| Prop | Type | Description | | ----------------- | ------------------- | -------------------------------------------------- | | sent | number | Number of packets sent. | | received | number | Number of echo packets received. | | lossPercent | number | Packet loss percentage (0–100, one decimal place). |