Skip to content

Commit

Permalink
Add docs on adding a new protocol protocol support (doxygen version)
Browse files Browse the repository at this point in the history
  • Loading branch information
gsurkov committed Oct 13, 2023
1 parent 576f8ac commit d0099d7
Show file tree
Hide file tree
Showing 2 changed files with 75 additions and 5 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,73 @@
* NFC protocol support helper abstracts common scenes with a single interface
* and lets each protocol decide on concrete implementation.
*
* @see nfc_protocol_support_base.h
* @see nfc_protocol_support_common.h
* # Integrating a new protocol into the application
*
* Most of the scenes in the NFC application work through abstract APIs, so they do not need
* protocol-specific versions of themselves. However, when such a situation
* occurs, the protocol support helper provides another level of abstraction to hide
* the protocol-specific details and isolate them to separate modules.
*
* @see nfc_protocol.h for more information on adding library protocols.
*
* The steps for adding support for a library protocol are described below.
*
* ## 1. Create the files
*
* ### 1.1 Recommended file structure
*
* The recommended file structure for a protocol support is as follows:
*
* ```text
* protocol_support
* |
* +- protocol_name
* |
* +- protocol_name.h
* |
* +- protocol_name.c
* |
* +- protocol_name_render.h
* |
* +- protocol_name_render.c
* |
* ```
* ### 1.2 File structure explanation
*
* | Filename | Explanation |
* |:-----------------------|:------------|
* | protocol_name.h | Interface structure declaration used in `nfc_protocol_support_defs.c`. |
* | protocol_name.c | Protocol-specific scene implemenatations and definitions. |
* | protocol_name_render.h | Protocol-specific rendering (formatting) functions. Used for converting protocol data into textual descriptions. |
* | protocol_name_render.c | Implementations for functions declared in `protocol_name_render.h`.|
*
* ## 2. Implement the code
*
* ### 2.1 Features
*
* Decide what features the protocol will be providing. The features can be combined using bitwise OR (`"|"`).
* This choice influences which scenes will have to be implemented in step 2.2.
*
* @see NfcProtocolFeature for the enumeration of possible features to implement.
*
* ### 2.2 Scenes
*
* If a particular scene is not implemented, its empty placeholder from nfc_protocol_support_gui_common.h must be used instead.
*
* @see nfc_protocol_support_common.h for the enumeration of all scenes that can be implemented.
* @see nfc_protocol_support_base.h for the scene implementation details.
*
* ### 2.3. Registering the protocol support
*
* After completing the protocol support, it must be registered within the application in order for it to be usable.
*
* In nfc_protocol_support_defs.c, include the `protocol_name.h` file and add a new entry in the `nfc_protocol_support[]`
* array under the appropriate index.
*
* ## Done!
*
* @note It will not always be possible to abstract all of the protocol's functionality using the protocol support helper.
* In such cases, creating separate protocol-specific scenes is okay (as an example, note the `nfc/scenes/nfc_scene_mf_classic_*` scenes which didn't fit this paradigm).
*/
#pragma once

Expand Down
11 changes: 8 additions & 3 deletions lib/nfc/protocols/nfc_protocol.h
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
* ### 2.1 Recommended file structure
*
* The recommended file structure for a protocol is as follows:
*
* ```text
* protocols
* |
Expand Down Expand Up @@ -63,7 +64,7 @@
* +- protocol_name_sync_api.h |
* | |- add for synchronous API support
* +- protocol_name_sync_api.c |
*
* |
* ```
*
* Additionally, an arbitrary amount of private `protocol_name_*_i.h` header files may be created. Do not put implementation
Expand All @@ -86,6 +87,7 @@
* | protocol_name_sync_api.c | Synchronous API implementation. Optional. |
*
* ## 3 Implement the code
*
* ### 3.1 Protocol data structure
*
* A protocol data structure is what holds all data that can be possibly read from a card of a certain type. It may include a unique identifier (UID),
Expand Down Expand Up @@ -149,10 +151,13 @@
*
* ## What's next?
*
* However not strictly necessary, it will be a good idea to integrate the newly implemented protocol to the main NFC application.
* After having done that, a supported card plugin may be implemented to take further advantage of the new protocol.
* It's about time to integrate the newly implemented protocol into the main NFC application. Without that, reading a card
* of this type would crash it.
*
* @see nfc_protocol_support.h for more information on protocol integration.
*
* After having done that, a supported card plugin may be implemented to take further advantage of the new protocol.
*
* @see nfc_supported_card_plugin.h for more information on supported card plugins.
*
*/
Expand Down

0 comments on commit d0099d7

Please sign in to comment.