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