.. _andcore: Core Concepts ======================================= Target of this section is to provide a high level description of the core concepts behind the Atooma environment. Focus will be on **Modules** and their inner structure, with emphasis on how they can be used for building **Rules** to be executed. Modules ------------------------------ **Modules** are sets of related functions packed into self-consistent software units, that are used for creating and executing rules. For example, ``SMS`` module includes functionalities for receiving, sending and managing messages, while ``WiFi`` module allows to control device WiFi features. .. Every module includes a *version number*, reflecting changes on module structure (e.g. new features added, features removed due to deprecation and so on). This information is extremely important because it allows to define conditions for safely exchanging rules between different client versions. Some modules may be not available on all devices. For example, if device lacks of ``NFC`` hardware, the corresponding module won’t be shown and, as a consequence, all rules including ``NFC`` module won't be executed. Each module defines a set of components among the following: :ref:`corevaluetype` , :ref:`coretrigger` , :ref:`coreconditionchecker` and :ref:`coreperformer`. All of them are described more in details in the following sections. .. _corevaluetype: Value Type ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Value Type** are components defining data types managed by the module. ``STRING``, ``BOOLEAN``, ``NUMBER`` and ``DATE`` are examples of basic value types defined in ``CORE`` module. Regardless of their internal representation, all value types must have a serialized format, allowing them to be exchanged as byte sequences, through a convention that must be specified by the value type definition itself. .. Provider ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Providers** are components that provide values on demand to rules requiring them. For example, ``SYSTEM_TIME`` is a provider defined by ``Core`` module, that returns value of current system clock. .. _coretrigger: Trigger ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Triggers** are rule activators. They are in charge of executing rules when specific events occur. Each trigger can include parameters, allowing to configure rule activation in some conditions only. For example, ``SMS`` module defines a trigger ``INCOMING`` that is activated when an ``SMS`` is received. It's possible to filter events by monitoring only messages coming from a specific *sender*. When activated, a trigger can inject values into the rule exectution context. For example ``INCOMING`` trigger of ``SMS`` module provides a set of information like message *content*, *sender* and so on. .. _coreconditionchecker: Condition Checker ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Condition Checkers** are boolean functions accepting one or more parameters. They are used in conditional part of the rule for checking values. One example for ``WiFi`` module is ``CONNECTED``, that returns *true* if device is connected to ``WiFi`` with *SSID* name specified as parameter. .. _coreperformer: Performer ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Performers** are components executing actions. For example, ``Facebook`` module has a performer ``POST_ON_WALL``, allowing to post a message provided in input on a friend's wall. Also performers can inject values into the rule execution context. Purpose is making such data avilable for the following performers. .. note:: Rule performers are not executed in parallel. They are treated as a pipeline. That's why each element can receive parameters in input and produce parameters in output. .. _rules: Rules ------------------------------ **Rules** are programs defining actions to execute when a specific event occurs, according to an *if-do paradigm* where *if part* is made by one trigger and contains up to four condition checkers, while *do part* contains up to five perfomers. .. figure:: _static/img/rule.jpg :width: 600 px :alt: Atooma rules paradigm :align: center In practice, *if-do parts* are contained in what is defined as **rule body**. In addition to body, all rules include a **header**, declaring all basic rule information: * A **title** for the rule (max 50 chars). * An optional **description** of the rule (max 250 chars). * The list of **modules** (with corresponding min version) that are needed for executing the rule. * An optional list of **properties** to be used as parameters for the rule, each one including an **identifier**, a **value type** and a **value**. Following sections provide advanced details on the structure of `Trigger`_, `Condition Checker`_ and `Performer`_ definitions. .. _Trigger: core.html#coretriggerdef .. _Condition Checker: core.html#coreconditioncheckerdef .. _Performer: core.html#coreperformerdef .. _coretriggerdef: Trigger Definition ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Trigger definition provides the configuration for the rule trigger. It includes three elements: * The **module** implementing the trigger. * The **identifier** of the trigger. * The eventual **list of parameters** required by the trigger. .. note:: Since rules are activated by triggers it's essential for them to define it. .. _coreconditioncheckerdef: Condition Checkers Definition ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Condition checker definition provides the configuration for a condition to be verified within the execution context of the rule after trigger activation. It includes four elements: * The **module** implementing the condition checker. * The **identifier** of the condition checker. * The eventual **list of parameters** required by the condition checker. * The eventual **inversion of the boolean** result of the condition evaluation (``NOT`` operator). .. note:: A rule can have up to four condition checkers, to be verified according to their declaration order. As soon as a condition evaluation returns *false*, the rule execution is interrupted. As a result, all subsequent conditions won't be evaluated and performers won't be executed. .. _coreperformerdef: Performers Definition ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Performer definition provides the configuration for a performer to be executed in case trigger is activated and all conditions are verified. It includes three elements: * The **module** implementing the performer. * The **identifier** of the performer. * The eventual **list of parameters** required by the performer. .. note:: All rules must include at least one performer. Parameters, Properties and Injected Values ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Defining trigger, condition checkers and performers may often require to use parameters, each one including an **identifier** and a **value type**. There are four possible value sources for parameters: * **Rule properties** - Properties declared within rule definition can be used as static parameter values. * **Injection from trigger** - When activating the execution of a rule, a trigger can inject one or more variables into the rule execution context. Of course, such variables can be used by performers only. * **Injection from performer** - During their execution, performers can inject one or more variables into the rule execution context. A variable coming from a performer can be used only after the execution of the performer that generated it. * **External providers** - Static functions can be used for dynamically generating values for rule variables. Of course depending on component, only some parameter sources can be used: * **Triggers** - Parameters can be rule properties or values coming from external providers. In particular, every time a trigger parameter is read from an external provider with rule already active, the rule itself is reloaded into Atooma engine. * **Condition Checkers** - Parameters can be rule properties, values coming from external providers or values injected from trigger. * **Performers** - Parameters can be rule properties, values coming from external providers, values injected from trigger or values injected from other performers previously executed. Data Analysis ------------------------------ On top of **Rules Engine**, Resonance SDK comes with a set of API allowing to determine user attitudes and providing to developers suitable functions for retrieving interesting user-related data. By analyzing data coming from user devices (from smartphones to connected wearables), Resonance SDK is able to answer to questions like: * Where does user live? * Where does user work? * Which is user favorite restaurant? * Does user most commonly take car or bus? * Which rules / smart actions can be more suitable for users? ... and much more. .. figure:: _static/img/data_analysis.png :width: 650 px :alt: Subsystems for Data Analysis :align: center Resonance subsystem for Data Analysis is made of three main functional blocks: * **Data Collector** - Allows to retrieve data from devices and to send them to Backend. * **Backend** - Receive data from devices, store and analyze them for determining regularities. * **Advisor** - Provide high level functions for exposing to clients all relevant information determined by Backend. Resonance Data Collector is the most important functional block for Data Analysis, having following responsibilities: * **Retrieving** data from user devices, adopting strategies aimed to reduce the amount of useless information by increasing sample rate in presence of more complex activities, of course with an eye to battery drain. * **Pre-processing** data for keeping just significant information. * **Packaging** valuable information into a structured format, ready to be delivered to Resonance Backend * **Deliverying** data to Resonance Backend, minimizing network load.