1# Interacting with Nanoapps from Client Code
2
3[TOC]
4
5Code that interacts with a nanoapp, for example within an Android app, is known
6as the *client* of the nanoapp. There are two ways to interact with nanoapps
7from the host (application processor): (1) Java (above the Context Hub HAL, from
8the Android framework or an APK), and (2) native vendor code (beneath the
9Context Hub HAL). Most clients, especially those with a UI component, should use
10the Java method, unless a vendor-partition native implementation is required
11(e.g. if interacting with a nanoapp is used to implement a different HAL, or if
12communication with other beneath-HAL modules is required).
13
14Interaction between nanoapps and clients occur through a flexible message
15passing interface. Refer to the Nanoapp Developer Guide for recommendations on
16how to design a protocol for use with a nanoapp.
17
18## Java APIs
19
20CHRE is exposed to Android apps holding the appropriate permissions through the
21[ContextHubManager](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/hardware/location/ContextHubManager.java)
22and the associated
23[ContextHubClient](https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/hardware/location/ContextHubClient.java)
24system APIs.
25
26To use the above APIs, your application must have access to the
27`ACCESS_CONTEXT_HUB` permission, which is restricted to `signature|privileged`.
28This permission must be declared in the app’s [Android
29Manifest](https://developer.android.com/guide/topics/manifest/uses-permission-element),
30and is only granted to APKs that are signed with the same key as the platform
31(“signature” scope) or are preinstalled in the privileged apps folder *and* are
32present on the [privileged permission
33whitelist](https://source.android.com/devices/tech/config/perms-whitelist).
34
35The recommended flow for Java nanoapp client code is as follows:
36
371. Retrieve the ContextHubManager object via
38   `Context.getSystemService(ContextHubManager.class)` - this will produce a
39   valid handle if the device supports `FEATURE_CONTEXT_HUB` as indicated by
40   `PackageManager.hasSystemFeature()`
412. Retrieve a reference to a Context Hub via
42   `ContextHubManager.getContextHubs()`
433. Confirm that the nanoapp is loaded and retrieve its version number by calling
44   `ContextHubManager.queryNanoApps()`
454. If the nanoapp was found, create a `ContextHubClient` object through
46   `ContextHubManager.createClient()`. This can be used to communicate with your
47   nanoapp, and receive notifications of system events like reset. Note that the
48   `createClient()` API supports two modes of operation, which define how events
49   and data are passed to the client: direct callback with
50   `ContextHubClientCallback` (requires a persistent process), or
51   `PendingIntent` with `ContextHubIntentEvent` (can start an app’s process when
52   an event occurs). To send messages to the nanoapp, use
53   `ContextHubClient.sendMessageToNanoApp()`.
54
55## Vendor Native
56
57Depending on the details of the platform implementation, you may also be able to
58interact with CHRE directly, beneath the Context Hub HAL, by using socket IPC as
59exposed by the CHRE daemon reference implementation. This approach has some
60advantages, like being able to interact with system nanoapps that are not
61exposed at the Java level, and it can be used with other low-level beneath-HAL
62code. However, it is not suitable for use from native code within an Android
63app.
64
65See `host/common/test/chre_test_client.cc` for an example of how to use this
66interface. Note that SELinux configuration is generally required to whitelist
67access to the CHRE socket.
68
69