1Android's Context Hub Runtime Environment (CHRE)
2################################################
3
4Android's context hub enables the use of nanoapps. A single nanoapp has 3 entry points seen in
5`chre_api/chre/nanoapp.h`_:
6
7* A ``nanoappStart`` function used to notify the nanoapp that it is now active.
8* A ``nanoappHandleEvent`` function used to notify the nanoapp tha an event of interest took place.
9* A ``nanoappEnd`` function used to notify the nanoapp that it is now deactivated.
10
11The CHRE connects to several frameworks called Platform Abstraction Layers (PAL)s. Note that
12currently, none of these are implemented for Zephyr, but they are scheduled to be added. These
13frameworks include:
14
15#. *Audio* - a framework allowing nanoapps to get audio events. See `pal/audio.h`_ for API details.
16#. *GNSS* - a framework allowing nanoapps to manage location and measurement sessions. See
17   `pal/gnss.h`_ for API details.
18#. *Sensor* - a framework allowing nanoapps to request changes to sensors configuration get
19   data/bias events. See `pal/sensor.h`_ for API details.
20#. *System* - a framework allowing nanoapps to make common system requests such as logging, clock,
21   and some basic memory allocation/deallocation. See `pal/system.h`_ for API details.
22#. *WiFi* - a framework allowing nanoapps to interact with the on board WiFi. See `pal/wifi.h`_ for
23   API details.
24#. *WWAN* - a framework allowing nanoapps to interact with the WWAN module such as getting the
25   current capabilities and info. See `pal/wwan.h`_ for API details.
26
27Building and expectations
28=========================
29
30To build the sample use the following west command:
31
32.. zephyr-app-commands::
33   :zephyr-app: samples/modules/chre
34   :board: native_sim
35   :goals: build
36
37Once built and run, the sample application should:
38
39#. Print a hello message
40#. Notify that the event loop started via an ``inf`` level log
41#. Notify that a nanoapp was started and assigned an instance/app ID of 1 via a ``dbg`` level log
42#. Print a message saying that the nanoapp's start callback was called
43#. Send an event of type ``1`` and no data to the nanoapp
44#. Notify that the event was processed
45#. Call the ``nanoappEnd`` function of the nanoapp
46#. Print a message notifying that it's not possible to remove a system level nanoapp
47#. Exit the event loop
48
49Roadmap
50=======
51
52#. Add an implementation of the `pal/sensor.h`_ and `pal/system.h`_ to Zephyr. These will be
53   standalone modules that can be used independently of CHRE, but when ``CONFIG_CHRE`` is enabled
54   will also provide an implementation of ``chrePalSensorGetApi()`` and ``struct chrePalSystemApi``.
55#. Add a directory ``chre/nanoapps`` which will host various nanoapps to be used by the Zephyr
56   community. These should each have their own Kconfig to enable them and set the appropriate
57   dependencies. The first nanoapp will be a lid angle calculator which will use 2 accelerometers.
58#. Update the ``overlay.dts`` of this sample application to include 2 emulated accelerometers and
59   configure them to return scripted data.
60#. Run this sample application and watch the nanoapp provide lid angle calculations based on 2
61   accelerometers provided by the sensors PAL framework.
62
63.. _`chre_api/chre/nanoapp.h`: https://cs.android.com/android/platform/superproject/+/master:system/chre/chre_api/include/chre_api/chre/nanoapp.h;drc=7c60a553288d63e6e3370d679803da46dac723a4
64.. _`pal/audio.h`: https://cs.android.com/android/platform/superproject/+/master:system/chre/pal/include/chre/pal/audio.h;l=69;drc=6ca547ad175f80ce9f09f5b7b14fcc6f14565f5c
65.. _`pal/gnss.h`: https://cs.android.com/android/platform/superproject/+/master:system/chre/pal/include/chre/pal/gnss.h;l=152;drc=830255234157cc7afe5201dca19a7fb71ea850fe
66.. _`pal/sensor.h`: https://cs.android.com/android/platform/superproject/+/master:system/chre/pal/include/chre/pal/sensor.h;l=51;drc=23207906add05054a94dfab41b95bcfc39bedfe4
67.. _`pal/system.h`: https://cs.android.com/android/platform/superproject/+/master:system/chre/pal/include/chre/pal/system.h;l=49;drc=6ca547ad175f80ce9f09f5b7b14fcc6f14565f5c
68.. _`pal/wifi.h`: https://cs.android.com/android/platform/superproject/+/master:system/chre/pal/include/chre/pal/wifi.h;l=153;drc=b673b80ed98e1b6e6360bee4ba98e2cd8f4e0935
69.. _`pal/wwan.h`: https://cs.android.com/android/platform/superproject/+/master:system/chre/pal/include/chre/pal/wwan.h;l=69;drc=629361a803cb305c8575b41614e6e071e7141a03
70