Kenji Arai
mbed-os5 only for TYBLE16
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
docs/design-documents/nfc/nfc_design.md@1:9db0e321a9f4, 2019-12-31 (annotated)
- Committer:
- kenjiArai
- Date:
- Tue Dec 31 06:02:27 2019 +0000
- Revision:
- 1:9db0e321a9f4
updated based on mbed-os5.15.0
Who changed what in which revision?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| kenjiArai | 1:9db0e321a9f4 | 1 | # Near-field communication in Mbed OS |
| kenjiArai | 1:9db0e321a9f4 | 2 | |
| kenjiArai | 1:9db0e321a9f4 | 3 | ## Table of contents |
| kenjiArai | 1:9db0e321a9f4 | 4 | |
| kenjiArai | 1:9db0e321a9f4 | 5 | - [Near-field communication in Mbed OS](#near-field-communication-in-mbed-os) |
| kenjiArai | 1:9db0e321a9f4 | 6 | - [Table of contents](#table-of-contents) |
| kenjiArai | 1:9db0e321a9f4 | 7 | - [Revision history](#revision-history) |
| kenjiArai | 1:9db0e321a9f4 | 8 | - [Introduction](#introduction) |
| kenjiArai | 1:9db0e321a9f4 | 9 | - [Overview and background](#overview-and-background) |
| kenjiArai | 1:9db0e321a9f4 | 10 | - [Use cases](#use-cases) |
| kenjiArai | 1:9db0e321a9f4 | 11 | - [Commissioning](#commissioning) |
| kenjiArai | 1:9db0e321a9f4 | 12 | - [Identification](#identification) |
| kenjiArai | 1:9db0e321a9f4 | 13 | - [Transport](#transport) |
| kenjiArai | 1:9db0e321a9f4 | 14 | - [BLE pairing](#ble-pairing) |
| kenjiArai | 1:9db0e321a9f4 | 15 | - [System architecture and high-level design](#system-architecture-and-high-level-design) |
| kenjiArai | 1:9db0e321a9f4 | 16 | - [Compliance with NFC forum specifications](#compliance-with-nfc-forum-specifications) |
| kenjiArai | 1:9db0e321a9f4 | 17 | - [User-facing API](#user-facing-api) |
| kenjiArai | 1:9db0e321a9f4 | 18 | - [Phase 1: MicroNFC stack integration](#phase-1-micronfc-stack-integration) |
| kenjiArai | 1:9db0e321a9f4 | 19 | - [Phase 2: NFC host/controller split, NCI and NFC HAL API](#phase-2-nfc-hostcontroller-split-nci-and-nfc-hal-api) |
| kenjiArai | 1:9db0e321a9f4 | 20 | - [Detailed design](#detailed-design) |
| kenjiArai | 1:9db0e321a9f4 | 21 | - [User-facing APIs](#user-facing-apis) |
| kenjiArai | 1:9db0e321a9f4 | 22 | - [NFC controller](#nfc-controller) |
| kenjiArai | 1:9db0e321a9f4 | 23 | - [Endpoints](#endpoints) |
| kenjiArai | 1:9db0e321a9f4 | 24 | - [NFC remote endpoint](#nfc-remote-endpoint) |
| kenjiArai | 1:9db0e321a9f4 | 25 | - [NFC NDEF capable](#nfc-ndef-capable) |
| kenjiArai | 1:9db0e321a9f4 | 26 | - [NFC remote initiator](#nfc-remote-initiator) |
| kenjiArai | 1:9db0e321a9f4 | 27 | - [NFC target](#nfc-target) |
| kenjiArai | 1:9db0e321a9f4 | 28 | - [NFC EEPROM](#nfc-eeprom) |
| kenjiArai | 1:9db0e321a9f4 | 29 | - [NFC remote target](#nfc-remote-target) |
| kenjiArai | 1:9db0e321a9f4 | 30 | - [NDEF API](#ndef-api) |
| kenjiArai | 1:9db0e321a9f4 | 31 | - [Common objects](#common-objects) |
| kenjiArai | 1:9db0e321a9f4 | 32 | - [Parsing](#parsing) |
| kenjiArai | 1:9db0e321a9f4 | 33 | - [ndef::MessageParser](#ndefmessageparser) |
| kenjiArai | 1:9db0e321a9f4 | 34 | - [ndef::MessageParser::Delegate](#ndefmessageparserdelegate) |
| kenjiArai | 1:9db0e321a9f4 | 35 | - [NDEF record parsing](#ndef-record-parsing) |
| kenjiArai | 1:9db0e321a9f4 | 36 | - [ndef::RecordParser](#ndefrecordparser) |
| kenjiArai | 1:9db0e321a9f4 | 37 | - [ndef::RecordParserChain](#ndefrecordparserchain) |
| kenjiArai | 1:9db0e321a9f4 | 38 | - [ndef::GenericRecordParser<ParserImplementation, ParsingResult>](#ndefgenericrecordparserparserimplementation-parsingresult) |
| kenjiArai | 1:9db0e321a9f4 | 39 | - [ndef::GenericRecordParser<ParserImplementation, ParsingResult>::Delegate](#ndefgenericrecordparserparserimplementation-parsingresultdelegate) |
| kenjiArai | 1:9db0e321a9f4 | 40 | - [Common parsers](#common-parsers) |
| kenjiArai | 1:9db0e321a9f4 | 41 | - [Simple parser](#simple-parser) |
| kenjiArai | 1:9db0e321a9f4 | 42 | - [Delegate](#delegate) |
| kenjiArai | 1:9db0e321a9f4 | 43 | - [Serialization](#serialization) |
| kenjiArai | 1:9db0e321a9f4 | 44 | - [HAL APIs](#hal-apis) |
| kenjiArai | 1:9db0e321a9f4 | 45 | - [NFC EEPROM API](#nfc-eeprom-api) |
| kenjiArai | 1:9db0e321a9f4 | 46 | - [NCI driver APIs](#nci-driver-apis) |
| kenjiArai | 1:9db0e321a9f4 | 47 | - [Testing strategy](#testing-strategy) |
| kenjiArai | 1:9db0e321a9f4 | 48 | - [NFC forum compliance](#nfc-forum-compliance) |
| kenjiArai | 1:9db0e321a9f4 | 49 | - [Interoperability](#interoperability) |
| kenjiArai | 1:9db0e321a9f4 | 50 | - [HAL testing](#hal-testing) |
| kenjiArai | 1:9db0e321a9f4 | 51 | - [Dependencies](#dependencies) |
| kenjiArai | 1:9db0e321a9f4 | 52 | |
| kenjiArai | 1:9db0e321a9f4 | 53 | ## Revision history |
| kenjiArai | 1:9db0e321a9f4 | 54 | |
| kenjiArai | 1:9db0e321a9f4 | 55 | | Revision | Date | Authors | Mbed OS version | Comments | |
| kenjiArai | 1:9db0e321a9f4 | 56 | |---------- |---------------- |-------------------------------------------------------- |----------------- |------------------ | |
| kenjiArai | 1:9db0e321a9f4 | 57 | | 1.0 | 24 August 2018 | Donatien Garnier ([@donatieng](https://github.com/donatieng/)); Vincent Coubard ([@pan-](https://github.com/pan-/)) | 5.10+ | Initial revision | |
| kenjiArai | 1:9db0e321a9f4 | 58 | |
| kenjiArai | 1:9db0e321a9f4 | 59 | # Introduction |
| kenjiArai | 1:9db0e321a9f4 | 60 | |
| kenjiArai | 1:9db0e321a9f4 | 61 | ## Overview and background |
| kenjiArai | 1:9db0e321a9f4 | 62 | |
| kenjiArai | 1:9db0e321a9f4 | 63 | NFC offers a straightforward and secure way of commissioning IoT devices in the field, and we are seeing increasing demand for this from prospective customers. We have a plan to introduce NFC into Mbed OS. This is the first phase to add a reference implementation of card emulation mode. |
| kenjiArai | 1:9db0e321a9f4 | 64 | |
| kenjiArai | 1:9db0e321a9f4 | 65 | NFC offers three modes: |
| kenjiArai | 1:9db0e321a9f4 | 66 | |
| kenjiArai | 1:9db0e321a9f4 | 67 | 1. NFC card emulation. |
| kenjiArai | 1:9db0e321a9f4 | 68 | 2. NFC reader/writer. |
| kenjiArai | 1:9db0e321a9f4 | 69 | 3. NFC peer to peer. |
| kenjiArai | 1:9db0e321a9f4 | 70 | |
| kenjiArai | 1:9db0e321a9f4 | 71 | To support new use cases, such as commissioning, BLE pairing and identification and authentication of NFC-enabled IoT endpoints, Mbed OS should support the card emulation mode. |
| kenjiArai | 1:9db0e321a9f4 | 72 | |
| kenjiArai | 1:9db0e321a9f4 | 73 | However, the architecture should be future-proofed and should also be extendable to support other NFC modes in the future. |
| kenjiArai | 1:9db0e321a9f4 | 74 | |
| kenjiArai | 1:9db0e321a9f4 | 75 | ## Use cases |
| kenjiArai | 1:9db0e321a9f4 | 76 | |
| kenjiArai | 1:9db0e321a9f4 | 77 | ### Commissioning |
| kenjiArai | 1:9db0e321a9f4 | 78 | |
| kenjiArai | 1:9db0e321a9f4 | 79 | NFC is a medium that can support commissioning requirements. |
| kenjiArai | 1:9db0e321a9f4 | 80 | |
| kenjiArai | 1:9db0e321a9f4 | 81 | #### Identification |
| kenjiArai | 1:9db0e321a9f4 | 82 | |
| kenjiArai | 1:9db0e321a9f4 | 83 | You can use an NDEF message to carry a device's unique identifier. This eases identification before handing over to another transport medium, such as BLE. |
| kenjiArai | 1:9db0e321a9f4 | 84 | |
| kenjiArai | 1:9db0e321a9f4 | 85 | #### Transport |
| kenjiArai | 1:9db0e321a9f4 | 86 | |
| kenjiArai | 1:9db0e321a9f4 | 87 | If the NFC controller can emulate a smartcard, no handover is necessary, and the full commissioning flow can happen over NFC. |
| kenjiArai | 1:9db0e321a9f4 | 88 | |
| kenjiArai | 1:9db0e321a9f4 | 89 | ### BLE pairing |
| kenjiArai | 1:9db0e321a9f4 | 90 | |
| kenjiArai | 1:9db0e321a9f4 | 91 | You can use a specifically crafted NDEF message to facilitate out-of-band pairing with man-in-the-middle protection as specified in the [Bluetooth® Secure Simple Pairing Using NFC](https://members.nfc-forum.org/apps/group_public/download.php/18688/NFCForum-AD-BTSSP_1_1.pdf) document. |
| kenjiArai | 1:9db0e321a9f4 | 92 | |
| kenjiArai | 1:9db0e321a9f4 | 93 | # System architecture and high-level design |
| kenjiArai | 1:9db0e321a9f4 | 94 | |
| kenjiArai | 1:9db0e321a9f4 | 95 | ## Compliance with NFC forum specifications |
| kenjiArai | 1:9db0e321a9f4 | 96 | |
| kenjiArai | 1:9db0e321a9f4 | 97 | The NFC Forum is one the bodies producing NFC standards. Most smartphones supporting NFC today are compliant with the NFC Forum's specifications. In that consideration, the NFC component in Mbed OS should map with the relevant standards from the NFC Forum, and NFC Forum terminology should be used where possible. |
| kenjiArai | 1:9db0e321a9f4 | 98 | |
| kenjiArai | 1:9db0e321a9f4 | 99 | ## User-facing API |
| kenjiArai | 1:9db0e321a9f4 | 100 | |
| kenjiArai | 1:9db0e321a9f4 | 101 | The NFC API exposed to the user should provide high-level, object-oriented C++ APIs for the following: |
| kenjiArai | 1:9db0e321a9f4 | 102 | |
| kenjiArai | 1:9db0e321a9f4 | 103 | - Starting/Stopping a discovery loop. |
| kenjiArai | 1:9db0e321a9f4 | 104 | - Listing wired targets (NFC EEPROMs). |
| kenjiArai | 1:9db0e321a9f4 | 105 | - Exchanging NDEF messages with an initiator or a wired target. |
| kenjiArai | 1:9db0e321a9f4 | 106 | - Emulate ISO7816-4 applications if supported. |
| kenjiArai | 1:9db0e321a9f4 | 107 | |
| kenjiArai | 1:9db0e321a9f4 | 108 | ## Phase 1: MicroNFC stack integration |
| kenjiArai | 1:9db0e321a9f4 | 109 | |
| kenjiArai | 1:9db0e321a9f4 | 110 | The first step toward adding NFC to Mbed OS is the integration of the MicroNFC stack, which has drivers for the PN512 and derivatives. |
| kenjiArai | 1:9db0e321a9f4 | 111 | |
| kenjiArai | 1:9db0e321a9f4 | 112 | Architecture: |
| kenjiArai | 1:9db0e321a9f4 | 113 | |
| kenjiArai | 1:9db0e321a9f4 | 114 | ![phase_1_architecture] |
| kenjiArai | 1:9db0e321a9f4 | 115 | |
| kenjiArai | 1:9db0e321a9f4 | 116 | ## Phase 2: NFC host/controller split, NCI and NFC HAL API |
| kenjiArai | 1:9db0e321a9f4 | 117 | |
| kenjiArai | 1:9db0e321a9f4 | 118 | At the moment, the MicroNFC stack is split into two components: |
| kenjiArai | 1:9db0e321a9f4 | 119 | |
| kenjiArai | 1:9db0e321a9f4 | 120 | - Applications protocols and upper stack. |
| kenjiArai | 1:9db0e321a9f4 | 121 | - Transceiver-specific polling loop and drivers. |
| kenjiArai | 1:9db0e321a9f4 | 122 | |
| kenjiArai | 1:9db0e321a9f4 | 123 | To more closely match with the NFC Forum standard and add a well-defined way for Partners to add support for their transceivers, we will amend that split to be compliant with the NFC Forum's NFC Communication Interface (NCI) protocol. |
| kenjiArai | 1:9db0e321a9f4 | 124 | |
| kenjiArai | 1:9db0e321a9f4 | 125 | The generic part of the controller stack will be clearly separated, so Partners can use it if they wish (approach 1). |
| kenjiArai | 1:9db0e321a9f4 | 126 | |
| kenjiArai | 1:9db0e321a9f4 | 127 | For NFC controllers natively supporting the NCI protocol, Partners would only have to write a transport driver (approach 2). |
| kenjiArai | 1:9db0e321a9f4 | 128 | |
| kenjiArai | 1:9db0e321a9f4 | 129 | ![phase_2_architecture] |
| kenjiArai | 1:9db0e321a9f4 | 130 | |
| kenjiArai | 1:9db0e321a9f4 | 131 | Examples of NCI-compliant controllers: |
| kenjiArai | 1:9db0e321a9f4 | 132 | |
| kenjiArai | 1:9db0e321a9f4 | 133 | - ST ST21NFC. |
| kenjiArai | 1:9db0e321a9f4 | 134 | - NXP PN7120 and PN7150. |
| kenjiArai | 1:9db0e321a9f4 | 135 | |
| kenjiArai | 1:9db0e321a9f4 | 136 | Examples of transceivers that are *not* NCI-compliant: |
| kenjiArai | 1:9db0e321a9f4 | 137 | |
| kenjiArai | 1:9db0e321a9f4 | 138 | - NXP PN512. |
| kenjiArai | 1:9db0e321a9f4 | 139 | - NXP PN5180. |
| kenjiArai | 1:9db0e321a9f4 | 140 | - AMS AS395x series. |
| kenjiArai | 1:9db0e321a9f4 | 141 | |
| kenjiArai | 1:9db0e321a9f4 | 142 | # Detailed design |
| kenjiArai | 1:9db0e321a9f4 | 143 | |
| kenjiArai | 1:9db0e321a9f4 | 144 | ## User-facing APIs |
| kenjiArai | 1:9db0e321a9f4 | 145 | |
| kenjiArai | 1:9db0e321a9f4 | 146 | We designed the user-facing APIs with the following principles: |
| kenjiArai | 1:9db0e321a9f4 | 147 | |
| kenjiArai | 1:9db0e321a9f4 | 148 | - Abstracting the underlying complexities of NFC from the user. |
| kenjiArai | 1:9db0e321a9f4 | 149 | - Offering a high-level C++ object-oriented API to the user. |
| kenjiArai | 1:9db0e321a9f4 | 150 | - Ensuring compliance with the NFC Forum's standards and terminology. |
| kenjiArai | 1:9db0e321a9f4 | 151 | - Ensuring consistency with the Mbed OS codebase. |
| kenjiArai | 1:9db0e321a9f4 | 152 | |
| kenjiArai | 1:9db0e321a9f4 | 153 | Class diagram: |
| kenjiArai | 1:9db0e321a9f4 | 154 | |
| kenjiArai | 1:9db0e321a9f4 | 155 | ### NFC controller |
| kenjiArai | 1:9db0e321a9f4 | 156 | |
| kenjiArai | 1:9db0e321a9f4 | 157 | ![nfc_controller_diagram] |
| kenjiArai | 1:9db0e321a9f4 | 158 | |
| kenjiArai | 1:9db0e321a9f4 | 159 | The `NFCController` class is the entrypoint into NFC for the user. |
| kenjiArai | 1:9db0e321a9f4 | 160 | |
| kenjiArai | 1:9db0e321a9f4 | 161 | When NCI integration is complete (phase 2), this class will be able to drive a `NCIDriver` instance. For now, the one controller we support is the PN512, which implements the `NFCControllerDriver` class. This class is specific to the current MicroNFC release. |
| kenjiArai | 1:9db0e321a9f4 | 162 | |
| kenjiArai | 1:9db0e321a9f4 | 163 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 164 | NFCController(NFCControllerDriver *driver, events::EventQueue *queue, const Span<uint8_t> &ndef_buffer); |
| kenjiArai | 1:9db0e321a9f4 | 165 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 166 | |
| kenjiArai | 1:9db0e321a9f4 | 167 | The user instantiates the `NFCController` class using a driver, an event queue used for asynchronous operations and a scratch buffer used for NDEF processing. |
| kenjiArai | 1:9db0e321a9f4 | 168 | |
| kenjiArai | 1:9db0e321a9f4 | 169 | It offers the following methods: |
| kenjiArai | 1:9db0e321a9f4 | 170 | |
| kenjiArai | 1:9db0e321a9f4 | 171 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 172 | void set_delegate(Delegate *delegate); |
| kenjiArai | 1:9db0e321a9f4 | 173 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 174 | |
| kenjiArai | 1:9db0e321a9f4 | 175 | Set the instance's delegate. |
| kenjiArai | 1:9db0e321a9f4 | 176 | |
| kenjiArai | 1:9db0e321a9f4 | 177 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 178 | struct nfc_rf_protocols_bitmask_t |
| kenjiArai | 1:9db0e321a9f4 | 179 | { |
| kenjiArai | 1:9db0e321a9f4 | 180 | uint8_t initiator_t1t : 1; |
| kenjiArai | 1:9db0e321a9f4 | 181 | uint8_t initiator_t2t : 1; |
| kenjiArai | 1:9db0e321a9f4 | 182 | uint8_t initiator_t3t : 1; |
| kenjiArai | 1:9db0e321a9f4 | 183 | uint8_t initiator_iso_dep : 1; |
| kenjiArai | 1:9db0e321a9f4 | 184 | uint8_t initiator_nfc_dep : 1; |
| kenjiArai | 1:9db0e321a9f4 | 185 | uint8_t initiator_t5t : 1; |
| kenjiArai | 1:9db0e321a9f4 | 186 | |
| kenjiArai | 1:9db0e321a9f4 | 187 | uint8_t target_t1t : 1; |
| kenjiArai | 1:9db0e321a9f4 | 188 | uint8_t target_t2t : 1; |
| kenjiArai | 1:9db0e321a9f4 | 189 | uint8_t target_t3t : 1; |
| kenjiArai | 1:9db0e321a9f4 | 190 | uint8_t target_iso_dep : 1; |
| kenjiArai | 1:9db0e321a9f4 | 191 | uint8_t target_nfc_dep : 1; |
| kenjiArai | 1:9db0e321a9f4 | 192 | uint8_t target_t5t : 1; |
| kenjiArai | 1:9db0e321a9f4 | 193 | }; |
| kenjiArai | 1:9db0e321a9f4 | 194 | |
| kenjiArai | 1:9db0e321a9f4 | 195 | nfc_rf_protocols_bitmask_t get_supported_rf_protocols() const; |
| kenjiArai | 1:9db0e321a9f4 | 196 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 197 | |
| kenjiArai | 1:9db0e321a9f4 | 198 | Retrieve the list of supported RF protocols. These are mapped against NFC Forum-defined protocols. |
| kenjiArai | 1:9db0e321a9f4 | 199 | |
| kenjiArai | 1:9db0e321a9f4 | 200 | - T1T is based on ISO/IEC 14443A-3 and commonly known as Topaz (Innovision). |
| kenjiArai | 1:9db0e321a9f4 | 201 | - T2T is based on ISO/IEC 14443A-3 and commonly known as Mifare Ultralight/NTAG (NXP). |
| kenjiArai | 1:9db0e321a9f4 | 202 | - T3T is based on JIS X6319-4, also known as Felica (Sony). |
| kenjiArai | 1:9db0e321a9f4 | 203 | - ISO-DEP is based on ISO/IEC 14443-4 and is the common interface for contactless smartcards. The underlying radio protocol can either be ISO/IEC 14443A or ISO/IEC 14443B. |
| kenjiArai | 1:9db0e321a9f4 | 204 | - NFC-DEP is based on ISO/IEC 18092/FIXME and is the basis for NFC peer-to-peer communication. |
| kenjiArai | 1:9db0e321a9f4 | 205 | - T5T is also known as ISO/IEC 15963. |
| kenjiArai | 1:9db0e321a9f4 | 206 | |
| kenjiArai | 1:9db0e321a9f4 | 207 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 208 | nfc_err_t initialize(); |
| kenjiArai | 1:9db0e321a9f4 | 209 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 210 | |
| kenjiArai | 1:9db0e321a9f4 | 211 | Initialize the NFC controller. |
| kenjiArai | 1:9db0e321a9f4 | 212 | |
| kenjiArai | 1:9db0e321a9f4 | 213 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 214 | nfc_err_t configure_rf_protocols(nfc_rf_protocols_bitmask_t rf_protocols); |
| kenjiArai | 1:9db0e321a9f4 | 215 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 216 | |
| kenjiArai | 1:9db0e321a9f4 | 217 | Configure which protocols should be enabled during the discovery process. |
| kenjiArai | 1:9db0e321a9f4 | 218 | |
| kenjiArai | 1:9db0e321a9f4 | 219 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 220 | nfc_err_t start_discovery(); |
| kenjiArai | 1:9db0e321a9f4 | 221 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 222 | |
| kenjiArai | 1:9db0e321a9f4 | 223 | Start the discovery process. |
| kenjiArai | 1:9db0e321a9f4 | 224 | |
| kenjiArai | 1:9db0e321a9f4 | 225 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 226 | nfc_err_t cancel_discovery(); |
| kenjiArai | 1:9db0e321a9f4 | 227 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 228 | |
| kenjiArai | 1:9db0e321a9f4 | 229 | Cancel the discovery process (if running). |
| kenjiArai | 1:9db0e321a9f4 | 230 | |
| kenjiArai | 1:9db0e321a9f4 | 231 | **Delegate** |
| kenjiArai | 1:9db0e321a9f4 | 232 | |
| kenjiArai | 1:9db0e321a9f4 | 233 | A `NFCController` instance needs to be configured with a delegate to receive events. |
| kenjiArai | 1:9db0e321a9f4 | 234 | |
| kenjiArai | 1:9db0e321a9f4 | 235 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 236 | enum nfc_discovery_terminated_reason_t { |
| kenjiArai | 1:9db0e321a9f4 | 237 | nfc_discovery_terminated_completed = 0 |
| kenjiArai | 1:9db0e321a9f4 | 238 | nfc_discovery_terminated_canceled, |
| kenjiArai | 1:9db0e321a9f4 | 239 | nfc_discovery_terminated_rf_error |
| kenjiArai | 1:9db0e321a9f4 | 240 | }; |
| kenjiArai | 1:9db0e321a9f4 | 241 | |
| kenjiArai | 1:9db0e321a9f4 | 242 | void on_discovery_terminated(nfc_discovery_terminated_reason_t reason); |
| kenjiArai | 1:9db0e321a9f4 | 243 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 244 | |
| kenjiArai | 1:9db0e321a9f4 | 245 | Let the user know when a discovery loop has been terminated (either because endpoints have been found, the user canceled it or an error occurred). |
| kenjiArai | 1:9db0e321a9f4 | 246 | |
| kenjiArai | 1:9db0e321a9f4 | 247 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 248 | void on_nfc_initiator_discovered(const mbed::SharedPtr<NFCRemoteInitiator> &nfc_initiator); |
| kenjiArai | 1:9db0e321a9f4 | 249 | |
| kenjiArai | 1:9db0e321a9f4 | 250 | void on_nfc_target_discovered(const mbed::SharedPtr<NFCRemoteTarget> &nfc_target); |
| kenjiArai | 1:9db0e321a9f4 | 251 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 252 | |
| kenjiArai | 1:9db0e321a9f4 | 253 | These methods called when a remote initiator (the local controller is acting as a target) or a remote target (the local controller is acting as an initiator) is detected. |
| kenjiArai | 1:9db0e321a9f4 | 254 | |
| kenjiArai | 1:9db0e321a9f4 | 255 | These methods use shared pointers, so the user does not have to maintain the lifetime of these objects. The `NFCController` instance releases its reference when the endpoint is lost (see below). |
| kenjiArai | 1:9db0e321a9f4 | 256 | |
| kenjiArai | 1:9db0e321a9f4 | 257 | ### Endpoints |
| kenjiArai | 1:9db0e321a9f4 | 258 | |
| kenjiArai | 1:9db0e321a9f4 | 259 | ![nfc_endpoints_diagram] |
| kenjiArai | 1:9db0e321a9f4 | 260 | |
| kenjiArai | 1:9db0e321a9f4 | 261 | #### NFC remote endpoint |
| kenjiArai | 1:9db0e321a9f4 | 262 | |
| kenjiArai | 1:9db0e321a9f4 | 263 | A remote endpoint is a generic NFC-enabled device with which the controller is communicating over the air interface: |
| kenjiArai | 1:9db0e321a9f4 | 264 | |
| kenjiArai | 1:9db0e321a9f4 | 265 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 266 | nfc_err_t connect(); |
| kenjiArai | 1:9db0e321a9f4 | 267 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 268 | |
| kenjiArai | 1:9db0e321a9f4 | 269 | Establish a connection with the remote endpoint. |
| kenjiArai | 1:9db0e321a9f4 | 270 | |
| kenjiArai | 1:9db0e321a9f4 | 271 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 272 | nfc_err_t disconnect(); |
| kenjiArai | 1:9db0e321a9f4 | 273 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 274 | |
| kenjiArai | 1:9db0e321a9f4 | 275 | Drop the connection with the remote endpoint. |
| kenjiArai | 1:9db0e321a9f4 | 276 | |
| kenjiArai | 1:9db0e321a9f4 | 277 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 278 | bool is_connected() const; |
| kenjiArai | 1:9db0e321a9f4 | 279 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 280 | |
| kenjiArai | 1:9db0e321a9f4 | 281 | Set to true when the remote endpoint activates the connection and selects it. |
| kenjiArai | 1:9db0e321a9f4 | 282 | |
| kenjiArai | 1:9db0e321a9f4 | 283 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 284 | bool is_disconnected() const; |
| kenjiArai | 1:9db0e321a9f4 | 285 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 286 | |
| kenjiArai | 1:9db0e321a9f4 | 287 | Set to true when the remote endpoint is lost and the `NFCController` instance releases its reference to the shared pointer. |
| kenjiArai | 1:9db0e321a9f4 | 288 | |
| kenjiArai | 1:9db0e321a9f4 | 289 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 290 | nfc_rf_protocols_bitmask_t rf_protocols() const; |
| kenjiArai | 1:9db0e321a9f4 | 291 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 292 | |
| kenjiArai | 1:9db0e321a9f4 | 293 | List the RF protocols that have been activated to communicate with that endpoint. |
| kenjiArai | 1:9db0e321a9f4 | 294 | |
| kenjiArai | 1:9db0e321a9f4 | 295 | **Delegate** |
| kenjiArai | 1:9db0e321a9f4 | 296 | |
| kenjiArai | 1:9db0e321a9f4 | 297 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 298 | virtual void on_connected(); |
| kenjiArai | 1:9db0e321a9f4 | 299 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 300 | |
| kenjiArai | 1:9db0e321a9f4 | 301 | This is called when a connection to this endpoint is succesfully established. |
| kenjiArai | 1:9db0e321a9f4 | 302 | |
| kenjiArai | 1:9db0e321a9f4 | 303 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 304 | virtual void on_disconnected(); |
| kenjiArai | 1:9db0e321a9f4 | 305 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 306 | |
| kenjiArai | 1:9db0e321a9f4 | 307 | This is called when this endpoint is lost and the controller instance is about to release the reference to the shared pointer. |
| kenjiArai | 1:9db0e321a9f4 | 308 | |
| kenjiArai | 1:9db0e321a9f4 | 309 | #### NFC NDEF capable |
| kenjiArai | 1:9db0e321a9f4 | 310 | |
| kenjiArai | 1:9db0e321a9f4 | 311 | This class is the ancestor class for all endpoints which have the capability of handling NDEF data. |
| kenjiArai | 1:9db0e321a9f4 | 312 | |
| kenjiArai | 1:9db0e321a9f4 | 313 | User-facing API: |
| kenjiArai | 1:9db0e321a9f4 | 314 | |
| kenjiArai | 1:9db0e321a9f4 | 315 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 316 | NFCNDEFCapable(const Span<uint8_t> &buffer); |
| kenjiArai | 1:9db0e321a9f4 | 317 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 318 | |
| kenjiArai | 1:9db0e321a9f4 | 319 | The class is constructed using a scratch buffer which is used to encode and/or decode NDEF messages. |
| kenjiArai | 1:9db0e321a9f4 | 320 | |
| kenjiArai | 1:9db0e321a9f4 | 321 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 322 | bool is_ndef_supported() const; |
| kenjiArai | 1:9db0e321a9f4 | 323 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 324 | |
| kenjiArai | 1:9db0e321a9f4 | 325 | API used by descendant classes: |
| kenjiArai | 1:9db0e321a9f4 | 326 | |
| kenjiArai | 1:9db0e321a9f4 | 327 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 328 | void parse_ndef_message(const ac_buffer_t &buffer); |
| kenjiArai | 1:9db0e321a9f4 | 329 | void build_ndef_message(ac_buffer_builder_t &buffer_builder); |
| kenjiArai | 1:9db0e321a9f4 | 330 | ndef_msg_t *ndef_message(); |
| kenjiArai | 1:9db0e321a9f4 | 331 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 332 | |
| kenjiArai | 1:9db0e321a9f4 | 333 | API implemented by descendant classes: |
| kenjiArai | 1:9db0e321a9f4 | 334 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 335 | virtual NFCNDEFCapable::Delegate *ndef_capable_delegate(); |
| kenjiArai | 1:9db0e321a9f4 | 336 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 337 | |
| kenjiArai | 1:9db0e321a9f4 | 338 | **Delegate** |
| kenjiArai | 1:9db0e321a9f4 | 339 | |
| kenjiArai | 1:9db0e321a9f4 | 340 | The instance receives requests to encode and decode NDEF messages, and the user can choose how to handle them using the relevant builders and parsers. |
| kenjiArai | 1:9db0e321a9f4 | 341 | |
| kenjiArai | 1:9db0e321a9f4 | 342 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 343 | void parse_ndef_message(const Span<const uint8_t> &buffer); |
| kenjiArai | 1:9db0e321a9f4 | 344 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 345 | |
| kenjiArai | 1:9db0e321a9f4 | 346 | The user receives the encoded NDEF message for processing. |
| kenjiArai | 1:9db0e321a9f4 | 347 | |
| kenjiArai | 1:9db0e321a9f4 | 348 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 349 | size_t build_ndef_message(const Span<uint8_t> &buffer); |
| kenjiArai | 1:9db0e321a9f4 | 350 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 351 | |
| kenjiArai | 1:9db0e321a9f4 | 352 | The user can encode a NDEF message in the buffer provided and return its size (or 0). |
| kenjiArai | 1:9db0e321a9f4 | 353 | |
| kenjiArai | 1:9db0e321a9f4 | 354 | #### NFC remote initiator |
| kenjiArai | 1:9db0e321a9f4 | 355 | |
| kenjiArai | 1:9db0e321a9f4 | 356 | This class derives from the base `NFCRemoteEndpoint` and `NFCNDEFCapable` classes. |
| kenjiArai | 1:9db0e321a9f4 | 357 | |
| kenjiArai | 1:9db0e321a9f4 | 358 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 359 | enum nfc_tag_type_t { |
| kenjiArai | 1:9db0e321a9f4 | 360 | nfc_tag_type_1, |
| kenjiArai | 1:9db0e321a9f4 | 361 | nfc_tag_type_2, |
| kenjiArai | 1:9db0e321a9f4 | 362 | nfc_tag_type_3, |
| kenjiArai | 1:9db0e321a9f4 | 363 | nfc_tag_type_4a, |
| kenjiArai | 1:9db0e321a9f4 | 364 | nfc_tag_type_4b, |
| kenjiArai | 1:9db0e321a9f4 | 365 | nfc_tag_type_5 |
| kenjiArai | 1:9db0e321a9f4 | 366 | }; |
| kenjiArai | 1:9db0e321a9f4 | 367 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 368 | |
| kenjiArai | 1:9db0e321a9f4 | 369 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 370 | nfc_tag_type_t nfc_tag_type(); |
| kenjiArai | 1:9db0e321a9f4 | 371 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 372 | |
| kenjiArai | 1:9db0e321a9f4 | 373 | Additionally, the user can recover the type of NFC tag (1 to 5) being emulated. Type 4 is implemented on either one of two technologies; therefore, this enum both includes type 4a and type 4b to identify the underlying technology. |
| kenjiArai | 1:9db0e321a9f4 | 374 | |
| kenjiArai | 1:9db0e321a9f4 | 375 | *Note: ISO7816 is only used internally for the initial release* |
| kenjiArai | 1:9db0e321a9f4 | 376 | |
| kenjiArai | 1:9db0e321a9f4 | 377 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 378 | bool is_iso7816_supported(); |
| kenjiArai | 1:9db0e321a9f4 | 379 | void add_iso7816_application(nfc_tech_iso7816_app_t *application); |
| kenjiArai | 1:9db0e321a9f4 | 380 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 381 | |
| kenjiArai | 1:9db0e321a9f4 | 382 | If the underlying technology supports it (ISO-DEP), the user can emulate a contactless smartcard and register ISO7816-4 applications using this API. |
| kenjiArai | 1:9db0e321a9f4 | 383 | |
| kenjiArai | 1:9db0e321a9f4 | 384 | **Delegate** |
| kenjiArai | 1:9db0e321a9f4 | 385 | |
| kenjiArai | 1:9db0e321a9f4 | 386 | The delegate derives from delegates of `NFCRemoteEndpoint` and `NFCNDEFCapable`. |
| kenjiArai | 1:9db0e321a9f4 | 387 | |
| kenjiArai | 1:9db0e321a9f4 | 388 | #### NFC target |
| kenjiArai | 1:9db0e321a9f4 | 389 | |
| kenjiArai | 1:9db0e321a9f4 | 390 | This is the base class for NFC targets that can be of two types: |
| kenjiArai | 1:9db0e321a9f4 | 391 | |
| kenjiArai | 1:9db0e321a9f4 | 392 | - NFC EEPROMs (Dual-interface wired devices). |
| kenjiArai | 1:9db0e321a9f4 | 393 | - Remote NFC targets (NFC devices over NFC RF interface). |
| kenjiArai | 1:9db0e321a9f4 | 394 | |
| kenjiArai | 1:9db0e321a9f4 | 395 | Apart from the actual transport (wired or NFC), the use is similar, which explains why these methods are shared across these devices types. |
| kenjiArai | 1:9db0e321a9f4 | 396 | |
| kenjiArai | 1:9db0e321a9f4 | 397 | This class derives from `NFCNDEFCapable`. |
| kenjiArai | 1:9db0e321a9f4 | 398 | |
| kenjiArai | 1:9db0e321a9f4 | 399 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 400 | void write_ndef_message(); |
| kenjiArai | 1:9db0e321a9f4 | 401 | void erase_ndef_message(); |
| kenjiArai | 1:9db0e321a9f4 | 402 | void read_ndef_message(); |
| kenjiArai | 1:9db0e321a9f4 | 403 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 404 | |
| kenjiArai | 1:9db0e321a9f4 | 405 | The user can trigger the appropriate NDEF parsing/building process using these methods if handlers are registered in the `NFCNDEFCapable` instance. |
| kenjiArai | 1:9db0e321a9f4 | 406 | |
| kenjiArai | 1:9db0e321a9f4 | 407 | **Delegate** |
| kenjiArai | 1:9db0e321a9f4 | 408 | |
| kenjiArai | 1:9db0e321a9f4 | 409 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 410 | void on_ndef_message_erased(nfc_err_t result); |
| kenjiArai | 1:9db0e321a9f4 | 411 | void on_ndef_message_written(nfc_err_t result); |
| kenjiArai | 1:9db0e321a9f4 | 412 | void on_ndef_message_read(nfc_err_t result); |
| kenjiArai | 1:9db0e321a9f4 | 413 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 414 | |
| kenjiArai | 1:9db0e321a9f4 | 415 | #### NFC EEPROM |
| kenjiArai | 1:9db0e321a9f4 | 416 | |
| kenjiArai | 1:9db0e321a9f4 | 417 | The `NFCEEPROM` class derives from `NFCTarget` and shares the same API. The user must pass a pointer to a `NFCEEPROMDriver` instance (see below) in the constructor. |
| kenjiArai | 1:9db0e321a9f4 | 418 | |
| kenjiArai | 1:9db0e321a9f4 | 419 | #### NFC remote target |
| kenjiArai | 1:9db0e321a9f4 | 420 | |
| kenjiArai | 1:9db0e321a9f4 | 421 | *Note: This is out of scope for the initial release* |
| kenjiArai | 1:9db0e321a9f4 | 422 | |
| kenjiArai | 1:9db0e321a9f4 | 423 | The `NFCRemoteTarget` class derives from `NFCTarget` and additionally from `NFCRemoteEndpoint`. |
| kenjiArai | 1:9db0e321a9f4 | 424 | |
| kenjiArai | 1:9db0e321a9f4 | 425 | ## NDEF API |
| kenjiArai | 1:9db0e321a9f4 | 426 | |
| kenjiArai | 1:9db0e321a9f4 | 427 | The NDEF API is constructed with these requirements: |
| kenjiArai | 1:9db0e321a9f4 | 428 | |
| kenjiArai | 1:9db0e321a9f4 | 429 | - Minimizing memory allocation and copies. |
| kenjiArai | 1:9db0e321a9f4 | 430 | - NFC Forum compliance. |
| kenjiArai | 1:9db0e321a9f4 | 431 | - Ease of use. |
| kenjiArai | 1:9db0e321a9f4 | 432 | - Extensibility. |
| kenjiArai | 1:9db0e321a9f4 | 433 | |
| kenjiArai | 1:9db0e321a9f4 | 434 | ### Common objects |
| kenjiArai | 1:9db0e321a9f4 | 435 | |
| kenjiArai | 1:9db0e321a9f4 | 436 | We will provide multiple helpers to make it easy to create and parse common record types: |
| kenjiArai | 1:9db0e321a9f4 | 437 | |
| kenjiArai | 1:9db0e321a9f4 | 438 | - URI. |
| kenjiArai | 1:9db0e321a9f4 | 439 | - Text. |
| kenjiArai | 1:9db0e321a9f4 | 440 | - Smart poster. |
| kenjiArai | 1:9db0e321a9f4 | 441 | - MIME data. |
| kenjiArai | 1:9db0e321a9f4 | 442 | |
| kenjiArai | 1:9db0e321a9f4 | 443 | For instance, the `URI`'s class API is: |
| kenjiArai | 1:9db0e321a9f4 | 444 | |
| kenjiArai | 1:9db0e321a9f4 | 445 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 446 | void set_uri(uri_identifier_code_t id, const Span<const uint8_t> &uri_field) |
| kenjiArai | 1:9db0e321a9f4 | 447 | |
| kenjiArai | 1:9db0e321a9f4 | 448 | uri_identifier_code_t get_id() const; |
| kenjiArai | 1:9db0e321a9f4 | 449 | Span<const uint8_t> get_uri_field() const; |
| kenjiArai | 1:9db0e321a9f4 | 450 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 451 | |
| kenjiArai | 1:9db0e321a9f4 | 452 | **Note:** These types can be replaced by user defined ones if parsing and serialization logic is provided. |
| kenjiArai | 1:9db0e321a9f4 | 453 | |
| kenjiArai | 1:9db0e321a9f4 | 454 | ### Parsing |
| kenjiArai | 1:9db0e321a9f4 | 455 | |
| kenjiArai | 1:9db0e321a9f4 | 456 | #### ndef::MessageParser |
| kenjiArai | 1:9db0e321a9f4 | 457 | |
| kenjiArai | 1:9db0e321a9f4 | 458 | ![ndef_message_parser_diagram] |
| kenjiArai | 1:9db0e321a9f4 | 459 | |
| kenjiArai | 1:9db0e321a9f4 | 460 | A `MessageParser`, which produces `Record` instances to its client, parses messages incoming from the peer. The parsing operation is event-driven: A message parser client registers a delegate inside the message parser. This delegate is notified whenever an interesting event happens during the parsing. |
| kenjiArai | 1:9db0e321a9f4 | 461 | |
| kenjiArai | 1:9db0e321a9f4 | 462 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 463 | void set_delegate(Delegate *delegate); |
| kenjiArai | 1:9db0e321a9f4 | 464 | void parse(const Span<const uint8_t> &data_buffer); |
| kenjiArai | 1:9db0e321a9f4 | 465 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 466 | |
| kenjiArai | 1:9db0e321a9f4 | 467 | It is important to note that the data_buffer in the entry of the parse function must contain the entire NDEF message. |
| kenjiArai | 1:9db0e321a9f4 | 468 | |
| kenjiArai | 1:9db0e321a9f4 | 469 | ##### ndef::MessageParser::Delegate |
| kenjiArai | 1:9db0e321a9f4 | 470 | |
| kenjiArai | 1:9db0e321a9f4 | 471 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 472 | virtual void on_parsing_started() { } |
| kenjiArai | 1:9db0e321a9f4 | 473 | virtual void on_record_parsed(const Record &record) { } |
| kenjiArai | 1:9db0e321a9f4 | 474 | virtual void on_parsing_terminated() { } |
| kenjiArai | 1:9db0e321a9f4 | 475 | virtual void on_parsing_error(MessageParser::error_t error) { } |
| kenjiArai | 1:9db0e321a9f4 | 476 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 477 | |
| kenjiArai | 1:9db0e321a9f4 | 478 | The delegate is notified by the parser when the parsing starts or ends, when an error is encountered or when an NDEF `Record` has been parsed. |
| kenjiArai | 1:9db0e321a9f4 | 479 | |
| kenjiArai | 1:9db0e321a9f4 | 480 | To reduce memory consumption, `Record` instances generated by the parser are short lived. They are only valid during the callback invocation. If a client is interested in the content of a message parsed and wants to use it after the parsing callback, then it must make a copy of the record object. |
| kenjiArai | 1:9db0e321a9f4 | 481 | |
| kenjiArai | 1:9db0e321a9f4 | 482 | #### NDEF record parsing |
| kenjiArai | 1:9db0e321a9f4 | 483 | |
| kenjiArai | 1:9db0e321a9f4 | 484 | ![ndef_record_parser_diagram] |
| kenjiArai | 1:9db0e321a9f4 | 485 | |
| kenjiArai | 1:9db0e321a9f4 | 486 | NDEF records can contain any type of content. Therefore, parsing of records is specific to the application. To help the developer, an optional NDEF record parsing framework is included. It follows the _chain-of-responsibility_ design pattern that facilitates the integration of record parsers defined by client code. |
| kenjiArai | 1:9db0e321a9f4 | 487 | |
| kenjiArai | 1:9db0e321a9f4 | 488 | ##### ndef::RecordParser |
| kenjiArai | 1:9db0e321a9f4 | 489 | |
| kenjiArai | 1:9db0e321a9f4 | 490 | It is the base building block of the record parsing frame working. It parses a record then returns true if the record has been parsed or false otherwise. |
| kenjiArai | 1:9db0e321a9f4 | 491 | |
| kenjiArai | 1:9db0e321a9f4 | 492 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 493 | virtual bool parse(const Record&); |
| kenjiArai | 1:9db0e321a9f4 | 494 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 495 | |
| kenjiArai | 1:9db0e321a9f4 | 496 | ##### ndef::RecordParserChain |
| kenjiArai | 1:9db0e321a9f4 | 497 | |
| kenjiArai | 1:9db0e321a9f4 | 498 | It aggregates `RecordParser` instances and defers parsing to the instances it contains. |
| kenjiArai | 1:9db0e321a9f4 | 499 | |
| kenjiArai | 1:9db0e321a9f4 | 500 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 501 | bool parse(const Record &record); |
| kenjiArai | 1:9db0e321a9f4 | 502 | void set_next_parser(RecordParser *parser); |
| kenjiArai | 1:9db0e321a9f4 | 503 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 504 | |
| kenjiArai | 1:9db0e321a9f4 | 505 | ##### ndef::GenericRecordParser<ParserImplementation, ParsingResult> |
| kenjiArai | 1:9db0e321a9f4 | 506 | |
| kenjiArai | 1:9db0e321a9f4 | 507 | This is a partial implementation of the `RecordParser` interface. It exposes a delegate type that clients of this parser can implement and register. This delegate expects objects of the parsing result type. |
| kenjiArai | 1:9db0e321a9f4 | 508 | |
| kenjiArai | 1:9db0e321a9f4 | 509 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 510 | bool parse(const Record&) |
| kenjiArai | 1:9db0e321a9f4 | 511 | void set_delegate(Delegate *delegate) |
| kenjiArai | 1:9db0e321a9f4 | 512 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 513 | |
| kenjiArai | 1:9db0e321a9f4 | 514 | Implementation of this class must expose the following nonvirtual function: |
| kenjiArai | 1:9db0e321a9f4 | 515 | |
| kenjiArai | 1:9db0e321a9f4 | 516 | ```c++ |
| kenjiArai | 1:9db0e321a9f4 | 517 | bool do_parse(const Record &record, ParsingResult &parsing_result); |
| kenjiArai | 1:9db0e321a9f4 | 518 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 519 | |
| kenjiArai | 1:9db0e321a9f4 | 520 | If the parsing is successful, then it should return true and fill `parsing_result`; otherwise, it should return false and leave `parsing_result` untouched. |
| kenjiArai | 1:9db0e321a9f4 | 521 | |
| kenjiArai | 1:9db0e321a9f4 | 522 | **Note:** The Curiously recurring template pattern (CRTP) is used to implement the delegation mechanism in a type-safe fashion. This is not achievable with _regular_ polymorphism. |
| kenjiArai | 1:9db0e321a9f4 | 523 | |
| kenjiArai | 1:9db0e321a9f4 | 524 | ###### ndef::GenericRecordParser<ParserImplementation, ParsingResult>::Delegate |
| kenjiArai | 1:9db0e321a9f4 | 525 | |
| kenjiArai | 1:9db0e321a9f4 | 526 | Clients of this class must implement this delegate. It receives the objects parsed. |
| kenjiArai | 1:9db0e321a9f4 | 527 | |
| kenjiArai | 1:9db0e321a9f4 | 528 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 529 | virtual void on_record_parsed(const ParsingResult &record, const RecordID *id); |
| kenjiArai | 1:9db0e321a9f4 | 530 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 531 | |
| kenjiArai | 1:9db0e321a9f4 | 532 | **Note:** Usually, clients are client of an implementation of an ndef::GenericRecordParser<ParserImplementation, ParsingResult> . They can refer to the delegate as `ImplementationName::Delegate`. |
| kenjiArai | 1:9db0e321a9f4 | 533 | |
| kenjiArai | 1:9db0e321a9f4 | 534 | #### Common parsers |
| kenjiArai | 1:9db0e321a9f4 | 535 | |
| kenjiArai | 1:9db0e321a9f4 | 536 | ![ndef_common_parsers_diagram] |
| kenjiArai | 1:9db0e321a9f4 | 537 | |
| kenjiArai | 1:9db0e321a9f4 | 538 | Parsers for each common record type exist. They inherit from the `GenericRecordParser` to exposes a common delegate interface: |
| kenjiArai | 1:9db0e321a9f4 | 539 | |
| kenjiArai | 1:9db0e321a9f4 | 540 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 541 | virtual void on_record_parsed(const <ParsedType> &result, const ndef::RecordID *id) |
| kenjiArai | 1:9db0e321a9f4 | 542 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 543 | |
| kenjiArai | 1:9db0e321a9f4 | 544 | #### Simple parser |
| kenjiArai | 1:9db0e321a9f4 | 545 | |
| kenjiArai | 1:9db0e321a9f4 | 546 | The APIs provide a class named `SimpleMessageParser` that glues together a `MessageParser` and a chain `RecordParser` containing the parsers for the common types. |
| kenjiArai | 1:9db0e321a9f4 | 547 | |
| kenjiArai | 1:9db0e321a9f4 | 548 | ![ndef_simple_parser_diagram] |
| kenjiArai | 1:9db0e321a9f4 | 549 | |
| kenjiArai | 1:9db0e321a9f4 | 550 | Clients of the class can register a delegate, parse a message or add a new `RecordParser` in the parsing chain. |
| kenjiArai | 1:9db0e321a9f4 | 551 | |
| kenjiArai | 1:9db0e321a9f4 | 552 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 553 | void set_delegate(Delegate *delegate); |
| kenjiArai | 1:9db0e321a9f4 | 554 | void parse(const Span<const uint8_t> &data_buffer); |
| kenjiArai | 1:9db0e321a9f4 | 555 | void add_record_parser(ndef::RecordParser *parser); |
| kenjiArai | 1:9db0e321a9f4 | 556 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 557 | |
| kenjiArai | 1:9db0e321a9f4 | 558 | ##### Delegate |
| kenjiArai | 1:9db0e321a9f4 | 559 | |
| kenjiArai | 1:9db0e321a9f4 | 560 | Clients of this class must implement this delegate. It receives events from the parsing process: |
| kenjiArai | 1:9db0e321a9f4 | 561 | |
| kenjiArai | 1:9db0e321a9f4 | 562 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 563 | virtual void on_parsing_error(ndef::MessageParser::error_t error); |
| kenjiArai | 1:9db0e321a9f4 | 564 | virtual void on_parsing_started(); |
| kenjiArai | 1:9db0e321a9f4 | 565 | virtual void on_text_parsed(const Text& text, const ndef::RecordID &id); |
| kenjiArai | 1:9db0e321a9f4 | 566 | virtual void on_mime_parsed(const Mime& text, const ndef::RecordID &id); |
| kenjiArai | 1:9db0e321a9f4 | 567 | virtual void on_uri_parsed(const URI& uri, const ndef::RecordID &id); |
| kenjiArai | 1:9db0e321a9f4 | 568 | virtual void on_unknown_record_parsed(const ndef::Record &record); |
| kenjiArai | 1:9db0e321a9f4 | 569 | virtual void on_parsing_terminated(); |
| kenjiArai | 1:9db0e321a9f4 | 570 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 571 | |
| kenjiArai | 1:9db0e321a9f4 | 572 | ### Serialization |
| kenjiArai | 1:9db0e321a9f4 | 573 | |
| kenjiArai | 1:9db0e321a9f4 | 574 | The class `MessageBuilder` is used to map a record into an NDEF message. It includes a data buffer that contains the _raw_ message. Client code uses the function `append_record` to append a new record into the message being built. |
| kenjiArai | 1:9db0e321a9f4 | 575 | |
| kenjiArai | 1:9db0e321a9f4 | 576 | ![ndef_message_builder_diagram] |
| kenjiArai | 1:9db0e321a9f4 | 577 | |
| kenjiArai | 1:9db0e321a9f4 | 578 | For convenience, serialization functions for common types are provided in the common types we provide. |
| kenjiArai | 1:9db0e321a9f4 | 579 | |
| kenjiArai | 1:9db0e321a9f4 | 580 | ## HAL APIs |
| kenjiArai | 1:9db0e321a9f4 | 581 | |
| kenjiArai | 1:9db0e321a9f4 | 582 | ### NFC EEPROM API |
| kenjiArai | 1:9db0e321a9f4 | 583 | |
| kenjiArai | 1:9db0e321a9f4 | 584 | To create the hardware-specific APIs to add support for a new NFC EEPROM, vendors need to derive from `NFCEEPROMDriver` and implement its virtual methods. |
| kenjiArai | 1:9db0e321a9f4 | 585 | |
| kenjiArai | 1:9db0e321a9f4 | 586 | From the upper layer's point of view, the EEPROM is a byte array that can be read from or written to. Long operations (reads, writes, erasures) must happen asynchronously. Booleans indicate whether a particular operation was succesful. |
| kenjiArai | 1:9db0e321a9f4 | 587 | |
| kenjiArai | 1:9db0e321a9f4 | 588 | Address 0 means the start of the NDEF buffer (not necessarily at address 0 in the EEPROM). |
| kenjiArai | 1:9db0e321a9f4 | 589 | |
| kenjiArai | 1:9db0e321a9f4 | 590 | When a buffer is passed to the backend, the reference remains valid until the corresponding event is called. |
| kenjiArai | 1:9db0e321a9f4 | 591 | |
| kenjiArai | 1:9db0e321a9f4 | 592 | The `set_size()` command is called to change the size of the NDEF buffer (within the limits set by `get_max_size()`). Inversely, that buffer size can be read using `get_size()`. |
| kenjiArai | 1:9db0e321a9f4 | 593 | |
| kenjiArai | 1:9db0e321a9f4 | 594 | `start_session()` and `end_session()` are used before a series of memory operations to allow the driver to lock or unlock the RF interface during these operations to avoid having concurrent access to the memory. |
| kenjiArai | 1:9db0e321a9f4 | 595 | |
| kenjiArai | 1:9db0e321a9f4 | 596 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 597 | void reset(); |
| kenjiArai | 1:9db0e321a9f4 | 598 | size_t get_max_size(); |
| kenjiArai | 1:9db0e321a9f4 | 599 | void start_session(bool force = true); |
| kenjiArai | 1:9db0e321a9f4 | 600 | void end_session(); |
| kenjiArai | 1:9db0e321a9f4 | 601 | void read_bytes(uint32_t address, size_t count); |
| kenjiArai | 1:9db0e321a9f4 | 602 | void write_bytes(uint32_t address, const uint8_t *bytes, size_t count); |
| kenjiArai | 1:9db0e321a9f4 | 603 | void read_size(size_t count); |
| kenjiArai | 1:9db0e321a9f4 | 604 | void write_size(); |
| kenjiArai | 1:9db0e321a9f4 | 605 | void erase_bytes(uint32_t address, size_t size) |
| kenjiArai | 1:9db0e321a9f4 | 606 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 607 | |
| kenjiArai | 1:9db0e321a9f4 | 608 | The following events must be called to signal completion of long operations: |
| kenjiArai | 1:9db0e321a9f4 | 609 | |
| kenjiArai | 1:9db0e321a9f4 | 610 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 611 | void on_session_started(bool success); |
| kenjiArai | 1:9db0e321a9f4 | 612 | void on_session_ended(bool success); |
| kenjiArai | 1:9db0e321a9f4 | 613 | void on_bytes_read(size_t count); |
| kenjiArai | 1:9db0e321a9f4 | 614 | void on_bytes_written(size_t count); |
| kenjiArai | 1:9db0e321a9f4 | 615 | void on_size_read(bool success, size_t size); |
| kenjiArai | 1:9db0e321a9f4 | 616 | void on_size_written(bool success); |
| kenjiArai | 1:9db0e321a9f4 | 617 | void on_bytes_erased(size_t count); |
| kenjiArai | 1:9db0e321a9f4 | 618 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 619 | |
| kenjiArai | 1:9db0e321a9f4 | 620 | The implementation also has access to an event queue in case asynchronous operations need to be run: |
| kenjiArai | 1:9db0e321a9f4 | 621 | |
| kenjiArai | 1:9db0e321a9f4 | 622 | ```cpp |
| kenjiArai | 1:9db0e321a9f4 | 623 | Delegate *delegate(); |
| kenjiArai | 1:9db0e321a9f4 | 624 | events::EventQueue *event_queue(); |
| kenjiArai | 1:9db0e321a9f4 | 625 | ``` |
| kenjiArai | 1:9db0e321a9f4 | 626 | |
| kenjiArai | 1:9db0e321a9f4 | 627 | ### NCI driver APIs |
| kenjiArai | 1:9db0e321a9f4 | 628 | |
| kenjiArai | 1:9db0e321a9f4 | 629 | This API will be defined in phase 2. |
| kenjiArai | 1:9db0e321a9f4 | 630 | |
| kenjiArai | 1:9db0e321a9f4 | 631 | # Testing strategy |
| kenjiArai | 1:9db0e321a9f4 | 632 | |
| kenjiArai | 1:9db0e321a9f4 | 633 | ## NFC forum compliance |
| kenjiArai | 1:9db0e321a9f4 | 634 | |
| kenjiArai | 1:9db0e321a9f4 | 635 | A dongle driven by [PyNFC](https://nfcpy.readthedocs.io/en/latest/index.html) will be used to run Greentea-based tests to ensure that the implementation behaves correctly for a range of system tests. |
| kenjiArai | 1:9db0e321a9f4 | 636 | |
| kenjiArai | 1:9db0e321a9f4 | 637 | Unit tests will cover all internal logic and NFC endpoints can be mocked/emulated where possible. |
| kenjiArai | 1:9db0e321a9f4 | 638 | |
| kenjiArai | 1:9db0e321a9f4 | 639 | In the future, we could run NFC Forum test suites using approved testing equipment. |
| kenjiArai | 1:9db0e321a9f4 | 640 | |
| kenjiArai | 1:9db0e321a9f4 | 641 | ## Interoperability |
| kenjiArai | 1:9db0e321a9f4 | 642 | |
| kenjiArai | 1:9db0e321a9f4 | 643 | Interoperability is important with a technology such as NFC. Therefore, our testing rig will include a selection of smartphones and NFC tags that can be connected using analog switches to the relevant NFC-enabled platform running Mbed OS. |
| kenjiArai | 1:9db0e321a9f4 | 644 | |
| kenjiArai | 1:9db0e321a9f4 | 645 | ![interop_test_rig] |
| kenjiArai | 1:9db0e321a9f4 | 646 | |
| kenjiArai | 1:9db0e321a9f4 | 647 | ## HAL testing |
| kenjiArai | 1:9db0e321a9f4 | 648 | |
| kenjiArai | 1:9db0e321a9f4 | 649 | Greentea tests will be provided to Partners to ensure compliance with the NFC EEPROM backend API. |
| kenjiArai | 1:9db0e321a9f4 | 650 | |
| kenjiArai | 1:9db0e321a9f4 | 651 | # Dependencies |
| kenjiArai | 1:9db0e321a9f4 | 652 | |
| kenjiArai | 1:9db0e321a9f4 | 653 | - Event Queue |
| kenjiArai | 1:9db0e321a9f4 | 654 | |
| kenjiArai | 1:9db0e321a9f4 | 655 | There are currently at least four event queues (Plaftorm, BLE, USB and IP) in Mbed OS, and NFC will also require an event queing mechanism. We should try to reuse one of these existing queues with the longterm goal of unifying these code bases. |
| kenjiArai | 1:9db0e321a9f4 | 656 | |
| kenjiArai | 1:9db0e321a9f4 | 657 | [phase_1_architecture]: phase_1_architecture.png |
| kenjiArai | 1:9db0e321a9f4 | 658 | [phase_2_architecture]: phase_2_architecture.png |
| kenjiArai | 1:9db0e321a9f4 | 659 | [nfc_controller_diagram]: uml_diagram_controller.png |
| kenjiArai | 1:9db0e321a9f4 | 660 | [nfc_endpoints_diagram]: uml_diagram_endpoints.png |
| kenjiArai | 1:9db0e321a9f4 | 661 | [interop_test_rig]: interop_test_rig.png |
| kenjiArai | 1:9db0e321a9f4 | 662 | [ndef_message_parser_diagram]: uml_diagram_ndef_message_parser.png |
| kenjiArai | 1:9db0e321a9f4 | 663 | [ndef_record_parser_diagram]: uml_diagram_ndef_record_parser.png |
| kenjiArai | 1:9db0e321a9f4 | 664 | [ndef_common_parsers_diagram]: uml_diagram_ndef_common_parsers.png |
| kenjiArai | 1:9db0e321a9f4 | 665 | [ndef_simple_parser_diagram]: uml_diagram_ndef_simple_parser.png |
| kenjiArai | 1:9db0e321a9f4 | 666 | [ndef_message_builder_diagram]: uml_diagram_ndef_message_builder_diagram.png |