NFC Extension

Overview

The nfc extension allows you to read and write NFC tags through the system. There are a variety of supported readers you can use. Pay attention to the type of tag and reader you are using — not all readers work with all tags and not all readers have the same features.

Extension Configuration

Configure the NFC reader/writer connection that communicates with tags:

{
  "nfc": {
    "key": "nfc_usb_reader",
    "address": "usb:072f:2200",
    "model": "ACR122U",
    "beep_enabled": false,
    "tracking": false,
    "persist_records": true,
    "save_tags": false,
    "writing": true,
    "default_records": [
      {
        "type": "text",
        "data": "MudPi",
        "position": 0
      },
      {
        "type": "uri",
        "data": "https://mudpi.app/docs",
        "position": 1
      }
    ]
  }
}

Tag Events

When you scan a tag, MudPi emits an NFCTagScanned event on the nfc topic with data about the tag including any NDEF data found.

Writing to Tags

MudPi can write to tags if your hardware supports it. Writing is disabled by default — set writing to true in your config to enable it. Be sure to verify the card type before writing and that your reader supports it.

Default Tag Records

Data written to tags uses NDEF format. MudPi writes basic data such as text and a link to the NFC docs by default when writing is enabled. Set default_records to an empty list to disable default data.

To provide your own default records, supply a list of objects with these options:

Tracking

When tracking is enabled, MudPi writes two additional records to the tag: a count:# that increments on each scan, and a last_scan:{datetime} with the timestamp of the last scan. This is useful for tracking scan totals and usage history.

Tag UID and Security

Each tag has a unique serial number (tag_id) set by the manufacturer. When writing is enabled, MudPi generates a UUID for the card that is stored alongside the serial number. This pairing allows MudPi to detect copies or if data was altered outside of MudPi.

Security events emitted when mismatches are detected:

Preregister Tags

Preregister tags in the tags option so MudPi can perform additional operations. The tags dict is keyed by the tag serial number and contains data such as a tag_uid. You can also provide tag-specific default_records.

{
  "nfc": {
    "tags": {
      "123456789ABCD": {
        "tag_uid": "123113-12313123-123123131-1331231",
        "default_records": [
          {
            "type": "text",
            "data": "Custom Default Record for Tag",
            "position": 0
          }
        ]
      }
    }
  }
}

Trigger Interface

The NFC extension provides a trigger interface that listens to NFC scan events. While a state trigger is recommended for most cases, the NFC trigger is useful for responding to specific tag events such as new tags scanned.

{
  "trigger": [
    {
      "key": "nfc_trigger",
      "interface": "nfc",
      "source": "ABCDEF12345789",
      "name": "Tag Scanned",
      "type": "tag_scanned",
      "frequency": "many",
      "actions": ["toggle.turn_on"]
    }
  ]
}

{
  "trigger": [
    {
      "key": "nfc_new_tag_trigger",
      "interface": "nfc",
      "source": "usb_nfc_reader",
      "name": "New Tag Scanned",
      "type": "new_tag",
      "frequency": "many",
      "actions": ["toggle.turn_on"]
    }
  ]
}

Sensor Interface

The NFC extension also provides a sensor interface that listens to NFC scan events for a specific tag. Use this when you want to track a specific tag's data in MudPi.

{
  "sensor": [
    {
      "key": "nfc_tag_1",
      "interface": "nfc",
      "name": "MudPi NFC Tag 1",
      "tag_uid": "67aaa6956-aaaa-aaaa-aaaa-a1b2f12f9a38",
      "tag_id": "123456789ABCDF",
      "reader_id": "nfc_usb_reader",
      "security": 0
    }
  ]
}

Setting Up NFC on Linux

On most Linux distributions the needed drivers are already installed. Visit the reader manufacturer's page for any missing drivers. You can look up the reader address by running:

python3 -m nfc

You may encounter permission errors on the first run. On Raspberry Pi, add proper permissions to the reader through the plugdev group:

sudo sh -c 'echo SUBSYSTEM==\"usb\", ACTION==\"add\", ATTRS{idVendor}==\"072f\", ATTRS{idProduct}==\"2200\", GROUP=\"plugdev\" >> /etc/udev/rules.d/nfcdev.rules'

Then reload the udev rules and reattach the reader:

sudo udevadm control -R

Ensure the user account is a member of the plugdev group:

sudo adduser mudpi plugdev