Skip to main content

Crate libadb

Crate libadb 

Source
Expand description

Low-level ADB (Android Debug Bridge) wire-protocol library.

Talks to a device directly over TCP or USB — no adbd fork/exec, no adb binary, no platform-tools dependency. Supports devices running Android 9 or later.

The core protocol layer is no_std + alloc. Any runtime feature (tokio, smol, nusb, rusb) implicitly enables std — the split Reader/Writer pair and USB backends rely on std sync primitives. For pure no_std + alloc builds, use the crate with default-features = false and bring your own embedded_io_async transport.

For a C ABI, see the companion crate libadb-ffi.

§Feature flags

FlagEnables
tokioTCP transport over tokio::net::TcpStream (default)
smolTCP transport over smol::net::TcpStream; may be combined with tokio
nusbUSB transport via nusb (pure-Rust); may be combined with rusb
rusbUSB transport via rusb (libusb); may be combined with nusb
usbConvenience alias enabling the default USB backend (nusb)
splitsplit Reader/Writer pair with no bundled runtime; pulls in std. Implied by every feature above
runtimeSet by tokio and smol, not by hand: it lets the examples require one of the two
keysBuilt-in RSA host key (keys::AdbKey): generation, PKCS#8/PKCS#1 load, PKCS#8 save, ADB public-key encoding. no_std + alloc
host-keyskeys::store on top of keys: read ~/.android/adbkey, or generate and persist one; pulls in std
tlsADB over TLS — wireless debugging on Android 11+ (STLS): tls::TlsIdentity, tls::TlsClientConfig, transport::tls::MaybeTls, Connection::connect_tls. Implies keys and split; pulls in std
pairingadb pair: pairing::pair puts a key on a device that has never seen it. Implies tls

§Quick start

ⓘ
use libadb::shell::v2;
use libadb::{Connection, ConnectionConfig, Feature, HostBanner, TokioTcp};

let tcp = tokio::net::TcpStream::connect("127.0.0.1:5555").await?;
tcp.set_nodelay(true)?; // ADB is chatty; Nagle costs a round per exchange
let transport = TokioTcp::new(tcp);

// `auth` is any `libadb::auth::Authenticator`. With the `keys`
// feature the crate ships one: `keys::AdbKey`, parsed from the
// key `adb` keeps in `~/.android/adbkey` or generated on the spot.
let mut conn = Connection::connect(
    transport,
    auth,
    HostBanner::Features(&[Feature::ShellV2]),
    ConnectionConfig::new(),
)
.await?;

let mut rx = [0u8; 64 * 1024];
let out = v2::exec(&mut conn, "getprop ro.product.model", &mut rx).await?;
println!("{}", core::str::from_utf8(&out.stdout)?);

§Memory budget

Every connection is opened with a ConnectionConfig that bounds what the library may allocate:

  • max_payload — advertised to the device in CNXN, so it caps the size of any single inbound packet (and hence the receive buffer);
  • initial_ack_bytes — delayed-ACK credit granted per channel;
  • max_rx_per_channel — fuse on data buffered for a channel nobody is reading;
  • max_channels — slots in the channel table, allocated up front;
  • max_banner_properties — how many properties the device’s CNXN banner may carry.

ConnectionConfig::new reproduces adb’s desktop behaviour (1 MiB packets, 32 MiB credit, unbounded buffering). ConnectionConfig::embedded fits a microcontroller:

ⓘ
let conn = Connection::connect(
    transport,
    auth,
    HostBanner::Features(&[Feature::ShellV2]),
    ConnectionConfig::embedded(),
)
.await?;

On a microcontroller-sized heap the default config is unusable: one 64 KiB WRTE can exhaust it, because the packet has to be buffered whole. embedded() caps packets at 8 KiB, and adbd honours the advertised limit.

§Services

  • shell::v1 — legacy shell: (interleaved stdout/stderr, no exit code)
  • shell::v2 — framed stdout/stderr/exit, optional PTY
  • exec — binary-clean exec: (raw PTY, no exit code)
  • cmd — abb_exec / abb / shell:cmd fallback chain
  • abb — Android Binder Bridge (Android 10+)
  • logcat — parsed binary logcat stream
  • sync — file transfer (STAT / LIST / SEND / RECV, v1 + v2)
  • reverse — adb reverse rules: the device listens and opens channels to the host
  • track_app — streaming debuggable/profileable process list

§Transports

TokioTcp, SmolTcp, transport::nusb::UsbTransport, transport::rusb::UsbTransport, or any user type implementing embedded_io_async::{Read, Write} plus Splittable. For concurrent read and write tasks on the same connection, see Connection::split and the resulting Reader / Writer pair.

To pick one from an address string, transport::any::connect (feature split) opens the transport a tcp:// or usb:// address names, as transport::uri parses it, on any runtime — Inline, with none at all, included.

For Android 11+ wireless debugging (feature tls), wrap the TCP transport in transport::tls::MaybeTls and connect with Connection::connect_tls.

§Status

Pre-1.0. Public API is subject to semver-breaking changes before 1.0.

Re-exports§

pub use base::auth;
pub use base::channel;
pub use base::connection;
pub use base::device_banner;
pub use base::protocol;
pub use base::session;
pub use transport::uri;
pub use base::connection::Connection;
pub use base::connection::ConnectionConfig;
pub use base::connection::HostBanner;
pub use base::connection::Incoming;
pub use base::protocol::features::Feature;
pub use base::protocol::features::DEFAULT_HOST_FEATURES;
pub use base::session::ServiceChannel;
pub use base::session::Session;
pub use error::Error;
pub use error::ProtocolError;
pub use transport::Splittable;
pub use keys::AdbKey;keys
pub use tls::TlsClientConfig;tls
pub use tls::TlsIdentity;tls
pub use split::IncomingListener;split
pub use split::Reader;split
pub use split::SplitIncoming;split
pub use split::Writer;split
pub use transport::tcp::TokioTcp;tokio
pub use transport::UsbBackend;
pub use transport::ADB_CLASS;
pub use transport::ADB_PROTOCOL;
pub use transport::ADB_SUBCLASS;

Modules§

abb
Android Binder Bridge (ABB) protocol.
base
Transport-agnostic ADB protocol core.
cmd
Run cmd commands on the device with automatic transport selection.
error
Error, what every connection and service call fails with, and the ProtocolError and AuthError it carries.
exec
exec: service — raw, binary-clean command execution.
keyskeys
ADB host key material: RSA-2048 generation, PKCS#8 import/export and the mincrypt public-key format used in the AUTH handshake.
logcat
Logcat — stream and parse Android log entries.
pairingpairing
adb pair: putting a key on a device that has never seen it.
prelude
Common vocabulary for use libadb::prelude::*;.
reverse
Reverse forwards (adb reverse): rules that make the device listen on its side and open channels toward the host.
shell
ADB shell: service — two wire protocol versions under one family.
splitsplit
Full-duplex Reader/Writer pair for a Connection whose transport is Splittable.
sync
ADB sync protocol — file operations (stat, list, push, pull).
tlstls
ADB over TLS: wireless debugging on Android 11+.
track_app
Track debuggable/profileable app processes on the device.
transport
Transport abstractions for ADB connections.