adb.adb_protocol module

ADB protocol implementation.

Implements the ADB protocol as seen in android’s adb/adbd binaries, but only the host side.

Contents

• _AdbConnection

  • _AdbConnection._Send()

  • _AdbConnection.Close()

  • _AdbConnection.Okay()

  • _AdbConnection.ReadUntil()

  • _AdbConnection.ReadUntilClose()

  • _AdbConnection.Write()

• AdbMessage

  • AdbMessage.CalculateChecksum()

  • AdbMessage.checksum()

  • AdbMessage.Command()

  • AdbMessage.Connect()

  • AdbMessage.InteractiveShellCommand()

  • AdbMessage.Open()

  • AdbMessage.Pack()

  • AdbMessage.Read()

  • AdbMessage.Send()

  • AdbMessage.StreamingCommand()

  • AdbMessage.Unpack()

• AuthSigner

  • AuthSigner.GetPublicKey()

  • AuthSigner.Sign()

• find_backspace_runs()

• InterleavedDataError

• InvalidChecksumError

• InvalidCommandError

• InvalidResponseError

• MakeWireIDs()

adb.adb_protocol.AUTH_RSAPUBLICKEY = 3

AUTH constants for arg0.

adb.adb_protocol.AUTH_SIGNATURE = 2

AUTH constants for arg0.

adb.adb_protocol.AUTH_TOKEN = 1

AUTH constants for arg0.

class adb.adb_protocol.AdbMessage(command=None, arg0=None, arg1=None, data=b'')

Bases: object

ADB Protocol and message class.

local_id/remote_id

Turns out the documentation is host/device ambidextrous, so local_id is the id for ‘the sender’ and remote_id is for ‘the recipient’. So since we’re only on the host, we’ll re-document with host_id and device_id:

OPEN(host_id, 0, 'shell:XXX')
READY/OKAY(device_id, host_id, '')
WRITE(0, host_id, 'data')
CLOSE(device_id, host_id, '')

Parameters

• command (bytes, None) – One of: [b'SYNC', b'CNXN', b'AUTH', b'OPEN', b'OKAY', b'CLSE', b'WRTE']

• arg0 (TODO, None) – TODO

• arg1 (TODO, None) – TODO

• data (bytes) – TODO

command

The value in AdbMessage.commands that corresponds to the command parameter

Type

int

commands

A dictionary with keys [b'SYNC', b'CNXN', b'AUTH', b'OPEN', b'OKAY', b'CLSE', b'WRTE'].

Type

dict

connections

TODO

Type

int

constants

A dictionary with values [b'SYNC', b'CNXN', b'AUTH', b'OPEN', b'OKAY', b'CLSE', b'WRTE'].

Type

dict

format

The format for unpacking the ADB message.

Type

bytes

ids

[b'SYNC', b'CNXN', b'AUTH', b'OPEN', b'OKAY', b'CLSE', b'WRTE']

Type

list[bytes]

static CalculateChecksum(data)

TODO

Returns

TODO

Return type

TODO

classmethod Command(usb, service, command='', timeout_ms=None)

One complete set of USB packets for a single command.

Sends service:command in a new connection, reading the data for the response. All the data is held in memory, large responses will be slow and can fill up memory.

Parameters

• usb (adb.common.TcpHandle, adb.common.UsbHandle) – A adb.common.TcpHandle or adb.common.UsbHandle instance with BulkRead and BulkWrite methods.

• service (TODO) – The service on the device to talk to.

• command (str) – The command to send to the service.

• timeout_ms (int, None) – Timeout in milliseconds for USB packets.

Returns

The response from the service.

Return type

str

Raises

• adb.adb_protocol.InterleavedDataError – Multiple streams running over usb.

• adb.adb_protocol.InvalidCommandError – Got an unexpected response command.

classmethod Connect(usb, banner=b'notadb', rsa_keys=None, auth_timeout_ms=100)

Establish a new connection to the device.

Parameters

• usb (adb.common.TcpHandle, adb.common.UsbHandle) – A adb.common.TcpHandle or adb.common.UsbHandle instance with BulkRead and BulkWrite methods.

• banner (str) – A string to send as a host identifier.

• rsa_keys (list[adb_protocol.AuthSigner]) – List of AuthSigner subclass instances to be used for authentication. The device can either accept one of these via the Sign method, or we will send the result of GetPublicKey from the first one if the device doesn’t accept any of them.

• auth_timeout_ms (int) – Timeout to wait for when sending a new public key. This is only relevant when we send a new public key. The device shows a dialog and this timeout is how long to wait for that dialog. If used in automation, this should be low to catch such a case as a failure quickly; while in interactive settings it should be high to allow users to accept the dialog. We default to automation here, so it’s low by default.

Returns

banner – The device’s reported banner. Always starts with the state (device, recovery, or sideload), sometimes includes information after a : with various product information.

Return type

TODO

Raises

• adb.usb_exceptions.DeviceAuthError – When the device expects authentication, but we weren’t given any valid keys.

• adb.adb_protocol.InvalidResponseError – When the device does authentication in an unexpected way.

• usb_exceptions.ReadFailedError – TODO

classmethod InteractiveShellCommand(conn, cmd=None, strip_cmd=True, delim=None, strip_delim=True, clean_stdout=True)

Retrieves stdout of the current InteractiveShell and sends a shell command if provided TODO: Should we turn this into a yield based function so we can stream all output?

Parameters

• conn (AdbConnection) – Instance of AdbConnection

• cmd (str, None) – Command to run on the target.

• strip_cmd (bool) – Strip command name from stdout.

• delim (TODO) – Delimiter to look for in the output to know when to stop expecting more output (usually the shell prompt)

• strip_delim (bool) – Strip the provided delimiter from the output

• clean_stdout (bool) – Cleanup the stdout stream of any backspaces and the characters that were deleted by the backspace

Returns

stdout – The stdout from the shell command.

Return type

TODO

classmethod Open(usb, destination, timeout_ms=None)

Opens a new connection to the device via an OPEN message.

Not the same as the posix open or any other google3 Open methods.

Parameters

• usb (adb.common.TcpHandle, adb.common.UsbHandle) – A adb.common.TcpHandle or adb.common.UsbHandle instance with BulkRead and BulkWrite methods.

• destination (TODO) – The service:command string.

• timeout_ms (int, None) – Timeout in milliseconds for USB packets.

Returns

The local connection id.

Return type

_AdbConnection, None

Raises

• adb.adb_protocol.InvalidResponseError – Wrong local_id sent to us.

• adb.adb_protocol.InvalidCommandError – Didn’t get a ready response.

Pack()

Returns this message in an over-the-wire format.

Returns

TODO

Return type

bytes

classmethod Read(usb, expected_cmds, timeout_ms=None, total_timeout_ms=None)

Receive a response from the device.

Parameters

• usb (adb.common.TcpHandle, adb.common.UsbHandle) – TODO

• expected_cmds (TODO) – Read until we receive a header ID that is in expected_cmds

• timeout_ms (int, None) – Timeout in milliseconds for USB packets.

• total_timeout_ms (int, None) – The total time to wait for a command in expected_cmds

Returns

• command (TODO) – TODO

• arg0 (TODO) – TODO

• arg1 (TODO) – TODO

• bytes – TODO

Raises

• adb.adb_protocol.InvalidCommandError – Unknown command or never got one of the expected responses.

• adb.adb_protocol.InvalidChecksumError – Received checksum does not match the expected checksum.

Send(usb, timeout_ms=None)

Send this message over USB.

Parameters

• usb (adb.common.TcpHandle, adb.common.UsbHandle) – TODO

• timeout_ms (int, None) – Timeout in milliseconds for USB packets.

classmethod StreamingCommand(usb, service, command='', timeout_ms=None)

One complete set of USB packets for a single command.

Sends service:command in a new connection, reading the data for the response. All the data is held in memory, large responses will be slow and can fill up memory.

Parameters

• usb (adb.common.TcpHandle, adb.common.UsbHandle) – A adb.common.TcpHandle or adb.common.UsbHandle instance with BulkRead and BulkWrite methods.

• service (TODO) – The service on the device to talk to.

• command (str) – The command to send to the service.

• timeout_ms (int, None) – Timeout in milliseconds for USB packets.

Yields

str – The responses from the service.

Raises

• adb.adb_protocol.InterleavedDataError – Multiple streams running over usb.

• adb.adb_protocol.InvalidCommandError – Got an unexpected response command.

classmethod Unpack(message)

TODO

Parameters

message (TODO) – TODO

Returns

• cmd (TODO) – TODO

• arg0 (TODO) – TODO

• arg1 (TODO) – TODO

• data_length (TODO) – TODO

• data_checksum (TODO) – TODO

• unused_magic (TODO) – TODO

Raises

ValueError – Unable to unpack the ADB command.

property checksum

TODO

Returns

TODO

Return type

TODO

commands = {b'AUTH': 1213486401, b'CLSE': 1163086915, b'CNXN': 1314410051, b'OKAY': 1497451343, b'OPEN': 1313165391, b'SYNC': 1129208147, b'WRTE': 1163154007}

connections = 0

constants = {1129208147: b'SYNC', 1163086915: b'CLSE', 1163154007: b'WRTE', 1213486401: b'AUTH', 1313165391: b'OPEN', 1314410051: b'CNXN', 1497451343: b'OKAY'}

format = b'<6I'

ids = [b'SYNC', b'CNXN', b'AUTH', b'OPEN', b'OKAY', b'CLSE', b'WRTE']

class adb.adb_protocol.AuthSigner

Bases: object

Signer for use with authenticated ADB, introduced in 4.4.x/KitKat.

GetPublicKey()

Returns the public key in PEM format without headers or newlines.

Raises

NotImplementedError – This method is implemented in subclasses.

Sign(data)

Signs given data using a private key.

Parameters

data (bytes) – The data to be signed

Raises

NotImplementedError – This method is implemented in subclasses.

exception adb.adb_protocol.InterleavedDataError

Bases: Exception

We only support command sent serially.

exception adb.adb_protocol.InvalidChecksumError

Bases: Exception

Checksum of data didn’t match expected checksum.

exception adb.adb_protocol.InvalidCommandError(message, response_header, response_data)

Bases: Exception

Got an invalid command over USB.

exception adb.adb_protocol.InvalidResponseError

Bases: Exception

Got an invalid response to our command.

adb.adb_protocol.MAX_ADB_DATA = 4096

Maximum amount of data in an ADB packet.

adb.adb_protocol.MakeWireIDs(ids)

TODO

Parameters

ids (list[bytes]) – TODO

Returns

• id_to_wire (dict) – TODO

• wire_to_id (dict) – TODO

adb.adb_protocol.VERSION = 16777216

ADB protocol version.

class adb.adb_protocol._AdbConnection(usb, local_id, remote_id, timeout_ms)

Bases: object

ADB Connection.

Parameters

• usb (adb.common.UsbHandle) – TODO

• local_id (TODO) – TODO

• remote_id (TODO) – TODO

• timeout_ms (int) – Timeout in milliseconds for USB packets.

local_id

The ID for the sender

Type

TODO

remote_id

The ID for the recipient

Type

TODO

timeout_ms

Timeout in milliseconds for USB packets.

Type

int

usb

TODO

Type

adb.common.UsbHandle

Close()

TODO

Raises

• usb_exceptions.AdbCommandFailureException – Command failed.

• adb.adb_protocol.InvalidCommandError – Expected a CLSE response but received something else.

Okay()

TODO

ReadUntil(*expected_cmds)

Read a packet, Ack any write packets.

Parameters

*expected_cmds (TODO) – TODO

Returns

• cmd (TODO) – TODO

• data (TODO) – TODO

Raises

• adb.adb_protocol.InterleavedDataError – We don’t support multiple streams…

• adb.adb_protocol.InvalidResponseError – Incorrect remote id.

ReadUntilClose()

Yield packets until a b'CLSE' packet is received.

Yields

data (TODO) – TODO

Write(data)

Write a packet and expect an Ack.

Parameters

data (TODO) – TODO

Returns

len(data)

Return type

int

Raises

• usb_exceptions.AdbCommandFailureException – The command failed.

• adb.adb_protocol.InvalidCommandError – Expected an OKAY in response to a WRITE, got something else.

_Send(command, arg0, arg1, data=b'')

TODO

Parameters

• command (TODO) – TODO

• arg0 (TODO) – TODO

• arg1 (TODO) – TODO

• data (bytes) – TODO

adb.adb_protocol.find_backspace_runs(stdout_bytes, start_pos)

TODO

Parameters

• stdout_bytes (TODO) – TODO

• start_pos (TODO) – TODO

Returns

• int – The index/position of the first backspace.

• num_backspaces (int) – TODO