Add NFC binary sensor platform doc (#3526)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

components/binary_sensor/nfc.rst

@@ -0,0 +1,90 @@
+NFC Binary Sensor
+=================
+
+.. seo::
+    :description: Instructions for setting up a NFC binary sensor in ESPHome
+    :image: nfc.png
+    :keywords: PN532, PN7150, PN7160, NFC
+
+.. _nfc-platform:
+
+The ``nfc`` binary sensor platform provides an easy way for you to determine if an NFC tag is presented to the reader.
+The tag may be identified in one of three ways:
+
+- By given unique ID (``uid``) -- for example ``74-10-37-94``
+- By a given NDEF tag "name", or...
+- By a given string contained in the tag's NDEF message/data
+
+Note that this platform is currently supported by the :doc:`PN7150 <../pn7150>` and :doc:`PN716x <../pn7160>` only;
+one of these components must be present in your device's configuration in order to use it.
+
+.. code-block:: yaml
+
+    # Example configuration entries
+    binary_sensor:
+      - platform: nfc
+        ndef_contains: pulse
+        name: "NFC 1 Tag"
+      - platform: nfc
+        tag_id: pulsed
+        name: "NFC 2 Tag"
+      - platform: nfc
+        uid: 74-10-37-94
+        name: "MFC Tag"
+
+Configuration variables:
+------------------------
+
+- **ndef_contains** (*Optional*, string): A (sub)string that must appear in the tag's NDEF message. May not be used
+  with ``tag_id`` and/or ``uid`` (below).
+- **tag_id** (*Optional*, string): A string that identifies the tag; in effect, its name. Specifically, this looks
+  for the Home Assistant URI encoded into one of the tag's NDEF records and then looks for this specific string. May
+  not be used with ``ndef_contains`` and/or ``uid``.
+- **uid** (*Optional*, string): The unique ID of the NFC tag. This is a hyphen-separated list of hexadecimal values.
+  For example: ``74-10-37-94``. May not be used with ``ndef_contains`` and/or ``tag_id`` (above).
+- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
+
+.. _nfc-setting_up_tags:
+
+Setting Up Tags
+---------------
+
+To set up a binary sensor for a given NFC tag, you must first know either its unique ID (``uid``), tag ID (if it was
+prepared using the Home Assistant Companion app) or (part of) a string that is contained within its NDEF message.
+
+To obtain a tag's UID:
+
+- Set up a simple NFC component (such as the :doc:`PN532 <pn532>`, :doc:`PN7150 <../pn7150>` or :doc:`PN716x <../pn7160>`)
+  configuration without any binary sensors.
+- Approach the NFC reader with an NFC tag. When the tag is sufficiently close to the reader, you'll see a message in the
+  ESPHome device's logs similar to this:
+
+  .. code::
+
+      Read tag type Mifare Classic with UID 1C-E5-E7-A6
+
+- Either:
+
+  - Copy this ID and use it to create a ``binary_sensor`` entry as shown in the configuration example above, or...
+  - Use the tag ID (as determined when it was prepared with the Home Assistant Companion app) to define the ``tag_id``
+    parameter for the ``binary_sensor`` as shown above, or...
+  - Choose a substring contained within the tag's NDEF message and use this to define the ``ndef_contains`` parameter
+    as shown in the example above. If present, the tag's NDEF records will appear in the log on the lines just below
+    the message shown above.
+
+Repeat this process for each tag.
+
+Note that, since *you* are able to define the NDEF message, this approach is more flexible and even allows multiple
+cards/tags to share the same message.
+
+See Also
+--------
+
+- :doc:`index`
+- :doc:`pn532`
+- :doc:`../pn7150`
+- :doc:`../pn7160`
+- :apiref:`pn532/pn532.h`
+- :apiref:`pn7150/pn7150.h`
+- :apiref:`pn7160/pn7160.h`
+- :ghedit:`Edit`

components/pn7150.rst

@@ -25,6 +25,8 @@ only read/write mode is enabled; card/tag emulation is enabled only if the ``emu
 variable is defined (see below). Regardless, reader/writer (polling) mode and card/tag emulation mode may be
 independently enabled and disabled by using the corresponding :ref:`pn7150-actions` (see below).
 
+In addition, the :doc:`binary_sensor/nfc` platform may be used to quickly and easily identify tags presented to the reader.
+
 .. code-block:: yaml
 
     pn7150_i2c:
@@ -372,8 +374,8 @@ See Also
 --------
 
 - :doc:`index`
-- :doc:`pn532`
-- :doc:`rc522`
-- :doc:`rdm6300`
+- :doc:`binary_sensor/pn532`
+- :doc:`binary_sensor/rc522`
+- :doc:`binary_sensor/rdm6300`
 - :apiref:`pn7150/pn7150.h`
 - :ghedit:`Edit`

components/pn7160.rst

@@ -30,6 +30,8 @@ only read/write mode is enabled; card/tag emulation is enabled only if the ``emu
 variable is defined (see below). Regardless, reader/writer (polling) mode and card/tag emulation mode may be
 independently enabled and disabled by using the corresponding :ref:`pn7160-actions` (see below).
 
+In addition, the :doc:`binary_sensor/nfc` platform may be used to quickly and easily identify tags presented to the reader.
+
 .. _pn7160-spi:
 
 Over SPI
@@ -430,8 +432,8 @@ See Also
 --------
 
 - :doc:`index`
-- :doc:`pn532`
-- :doc:`rc522`
-- :doc:`rdm6300`
+- :doc:`binary_sensor/pn532`
+- :doc:`binary_sensor/rc522`
+- :doc:`binary_sensor/rdm6300`
 - :apiref:`pn7160/pn7160.h`
 - :ghedit:`Edit`

index.rst

@@ -483,9 +483,10 @@ Often known as "tag" or "card" readers within the community.
 
 .. imgtable::
 
+    NFC Tag, components/binary_sensor/nfc, nfc.png
     PN532, components/binary_sensor/pn532, pn532.jpg
-    PN7150, components/binary_sensor/pn7150, pn7150.jpg
-    PN716X, components/binary_sensor/pn7160, pn716x.jpg
+    PN7150, components/pn7150, pn7150.jpg
+    PN716X, components/pn7160, pn716x.jpg
     RC522, components/binary_sensor/rc522, rc522.jpg
     RDM6300, components/binary_sensor/rdm6300, rdm6300.jpg