1# Avatar
2
3Avatar is a python Bluetooth testing tool orchestrating multiple devices which
4implement [Pandora APIs](https://github.com/google/bt-test-interfaces) to
5automate Bluetooth interoperability and functional tests.
6
7## Main architecture
8
9Avatar is built around 4 key components:
10
11* [Pandora APIs](https://github.com/google/bt-test-interfaces): They provide a
12  common abstraction for Avatar to interact with all Bluetooth implementations,
13  exposing all standard Bluetooth capabilities over [gRPC](https://grpc.io/).
14* [Bumble](https://github.com/google/bumble): a python Bluetooth stack which
15  can be used as a reference against any DUT.
16* [Rootcanal][rootcanal-code]: A virtual Bluetooth Controller which emulates the
17  Bluetooth communication between the devices being tested. It is notably
18  integrated in Cuttlefish (CF), an Android virtual device.
19* [Mobly](https://github.com/google/mobly): Avatar core python test runner.
20
21For example, here is Avatar Android architecture:
22
23![Avatar Android architecture](
24images/avatar-android-bumble-virtual-architecture-simplified.svg)
25
26A basic Avatar test is built by calling a Pandora API exposed by the DUT to
27trigger a Bluetooth action and calling another Pandora API on a Reference
28device (REF) to verify that this action has been correctly executed.
29
30For example:
31
32```python
33# Test the LE connection between the central device (DUT) and peripheral device (REF).
34def test_le_connect_central(self) -> None:
35    # Start advertising on the REF device, this makes it discoverable by the DUT.
36    # The REF advertises as `connectable` and the own address type is set to `random`.
37    advertisement = self.ref.host.Advertise(
38        # Legacy since extended advertising is not yet supported in Bumble.
39        legacy=True,
40        connectable=True,
41        own_address_type=RANDOM,
42        # DUT device matches the REF device using the specific manufacturer data.
43        data=DataTypes(manufacturer_specific_data=b'pause cafe'),
44    )
45
46    # Start scanning on the DUT device.
47    scan = self.dut.host.Scan(own_address_type=RANDOM)
48    # Find the REF device using the specific manufacturer data.
49    peer = next((peer for peer in scan
50        if b'pause cafe' in peer.data.manufacturer_specific_data))
51    scan.cancel()  # Stop the scan process on the DUT device.
52
53    # Connect the DUT device to the REF device as central device.
54    connect_res = self.dut.host.ConnectLE(
55        own_address_type=RANDOM,
56        random=peer.random,  # Random REF address found during scanning.
57    )
58    advertisement.cancel()
59
60    # Assert that the connection was successful.
61    assert connect_res.connection
62    dut_ref = connect_res.connection
63
64    # Disconnect the DUT device from the REF device.
65    self.dut.host.Disconnect(connection=dut_ref)
66```
67
68Avatar tests requires DUT and REF to provide a Pandora gRPC server which
69implements the Pandora APIs and exposes them.
70
71## Bumble as a reference device
72
73By default, Avatar uses Bumble as a reference device. **Bumble is very practical
74at emulating non-Android interoperability behaviors**: because it is written in
75python and thus interpreted, its behavior can be overridden directly within the
76tests by using direct python calls to Bumble internal functions when no Pandora
77API is available (see [Implementing your own tests](
78android-guide#implementing-your-own-tests)).
79
80For example, using another Android device to emulate an interoperability
81behavior of a specific headset would require building dedicated hooks in the
82Android Bluetooth stack and the corresponding APIs which wouldn't be practical.
83
84However, other setups are also supported (see [Extended architecture](
85#extended-architecture)).
86
87## Types of Avatar tests
88
89Avatar principally addresses 2 types of tests:
90
91### Functional tests
92
93* Verify that the DUT is meeting a required specification.
94* This can be either the official Bluetooth specification or a vendor
95  specification (for example, Google's ASHA specification).
96* Aim to address all functional tests not supported by the official Bluetooth
97  Profile Tuning Suite (PTS).
98
99### Interoperability regression tests
100
101* Built by isolating and simulating only the problematic behavior of a peer
102  device in Bumble after it has been discovered.
103* Effectively scalable because it would be impossible to set up a dedicated
104  physical test bench for each peer device presenting an interoperability issue.
105
106### Examples
107
108* [Android ASHA central tests][asha-central-tests-code]
109* [Android GATT read characteristic while pairing test][gatt-test-example-code]
110
111## Design Avatar tests
112
113There are different approaches to identify new Avatar tests to implement:
114
115### From the Bluetooth specification (or a Google specification)
116
117The first approach is for creating functional tests: mandatory behaviors are
118identified in the Bluetooth specification and corresponding test cases are
119defined, and then implemented, except for test cases which are already covered
120by PTS and which must be implemented with PTS-bot. This helps cover most of the
121usual flows in the Bluetooth stack, and prevent any new changes to break them.
122
123For example: [ASHA central tests][asha-central-tests-spec] (identified from the
124ASHA specification).
125
126This approach applies to all layers of the stack and should in general be
127prioritized over the other approaches because breaking any of those usual flows
128likely translates into a top priority issue (since a large number of devices
129can be impacted).
130
131### From a bug fix
132
133The second approach is for creating interoperability regression tests: in most
134cases, interoperability issues are discovered in Dog Food or production, due to
135the extremely large number of Bluetooth devices on the market, which cannot be
136tested preventively, even manually.
137
138When such a bug is fixed, Avatar can be leveraged to build a corresponding
139regression test.
140
141### From a coverage report
142
143The third approach is to start from a code coverage report: uncovered code
144paths are identified and corresponding Avatar tests are implemented to target
145them.
146
147## Extended architecture
148
149Avatar is capable to handle any setup with multiple devices which implement
150the Pandora APIs. Avatar tests can be run physically or virtually (with
151Rootcanal).
152
153![Avatar Android architecture](
154images/avatar-extended-architecture-simplified.svg)
155
156Avatar notably supports the following setups:
157
158* Bumble DUT vs Bumble REF
159* Android DUT vs Bumble REF
160* Android DUT vs Android REF
161
162[rootcanal-code]: https://cs.android.com/android/platform/superproject/+/main:packages/modules/Bluetooth/tools/rootcanal/
163
164[asha-central-tests-code]: https://cs.android.com/android/platform/superproject/+/main:packages/modules/Bluetooth/android/pandora/test/asha_test.py
165
166[gatt-test-example-code]: https://r.android.com/2470981
167
168[asha-central-tests-spec]: https://docs.google.com/document/d/1HmihYrjBGDys4FAEgh05e5BHPMxNUiz8QIOYez9GT1M/edit?usp=sharing
169