Skip to main content
Version: next

Create client

ADB Server has its own sets of commands. AdbServerClient class is a TypeScript re-implementation of Google ADB Client, that provides a high-level API to interact with the Server.

Create connector​

AdbServerClient class needs to connect to the ADB Server using TCP sockets. To support different runtime environments, AdbServerClient uses an AdbServerConnector implementation to create those TCP sockets.

Web​

Direct Socket API is a new Web API that provides TCP and UDP sockets. The TCPSocket class from this API can be used to create a TCP connection to ADB Servers.

However, as of September 2024, it's still not clear how Direct Socket API will be implemented. The current proposal requires the Web app to be bundled and signed by the developer, then manually installed by users. This is not a practical solution for general Web apps.

Another method to get TCP sockets on Web platform is to use a native "bridge" app to convert TCP sockets to WebSocket. They are usually called "WebSockify" softwares.

We provide a more sophisticated bridge app, which also bundles and starts Google ADB if it's not available of not running. The source code is at https://github.com/tango-adb/bridge-rs.

Node.js​

The @yume-chan/adb-server-node-tcp package provides a server connector based on Node.js built-in net module.

npm i @yume-chan/adb-server-node-tcp

The constructor saves the connection information, and each command will create a new connection to the server.

Default Connection​

Connects to the default socket spec using environment variables if set.

declare class AdbServerNodeTcpConnector {
  constructor();
}

If environment variable ADB_SERVER_SOCKET is set, it will be parsed as an ADB socket spec and used. Otherwise, a TCP socket spec is used, where the host is localhost or the value of the environment variable ANDROID_ADB_SERVER_ADDRESS, and the port is 5037 or the value of the environment variable ANDROID_ADB_SERVER_PORT.

Equivalent ADB Command
# Set environment variables for server connection
export ADB_SERVER_SOCKET=tcp:localhost:5037
# or
export ANDROID_ADB_SERVER_ADDRESS=localhost
export ANDROID_ADB_SERVER_PORT=5037

# Then run adb commands normally
adb devices
import { AdbServerNodeTcpConnector } from "@yume-chan/adb-server-node-tcp";

const connector: AdbServerNodeTcpConnector = new AdbServerNodeTcpConnector();

ADB Socket Spec String​

Connects to the specified socket using an ADB socket spec string.

declare class AdbServerNodeTcpConnector {
  constructor(spec: string);
}

Accepts an ADB socket spec string to define the connection.

TCP sockets:

  • "tcp:<host>": connects to the default TCP port on the specified host
  • "tcp:<port>": connects to the specified TCP port on default host
  • "tcp:<host>:<port>": connects to the specified port on the specified host

Unix domain sockets:

  • "local:<path>" or "localfilesystem:<path>": connects to the specified Unix domain socket on a file path. Not supported on Windows.

The default host is localhost, or the value of the environment variable ANDROID_ADB_SERVER_ADDRESS. The default port is 5037, or the value of the environment variable ANDROID_ADB_SERVER_PORT.

vsock: and localabstract: socket specs are not supported.

Equivalent ADB Command
# Using the -L flag to specify the socket
adb -L tcp:localhost:5037 devices

# Or set environment variable
export ADB_SERVER_SOCKET=tcp:localhost:5037
adb devices
import { AdbServerNodeTcpConnector } from "@yume-chan/adb-server-node-tcp";

const connector: AdbServerNodeTcpConnector = new AdbServerNodeTcpConnector("tcp:localhost:5037");

TCP Socket Options​

Connects using specific TCP socket connection options.

declare class AdbServerNodeTcpConnector {
  constructor(
      spec: Omit<TcpSocketConnectOpts, "port"> & {
          port?: number | undefined;
      },
  );
}

Uses the specified TCP connect options.

Unlike the original Node.js TCP connect options, the port field is also optional.

If both port and host fields are undefined, and environment variable ADB_SERVER_SOCKET is set, it will be parsed as an ADB socket spec and used. Otherwise, if the host field is undefined, the default value is localhost or the value of the environment variable ANDROID_ADB_SERVER_ADDRESS. If the port field is undefined, the default value is 5037 or the value of the environment variable ANDROID_ADB_SERVER_PORT.

Equivalent ADB Command
# Using the -H and -P flags to specify host and port
adb -H localhost -P 5037 devices

# Or set environment variables
export ANDROID_ADB_SERVER_ADDRESS=localhost
export ANDROID_ADB_SERVER_PORT=5037
adb devices
import { AdbServerNodeTcpConnector } from "@yume-chan/adb-server-node-tcp";

const connector: AdbServerNodeTcpConnector = new AdbServerNodeTcpConnector({
  host: "localhost",
  port: 5037,
});

Unix Domain Socket​

Connects using Node.js Unix domain socket connection options.

declare class AdbServerNodeTcpConnector {
  constructor(spec: IpcSocketConnectOpts);
}

Uses the specified Node.js domain socket connect options. Not supported on Windows, because ADB server can't listen on Named Pipes on Windows.

Equivalent ADB Command
# Using the -L flag with local socket (Unix only)
adb -L local:/path/to/adb_socket devices
import { AdbServerNodeTcpConnector } from "@yume-chan/adb-server-node-tcp";

const connector: AdbServerNodeTcpConnector = new AdbServerNodeTcpConnector({
  path: "/path/to/socket",
});

Create client​

With a server connector, we can create a client:

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

const client: AdbServerClient = new AdbServerClient(connector);

This step doesn't send or receive any packets, it only initializes some internal states.