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
| Flag | Enables |
|---|---|
tokio | TCP transport over tokio::net::TcpStream (default) |
smol | TCP transport over smol::net::TcpStream; may be combined with tokio |
nusb | USB transport via nusb (pure-Rust); may be combined with rusb |
rusb | USB transport via rusb (libusb); may be combined with nusb |
usb | Convenience alias enabling the default USB backend (nusb) |
split | split Reader/Writer pair with no bundled runtime; pulls in std. Implied by every feature above |
runtime | Set by tokio and smol, not by hand: it lets the examples require one of the two |
keys | Built-in RSA host key (keys::AdbKey): generation, PKCS#8/PKCS#1 load, PKCS#8 save, ADB public-key encoding. no_std + alloc |
host-keys | keys::store on top of keys: read ~/.android/adbkey, or generate and persist one; pulls in std |
tls | ADB 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 |
pairing | adb 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— legacyshell:(interleaved stdout/stderr, no exit code)shell::v2— framed stdout/stderr/exit, optional PTYexec— binary-cleanexec:(raw PTY, no exit code)cmd—abb_exec/abb/shell:cmdfallback chainabb— Android Binder Bridge (Android 10+)logcat— parsed binary logcat streamsync— file transfer (STAT/LIST/SEND/RECV, v1 + v2)reverse—adb reverserules: the device listens and opens channels to the hosttrack_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::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;keyspub use tls::TlsClientConfig;tlspub use tls::TlsIdentity;tlspub use split::IncomingListener;splitpub use split::Reader;splitpub use split::SplitIncoming;splitpub use split::Writer;splitpub use transport::tcp::TokioTcp;tokiopub 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
cmdcommands on the device with automatic transport selection. - error
Error, what every connection and service call fails with, and theProtocolErrorandAuthErrorit carries.- exec
exec:service — raw, binary-clean command execution.- keys
keys - 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.
- pairing
pairing 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. - split
split - Full-duplex Reader/Writer pair for a Connection whose transport is
Splittable. - sync
- ADB sync protocol — file operations (stat, list, push, pull).
- tls
tls - ADB over TLS: wireless debugging on Android 11+.
- track_
app - Track debuggable/profileable app processes on the device.
- transport
- Transport abstractions for ADB connections.