diff --git a/components/binary_sensor/images/pn716x-full.jpg b/components/binary_sensor/images/pn716x-full.jpg new file mode 100644 index 000000000..da4a97241 Binary files /dev/null and b/components/binary_sensor/images/pn716x-full.jpg differ diff --git a/components/binary_sensor/pn7160.rst b/components/binary_sensor/pn7160.rst new file mode 100644 index 000000000..674ee6693 --- /dev/null +++ b/components/binary_sensor/pn7160.rst @@ -0,0 +1,437 @@ +PN7160 NFC +========== + +.. seo:: + :description: Instructions for setting up PN7160 NFC tag readers and tags in ESPHome + :image: pn716x.jpg + :keywords: PN7160, NFC, RFID + +.. _pn7160-component: + +Component/Hub +------------- + +The ``pn7160`` component allows you to use PN7160 NFC controllers with ESPHome. This component is a global hub that +establishes a connection to the PN7160 via :ref:`SPI ` or :ref:`I²C `. + +.. figure:: images/pn716x-full.jpg + :align: center + :width: 70.0% + +Within ESPHome, the PN7160 can be configured to use either the SPI **or** I²C protocol for data communication. +Note that there are different versions of the IC for each bus type, each with a different part number; in other +words, **the bus type cannot be changed by jumpers/switches as it is determed at the time of manufacture.** + +You must determine which version of the IC you have and then configure the corresponding bus -- either the +:ref:`SPI bus ` or the :ref:`I²C bus `. + +ESPHome supports both card/tag reading/writing as well as card/tag emulation with this component. By default, +only read/write mode is enabled; card/tag emulation is enabled only if the ``emulation_message`` configuration +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). + +.. _pn7160-spi: + +Over SPI +-------- + +The ``pn7160_spi`` component allows you to use :ref:`SPI-equipped ` PN7160 NFC controllers with with ESPHome. + +.. code-block:: yaml + + pn7160_spi: + cs_pin: 15 + dwl_req_pin: 17 + irq_pin: 35 + ven_pin: 16 + wkup_req_pin: 21 + emulation_message: https://www.home-assistant.io/tag/pulse_ce + tag_ttl: 1000ms + +Configuration variables: +************************ + +- **cs_pin** (**Required**, :ref:`Pin Schema `): The pin connected to the PN7160's ``NSS`` (chip + select) line. +- **dwl_req_pin** (*Optional*, :ref:`Pin Schema `): The pin connected to the PN7160's + ``DWL_REQ`` line. Used to invoke the PN7160's firmware update mode; may be used in a future release. +- **irq_pin** (**Required**, :ref:`Pin Schema `): The pin connected to the PN7160's ``IRQ`` line. +- **ven_pin** (**Required**, :ref:`Pin Schema `): The pin connected to the PN7160's ``VEN`` line. +- **wkup_req_pin** (*Optional*, :ref:`Pin Schema `): The pin connected to the PN7160's + ``WKUP_REQ`` line. May be used to improve power management in a future release. +- **emulation_message** (*Optional*, string): When scanned by another NFC card/tag reader (such as a smartphone), this + string is used as the content for an NDEF-formatted response. This allows the PN7160 to act as a tag in addition to a + tag reader/writer. +- **tag_ttl** (*Optional*, :ref:`config-time`): The duration that must elapse after the PN7160 is no longer able to + "see" a tag before it is considered to have been removed from the reader. +- **on_tag** (*Optional*, :ref:`Automation `): An automation to perform when a tag is first read. See + :ref:`pn7160-on_tag`. +- **on_tag_removed** (*Optional*, :ref:`Automation `): An automation to perform after a tag is removed. See + :ref:`pn7160-on_tag_removed`. +- **on_emulated_tag_scan** (*Optional*, :ref:`Automation `): An automation to perform when the PN7160 is + scanned by another tag reader (such as a smartphone). See :ref:`pn7160-on_emulated_tag_scan`. +- **spi_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`SPI Component ` if you want + to use multiple SPI buses. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this component. + +.. _pn7160-i2c: + +Over I²C +-------- + +The ``pn7160_i2c`` component allows you to use :ref:`I²C-equipped ` PN7160 NFC controllers with ESPHome. + + +.. code-block:: yaml + + pn7160_i2c: + dwl_req_pin: 17 + irq_pin: 35 + ven_pin: 16 + wkup_req_pin: 21 + emulation_message: https://www.home-assistant.io/tag/pulse_ce + tag_ttl: 1000ms + +Configuration variables: +************************ + +- **dwl_req_pin** (*Optional*, :ref:`Pin Schema `): The pin connected to the PN7160's + ``DWL_REQ`` line. Used to invoke the PN7160's firmware update mode; may be used in a future release. +- **irq_pin** (**Required**, :ref:`Pin Schema `): The pin connected to the PN7160's ``IRQ`` line. +- **ven_pin** (**Required**, :ref:`Pin Schema `): The pin connected to the PN7160's ``VEN`` line. +- **wkup_req_pin** (*Optional*, :ref:`Pin Schema `): The pin connected to the PN7160's + ``WKUP_REQ`` line. May be used to improve power management in a future release. +- **emulation_message** (*Optional*, string): When scanned by another NFC card/tag reader (such as a smartphone), this + string is used as the content for an NDEF-formatted response. This allows the PN7160 to act as a tag in addition to a + tag reader/writer. +- **tag_ttl** (*Optional*, :ref:`config-time`): The duration that must elapse after the PN7160 is no longer able to + "see" a tag before it is considered to have been removed from the reader. +- **on_tag** (*Optional*, :ref:`Automation `): An automation to perform when a tag is first read. See + :ref:`pn7160-on_tag`. +- **on_tag_removed** (*Optional*, :ref:`Automation `): An automation to perform after a tag is removed. See + :ref:`pn7160-on_tag_removed`. +- **on_emulated_tag_scan** (*Optional*, :ref:`Automation `): An automation to perform when the PN7160 is + scanned by another tag reader (such as a smartphone). See :ref:`pn7160-on_emulated_tag_scan`. +- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`I²C Component ` if you need + to use multiple I²C buses. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this component. + + +.. _pn7160-actions: + +Actions +------- + +.. _pn7160-set_clean_mode: + +``tag.set_clean_mode`` Action +***************************** + +Use this action to invoke "clean mode" -- the next tag presented to the PN7160 will be "cleaned", removing all data +from the tag. + +.. code-block:: yaml + + on_...: + then: + - tag.set_clean_mode: my_pn7160_id + +.. _pn7160-set_format_mode: + +``tag.set_format_mode`` Action +****************************** + +Use this action to invoke "format mode" -- the next tag presented to the PN7160 will be "formatted", leaving only an +empty NDEF message structure on the tag. + +.. code-block:: yaml + + on_...: + then: + - tag.set_format_mode: my_pn7160_id + +.. _pn7160-set_read_mode: + +``tag.set_read_mode`` Action +**************************** + +Use this action to invoke "read mode" -- the next tag presented to the PN7160 will be read. This is the default mode +that the component operates in. + +.. code-block:: yaml + + on_...: + then: + - tag.set_read_mode: my_pn7160_id + +.. _pn7160-set_write_message: + +``tag.set_write_message`` Action +******************************** + +Use this action to set the NDEF message used for "write mode" (see below). + +.. code-block:: yaml + + on_...: + then: + - tag.set_write_message: + message: https://www.home-assistant.io/tag/pulse + include_android_app_record: false + +- **message** (**Required**, string, templatable): The string to include in the tag's first NDEF record; typically + a URL as shown. +- **include_android_app_record** (*Optional*, boolean): Include a second NDEF record required for some Android + operating systems. Defaults to ``true``. + +.. _pn7160-set_write_mode: + +``tag.set_write_mode`` Action +***************************** + +Use this action to invoke "write mode" -- the next tag presented to the PN7160 will have its NDEF message set to the +message defined by the ``tag.set_write_message`` action (see above). **Note that a message must be set before this mode +may be invoked.** + +.. code-block:: yaml + + on_...: + then: + - tag.set_write_mode: my_pn7160_id + +.. _pn7160-set_emulation_message: + +``tag.set_emulation_message`` Action +************************************ + +Use this action to set the NDEF message used for card (tag) emulation mode, when enabled (see below). + +.. code-block:: yaml + + on_...: + then: + - tag.set_emulation_message: + message: https://www.home-assistant.io/tag/pulse + include_android_app_record: false + +- **message** (**Required**, string, templatable): The string to include in the (emulated) tag's first NDEF record; + typically a URL as shown. +- **include_android_app_record** (*Optional*, boolean): Include a second NDEF record required for some Android + operating systems. Defaults to ``true``. + +.. _pn7160-emulation_off: + +``tag.emulation_off`` Action +**************************** + +Use this action to disable card (tag) emulation mode. The PN7160 will no longer respond to requests from other readers, +such as smartphones. + +.. code-block:: yaml + + on_...: + then: + - tag.emulation_off: my_pn7160_id + +.. _pn7160-emulation_on: + +``tag.emulation_on`` Action +*************************** + +Use this action to enable card (tag) emulation mode. The PN7160 will respond to requests from other readers, such as +smartphones. + +**Note:** when card/tag emulation is enabled, polling (detecting a nearby card/tag) frequency is decreased; this +typically results in slightly slower detection of cards/tags presented to the PN7160. This behavior is normal and should +be expected; it is the result of the PN7160 toggling between polling and listening modes to support both functions. + +.. code-block:: yaml + + on_...: + then: + - tag.emulation_on: my_pn7160_id + +.. _pn7160-polling_off: + +``tag.polling_off`` Action +**************************** + +Use this action to disable card (tag) reading/writing. The PN7160 will no longer read or write cards/tags. + +.. code-block:: yaml + + on_...: + then: + - tag.polling_off: my_pn7160_id + +.. _pn7160-polling_on: + +``tag.polling_on`` Action +*************************** + +Use this action to enable card (tag) reading/writing. The PN7160 will read or write cards/tags. + +.. code-block:: yaml + + on_...: + then: + - tag.polling_on: my_pn7160_id + +Triggers +-------- + +.. _pn7160-on_tag: + +``on_tag`` Trigger +****************** + +This automation will be triggered immediately after the PN7160 module identifies a tag and reads its NDEF +message (if one is present). + +The parameter ``x`` this trigger provides is of type ``std::string`` and is the tag UID in the format +``74-10-37-94``. The example configuration below will publish the tag ID on the MQTT topic ``pn7160/tag``. + +See :ref:`pn7160-ndef_reading` below for how to use the second ``tag`` parameter that is provided to this trigger. + +.. code-block:: yaml + + pn7160_...: + # ... + on_tag: + then: + - mqtt.publish: + topic: pn7160/tag + payload: !lambda 'return x;' + +A tag scanned event can also be sent to the Home Assistant tag component +using :ref:`api-homeassistant_tag_scanned_action`. + +.. code-block:: yaml + + pn7160_...: + # ... + on_tag: + then: + - homeassistant.tag_scanned: !lambda 'return x;' + +You could also send the value to Home Assistant via a :doc:`template sensor `: + +.. code-block:: yaml + + pn7160_...: + # ... + on_tag: + then: + - text_sensor.template.publish: + id: nfc_tag + state: !lambda 'return x;' + + text_sensor: + - platform: template + name: "NFC Tag" + id: nfc_tag + +.. _pn7160-on_tag_removed: + +``on_tag_removed`` Trigger +************************** + +This automation will be triggered after the ``tag_ttl`` interval (see above) when the PN7160 no longer "sees" a +previously scanned tag. + +The parameter ``x`` this trigger provides is of type ``std::string`` and is the removed tag UID in the format +``74-10-37-94``. The example configuration below will publish the removed tag ID on the MQTT topic ``pn7160/tag_removed``. + +.. code-block:: yaml + + pn7160_...: + # ... + on_tag_removed: + then: + - mqtt.publish: + topic: pn7160/tag_removed + payload: !lambda 'return x;' + +.. _pn7160-on_emulated_tag_scan: + +``on_emulated_tag_scan`` Trigger +******************************** + +If card/tag emulation is enabled, this automation will be triggered when another reader (such as a smartphone) scans +the PN7160 and reads the NDEF message it responds with. No parameters are available to this action because data is only +sent *from* the PN7160 *to* the scanning device. + +.. code-block:: yaml + + pn7160_...: + # ... + on_emulated_tag_scan: + then: + - rtttl.play: "alert:d=32,o=5,b=160:e6,p,e6,p,e6" + + +.. _pn7160-ndef: + +NDEF +==== + +The PN7160 supports reading NDEF messages from and writing NDEF messages to cards/tags. + +.. _pn7160-ndef_reading: + +NDEF Reading +------------ + +Given an NFC tag formatted and written using the Home Assistant Companion App, the following example will send the tag +ID contained within its NDEF message to Home Assistant using the :ref:`api-homeassistant_tag_scanned_action`. +If no NDEF record is found with a tag ID, the tag's UID will be sent to Home Assistant, instead. + +The ``tag`` variable is available to any actions that run within the ``on_tag`` and ``on_tag_removed`` triggers. + +.. code-block:: yaml + + pn7160_...: + # ... + on_tag: + then: + - homeassistant.tag_scanned: !lambda "return tag.has_ha_tag_id() ? tag.get_ha_tag_id() : x;" + +.. _pn7160-ndef_writing: + +NDEF Writing +------------ + +The examples below illustrate how NDEF messages may be written to cards/tags via the PN7160. Note that a +:doc:`button ` is a great mechanism to use to trigger these actions. + +The first example will write a simple, fixed NDEF message to a tag. + +.. code-block:: yaml + + on_... + then: + - tag.set_write_message: + message: https://www.home-assistant.io/tag/pulse + include_android_app_record: false # optional + - tag.set_write_mode: my_pn7160_id + +The next example can be used to write a (pseudo) random UUID to a tag in the same manner as the Home Assistant +Companion App. + +.. code-block:: yaml + + on_... + then: + - tag.set_write_message: + message: !lambda "return nfc::get_random_ha_tag_ndef();" + - tag.set_write_mode: my_pn7160_id + +See Also +-------- + +- :doc:`index` +- :doc:`pn532` +- :doc:`rc522` +- :doc:`rdm6300` +- :apiref:`pn7160/pn7160.h` +- :ghedit:`Edit` diff --git a/images/pn716x.jpg b/images/pn716x.jpg new file mode 100644 index 000000000..b9cef4e52 Binary files /dev/null and b/images/pn716x.jpg differ diff --git a/index.rst b/index.rst index f1572ce34..641745586 100644 --- a/index.rst +++ b/index.rst @@ -483,6 +483,7 @@ Often known as "tag" or "card" readers within the community. .. imgtable:: PN532, components/binary_sensor/pn532, pn532.jpg + PN716X, components/binary_sensor/pn7160, pn716x.jpg RC522, components/binary_sensor/rc522, rc522.jpg RDM6300, components/binary_sensor/rdm6300, rdm6300.jpg