yetangitu/ya-webadb
1
0
Fork 0
mirror of https://github.com/yume-chan/ya-webadb.git synced 2025-10-03 09:49:24 +02:00
Code Issues Projects Releases Packages Wiki Activity

doc: update README

Browse source
This commit is contained in:
Simon Chan 2020-08-27 00:42:02 +08:00
parent 14a10a65d5
commit 5951780607
1 changed files with 71 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

82
README.md
View file

@ -1,39 +1,99 @@
# Yet Another WebADB
Connect to your Android phones from everything that can run (supported) web browser, including PC, mac, and even another Android phone.
Connect to your Android phones from any (supported) web browsers, even from another Android phone.
Inspired by [webadb.js](https://github.com/webadb/webadb.js), but completely rewritten.
Try it online at https://yume-chan.github.io/ya-webadb
## How does it work
Currently only the interactive shell (`adb shell`) is implemented, but I think it's the most difficult but interesting part.
[WebUSB](https://wicg.github.io/webusb) API allow JavaScript to communicate with connected USB devices, including Android phones.
WebUSB API gives JavaScript running in supported web browsers access to USB devices, including Android phones.
ADB uses a fairly simple protocol, so it's pretty easy to reimplement with JavaScript.
ADB uses a fairly simple protocol to communicate, so it's pretty easy to reimplement with JavaScript.
`adb shell`, the interactive shell, uses the PTY protocol, and [xterm.js](https://github.com/xtermjs/xterm.js/) can handle it very well.
`adb shell`, the interactive shell, uses plain PTY protocol, and [xterm.js](https://github.com/xtermjs/xterm.js/) can handle it very well.
## Packages
This repository is a monorepo containing following packages:
| Folder Name | Package Name | Description |
|----------------|-----------------------|------------------------------|
| event | `@yume-chan/event` | Provides an EventEmitter pattern. Ready to be published to npm |
| adb | `@yume-chan/adb` | Provides platform-independent ADB logic implemented in TypeScript, requires a [backend](#backend) to work. Ready to be published to npm |
| adb-webusb | `@yume-chan/adb-webusb` | Provides a Web API powered backend for `@yume-chan/adb`. Ready to be published to npm |
| webpack-config | - | Webpack configuration file in TypeScript, will output into `demo` folder |
| demo | - | A sample website demonstrating usage of `@yume-chan/adb` and `@yume-chan/adb-webusb` packages |
## Backend
`@yume-chan/adb` isn't tied to a specific transfer API. In fact it doesn't use any Web-only API, so with a proper backend it may also be able to run on Node.js or Electron.
A backend needs to provide these functions:
1. Data transferring. For example using the WebUSB API.
2. Private key storage and generation. For example using the LocalStorage and WebCrypto API.
3. UTF-8 string encoding and decoding. For example using the `TextEncoder` and `TextDecoder` API.
## Build
### Pre-requirements
First, install all dependencies:
```shell
npm i
```
or if you already have `lerna` installed, run
```shell
lerna bootstrap
```
### Build npm packages
To build `@yume-chan/event`, `@yume-chan/adb` and `@yume-chan/adb-webusb`, run
```shell
npm run build
```
## Run
Or you can `cd` into each folder and run
```shell
npm start
npm run build
```
And navigate to `http://localhost:8080/test.html`.
All packages have TypeScript project references configured so building one package will automatically build dependency packages too.
### Watch npm packages
To watch changes and rebuild, run
```shell
npm run build:watch
```
### Run demo
Build or watch npm packages first, then run
```shell
npm run start:demo
```
to start the webpack dev server for the `demo` package.
Now navigate to `http://localhost:9000`.
#### Note
WebUSB API requires a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) (basically means HTTPS).
Chrome will treat `localhost` as one, but if you want to access test server running on another machine, you can configure you Chrome as following:
Chrome will treat `localhost` as secure, but if you want to access a dev server running on another machine, you need to add the domain to excepts:
1. Open `chrome://flags/#unsafely-treat-insecure-origin-as-secure`
2. Add the protocol and domain part of your url (e.g. `http://192.168.0.100:8080`) to the input box
2. Add the protocol and domain part of your url (e.g. `http://192.168.0.100:9000`) to the input box
3. Choose `Enable` from the dropdown menu
4. Restart your browser