.. zephyr:code-sample:: chre
:name: Android's Context Hub Runtime Environment (CHRE)
Run nanoapps on Zephyr using the Context Hub Runtime Environment (CHRE).
Overview
========
Android's context hub enables the use of nanoapps. A single nanoapp has 3 entry points seen in
`chre_api/chre/nanoapp.h`_:
* A ``nanoappStart`` function used to notify the nanoapp that it is now active.
* A ``nanoappHandleEvent`` function used to notify the nanoapp tha an event of interest took place.
* A ``nanoappEnd`` function used to notify the nanoapp that it is now deactivated.
The CHRE connects to several frameworks called Platform Abstraction Layers (PAL)s. Note that
currently, none of these are implemented for Zephyr, but they are scheduled to be added. These
frameworks include:
#. *Audio* - a framework allowing nanoapps to get audio events. See `pal/audio.h`_ for API details.
#. *GNSS* - a framework allowing nanoapps to manage location and measurement sessions. See
`pal/gnss.h`_ for API details.
#. *Sensor* - a framework allowing nanoapps to request changes to sensors configuration get
data/bias events. See `pal/sensor.h`_ for API details.
#. *System* - a framework allowing nanoapps to make common system requests such as logging, clock,
and some basic memory allocation/deallocation. See `pal/system.h`_ for API details.
#. *WiFi* - a framework allowing nanoapps to interact with the on board WiFi. See `pal/wifi.h`_ for
API details.
#. *WWAN* - a framework allowing nanoapps to interact with the WWAN module such as getting the
current capabilities and info. See `pal/wwan.h`_ for API details.
Building and expectations
=========================
To build the sample use the following west command:
.. zephyr-app-commands::
:zephyr-app: samples/modules/chre
:board: native_sim
:goals: build
Once built and run, the sample application should:
#. Print a hello message
#. Notify that the event loop started via an ``inf`` level log
#. Notify that a nanoapp was started and assigned an instance/app ID of 1 via a ``dbg`` level log
#. Print a message saying that the nanoapp's start callback was called
#. Send an event of type ``1`` and no data to the nanoapp
#. Notify that the event was processed
#. Call the ``nanoappEnd`` function of the nanoapp
#. Print a message notifying that it's not possible to remove a system level nanoapp
#. Exit the event loop
Roadmap
=======
#. Add an implementation of the `pal/sensor.h`_ and `pal/system.h`_ to Zephyr. These will be
standalone modules that can be used independently of CHRE, but when ``CONFIG_CHRE`` is enabled
will also provide an implementation of ``chrePalSensorGetApi()`` and ``struct chrePalSystemApi``.
#. Add a directory ``chre/nanoapps`` which will host various nanoapps to be used by the Zephyr
community. These should each have their own Kconfig to enable them and set the appropriate
dependencies. The first nanoapp will be a lid angle calculator which will use 2 accelerometers.
#. Update the ``overlay.dts`` of this sample application to include 2 emulated accelerometers and
configure them to return scripted data.
#. Run this sample application and watch the nanoapp provide lid angle calculations based on 2
accelerometers provided by the sensors PAL framework.
.. _`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
.. _`pal/audio.h`: https://cs.android.com/android/platform/superproject/+/master:system/chre/pal/include/chre/pal/audio.h;l=69;drc=6ca547ad175f80ce9f09f5b7b14fcc6f14565f5c
.. _`pal/gnss.h`: https://cs.android.com/android/platform/superproject/+/master:system/chre/pal/include/chre/pal/gnss.h;l=152;drc=830255234157cc7afe5201dca19a7fb71ea850fe
.. _`pal/sensor.h`: https://cs.android.com/android/platform/superproject/+/master:system/chre/pal/include/chre/pal/sensor.h;l=51;drc=23207906add05054a94dfab41b95bcfc39bedfe4
.. _`pal/system.h`: https://cs.android.com/android/platform/superproject/+/master:system/chre/pal/include/chre/pal/system.h;l=49;drc=6ca547ad175f80ce9f09f5b7b14fcc6f14565f5c
.. _`pal/wifi.h`: https://cs.android.com/android/platform/superproject/+/master:system/chre/pal/include/chre/pal/wifi.h;l=153;drc=b673b80ed98e1b6e6360bee4ba98e2cd8f4e0935
.. _`pal/wwan.h`: https://cs.android.com/android/platform/superproject/+/master:system/chre/pal/include/chre/pal/wwan.h;l=69;drc=629361a803cb305c8575b41614e6e071e7141a03
f6c232ec2e