PN7150 NFC¶

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

An I²C 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 Actions (see below).

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

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, 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, Pin Schema): The pin connected to the PN7150’s IRQ line.
ven_pin (Required, Pin Schema): The pin connected to the PN7150’s VEN line.
wkup_req_pin (Optional, 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, 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, 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 PN7150 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 PN7150 will be “cleaned”, removing all data from the tag.

on_...:
  then:
    - tag.set_clean_mode: my_pn7150_id

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

on_...:
  then:
    - tag.set_format_mode: my_pn7150_id

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

on_...:
  then:
    - tag.set_read_mode: my_pn7150_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 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.

on_...:
  then:
    - tag.set_write_mode: my_pn7150_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 PN7150 will no longer respond to requests from other readers, such as smartphones.

on_...:
  then:
    - tag.emulation_off: my_pn7150_id

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

on_...:
  then:
    - tag.emulation_on: my_pn7150_id

`tag.polling_off` Action¶

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

on_...:
  then:
    - tag.polling_off: my_pn7150_id

`tag.polling_on` Action¶

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

on_...:
  then:
    - tag.polling_on: my_pn7150_id

Triggers¶

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

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

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

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

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

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

pn7150_i2c:
  # ...
  on_tag_removed:
    then:
      - mqtt.publish:
          topic: pn7150/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 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.

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

NDEF¶

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

pn7150_i2c:
  # ...
  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 PN7150. 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_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.

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

Table of Contents

PN7150 NFC¶

Component/Hub¶

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¶

PN7150 NFC¶

Component/Hub¶

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¶