add ADB server version info

tango-adb · Dec 30, 2024 · ee8a6e5 · ee8a6e5
1 parent 5375673
commit ee8a6e5
Show file tree

Hide file tree

Showing 9 changed files with 126 additions and 24 deletions.
diff --git a/docs/api/server/create-device-connection.mdx b/docs/api/server/create-device-connection.mdx
@@ -21,9 +21,22 @@ declare class AdbServerClient {
 
 Creates a socket to the ADB daemon on the device, letting the server forward packets between the client and the device.
 
-The socket can be used to run an [ADB command](../index.mdx#adb-from-yume-chanadb), or [connect to a socket](../adb/socket.mdx#forward-tunnel) on device.
+## Parameters
 
-Usually you don't need to call this method directly, the `createTransport` method uses it to implement `AdbTransport`.
+### `device`
+
+A [device selector](./selector.mdx).
+
+Using selectors other than transport IDs requires [server version 41](../../internal/version.mdx#v41) or higher. Transport ID selectors are recommended anyway.
+
+### `service`
+
+An [ADB command](../index.mdx#adb-from-yume-chanadb), or a [socket address](../adb/socket.mdx#forward-tunnel) on device to connect to.
+
+
+## Remarks
+
+Usually you don't need to call this method directly. [`createTransport`](./create-transport.mdx) method uses it internally to implement `AdbTransport`.
 
 :::info[Equivalent ADB Command]
 

diff --git a/docs/api/server/get-version.mdx b/docs/api/server/get-version.mdx
@@ -18,7 +18,7 @@ This is the version you see in the error message when you use a wrong ADB client
 adb server version (39) doesn't match this client (41); killing...
 ```
 
-Tango doesn't check the version number, although not thoroughly tested, most of the commands should work on any version of ADB server.
+Some features (for example [waitFor](./wait-for.mdx)) requires a certain version to work.
 
 :::info[Equivalent ADB Command]
 

diff --git a/docs/api/server/wait-for.mdx b/docs/api/server/wait-for.mdx
@@ -5,16 +5,18 @@ sidebar_position: 10
 # `waitFor`
 
 ```ts
-interface AdbServerConnectionOptions {
-  unref?: boolean | undefined;
-  signal?: AbortSignal | undefined;
+namespace AdbServerClient {
+  interface ServerConnectionOptions {
+    unref?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+  }
 }
 
 declare class AdbServerClient {
   waitFor(
     device: AdbServerClient.DeviceSelector,
     state: "device" | "disconnect",
-    options?: AdbServerConnectionOptions
+    options?: AdbServerClient.ServerConnectionOptions
   ): Promise<void>;
 }
 ```
@@ -23,10 +25,29 @@ Wait for a device to be connected or disconnected. This method returns a `Promis
 
 If the selector is `usb`, `tcp` or `undefined`, it won't tell which device is connected or disconnected.
 
+## State
+
+### `device`
+
+Wait for a device to be available.
+
+### `disconnect`
+
+Wait for a device to be disconnected.
+
+This state requires [server version 41](../../internal/version.mdx#v41) or higher, otherwise an "unknown host service" error will be thrown.
+
+If `device` parameter is a transport ID selector, you can use `waitForDisconnect` method instead, which fallbacks to [`trackDevices`](./track-devices.mdx) for server version below 41.
+
 ## Options
 
-- `unref`: If the underlying connection is using Node.js `net` module, then [`unref`](https://nodejs.org/api/net.html#socketunref) the socket, so the process can exit even if the connection is still alive.
-- `signal`: Stops the wait when the signal is aborted.
+### `unref`
+
+If the underlying connection is using Node.js `net` module, then [`unref`](https://nodejs.org/api/net.html#socketunref) the socket, so the process can exit even if the connection is still alive.
+
+### `signal`
+
+Stops waiting when the signal is aborted.
 
 :::info[Equivalent ADB Command]
 

diff --git a/docs/internal/version.mdx b/docs/internal/version.mdx
@@ -0,0 +1,14 @@
+# Server Versions
+
+This is an incomplete list of breaking changes in ADB server.
+
+Because there are internal, undocumented changes, and the source code history is full of refactoring and C++ modernizing, it's difficult to find them.
+
+Thanks https://kirschju.re/posts/listing-historic-versions-of-android-debug-bridge/ for listing ADB server versions and download links.
+
+## v41
+
+Rough commit range: 070e8ba5b57f929de4bef1acea610387dc6544d5...ee7b44d91c809f64cbabc4ced8c05360991c29b2
+
+* Support `wait-for-*-disconnect`
+* Support `tport:` services for selecting devices
diff --git a/docs/scrcpy/versions.mdx b/docs/scrcpy/versions.mdx
@@ -17,12 +17,30 @@ Generally, the latest version should be used, as they contain bug fixes and new
 - ⛔: Not supported
 - (**Breaking**): A breaking change. Some new options are not marked as breaking changes even if they contain protocol changes, as the old client can still work with the new server when the new options are not used.
 
+## v3.1 (2/2)
+
+[Official release notes](https://github.com/Genymobile/scrcpy/releases/tag/v3.1)
+
+| Scrcpy version | `@yume-chan/scrcpy` version | `@yume-chan/adb-scrcpy` version |
+| -------------- | --------------------------- | ------------------------------- |
+| v3.1           | `ScrcpyOptions3_1`          | `AdbScrcpyOptions2_1`           |
+
+### New options
+
+- ✅ Don't destroy contents on virtual displays on exit (`--no-vd-destroy-content`)
+
+### Protocol changes
+
+- ✅ (**Breaking**) Add vendor ID and product ID to UHID create control message
+
 ## v3.0 (9/10)
 
 [Official release notes](https://github.com/Genymobile/scrcpy/releases/tag/v3.0)
 
 | Scrcpy version | `@yume-chan/scrcpy` version | `@yume-chan/adb-scrcpy` version |
 | -------------- | --------------------------- | ------------------------------- |
+| v3.0.2         | `ScrcpyOptions3_0_2`        | `AdbScrcpyOptions2_1`           |
+| v3.0.1         | `ScrcpyOptions3_0_1`        | `AdbScrcpyOptions2_1`           |
 | v3.0           | `ScrcpyOptions3_0`          | `AdbScrcpyOptions2_1`           |
 
 ### New options
@@ -60,6 +78,7 @@ Generally, the latest version should be used, as they contain bug fixes and new
 
 | Scrcpy version | `@yume-chan/scrcpy` version | `@yume-chan/adb-scrcpy` version |
 | -------------- | --------------------------- | ------------------------------- |
+| v2.6.1         | `ScrcpyOptions2_6_1`        | `AdbScrcpyOptions2_1`           |
 | v2.6           | `ScrcpyOptions2_6`          | `AdbScrcpyOptions2_1`           |
 
 ### New options
@@ -73,7 +92,7 @@ Generally, the latest version should be used, as they contain bug fixes and new
 
 | Scrcpy version | `@yume-chan/scrcpy` version | `@yume-chan/adb-scrcpy` version |
 | -------------- | --------------------------- | ------------------------------- |
-| v2.5           | `ScrcpyOptions2_4`          | `AdbScrcpyOptions2_1`           |
+| v2.5           | `ScrcpyOptions2_5`          | `AdbScrcpyOptions2_1`           |
 | v2.4           | `ScrcpyOptions2_4`          | `AdbScrcpyOptions2_1`           |
 
 ### New options
@@ -87,7 +106,7 @@ Generally, the latest version should be used, as they contain bug fixes and new
 
 | Scrcpy version | `@yume-chan/scrcpy` version | `@yume-chan/adb-scrcpy` version |
 | -------------- | --------------------------- | ------------------------------- |
-| v2.3.1         | `ScrcpyOptions2_3`          | `AdbScrcpyOptions2_1`           |
+| v2.3.1         | `ScrcpyOptions2_3_1`        | `AdbScrcpyOptions2_1`           |
 | v2.3           | `ScrcpyOptions2_3`          | `AdbScrcpyOptions2_1`           |
 
 ### New options
@@ -130,7 +149,7 @@ Implement these features in Tango is not a priority, as we are using the interna
 
 | Scrcpy version | `@yume-chan/scrcpy` version | `@yume-chan/adb-scrcpy` version |
 | -------------- | --------------------------- | ------------------------------- |
-| v2.1.1         | `ScrcpyOptions2_1`          | `AdbScrcpyOptions2_1`           |
+| v2.1.1         | `ScrcpyOptions2_1_1`        | `AdbScrcpyOptions2_1`           |
 | v2.1           | `ScrcpyOptions2_1`          | `AdbScrcpyOptions2_1`           |
 
 ### New options
@@ -253,8 +272,8 @@ Implement these features in Tango is not a priority, as we are using the interna
 
 | Scrcpy version | `@yume-chan/scrcpy` version | `@yume-chan/adb-scrcpy` version |
 | -------------- | --------------------------- | ------------------------------- |
-| v1.20          | `ScrcpyOptions1_18`         | `AdbScrcpyOptions1_16`          |
-| v1.19          | `ScrcpyOptions1_18`         | `AdbScrcpyOptions1_16`          |
+| v1.20          | `ScrcpyOptions1_20`         | `AdbScrcpyOptions1_16`          |
+| v1.19          | `ScrcpyOptions1_19`         | `AdbScrcpyOptions1_16`          |
 | v1.18          | `ScrcpyOptions1_18`         | `AdbScrcpyOptions1_16`          |
 
 ### New options
@@ -286,8 +305,8 @@ Implement these features in Tango is not a priority, as we are using the interna
 
 | Scrcpy version | `@yume-chan/scrcpy` version | `@yume-chan/adb-scrcpy` version |
 | -------------- | --------------------------- | ------------------------------- |
-| v1.16          | `ScrcpyOptions1_15`         | `AdbScrcpyOptions1_16`          |
-| v1.15.1        | `ScrcpyOptions1_15`         | `AdbScrcpyOptions1_16`          |
+| v1.16          | `ScrcpyOptions1_16`         | `AdbScrcpyOptions1_16`          |
+| v1.15.1        | `ScrcpyOptions1_15_1`       | `AdbScrcpyOptions1_16`          |
 | v1.15          | `ScrcpyOptions1_15`         | `AdbScrcpyOptions1_16`          |
 | Older versions | Not supported               | Not supported                   |
 

diff --git a/docs/tango/upgrade.mdx b/docs/tango/upgrade.mdx
@@ -1,5 +1,13 @@
 # Upgrade from 1.0.0
 
-This version doesn't include any changes in core packages.
+This page lists changes from version 1.0.0 in core packages.
 
 For changes in Scrcpy-related packages, see [this page](../scrcpy/upgrade.mdx).
+
+## `@yume-chan/adb`
+
+Add partial support for ADB server version 40:
+
+* `createDeviceConnection` now skips server version check when device selector is transport ID
+* `waitFor` now checks server version when `state` is `disconnect`
+* Added `waitForDisconnect` which supports waiting for transport ID disconnect on all server versions
diff --git a/versioned_docs/version-1.0.0/api/server/create-device-connection.mdx b/versioned_docs/version-1.0.0/api/server/create-device-connection.mdx
@@ -21,9 +21,22 @@ declare class AdbServerClient {
 
 Creates a socket to the ADB daemon on the device, letting the server forward packets between the client and the device.
 
-The socket can be used to run an [ADB command](../index.mdx#adb-from-yume-chanadb), or [connect to a socket](../adb/socket.mdx#forward-tunnel) on device.
+## Parameters
 
-Usually you don't need to call this method directly, the `createTransport` method uses it to implement `AdbTransport`.
+### `device`
+
+A [device selector](./selector.mdx).
+
+Using selectors other than transport IDs requires [server version 41](../../internal/version.mdx#v41) or higher. Transport ID selectors are recommended anyway.
+
+### `service`
+
+An [ADB command](../index.mdx#adb-from-yume-chanadb), or a [socket address](../adb/socket.mdx#forward-tunnel) on device to connect to.
+
+
+## Remarks
+
+Usually you don't need to call this method directly. [`createTransport`](./create-transport.mdx) method uses it internally to implement `AdbTransport`.
 
 :::info[Equivalent ADB Command]
 

diff --git a/versioned_docs/version-1.0.0/api/server/get-version.mdx b/versioned_docs/version-1.0.0/api/server/get-version.mdx
@@ -18,7 +18,7 @@ This is the version you see in the error message when you use a wrong ADB client
 adb server version (39) doesn't match this client (41); killing...
 ```
 
-Tango doesn't check the version number, although not thoroughly tested, most of the commands should work on any version of ADB server.
+Some features (for example [waitFor](./wait-for.mdx)) requires a certain version to work.
 
 :::info[Equivalent ADB Command]
 

diff --git a/versioned_docs/version-1.0.0/api/server/wait-for.mdx b/versioned_docs/version-1.0.0/api/server/wait-for.mdx
@@ -5,16 +5,18 @@ sidebar_position: 10
 # `waitFor`
 
 ```ts
-interface AdbServerConnectionOptions {
-  unref?: boolean | undefined;
-  signal?: AbortSignal | undefined;
+namespace AdbServerClient {
+  interface ServerConnectionOptions {
+    unref?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+  }
 }
 
 declare class AdbServerClient {
   waitFor(
     device: AdbServerClient.DeviceSelector,
     state: "device" | "disconnect",
-    options?: AdbServerConnectionOptions
+    options?: AdbServerClient.ServerConnectionOptions
   ): Promise<void>;
 }
 ```
@@ -23,6 +25,18 @@ Wait for a device to be connected or disconnected. This method returns a `Promis
 
 If the selector is `usb`, `tcp` or `undefined`, it won't tell which device is connected or disconnected.
 
+## State
+
+### `device`
+
+Wait for a device to be available.
+
+### `disconnect`
+
+Wait for a device to be disconnected.
+
+This state requires [server version 41](../../internal/version.mdx#v41) or higher, otherwise an "unknown host service" error will be thrown.
+
 ## Options
 
 - `unref`: If the underlying connection is using Node.js `net` module, then [`unref`](https://nodejs.org/api/net.html#socketunref) the socket, so the process can exit even if the connection is still alive.