mobi-nex / adborc Goto Github PK

View Code? Open in Web Editor NEW

88.0 6.0 3.0 334 KB

Create a network of android devices for remote debugging

Home Page: https://mobinex.io

License: Apache License 2.0

Rust 100.00%

adb android distributed-networking remote-access rust

adborc's Introduction

AdbOrc

AdbOrc makes it easy to create psuedo-distributed network of android devices. It is a simple wrapper around adb that allows you to easily share devices with other users on your network. Securely share your devices within your network for testing, debugging or development.

Overview

There are three modes of operation for a network node in AdbOrc:

Supplier - A machine on the network that has one or more android devices attached to it. Supplier, as the name implies, supplies devices to the network. There can be any number of Suppliers on the network.
Consumer - A machine on the network that wants to use one or more android devices. Consumer, as the name implies, consumes devices from the network. There can be any number of Consumers on the network.
MarketMaker - A machine on the network that acts as a middleman between Suppliers and Consumers. MarketMaker is responsible for matching Suppliers and Consumers and handling all the metadata of the network. There is exactly one MarketMaker on the network. For Suppliers and Consumers, MarketMaker serves as a proxy for the network.

A system on the network can be operating in any combination of the above modes. For example, a system can be a Supplier and a Consumer at the same time. It can also be a MarketMaker and a Consumer at the same time.

Supplying devices to the network is as simple as joining the network as a Supplier and choosing the devices you wish to supply.

To use devices from the network, you need to join the network as a Consumer and list the available devices within the network. You can then choose the devices you wish to use and ask MarketMaker to reserve them for you. Once you are done using the devices, you can release them back to the network.

All reserved devices are available for use only to the Consumer that reserved them. The devices are available directly via adb. Device screen mirroring for reserved devices is also supported directly by AdbOrc via scrcpy.

All communications between Suppliers, Consumers and MarketMaker are encrypted using the Noise Protocol Framework. The encryption keys are generated using the X25519 curve and the ChaChaPoly cipher suite with Blake2s as the hash function. The XX_25519_ChaChaPoly_BLAKE2s handshake pattern is used.

By default, device communications within the network between Suppliers and Consumers are NOT encrypted. However, Suppliers can choose to encrypt device communications with Consumers using the same Noise protocol cipher suites (uses KK pattern). This is done by simply enabling secure_mode while joining the network as a Supplier.

Usage

Start the network by starting MarketMaker on a machine:

$ adborc marketmaker start

Join the network as a Supplier from another machine:

$ adborc supplier start <MarketMaker_IP>

# Or, if you wish to enable secure mode
$ adborc supplier start <MarketMaker_IP> --secure

# Supply specific devices to the network
$ adborc supplier supply --devices "<android_serial1>,<android_serial2>,..."

# Or, supply all connected devices
$ adborc supplier supply

Join the network as a Consumer from another machine:

$ adborc consumer start <MarketMaker_IP>

# List available devices
$ adborc consumer list-available

# Reserve devices
$ adborc consumer reserve <device_id>

# Use the devices via adb
$ adb shell

# Or, use the devices via scrcpy
$ adborc consumer scrcpy <device_id>

For a more detailed usage, see the command reference

Installation

From source

# Assuming you have the rust toolchain installed
$ cargo install --git https://github.com/mobi-nex/adborc.git 

# Or, if you want to build from local source
$ git clone https://github.com/mobi-nex/adborc.git
$ cd adborc

$ cargo install --path .

From crates.io

# Assuming you have the rust toolchain installed
$ cargo install adborc

Note: AdbOrc in Consumer/Supplier mode requires adb to be installed on the system. It also requires scrcpy to be installed on the system if you wish to use device screen mirroring. See dependencies section for more details.

From releases (Windows only)

You can download the latest release from here. The release contains all dependencies bundled, including adb and scrcpy. Just extract the archive and run adborc.exe on the command line from the extracted directory.

Dependencies

AdbOrc depends on the following:

adb - Android Debug Bridge
scrcpy - Optional, for screen mirroring

For MarketMaker mode, none of the above are required.

For Consumer mode to work, minimum version of adb required is 1.0.41.

Optionally, scrcpy can be used for screen mirroring. Minimum version of scrcpy required is 1.13.

For Supplier mode to work, minimum version of adb required is 1.0.41, with minimum revision number of 33.0.1.

Note: scrcpy is not required for Supplier mode.

You can override the default adb and scrcpy used by:

# Full path to the adb executable
$ adborc set-adb-path <path_to_adb>

# Full path to the scrcpy executable
$ adborc set-scrcpy-path <path_to_scrcpy>

See command reference for more details.

Contributing

Contributions are welcome! Please feel free to open issues and pull requests.

Just make sure to run cargo fmt and cargo clippy before submitting a PR.

License

AdbOrc is licensed under the Apache License 2.0. See LICENSE for more details.

adborc's People

Contributors

Stargazers

Watchers

Forkers

coolashel fjborquez victorlpgazolli

adborc's Issues

Add/update logging

Two kinds of logging update are needed:

Remove/Change lot of log levels. For example: many of the logs currently have the error level. When they can be easily relegated to warning or even debug prints. This creates a lot of clutter and useless information on the console. Also, some of the debug prints need to be upgraded to info.
There are a lot of places where logging needs improvement or addition at the moment.

This is an excellent first issue as the changes can be easily implemented and they provide a very good opportunity to understand the design and implementation of the project.

Take the `cli` module out of library crate

Currently, cli is a public module of the adborc library. This is completely unnecessary as anyone using AdbOrc as a library will either want to develop their on cli or slap a GUI on top of it, or have some other internal or external api access it. We should take the cli module out of the library and have it only as a part of the binary.

Add version checking between client and server

Currently, version checking is implemented between two nodes, i.e. if a supplier or consumer of v0.1.0 is trying to connect to a marketmaker of v0.2.0, it will result in a connection failure, and vice-versa. But if the local AdbOrc client is different from the localhost AdbOrc server, no descriptive error is returned. Commands may fail if there is an API change between client and server. eg:

# Start AdbOrc server with version say: 0.2.0
$ ./target/release/adborc init

# Use a different AdbOrc client to communicate with the server, version say: 0.1.0
# This command will not result in an error, as no API change between 0.1.0 and 0.2.0
$ adborc consumer start localhost

# This command will result in a cryptic and unfriendly error because of API change
$ adborc consumer scrcpy <device_id>

Introduce an API change such that AdbOrc client advertises its version to the server and
server checks this version before trying to execute the client command.

Add a sub-command for stopping scrcpy mirroring

Currently, there is no command to stop scrcpy mirroring once it is started. This is not a problem usually because the mirroring window has a close button that can be clicked to stop scrcpy. But in some cases, like with the scrcpy option --window-borderless there are no border decorations for the window and hence no close button. The only way to stop mirroring in such cases is to release the device or stop the consumer altogether. Both are not ideal. Also, regardless, there should be a cli command to stop mirroring as that might be needed for automation use cases.

Refactor large files?

As highlighted by @fjborquez in #6 there are a lot of large files in the project currently that can be more easily manageable/readable/navigable if they were smaller. Also, unit testing would be easier. Maybe a refactor of some of these files into smaller files should be considered. This issue is created to track discussions related to above referenced refactor.

Enable running the system listener in windows as a background service

For both linux and macos, the system listener is run as a daemon currently. This is not available for windows. This means that the adborc init window needs to be kept open for the duration the server is running. This is not ideal, and running as a background service should be considered for windows.

`stop-scrcpy` doesn't work if Consumer and Supplier are same

#12 Added ability to stop device screen mirroring. It stops the mirroring by closing the tunnels established for scrcpy. This doesn't work if both the Consumer and Supplier are on the same machine as no scrcpy tunnels are established if they are on the same machine. Need another way to stop the screen mirroring.

Include Mac and Linux binaries in releases?

Explore addition of Mac and Linux executables along with adb and scrcpy dependencies in the next release.

It is easily possible to ship the AdbOrc executable for mac and linux as it is a single executable with statically linked libraries. But the external dependencies adb and scrcpy have certain requirements (listed below) that need to be considered before bundling them in a release. Currently for windows releases, these dependencies are directly downloaded from the scrcpy releases page and bundled as-is.

ADB: Platform-tools can be downloaded from the official android site, but the license requirement is that the user should accept the terms.
scrcpy: It is a bit complicated to bundle scrcpy as it depends on dynamically linked libs (ffmpeg libs, sdl2, libusb). Some of the dependencies(ffmpeg) are licensed under GPL v3 which needs to be considered before bundling them.

scrcpy failed to start from adborc

Tried to execute command adborc consumer scrcpy deviceId. However got an error:

Screen mirroring failed: Could not start scrcpy: Scrcpy server failed to start: 2023-03-03 17:12:20.255 scrcpy[28358:144649] ERROR: Command not found: [adb], [start-server]

Tried several fixes:

added adb to $PATH variable. Now it accessible as a command from console
tried to run just scrcpy command and Wow it works and sees my device connected remotely, however won't start the screen mirroring too. That means that my scrcpy installed can execute adb commands.

Can someone explain, what could it be please?

ENV
adborc version: v0.1.0
scrcpy version 1.25

Android Debug Bridge version 1.0.41
Version 34.0.0-9570255

consumer/marketmaker - macos m1
supplier - windows 10
device Android 7.1.1

Tests need improvement and addition

Current state of tests is pretty bad. Only limited number of unit tests exist and even they aren't very good. Not to mention, no integration tests exist at the moment. This leads to a lot of wasted time before being confident about merging changes. Tests -- both unit test and integration test, need drastic improvement.