1 /* 2 * Copyright (c) 2018 - 2020, Nordic Semiconductor ASA 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, this 9 * list of conditions and the following disclaimer. 10 * 11 * 2. Redistributions in binary form must reproduce the above copyright 12 * notice, this list of conditions and the following disclaimer in the 13 * documentation and/or other materials provided with the distribution. 14 * 15 * 3. Neither the name of the copyright holder nor the names of its 16 * contributors may be used to endorse or promote products derived from this 17 * software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 20 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 23 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29 * POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 #ifndef NRFX_NFCT_H__ 33 #define NRFX_NFCT_H__ 34 35 #include <nrfx.h> 36 #include <hal/nrf_nfct.h> 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /** 43 * @defgroup nrfx_nfct NFCT driver 44 * @{ 45 * @ingroup nrf_nfct 46 * @brief Near Field Communication Tag (NFCT) peripheral driver. 47 */ 48 49 #define NRFX_NFCT_NFCID1_SINGLE_SIZE 4u ///< Length of single-size NFCID1. 50 #define NRFX_NFCT_NFCID1_DOUBLE_SIZE 7u ///< Length of double-size NFCID1. 51 #define NRFX_NFCT_NFCID1_TRIPLE_SIZE 10u ///< Length of triple-size NFCID1. 52 53 #define NRFX_NFCT_NFCID1_DEFAULT_LEN NRFX_NFCT_NFCID1_DOUBLE_SIZE ///< Default length of NFC ID. */ 54 55 /** @brief NFCT hardware states. */ 56 typedef enum 57 { 58 NRFX_NFCT_STATE_DISABLED = NRF_NFCT_TASK_DISABLE, ///< NFC Tag is disabled (no sensing of an external NFC field). 59 NRFX_NFCT_STATE_SENSING = NRF_NFCT_TASK_SENSE, ///< NFC Tag is sensing whether there is an external NFC field. 60 NRFX_NFCT_STATE_ACTIVATED = NRF_NFCT_TASK_ACTIVATE, ///< NFC Tag is powered-up (see @ref nrfx_nfct_active_state_t for possible substates). 61 } nrfx_nfct_state_t; 62 63 /** 64 * @brief NFC tag states, when NFCT hardware is activated. 65 * 66 * @details These states are substates of the @ref NRFX_NFCT_STATE_ACTIVATED state. 67 */ 68 typedef enum 69 { 70 NRFX_NFCT_ACTIVE_STATE_IDLE = NRF_NFCT_TASK_GOIDLE, ///< NFC Tag is activated and idle (not selected by a reader). 71 NRFX_NFCT_ACTIVE_STATE_SLEEP = NRF_NFCT_TASK_GOSLEEP, ///< NFC Tag is sleeping. 72 NRFX_NFCT_ACTIVE_STATE_DEFAULT, ///< NFC Tag is either sleeping or idle, depending on the previous state before being selected by a poller. 73 } nrfx_nfct_active_state_t; 74 75 /** 76 * @brief NFCT driver event types, passed to the upper-layer callback function 77 * provided during the initialization. 78 */ 79 typedef enum 80 { 81 NRFX_NFCT_EVT_FIELD_DETECTED = NRF_NFCT_INT_FIELDDETECTED_MASK, ///< External NFC field is detected. 82 NRFX_NFCT_EVT_FIELD_LOST = NRF_NFCT_INT_FIELDLOST_MASK, ///< External NFC Field is lost. 83 NRFX_NFCT_EVT_SELECTED = NRF_NFCT_INT_SELECTED_MASK, ///< Tag was selected by the poller. 84 NRFX_NFCT_EVT_RX_FRAMESTART = NRF_NFCT_INT_RXFRAMESTART_MASK, ///< Data frame reception started. 85 NRFX_NFCT_EVT_RX_FRAMEEND = NRF_NFCT_INT_RXFRAMEEND_MASK, ///< Data frame is received. 86 NRFX_NFCT_EVT_TX_FRAMESTART = NRF_NFCT_INT_TXFRAMESTART_MASK, ///< Data frame transmission started. 87 NRFX_NFCT_EVT_TX_FRAMEEND = NRF_NFCT_INT_TXFRAMEEND_MASK, ///< Data frame is transmitted. 88 NRFX_NFCT_EVT_ERROR = NRF_NFCT_INT_ERROR_MASK, ///< Error occurred in an NFC communication. 89 } nrfx_nfct_evt_id_t; 90 91 /** @brief NFCT timing-related error types. */ 92 typedef enum 93 { 94 NRFX_NFCT_ERROR_FRAMEDELAYTIMEOUT, ///< No response frame was transmitted to the poller in the transmit window. 95 NRFX_NFCT_ERROR_NUM, ///< Total number of possible errors. 96 } nrfx_nfct_error_t; 97 98 /** @brief NFCT driver parameter types. */ 99 typedef enum 100 { 101 NRFX_NFCT_PARAM_ID_FDT, ///< NFC-A Frame Delay Time parameter. 102 NRFX_NFCT_PARAM_ID_SEL_RES, ///< Value of the 'Protocol' field in the NFC-A SEL_RES frame. 103 NRFX_NFCT_PARAM_ID_NFCID1, ///< NFC-A NFCID1 setting (NFC tag identifier). 104 } nrfx_nfct_param_id_t; 105 106 /** @brief NFCID1 descriptor. */ 107 typedef struct 108 { 109 uint8_t const * p_id; ///< NFCID1 data. 110 uint8_t id_size; ///< NFCID1 size. 111 } nrfx_nfct_nfcid1_t; 112 113 /** @brief NFCT driver parameter descriptor. */ 114 typedef struct 115 { 116 nrfx_nfct_param_id_t id; ///< Type of parameter. 117 union 118 { 119 uint32_t fdt; ///< NFC-A Frame Delay Time. Filled when nrfx_nfct_param_t.id is @ref NRFX_NFCT_PARAM_ID_FDT. 120 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. 121 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. 122 } data; ///< Union to store parameter data. 123 } nrfx_nfct_param_t; 124 125 /** @brief NFCT driver RX/TX buffer descriptor. */ 126 typedef struct 127 { 128 uint32_t data_size; ///< RX/TX buffer size. 129 uint8_t const * p_data; ///< RX/TX buffer. 130 } nrfx_nfct_data_desc_t; 131 132 /** @brief Structure used to describe the @ref NRFX_NFCT_EVT_RX_FRAMEEND event type. */ 133 typedef struct 134 { 135 uint32_t rx_status; ///< RX error status. 136 nrfx_nfct_data_desc_t rx_data; ///< RX buffer. 137 } nrfx_nfct_evt_rx_frameend_t; 138 139 /** @brief Structure used to describe the @ref NRFX_NFCT_EVT_TX_FRAMESTART event type. */ 140 typedef struct 141 { 142 nrfx_nfct_data_desc_t tx_data; ///< TX buffer. 143 } nrfx_nfct_evt_tx_framestart_t; 144 145 /** @brief Structure used to describe the @ref NRFX_NFCT_EVT_ERROR event type. */ 146 typedef struct 147 { 148 nrfx_nfct_error_t reason; ///< Reason for error. 149 } nrfx_nfct_evt_error_t; 150 151 /** @brief NFCT driver event. */ 152 typedef struct 153 { 154 nrfx_nfct_evt_id_t evt_id; ///< Type of event. 155 union 156 { 157 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. 158 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. 159 nrfx_nfct_evt_error_t error; ///< Error data. Filled when nrfx_nfct_evt_t.evt_id is @ref NRFX_NFCT_EVT_ERROR. 160 } params; ///< Union to store event data. 161 } nrfx_nfct_evt_t; 162 163 /** 164 * @brief Callback descriptor to pass events from the NFCT driver to the upper layer. 165 * 166 * @param[in] p_event Pointer to the event descriptor. 167 * 168 * @note @ref NRFX_NFCT_EVT_FIELD_DETECTED and @ref NRFX_NFCT_EVT_FIELD_LOST are generated only on field state transitions, 169 * i.e. there will be no multiple events of the same type (out of the 2 mentioned) coming in a row. 170 */ 171 typedef void (*nrfx_nfct_handler_t)(nrfx_nfct_evt_t const * p_event); 172 173 /** @brief NFCT driver configuration structure. */ 174 typedef struct 175 { 176 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. */ 177 nrfx_nfct_handler_t cb; ///< Callback. 178 } nrfx_nfct_config_t; 179 180 /** 181 * @brief Function for initializing the NFCT driver. 182 * 183 * @param[in] p_config Pointer to the NFCT driver configuration structure. 184 * 185 * @retval NRFX_SUCCESS The NFCT driver was initialized successfully. 186 * @retval NRFX_ERROR_INVALID_STATE The NFCT driver is already initialized. 187 */ 188 nrfx_err_t nrfx_nfct_init(nrfx_nfct_config_t const * p_config); 189 190 /** 191 * @brief Function for uninitializing the NFCT driver. 192 * 193 * After uninitialization, the instance is in disabled state. 194 */ 195 void nrfx_nfct_uninit(void); 196 197 /** 198 * @brief Function for starting the NFC subsystem. 199 * 200 * After this function completes, NFC readers are able to detect the tag. 201 */ 202 void nrfx_nfct_enable(void); 203 204 /** 205 * @brief Function for disabling the NFCT driver. 206 * 207 * After this function returns, NFC readers are no longer able to connect 208 * to the tag. 209 */ 210 void nrfx_nfct_disable(void); 211 212 /** 213 * @brief Function for checking whether the external NFC field is present in the range of the tag. 214 * 215 * @retval true The NFC field is present. 216 * @retval false No NFC field is present. 217 */ 218 bool nrfx_nfct_field_check(void); 219 220 /** 221 * @brief Function for preparing the NFCT driver for receiving an NFC frame. 222 * 223 * @param[in] p_rx_data Pointer to the RX buffer. 224 */ 225 void nrfx_nfct_rx(nrfx_nfct_data_desc_t const * p_rx_data); 226 227 /** 228 * @brief Function for transmitting an NFC frame. 229 * 230 * @param[in] p_tx_data Pointer to the TX buffer. 231 * @param[in] delay_mode Delay mode of the NFCT frame timer. 232 * 233 * @retval NRFX_SUCCESS The operation was successful. 234 * @retval NRFX_ERROR_INVALID_LENGTH The TX buffer size is invalid. 235 */ 236 nrfx_err_t nrfx_nfct_tx(nrfx_nfct_data_desc_t const * p_tx_data, 237 nrf_nfct_frame_delay_mode_t delay_mode); 238 239 /** 240 * @brief Function for moving the NFCT to a new state. 241 * 242 * @note The HFCLK must be running before activating the NFCT with 243 * @ref NRFX_NFCT_STATE_ACTIVATED. 244 * 245 * @param[in] state The required state. 246 */ 247 void nrfx_nfct_state_force(nrfx_nfct_state_t state); 248 249 /** 250 * @brief Function for moving the NFCT to a new initial substate within @ref NRFX_NFCT_STATE_ACTIVATED. 251 * 252 * @param[in] sub_state The required substate. 253 */ 254 void nrfx_nfct_init_substate_force(nrfx_nfct_active_state_t sub_state); 255 256 /** 257 * @brief Function for setting the NFC communication parameter. 258 * 259 * @note Parameter validation for length and acceptable values. 260 * 261 * @param[in] p_param Pointer to parameter descriptor. 262 * 263 * @retval NRFX_SUCCESS The operation was successful. 264 * @retval NRFX_ERROR_INVALID_PARAM The parameter data is invalid. 265 */ 266 nrfx_err_t nrfx_nfct_parameter_set(nrfx_nfct_param_t const * p_param); 267 268 /** 269 * @brief Function for getting default bytes for NFCID1. 270 * 271 * @note This function cannot be used from the non-secure code because it requires access 272 * to FICR registers. 273 * 274 * @param[in,out] p_nfcid1_buff In: empty buffer for data; 275 * Out: buffer with the NFCID1 default data. These values 276 * can be used to fill the Type 2 Tag Internal Bytes. 277 * @param[in] nfcid1_buff_len Length of the NFCID1 buffer. 278 * 279 * @retval NRFX_SUCCESS The operation was successful. 280 * @retval NRFX_ERROR_INVALID_LENGTH Length of the NFCID buffer is different than 281 * @ref NRFX_NFCT_NFCID1_SINGLE_SIZE, 282 * @ref NRFX_NFCT_NFCID1_DOUBLE_SIZE, or 283 * @ref NRFX_NFCT_NFCID1_TRIPLE_SIZE. 284 */ 285 nrfx_err_t nrfx_nfct_nfcid1_default_bytes_get(uint8_t * const p_nfcid1_buff, 286 uint32_t nfcid1_buff_len); 287 288 /** 289 * @brief Function for enabling the automatic collision resolution. 290 * 291 * @details As defined by the NFC Forum Digital Protocol Technical Specification (and ISO 14443-3), 292 * the automatic collision resolution is implemented in the NFCT hardware. 293 * This function allows enabling and disabling this feature. 294 */ 295 void nrfx_nfct_autocolres_enable(void); 296 297 /** 298 * @brief Function for disabling the automatic collision resolution. 299 * 300 * @details See also details in @ref nrfx_nfct_autocolres_enable. 301 */ 302 void nrfx_nfct_autocolres_disable(void); 303 304 /** @} */ 305 306 307 void nrfx_nfct_irq_handler(void); 308 309 310 #ifdef __cplusplus 311 } 312 #endif 313 314 315 /** 316 * @defgroup nrfx_nfct_fixes NFCT driver fixes and workarounds 317 * @{ 318 * @ingroup nrf_nfct 319 * @brief Fixes for hardware-related anomalies. 320 * 321 * If you are using the nRF52832 chip, the workarounds for the following anomalies are applied: 322 * - 79. NFCT: A false EVENTS_FIELDDETECTED event occurs after the field is lost. 323 * - 116. NFCT does not release HFCLK when switching from ACTIVATED to SENSE mode. 324 * To implement the first workaround, an instance of NRF_TIMER is used. After the NFC field is detected, 325 * the timing module periodically polls its state to determine when the field is turned off. 326 * To implement the second workaround, power reset is used to release the clock acquired by NFCT 327 * after the field is turned off. Note that the NFCT register configuration is restored to defaults. 328 * 329 * If you are using the nRF52833, nRF52840 or nRF5340 chips, the workarounds for the following 330 * anomalies are applied: 331 * - 190. NFCT: Event FIELDDETECTED can be generated too early. 332 * To implement this workaround, an instance of NRF_TIMER is used. After the NFC field is detected, 333 * the timing module measures the necessary waiting period after which NFCT can be activated. 334 * This debouncing technique is used to filter possible field instabilities. 335 * 336 * The current code contains a patch for the anomaly 25 (NFCT: Reset value of 337 * SENSRES register is incorrect), so that the module now works on Windows Phone. 338 * @} 339 */ 340 341 #endif // NRFX_NFCT_H__ 342