xref: /nrf52832-nimble/nordic/nrfx/drivers/include/nrfx_nfct.h (revision 150812a83cab50279bd772ef6db1bfaf255f2c5b)

/*
 * Copyright (c) 2018, 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 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 the copyright holder nor the names of its
 *    contributors may be used to endorse or promote products derived from this
 *    software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER 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 NRFX_NFCT_H__
#define NRFX_NFCT_H__

#include <nrfx.h>
#include <hal/nrf_nfct.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @defgroup nrfx_nfct NFCT driver
 * @{
 * @ingroup nrf_nfct
 * @brief   Near Field Communication Tag (NFCT) peripheral driver.
 */

#define NRFX_NFCT_NFCID1_SINGLE_SIZE 4u  ///< Length of single-size NFCID1.
#define NRFX_NFCT_NFCID1_DOUBLE_SIZE 7u  ///< Length of double-size NFCID1.
#define NRFX_NFCT_NFCID1_TRIPLE_SIZE 10u ///< Length of triple-size NFCID1.

#define NRFX_NFCT_NFCID1_DEFAULT_LEN NRFX_NFCT_NFCID1_DOUBLE_SIZE ///< Default length of NFC ID. */

/**
 * @brief NFCT hardware states.
 */
typedef enum
{
    NRFX_NFCT_STATE_DISABLED  = NRF_NFCT_TASK_DISABLE,  ///< NFC Tag is disabled (no sensing of an external NFC field).
    NRFX_NFCT_STATE_SENSING   = NRF_NFCT_TASK_SENSE,    ///< NFC Tag is sensing whether there is an external NFC field.
    NRFX_NFCT_STATE_ACTIVATED = NRF_NFCT_TASK_ACTIVATE, ///< NFC Tag is powered-up (see @ref nrfx_nfct_active_state_t for possible substates).
} nrfx_nfct_state_t;

/**
 * @brief NFC tag states, when NFCT hardware is activated.
 *
 * @details These states are substates of the @ref NRFX_NFCT_STATE_ACTIVATED state.
 */
typedef enum
{
    NRFX_NFCT_ACTIVE_STATE_IDLE  = NRF_NFCT_TASK_GOIDLE,  ///< NFC Tag is activated and idle (not selected by a reader).
    NRFX_NFCT_ACTIVE_STATE_SLEEP = NRF_NFCT_TASK_GOSLEEP, ///< NFC Tag is sleeping.
    NRFX_NFCT_ACTIVE_STATE_DEFAULT,                       ///< NFC Tag is either sleeping or idle, depending on the previous state before being selected by a poller.
} nrfx_nfct_active_state_t;

/**
 * @brief NFCT driver event types, passed to the upper-layer callback function
 *        provided during the initialization.
 */
typedef enum
{
    NRFX_NFCT_EVT_FIELD_DETECTED = NRF_NFCT_INT_FIELDDETECTED_MASK, ///< External NFC field is detected.
    NRFX_NFCT_EVT_FIELD_LOST     = NRF_NFCT_INT_FIELDLOST_MASK,     ///< External NFC Field is lost.
    NRFX_NFCT_EVT_SELECTED       = NRF_NFCT_INT_SELECTED_MASK,      ///< Tag was selected by the poller.
    NRFX_NFCT_EVT_RX_FRAMESTART  = NRF_NFCT_INT_RXFRAMESTART_MASK,  ///< Data frame reception started.
    NRFX_NFCT_EVT_RX_FRAMEEND    = NRF_NFCT_INT_RXFRAMEEND_MASK,    ///< Data frame is received.
    NRFX_NFCT_EVT_TX_FRAMESTART  = NRF_NFCT_INT_TXFRAMESTART_MASK,  ///< Data frame transmission started.
    NRFX_NFCT_EVT_TX_FRAMEEND    = NRF_NFCT_INT_TXFRAMEEND_MASK,    ///< Data frame is transmitted.
    NRFX_NFCT_EVT_ERROR          = NRF_NFCT_INT_ERROR_MASK,         ///< Error occurred in an NFC communication.
} nrfx_nfct_evt_id_t;

/**
 * @brief NFCT timing-related error types.
 */
typedef enum
{
    NRFX_NFCT_ERROR_FRAMEDELAYTIMEOUT, ///< No response frame was transmitted to the poller in the transmit window.
    NRFX_NFCT_ERROR_NUM,               ///< Total number of possible errors.
} nrfx_nfct_error_t;

/**
 * @brief NFCT driver parameter types.
 */
typedef enum
{
    NRFX_NFCT_PARAM_ID_FDT,     ///< NFC-A Frame Delay Time parameter.
    NRFX_NFCT_PARAM_ID_SEL_RES, ///< Value of the 'Protocol' field in the NFC-A SEL_RES frame.
    NRFX_NFCT_PARAM_ID_NFCID1,  ///< NFC-A NFCID1 setting (NFC tag identifier).
} nrfx_nfct_param_id_t;

/**
 * @brief NFCID1 descriptor.
 */
typedef struct
{
    uint8_t const * p_id;    ///< NFCID1 data.
    uint8_t         id_size; ///< NFCID1 size.
} nrfx_nfct_nfcid1_t;

/**
 * @brief NFCT driver parameter descriptor.
 */
typedef struct
{
    nrfx_nfct_param_id_t   id;               ///< Type of parameter.
    union
    {
        uint32_t           fdt;              ///< NFC-A Frame Delay Time. Filled when nrfx_nfct_param_t::id is @ref NRFX_NFCT_PARAM_ID_FDT.
        uint8_t            sel_res_protocol; ///< NFC-A value of the 'Protocol' field in the SEL_RES frame. Filled when nrfx_nfct_param_t::id is @ref NRFX_NFCT_PARAM_ID_SEL_RES.
        nrfx_nfct_nfcid1_t nfcid1;           ///< NFC-A NFCID1 value (tag identifier). Filled when nrfx_nfct_param_t::id is @ref NRFX_NFCT_PARAM_ID_NFCID1.
    } data;
} nrfx_nfct_param_t;

/**
 * @brief NFCT driver RX/TX buffer descriptor.
 */
typedef struct
{
    uint32_t        data_size; ///< RX/TX buffer size.
    uint8_t const * p_data;    ///< RX/TX buffer.
} nrfx_nfct_data_desc_t;

/**
 * @brief Structure used to describe the @ref NRFX_NFCT_EVT_RX_FRAMEEND event type.
 */
typedef struct
{
    uint32_t              rx_status; ///< RX error status.
    nrfx_nfct_data_desc_t rx_data;   ///< RX buffer.
} nrfx_nfct_evt_rx_frameend_t;

/**
 * @brief Structure used to describe the @ref NRFX_NFCT_EVT_TX_FRAMESTART event type.
 */
typedef struct
{
    nrfx_nfct_data_desc_t tx_data; ///< TX buffer.
} nrfx_nfct_evt_tx_framestart_t;

/**
 * @brief Structure used to describe the @ref NRFX_NFCT_EVT_ERROR event type.
 */
typedef struct
{
    nrfx_nfct_error_t reason; ///< Reason for error.
} nrfx_nfct_evt_error_t;

/**
 * @brief NFCT driver event.
 */
typedef struct
{
    nrfx_nfct_evt_id_t evt_id;                       ///< Type of event.
    union
    {
        nrfx_nfct_evt_rx_frameend_t   rx_frameend;   ///< End of the RX frame data. Filled when nrfx_nfct_evt_t::evt_id is @ref NRFX_NFCT_EVT_RX_FRAMEEND.
        nrfx_nfct_evt_tx_framestart_t tx_framestart; ///< Start of the TX frame data. Filled when nrfx_nfct_evt_t::evt_id is @ref NRFX_NFCT_EVT_TX_FRAMESTART.
        nrfx_nfct_evt_error_t         error;         ///< Error data. Filled when nrfx_nfct_evt_t::evt_id is @ref NRFX_NFCT_EVT_ERROR.
    } params;
} nrfx_nfct_evt_t;

/**
 * @brief Callback descriptor to pass events from the NFCT driver to the upper layer.
 *
 * @param[in] p_event Pointer to the event descriptor.
 */
typedef void (*nrfx_nfct_handler_t)(nrfx_nfct_evt_t const * p_event);

/**
 * @brief NFCT driver configuration structure.
 */
typedef struct
{
    uint32_t            rxtx_int_mask; ///< Mask for enabling RX/TX events. Indicate which events must be forwarded to the upper layer by using @ref nrfx_nfct_evt_id_t. By default, no events are enabled. */
    nrfx_nfct_handler_t cb;            ///< Callback.
} nrfx_nfct_config_t;

/**
 * @brief Function for initializing the NFCT driver.
 *
 * @param[in] p_config  Pointer to the NFCT driver configuration structure.
 *
 * @retval NRFX_SUCCESS             If the NFCT driver was initialized successfully.
 * @retval NRFX_ERROR_INVALID_STATE If the NFCT driver is already initialized.
 */
nrfx_err_t nrfx_nfct_init(nrfx_nfct_config_t const * p_config);

/**
 * @brief Function for uninitializing the NFCT driver.
 *
 * After uninitialization, the instance is in disabled state.
 */
void nrfx_nfct_uninit(void);

/**
 * @brief Function for starting the NFC subsystem.
 *
 * After this function completes, NFC readers are able to detect the tag.
 */
void nrfx_nfct_enable(void);

/**
 * @brief Function for disabling the NFCT driver.
 *
 * After this function returns, NFC readers are no longer able to connect
 * to the tag.
 */
void nrfx_nfct_disable(void);

/**
 * @brief Function for checking whether the external NFC field is present in the range of the tag.
 *
 * @retval true  If the NFC field is present.
 * @retval false If no NFC field is present.
 */
bool nrfx_nfct_field_check(void);

/**
 * @brief Function for preparing the NFCT driver for receiving an NFC frame.
 *
 * @param[in] p_rx_data  Pointer to the RX buffer.
 */
void nrfx_nfct_rx(nrfx_nfct_data_desc_t const * p_rx_data);

/**
 * @brief Function for transmitting an NFC frame.
 *
 * @param[in] p_tx_data   Pointer to the TX buffer.
 * @param[in] delay_mode  Delay mode of the NFCT frame timer.
 *
 * @retval NRFX_SUCCESS              If the operation was successful.
 * @retval NRFX_ERROR_INVALID_LENGTH If the TX buffer size is invalid.
 */
nrfx_err_t nrfx_nfct_tx(nrfx_nfct_data_desc_t const * p_tx_data,
                        nrf_nfct_frame_delay_mode_t   delay_mode);

/**
 * @brief Function for moving the NFCT to a new state.
 *
 * @note  The HFCLK must be running before activating the NFCT with
 *        @ref NRFX_NFCT_STATE_ACTIVATED.
 *
 * @param[in] state  The required state.
 */
void nrfx_nfct_state_force(nrfx_nfct_state_t state);

/**
 * @brief Function for moving the NFCT to a new initial substate within @ref NRFX_NFCT_STATE_ACTIVATED.
 *
 * @param[in] sub_state  The required substate.
 */
void nrfx_nfct_init_substate_force(nrfx_nfct_active_state_t sub_state);

/**
 * @brief Function for setting the NFC communication parameter.
 *
 * @note Parameter validation for length and acceptable values.
 *
 * @param[in] p_param  Pointer to parameter descriptor.
 *
 * @retval NRFX_SUCCESS             If the operation was successful.
 * @retval NRFX_ERROR_INVALID_PARAM If the parameter data is invalid.
 */
nrfx_err_t nrfx_nfct_parameter_set(nrfx_nfct_param_t const * p_param);

/**
 * @brief Function for getting default bytes for NFCID1.
 *
 * @param[in,out] p_nfcid1_buff    In:  empty buffer for data;
 *                                 Out: buffer with the NFCID1 default data. These values
 *                                      can be used to fill the Type 2 Tag Internal Bytes.
 * @param[in]     nfcid1_buff_len  Length of the NFCID1 buffer.
 *
 * @retval NRFX_SUCCESS              If the operation was successful.
 * @retval NRFX_ERROR_INVALID_LENGTH If length of the NFCID buffer is different than
 *                                   @ref NRFX_NFCT_NFCID1_SINGLE_SIZE,
 *                                   @ref NRFX_NFCT_NFCID1_DOUBLE_SIZE, or
 *                                   @ref NRFX_NFCT_NFCID1_TRIPLE_SIZE.
 */
nrfx_err_t nrfx_nfct_nfcid1_default_bytes_get(uint8_t * const p_nfcid1_buff,
                                              uint32_t        nfcid1_buff_len);

/**
 * @brief Function for enabling the automatic collision resolution.
 *
 * @details As defined by the NFC Forum Digital Protocol Technical Specification (and ISO 14443-3),
 *          the automatic collision resolution is implemented in the NFCT hardware.
 *          This function allows enabling and disabling this feature.
 */
void nrfx_nfct_autocolres_enable(void);

/**
 * @brief Function for disabling the automatic collision resolution.
 *
 * @details See also details in @ref nrfx_nfct_autocolres_enable.
 */
void nrfx_nfct_autocolres_disable(void);


void nrfx_nfct_irq_handler(void);


/** @} */

#ifdef __cplusplus
}
#endif


/**
 * @defgroup nrfx_nfct_fixes NFCT driver fixes and workarounds
 * @{
 * @ingroup nrf_nfct
 * @brief Fixes for hardware-related anomalies.
 *
 * If you are using the nRF52832 chip, the workarounds for the following anomalies are applied:
 * - 79. NFCT: A false EVENTS_FIELDDETECTED event occurs after the field is lost.
 * - 116. NFCT does not release HFCLK when switching from ACTIVATED to SENSE mode.
 * To implement the first workaround, an instance of NRF_TIMER is used. After the NFC field is detected,
 * the timing module periodically polls its state to determine when the field is turned off.
 * To implement the second workaround, power reset is used to release the clock acquired by NFCT
 * after the field is turned off. Note that the NFCT register configuration is restored to defaults.
 *
 * If you are using the nRF52840 chip, rev. Engineering A, the workarounds for the following anomalies
 * are applied:
 * - 98. NFCT: The NFCT is not able to communicate with the peer.
 * - 116. NFCT does not release HFCLK when switching from ACTIVATED to SENSE mode.
 * - 144. NFCT: Not optimal NFC performance
 *
 * If you are using the nRF52840 chip, rev. 1, or rev. Engineering B or C, the workarounds for the following
 * anomalies are applied:
 * - 190. NFCT: Event FIELDDETECTED can be generated too early.
 * To implement this workaround, an instance of NRF_TIMER is used. After the NFC field is detected,
 * the timing module measures the necessary waiting period after which NFCT can be activated.
 * This debouncing technique is used to filter possible field instabilities.
 *
 * The application of the implemented workarounds for the nRF52840 chip is determined at runtime and depends
 * on the chip variant.
 *
 * The current code contains a patch for the anomaly 25 (NFCT: Reset value of
 * SENSRES register is incorrect), so that the module now works on Windows Phone.
 * @}
 */

#endif // NRFX_NFCT_H__