Add PN7150 doc (#3242)

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

components/binary_sensor/pn7150.rst

@@ -0,0 +1,379 @@
+PN7150 NFC
+==========
+
+.. seo::
+    :description: Instructions for setting up PN7150 NFC tag readers and tags in ESPHome
+    :image: pn7150.jpg
+    :keywords: PN7150, NFC, RFID
+
+.. _pn7150-component:
+
+Component/Hub
+-------------
+
+The ``pn7150`` component allows you to use PN7150 NFC controllers with ESPHome. This component is a global hub that
+establishes a connection to the PN7150 via :ref:`I²C <i2c>`.
+
+.. figure:: images/pn7150-full.jpg
+    :align: center
+    :width: 70.0%
+
+An :ref:`I²C <i2c>` bus must be defined within your device's ESPHome configuration to use the PN7150.
+
+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:`pn7150-actions` (see below).
+
+.. code-block:: yaml
+
+    pn7150_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 <config-pin_schema>`): The pin connected to the PN7150's
+  ``DWL_REQ`` line. Used to invoke the PN7150's firmware update mode; may be used in a future release.
+- **irq_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7150's ``IRQ`` line.
+- **ven_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7150's ``VEN`` line.
+- **wkup_req_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin connected to the PN7150'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 PN7150 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 PN7150 is no longer able to
+  "see" a tag before it is considered to have been removed from the reader.
+- **on_tag** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a tag is first read. See
+  :ref:`pn7150-on_tag`.
+- **on_tag_removed** (*Optional*, :ref:`Automation <automation>`): An automation to perform after a tag is removed. See
+  :ref:`pn7150-on_tag_removed`.
+- **on_emulated_tag_scan** (*Optional*, :ref:`Automation <automation>`): An automation to perform when the PN7150 is
+  scanned by another tag reader (such as a smartphone). See :ref:`pn7150-on_emulated_tag_scan`.
+- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`I²C Component <i2c>` if you need
+  to use multiple I²C buses.
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this component.
+
+
+.. _pn7150-actions:
+
+Actions
+-------
+
+.. _pn7150-set_clean_mode:
+
+``tag.set_clean_mode`` Action
+*****************************
+
+Use this action to invoke "clean mode" -- the next tag presented to the PN7150 will be "cleaned", removing all data
+from the tag.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - tag.set_clean_mode: my_pn7150_id
+
+.. _pn7150-set_format_mode:
+
+``tag.set_format_mode`` Action
+******************************
+
+Use this action to invoke "format mode" -- the next tag presented to the PN7150 will be "formatted", leaving only an
+empty NDEF message structure on the tag.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - tag.set_format_mode: my_pn7150_id
+
+.. _pn7150-set_read_mode:
+
+``tag.set_read_mode`` Action
+****************************
+
+Use this action to invoke "read mode" -- the next tag presented to the PN7150 will be read. This is the default mode
+that the component operates in.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - tag.set_read_mode: my_pn7150_id
+
+.. _pn7150-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``.
+
+.. _pn7150-set_write_mode:
+
+``tag.set_write_mode`` Action
+*****************************
+
+Use this action to invoke "write mode" -- the next tag presented to the PN7150 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_pn7150_id
+
+.. _pn7150-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``.
+
+.. _pn7150-emulation_off:
+
+``tag.emulation_off`` Action
+****************************
+
+Use this action to disable card (tag) emulation mode. The PN7150 will no longer respond to requests from other readers,
+such as smartphones.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - tag.emulation_off: my_pn7150_id
+
+.. _pn7150-emulation_on:
+
+``tag.emulation_on`` Action
+***************************
+
+Use this action to enable card (tag) emulation mode. The PN7150 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 PN7150. This behavior is normal and should
+be expected; it is the result of the PN7150 toggling between polling and listening modes to support both functions.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - tag.emulation_on: my_pn7150_id
+
+.. _pn7150-polling_off:
+
+``tag.polling_off`` Action
+****************************
+
+Use this action to disable card (tag) reading/writing. The PN7150 will no longer read or write cards/tags.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - tag.polling_off: my_pn7150_id
+
+.. _pn7150-polling_on:
+
+``tag.polling_on`` Action
+***************************
+
+Use this action to enable card (tag) reading/writing. The PN7150 will read or write cards/tags.
+
+.. code-block:: yaml
+
+    on_...:
+      then:
+        - tag.polling_on: my_pn7150_id
+
+Triggers
+--------
+
+.. _pn7150-on_tag:
+
+``on_tag`` Trigger
+******************
+
+This automation will be triggered immediately after the PN7150 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 ``pn7150/tag``.
+
+See :ref:`pn7150-ndef_reading` below for how to use the second ``tag`` parameter that is provided to this trigger.
+
+.. code-block:: yaml
+
+    pn7150_i2c:
+      # ...
+      on_tag:
+        then:
+          - mqtt.publish:
+              topic: pn7150/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
+
+    pn7150_i2c:
+      # ...
+      on_tag:
+        then:
+          - homeassistant.tag_scanned: !lambda 'return x;'
+
+You could also send the value to Home Assistant via a :doc:`template sensor </components/sensor/template>`:
+
+.. code-block:: yaml
+
+    pn7150_i2c:
+      # ...
+      on_tag:
+        then:
+        - text_sensor.template.publish:
+            id: nfc_tag
+            state: !lambda 'return x;'
+
+    text_sensor:
+      - platform: template
+        name: "NFC Tag"
+        id: nfc_tag
+
+.. _pn7150-on_tag_removed:
+
+``on_tag_removed`` Trigger
+**************************
+
+This automation will be triggered after the ``tag_ttl`` interval (see above) when the PN7150 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 ``pn7150/tag_removed``.
+
+.. code-block:: yaml
+
+    pn7150_i2c:
+      # ...
+      on_tag_removed:
+        then:
+          - mqtt.publish:
+              topic: pn7150/tag_removed
+              payload: !lambda 'return x;'
+
+.. _pn7150-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 PN7150 and reads the NDEF message it responds with. No parameters are available to this action because data is only
+sent *from* the PN7150 *to* the scanning device.
+
+.. code-block:: yaml
+
+    pn7150_i2c:
+      # ...
+      on_emulated_tag_scan:
+        then:
+          - rtttl.play: "alert:d=32,o=5,b=160:e6,p,e6,p,e6"
+
+.. _pn7150-ndef:
+
+NDEF
+====
+
+The PN7150 supports reading NDEF messages from and writing NDEF messages to cards/tags.
+
+.. _pn7150-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
+
+    pn7150_i2c:
+      # ...
+      on_tag:
+        then:
+          - homeassistant.tag_scanned: !lambda "return tag.has_ha_tag_id() ? tag.get_ha_tag_id() : x;"
+
+.. _pn7150-ndef_writing:
+
+NDEF Writing
+------------
+
+The examples below illustrate how NDEF messages may be written to cards/tags via the PN7150. Note that a
+:doc:`button </components/button/index>` 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_pn7150_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_pn7150_id
+
+See Also
+--------
+
+- :doc:`index`
+- :doc:`pn532`
+- :doc:`rc522`
+- :doc:`rdm6300`
+- :apiref:`pn7150/pn7150.h`
+- :ghedit:`Edit`

index.rst

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