android-maestro/README.rst

===============
Android Maestro
===============

An orchestrator of system load on Android devices, such as stability
testing for a fixed duration. An interactive shell brings a simple
interface to human operators.

*Maestro* can initiate load sessions on one or more devices at once.
The progress of running sessions can be monitored on the fly.

It is important to begin a test from a well-known state. The target
devices must have been prepared (either manually or automatically)
in a consistent and reproducible fashion. An example of preparation
is described thereafter.

Installation
------------

*Maestro* can be installed directly from the Git repository::

    # Install the latest native Python RSA crypto library
    $ pip install rsa~=4.0
    # Install the latest Android Maestro
    $ pip install --process-dependency-links \
    'git+https://code.fairphone.com/gerrit/vendor/fairphone/tools#subdirectory=android-maestro&egg=android-maestro'

Alternatively, from a local check-out::

    # Install the latest native Python RSA crypto library
    $ pip install rsa~=4.0
    # Install Android Maestro from the checked-out directory
    $ pip install .

It requires:

* Python 3.6
* The `libusb-1.0`_ library (required by the `Android tools library`_)
* One of the `Python RSA library`_ or the (compiled) `M2Crypto library`_
  (required by the `Android tools library`_)

.. note:: Install the cryptography library of your choice before *Maestro*.

    *Maestro* uses the `Android tools library`_ that itself uses the
    `Python ADB library`_ that requires one of the two aforementioned
    crypto library to be installed. `Python ADB library`_ automatically
    installs the `M2Crypto library`_ by default, which requires non-Python
    development library on the host system (OpenSSL headers).

    To avoid a broken installation process when the extra components are
    missing, it is recommended to install the `Python RSA library`_
    beforehand. The `M2Crypto library`_ will still be used if it is
    available.

Android device preparation
--------------------------

1.  Wipe the user data off the device;
2.  Go through the setup wizard and make sure the following features are
    configured:

  1.  Wi-Fi is enabled and a network can be reached (with access to the
      Internet);
  2.  GPS is on and, if available, high accuracy is enabled;
  3.  Any other wireless features are turned off (telephony, Bluetooth,
      NFC).

3.  Enable *Developer options* and turn off the USB app verification;
4.  Connect the device to the host and approve the adb connection.

Development
-----------

This library belongs to the `Fairphone Android tools`_ project. Refer to its
documentation for more information.

Documentation
-------------

Build this project documentation with Sphinx, inside the development
environment::

    $ cd docs
    $ make html
    $ xdg-open _build/html/index.html

Versioning
----------

The intersection of `PEP 440`_ and `Semantic Versioning 2.00`_ defines
the simple versioning scheme: "major.minor[.patch]".

License
-------

The project is made available under the terms of the `Apache 2.0 license`_.
See the `LICENSE` file for details.

.. _`Android tools library`: https://code.fairphone.com/gerrit/gitweb?p=vendor/fairphone/tools.git;f=python-libs/android-tools
.. _`Apache 2.0 license`: http://apache.org/licenses/LICENSE-2.0.txt
.. _`Fairphone Android tools`: https://code.fairphone.com/gerrit/gitweb?p=vendor/fairphone/tools.git
.. _`libusb-1.0`: https://libusb.info
.. _`M2Crypto library`: https://gitlab.com/m2crypto/m2crypto
.. _`PEP 440`: https://www.python.org/dev/peps/pep-0440/
.. _`Python ADB library`: https://github.com/google/python-adb
.. _`Python RSA library`: https://stuvel.eu/rsa
.. _`Semantic Versioning 2.00`: https://semver.org/spec/v2.0.0.html