[FL-3594] NFC docs (new stack) (#3147)

* Add doxygen comments to nfc_device_base.h * Add doxygen comments to nfc_protocol.h and .c * Add doxygen comments to nfc_scanner.h * Add doxygen comments to nfc_device.h * Add doxygen comments to nfc_common.h * Add doxygen comments to nfc_poller.h * Add doxygen comments to nfc_listener.h * Add doxygen comments to nfc_listener_i.h * Add doxygen comments to nfc_device_defs.c * Add doxygen comments to nfc_poller_base.h * Add doxygen comments to nfc_listener_base.h * Add doxygen comments to nfc_generic_event.h * Fix factual eror in nfc_protocol.c comments * Add doxygen comments to nfc.h, remove unused enum values * Add doxygen comments to furi_hal_nfc.h, remove unused enum values * Separate NFC HAL tech definitions to its own private header * Add doxygen comments to furi_hal_nfc_tech_i.h * Add doxygen comments to furi_hal_nfc_i.h * Improve doxygen formatting * Improve wording and some formatting * Fix compilation issue * Clean up nfc application includes * Add doxygen comments to nfc_protocol_support_common.h, rename a enum value * Rename scene to MoreInfo * Add doxygen comments to nfc_protocol_support.h * Add doxygen comments to nfc_protocol_support_render_common.h * Add doxygen comments to nfc_protocol_support_gui_common.h * Add doxygen comments to nfc_protocol_support_base.h * Add doxygen comments to nfc_protocol_support* various files. * Refactor nfc_protocol_support * Add doxygen comments for supported card plugins * Add docs on adding a new protocol (doxygen version) * Add docs on adding a new protocol protocol support (doxygen version) * nfc: add documentation fixes * nfc app: fix st25tb protocol support * nfc app: st25tb remove unnecessary TODO --------- Co-authored-by: gornekich <[email protected]>
flipperdevices · Oct 16, 2023 · 5139d17 · 5139d17
1 parent a966c33
commit 5139d17
Show file tree

Hide file tree

Showing 58 changed files with 2,601 additions and 697 deletions.
diff --git a/applications/main/nfc/helpers/nfc_supported_cards.h b/applications/main/nfc/helpers/nfc_supported_cards.h
@@ -1,3 +1,9 @@
+/**
+ * @file nfc_supported_cards.h
+ * @brief Supported card plugin loader interface.
+ *
+ * @see nfc_supported_card_plugin.h for instructions on adding a new plugin.
+ */
 #pragma once
 
 #include <core/string.h>
@@ -9,8 +15,34 @@
 extern "C" {
 #endif
 
+/**
+ * @brief Read the card using a custom procedure.
+ *
+ * This function will load all suitable supported card plugins one by one and
+ * try to execute the custom read procedure specified in each. Upon first success,
+ * no further attempts will be made and the function will return.
+ *
+ * @param[in,out] device pointer to a device instance to hold the read data.
+ * @param[in,out] nfc pointer to an Nfc instance.
+ * @returns true if the card was successfully read, false otherwise.
+ *
+ * @see NfcSupportedCardPluginRead for detailed description.
+ */
 bool nfc_supported_cards_read(NfcDevice* device, Nfc* nfc);
 
+/**
+ * @brief Parse raw data into human-readable representation.
+ *
+ * This function will load all suitable supported card plugins one by one and
+ * try to parse the data according to each implementation. Upon first success,
+ * no further attempts will be made and the function will return.
+ *
+ * @param[in] device pointer to a device instance holding the data is to be parsed.
+ * @param[out] parsed_data pointer to the string to contain the formatted result.
+ * @returns true if the card was successfully parsed, false otherwise.
+ *
+ * @see NfcSupportedCardPluginParse for detailed description.
+ */
 bool nfc_supported_cards_parse(const NfcDevice* device, FuriString* parsed_data);
 
 #ifdef __cplusplus

diff --git a/applications/main/nfc/helpers/protocol_support/felica/felica.c b/applications/main/nfc/helpers/protocol_support/felica/felica.c
@@ -5,6 +5,7 @@
 
 #include "nfc/nfc_app_i.h"
 
+#include "../nfc_protocol_support_common.h"
 #include "../nfc_protocol_support_gui_common.h"
 
 static void nfc_scene_info_on_enter_felica(NfcApp* instance) {
@@ -67,17 +68,17 @@ static bool nfc_scene_saved_menu_on_event_felica(NfcApp* instance, uint32_t even
 }
 
 const NfcProtocolSupportBase nfc_protocol_support_felica = {
-    .features = NfcProtocolFeatureNone, // TODO: Implement better UID editing,
+    .features = NfcProtocolFeatureNone, // TODO: Implement better UID editing
 
     .scene_info =
         {
             .on_enter = nfc_scene_info_on_enter_felica,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_read =
         {
             .on_enter = nfc_scene_read_on_enter_felica,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_read_menu =
         {
@@ -87,7 +88,7 @@ const NfcProtocolSupportBase nfc_protocol_support_felica = {
     .scene_read_success =
         {
             .on_enter = nfc_scene_read_success_on_enter_felica,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_saved_menu =
         {
@@ -96,12 +97,12 @@ const NfcProtocolSupportBase nfc_protocol_support_felica = {
         },
     .scene_save_name =
         {
-            .on_enter = NULL,
-            .on_event = NULL,
+            .on_enter = nfc_protocol_support_common_on_enter_empty,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_emulate =
         {
-            .on_enter = NULL,
-            .on_event = NULL,
+            .on_enter = nfc_protocol_support_common_on_enter_empty,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
 };
diff --git a/applications/main/nfc/helpers/protocol_support/iso14443_3a/iso14443_3a.c b/applications/main/nfc/helpers/protocol_support/iso14443_3a/iso14443_3a.c
@@ -5,6 +5,7 @@
 
 #include "nfc/nfc_app_i.h"
 
+#include "../nfc_protocol_support_common.h"
 #include "../nfc_protocol_support_gui_common.h"
 
 static void nfc_scene_info_on_enter_iso14443_3a(NfcApp* instance) {
@@ -109,12 +110,12 @@ const NfcProtocolSupportBase nfc_protocol_support_iso14443_3a = {
     .scene_info =
         {
             .on_enter = nfc_scene_info_on_enter_iso14443_3a,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_read =
         {
             .on_enter = nfc_scene_read_on_enter_iso14443_3a,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_read_menu =
         {
@@ -124,21 +125,21 @@ const NfcProtocolSupportBase nfc_protocol_support_iso14443_3a = {
     .scene_read_success =
         {
             .on_enter = nfc_scene_read_success_on_enter_iso14443_3a,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_saved_menu =
         {
             .on_enter = nfc_protocol_support_common_on_enter_empty,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_save_name =
         {
-            .on_enter = NULL,
-            .on_event = NULL,
+            .on_enter = nfc_protocol_support_common_on_enter_empty,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_emulate =
         {
             .on_enter = nfc_scene_emulate_on_enter_iso14443_3a,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
 };
diff --git a/applications/main/nfc/helpers/protocol_support/iso14443_3a/iso14443_3a_render.c b/applications/main/nfc/helpers/protocol_support/iso14443_3a/iso14443_3a_render.c
@@ -17,8 +17,7 @@ void nfc_render_iso14443_3a_info(
 
     nfc_render_iso14443_3a_brief(data, str);
 
-    if(format_type == NfcProtocolFormatTypeFull ||
-       format_type == NfcProtocolFormatTypeShortExtra) {
+    if(format_type == NfcProtocolFormatTypeFull) {
         nfc_render_iso14443_3a_extra(data, str);
     }
 }

diff --git a/applications/main/nfc/helpers/protocol_support/iso14443_3b/iso14443_3b.c b/applications/main/nfc/helpers/protocol_support/iso14443_3b/iso14443_3b.c
@@ -5,6 +5,7 @@
 
 #include "nfc/nfc_app_i.h"
 
+#include "../nfc_protocol_support_common.h"
 #include "../nfc_protocol_support_gui_common.h"
 
 static void nfc_scene_info_on_enter_iso14443_3b(NfcApp* instance) {
@@ -77,12 +78,12 @@ const NfcProtocolSupportBase nfc_protocol_support_iso14443_3b = {
     .scene_info =
         {
             .on_enter = nfc_scene_info_on_enter_iso14443_3b,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_read =
         {
             .on_enter = nfc_scene_read_on_enter_iso14443_3b,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_read_menu =
         {
@@ -92,7 +93,7 @@ const NfcProtocolSupportBase nfc_protocol_support_iso14443_3b = {
     .scene_read_success =
         {
             .on_enter = nfc_scene_read_success_on_enter_iso14443_3b,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_saved_menu =
         {
@@ -101,12 +102,12 @@ const NfcProtocolSupportBase nfc_protocol_support_iso14443_3b = {
         },
     .scene_save_name =
         {
-            .on_enter = NULL,
-            .on_event = NULL,
+            .on_enter = nfc_protocol_support_common_on_enter_empty,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_emulate =
         {
-            .on_enter = NULL,
-            .on_event = NULL,
+            .on_enter = nfc_protocol_support_common_on_enter_empty,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
 };
diff --git a/applications/main/nfc/helpers/protocol_support/iso14443_4a/iso14443_4a.c b/applications/main/nfc/helpers/protocol_support/iso14443_4a/iso14443_4a.c
@@ -6,6 +6,7 @@
 
 #include "nfc/nfc_app_i.h"
 
+#include "../nfc_protocol_support_common.h"
 #include "../nfc_protocol_support_gui_common.h"
 
 static void nfc_scene_info_on_enter_iso14443_4a(NfcApp* instance) {
@@ -113,12 +114,12 @@ const NfcProtocolSupportBase nfc_protocol_support_iso14443_4a = {
     .scene_info =
         {
             .on_enter = nfc_scene_info_on_enter_iso14443_4a,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_read =
         {
             .on_enter = nfc_scene_read_on_enter_iso14443_4a,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_read_menu =
         {
@@ -128,21 +129,21 @@ const NfcProtocolSupportBase nfc_protocol_support_iso14443_4a = {
     .scene_read_success =
         {
             .on_enter = nfc_scene_read_success_on_enter_iso14443_4a,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_saved_menu =
         {
             .on_enter = nfc_scene_saved_menu_on_enter_iso14443_4a,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_save_name =
         {
-            .on_enter = NULL,
-            .on_event = NULL,
+            .on_enter = nfc_protocol_support_common_on_enter_empty,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_emulate =
         {
             .on_enter = nfc_scene_emulate_on_enter_iso14443_4a,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
 };
diff --git a/applications/main/nfc/helpers/protocol_support/iso14443_4b/iso14443_4b.c b/applications/main/nfc/helpers/protocol_support/iso14443_4b/iso14443_4b.c
@@ -5,6 +5,7 @@
 
 #include "nfc/nfc_app_i.h"
 
+#include "../nfc_protocol_support_common.h"
 #include "../nfc_protocol_support_gui_common.h"
 #include "../iso14443_3b/iso14443_3b_i.h"
 
@@ -82,12 +83,12 @@ const NfcProtocolSupportBase nfc_protocol_support_iso14443_4b = {
     .scene_info =
         {
             .on_enter = nfc_scene_info_on_enter_iso14443_4b,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_read =
         {
             .on_enter = nfc_scene_read_on_enter_iso14443_4b,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_read_menu =
         {
@@ -97,7 +98,7 @@ const NfcProtocolSupportBase nfc_protocol_support_iso14443_4b = {
     .scene_read_success =
         {
             .on_enter = nfc_scene_read_success_on_enter_iso14443_4b,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_saved_menu =
         {
@@ -106,12 +107,12 @@ const NfcProtocolSupportBase nfc_protocol_support_iso14443_4b = {
         },
     .scene_save_name =
         {
-            .on_enter = NULL,
-            .on_event = NULL,
+            .on_enter = nfc_protocol_support_common_on_enter_empty,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_emulate =
         {
-            .on_enter = NULL,
-            .on_event = NULL,
+            .on_enter = nfc_protocol_support_common_on_enter_empty,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
 };
diff --git a/applications/main/nfc/helpers/protocol_support/iso15693_3/iso15693_3.c b/applications/main/nfc/helpers/protocol_support/iso15693_3/iso15693_3.c
@@ -6,6 +6,7 @@
 
 #include "nfc/nfc_app_i.h"
 
+#include "../nfc_protocol_support_common.h"
 #include "../nfc_protocol_support_gui_common.h"
 
 static void nfc_scene_info_on_enter_iso15693_3(NfcApp* instance) {
@@ -108,12 +109,12 @@ const NfcProtocolSupportBase nfc_protocol_support_iso15693_3 = {
     .scene_info =
         {
             .on_enter = nfc_scene_info_on_enter_iso15693_3,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_read =
         {
             .on_enter = nfc_scene_read_on_enter_iso15693_3,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_read_menu =
         {
@@ -123,7 +124,7 @@ const NfcProtocolSupportBase nfc_protocol_support_iso15693_3 = {
     .scene_read_success =
         {
             .on_enter = nfc_scene_read_success_on_enter_iso15693_3,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_saved_menu =
         {
@@ -132,12 +133,12 @@ const NfcProtocolSupportBase nfc_protocol_support_iso15693_3 = {
         },
     .scene_save_name =
         {
-            .on_enter = NULL,
-            .on_event = NULL,
+            .on_enter = nfc_protocol_support_common_on_enter_empty,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
     .scene_emulate =
         {
             .on_enter = nfc_scene_emulate_on_enter_iso15693_3,
-            .on_event = NULL,
+            .on_event = nfc_protocol_support_common_on_event_empty,
         },
 };