1 /* 2 * Copyright (c) 2018, 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 /** 56 * @brief NFCT hardware states. 57 */ 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 /** 94 * @brief NFCT timing-related error types. 95 */ 96 typedef enum 97 { 98 NRFX_NFCT_ERROR_FRAMEDELAYTIMEOUT, ///< No response frame was transmitted to the poller in the transmit window. 99 NRFX_NFCT_ERROR_NUM, ///< Total number of possible errors. 100 } nrfx_nfct_error_t; 101 102 /** 103 * @brief NFCT driver parameter types. 104 */ 105 typedef enum 106 { 107 NRFX_NFCT_PARAM_ID_FDT, ///< NFC-A Frame Delay Time parameter. 108 NRFX_NFCT_PARAM_ID_SEL_RES, ///< Value of the 'Protocol' field in the NFC-A SEL_RES frame. 109 NRFX_NFCT_PARAM_ID_NFCID1, ///< NFC-A NFCID1 setting (NFC tag identifier). 110 } nrfx_nfct_param_id_t; 111 112 /** 113 * @brief NFCID1 descriptor. 114 */ 115 typedef struct 116 { 117 uint8_t const * p_id; ///< NFCID1 data. 118 uint8_t id_size; ///< NFCID1 size. 119 } nrfx_nfct_nfcid1_t; 120 121 /** 122 * @brief NFCT driver parameter descriptor. 123 */ 124 typedef struct 125 { 126 nrfx_nfct_param_id_t id; ///< Type of parameter. 127 union 128 { 129 uint32_t fdt; ///< NFC-A Frame Delay Time. Filled when nrfx_nfct_param_t::id is @ref NRFX_NFCT_PARAM_ID_FDT. 130 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. 131 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. 132 } data; 133 } nrfx_nfct_param_t; 134 135 /** 136 * @brief NFCT driver RX/TX buffer descriptor. 137 */ 138 typedef struct 139 { 140 uint32_t data_size; ///< RX/TX buffer size. 141 uint8_t const * p_data; ///< RX/TX buffer. 142 } nrfx_nfct_data_desc_t; 143 144 /** 145 * @brief Structure used to describe the @ref NRFX_NFCT_EVT_RX_FRAMEEND event type. 146 */ 147 typedef struct 148 { 149 uint32_t rx_status; ///< RX error status. 150 nrfx_nfct_data_desc_t rx_data; ///< RX buffer. 151 } nrfx_nfct_evt_rx_frameend_t; 152 153 /** 154 * @brief Structure used to describe the @ref NRFX_NFCT_EVT_TX_FRAMESTART event type. 155 */ 156 typedef struct 157 { 158 nrfx_nfct_data_desc_t tx_data; ///< TX buffer. 159 } nrfx_nfct_evt_tx_framestart_t; 160 161 /** 162 * @brief Structure used to describe the @ref NRFX_NFCT_EVT_ERROR event type. 163 */ 164 typedef struct 165 { 166 nrfx_nfct_error_t reason; ///< Reason for error. 167 } nrfx_nfct_evt_error_t; 168 169 /** 170 * @brief NFCT driver event. 171 */ 172 typedef struct 173 { 174 nrfx_nfct_evt_id_t evt_id; ///< Type of event. 175 union 176 { 177 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. 178 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. 179 nrfx_nfct_evt_error_t error; ///< Error data. Filled when nrfx_nfct_evt_t::evt_id is @ref NRFX_NFCT_EVT_ERROR. 180 } params; 181 } nrfx_nfct_evt_t; 182 183 /** 184 * @brief Callback descriptor to pass events from the NFCT driver to the upper layer. 185 * 186 * @param[in] p_event Pointer to the event descriptor. 187 */ 188 typedef void (*nrfx_nfct_handler_t)(nrfx_nfct_evt_t const * p_event); 189 190 /** 191 * @brief NFCT driver configuration structure. 192 */ 193 typedef struct 194 { 195 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. */ 196 nrfx_nfct_handler_t cb; ///< Callback. 197 } nrfx_nfct_config_t; 198 199 /** 200 * @brief Function for initializing the NFCT driver. 201 * 202 * @param[in] p_config Pointer to the NFCT driver configuration structure. 203 * 204 * @retval NRFX_SUCCESS If the NFCT driver was initialized successfully. 205 * @retval NRFX_ERROR_INVALID_STATE If the NFCT driver is already initialized. 206 */ 207 nrfx_err_t nrfx_nfct_init(nrfx_nfct_config_t const * p_config); 208 209 /** 210 * @brief Function for uninitializing the NFCT driver. 211 * 212 * After uninitialization, the instance is in disabled state. 213 */ 214 void nrfx_nfct_uninit(void); 215 216 /** 217 * @brief Function for starting the NFC subsystem. 218 * 219 * After this function completes, NFC readers are able to detect the tag. 220 */ 221 void nrfx_nfct_enable(void); 222 223 /** 224 * @brief Function for disabling the NFCT driver. 225 * 226 * After this function returns, NFC readers are no longer able to connect 227 * to the tag. 228 */ 229 void nrfx_nfct_disable(void); 230 231 /** 232 * @brief Function for checking whether the external NFC field is present in the range of the tag. 233 * 234 * @retval true If the NFC field is present. 235 * @retval false If no NFC field is present. 236 */ 237 bool nrfx_nfct_field_check(void); 238 239 /** 240 * @brief Function for preparing the NFCT driver for receiving an NFC frame. 241 * 242 * @param[in] p_rx_data Pointer to the RX buffer. 243 */ 244 void 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 If the operation was successful. 253 * @retval NRFX_ERROR_INVALID_LENGTH If the TX buffer size is invalid. 254 */ 255 nrfx_err_t nrfx_nfct_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 If the operation was successful. 283 * @retval NRFX_ERROR_INVALID_PARAM If 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 * @param[in,out] p_nfcid1_buff In: empty buffer for data; 291 * Out: buffer with the NFCID1 default data. These values 292 * can be used to fill the Type 2 Tag Internal Bytes. 293 * @param[in] nfcid1_buff_len Length of the NFCID1 buffer. 294 * 295 * @retval NRFX_SUCCESS If the operation was successful. 296 * @retval NRFX_ERROR_INVALID_LENGTH If length of the NFCID buffer is different than 297 * @ref NRFX_NFCT_NFCID1_SINGLE_SIZE, 298 * @ref NRFX_NFCT_NFCID1_DOUBLE_SIZE, or 299 * @ref NRFX_NFCT_NFCID1_TRIPLE_SIZE. 300 */ 301 nrfx_err_t nrfx_nfct_nfcid1_default_bytes_get(uint8_t * const p_nfcid1_buff, 302 uint32_t nfcid1_buff_len); 303 304 /** 305 * @brief Function for enabling the automatic collision resolution. 306 * 307 * @details As defined by the NFC Forum Digital Protocol Technical Specification (and ISO 14443-3), 308 * the automatic collision resolution is implemented in the NFCT hardware. 309 * This function allows enabling and disabling this feature. 310 */ 311 void nrfx_nfct_autocolres_enable(void); 312 313 /** 314 * @brief Function for disabling the automatic collision resolution. 315 * 316 * @details See also details in @ref nrfx_nfct_autocolres_enable. 317 */ 318 void nrfx_nfct_autocolres_disable(void); 319 320 321 void nrfx_nfct_irq_handler(void); 322 323 324 /** @} */ 325 326 #ifdef __cplusplus 327 } 328 #endif 329 330 331 /** 332 * @defgroup nrfx_nfct_fixes NFCT driver fixes and workarounds 333 * @{ 334 * @ingroup nrf_nfct 335 * @brief Fixes for hardware-related anomalies. 336 * 337 * If you are using the nRF52832 chip, the workarounds for the following anomalies are applied: 338 * - 79. NFCT: A false EVENTS_FIELDDETECTED event occurs after the field is lost. 339 * - 116. NFCT does not release HFCLK when switching from ACTIVATED to SENSE mode. 340 * To implement the first workaround, an instance of NRF_TIMER is used. After the NFC field is detected, 341 * the timing module periodically polls its state to determine when the field is turned off. 342 * To implement the second workaround, power reset is used to release the clock acquired by NFCT 343 * after the field is turned off. Note that the NFCT register configuration is restored to defaults. 344 * 345 * If you are using the nRF52840 chip, rev. Engineering A, the workarounds for the following anomalies 346 * are applied: 347 * - 98. NFCT: The NFCT is not able to communicate with the peer. 348 * - 116. NFCT does not release HFCLK when switching from ACTIVATED to SENSE mode. 349 * - 144. NFCT: Not optimal NFC performance 350 * 351 * If you are using the nRF52840 chip, rev. 1, or rev. Engineering B or C, the workarounds for the following 352 * anomalies are applied: 353 * - 190. NFCT: Event FIELDDETECTED can be generated too early. 354 * To implement this workaround, an instance of NRF_TIMER is used. After the NFC field is detected, 355 * the timing module measures the necessary waiting period after which NFCT can be activated. 356 * This debouncing technique is used to filter possible field instabilities. 357 * 358 * The application of the implemented workarounds for the nRF52840 chip is determined at runtime and depends 359 * on the chip variant. 360 * 361 * The current code contains a patch for the anomaly 25 (NFCT: Reset value of 362 * SENSRES register is incorrect), so that the module now works on Windows Phone. 363 * @} 364 */ 365 366 #endif // NRFX_NFCT_H__ 367