@mcesystems/adb-kit

1. Description

What it does: ADB (Android Debug Bridge) toolkit for device management. Provides a TypeScript wrapper around adbkit for Android device operations: listing devices, reading device properties, installing/uninstalling apps, checking and waiting for USB debugging, and port forwarding.

When it's used: Use this package when your application needs to communicate with Android devices over ADB—for example device management tools, test runners, or installers that target Android hardware.

2. Install

npm install @mcesystems/adb-kit

Requirements: Node.js 18+, Android device with USB debugging enabled, and ADB binaries (see Resources).

3. Resources

This package needs ADB binaries to run. You can obtain them in one of these ways:

Option A – Export script (recommended for distribution)
Bundle ADB for your app using the provided script:

npx export-adb-resources /path/to/your-app/resources/adb-kit

# All platforms
npx export-adb-resources /path/to/your-app/resources/adb-kit --all

See scripts/README.md for arguments, options, output layout, and prerequisites.

Option B – Development

• Windows / macOS: Set AdbBinPath to your ADB binary directory, or have adb on system PATH.
• Linux: Install via package manager (e.g. sudo apt install adb).

The package resolves ADB in this order: AdbBinPath env, then bundled resources under dist/resources/bin/<platform>/, then system PATH.

4. Examples

Create a device kit and read properties

import { AdbDeviceKit } from '@mcesystems/adb-kit';

const device = new AdbDeviceKit('device-serial-number', 1);
const [manufacturer, model] = await device.getDeviceProperties(['Manufacturer', 'Model']);
const allProps = await device.getAllDeviceProperties();
const devices = await device.listDevices();

Install/uninstall and check app

await device.installApp('/path/to/app.apk');
const isInstalled = await device.isAppInstalled('com.example.app');
await device.uninstallApp('com.example.app');

USB debugging

const hasDebugging = await device.hasUsbDebugging();
const { promise, events } = device.waitForUsbDebugging(30000); // 30s timeout
events.on("usbDebuggingOff", () => console.log("Enable USB debugging on device"));
events.on("usbDebuggingNeedsAlwaysAllow", () => console.log("Tap Always allow on device"));
events.on("usbDebuggingAuthorized", () => console.log("Device ready"));
const ok = await promise;

Port forwarding

const localPort = await device.startPortForward('tcp:8080');

Low-level clients

const client = await device.getClient();
const deviceClient = await device.getDeviceClient();

First connected Android properties

One-shot example that discovers the first connected Android device and prints a curated set of its properties (manufacturer, model, brand, Android version, etc.).

# From packages/adb-kit
pnpm example:first-android-properties

See src/examples/first-connected-android-properties.ts for the script.

USB debugging robustness example

Interactive example that runs the same flow 5 times to verify waitForUsbDebugging handling: start without USB debugging (device not found), short 5s timeout (user lets it pass), then wait up to 30s while the user enables USB debugging, show device recognized, then user disables USB debugging and repeats.

# From packages/adb-kit (set ADB_DEVICE_SERIAL if USB debugging is off)
pnpm example:usb-debugging

See src/examples/usb-debugging-robustness.ts for the script.

USB debugging playground

Interactive playground to observe status events while you toggle USB debugging on/off or revoke authorizations. Prints events in real time as you change device settings.

# From packages/adb-kit (set ADB_DEVICE_SERIAL if USB debugging is off)
pnpm example:usb-debugging-playground

See src/examples/usb-debugging-playground.ts for the script.

For more scenarios and step-by-step explanations, see Example.md.

5. API

AdbDeviceKit

Constructor

• Input: deviceId: string, port: number
• Output: new AdbDeviceKit instance bound to that device and logical port.

listDevices()

• Input: none
• Output: Promise<AdbDevice[]> — list of connected devices (AdbDevice: { id: string; type: AdbDeviceType }).

getDeviceProperties(properties)

• Input: properties: DeviceProperty[] — e.g. ['Manufacturer', 'Model']
• Output: Promise<string[]> — values in the same order as properties; failed props are "".

getAllDeviceProperties()

• Input: none
• Output: Promise<Record<string, string>> — all device properties from getprop.

installApp(appPath)

• Input: appPath: string — path to APK
• Output: Promise<void> — resolves when install finishes; rejects on failure.

uninstallApp(packageName)

• Input: packageName: string — e.g. 'com.example.app'
• Output: Promise<void> — resolves when uninstall finishes; rejects on failure.

isAppInstalled(packageName)

• Input: packageName: string
• Output: Promise<boolean> — whether the package is installed.

hasUsbDebugging()

• Input: none
• Output: Promise<boolean> — whether this device appears in the ADB device list.

waitForUsbDebugging(timeout?, numberOfAllowedAttempts?)

• Input: timeout?: number (default 120000 ms), numberOfAllowedAttempts?: number (default 5, accepted for backward compatibility; give-up is determined by timeout and tracker end only)
• Output: { promise: Promise<boolean>; events: EventEmitter } — await promise for the result (true when device is ready, false when tracking ends without device; rejects on timeout, device removal, or connection error). Subscribe to events for state changes:
  • usbDebuggingOff — waiting started (USB debugging not enabled on device)
  • usbDebuggingNeedsAlwaysAllow — device visible but user must tap "Always allow" on device
  • usbDebuggingAuthorized — device ready

startPortForward(serviceName)

• Input: serviceName: string — e.g. 'tcp:8080'
• Output: Promise<number | null> — local port number used for forwarding, or null if forwarding failed. Reuses same port on repeated calls.

getClient()

• Input: none
• Output: Promise<AdbClient> — underlying adbkit client.

getDeviceClient()

• Input: none
• Output: Promise<DeviceClient> — adbkit device client for this device.

getDeviceId()

• Input: none
• Output: string — device serial (last segment after \ on Windows).

getPort()

• Input: none
• Output: number — logical port passed to the constructor.

DeviceProperty

Supported property names for getDeviceProperties():
Manufacturer, Name, Model, Brand, Device, Android Version, Platform, CPU, CPU.abi2, Description, Fingerprint, GSM Flexversion, GSM IMEI, Locale Language, Locale Region, Wifi Channels, Board Platform, Product Board, Display ID, Version Incremental, Version SDK, Version Codename, Version Release, Build Date, Build Type, Build User.

6. Flow

Example flow: wait for device, read identity, install an app, then forward a port.

import { AdbDeviceKit } from '@mcesystems/adb-kit';

const deviceId = 'ABC123'; // from your device discovery
const device = new AdbDeviceKit(deviceId, 1);

// 1. Wait for USB debugging (e.g. after user enables it)
const { promise } = device.waitForUsbDebugging(60000);
await promise;

// 2. Identify device
const [manufacturer, model] = await device.getDeviceProperties(['Manufacturer', 'Model']);
console.log(`Device: ${manufacturer} ${model}`);

// 3. Install app
await device.installApp('./build/app.apk');

// 4. Forward a device service to a local port
const localPort = await device.startPortForward('tcp:8080');
console.log(`Service reachable at localhost:${localPort}`);

7. TODO

• [ ] Optional: Re-authorize handling when ADB reports vendor keys not set (revoke and re-authorize device).
• [ ] Optional: Add Example.md with more detailed scenarios and explanations.