README.md
1# Pandora Android server
2
3The Pandora Android server exposes the [Pandora test interfaces](
4go/pandora-doc) over gRPC implemented on top of the Android Bluetooth SDK.
5
6## Getting started
7
8Using Pandora Android server requires to:
9
10* Build AOSP for your DUT, which can be either a physical device or an Android
11 Virtual Device (AVD).
12* [Only for virtual tests] Build Rootcanal, the Android
13 virtual Bluetooth Controller.
14* Setup your test environment.
15* Build, install, and run Pandora server.
16* Run your tests.
17
18### 1. Build and run AOSP code
19
20Refer to the AOSP documentation to [initialize and sync](
21https://g3doc.corp.google.com/company/teams/android/developing/init-sync.md)
22AOSP code, and [build](
23https://g3doc.corp.google.com/company/teams/android/developing/build-flash.md)
24it for your DUT (`aosp_cf_x86_64_phone-userdebug` for the emulator).
25
26**If your DUT is a physical device**, flash the built image on it. You may
27need to use [Remote Device Proxy](
28https://g3doc.corp.google.com/company/teams/android/wfh/adb/remote_device_proxy.md)
29if you are using a remote instance to build. If you are also using `adb` on
30your local machine, you may need to force kill the local `adb` server (`adb
31kill-server` before using Remote Device Proxy.
32
33**If your DUT is a Cuttlefish virtual device**, then proceed with the following steps:
34
35* Connect to your [Chrome Remote Desktop](
36 https://remotedesktop.corp.google.com/access/).
37* Create a local Cuttlefish instance using your locally built image with the command
38 `acloud create --local-instance --local-image` (see [documentation](
39 go/acloud-manual#local-instance-using-a-locally-built-image))
40
41### 2. Build Rootcanal [only for virtual tests on a physical device]
42
43Rootcanal is a virtual Bluetooth Controller that allows emulating Bluetooth
44communications. It is used by default within Cuttlefish when running it using the [acloud](go/acloud) command (and thus this step is not
45needed) and is required for all virtual tests. However, it does not come
46preinstalled on a build for a physical device.
47
48Proceed with the [following instructions](
49https://docs.google.com/document/d/1-qoK1HtdOKK6sTIKAToFf7nu9ybxs8FQWU09idZijyc/edit#heading=h.x9snb54sjlu9)
50to build and install Rootcanal on your DUT.
51
52### 3. Setup your test environment
53
54Each time when starting a new ADB server to communicate with your DUT, proceed
55with the following steps to setup the test environment:
56
57* If running virtual tests (such as PTS-bot) on a physical device:
58 * Run Rootcanal:
59 `adb root` then
60 `adb shell ./vendor/bin/hw/android.hardware.bluetooth@1.1-service.sim &`
61 * Forward Rootcanal port through ADB:
62 `adb forward tcp:<rootcanal-port> tcp:<rootcanal-port>`.
63 Rootcanal port number may differ depending on its configuration. It is
64 7200 for the AVD, and generally 6211 for physical devices.
65* Forward Pandora Android server port through ADB:
66 `adb forward tcp:8999 tcp:8999`.
67
68The above steps can be done by executing the `setup.sh` helper script (the
69`-rootcanal` option must be used for virtual tests on a physical device).
70
71Finally, you must also make sure that the machine on which tests are executed
72can access the ports of the Pandora Android server, Rootcanal (if required),
73and ADB (if required).
74
75You can also check the usage examples provided below.
76
77### 4. Build, install, and run Pandora Android server
78
79* `m PandoraServer`
80* `adb install -r -g out/target/product/<device>/testcases/Pandora/arm64/Pandora.apk`
81
82* Start the instrumented app:
83* `adb shell am instrument -w -e Debug false com.android.pandora/.Server`
84
85### 5. Run your tests
86
87You should now be fully set up to run your tests!
88
89### Usage examples
90
91Here are some usage examples:
92
93* **DUT**: physical
94 **Test type**: virtual
95 **Test executer**: remote instance (for instance a Cloudtop) accessed via SSH
96 **Pandora Android server repository location**: local machine (typically
97 using Android Studio)
98
99 * On your local machine: `./setup.sh --rootcanal`.
100 * On your local machine: build and install the app on your DUT.
101 * Log on your remote instance, and forward Rootcanal port (6211, may change
102 depending on your build) and Pandora Android server (8999) port:
103 `ssh -R 6211:localhost:6211 -R 8999:localhost:8999 <remote-instance>`.
104 Optionnally, you can also share ADB port to your remote instance (if
105 needed) by adding `-R 5037:localhost:5037` to the command.
106 * On your remote instance: execute your tests.
107
108* **DUT**: virtual (running in remote instance)
109 **Test type**: virtual
110 **Test executer**: remote instance
111 **Pandora Android server repository location**: remote instance
112
113 On your remote instance:
114 * `./setup.sh`.
115 * Build and install the app on the AVD.
116 * Execute your tests.
117
118