home-assistant
/
esphome-docs
mirror of https://github.com/esphome/esphome-docs.git
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
esphome-docs/components/pn7150.rst

382 lines
12 KiB
ReStructuredText
Raw Permalink Blame History

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).
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:
dwl_req_pin: GPIOXX
irq_pin: GPIOXX
ven_pin: GPIOXX
wkup_req_pin: GPIOXX
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:`binary_sensor/pn532`
- :doc:`binary_sensor/rc522`
- :doc:`binary_sensor/rdm6300`
- :apiref:`pn7150/pn7150.h`
- :ghedit:`Edit`
Reference in New Issue View Git Blame Copy Permalink