owner-nrf52sdk/nRF5_SDK_17.0.2/components/libraries/csense/nrf_csense.h

/**
 * Copyright (c) 2016 - 2020, Nordic Semiconductor ASA
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form, except as embedded into a Nordic
 *    Semiconductor ASA integrated circuit in a product or a software update for
 *    such product, must reproduce the above copyright notice, this list of
 *    conditions and the following disclaimer in the documentation and/or other
 *    materials provided with the distribution.
 *
 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
 *    contributors may be used to endorse or promote products derived from this
 *    software without specific prior written permission.
 *
 * 4. This software, with or without modification, must only be used with a
 *    Nordic Semiconductor ASA integrated circuit.
 *
 * 5. Any software provided in binary form under this license must not be reverse
 *    engineered, decompiled, modified and/or disassembled.
 *
 * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 */
#ifndef NRF_CSENSE_H__
#define NRF_CSENSE_H__

#include <stdint.h>
#include "nrf.h"
#include "sdk_errors.h"
#include "app_timer.h"
#include "nrf_drv_csense.h"
#include "nrf_csense_macros.h"
#include "app_util.h"

/** @file
 *
 * @defgroup nrf_csense Capacitive sensor library
 * @{
 * @ingroup app_common
 *
 * @brief Module for using the capacitive sensor library with support for many instances of sliders, wheels, and buttons.
 */

/**
 * @brief Macro for returning the address of a variable.
 */
#define NRF_CSENSE_GET_INSTANCE_ID(instance) (&instance)

/**
 * @brief Statically allocate memory for the instance of a capacitive sensor.
 *
 * @param[in,out] name          Name of the capacitive sensor instance that will be created.
 * @param[in] p1                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 */
#define NRF_CSENSE_BUTTON_DEF(name, p1) NRF_CSENSE_INTERNAL_BUTTON_DEF(name, p1)

/**
 * @brief Macro for creating a 2-pad slider instance.
 *
 * @param[in,out] name          Name of the capacitive sensor instance that will be created.
 * @param[in] steps_no          Number of relative pads. It means that the slider in its handler will give values (1, steps_no).
 * @param[in] p1                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p2                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 */
#define NRF_CSENSE_SLIDER_2_DEF(name, steps_no, p1, p2) NRF_CSENSE_INTERNAL_SLIDER_2_DEF(name, steps_no, p1, p2)

/**
 * @brief Macro for creating a 3-pad slider instance.
 *
 * @param[in,out] name          Name of the capacitive sensor instance that will be created.
 * @param[in] steps_no          Number of relative pads. It means that the slider in its handler will give values (1, steps_no).
 * @param[in] p1                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p2                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p3                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 */
#define NRF_CSENSE_SLIDER_3_DEF(name, steps_no, p1, p2, p3) NRF_CSENSE_INTERNAL_SLIDER_3_DEF(name, steps_no, p1, p2, p3)

/**
 * @brief Macro for creating a 4-pad slider instance.
 *
 * @param[in,out] name          Name of the capacitive sensor instance that will be created.
 * @param[in] steps_no          Number of relative pads. It means that the slider in its handler will give values (1, steps_no).
 * @param[in] p1                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p2                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p3                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p4                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 */
#define NRF_CSENSE_SLIDER_4_DEF(name, steps_no, p1, p2, p3, p4) NRF_CSENSE_INTERNAL_SLIDER_4_DEF(name, steps_no, p1, p2, p3, p4)

/**
 * @brief Macro for creating a 5-pad slider instance.
 *
 * @param[in,out] name          Name of the capacitive sensor instance that will be created.
 * @param[in] steps_no          Number of relative pads. It means that the slider in its handler will give values (1, steps_no).
 * @param[in] p1                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p2                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p3                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p4                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p5                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 */
#define NRF_CSENSE_SLIDER_5_DEF(name, steps_no, p1, p2, p3, p4, p5) NRF_CSENSE_INTERNAL_SLIDER_5_DEF(name, steps_no, p1, p2, p3, p4, p5)

/**
 * @brief Macro for creating a 3-pad wheel instance.
 *
 * @param[in,out] name          Name of the capacitive sensor instance that will be created.
 * @param[in] steps_no          Number of relative pads. It means that the slider in its handler will give values (1, steps_no).
 * @param[in] p1                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p2                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p3                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 */
#define NRF_CSENSE_WHEEL_3_DEF(name, steps_no, p1, p2, p3) NRF_CSENSE_INTERNAL_WHEEL_3_DEF(name, steps_no, p1, p2, p3)

/**
 * @brief Macro for creating a 4-pad wheel instance.
 *
 * @param[in,out] name          Name of the capacitive sensor instance that will be created.
 * @param[in] steps_no          Number of relative pads. It means that the slider in its handler will give values (1, steps_no).
 * @param[in] p1                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p2                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p3                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p4                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 */
#define NRF_CSENSE_WHEEL_4_DEF(name, steps_no, p1, p2, p3, p4) NRF_CSENSE_INTERNAL_WHEEL_4_DEF(name, steps_no, p1, p2, p3, p4)

/**
 * @brief Macro for creating a 5-pad wheel instance.
 *
 * @param[in,out] name          Name of the capacitive sensor instance that will be created.
 * @param[in] steps_no          Number of relative pads. It means that the slider in its handler will give values (1, steps_no).
 * @param[in] p1                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p2                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p3                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p4                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 * @param[in] p5                Pair of two arguments: threshold and analog_input_number. Must be passed as (analog_input_number, threshold).
 */
#define NRF_CSENSE_WHEEL_5_DEF(name, steps_no, p1, p2, p3, p4, p5) NRF_CSENSE_INTERNAL_WHEEL_5_DEF(name, steps_no, p1, p2, p3, p4, p5)

/**
 * @cond (NODOX)
 * @defgroup nrf_csense_internal Auxiliary internal types declarations
 * @brief Module for internal usage inside the library only.
 * @details These definitions are available to the user, but they should not
 * be accessed directly. Use the API to access them.
 * @{
 *
 */

     /*
      * @brief Forward declaration of capacitive sensor instance.
      */
    typedef struct nrf_csense_instance_s nrf_csense_instance_t;

    /*
     * @brief Forward declaration of a capacitive sensor pad.
     */
    typedef struct nrf_csense_pad_s nrf_csense_pad_t;

    /**
     * @brief Structure with pointer to min and max values measured on pads.
     */
    typedef struct
    {
        uint16_t                   max_value;                //!< Max value measured on pads.
        uint16_t                   min_value;                //!< Min value measured on pads.
    }nrf_csense_min_max_t;

    /**
     * @brief Structure with single instance parameters. This can be either a slider or a button.
     */
    struct nrf_csense_instance_s
    {
        nrf_csense_instance_t *     p_next_instance;            //!< Pointer to the next instance.
        nrf_csense_pad_t *          p_nrf_csense_pad;           //!< Pointer to the first pad of the module.
        nrf_csense_min_max_t *      min_max;                    //!< Structure with pointers to min and max values measured on pads.
        uint16_t                    steps;                      //!< Number of relative pads. It means that the slider in its handler will give values (1, steps_no).
        uint8_t                     number_of_pads;             //!< Number of pads that the instance is using.
        bool                        is_active;                  //!< Flag to indicate if the instance is active.
        bool                        is_touched;                 //!< Flag to indicate if the instance is touched.
        void *                      p_context;                  //!< General purpose pointer.
    };

    /* Structure with single pad parameters used for initialization. */
    struct nrf_csense_pad_s
    {
        nrf_csense_pad_t *          p_next_pad;                 //!< Pointer to the next pad.
        uint16_t                    threshold;                  //!< Threshold voltage on pad/time of charging to decide if the pad was touched.
        uint8_t                     pad_index;                  //!< Index of the pad.
        uint8_t                     analog_input_number;        //!< Analog input connected to the pad.
    };

/** @}
 * @endcond
 */

/**
 * @brief Enum for nrf_csense events.
 */
typedef enum
{
    NRF_CSENSE_BTN_EVT_PRESSED,                                 //!< Event for pad pressed.
    NRF_CSENSE_BTN_EVT_RELEASED,                                //!< Event for pad released.
    NRF_CSENSE_SLIDER_EVT_PRESSED,                              //!< Event for pad pressed.
    NRF_CSENSE_SLIDER_EVT_RELEASED,                             //!< Event for pad released.
    NRF_CSENSE_SLIDER_EVT_DRAGGED,                              //!< Event for pad dragged.
}nrf_csense_evt_type_t;

/**
 * @brief Structure with slider event data including the measured step.
 */
typedef struct
{
    uint16_t step;                                              //!< Measured step.
} nrf_csense_slider_evt_t;

/**
 * @brief Event data union for nrf_csense events.
 */
typedef union
{
    nrf_csense_slider_evt_t slider;                             //!< Structure with slider event data including the measured step.
} nrf_csense_evt_param_t;

/**
 * @brief Structure with event parameters.
 */
typedef struct
{
    nrf_csense_evt_type_t       nrf_csense_evt_type;            //!< Type of event.
    nrf_csense_instance_t *     p_instance;                     //!< Pointer to instance.
    nrf_csense_evt_param_t      params;                         //!< Event data union for nrf_csense events.
}nrf_csense_evt_t;

/**
 * @brief Capacitive sensor handler type.
 */
typedef void (* nrf_csense_event_handler_t)(nrf_csense_evt_t * p_evt);

/**
 * @brief Function for setting a handler of the instance.
 *
 * @param [in] p_instance                           Pointer to the instance whose steps are going to be changed.
 * @param [in] p_context                            General purpose pointer. Will be passed to the callback function.
 */
__STATIC_INLINE void nrf_csense_instance_context_set(nrf_csense_instance_t * const p_instance, void * p_context)
{
    p_instance->p_context = p_context;
}

/**
 * @brief Function for initializing the module. After initialization, no instances are enabled.
 *
 * @param [in] event_handler                          Event handler for the Capacitive Sensor module.
 * @param [in] ticks                                  Time in app_timer ticks between next conversions.
 *
 * @retval NRF_ERROR_INVALID_PARAM                    If invalid parameter was provided.
 * @retval NRF_ERROR_INVALID_STATE                    If one of the used modules is in invalid state.
 * @retval NRF_ERROR_INTERNAL                         If an error occured while initializing one of the modules used by the capacitive sensor library.
 * @retval NRF_SUCCESS                                If the module was initialized successfully.
 */
ret_code_t nrf_csense_init(nrf_csense_event_handler_t event_handler, uint32_t ticks);

/**
 * @brief Function for uninitializing the module.
 *
 * @return Values returned by @ref nrf_drv_csense_uninit and @ref app_timer_stop.
 */
ret_code_t nrf_csense_uninit(void);

/**
 * @brief Function for adding an instance of capacitive sensor to a linked list.
 *
 * The function calls @ref nrf_csense_enable to enable the instance that was added to the linked list.
 *
 * @param [in] p_instance                            Pointer to the capacitive sensor instance. It is saved by the module and is used whenever the instance is referred.
 *
 * @return Values returned by @ref nrf_csense_enable.
 */
ret_code_t nrf_csense_add(nrf_csense_instance_t * const p_instance);

/**
 * @brief Function for enabling a single instance.
 *
 * @param [in,out] p_instance                        Pointer to the capacitive sensor instance. It is saved by the module and is used whenever the instance is referred.
 *
 * @return Values returned by @ref app_timer_start.
 */
ret_code_t nrf_csense_enable(nrf_csense_instance_t * const p_instance);

/**
 * @brief Function for disabling an instance.
 *
 * @param [in] p_instance                              Pointer to the instance to be disabled.
 *
 * @retval NRF_ERROR_INVALID_PARAM                     If the instance was already disabled.
 * @retval NRF_SUCCESS                                 If the instance was disabled successfully.
 */
ret_code_t nrf_csense_disable(nrf_csense_instance_t * const p_instance);

/**
 * @brief Function for setting ticks between next measurements.
 *
 * @param [in] ticks                                 New time between conversions in app_timer ticks.
 *
 * @retval NRF_ERROR_BUSY                             If the capacitive sensor was busy.
 * @retval NRF_ERROR_INVALID_PARAM                    If an invalid parameter was provided.
 * @retval NRF_ERROR_INVALID_STATE                    If app_timer was in invalid state.
 * @retval NRF_SUCCESS                                If ticks were set successfully.
 */
ret_code_t nrf_csense_ticks_set(uint32_t ticks);

/**
 * @brief Function for setting steps of an instance.
 *
 * Note that you have do disable the instance before you can change its number of steps.
 *
 * @param [in] p_instance                           Pointer to the instance whose steps are going to be changed.
 * @param [in] steps                                New steps value.
 *
 * @retval NRF_ERROR_BUSY                           If the capacitive sensor was busy.
 * @retval NRF_SUCCESS                              If steps were set successfully.
 */
ret_code_t nrf_csense_steps_set(nrf_csense_instance_t  * const p_instance, uint16_t steps);


/** @} */

#endif //NRF_CSENSE_H__