[FL-3666] NFC API improvements (#3214)

* drivers: expose st25r3916 driver API * nfc poller: add start with custom callback * mf classic: rework sync API with poller custom start * mf ultralight: rework sync API with poller custom start * iso14443_3a poller: remove unused col res state * nfc: rework nfc poller custom start * mf ultralight: rename sync API * mf classic: rename sync API * iso14443-3a: rename sync API * nfc: remove async prefix in internal functions * nfc: expose internal API * nfc: fix sync api include and docs * targets: fix f18 build * nfc: rework NfcGenericEventEx type * nfc poller: add documentation * iso14443-3a poller: add documentation * felica poller: add documentation * iso14443_3b poller: add documentation * so14443_4a poller: add documentation * iso14443_4b poller: add documentation * iso15693 poller: add documentation * slix poller: add documentation * mf desfire poller: add documentation * mf ultralight poller: fix API and add documentation * mf classic poller: add documentation Co-authored-by: あく <alleteam@gmail.com>
2023-11-15 17:32:45 +09:00
parent d0b9a3a4ae
commit c00776ca22
62 changed files with 1708 additions and 719 deletions
@@ -72,7 +72,7 @@ static NfcCommand iso14443_3a_poller_run(NfcGenericEvent event, void* context) {
    if(nfc_event->type == NfcEventTypePollerReady) {
        if(instance->state != Iso14443_3aPollerStateActivated) {
            Iso14443_3aData data = {};
-            Iso14443_3aError error = iso14443_3a_poller_async_activate(instance, &data);
+            Iso14443_3aError error = iso14443_3a_poller_activate(instance, &data);
            if(error == Iso14443_3aErrorNone) {
                instance->state = Iso14443_3aPollerStateActivated;
                instance->iso14443_3a_event.type = Iso14443_3aPollerEventTypeReady;
@@ -111,7 +111,7 @@ static bool iso14443_3a_poller_detect(NfcGenericEvent event, void* context) {
    furi_assert(instance->state == Iso14443_3aPollerStateIdle);

    if(nfc_event->type == NfcEventTypePollerReady) {
-        Iso14443_3aError error = iso14443_3a_poller_async_activate(instance, NULL);
+        Iso14443_3aError error = iso14443_3a_poller_activate(instance, NULL);
        protocol_detected = (error == Iso14443_3aErrorNone);
    }

@@ -9,34 +9,137 @@
 extern "C" {
 #endif

+/**
+ * @brief Iso14443_3aPoller opaque type definition.
+ */
 typedef struct Iso14443_3aPoller Iso14443_3aPoller;

+/**
+ * @brief Enumeration of possible Iso14443_3a poller event types.
+ */
 typedef enum {
-    Iso14443_3aPollerEventTypeError,
-    Iso14443_3aPollerEventTypeReady,
+    Iso14443_3aPollerEventTypeError, /**< The card was activated by the poller. */
+    Iso14443_3aPollerEventTypeReady, /**< An error occured during activation procedure. */
 } Iso14443_3aPollerEventType;

-typedef struct {
-    Iso14443_3aError error;
+/**
+ * @brief Iso14443_3a poller event data.
+ */
+typedef union {
+    Iso14443_3aError error; /**< Error code indicating card activation fail reason. */
 } Iso14443_3aPollerEventData;

+/**
+ * @brief Iso14443_3a poller event structure.
+ *
+ * Upon emission of an event, an instance of this struct will be passed to the callback.
+ */
 typedef struct {
-    Iso14443_3aPollerEventType type;
-    Iso14443_3aPollerEventData* data;
+    Iso14443_3aPollerEventType type; /**< Type of emmitted event. */
+    Iso14443_3aPollerEventData* data; /**< Pointer to event specific data. */
 } Iso14443_3aPollerEvent;

+/**
+ * @brief Transmit and receive Iso14443_3a frames in poller mode.
+ *
+ * Must ONLY be used inside the callback function.
+ *
+ * The rx_buffer will be filled with any data received as a response to data
+ * sent from tx_buffer, with a timeout defined by the fwt parameter.
+ *
+ *
+ * @param[in, out] instance pointer to the instance to be used in the transaction.
+ * @param[in] tx_buffer pointer to the buffer containing the data to be transmitted.
+ * @param[out] rx_buffer pointer to the buffer to be filled with received data.
+ * @param[in] fwt frame wait time (response timeout), in carrier cycles.
+ * @return Iso14443_3aErrorNone on success, an error code on failure.
+ */
 Iso14443_3aError iso14443_3a_poller_txrx(
    Iso14443_3aPoller* instance,
    const BitBuffer* tx_buffer,
    BitBuffer* rx_buffer,
    uint32_t fwt);

+/**
+ * @brief Transmit and receive Iso14443_3a standard frames in poller mode.
+ *
+ * Must ONLY be used inside the callback function.
+ *
+ * The rx_buffer will be filled with any data received as a response to data
+ * sent from tx_buffer, with a timeout defined by the fwt parameter.
+ *
+ * @param[in, out] instance pointer to the instance to be used in the transaction.
+ * @param[in] tx_buffer pointer to the buffer containing the data to be transmitted.
+ * @param[out] rx_buffer pointer to the buffer to be filled with received data.
+ * @param[in] fwt frame wait time (response timeout), in carrier cycles.
+ * @return Iso14443_3aErrorNone on success, an error code on failure.
+ */
 Iso14443_3aError iso14443_3a_poller_send_standard_frame(
    Iso14443_3aPoller* instance,
    const BitBuffer* tx_buffer,
    BitBuffer* rx_buffer,
    uint32_t fwt);

+/**
+ * @brief Transmit and receive Iso14443_3a frames with custom parity bits in poller mode.
+ *
+ * Must ONLY be used inside the callback function.
+ *
+ * The rx_buffer will be filled with any data received as a response to data
+ * sent from tx_buffer, with a timeout defined by the fwt parameter.
+ *
+ * Custom parity bits must be set in the tx_buffer. The rx_buffer will contain
+ * the received data with the parity bits.
+ *
+ * @param[in, out] instance pointer to the instance to be used in the transaction.
+ * @param[in] tx_buffer pointer to the buffer containing the data to be transmitted.
+ * @param[out] rx_buffer pointer to the buffer to be filled with received data.
+ * @param[in] fwt frame wait time (response timeout), in carrier cycles.
+ * @return Iso14443_3aErrorNone on success, an error code on failure.
+ */
+Iso14443_3aError iso14443_3a_poller_txrx_custom_parity(
+    Iso14443_3aPoller* instance,
+    const BitBuffer* tx_buffer,
+    BitBuffer* rx_buffer,
+    uint32_t fwt);
+
+/**
+ * @brief Checks presence of Iso14443_3a complient card.
+ *
+ * Must ONLY be used inside the callback function.
+ *
+ * @param[in, out] instance pointer to the instance to be used in the transaction.
+ * @return Iso14443_3aErrorNone if card is present, an error code otherwise.
+ */
+Iso14443_3aError iso14443_3a_poller_check_presence(Iso14443_3aPoller* instance);
+
+/**
+ * @brief Perform collision resolution procedure.
+ *
+ * Must ONLY be used inside the callback function.
+ *
+ * Perfoms the collision resolution procedure as defined in Iso14443-3a. The iso14443_3a_data
+ * field will be filled with Iso14443-3a data on success.
+ *
+ * @param[in, out] instance pointer to the instance to be used in the transaction.
+ * @param[out] iso14443_3a_data pointer to the Iso14443_3a data structure to be filled.
+ * @return Iso14443_3aErrorNone on success, an error code on failure.
+ */
+Iso14443_3aError
+    iso14443_3a_poller_activate(Iso14443_3aPoller* instance, Iso14443_3aData* iso14443_3a_data);
+
+/**
+ * @brief Send HALT command to the card.
+ *
+ * Must ONLY be used inside the callback function.
+ *
+ * Halts card and changes internal Iso14443_3aPoller state to Idle.
+ *
+ * @param[in, out] instance pointer to the instance to be used in the transaction.
+ * @return Iso14443_3aErrorNone on success, an error code on failure.
+ */
+Iso14443_3aError iso14443_3a_poller_halt(Iso14443_3aPoller* instance);
+
 #ifdef __cplusplus
 }
 #endif
@@ -94,9 +94,8 @@ Iso14443_3aError iso14443_3a_poller_halt(Iso14443_3aPoller* instance) {
    return Iso14443_3aErrorNone;
 }

-Iso14443_3aError iso14443_3a_poller_async_activate(
-    Iso14443_3aPoller* instance,
-    Iso14443_3aData* iso14443_3a_data) {
+Iso14443_3aError
+    iso14443_3a_poller_activate(Iso14443_3aPoller* instance, Iso14443_3aData* iso14443_3a_data) {
    furi_assert(instance);
    furi_assert(instance->nfc);
    furi_assert(instance->tx_buffer);
@@ -39,15 +39,9 @@ typedef enum {
    Iso14443_3aPollerStateActivated,
 } Iso14443_3aPollerState;

-typedef enum {
-    Iso14443_3aPollerConfigStateIdle,
-    Iso14443_3aPollerConfigStateDone,
-} Iso14443_3aPollerConfigState;
-
 struct Iso14443_3aPoller {
    Nfc* nfc;
    Iso14443_3aPollerState state;
-    Iso14443_3aPollerConfigState config_state;
    Iso14443_3aPollerColRes col_res;
    Iso14443_3aData* data;
    BitBuffer* tx_buffer;
@@ -62,20 +56,6 @@ struct Iso14443_3aPoller {

 const Iso14443_3aData* iso14443_3a_poller_get_data(Iso14443_3aPoller* instance);

-Iso14443_3aError iso14443_3a_poller_check_presence(Iso14443_3aPoller* instance);
-
-Iso14443_3aError iso14443_3a_poller_async_activate(
-    Iso14443_3aPoller* instance,
-    Iso14443_3aData* iso14443_3a_data);
-
-Iso14443_3aError iso14443_3a_poller_halt(Iso14443_3aPoller* instance);
-
-Iso14443_3aError iso14443_3a_poller_txrx_custom_parity(
-    Iso14443_3aPoller* instance,
-    const BitBuffer* tx_buffer,
-    BitBuffer* rx_buffer,
-    uint32_t fwt);
-
 #ifdef __cplusplus
 }
 #endif
@@ -1,4 +1,4 @@
-#include "iso14443_3a_poller_sync_api.h"
+#include "iso14443_3a_poller_sync.h"

 #include "iso14443_3a_poller_i.h"
 #include <nfc/nfc_poller.h>
@@ -34,7 +34,7 @@ NfcCommand iso14443_3a_poller_read_callback(NfcGenericEvent event, void* context
    return NfcCommandStop;
 }

-Iso14443_3aError iso14443_3a_poller_read(Nfc* nfc, Iso14443_3aData* iso14443_3a_data) {
+Iso14443_3aError iso14443_3a_poller_sync_read(Nfc* nfc, Iso14443_3aData* iso14443_3a_data) {
    furi_assert(nfc);
    furi_assert(iso14443_3a_data);

@@ -7,7 +7,7 @@
 extern "C" {
 #endif

-Iso14443_3aError iso14443_3a_poller_read(Nfc* nfc, Iso14443_3aData* iso14443_3a_data);
+Iso14443_3aError iso14443_3a_poller_sync_read(Nfc* nfc, Iso14443_3aData* iso14443_3a_data);

 #ifdef __cplusplus
 }