Navigation

ADB Handset

Although handset objects can be created explicitly, you should always allocate handsets through the broker instead (possibly with more attributes set in the allocation profile):

from ave.broker import Broker

broker = Broker()
handset = broker.get({'type':'handset', 'platform':'adb'})

The returned handset implements the API that is documented here.

Warning

Many functions require super user privileges and will not work before a root() call has been made.

class ave.handset.adb_handset.AdbHandset(profile)

Base class for handsets supporting the ADB protocol.

Parameters:
  • profile –

    A HandsetProfile instance that must contain at least the following members:

    {
    'type'    : 'handset',
    'platform': 'adb',
    'serial'  : 'xxx' # the serial number of the handset
}
  • profile – A dictionary containing at least the "type":"handset" and "platform":"adb" entries.
Returns:

An AndroidHandset instance.
get_profile()

Get the profile that the handset was allocated against. This method is intended for AVE internal usage and not recommended for regular users. This profile is not updated when the handset’s state changes, e.g. rebooting does not affect this profile’s power_state value.

Returns:A dictionary.
get_workstation()

Get the workstation to which the handset is connected.

Returns:the handset’s workstation name
Raises Exception:
 If an error occurs.

Port Forwarding

open_forwarded_port(remote)

Set up an ADB port forwarding rule.

Parameters:remote – An ADB port forwarding expression. E.g. "tcp:2001" would create a rule that forwards connections to TCP port 2001 on the handset. See ADB documentation for details.
Returns:An identifying token that may be used as input to functions that manipulate or query the state of the forwarded port. The token is formatted as "tcp:<int>" where <int> is the randomized port number used on the PC to forward connections.
close_forwarded_port(entry)

Tear down an ADB port forwarding rule.

Parameters:entry – A token returned by open_forwarded_port().
list_forwarded_ports(all_adb=False)

List all port forwarding rules.

Parameters:all_adb – If set, return all forwarding rules for all handsets. Default behavior is to only list rules for the current handset.

Power States

has_adb()

Check if the handset is reachable via adb.

Returns:True or False.
boot_completed()

Check if handset property sys.boot_completed has been set to “1”.

Returns:True or False.
get_power_state()

Get the handset’s current power state.

Reachable power states:

'offline',         # the handset is turned off or not connected
'service',         # the handset is in service mode
'enumeration',     # the handset's USB is set up and ready
'adb',             # the handset is available via adb
'boot_completed'   # the sys.boot_completed property is set to "1"
Returns:The current power state.
wait_power_state(states, timeout=0)

Wait for the handset to reach a desired power state.

Reachable power states:

'offline',         # the handset is turned off or not connected
'service',         # the handset is in service mode
'enumeration',     # the handset's USB is set up and ready
'adb',             # the handset is available via adb
'boot_completed'   # the sys.boot_completed property is set to "1"

On a normal boot of a handset it will go through the power states in the following order:

offline > enumeration > adb > boot_completed
Parameters:
  • states – A string or a list of strings, where the string(s) can be any of the reachable states listed above.
  • timeout – If timeout > 0, seconds before time out.
Returns:

The reached power state.
Raises Exception:
 

If an error occurs.
reboot(timeout=30)

Reboot the handset.

Parameters:

timeout – Number of seconds to wait for the handset to go offline.
Raises:
  • Timeout – If such occurs.
  • Exception – If an error occurs.

ADB Intrinsics

root()

Restart adbd as root.

The call will block until the device is available again. :raises Exception: If an error occurs.

remount()

Remount the handset’s system partition as writable.

Returns:The output of the remount command.
Raises Exception:
 If an error occurs.

File System Functionality

ls(path)

List files in path on handset.

Args path:The path to list files in.
Returns:A list of files.
Raises Exception:
 If an error occurs.
cat(target)

Get the content of the file target.

Parameters:target – The file to read.
Returns:The content of the target file as a string.
Raises Exception:
 If an error occurs.
rm(target, recursive=False)

Remove file or directory from the handset.

Parameters:
  • target – The file or directory to remove.
  • recursive – If True files will be removed recursively, else not.
Raises Exception:
 

If an error occurs.
mv(src, dst)

Move file(s) on the handset.

Parameters:
  • src – Source path.
  • dst – Destination path.
Raises Exception:
 

If an error occurs.
mkdir(target, parents=False)

Create directory on handset.

Parameters:
  • target – The directory to create.
  • parents – If True create parent directories as needed and don’t raise an exception if target already exists.
Raises Exception:
 

If an error occurs or the directory already exists.
chmod(permissions, target)

Change permissions of a file on the handset.

Parameters:
  • permissions – Permissions to set on the file (e.g. “777”).
  • target – The file to change permissions on.
Raises Exception:
 

If an error occurs.
path_exists(path, file_type=None)

Check if path exists on handset. Optional: check file type of path.

Parameters:
  • path – Path on handset to check.
  • file_type –

    If given, verify that the file type of path is file_type. Valid values:

    'symlink', 'directory', 'file', 'executable'
Returns:

True if path exists (and file type is file_type, if that parameter was given), else False.
Raises Exception:
 

If an error occurs.
push(src, dst, timeout=0)

Push file to the handset via adb.if the pushed source filename starts with ‘tmp’ then the method raises an exception: temp-files generated by the workspace are not possible to track after the test execution and thus the possibility to push these files to the handset has been restricted. In order to push a generated file, it must first be secured that the file can be resurrected during post mortem analysis. AVE offers two ways to do this: Either during write_tempfile() or with the specific workspace method promote(). Please refer to the API description for details.

Parameters:
  • src – The path on host to the source file.
  • dst – The destination on the handset.
  • timeout – Seconds before time out.
Returns:

The execution output.
Raises:
  • Timeout – If such occurs.
  • Exception – If other error occurs.
pull(src, dst, timeout=0)

Pull file from the handset via adb.

Parameters:
  • src – The source file(s) on the handset (wildcards allowed).
  • dst – The local destination path.
  • timeout – Seconds before time out.
Returns:

The execution output.
Raises:
  • Timeout – If such occurs.
  • Exception – On other errors.
take_screenshot(dst, timeout=20)

Take screenshot of the device via adb.

Parameters:
  • dst – The destination file of screenshot.
  • timeout – Seconds before time out.
Returns:

The execution output.
Raises:
  • Timeout – If such occurs.
  • Exception – On other errors.
is_mounted(mount_point)

Check if mount_point is mounted.

Parameters:mount_point – Mount point as a string.
Returns:True if mount_point is mounted, else False.
Raises Exception:
 If an error occurs.
wait_mounted(sdcard, ext_card, timeout=30)

Wait until sdcard and/or ext_card is mounted.

Parameters:
  • sdcard – If True wait for sdcard to be mounted.
  • ext_card – If True wait for ext_card to be mounted.
  • timeout – Seconds before time out.
Raises Timeout:

If such occured.
wait_for_path(path, file_type=None, timeout=0)

Wait until path exists on handset. Optional: check file type of path.

Parameters:
  • path – Path on handset to check.
  • file_type –

    If given, verify that the file type of path is file_type. Valid values:

    'symlink', 'directory', 'file', 'executable'
  • timeout – If timeout > 0, seconds before time out.
Raises Exception:
 

If an error occurs.

Processes

shell(args, timeout=0, bg=False)

Execute an adb shell command.

Parameters:
  • args – A list or a string of arguments to be executed by adb shell
  • timeout – Timeout for the command. No timeout is set by default.
  • bg – specify the running mode, if True, run the command in background
Returns:

if the cmd run in background the return values are the new process id and the file descriptor of the new process’s pseudoterminal, else is the Output from execution.
Raises:
  • Timeout – If such occured.
  • Exception – On other errors.

Note

Detection of failure is hard with ADB because the exit code for an execution is not returned to the test host. shell() only checks for known error indications on stdout.

kill_background_cmd(pid, fd)

Kill the cmd process now is running in background

Parameters:
  • pid – The id of the background process
  • fd – The file descriptor of the process’s pseudoterminal
Raises:
  • OSError – If cannot close fd
  • Exception – On other errors
ps(name=None, exact=False)

Get all current procceses’ id and name.

Parameters:
  • name – If given only return processes with matching name.
  • exact – If True only return processes with exact matching name.
Returns:

A list with dicts, e.g [{‘pid’:123,’name’:’pid_name’},..]
Raises Exception:
 

If an error occurs.

Properties

set_property(key, value)

Set property and verify value.

Parameters:
  • key – The property name.
  • value – The new property value as a string.
Raises Exception:
 

If property was not set successfully.
get_property(key)

Get the value of the given property.

Parameters:key – The property name.
Returns:The property’s value.
Raises Exception:
 If no value was found or an error occured.
get_product_name()

Get the product name of the handset.

Returns:The product name of the handset, or empty string if product name wasn’t found.
Raises Exception:
 If an error occurs.
get_build_label()

Get the build label of the software on the handset.

Returns:The build label of the software on the handset.
Raises Exception:
 If the build label was not fetched successfully.
clear_property(key)

Clear the value for the given property.

Parameters:key – The property name.
Raises Exception:
 If failed to clear property or an error occured.
get_sdk_version()

Get the SDK version of the running platform.

Returns:An integer denoting the version. E.g. 23 for Android M

Crash Handling

run_bugreport(directory)

Execute ‘bugreport’ on handset. Create a file with the bugreport output in the given directory on the handset and return the file’s full path.

Parameters:directory – An existing directory on the handset where the file will be written.
Returns:The full path on the handset to the created file.
Raises Exception:
 If an error occurs.
force_dump(timeout=0)

Force the handset to dump.

Parameters:

timeout – Secods before time out.
Raises:
  • Timeout – If such occured.
  • Exception – On other errors.

Table Of Contents

Previous topic

Handset Profile

Next topic

Android Handset

This Page

Navigation

© Copyright 2013-2014, Sony Mobile Communications Inc.. Created using Sphinx 1.1.3.