# Nanoapp Developer Guide [TOC] Since CHRE is an open platform, anyone can write nanoapps. However, deploying to a device requires cooperation of the device manufacturer, because CHRE is a security-sensitive trusted environment, similar to other low-level firmware, and it typically has tight resource constraints. This section assumes you have a basic understanding of what a nanoapp is (if not, see the Nanoapp Overview section), and provides some simple instructions to help you get started with developing your own nanoapp. ## Getting Started When starting a new nanoapp, it’s helpful to start with the skeleton of an existing nanoapp. The simplest example can be found at `apps/hello_world`. Start by copying this folder to the location where you will develop the nanoapp - it can be outside of the `system/chre` project, for example in a vendor-specific Git repository in the `vendor/` folder of the Android tree. If you don’t plan to use this nanoapp as a *static nanoapp* (see the Nanoapp Overview for details), remove the `hello_world.mk` file and delete the code blocks wrapped in `#ifdef CHRE_NANOAPP_INTERNAL`. Rename the remaining files to match your nanoapp. ### Picking a Nanoapp ID Nanoapps are uniquely identified by a 64-bit number. The most significant 5 bytes of this number are the vendor identifier, and the remaining bytes identify the nanoapp within the vendor’s namespace. The vendor identifier is usually devised from an ASCII representation of the vendor’s name, for example Google uses 0x476F6F676C (“Googl”). The remaining portion of the ID is typically just an incrementing value for each nanoapp. Refer to `system/chre/chre_api/include/chre_api/chre/common.h` and `util/include/chre/util/nanoapp/app_id.h` for some examples and utilities. Be sure to pick a unique nanoapp ID when creating a new nanoapp. ### Picking a Language CHRE guarantees support for nanoapps written in C11 or C++17, though not all standard library functions are supported (see below for details). For a device-specific nanoapp, additional programming languages/versions *may* be supported, but this can impact portability. ### Building the Nanoapp Binary While it’s possible to build a nanoapp with a different build system, just as it is for the CHRE framework, it’s recommended to use the common build system included in this project, as it makes it easy to support a variety of target platforms. The rest of this section assumes you are using the CHRE build system to create a non-static nanoapp. Update the `Makefile` in your nanoapp’s directory to: * Define nanoapp metadata, including: * `NANOAPP_NAME`: sets the output filename of the binary * `NANOAPP_ID`: 64-bit identifier, in hexadecimal format * `NANOAPP_VERSION`: 32-bit version, in hexadecimal format (see versioning section below) * `NANOAPP_NAME_STRING`, `NANOAPP_VENDOR_STRING`: human-readable strings for the name of the nanoapp and vendor, respectively * `NANOAPP_IS_SYSTEM_NANOAPP`: 0 or 1 (see Nanoapp Overview) * Populate `COMMON_SRCS` with the C or C++ source files to compile * Populate `COMMON_CFLAGS` with compiler flags, like additional include paths * Include any additional `.mk` files for vendor extensions, etc. before `app.mk` Refer to `build/nanoapp/app.mk` for full details. The nanoapp can then be built using a command like ``OPT_LEVEL=s make -j`nproc` `` (see the CHRE Framework Build System section for details on build targets), which will produce build artifacts at `out//.*`. ### Loading onto a Device Exact steps to load a nanoapp binary can vary by device, but for developing a preloaded nanoapp, this typically involves the following steps: * Perform any needed post-processing of the nanoapp binary to permit it to be loaded (such as signing with a development or production key) * Write the binary to the device’s storage (for example, using `adb push`) * Update `preloaded_nanoapps.json` or other configuration as needed, so that CHRE knows to load the new nanoapp * Restart CHRE to reload all nanoapps, including the new one ## Nanoapp Versioning While not strictly enforced, nanoapps are recommended to follow the convention of the CHRE framework and use [Semantic Versioning](http://semver.org). In the case of a nanoapp, the key versioned “API” is considered the interface between the client and nanoapp. Nanoapp versions are represented as a 32-bit integer, where the most significant byte represents the major version, followed by one byte for the minor version, and two bytes for the patch version. ## Using the CHRE API The CHRE API is the key interface between each nanoapp and the underlying system. Refer to the extensive API documentation in the header files at `chre_api/include`, as well as usage of the APIs by sample nanoapps. The CHRE API is normally included via `#include `. ## Utility Libraries Some source and header files under `util` are specifically designed to aid in nanoapp development, and others were initially created for use in the framework but can be leveraged by nanoapps as well. In general, any source and header file there that does **not** include a header from `chre/platform` (part of the internal CHRE framework implementation details) may be used by a nanoapp, and files within a subdirectory called `nanoapp` are specifically targeted for use by nanoapps. This includes `util/include/chre/util/nanoapp/log.h` (meant to be included via `#include “chre/util/nanoapp/log.h”`), which provides macros like `LOGD` which can be conditionally compiled, include a configurable prefix to help identify the sender, and suppress double promotion warnings. The utilities library also includes a number of container classes, which are meant to mimic the C++ standard library, but with a lightweight, CHRE-compatible implementation. This includes: * `chre::DynamicVector`: an `std::vector` analogue * `chre::FixedSizeVector`: accessed like `std::vector`, but only uses statically allocated memory * `chre::ArrayQueue`: can be used as a circular buffer * `chre::UniquePtr`: an `std::unique_ptr` analogue * `chre::Optional`: an analogue to `std::optional` from C++17 * `chre::Singleton`: a container for a statically allocated object with explicit initialization and deinitialization (e.g. enables construction of a global object to be deferred until `nanoappStart()`) ## Interacting with the Host Nanoapps can interact with one or more clients on the host (applications processor) through a flexible binary message-passing interface. For simple interactions in cases where the lowest memory footprint is desired, using only the built-in message type field with no additional payload, or passing hand-rolled packed C-style structures (e.g. using Java’s ByteBuffer on the client side) can work, though this approach can be error-prone. Using a well-defined serialization format, such as Protocol Buffers (see the Using NanoPB section below) or FlatBuffers, is usually a better choice. There are a few common tips to keep in mind when interacting with the host: 1. Nanoapp binaries are usually updated independently from client code - watch out for compatibility issues arising from changes to the messaging protocol, and use a serialization format like Protocol Buffers if possible. 2. Nanoapp messages to the host always wake it up if it’s asleep. If this is not required, nanoapps are encouraged to batch their messages and opportunistically send when the host wakes up for another reason (see `chreConfigureHostSleepStateEvents()`). 3. After calling `chreSendMessageToHostEndpoint()`, ownership of the memory associated with the message payload is assigned to the framework. Do not modify it until the free callback is invoked. 4. Nanoapp messaging should be unicast, unless broadcast messaging is strictly necessary. Design the messaging protocol such that the client initiates communication, and save the host endpoint ID in the nanoapp to use when sending replies. ## Interacting with Other Nanoapps While most nanoapps are only concerned with providing functionality for a single client on the host, it is possible for a nanoapp to provide services to other nanoapps within CHRE. Similar to how nanoapps communicate with the host by passing *messages*, nanoapps can communicate with one another by passing *events* with arbitrary binary payload. Event IDs starting in the range `CHRE_EVENT_FIRST_USER_VALUE` are reserved for this purpose. Typically a nanoapp creates a *nanoapp client library* which other nanoapps can include, which presents a simple, expressive API, and handles the implementation details of passing events to the target nanoapp, and interpreting incoming messages. Refer to the functions defined in `chre/event.h` for more details. ## Using TensorFlow Lite for Microcontrollers Many nanoapps use machine learning techniques to accomplish their functionality. The CHRE build system has built-in support for integrating [TensorFlow Lite for Microcontrollers](https://www.tensorflow.org/lite/microcontrollers) (TFLM) into a nanoapp. Sync the TFLM sources, set `TFLM_PATH`, and define `USE_TFLM=true` in your Makefile - see `apps/tflm_demo/README` for details and an example nanoapp. ## Using Nanopb The CHRE build system has integrated support for using [Nanopb](https://jpa.kapsi.fi/nanopb/) to provide support for [Protocol Buffers](https://developers.google.com/protocol-buffers) in a nanoapp. To integrate this into your nanoapp’s Makefile, first install and configure dependencies: * Sync the Nanopb source tree (e.g. from a release on GitHub), and define the `NANOPB_PREFIX` environment variable to its path * Download and install the protobuf compiler `protoc` and make it available in your `$PATH`, or set the `PROTOC` environment variable Then in your nanoapp’s Makefile, populate `NANOPB_SRCS` with the desired `.proto` file(s). That’s it! Though some additional options/parameters are available - see `build/nanopb.mk` for details. ## Nanoapp Development Best Practices Even though CHRE aims to provide an environment for low-power and low-latency contextual signal processing, these two are often conflicting goals. In addition, CHRE is usually implemented in a resource-constrained environment with limited memory available. As it requires collaboration from all nanoapps to optimize their resource usage for CHRE to live up to its promises, some best practices are provided here as guidance for nanoapp development. ### Memory Efficiency #### Avoid dynamic heap allocations where possible As CHRE is designed in a resource-constrained environment, there is no guarantee runtime memory allocation will succeed. In addition, dynamic heap allocations make it difficult to estimate the memory usage in advance. Developers are therefore encouraged to use static allocations where possible. #### Be careful of stack usage Unlike Linux’s default stack of 8MB that scales dynamically, CHRE only has a fixed stack of limited size (8KB is typical). Ensure you keep any allocations to an absolute minimum and any large allocations should go out of scope prior to navigating deeper into a stack. #### Prefer in-place algorithms Prefer in-place algorithms over out-of-place ones where efficiency allows to minimize additional memory requirements. ### Power Efficiency #### Be opportunistic when possible Examples include: * If the host is asleep and doesn’t need to act on a nanoapp message immediately, buffer until it wakes up for another reason. * Make a WiFi on-demand scan request only if the WiFi scan monitor doesn’t provide a scan result in time. #### Batch data at the source where possible By batching data at the source, it reduces the data delivery frequency and helps keep CHRE asleep and improve power efficiency. Clients should make data requests with the longest batch interval that still meets the latency requirement. Examples include: * Make a sensor data request with the longest ``latency`` possible. * Make an audio data request with the longest ``deliveryInterval`` possible. ### Standard Library Usage CHRE implementations are only required to support a subset of the standard C and C++ libraries, as well as language features requiring run-time support. This list is carefully considered to ensure memory usage and implementation complexity are minimized. Following these principles, some features are explicitly excluded due to their memory and/or extensive OS-level dependencies, and others because they are supplanted by more suitable CHRE-specific APIs. While not meant to be an exhaustive list and some platforms may differ, the following standard library features are not meant to be used by nanoapps: * C++ exceptions and run-time type information (RTTI) * Standard library multi-threading support, including C++ library headers ` `, ``, ``, ``, etc. * C and C++ Standard Input/Output libraries * C++ Standard Template Library (STL) * C++ Standard Regular Expressions library * Dynamic memory allocation (`malloc`, `calloc`, `realloc`, `free`), and libraries that inherently use dynamic allocation, such as `std::unique_ptr` * Localization and Unicode character support * Date and time libraries * Functions that modify normal program flow, including ``, ``, `abort`, `std::terminate`, etc. * Accessing the host environment, including `system`, `getenv`, etc. * POSIX or other libraries not included in the C11 or C++17 language standards In many cases, equivalent functionality is available from CHRE API functions and/or utility libraries. For example, `chreLog` may be used for debug logging, where a more traditional program might use `printf`. ## Debugging Similar to the framework debugging methods, each has its nanoapp counterpart to support nanoapp debugging through the framework. Please see the Framework Debugging section for reference/context. ### Logging CHRE API `chreLog()` logs information into the system as part of the CHRE logs. Normally this appears in logcat, but some platforms may route it to a different logging system (a future version of the CHRE API is expected to make logcat logging mandatory). Nanoapps are encouraged to `#include "chre/util/nanoapp/log.h"` and use the `LOGx()` macros defined therein, which requires these additional steps: * Define `LOG_TAG` to a short, human-readable identifier for your nanoapp, as this gets prepended to logs * Define `NANOAPP_MINIMUM_LOG_LEVEL` to a `CHRE_LOG_LEVEL_\*` value in your Makefile for compile time log level filtering - it’s recommended to use `CHRE_LOG_LEVEL_DEBUG` for development, and `CHRE_LOG_LEVEL_INFO` for release See also the Framework Debugging section for more general guidance on logging in CHRE. ### Debug Dump When running on CHRE v1.4+, nanoapps can also append information to the CHRE framework debug dump. Nanoapps interested in using this capability should call `chreConfigureDebugDumpEvent(true)` in `nanoappStart()`, then when `CHRE_EVENT_DEBUG_DUMP` is received in `nanoappHandleEvent()`, use `chreDebugDumpLog()` to write human-readable output to the debug dump, which appears in bug reports under the Context Hub HAL debug section. In the reference CHRE framework implementation, nanoapp debug dumps have the nanoapp name and ID automatically prepended, for example: ``` Nanoapp debug dumps: DebugDumpWorld 0x0123456789000011: Debug event count: 2 Total dwell time: 92 us ``` Refer to the associated CHRE API documentation and Framework Debugging section for more information. ### CHRE_ASSERT To help catch programming errors or other unexpected conditions, nanoapps can use the `CHRE_ASSERT` macro provided by `#include "chre/util/nanoapp/assert.h"`. Keep in mind that if one nanoapp encounters an assertion failure, it most likely will cause a reset of the processor where CHRE is running, impacting other functionality (though this can vary by platform). Therefore, assertions are only recommended to be used during development. Define the `CHRE_ASSERTIONS_ENABLED` variable in your Makefile to `false` to disable assertions at compile time.