Skip to main content
Version: next

Watch devices

Google ADB Server has a hidden command to notify the client about device added and removed, so you don't need to poll the device list.

import type { Event } from "@yume-chan/event";

import type { Closeable } from "@yume-chan/adb";

export interface DeviceObserver<T> extends Closeable {
  onDeviceAdd: Event<readonly T[]>;
  onDeviceRemove: Event<readonly T[]>;
  onListChange: Event<readonly T[]>;
  current: readonly T[];
  close(): void;
}

export declare class AdbServerClient {
  trackDevices(): Promise<AdbServerDeviceObserver>;
}

export namespace AdbServerClient {
  export interface DeviceObserver extends DeviceObserverBase<Device> {
    onError: Event<Error>;
  }
}
Equivalent ADB command

There is no equivalent ADB command.

Create an observer​

The AdbServerClient#trackDevices method creates an AdbServerDeviceObserver:

import { AdbServerClient } from "@yume-chan/adb";

declare const client: AdbServerClient;

const observer = await client.trackDevices();

Filter devices by state​

trackDevices method accepts an optional includeStates parameter to filter devices by connection state.

It can be an array of AdbServerClient.ConnectionState:

  • "unauthorized": The device is connected but not yet authorized (a popup should appear on the device to ask for authorization)
  • "offline": The device is connected previously, but now offline (typically for wireless devices)
  • "device": The device is connected and authorized

The default value is ["unauthorized", "device"] for backward compatibility. In a future major version, the default value will be changed to ["unauthorized", "offline", "device"].

import type { AdbServerClient } from "@yume-chan/adb";

declare const client: AdbServerClient;

const observer = await client.trackDevices({
  includeStates: ["unauthorized", "offline", "device"],
});

For more information about device states and the state property, see Get devices.

onError​

The onError event is fired when an error occurs, like the connection to Google ADB Server is lost.

observer.onError((error) => {
  console.error(error);
});

current​

current is an immutable array containing all currently connected devices. It will be populated upon creation. When the list changes, a new array will be created and returned from current.

for (const device of observer.current) {
  console.log(device.serial);
}

onListChange​

When device list changes, the onListChange event will also fire with the new array.

onListChange is a sticky event, meaning newly attached event listeners will be invoked immediately with latest value.

This means, if you don't care about individual add or remove events, only listening to onListChange event is enough, reading current or calling AdbServerClient#getDevices is unnecessary.

observer.onListChange((devices) => {
  console.log(devices === observer.current); // true
});

onDeviceAdd and onDeviceRemove​

The onDeviceAdd and onDeviceRemove events are fired when a device is added or removed. The event argument is an array of AdbServerClient.Device objects that have changed.

observer.onDeviceAdd((devices) => {
  for (const device of devices) {
    console.log(device.serial);
  }
});

observer.onDeviceRemove((devices) => {
  for (const device of devices) {
    console.log(device.serial);
  }
});

Stop the observer​

The close method removes all the event listeners and releases all the resources. The device observer instance is no longer usable after calling close.

observer.close();