Merge pull request #7426 from donatieng/nfc-spec

NFC APIs Design Specification

Author: 0xc0170

docs/design-documents/nfc/interop_test_rig.png

@@ -0,0 +1,33 @@
+@startuml
+class NFCController {
+  +NFCController(NFCControllerDriver* driver, events::EventQueue* queue)
+  +void set_delegate(NFCController::Delegate* delegate)
+  +nfc_rf_protocols_bitmask_t get_supported_rf_protocols() const
+  +nfc_err_t initialize()
+  +nfc_err_t configure_rf_protocols(nfc_rf_protocols_bitmask_t rf_protocols)
+  +nfc_err_t start_discovery()
+  +nfc_err_t cancel_discovery()
+}
+
+abstract class NFCController::Delegate {
+  +{abstract} void on_discovery_terminated(nfc_discovery_terminated_reason_t reason)
+  +{abstract} void on_nfc_target_discovered(const mbed::SharedPtr<NFCRemoteTarget>& target)
+  +{abstract} void on_nfc_initiator_discovered(const mbed::SharedPtr<NFCRemoteInitiator>& initiator)
+}
+
+abstract class NFCControllerDriver {
+  +void set_delegate(Delegate* delegate)
+  +{abstract} transceiver_t* initialize(scheduler_timer_t* pTimer)
+  +{abstract} void get_supported_nfc_techs(nfc_tech_t* initiator, nfc_tech_t* target) const
+}
+
+abstract class NFCControllerDriver::Delegate {
+  +{abstract} void on_hw_interrupt()
+}
+
+NFCController o-- NFCController::Delegate
+NFCController o-- NFCControllerDriver
+NFCControllerDriver o-- NFCControllerDriver::Delegate
+NFCControllerDriver::Delegate <-- NFCController
+
+@enduml

docs/design-documents/nfc/nfc_design.md

@@ -0,0 +1,108 @@
+@startuml
+
+abstract class NFCNDEFCapable {
+  +{abstract} bool is_ndef_supported() const
+
+  #void parse_ndef_message(const ac_buffer_t& buffer)
+  #void build_ndef_message(ac_buffer_builder_t& buffer_builder)
+  #ndef_msg_t* ndef_message()
+  #{abstract} NFCNDEFCapable::Delegate* ndef_capable_delegate()
+}
+
+abstract class NFCNDEFCapable::Delegate {
+  +{abstract} void parse_ndef_message(const Span<const uint8_t> &buffer)
+  +{abstract} size_t build_ndef_message(const Span<uint8_t> &buffer)
+}
+
+abstract class NFCRemoteEndpoint {
+  +{abstract} bool is_connected() const
+  +{abstract} bool is_disconnected() const
+  +{abstract} nfc_rf_protocols_bitmask_t rf_protocols() const
+  +{abstract} nfc_err_t connect()
+  +{abstract} nfc_err_t disconnect()
+}
+
+abstract class NFCRemoteEndpoint::Delegate {
+  +{abstract} void on_connected()
+  +{abstract} void on_disconnected()
+}
+
+abstract class NFCTarget {
+  +void write_ndef_message()
+  +void erase_ndef_message()
+  +void read_ndef_message()
+}
+
+abstract class NFCTarget::Delegate {
+  +{abstract} void on_ndef_message_written(nfc_err_t result)
+  +{abstract} void on_ndef_message_erased(nfc_err_t result)
+  +{abstract} void on_ndef_message_read(nfc_err_t result)
+}
+
+NFCNDEFCapable <-- NFCTarget
+NFCNDEFCapable::Delegate <-- NFCTarget::Delegate
+
+class NFCEEPROM {
+  +nfc_err_t initialize()
+  +void set_delegate(NFCEEPROM::Delegate* delegate)
+}
+
+abstract class NFCEEPROM::Delegate {
+
+}
+
+abstract class NFCEEPROMDriver {
+  +void set_delegate(Delegate* delegate)
+  +void set_event_queue(events::EventQueue* queue)
+
+  +{abstract} void reset()
+  +{abstract} size_t get_max_size()
+  +{abstract} void start_session(bool force = true)
+  +{abstract} void end_session()
+  +{abstract} void read_bytes(uint32_t address, size_t count)
+  +{abstract} void write_bytes(uint32_t address, const uint8_t* bytes, size_t count)
+  +{abstract} void write_size(size_t count)
+  +{abstract} void read_size()
+  +{abstract} void erase_bytes(uint32_t address, size_t size)
+  #NFCEEPROMDriver::Delegate *delegate()
+  #events::EventQueue *event_queue()
+}
+
+abstract class NFCEEPROMDriver::Delegate {
+  +{abstract} void on_session_started(bool success)
+  +{abstract} void on_session_ended(bool success)
+  +{abstract} void on_bytes_read(size_t count)
+  +{abstract} void on_bytes_written(size_t count)
+  +{abstract} void on_size_read(bool success, size_t size)
+  +{abstract} void on_size_written(bool success)
+  +{abstract} void on_bytes_erased(size_t count)
+}
+
+NFCTarget <-- NFCEEPROM
+NFCTarget::Delegate <-- NFCEEPROM::Delegate
+NFCEEPROM o-- NFCEEPROM::Delegate
+NFCEEPROM o-- NFCEEPROMDriver
+NFCEEPROMDriver o-- NFCEEPROMDriver::Delegate
+NFCEEPROMDriver::Delegate <-- NFCEEPROM
+
+class NFCRemoteInitiator {
+  +void set_delegate(NFCRemoteInitiator::Delegate* delegate)
+  
+  +{abstract}bool is_iso7816_supported() const
+  +{abstract}void add_iso7816_application(nfc_tech_iso7816_app_t *application)
+  
+  +{abstract} nfc_tag_type_t nfc_tag_type()
+  +{abstract} bool is_ndef_supported()
+}
+
+abstract class NFCRemoteInitiator::Delegate {
+
+}
+
+NFCNDEFCapable <-- NFCRemoteInitiator
+NFCRemoteEndpoint <-- NFCRemoteInitiator
+NFCRemoteEndpoint::Delegate <-- NFCRemoteInitiator::Delegate
+NFCNDEFCapable::Delegate <-- NFCRemoteInitiator::Delegate
+NFCRemoteInitiator o-- NFCRemoteInitiator::Delegate
+
+@enduml

docs/design-documents/nfc/phase_1_architecture.png

@@ -0,0 +1,58 @@
+@startuml
+
+package ndef {
+
+abstract RecordParser { 
+   +RecordParser()
+   +{abstract} bool parse(const Record&)
+   #~RecordParser()
+}
+
+abstract GenericRecordParser<ParserImplementation, ParsingResult> { 
+   +GenericRecordParser()
+   +bool parse(const Record&)
+   +void set_delegate(Delegate* delegate)
+   #~GenericRecordParser()
+}
+
+interface GenericRecordParser::Delegate<ParsingResult> { 
+   +{abstract} void on_record_parsed(const ParsingResult& result, const RecordID* id)
+   #~Delegate()
+}
+
+RecordParser    <|- GenericRecordParser
+GenericRecordParser     +- "0..1" GenericRecordParser::Delegate
+
+}
+
+package common { 
+class URI { 
+}
+class Mime { 
+}
+class Text { 
+}
+
+class URIParser { 
+    bool do_parse(const ndef::Record& record, URI& uri)
+}
+
+class TextParser { 
+    bool do_parse(const ndef::Record& record, Text& text)
+}
+
+class MimeParser { 
+    bool do_parse(const ndef::Record& record, Mime& mime)
+}
+
+URI -- URIParser: Produce <
+Text -- TextParser: Produce <
+Mime -- MimeParser: Produce <
+
+URIParser --|> GenericRecordParser
+TextParser --|> GenericRecordParser
+MimeParser --|> GenericRecordParser
+}
+
+
+@enduml

docs/design-documents/nfc/phase_2_architecture.png

@@ -0,0 +1,66 @@
+@startuml
+
+package ndef {
+
+class MessageBuilder { 
+    +MessageBuilder(const Span<uint8_t> &buffer)
+    +~MessageBuilder()
+    +bool append_record(const RecordType &type, const RecordPayload &payload = RecordPayload(), bool is_last_record = false)
+    +bool append_record(const RecordType &type, const PayloadBuilder &builder, bool is_last_record = false)
+    +bool append_record(const Record &record, const PayloadBuilder *builder = NULL)
+    +void reset();
+    +void reset(const Span<uint8_t> &buffer);
+    +bool is_message_complete() const
+    +Span<const uint8_t> get_message() const
+}
+
+class Record { 
+}
+
+class RecordType{ 
+}
+
+class RecordPayload{ 
+}
+
+class RecordID{
+}
+
+interface MessageBuilder::PayloadBuilder { 
+    +{abstract} size_t size() const
+    +{abstract} void build(const Span<uint8_t> &buffer) const
+    # ~PayloadBuilder()
+}
+
+
+Record *-- RecordType
+Record *-- "0..1" RecordPayload
+Record *-- "0..1" RecordID
+
+Record - MessageBuilder: insert >
+MessageBuilder - MessageBuilder::PayloadBuilder: < build payload at insertion
+
+}
+
+package common { 
+
+
+class URI { 
++bool append_as_record(ndef::MessageBuilder &builder, bool is_last_record) const
+}
+
+class Text { 
++bool append_as_record(ndef::MessageBuilder &builder, bool is_last_record) const
+}
+
+class Mime { 
++bool append_as_record(ndef::MessageBuilder &builder, bool is_last_record) const
+}
+
+URI -- MessageBuilder: uses >
+Text -- MessageBuilder: uses >
+Mime -- MessageBuilder: uses >
+
+}
+
+@enduml

docs/design-documents/nfc/uml_diagram_controller.png

@@ -0,0 +1,46 @@
+@startuml
+
+package ndef {
+
+class MessageParser { 
+    +MessageParser()
+    +void set_delegate(Delegate *delegate)
+    +void parse(const Span<const uint8_t> &data_buffer)
+}
+
+interface MessageParser::Delegate { 
+    +{abstract} void on_parsing_started()
+    +{abstract} void on_record_parsed(const Record &record)
+    +{abstract} void on_parsing_terminated()
+    +{abstract} void on_parsing_error(error_t error)
+    # ~Delegate()
+}
+
+enum MessageParser::error_t { 
+}
+
+MessageParser +-- "0..1" MessageParser::Delegate
+MessageParser +-- MessageParser::error_t
+
+note top of "MessageParser::Delegate"
+Implemented by the client of the parsing operation.
+end note
+
+class Record { 
+}
+class RecordType { 
+}
+class RecordPayload { 
+}
+class RecordID { 
+}
+
+Record *-- RecordType
+Record *-- "0..1" RecordPayload
+Record *-- "0..1" RecordID
+
+MessageParser - Record: Produce >
+
+}
+
+@enduml

docs/design-documents/nfc/uml_diagram_controller.txt

@@ -0,0 +1,73 @@
+@startuml
+
+package ndef {
+
+class Record { 
+}
+class RecordType { 
+}
+class RecordPayload { 
+}
+class RecordID { 
+}
+
+Record *-- RecordType
+Record *-- "0..1" RecordPayload
+Record *-- "0..1" RecordID
+
+abstract RecordParser { 
+   +RecordParser()
+   +{abstract} bool parse(const Record&)
+   #~RecordParser()
+}
+
+abstract GenericRecordParser<ParserImplementation, ParsingResult> { 
+   +GenericRecordParser()
+   +bool parse(const Record&)
+   +void set_delegate(Delegate* delegate)
+   #~GenericRecordParser()
+}
+
+interface GenericRecordParserConcept<ParsingResult> { 
+   +bool do_parse(const Record& record, ParsingResult& parsing_result)
+}
+
+interface GenericRecordParser::Delegate<ParsingResult> { 
+   +{abstract} void on_record_parsed(const ParsingResult& record, const RecordID* id)
+   #~Delegate()
+}
+
+RecordParser    <|-- GenericRecordParser
+GenericRecordParser     <|-- GenericRecordParserConcept
+GenericRecordParser     +-- "0..1" GenericRecordParser::Delegate
+
+note as N1 
+    GenericRecordParserConcept model the concept that must
+    be implemented by GenericRecordParser childs. 
+    It doesn't exist in the hierarchy.
+end note
+
+N1 - GenericRecordParser
+N1 - GenericRecordParserConcept
+
+note bottom of "GenericRecordParser::Delegate"
+Implemented by the client of the parsing operation.
+end note
+
+class RecordParserChain { 
+    +RecordParserChain()
+    +~RecordParserChain()
+    +bool parse(const Record& record)
+    +void set_next_parser(RecordParser* parser)
+}
+
+note bottom of "RecordParserChain"
+Chain of responsibility pattern.
+end note
+
+Record - RecordParserChain: Parse >
+RecordParserChain o- "*" RecordParser
+
+}
+
+@enduml