1 /* 2 * Copyright (c) 2018 - 2023, 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 <hal/nrf_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 } nrfx_nfct_config_t; 183 184 /** 185 * @brief Function for initializing the NFCT driver. 186 * 187 * @param[in] p_config Pointer to the NFCT driver configuration structure. 188 * 189 * @retval NRFX_SUCCESS The NFCT driver was initialized successfully. 190 * @retval NRFX_ERROR_INVALID_STATE The NFCT driver is already initialized. 191 */ 192 nrfx_err_t nrfx_nfct_init(nrfx_nfct_config_t const * p_config); 193 194 /** 195 * @brief Function for uninitializing the NFCT driver. 196 * 197 * After uninitialization, the instance is in disabled state. 198 */ 199 void nrfx_nfct_uninit(void); 200 201 /** 202 * @brief Function for starting the NFC subsystem. 203 * 204 * After this function completes, NFC readers are able to detect the tag. 205 */ 206 void nrfx_nfct_enable(void); 207 208 /** 209 * @brief Function for disabling the NFCT driver. 210 * 211 * After this function returns, NFC readers are no longer able to connect 212 * to the tag. 213 */ 214 void nrfx_nfct_disable(void); 215 216 /** 217 * @brief Function for checking whether the external NFC field is present in the range of the tag. 218 * 219 * @retval true The NFC field is present. 220 * @retval false No NFC field is present. 221 */ 222 bool nrfx_nfct_field_check(void); 223 224 /** 225 * @brief Function for preparing the NFCT driver for receiving an NFC frame. 226 * 227 * @param[in] p_rx_data Pointer to the RX buffer. 228 */ 229 void nrfx_nfct_rx(nrfx_nfct_data_desc_t const * p_rx_data); 230 231 /** 232 * @brief Function for transmitting an NFC frame. 233 * 234 * @param[in] p_tx_data Pointer to the TX buffer. 235 * @param[in] delay_mode Delay mode of the NFCT frame timer. 236 * 237 * @retval NRFX_SUCCESS The operation was successful. 238 * @retval NRFX_ERROR_INVALID_LENGTH The TX buffer size is invalid. 239 * @retval NRFX_ERROR_BUSY Driver is already transferring. 240 */ 241 nrfx_err_t nrfx_nfct_tx(nrfx_nfct_data_desc_t const * p_tx_data, 242 nrf_nfct_frame_delay_mode_t delay_mode); 243 244 /** 245 * @brief Function for transmitting an NFC frame with a specified number of bits. 246 * 247 * @param[in] p_tx_data Pointer to the TX buffer. Unlike in @ref nrfx_nfct_tx, @p data_size is 248 * used as the number of bits to transmit, rather than bytes. 249 * @param[in] delay_mode Delay mode of the NFCT frame timer. 250 * 251 * @retval NRFX_SUCCESS The operation was successful. 252 * @retval NRFX_ERROR_INVALID_LENGTH The TX buffer size is invalid. 253 * @retval NRFX_ERROR_BUSY Driver is already transferring. 254 */ 255 nrfx_err_t nrfx_nfct_bits_tx(nrfx_nfct_data_desc_t const * p_tx_data, 256 nrf_nfct_frame_delay_mode_t delay_mode); 257 258 /** 259 * @brief Function for moving the NFCT to a new state. 260 * 261 * @note The HFCLK must be running before activating the NFCT with 262 * @ref NRFX_NFCT_STATE_ACTIVATED. 263 * 264 * @param[in] state The required state. 265 */ 266 void nrfx_nfct_state_force(nrfx_nfct_state_t state); 267 268 /** 269 * @brief Function for moving the NFCT to a new initial substate within @ref NRFX_NFCT_STATE_ACTIVATED. 270 * 271 * @param[in] sub_state The required substate. 272 */ 273 void nrfx_nfct_init_substate_force(nrfx_nfct_active_state_t sub_state); 274 275 /** 276 * @brief Function for setting the NFC communication parameter. 277 * 278 * @note Parameter validation for length and acceptable values. 279 * 280 * @param[in] p_param Pointer to parameter descriptor. 281 * 282 * @retval NRFX_SUCCESS The operation was successful. 283 * @retval NRFX_ERROR_INVALID_PARAM The parameter data is invalid. 284 */ 285 nrfx_err_t nrfx_nfct_parameter_set(nrfx_nfct_param_t const * p_param); 286 287 /** 288 * @brief Function for getting default bytes for NFCID1. 289 * 290 * @note This function cannot be used from the non-secure code because it requires access 291 * to FICR registers. 292 * 293 * @param[in,out] p_nfcid1_buff In: empty buffer for data; 294 * Out: buffer with the NFCID1 default data. These values 295 * can be used to fill the Type 2 Tag Internal Bytes. 296 * @param[in] nfcid1_buff_len Length of the NFCID1 buffer. 297 * 298 * @retval NRFX_SUCCESS The operation was successful. 299 * @retval NRFX_ERROR_INVALID_LENGTH Length of the NFCID buffer is different than 300 * @ref NRFX_NFCT_NFCID1_SINGLE_SIZE, 301 * @ref NRFX_NFCT_NFCID1_DOUBLE_SIZE, or 302 * @ref NRFX_NFCT_NFCID1_TRIPLE_SIZE. 303 */ 304 nrfx_err_t nrfx_nfct_nfcid1_default_bytes_get(uint8_t * const p_nfcid1_buff, 305 uint32_t nfcid1_buff_len); 306 307 /** 308 * @brief Function for enabling the automatic collision resolution. 309 * 310 * @details As defined by the NFC Forum Digital Protocol Technical Specification (and ISO 14443-3), 311 * the automatic collision resolution is implemented in the NFCT hardware. 312 * This function allows enabling and disabling this feature. 313 */ 314 void nrfx_nfct_autocolres_enable(void); 315 316 /** 317 * @brief Function for disabling the automatic collision resolution. 318 * 319 * @details See also details in @ref nrfx_nfct_autocolres_enable. 320 */ 321 void nrfx_nfct_autocolres_disable(void); 322 323 /** @} */ 324 325 326 void nrfx_nfct_irq_handler(void); 327 328 329 #ifdef __cplusplus 330 } 331 #endif 332 333 334 /** 335 * @defgroup nrfx_nfct_fixes NFCT driver fixes and workarounds 336 * @{ 337 * @ingroup nrf_nfct 338 * @brief Fixes for hardware-related anomalies. 339 * 340 * If you are using the nRF52832 chip, the workarounds for the following anomalies are applied: 341 * - 79. NFCT: A false EVENTS_FIELDDETECTED event occurs after the field is lost. 342 * - 116. NFCT does not release HFCLK when switching from ACTIVATED to SENSE mode. 343 * To implement the first workaround, an instance of NRF_TIMER is used. After the NFC field is detected, 344 * the timing module periodically polls its state to determine when the field is turned off. 345 * To implement the second workaround, power reset is used to release the clock acquired by NFCT 346 * after the field is turned off. Note that the NFCT register configuration is restored to defaults. 347 * 348 * If you are using the nRF52833, nRF52840 or nRF5340 chips, the workarounds for the following 349 * anomalies are applied: 350 * - 190. NFCT: Event FIELDDETECTED can be generated too early. 351 * To implement this workaround, an instance of NRF_TIMER is used. After the NFC field is detected, 352 * the timing module measures the necessary waiting period after which NFCT can be activated. 353 * This debouncing technique is used to filter possible field instabilities. 354 * 355 * The current code contains a patch for the anomaly 25 (NFCT: Reset value of 356 * SENSRES register is incorrect), so that the module now works on Windows Phone. 357 * @} 358 */ 359 360 #endif // NRFX_NFCT_H__ 361
