| =============== |
| 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 |