1# Pandora APIs
2
3Pandora Bluetooth test interfaces provide a common abstraction for Bluetooth
4testing tools to interact with all Bluetooth implementations, exposing all
5standard Bluetooth capabilities over [gRPC](https://grpc.io/).
6
7While all Bluetooth stacks are different in their supported profiles, features,
8and corresponding APIs, the goal of Pandora is to provide a set of unified
9test interfaces which they could all implement, so testing tools can be reused
10and scaled across the entire Bluetooth ecosystem.
11
12## Requirements
13
14Since each Bluetooth stack exposes different APIs, the test interfaces must be
15generic enough and must not rely on any implementation specific behavior.
16However, they must ensure that they provide all the necessary access to the
17existing testing tools. For this reason, the test interfaces are co-designed by
18multiple teams at Google.
19
20The test interfaces must be implemented using [gRPC](https://grpc.io/) services
21and must use [protocol buffers](https://developers.google.com/protocol-buffers)
22as Interface Definition Language (IDL). A Bluetooth stack under test exposing
23such interfaces must thus implement a gRPC server.
24
25The test interfaces definition must follow the [Pandora style guide](
26style-guide.md).
27
28## Abstraction level
29
30**A test interface is defined for each Bluetooth profile (standard or custom)**.
31This allows the Bluetooth stack under test to implement only the test interfaces
32corresponding to its supported profiles. Additional platform/device-specific
33interfaces may also be added if necessary (but should be avoided as much as
34possible).
35
36**The same test interface can be implemented at different levels of a same
37stack**: for example, in Android, the Pandora Bluetooth test interfaces can be
38implemented both on top of Topshim (which is a Rust shim layer just on top of
39the native stack), which is advantageous as tests running at that level can
40apply to ChromeOS as well as Android, or on top of the Android Bluetooth SDK
41(Java) which is advantageous for Android, since the Bluetooth module includes
42both the native stack and the SDK.
43
44![Pandora APIs levels](images/pandora-apis-levels.svg)
45
46## Optional features
47
48As Bluetooth profiles contain optional features, some methods of the test
49interfaces might not be implementable by a specific Bluetooth stack.
50
51Such unimplemented methods must return an [UNIMPLEMENTED](
52https://grpc.github.io/grpc/core/md_doc_statuscodes.html) status code as defined
53by gRPC.
54
55Discovering which features are supported by a Bluetooth stack is not (yet) part
56of the test interfaces as this is already doable via Bluetooth SIG
57[Implementation Conformance Statements (ICS)](
58https://www.bluetooth.com/specifications/qualification-test-requirements/).
59