Add NFC binary sensor platform doc (#3526)
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
This commit is contained in:
parent
b8feef3b60
commit
1288961250
|
@ -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`
|
Before Width: | Height: | Size: 180 KiB After Width: | Height: | Size: 180 KiB |
Before Width: | Height: | Size: 180 KiB After Width: | Height: | Size: 180 KiB |
|
@ -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
|
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).
|
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
|
.. code-block:: yaml
|
||||||
|
|
||||||
pn7150_i2c:
|
pn7150_i2c:
|
||||||
|
@ -372,8 +374,8 @@ See Also
|
||||||
--------
|
--------
|
||||||
|
|
||||||
- :doc:`index`
|
- :doc:`index`
|
||||||
- :doc:`pn532`
|
- :doc:`binary_sensor/pn532`
|
||||||
- :doc:`rc522`
|
- :doc:`binary_sensor/rc522`
|
||||||
- :doc:`rdm6300`
|
- :doc:`binary_sensor/rdm6300`
|
||||||
- :apiref:`pn7150/pn7150.h`
|
- :apiref:`pn7150/pn7150.h`
|
||||||
- :ghedit:`Edit`
|
- :ghedit:`Edit`
|
|
@ -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
|
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).
|
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:
|
.. _pn7160-spi:
|
||||||
|
|
||||||
Over SPI
|
Over SPI
|
||||||
|
@ -430,8 +432,8 @@ See Also
|
||||||
--------
|
--------
|
||||||
|
|
||||||
- :doc:`index`
|
- :doc:`index`
|
||||||
- :doc:`pn532`
|
- :doc:`binary_sensor/pn532`
|
||||||
- :doc:`rc522`
|
- :doc:`binary_sensor/rc522`
|
||||||
- :doc:`rdm6300`
|
- :doc:`binary_sensor/rdm6300`
|
||||||
- :apiref:`pn7160/pn7160.h`
|
- :apiref:`pn7160/pn7160.h`
|
||||||
- :ghedit:`Edit`
|
- :ghedit:`Edit`
|
Binary file not shown.
After Width: | Height: | Size: 3.8 KiB |
|
@ -483,9 +483,10 @@ Often known as "tag" or "card" readers within the community.
|
||||||
|
|
||||||
.. imgtable::
|
.. imgtable::
|
||||||
|
|
||||||
|
NFC Tag, components/binary_sensor/nfc, nfc.png
|
||||||
PN532, components/binary_sensor/pn532, pn532.jpg
|
PN532, components/binary_sensor/pn532, pn532.jpg
|
||||||
PN7150, components/binary_sensor/pn7150, pn7150.jpg
|
PN7150, components/pn7150, pn7150.jpg
|
||||||
PN716X, components/binary_sensor/pn7160, pn716x.jpg
|
PN716X, components/pn7160, pn716x.jpg
|
||||||
RC522, components/binary_sensor/rc522, rc522.jpg
|
RC522, components/binary_sensor/rc522, rc522.jpg
|
||||||
RDM6300, components/binary_sensor/rdm6300, rdm6300.jpg
|
RDM6300, components/binary_sensor/rdm6300, rdm6300.jpg
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue