aio_adb_shell.adb_device module

Implement the AdbDevice class, which can connect to a device and run ADB shell commands.

Contents

• _AdbTransactionInfo

• _FileSyncTransactionInfo

  • _FileSyncTransactionInfo.can_add_to_send_buffer()

• AdbDevice

  • AdbDevice._close()

  • AdbDevice._filesync_flush()

  • AdbDevice._filesync_read()

  • AdbDevice._filesync_read_buffered()

  • AdbDevice._filesync_read_until()

  • AdbDevice._filesync_send()

  • AdbDevice._handle_progress()

  • AdbDevice._okay()

  • AdbDevice._open()

  • AdbDevice._pull()

  • AdbDevice._push()

  • AdbDevice._read()

  • AdbDevice._read_until()

  • AdbDevice._read_until_close()

  • AdbDevice._send()

  • AdbDevice._service()

  • AdbDevice._streaming_command()

  • AdbDevice._streaming_service()

  • AdbDevice._write()

  • AdbDevice.available

  • AdbDevice.close()

  • AdbDevice.connect()

  • AdbDevice.list()

  • AdbDevice.pull()

  • AdbDevice.push()

  • AdbDevice.root()

  • AdbDevice.shell()

  • AdbDevice.stat()

  • AdbDevice.streaming_shell()

• AdbDeviceTcp

class aio_adb_shell.adb_device.AdbDevice(handle, banner=None)

Bases: object

A class with methods for connecting to a device and executing ADB commands.

Parameters

• handle (BaseHandle) – A user-provided handle for communicating with the device; must be an instance of a subclass of BaseHandle

• banner (str, bytes, None) – The hostname of the machine where the Python interpreter is currently running; if it is not provided, it will be determined via socket.gethostname()

Raises

adb_shell.exceptions.InvalidHandleError – The passed handle is not an instance of a subclass of BaseHandle

_available

Whether an ADB connection to the device has been established

Type

bool

_banner

The hostname of the machine where the Python interpreter is currently running

Type

bytearray, bytes

_handle

The handle that is used to connect to the device; must be a subclass of BaseHandle

Type

BaseHandle

async _close(adb_info)

Send a b'CLSE' message.

Warning

This is not to be confused with the AdbDevice.close() method!

Parameters

adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

async _filesync_flush(adb_info, filesync_info)

Write the data in the buffer up to filesync_info.send_idx, then set filesync_info.send_idx to 0.

Parameters

• adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

• filesync_info (_FileSyncTransactionInfo) – Data and storage for this FileSync transaction

async _filesync_read(expected_ids, adb_info, filesync_info, read_data=True)

Read ADB messages and return FileSync packets.

Parameters

• expected_ids (tuple[bytes]) – If the received header ID is not in expected_ids, an exception will be raised

• adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

• filesync_info (_FileSyncTransactionInfo) – Data and storage for this FileSync transaction

• read_data (bool) – Whether to read the received data

Returns

• command_id (bytes) – The received header ID

• tuple – The contents of the header

• data (bytearray, None) – The received data, or None if read_data is False

Raises

• adb_shell.exceptions.AdbCommandFailureException – Command failed

• adb_shell.exceptions.InvalidResponseError – Received response was not in expected_ids

async _filesync_read_buffered(size, adb_info, filesync_info)

Read size bytes of data from self.recv_buffer.

Parameters

• size (int) – The amount of data to read

• adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

• filesync_info (_FileSyncTransactionInfo) – Data and storage for this FileSync transaction

Returns

result – The read data

Return type

bytearray

_filesync_read_until(expected_ids, finish_ids, adb_info, filesync_info)

Useful wrapper around AdbDevice._filesync_read().

Parameters

• expected_ids (tuple[bytes]) – If the received header ID is not in expected_ids, an exception will be raised

• finish_ids (tuple[bytes]) – We will read until we find a header ID that is in finish_ids

• adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

• filesync_info (_FileSyncTransactionInfo) – Data and storage for this FileSync transaction

Yields

• cmd_id (bytes) – The received header ID

• header (tuple) – TODO

• data (bytearray) – The received data

async _filesync_send(command_id, adb_info, filesync_info, data=b'', size=0)

Send/buffer FileSync packets.

Packets are buffered and only flushed when this connection is read from. All messages have a response from the device, so this will always get flushed.

Parameters

• command_id (bytes) – Command to send.

• adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

• filesync_info (_FileSyncTransactionInfo) – Data and storage for this FileSync transaction

• data (str, bytes) – Optional data to send, must set data or size.

• size (int) – Optionally override size from len(data).

static _handle_progress(progress_callback)

Calls the callback with the current progress and total bytes written/received.

Parameters

progress_callback (function) – Callback method that accepts filename, bytes_written, and total_bytes; total_bytes will be -1 for file-like objects.

async _okay(adb_info)

Send an b'OKAY' mesage.

Parameters

adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

async _open(destination, adb_info)

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

1. _send() an b'OPEN' command to the device that specifies the local_id

2. _read() a response from the device that includes a command, another local ID (their_local_id), and remote_id

   • If local_id and their_local_id do not match, raise an exception.

   • If the received command is b'CLSE', _read() another response from the device

   • If the received command is not b'OKAY', raise an exception

   • Set the adb_info.local_id and adb_info.remote_id attributes

Parameters

• destination (bytes) – b'SERVICE:COMMAND'

• adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

Raises

adb_shell.exceptions.InvalidResponseError – Wrong local_id sent to us.

async _pull(filename, dest, progress_callback, adb_info, filesync_info)

Pull a file from the device into the file-like dest_file.

Parameters

• filename (str) – The file to be pulled

• dest (_io.BytesIO) – File-like object for writing to

• progress_callback (function, None) – Callback method that accepts filename, bytes_written, and total_bytes

• adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

• filesync_info (_FileSyncTransactionInfo) – Data and storage for this FileSync transaction

async _push(datafile, filename, st_mode, mtime, progress_callback, adb_info, filesync_info)

Push a file-like object to the device.

Parameters

• datafile (_io.BytesIO) – File-like object for reading from

• filename (str) – Filename to push to

• st_mode (int) – Stat mode for filename

• mtime (int) – Modification time

• progress_callback (function, None) – Callback method that accepts filename, bytes_written, and total_bytes

• adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

Raises

PushFailedError – Raised on push failure.

async _read(expected_cmds, adb_info)

Receive a response from the device.

1. Read a message from the device and unpack the cmd, arg0, arg1, data_length, and data_checksum fields

2. If cmd is not a recognized command in adb_shell.constants.WIRE_TO_ID, raise an exception

3. If the time has exceeded total_timeout_s, raise an exception

4. Read data_length bytes from the device

5. If the checksum of the read data does not match data_checksum, raise an exception

6. Return command, arg0, arg1, and bytes(data)

Parameters

• expected_cmds (list[bytes]) – We will read packets until we encounter one whose “command” field is in expected_cmds

• adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

Returns

• command (bytes) – The received command, which is in adb_shell.constants.WIRE_TO_ID and must be in expected_cmds

• arg0 (int) – TODO

• arg1 (int) – TODO

• bytes – The data that was read

Raises

• adb_shell.exceptions.InvalidCommandError – Unknown command or never got one of the expected responses.

• adb_shell.exceptions.InvalidChecksumError – Received checksum does not match the expected checksum.

async _read_until(expected_cmds, adb_info)

Read a packet, acknowledging any write packets.

1. Read data via AdbDevice._read()

2. If a b'WRTE' packet is received, send an b'OKAY' packet via AdbDevice._okay()

3. Return the cmd and data that were read by AdbDevice._read()

Parameters

• expected_cmds (list[bytes]) – AdbDevice._read() with look for a packet whose command is in expected_cmds

• adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

Returns

• cmd (bytes) – The command that was received by AdbDevice._read(), which is in adb_shell.constants.WIRE_TO_ID and must be in expected_cmds

• data (bytes) – The data that was received by AdbDevice._read()

Raises

• adb_shell.exceptions.InterleavedDataError – We don’t support multiple streams…

• adb_shell.exceptions.InvalidResponseError – Incorrect remote id.

• adb_shell.exceptions.InvalidCommandError – Never got one of the expected responses.

_read_until_close(adb_info)

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

1. Read the cmd and data fields from a b'CLSE' or b'WRTE' packet via AdbDevice._read_until()

2. If cmd is b'CLSE', then send a b'CLSE' message and stop

3. If cmd is not b'WRTE', raise an exception

   • If cmd is b'FAIL', raise AdbCommandFailureException

   • Otherwise, raise InvalidCommandError

4. Yield data and repeat

Parameters

adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

Yields

data (bytes) – The data that was read by AdbDevice._read_until()

async _send(msg, adb_info)

Send a message to the device.

1. Send the message header (adb_shell.adb_message.AdbMessage.pack)

2. Send the message data

Parameters

• msg (AdbMessage) – The data that will be sent

• adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

async _service(service, command, timeout_s=None, total_timeout_s=10.0, decode=True)

Send an ADB command to the device.

Parameters

• service (bytes) – The ADB service to talk to (e.g., b'shell')

• command (bytes) – The command that will be sent

• timeout_s (float, None) – Timeout in seconds for sending and receiving packets, or None; see BaseHandle.bulk_read() and BaseHandle.bulk_write()

• total_timeout_s (float) – The total time in seconds to wait for a b'CLSE' or b'OKAY' command in AdbDevice._read()

• decode (bool) – Whether to decode the output to utf8 before returning

Returns

The output of the ADB command as a string if decode is True, otherwise as bytes.

Return type

bytes, str

_streaming_command(service, command, adb_info)

One complete set of USB packets for a single command.

1. _open() a new connection to the device, where the destination parameter is service:command

2. Read the response data via AdbDevice._read_until_close()

Note

All the data is held in memory, and thus large responses will be slow and can fill up memory.

Parameters

• service (bytes) – The ADB service (e.g., b'shell', as used by AdbDevice.shell())

• command (bytes) – The service command

• adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

Yields

bytes – The responses from the service.

_streaming_service(service, command, timeout_s=None, total_timeout_s=10.0, decode=True)

Send an ADB command to the device, yielding each line of output.

Parameters

• service (bytes) – The ADB service to talk to (e.g., b'shell')

• command (bytes) – The command that will be sent

• timeout_s (float, None) – Timeout in seconds for sending and receiving packets, or None; see BaseHandle.bulk_read() and BaseHandle.bulk_write()

• total_timeout_s (float) – The total time in seconds to wait for a b'CLSE' or b'OKAY' command in AdbDevice._read()

• decode (bool) – Whether to decode the output to utf8 before returning

Yields

bytes, str – The line-by-line output of the ADB command as a string if decode is True, otherwise as bytes.

async _write(data, adb_info)

Write a packet and expect an Ack.

Parameters

• data (bytes) – The data that will be sent

• adb_info (_AdbTransactionInfo) – Info and settings for this ADB transaction

property available

Whether or not an ADB connection to the device has been established.

Returns

self._available

Return type

bool

async close()

Close the connection via the provided handle’s close() method.

async connect(rsa_keys=None, timeout_s=None, auth_timeout_s=10.0, total_timeout_s=10.0, auth_callback=None)

Establish an ADB connection to the device.

1. Use the handle to establish a connection

2. Send a b'CNXN' message

3. Unpack the cmd, arg0, arg1, and banner fields from the response

4. If cmd is not b'AUTH', then authentication is not necesary and so we are done

5. If no rsa_keys are provided, raise an exception

6. Loop through our keys, signing the last banner that we received

   1. If the last arg0 was not adb_shell.constants.AUTH_TOKEN, raise an exception

   2. Sign the last banner and send it in an b'AUTH' message

   3. Unpack the cmd, arg0, and banner fields from the response via adb_shell.adb_message.unpack()

   4. If cmd is b'CNXN', return banner

7. None of the keys worked, so send rsa_keys[0]’s public key; if the response does not time out, we must have connected successfully

Parameters

• rsa_keys (list, None) – A list of signers of type CryptographySigner, PycryptodomeAuthSigner, or PythonRSASigner

• timeout_s (float, None) – Timeout in seconds for sending and receiving packets, or None; see BaseHandle.bulk_read() and BaseHandle.bulk_write()

• auth_timeout_s (float, None) – The time in seconds to wait for a b'CNXN' authentication response

• total_timeout_s (float) – The total time in seconds to wait for expected commands in AdbDevice._read()

• auth_callback (function, None) – Function callback invoked when the connection needs to be accepted on the device

Returns

Whether the connection was established (AdbDevice.available)

Return type

bool

Raises

• adb_shell.exceptions.DeviceAuthError – Device authentication required, no keys available

• adb_shell.exceptions.InvalidResponseError – Invalid auth response from the device

async list(device_path, timeout_s=None, total_timeout_s=10.0)

Return a directory listing of the given path.

Parameters

• device_path (str) – Directory to list.

• timeout_s (float, None) – Expected timeout for any part of the pull.

• total_timeout_s (float) – The total time in seconds to wait for a b'CLSE' or b'OKAY' command in AdbDevice._read()

Returns

files – Filename, mode, size, and mtime info for the files in the directory

Return type

list[DeviceFile]

async pull(device_filename, dest_file=None, progress_callback=None, timeout_s=None, total_timeout_s=10.0)

Pull a file from the device.

Parameters

• device_filename (str) – Filename on the device to pull.

• dest_file (str, file, io.IOBase, None) – If set, a filename or writable file-like object.

• progress_callback (function, None) – Callback method that accepts filename, bytes_written and total_bytes, total_bytes will be -1 for file-like objects

• timeout_s (float, None) – Expected timeout for any part of the pull.

• total_timeout_s (float) – The total time in seconds to wait for a b'CLSE' or b'OKAY' command in AdbDevice._read()

Returns

The file data if dest_file is not set. Otherwise, True if the destination file exists

Return type

bytes, bool

Raises

ValueError – If dest_file is of unknown type.

async push(source_file, device_filename, st_mode=33272, mtime=0, progress_callback=None, timeout_s=None, total_timeout_s=10.0)

Push a file or directory to the device.

Parameters

• source_file (str) – Either a filename, a directory or file-like object to push to the device.

• device_filename (str) – Destination on the device to write to.

• st_mode (int) – Stat mode for filename

• mtime (int) – Modification time to set on the file.

• progress_callback (function, None) – Callback method that accepts filename, bytes_written and total_bytes, total_bytes will be -1 for file-like objects

• timeout_s (float, None) – Expected timeout for any part of the push.

• total_timeout_s (float) – The total time in seconds to wait for a b'CLSE' or b'OKAY' command in AdbDevice._read()

async root(timeout_s=None, total_timeout_s=10.0)

Gain root access.

The device must be rooted in order for this to work.

Parameters

• timeout_s (float, None) – Timeout in seconds for sending and receiving packets, or None; see BaseHandle.bulk_read() and BaseHandle.bulk_write()

• total_timeout_s (float) – The total time in seconds to wait for a b'CLSE' or b'OKAY' command in AdbDevice._read()

async shell(command, timeout_s=None, total_timeout_s=10.0, decode=True)

Send an ADB shell command to the device.

Parameters

• command (str) – The shell command that will be sent

• timeout_s (float, None) – Timeout in seconds for sending and receiving packets, or None; see BaseHandle.bulk_read() and BaseHandle.bulk_write()

• total_timeout_s (float) – The total time in seconds to wait for a b'CLSE' or b'OKAY' command in AdbDevice._read()

• decode (bool) – Whether to decode the output to utf8 before returning

Returns

The output of the ADB shell command as a string if decode is True, otherwise as bytes.

Return type

bytes, str

async stat(device_filename, timeout_s=None, total_timeout_s=10.0)

Get a file’s stat() information.

Parameters

• device_filename (str) – The file on the device for which we will get information.

• timeout_s (float, None) – Expected timeout for any part of the pull.

• total_timeout_s (float) – The total time in seconds to wait for a b'CLSE' or b'OKAY' command in AdbDevice._read()

Returns

• mode (int) – The octal permissions for the file

• size (int) – The size of the file

• mtime (int) – The last modified time for the file

streaming_shell(command, timeout_s=None, total_timeout_s=10.0, decode=True)

Send an ADB shell command to the device, yielding each line of output.

Parameters

• command (str) – The shell command that will be sent

• timeout_s (float, None) – Timeout in seconds for sending and receiving packets, or None; see BaseHandle.bulk_read() and BaseHandle.bulk_write()

• total_timeout_s (float) – The total time in seconds to wait for a b'CLSE' or b'OKAY' command in AdbDevice._read()

• decode (bool) – Whether to decode the output to utf8 before returning

Yields

bytes, str – The line-by-line output of the ADB shell command as a string if decode is True, otherwise as bytes.

class aio_adb_shell.adb_device.AdbDeviceTcp(host, port=5555, default_timeout_s=None, banner=None)

Bases: aio_adb_shell.adb_device.AdbDevice

A class with methods for connecting to a device via TCP and executing ADB commands.

Parameters

• host (str) – The address of the device; may be an IP address or a host name

• port (int) – The device port to which we are connecting (default is 5555)

• default_timeout_s (float, None) – Default timeout in seconds for TCP packets, or None

• banner (str, bytes, None) – The hostname of the machine where the Python interpreter is currently running; if it is not provided, it will be determined via socket.gethostname()

_available

Whether an ADB connection to the device has been established

Type

bool

_banner

The hostname of the machine where the Python interpreter is currently running

Type

bytearray, bytes

_handle

The handle that is used to connect to the device

Type

TcpHandle

class aio_adb_shell.adb_device.DeviceFile(filename, mode, size, mtime)

Bases: tuple

_asdict()

Return a new OrderedDict which maps field names to their values.

_fields = ('filename', 'mode', 'size', 'mtime')

_fields_defaults = {}

classmethod _make(iterable)

Make a new DeviceFile object from a sequence or iterable

_replace(**kwds)

Return a new DeviceFile object replacing specified fields with new values

property filename

Alias for field number 0

property mode

Alias for field number 1

property mtime

Alias for field number 3

property size

Alias for field number 2

class aio_adb_shell.adb_device._AdbTransactionInfo(local_id, remote_id, timeout_s=None, total_timeout_s=10.0)

Bases: object

A class for storing info and settings used during a single ADB “transaction.”

Parameters

• local_id (int) – The ID for the sender (i.e., the device running this code)

• remote_id (int) – The ID for the recipient

• timeout_s (float, None) – Timeout in seconds for sending and receiving packets, or None; see BaseHandle.bulk_read() and BaseHandle.bulk_write()

• total_timeout_s (float) – The total time in seconds to wait for a command in expected_cmds in AdbDevice._read()

local_id

The ID for the sender (i.e., the device running this code)

Type

int

remote_id

The ID for the recipient

Type

int

timeout_s

Timeout in seconds for sending and receiving packets, or None; see BaseHandle.bulk_read() and BaseHandle.bulk_write()

Type

float, None

total_timeout_s

The total time in seconds to wait for a command in expected_cmds in AdbDevice._read()

Type

float

class aio_adb_shell.adb_device._FileSyncTransactionInfo(recv_message_format)

Bases: object

A class for storing info used during a single FileSync “transaction.”

Parameters

recv_message_format (bytes) – The FileSync message format

recv_buffer

A buffer for storing received data

Type

bytearray

recv_message_format

The FileSync message format

Type

bytes

recv_message_size

The FileSync message size

Type

int

send_buffer

A buffer for storing data to be sent

Type

bytearray

send_idx

The index in recv_buffer that will be the start of the next data packet sent

Type

int

can_add_to_send_buffer(data_len)

Determine whether data_len bytes of data can be added to the send buffer without exceeding constants.MAX_ADB_DATA.

Parameters

data_len (int) – The length of the data to be potentially added to the send buffer (not including the length of its header)

Returns

Whether data_len bytes of data can be added to the send buffer without exceeding constants.MAX_ADB_DATA

Return type

bool

aio_adb_shell.adb_device._open(name, mode='r')

Handle opening and closing of files and IO streams.

Parameters

• name (str, io.IOBase) – The name of the file or an IO stream

• mode (str) – The mode for opening the file

Yields

io.IOBase – The opened file or the IO stream