Add docs for pn532 NDEF functionality (#936)

components/binary_sensor/pn532.rst

@@ -77,9 +77,11 @@ if the tag is changed or goes away for one cycle of ``update_interval``.
 The parameter ``x`` this trigger provides is of type ``std::string`` and is the tag UID in the format
 ``74-10-37-94``. The configuration below will for example publish the tag ID on the MQTT topic ``pn532/tag``.
 
+See :ref:`pn532-ndef_reading` below for how to use the second ``tag`` parameter that is provided to this trigger.
+
 .. code-block:: yaml
 
-    pn532:
+    pn532_...:
       # ...
       on_tag:
         then:
@@ -92,7 +94,7 @@ using :ref:`api-homeassistant_tag_scanned_action`.
 
 .. code-block:: yaml
 
-    pn532:
+    pn532_...:
       # ...
       on_tag:
         then:
@@ -103,7 +105,7 @@ Alternatively you could also send the value directly to Home Assistant via a
 
 .. code-block:: yaml
 
-    pn532:
+    pn532_...:
       # ...
       on_tag:
         then:
@@ -167,10 +169,82 @@ When your code is running and you approach the PN532 with an NFC Tag, you should
 Then copy this id and create a ``binary_sensor`` entry as in the configuration example. Repeat this process for
 each tag.
 
+.. _pn532-ndef:
+
+NDEF
+====
+
+The PN532 supports reading and writing NDEF formatted data into the cards.
+
+.. _pn532-ndef_reading:
+
+NDEF reading
+------------
+
+The following example will read an NFC tag that has been formatted and written using the Home Assistant Companion
+App and send it to Home Assistant using the :ref:`api-homeassistant_tag_scanned_action`. The ``tag`` variable is
+supplied to the ``on_tag`` trigger and any actions that run and can be used as below.
+
+.. code-block:: yaml
+
+    pn532_...:
+      # ...
+      on_tag:
+        then:
+          - homeassistant.tag_scanned: !lambda |
+              if (!tag.has_ndef_message()) {
+                return x;
+              }
+              auto message = tag.get_ndef_message();
+              auto records = message->get_records();
+              for (auto &record : records) {
+                std::string payload = record->get_payload();
+                size_t pos = payload.find("https://www.home-assistant.io/tag/");
+                if (pos != std::string::npos) {
+                  return payload.substr(pos + 34);
+                }
+              }
+              return x;
+
+.. _pn532-ndef_writing:
+
+NDEF Writing
+------------
+
+The following example can be used to write a (pseudo) random UUID to the tag in the same format as the
+Home Assistant Companion App does.
+
+.. code-block:: yaml
+
+    on_...
+      then:
+        - lambda: |-
+            static const char alphanum[] = "0123456789abcdef";
+            std::string uri = "https://www.home-assistant.io/tag/";
+            for (int i = 0; i < 8; i++)
+              uri += alphanum[random_uint32() % (sizeof(alphanum) - 1)];
+            uri += "-";
+            for (int j = 0; j < 3; j++) {
+              for (int i = 0; i < 4; i++)
+                uri += alphanum[random_uint32() % (sizeof(alphanum) - 1)];
+              uri += "-";
+            }
+            for (int i = 0; i < 12; i++)
+              uri += alphanum[random_uint32() % (sizeof(alphanum) - 1)];
+            auto message = new nfc::NdefMessage();
+            message->add_uri_record(uri);
+            ESP_LOGD("ndef", "Writing payload: %s", uri.c_str());
+            id(pn532_board).write_mode(message);
+        - wait_until:
+            not:
+              pn532.is_writing:
+        - logger.log: "Finished writing tag"
+
 See Also
 --------
 
 - :doc:`index`
 - :doc:`rdm6300`
+- :doc:`rc522`
 - :apiref:`pn532/pn532.h`
 - :ghedit:`Edit`