Overview

A Target instance serves as the main interface to the target device. There are currently four target interfaces:

  • LinuxTarget for interacting with Linux devices over SSH.

  • AndroidTarget for interacting with Android devices over adb.

  • ChromeOsTarget: for interacting with ChromeOS devices over SSH, and their Android containers over adb.

  • LocalLinuxTarget: for interacting with the local Linux host.

They all work in more-or-less the same way, with the major difference being in how connection settings are specified; though there may also be a few APIs specific to a particular target type (e.g. AndroidTarget exposes methods for working with logcat).

Acquiring a Target

To create an interface to your device, you just need to instantiate one of the Target derivatives listed above, and pass it the right connection_settings. Code snippet below gives a typical example of instantiating each of the three target types.

from devlib import LocalLinuxTarget, LinuxTarget, AndroidTarget

# Local machine requires no special connection settings.
t1 = LocalLinuxTarget()

# For a Linux device, you will need to provide the normal SSH credentials.
# Both password-based, and key-based authentication is supported (password
# authentication requires sshpass to be installed on your host machine).'
t2 = LinuxTarget(connection_settings={'host': '192.168.0.5',
                                     'username': 'root',
                                     'password': 'sekrit',
                                     # or
                                     'keyfile': '/home/me/.ssh/id_rsa'})
# ChromeOsTarget connection is performed in the same way as LinuxTarget

# For an Android target, you will need to pass the device name as reported
# by "adb devices". If there is only one device visible to adb, you can omit
# this setting and instantiate similar to a local target.
t3 = AndroidTarget(connection_settings={'device': '0123456789abcde'})

Instantiating a target may take a second or two as the remote device will be queried to initialize Target’s internal state. If you would like to create a Target instance but not immediately connect to the remote device, you can pass connect=False parameter. If you do that, you would have to then explicitly call t.connect() before you can interact with the device.

There are a few additional parameters you can pass in instantiation besides connection_settings, but they are usually unnecessary. Please see Target API documentation for more details.

Target Interface

This is a quick overview of the basic interface to the device. See Target API documentation for the full list of supported methods and more detailed documentation.

One-time Setup

from devlib import LocalLinuxTarget
t = LocalLinuxTarget()

t.setup()

This sets up the target for devlib interaction. This includes creating working directories, deploying busybox, etc. It’s usually enough to do this once for a new device, as the changes this makes will persist across reboots. However, there is no issue with calling this multiple times, so, to be on the safe side, it’s a good idea to call this once at the beginning of your scripts.

Command Execution

There are several ways to execute a command on the target. In each case, an instance of a subclass of TargetError will be raised if something goes wrong. When a transient error is encountered such as the loss of the network connectivity, it will raise a TargetTransientError. When the command fails, it will raise a TargetStableError unless the will_succeed=True parameter is specified, in which case a TargetTransientError will be raised since it is assumed that the command cannot fail unless there is an environment issue. In each case, it is also possible to specify as_root=True if the specified command should be executed as root.

from devlib import LocalLinuxTarget
t = LocalLinuxTarget()

# Execute a command
output = t.execute('echo $PWD')

# Execute command via a subprocess and return the corresponding Popen object.
# This will block current connection to the device until the command
# completes.
p = t.background('echo $PWD')
output, error = p.communicate()

# Run the command in the background on the device and return immediately.
# This will not block the connection, allowing to immediately execute another
# command.
t.kick_off('echo $PWD')

# This is used to invoke an executable binary on the device. This allows some
# finer-grained control over the invocation, such as specifying the directory
# in which the executable will run; however you're limited to a single binary
# and cannot construct complex commands (e.g. this does not allow chaining or
# piping several commands together).
output = t.invoke('echo', args=['$PWD'], in_directory='/')

File Transfer

from devlib import LocalLinuxTarget
t = LocalLinuxTarget()

# "push" a file from the local machine onto the target device.
t.push('/path/to/local/file.txt', '/path/to/target/file.txt')

# "pull" a file from the target device into a location on the local machine
t.pull('/path/to/target/file.txt', '/path/to/local/file.txt')

# Install the specified binary on the target. This will deploy the file and
# ensure it's executable. This will *not* guarantee that the binary will be
# in PATH. Instead the path to the binary will be returned; this should be
# used to call the binary henceforth.
target_bin = t.install('/path/to/local/bin.exe')
# Example invocation:
output = t.execute('{} --some-option'.format(target_bin))

The usual access permission constraints on the user account (both on the target and the host) apply.

Process Control

import signal
from devlib import LocalLinuxTarget
t = LocalLinuxTarget()

# return PIDs of all running instances of a process
pids = t.get_pids_of('sshd')

# kill a running process. This works the same ways as the kill command, so
# SIGTERM will be used by default.
t.kill(666, signal=signal.SIGKILL)

# kill all running instances of a process.
t.killall('badexe', signal=signal.SIGKILL)

# List processes running on the target. This returns a list of parsed
# PsEntry records.
entries = t.ps()
# e.g.  print virtual memory sizes of all running sshd processes:
print(', '.join(str(e.vsize) for e in entries if e.name == 'sshd'))

More…

As mentioned previously, the above is not intended to be exhaustive documentation of the Target interface. Please refer to the API documentation for the full list of attributes and methods and their parameters.

Super User Privileges

It is not necessary for the account logged in on the target to have super user privileges, however the functionality will obviously be diminished, if that is not the case. devlib will determine if the logged in user has root privileges and the correct way to invoke it. You should avoid including “sudo” directly in your commands, instead, specify as_root=True where needed. This will make your scripts portable across multiple devices and OS’s.

On-Target Locations

File system layouts vary wildly between devices and operating systems. Hard-coding absolute paths in your scripts will mean there is a good chance they will break if run on a different device. To help with this, devlib defines a couple of “standard” locations and a means of working with them.

working_directory

This is a directory on the target readable and writable by the account used to log in. This should generally be used for all output generated by your script on the device and as the destination for all host-to-target file transfers. It may or may not permit execution so executables should not be run directly from here.

executables_directory

This directory allows execution. This will be used by install().

from devlib import LocalLinuxTarget
t = LocalLinuxTarget()

# t.path  is equivalent to Python standard library's os.path, and should be
# used in the same way. This insures that your scripts are portable across
# both target and host OS variations. e.g.
on_target_path = t.path.join(t.working_directory, 'assets.tar.gz')
t.push('/local/path/to/assets.tar.gz', on_target_path)

# Since working_directory is a common base path for on-target locations,
# there a short-hand for the above:
t.push('/local/path/to/assets.tar.gz', t.get_workpath('assets.tar.gz'))

Exceptions Handling

Devlib custom exceptions all derive from DevlibError. Some exceptions are further categorized into DevlibTransientError and DevlibStableError. Transient errors are raised when there is an issue in the environment that can happen randomly such as the loss of network connectivity. Even a properly configured environment can be subject to such transient errors. Stable errors are related to either programming errors or configuration issues in the broad sense. This distinction allows quicker analysis of failures, since most transient errors can be ignored unless they happen at an alarming rate. DevlibTransientError usually propagates up to the caller of devlib APIs, since it means that an operation could not complete. Retrying it or bailing out is therefore a responsability of the caller.

The hierarchy is as follows:

  • DevlibError

    • WorkerThreadError

    • HostError

    • TargetError

      • TargetStableError

      • TargetTransientError

      • TargetNotRespondingError

    • DevlibStableError

      • TargetStableError

    • DevlibTransientError

      • TimeoutError

      • TargetTransientError

      • TargetNotRespondingError

Extending devlib

New devlib code is likely to face the decision of raising a transient or stable error. When it is unclear which one should be used, it can generally be assumed that the system is properly configured and therefore, the error is linked to an environment transient failure. If a function is somehow probing a property of a system in the broad meaning, it can use a stable error as a way to signal a non-expected value of that property even if it can also face transient errors. An example are the various execute() methods where the command can generally not be assumed to be supposed to succeed by devlib. Their failure does not usually come from an environment random issue, but for example a permission error. The user can use such expected failure to probe the system. Another example is boot completion detection on Android: boot failure cannot be distinguished from a timeout which is too small. A non-transient exception is still raised, since assuming the timeout comes from a network failure would either make the function useless, or force the calling code to handle a transient exception under normal operation. The calling code would potentially wrongly catch transient exceptions raised by other functions as well and attach a wrong meaning to them.

Modules

Additional functionality is exposed via modules. Modules are initialized as attributes of a target instance. By default, hotplug, cpufreq, cpuidle, cgroups and hwmon will attempt to load on target; additional modules may be specified when creating a Target instance.

A module will probe the target for support before attempting to load. So if the underlying platform does not support particular functionality (e.g. the kernel on target device was built without hotplug support). To check whether a module has been successfully installed on a target, you can use has() method, e.g.

from devlib import LocalLinuxTarget
t = LocalLinuxTarget()

cpu0_freqs = []
if t.has('cpufreq'):
    cpu0_freqs = t.cpufreq.list_frequencies(0)

Please see the modules documentation for more detail.

Instruments and Collectors

You can retrieve multiple types of data from a target. There are two categories of classes that allow for this:

  • An Instrument which may be used to collect measurements (such as power) from targets that support it. Please see the instruments documentation for more details.

  • A Collector may be used to collect arbitary data from a Target varying from screenshots to trace data. Please see the collectors documentation for more details.

An example workflow using FTraceCollector is as follows:

from devlib import AndroidTarget, FtraceCollector
t = LocalLinuxTarget()

# Initialize a collector specifying the events you want to collect and
# the buffer size to be used.
trace = FtraceCollector(t, events=['power*'], buffer_size=40000)

# As a context manager, clear ftrace buffer using trace.reset(),
# start trace collection using trace.start(), then stop it Using
# trace.stop(). Using a context manager brings the guarantee that
# tracing will stop even if an exception occurs, including
# KeyboardInterrupt (ctr-C) and SystemExit (sys.exit)
with trace:
   # Perform the operations you want to trace here...
   import time; time.sleep(5)

# extract the trace file from the target into a local file
trace.get_data('/tmp/trace.bin')

# View trace file using Kernelshark (must be installed on the host).
trace.view('/tmp/trace.bin')

# Convert binary trace into text format. This would normally be done
# automatically during get_data(), unless autoreport is set to False during
# instantiation of the trace collector.
trace.report('/tmp/trace.bin', '/tmp/trace.txt')