Add a quick tutorial for services. (#527)
diff --git a/README.md b/README.md
index 89d511d..19feafa 100644
--- a/README.md
+++ b/README.md
@@ -59,10 +59,15 @@
restrictions.
## Tutorials
-To get started with some simple tests, see the [Mobly tutorial](docs/tutorial.md).
-To get started running single-device Android instrumentation tests with Mobly,
-see the [instrumentation runner tutorial](docs/instrumentation_tutorial.md).
+* [Mobly 101](docs/tutorial.md) -
+Simple test examples to get you started with Mobly.
+
+* [Mobly Instrumentation Runner Tutorial](docs/instrumentation_tutorial.md) -
+How to use Mobly's Android instrumentation test runner to run Android instrumentation tests.
+
+* [Mobly AndroidDevice Service](docs/android_device_service.md) -
+Create custom service to attach to Mobly's `AndroidDevice` controller.
## Mobly Snippet
The Mobly Snippet projects let users better control Android devices.
diff --git a/docs/android_device_service.md b/docs/android_device_service.md
new file mode 100644
index 0000000..a76456a
--- /dev/null
+++ b/docs/android_device_service.md
@@ -0,0 +1,80 @@
+# Mobly Android Device Service
+
+This tutorial shows how to use the service mechanism in Mobly's `AndroidDevice`
+controller.
+
+## Purpose
+Mobly's `AndroidDevice` controller is a Python module that lets users interact
+with Android devices with Python code.
+
+Often times, we need long-running services associated with `AndroidDevice`
+objects that persist during a test, e.g. adb logcat collection, screen
+recording. Meanwhile, we may want to alter the device's state during the
+test, e.g. reboot.
+
+`AndroidDevice` services makes it easier to implement long-running services.
+
+## Usage
+
+Implement your service per the
+[`BaseService` interface](https://github.com/google/mobly/blob/master/mobly/controllers/android_device_lib/services/base_service.py).
+
+Here is a dummy service example:
+
+`my_service.py`
+
+```python
+class Configs(object):
+ def __init__(self, secret=None):
+ self.secret = secret
+
+
+class MyService(base_service.BaseService):
+ """Dummy service demonstrating the service interface."""
+ def __init__(self, device, configs=None):
+ self._device = device
+ self._configs = configs
+ self._is_alive = False
+
+ def get_my_secret(self):
+ return self._configs.secret
+
+ @property
+ def is_alive(self):
+ """Override base class"""
+ return self._is_alive
+
+ def start(self):
+ """Override base class"""
+ self._is_alive = True
+
+ def stop(self):
+ """Override base class"""
+ self._is_alive = False
+```
+
+Once you have your service class, you can register your service with the
+`ServiceManager`. Let's say we already have an `AndroidDevice` instance `ad`:
+
+```python
+ad.services.register('secret_service',
+ my_service.MyService,
+ my_service.Configs(secret=42))
+```
+
+After registration, you can interact with the service instance:
+
+```python
+ad.services.secret_service.is_alive # True
+ad.services.secret_service.get_my_secret() # 42
+```
+
+When the `ad` reboots or gets destroyed, the service manager will handle the
+lifecycle changes of each service instance. So users don't have to explicitly
+write code to handle device state changes for each service, which makes the
+test verbose.
+
+The service interface also has optional methods `pause` and `resume` for
+services that are sensitive to device disconnect without reboot. For more
+details, see the docstrings of the
+[`BaseService` interface](https://github.com/google/mobly/blob/master/mobly/controllers/android_device_lib/services/base_service.py).
diff --git a/docs/tutorial.md b/docs/tutorial.md
index 59ea651..5fd98c0 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -1,11 +1,10 @@
-Getting started with Mobly
-======
+# Getting started with Mobly
This tutorial shows how to write and execute simple Mobly test cases. We are
using Android devices here since they are pretty accessible. Mobly supports
various devices and you can also use your own custom hardware/equipment.
-# Setup Requirements
+## Setup Requirements
* A computer with at least 2 USB ports.
* Mobly package and its system dependencies installed on the computer.
@@ -16,7 +15,7 @@
and make sure it has "USB debugging" enabled. Make sure the device shows up
in the list printed by `adb devices`.
-# Example 1: Hello World!
+## Example 1: Hello World!
Let's start with the simple example of posting "Hello World" on the Android
device's screen. Create the following files:
@@ -78,7 +77,7 @@
label: golden_device
```
-# Example 2: Invoking specific test case
+## Example 2: Invoking specific test case
We have multiple tests written in a test script, and we only want to execute
a subset of them.
@@ -129,7 +128,7 @@
Toast notifications appear on your device's screen in the following order:
"Goodbye!", "Hello World!", "Goodbye!".
-# Example 3: User parameters
+## Example 3: User parameters
You could specify user parameters to be passed into your test class in the
config file.
@@ -158,7 +157,7 @@
self.dut.mbs.makeToast("I'm not hungry.")
```
-# Example 4: Multiple Test Beds and Default Test Parameters
+## Example 4: Multiple Test Beds and Default Test Parameters
Multiple test beds can be configured in one configuration file.
@@ -200,7 +199,7 @@
screen.
-# Example 5: Test with Multiple Android devices
+## Example 5: Test with Multiple Android devices
In this example, we use one Android device to discover another Android device
via bluetooth. This test demonstrates several essential elements in test
@@ -303,7 +302,7 @@
(https://github.com/google/mobly-snippet-lib/tree/master/examples).
-# Example 6: Generated Tests
+## Example 6: Generated Tests
A common use case in writing tests is to execute the same test logic multiple
times, each time with a different set of parameters. Instead of duplicating the
