diff --git a/components/binary_sensor/nfc.rst b/components/binary_sensor/nfc.rst new file mode 100644 index 000000000..9c41f9520 --- /dev/null +++ b/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 `. + +.. _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 `, :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` diff --git a/components/binary_sensor/images/pn7150-full.jpg b/components/images/pn7150-full.jpg similarity index 100% rename from components/binary_sensor/images/pn7150-full.jpg rename to components/images/pn7150-full.jpg diff --git a/components/binary_sensor/images/pn716x-full.jpg b/components/images/pn716x-full.jpg similarity index 100% rename from components/binary_sensor/images/pn716x-full.jpg rename to components/images/pn716x-full.jpg diff --git a/components/binary_sensor/pn7150.rst b/components/pn7150.rst similarity index 98% rename from components/binary_sensor/pn7150.rst rename to components/pn7150.rst index 3fafd6d66..b76e6e2df 100644 --- a/components/binary_sensor/pn7150.rst +++ b/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` diff --git a/components/binary_sensor/pn7160.rst b/components/pn7160.rst similarity index 98% rename from components/binary_sensor/pn7160.rst rename to components/pn7160.rst index 674ee6693..f359a7b5d 100644 --- a/components/binary_sensor/pn7160.rst +++ b/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` diff --git a/images/nfc.png b/images/nfc.png new file mode 100644 index 000000000..101dd1a1d Binary files /dev/null and b/images/nfc.png differ diff --git a/index.rst b/index.rst index 8d28c7bf8..f4a44f0de 100644 --- a/index.rst +++ b/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