PN7160 NFC¶

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 SPI or I²C.

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 SPI bus or the 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 Actions (see below).

In addition, the NFC Binary Sensor platform may be used to quickly and easily identify tags presented to the reader.

Over SPI¶

The pn7160_spi component allows you to use SPI-equipped PN7160 NFC controllers with with ESPHome.

pn7160_spi:
  cs_pin: GPIOXX
  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:¶

cs_pin (Required, Pin Schema): The pin connected to the PN7160’s NSS (chip select) line.
dwl_req_pin (Optional, 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, Pin Schema): The pin connected to the PN7160’s IRQ line.
ven_pin (Required, Pin Schema): The pin connected to the PN7160’s VEN line.
wkup_req_pin (Optional, 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, 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, Automation): An automation to perform when a tag is first read. See on_tag Trigger.
on_tag_removed (Optional, Automation): An automation to perform after a tag is removed. See on_tag_removed Trigger.
on_emulated_tag_scan (Optional, Automation): An automation to perform when the PN7160 is scanned by another tag reader (such as a smartphone). See on_emulated_tag_scan Trigger.
spi_id (Optional, ID): Manually specify the ID of the SPI Component if you want to use multiple SPI buses.
id (Optional, ID): Manually specify the ID for this component.

Over I²C¶

The pn7160_i2c component allows you to use I²C-equipped PN7160 NFC controllers with ESPHome.

pn7160_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, 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, Pin Schema): The pin connected to the PN7160’s IRQ line.
ven_pin (Required, Pin Schema): The pin connected to the PN7160’s VEN line.
wkup_req_pin (Optional, 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, 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, Automation): An automation to perform when a tag is first read. See on_tag Trigger.
on_tag_removed (Optional, Automation): An automation to perform after a tag is removed. See on_tag_removed Trigger.
on_emulated_tag_scan (Optional, Automation): An automation to perform when the PN7160 is scanned by another tag reader (such as a smartphone). See on_emulated_tag_scan Trigger.
i2c_id (Optional, ID): Manually specify the ID of the I²C Component if you need to use multiple I²C buses.
id (Optional, ID): Manually specify the ID for this component.

Actions¶

`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.

on_...:
  then:
    - tag.set_clean_mode: my_pn7160_id

`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.

on_...:
  then:
    - tag.set_format_mode: my_pn7160_id

`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.

on_...:
  then:
    - tag.set_read_mode: my_pn7160_id

`tag.set_write_message` Action¶

Use this action to set the NDEF message used for “write mode” (see below).

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.

`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.

on_...:
  then:
    - tag.set_write_mode: my_pn7160_id

`tag.set_emulation_message` Action¶

Use this action to set the NDEF message used for card (tag) emulation mode, when enabled (see below).

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.

`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.

on_...:
  then:
    - tag.emulation_off: my_pn7160_id

`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.

on_...:
  then:
    - tag.emulation_on: my_pn7160_id

`tag.polling_off` Action¶

Use this action to disable card (tag) reading/writing. The PN7160 will no longer read or write cards/tags.

on_...:
  then:
    - tag.polling_off: my_pn7160_id

`tag.polling_on` Action¶

Use this action to enable card (tag) reading/writing. The PN7160 will read or write cards/tags.

on_...:
  then:
    - tag.polling_on: my_pn7160_id

Triggers¶

`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 NDEF Reading below for how to use the second tag parameter that is provided to this trigger.

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 homeassistant.tag_scanned Action.

pn7160_...:
  # ...
  on_tag:
    then:
      - homeassistant.tag_scanned: !lambda 'return x;'

You could also send the value to Home Assistant via a template sensor:

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

`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.

pn7160_...:
  # ...
  on_tag_removed:
    then:
      - mqtt.publish:
          topic: pn7160/tag_removed
          payload: !lambda 'return x;'

`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.

pn7160_...:
  # ...
  on_emulated_tag_scan:
    then:
      - rtttl.play: "alert:d=32,o=5,b=160:e6,p,e6,p,e6"

NDEF¶

The PN7160 supports reading NDEF messages from and writing NDEF messages to cards/tags.

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 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.

pn7160_...:
  # ...
  on_tag:
    then:
      - homeassistant.tag_scanned: !lambda "return tag.has_ha_tag_id() ? tag.get_ha_tag_id() : x;"

NDEF Writing¶

The examples below illustrate how NDEF messages may be written to cards/tags via the PN7160. Note that a button is a great mechanism to use to trigger these actions.

The first example will write a simple, fixed NDEF message to a tag.

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.

on_...
  then:
    - tag.set_write_message:
        message: !lambda "return nfc::get_random_ha_tag_ndef();"
    - tag.set_write_mode: my_pn7160_id

Table of Contents

PN7160 NFC¶

Component/Hub¶

Over SPI¶

Configuration variables:¶

Over I²C¶

Configuration variables:¶

Actions¶

`tag.set_clean_mode` Action¶

`tag.set_format_mode` Action¶

`tag.set_read_mode` Action¶

`tag.set_write_message` Action¶

`tag.set_write_mode` Action¶

`tag.set_emulation_message` Action¶

`tag.emulation_off` Action¶

`tag.emulation_on` Action¶

`tag.polling_off` Action¶

`tag.polling_on` Action¶

Triggers¶

`on_tag` Trigger¶

`on_tag_removed` Trigger¶

`on_emulated_tag_scan` Trigger¶

NDEF¶

NDEF Reading¶

NDEF Writing¶

See Also¶

PN7160 NFC¶

Component/Hub¶

Over SPI¶

Configuration variables:¶

Over I²C¶

Configuration variables:¶

Actions¶

tag.set_clean_mode Action¶

tag.set_format_mode Action¶

tag.set_read_mode Action¶

tag.set_write_message Action¶

tag.set_write_mode Action¶

tag.set_emulation_message Action¶

tag.emulation_off Action¶

tag.emulation_on Action¶

tag.polling_off Action¶

tag.polling_on Action¶

Triggers¶

on_tag Trigger¶

on_tag_removed Trigger¶

on_emulated_tag_scan Trigger¶

NDEF¶

NDEF Reading¶

NDEF Writing¶

See Also¶

`tag.set_clean_mode` Action¶

`tag.set_format_mode` Action¶

`tag.set_read_mode` Action¶

`tag.set_write_message` Action¶

`tag.set_write_mode` Action¶

`tag.set_emulation_message` Action¶

`tag.emulation_off` Action¶

`tag.emulation_on` Action¶

`tag.polling_off` Action¶

`tag.polling_on` Action¶

`on_tag` Trigger¶

`on_tag_removed` Trigger¶

`on_emulated_tag_scan` Trigger¶