taigrr / adb

Provides idiomatic adb bindings for go developers, in order to make it easier to write system tooling using golang.

adb

This library aims at providing idiomatic adb bindings for go developers, in order to make it easier to write system tooling using golang. This tool tries to take guesswork out of arbitrarily shelling out to adb by providing a structured, thoroughly-tested wrapper for the adb functions most-likely to be used in a system program.

If adb must be installed in your path PATH. At this time, while this library may work on Windows or MacOS, only Linux is supported. If you would like to add support for Windows, MacOS, *BSD..., please Submit a Pull Request.

What is adb

adb, the Android Debug Bridge, is a command-line program which allows a user to remote-control and debug Android devices.

Supported adb functions

• adb connect
• adb disconnect
• adb shell <input>s
• adb kill-server
• adb device
• adb pull
• adb install
• adb push
• adb reboot
• adb shell input tap X Y
• adb shell input swipe X1 Y1 X2 Y2 duration

Please note that as this is a purpose-driven project library, not all functionality of ADB is currently supported, but if you need functionality that's not currently supported, Feel free to Open an Issue or Submit a Pull Request

Helper functionality

• In addition to using the shell commands, this library provides helper methods for stateful connections. That is, you can connect to a device and get back a handler object and call functions against it with better error handling.

• In addition to the connection commands, this library also has helper functions for many common shell commands, including:

  • pm grant
  • am start
  • dumpsys
  • screencap
  • screenrecord
  • rm

Useful errors

All functions return a predefined error type, and it is highly recommended these errors are handled properly.

Context support

All calls into this library support go's context functionality. Therefore, blocking calls can time out according to the caller's needs, and the returned error should be checked to see if a timeout occurred (ErrExecTimeout).

Simple example

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/taigrr/adb"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    // Equivalent to `adb connect 192.168.2.5` with a 10 second timeout
    opts := adb.Options{ Address: "192.168.2.5" }
    dev, err := adb.Connect(ctx, opts)
    if err != nil {
        log.Fatalf("unable to connect to device %s: %v", opts.Address, err)
    }
    defer dev.Disconnect()
    stdout, stderr, errCode, err := dev.Shell("ls")
    if err != nil {
        log.Fatalf("unable to shell into device %s: %v", opts.Address, err)
    }
    log.Printf("Stdout: %s\nStderr: %s\n, ErrCode: %d", stdout, stderr, errCode)
}

License

This project is licensed under the 0BSD License, written by Rob Landley. As such, you may use this library without restriction or attribution, but please don't pass it off as your own. Attribution, though not required, is appreciated.

By contributing, you agree all code submitted also falls under the License.

External resources

• Official adb documentation
• Inspiration for this repo