NFC Documentation #691

donatieng · 2018-08-28T17:13:04Z

This is the associated docs PR for ARMmbed/mbed-os#7822

AnotherButler

We need to move any architecture content to create the technology page.

AnotherButler · 2018-08-28T19:29:00Z

docs/reference/api/connectivity/nfc/NFC.md

+};
+```
+
+#### NFC controller


If these are separate APIs, they should each get their own page and description.

AnotherButler · 2018-08-28T19:30:00Z

docs/reference/api/connectivity/nfc/NFC.md

+A detailed design document is available [within the Mbed OS source tree](https://github.com/ARMmbed/mbed-os/docs/design-documents/nfc/nfc_design.md). It details the rationale behind the API design.
+
+[explorenfc_nucleo]: explorenfc_nucleo.jpg
+[n_mark]: n_mark.png


Query: Do we have an example created for NFC?

AnotherButler · 2018-08-28T19:32:15Z

docs/reference/api/connectivity/nfc/NFC.md

+
+Mbed OS supports the card emulation mode, either through the use of a controller or NFC EEPROM.
+
+NFC support is available for the NXP PN512 transceiver. In terms of NFC EEPROMs, a driver for the ST M24SR EEPROM series is available - we also provide a [porting guide](https://os.mbed.com/contributing/connectivity/NFCEEPROMDriver.html) to add support for other NFC EEPROMs.


Let's remove the first part of this, so what we support doesn't quickly become out of date.

AnotherButler · 2018-08-28T19:34:42Z

docs/reference/api/connectivity/nfc/NFC.md

+
+### Getting started with NFC and example
+
+NFC examples are available on [GitHub](https://github.com/ARMmbed/mbed-os-example-nfc) and demonstrate how to create NFC tags that you can be read from and write to using a phone.


Note to self: Delete extra word.

AnotherButler · 2018-08-29T17:42:47Z

docs/reference/api/connectivity/nfc/NFC.md

+
+### Design
+
+A detailed design document is available [within the Mbed OS source tree](https://github.com/ARMmbed/mbed-os/docs/design-documents/nfc/nfc_design.md). It details the rationale behind the API design.


This link is broken, and I can't seem to find where to go to replace it. Could you please point me to the right one?

That's this one - the link above will become valid once the PR is merged in :)
https://github.com/donatieng/mbed-os/blob/nfc-spec/docs/design-documents/nfc/nfc_design.md

There is really good content here. I'd love to see this is the technology section.

MarceloSalazar · 2018-08-30T06:55:57Z

The docs is looking good.
I feel some of the content in the intro belongs to the technology section?

Also, would be nice to update the photo "explorenfc_nucleo.jpg" as it looks a bit messy with many cables and can't see much details on the NFC shield.

AnotherButler

These look really good, @donatieng

I left a few comments for you to address.

AnotherButler · 2018-08-31T01:02:50Z

docs/reference/api/connectivity/nfc/NDEF.md

+
+An application can extend capabilities of `SimpleMessageParser` by adding new record parsers (`mbed::nfc::ndef::RecordParser`) at runtime.
+
+[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/FIXME)


Note to self: Add correct link after code merges.

Do you think it makes sense to add this code at it is, or should we let users import it?
Maybe this code is already available in the mbed-os-example-nfc application?

We do not have any parsing in our examples yet plus 60 lines of well focused code that demonstrate the API are different than an example which just solves a specific use case with the whole NFC API.

Technology examples and API demonstrations are different beasts.

AnotherButler · 2018-08-31T01:02:55Z

docs/reference/api/connectivity/nfc/NDEF.md

+}
+```
+
+[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/FIXME)


Note to self: Add correct link after code merges.

AnotherButler · 2018-08-31T01:03:11Z

docs/reference/api/connectivity/nfc/NFCController.md

+
+### NFC controller class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/FIXME)


Note to self: Add correct link after code merges.

AnotherButler · 2018-08-31T01:03:15Z

docs/reference/api/connectivity/nfc/NFCEEPROM.md

+
+### NFC EEPROM class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/FIXME)


Note to self: Add correct link after code merges.

AnotherButler · 2018-08-31T01:03:41Z

docs/reference/api/connectivity/nfc/NDEF.md

@@ -0,0 +1,106 @@
+### NDEF API


I love this file. Nice work.

That's Copyright @pan- :)

AnotherButler · 2018-08-31T01:04:38Z

docs/reference/api/connectivity/nfc/NFCController.md

@@ -0,0 +1,49 @@
+## NFC controller
+
+To use an NFC controller, you must initiate the instance with a driver instance, an event queue and a scratch buffer for NDEF messages.


This tells us how to use it but doesn't say what it is. Could we add a sentence saying what this is and when/why you'd want to use it?

AnotherButler · 2018-08-31T01:05:17Z

docs/reference/api/connectivity/nfc/NFCEEPROM.md

@@ -0,0 +1,28 @@
+## NFC EEPROM
+
+To use an NFC controller, you must initiate the instance with a driver instance, an event queue and a scratch buffer for NDEF messages.


I'm not sure how this sentence about an NFC controller ties in to this page about NFC EEPROM. Could we say what NFC EEPROM is, what it stands for and when/why you'd want to use it?

AnotherButler · 2018-08-31T01:06:27Z

Note to self: Fix Doxy links after code merges, and upload images after doc merges.

AnotherButler · 2018-08-31T01:06:47Z

@donatieng Could you also resolve the merge conflicts when you're finished with your changes?

MarceloSalazar · 2018-08-31T09:48:59Z

docs/reference/api/connectivity/nfc/NDEF.md

+using mbed::nfc::ndef::common::SimpleMessageParser;
+
+void parse_ndef_message(const Span<const uint8_t> &buffer) {
+    SimpleMessageParser parser;


What's the purpose of these functions?
Are they included in Mbed OS, or something that a developer will need to copy & paste in their application?

The line above the code it is indicated that mbed::nfc::ndef::common::SimpleMessageParser is part of the API provided.

The code just demonstrate how to use this class to parse an NDEF message.

MarceloSalazar · 2018-08-31T09:50:19Z

docs/reference/api/connectivity/nfc/NDEF.md

+using mbed::nfc::ndef::common::URI;
+
+size_t build_ndef_message(const Span<uint8_t> &buffer) {
+    MessageBuilder builder(buffer);


Same question for this function.
Is this included in Mbed OS or should the developer include this code in their app?

Same as above, it is explicitly that mbed::nfc::ndef::MessageBuilder is part of the API mbed OS provide.

It just demonstrate how an application can create an NDEF message.

Make initial copy edits.

Fix minor grammar nits.

Copy edit for consistent capitalization across docs.

Copy edit file for consistent capitalization across docs.

Copy edit for image formatting.

Copy edit for minor formatting and grammar nits.

Change passive to active voice.

Copy edit for active voice.

AnotherButler · 2018-08-31T15:05:51Z

@donatieng Thanks for making those changes 👍

AnotherButler · 2018-08-31T15:06:40Z

Note to self: Add pages to .json after merging.

AnotherButler · 2018-09-04T10:51:28Z

@donatieng I can't find the APIs in the Doxygen. Could you please help me?

Fix missing link.

Add missing links.

AnotherButler requested review from MarceloSalazar, ashok-rao, AnotherButler, paul-szczepanek-arm and ithinuel August 28, 2018 18:22

AnotherButler added the code dependency label Aug 28, 2018

AnotherButler reviewed Aug 28, 2018

View reviewed changes

AnotherButler reviewed Aug 29, 2018

View reviewed changes

AnotherButler reviewed Aug 31, 2018

View reviewed changes

MarceloSalazar reviewed Aug 31, 2018

View reviewed changes

donatieng force-pushed the nfc branch from 1ce3b50 to a1d5eaf Compare August 31, 2018 10:29

Donatien Garnier and others added 14 commits August 31, 2018 11:30

Create handbook page for NFC

ef58d8e

NFC: Amend connectivity page

cc3525a

Make initial copy edit to NFC.md

cd16ed4

Make initial copy edits.

Update photo of NFC setup

78fe31d

NFC: fix code example.

deacf5e

NFC: Add NDEF documentation.

b7c989f

NFC: fix typo.

f3d15cd

Move some content to technology section, add doc for specific classes

6abed18

Copy edit NDEF.md

b9509bf

Fix minor grammar nits.

Copy edit NFCController.md

fc89f44

Copy edit for consistent capitalization across docs.

Copy edit NFCEEPROM.md

9bce57a

Copy edit file for consistent capitalization across docs.

Copy edit NFC.md

60d7e1d

Copy edit for image formatting.

Copy edit connectivity.md

8ddd180

Copy edit for minor formatting and grammar nits.

Added one-sentence description for NFCController and NFCEEPROM

83a6baa

donatieng force-pushed the nfc branch from a1d5eaf to 83a6baa Compare August 31, 2018 10:32

pan- approved these changes Aug 31, 2018

View reviewed changes

Amanda Butler added 2 commits August 31, 2018 10:03

Copy edit NFCController.md

7d8c325

Change passive to active voice.

Copy edit NFCEEPROM.md

9bdc703

Copy edit for active voice.

AnotherButler approved these changes Aug 31, 2018

View reviewed changes

AnotherButler added 5.10 urgent and removed code dependency labels Sep 4, 2018

Amanda Butler added 3 commits September 4, 2018 07:11

Fix link in NFCController.md

d459fd7

Fix missing link.

Fix link in NFCEEPROM.md

8a0c322

Fix missing link.

Fix links in NDEF.md

cbb3d9e

Add missing links.

AnotherButler merged commit 68a670a into ARMmbed:development Sep 4, 2018


		Mbed OS supports the card emulation mode, either through the use of a controller or NFC EEPROM.

		NFC support is available for the NXP PN512 transceiver. In terms of NFC EEPROMs, a driver for the ST M24SR EEPROM series is available - we also provide a [porting guide](https://os.mbed.com/contributing/connectivity/NFCEEPROMDriver.html) to add support for other NFC EEPROMs.


		### Getting started with NFC and example

		NFC examples are available on [GitHub](https://github.com/ARMmbed/mbed-os-example-nfc) and demonstrate how to create NFC tags that you can be read from and write to using a phone.


		### Design

		A detailed design document is available [within the Mbed OS source tree](https://github.com/ARMmbed/mbed-os/docs/design-documents/nfc/nfc_design.md). It details the rationale behind the API design.


		An application can extend capabilities of `SimpleMessageParser` by adding new record parsers (`mbed::nfc::ndef::RecordParser`) at runtime.

		[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/FIXME)


		### NFC controller class reference

		[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/FIXME)


		### NFC EEPROM class reference

		[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/FIXME)

		@@ -0,0 +1,49 @@
		## NFC controller

		To use an NFC controller, you must initiate the instance with a driver instance, an event queue and a scratch buffer for NDEF messages.

		@@ -0,0 +1,28 @@
		## NFC EEPROM

		To use an NFC controller, you must initiate the instance with a driver instance, an event queue and a scratch buffer for NDEF messages.

NFC Documentation #691

NFC Documentation #691

Uh oh!

Conversation

donatieng commented Aug 28, 2018

Uh oh!

AnotherButler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MarceloSalazar commented Aug 30, 2018

Uh oh!

AnotherButler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnotherButler commented Aug 31, 2018

Uh oh!

AnotherButler commented Aug 31, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnotherButler commented Aug 31, 2018

Uh oh!

AnotherButler commented Aug 31, 2018

Uh oh!

AnotherButler commented Sep 4, 2018

Uh oh!

Uh oh!