Common Application Framework overview

Common Application Framework (CAF) is a set of ready-for-use modules and events built on top of Application Event Manager. Using CAF allows you to have a consistent event-based architecture in your application.

You can check the Common Application Framework preview for a demonstration of how to add ready-for-use and custom CAF modules into an application.

Architecture 

In an event-based application, parts of the application functionality are separated into isolated modules that communicate with each other using Application Event Manager’s events. These events are defined either by CAF or by the application. They are submitted by modules and other modules can subscribe and react to them.

Every CAF module can use additional libraries or drivers. The drivers can be used to communicate with hardware. The module can then broadcast information from the driver using events (for example, the buttons module can submit a button_event on a button press). It can also forward information from application to the driver (for example, the LEDs module can display a given LED effect upon receiving led_event).

In your application, you can use any number of CAF modules together with your own custom modules. Custom modules can use both CAF and custom events. The figure shows an example application that uses one CAF module and one custom module, which has one custom event.

Enabling CAF 

To enable CAF, you need to enable the required Kconfig option and enable and initialize Application Event Manager. You then must submit the first module_state_event, because CAF modules are initialized when they receive a module_state_event that reports MODULE_STATE_READY of the module main.

complete the following steps:

Enable CONFIG_CAF Kconfig option in your project configuration file.
Enable and initialize Application Event Manager. See Configuration for more details.
Submit the first module_state_event:
1. Add the following in your main.c file:
```
#define MODULE main
#include <caf/events/module_state_event.h>
```
2. Call the following function after Application Event Manager is initialized:
```
module_set_state(MODULE_STATE_READY);
```
  This function call submits the required module_state_event.
For an example implementation, see applications/nrf_desktop/src/main.c.

CAF modules 

CAF supports a set of predefined modules. Each of these modules is available for use out of the box and needs to be enabled and configured separately.

There is no limit to the number of modules and events that can be used. However, Application Event Manager sets the limit of event types in an application to 32, and CAF inherits this limitation.

Configuration of CAF modules 

Each module must be configured separately. When configuring CAF modules, you will be asked to use the following configuration methods:

Edit Devicetree Specification (DTS) files - These files reflect the hardware configuration. See Devicetree Guide for more information about the DTS data structure.
Edit _def files - These files contain configuration arrays for the application modules and are specific to CAF.
Select Kconfig options or modify Kconfig files, or both - These reflect the software configuration. See Kconfig - Tips and Best Practices for information about how to configure them.

CAF modules can use all or some of these methods. For example, enabling the CAF: Bluetooth LE advertising module requires enabling Kconfig options and creating a configuration file, while CAF: Bluetooth LE state module can be configured using only Kconfig options.

Adding custom modules 

As part of your application, you can add your own custom modules. These modules can communicate using Application Event Manager’s events. However, if you want to add custom modules that communicate with CAF modules using CAF events, you must make sure that they meet the following requirements:

A custom module must register as Application Event Manager’s listener and subscribe for CAF events that should be handled by that custom module. You can subscribe for a CAF event in the same way as you subscribe for any other Application Event Manager event. See the Registering a module as listener documentation for instructions about how to configure this.
The module must work with module_state_event. It must submit it and react to it.

Note

If you want a module to react to a CAF event, check the event’s documentation for information about the event.