wire-protocol¶

Android Debug Bridge (ADB) Wire Protocol.

Modules¶

adbwp.consts¶

Contains constant values used by the protocol.

adbwp.consts.VERSION = 16777216¶: Protocol version.

adbwp.consts.MAXDATA = 262144¶: Maximum message body size.

adbwp.consts.CONNECT_AUTH_MAXDATA = 4096¶: Older ADB version max data size limit; required max for CONNECT and AUTH messages.

adbwp.consts.MESSAGE_SIZE = 24¶: Size of a serialized ADB message in bytes.

adbwp.consts.COMMAND_MASK = 4294967295¶: Bitmask applied to the “magic” value of ADB messages.

adbwp.enums¶

Contains enumeration types used by the protocol.

class adbwp.enums.Command(value)¶: Enumeration for command types used by the ADB protocol.

class adbwp.enums.CommandResponse(value)¶: Enumeration for response message types from ADB connection requests.

class adbwp.enums.AuthType(value)¶: Enumeration for authentication types used by the ADB protocol.

class adbwp.enums.SystemType(value)¶: Enumeration for “systemtype” values used by the ADB protocol for the “system-identity-string” value in a CONNECT message.

adbwp.exceptions¶

Contains exception types used across the package.

exception adbwp.exceptions.WireProtocolError¶

Base exception for all ADB wire protocol related errors.

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception adbwp.exceptions.PackError¶

Exception raised when unable to pack/serialize a model into bytes.

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception adbwp.exceptions.UnpackError¶

Exception raised when unable to unpack/deserialize bytes into a model.

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception adbwp.exceptions.ChecksumError¶

Exception raised when the computed checksum of a data payload does not match the value in the header.

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

adbwp.header¶

Object representation of a message header.

class adbwp.header.Header(command, arg0, arg1, data_length, data_checksum, magic)¶

Represents the header of an ADB protocol message.

A header is 24 bytes consisting of 6 32-bit words in little-endian format.

Create new instance of Header(command, arg0, arg1, data_length, data_checksum, magic)

property connect¶

Indicates whether or not this header represents a connect message.

Returns: Bool indicating if it is a connect message or not.
Return type: bool

property auth¶

Indicates whether or not this header represents an auth message.

Returns: Bool indicating if it is an auth message or not.
Type: bool

property open¶

Indicates whether or not this header represents a open message.

Returns: Bool indicating if it is a open message or not.
Return type: bool

property ready¶

Indicates whether or not this header represents a ready message.

Returns: Bool indicating if it is a ready message or not.
Return type: bool

property write¶

Indicates whether or not this header represents a write message.

Returns: Bool indicating if it is a write message or not.
Return type: bool

property close¶

Indicates whether or not this header represents a close message.

Returns: Bool indicating if it is a close message or not.
Return type: bool

property sync¶

Indicates whether or not this header represents a sync message.

Returns: Bool indicating if it is a sync message or not.
Return type: bool

property okay¶

Indicates whether or not this header represents an okay response.

Returns: Bool indicating if it is an okay response or not.
Return type: bool

property fail¶

Indicates whether or not this header represents a fail response.

Returns: Bool indicating if it is a fail response or not.
Return type: bool

property arg0¶: Alias for field number 1

property arg1¶: Alias for field number 2

property command¶: Alias for field number 0

count(value, /)¶: Return number of occurrences of value.

property data_checksum¶: Alias for field number 4

property data_length¶: Alias for field number 3

index(value, start=0, stop=9223372036854775807, /)¶

Return first index of value.

Raises ValueError if the value is not present.

property magic¶: Alias for field number 5

adbwp.header.new(command: Union[int, adbwp.enums.Command], arg0: int = 0, arg1: int = 0, data_length: int = 0, data_checksum: int = 0, magic: int = 0) → adbwp.header.Header ¶

Create a new Header instance with optional default values.

Parameters

command (Command or int) – Command identifier
arg0 (int) – (Optional) First argument of the command
arg1 (int) – (Optional) Second argument of the command
data_length (int) – (Optional) Length of the payload
data_checksum (int) – (Optional) Computed checksum of the payload
magic (int) – (Optional) “Magic” XOR of the command

Returns

Header instance created from values

Return type

Header

adbwp.header.to_bytes(header: adbwp.header.Header) → bytes ¶

Create a bytes from the given Header.

Parameters: header (Header) – Message header
Returns: Header represented as bytes
Return type: bytes
Raises: PackError – when unable to pack instance into 6 bytes

adbwp.header.from_bytes(header: bytes) → adbwp.header.Header ¶

Create a Header from the given bytes.

Parameters: header (bytes) – Message header in bytes
Returns: Bytes converted to a header
Return type: Header
Raises: UnpackError – When unable to unpack instance from bytes

adbwp.hints¶

Contains type hint definitions used across modules in this package.

adbwp.hints.Bytes¶: alias of bytes

adbwp.hints.Bool¶: alias of bool

adbwp.hints.Int¶: alias of int

adbwp.hints.Str¶: alias of str

adbwp.hints.Command¶

Type hint that defines multiple types that represent a command.

alias of Union[int, adbwp.enums.Command]

adbwp.hints.SystemType¶

Type hint that defines multiple types that can represent a system type used in a connect message.

alias of Union[str, adbwp.enums.SystemType]

adbwp.hints.Buffer¶

Type hint that defines multiple types that can represent a collection of bytes that can be used to create model types.

alias of Union[bytes, bytearray, str, memoryview]

adbwp.message¶

Object representation of a message.

class adbwp.message.Message(header, data)¶

Represents an entire ADB protocol message.

A message consists of a 24-byte header followed by an optional data payload.

Create new instance of Message(header, data)

count(value, /)¶: Return number of occurrences of value.

property data¶: Alias for field number 1

property header¶: Alias for field number 0

index(value, start=0, stop=9223372036854775807, /)¶

Return first index of value.

Raises ValueError if the value is not present.

adbwp.message.new(command: Union[int, adbwp.enums.Command], arg0: int = 0, arg1: int = 0, data: Union[bytes, bytearray, str, memoryview] = b'') → adbwp.message.Message ¶

Create a new Message instance with optional default values.

Parameters

command (Command or int) – Command identifier
arg0 (int) – (Optional) First argument of the command
arg1 (int) – (Optional) Second argument of the command
data (bytes, bytearray, str, or memoryview) – (Optional) Message payload

Returns

Message instance from given values

Return type

Message

Raises

ValueError – When data payload is greater than MAXDATA

adbwp.message.from_header(header: adbwp.header.Header, data: Union[bytes, bytearray, str, memoryview] = b'') → adbwp.message.Message ¶

Create a new Message instance from an existing Header.

Parameters

header (Header) – Message header
data (bytes, bytearray, str, or memoryview) – (Optional) Message payload

Returns

Message instance from given values

Return type

Message

Raises

ValueError – When data payload is greater than MAXDATA
ChecksumError – When data payload checksum doesn’t match header checksum

adbwp.message.connect(serial: str, banner: str, system_type: Union[str, adbwp.enums.SystemType] = <SystemType.HOST: 'host'>) → adbwp.message.Message ¶

Create a Message instance that represents a connect message.

Parameters

serial (str) – Unique identifier
banner (str) – Human readable version/identifier string
system_type (SystemType or str) – System type creating the message

Returns

Message used to connect to a remote system

Return type

Message

Raises

ValueError – When data payload is greater than CONNECT_AUTH_MAXDATA

adbwp.message.auth_signature(signature: bytes) → adbwp.message.Message ¶

Create a Message instance that represents a signature authentication message.

Parameters: signature (bytes) – Signed data payload
Returns: Message used to verify key pair
Return type: Message
Raises: ValueError – When data payload is greater than CONNECT_AUTH_MAXDATA

adbwp.message.auth_rsa_public_key(public_key: bytes) → adbwp.message.Message ¶

Create a Message instance that represents a RSA public key authentication message.

Parameters: public_key (bytes) – Public key for remote system to conditionally accept
Returns: Message used to share public key
Return type: Message
Raises: ValueError – When data payload is greater than CONNECT_AUTH_MAXDATA

adbwp.message.open(local_id: int, destination: str) → adbwp.message.Message ¶

Create a Message instance that represents a open message.

Parameters

local_id (int) – Stream id on remote system to connect with
destination (str) – Stream destination

Returns

Message used to open a stream by id on a remote system

Return type

Message

Raises

ValueError – When local id is zero
ValueError – When data payload is greater than MAXDATA

adbwp.message.ready(local_id: int, remote_id: int) → adbwp.message.Message ¶

Create a Message instance that represents a ready message.

Parameters

local_id (int) – Identifier for the stream on the local end
remote_id (int) – Identifier for the stream on the remote system

Returns

Message used to inform remote system it’s ready for write messages

Return type

Message

Raises

ValueError – When local id is zero
ValueError – When remote id is zero
ValueError – When data payload is greater than MAXDATA

adbwp.message.write(local_id: int, remote_id: int, data: Union[bytes, bytearray, str, memoryview]) → adbwp.message.Message ¶

Create a Message instance that represents a write message.

Parameters

local_id (int) – Identifier for the stream on the local end
remote_id (int) – Identifier for the stream on the remote system
data (bytes, bytearray, str, or memoryview) – Data payload sent to the stream

Returns

Message used to write data to remote stream

Return type

Message

Raises

ValueError – When data payload is empty
ValueError – When data payload is greater than MAXDATA

adbwp.message.close(local_id: int, remote_id: int) → adbwp.message.Message ¶

Create a Message instance that represents a close message.

Parameters

local_id (int) – Identifier for the stream on the local end
remote_id (int) – Identifier for the stream on the remote system

Returns

Message used to inform the remote system of stream closing

Return type

Message

Raises

ValueError – When id is zero
ValueError – When remote id is zero
ValueError – When data payload is greater than MAXDATA

adbwp.payload¶

Contains functionality for message data payloads.

adbwp.payload.checksum(data: Union[bytes, bytearray, str, memoryview]) → int ¶

Compute the checksum value of a header that uses the given data payload.

Parameters: data (bytes, bytearray, str, or memoryview) – Data payload
Returns: Data payload checksum
Return type: int

adbwp.payload.null_terminate(data: Union[bytes, bytearray, str, memoryview]) → bytes ¶

Null terminate the given data payload.

Parameters: data (bytes, bytearray, str, or memoryview) – Data payload
Returns: Data payload ending with a zero byte.
Return type: bytes

adbwp.payload.as_bytes(data: Union[bytes, bytearray, str, memoryview], encoding: str = 'utf-8', errors: str = 'strict') → bytes ¶

Ensure the given data payload is a bytes instance.

Parameters

data (bytes, bytearray, str, or memoryview) – Data payload
encoding (str) – (Optional) Encoding if data payload is a str
errors (str) – (Optional) How to handle encoding errors

Returns

Data payload as bytes

Return type

bytes

Raises

ValueError – When data is not one of the supported types

adbwp.payload.system_identity_string(system_type: Union[str, adbwp.enums.SystemType], serial: str, banner: str)¶

Compute the system identity string data payload.

Parameters

system_type (SystemType or str) – System type creating the message
serial (str) – Unique identifier
banner (str) – Human readable version/identifier string

Returns

System identity string payload for connect messages

Return type

str