Awesome Open Source
Awesome Open Source

NFC Scanner 🔍 for Home Assistant 🏠


Imagine that you could start or stop everything with a NFC tag in Home Assistant 😄 Every time you hold an NFC tag against the scanner (and the UID of it is included in the list), there will be send an MQTT message to your broker and eventually to Home Assistant. With a LED you also get physical feedback, that the scanner has actually recognized your Tag. Recently I have added the feature to use Over The Air(OTA) updates, with password protection.

For the NFC scanner I designed a circuit board (PCB) and a 3D printed case.

  • In the case folder you will find the required STL files.
  • In the pcb folder you can find the Gerber files. Many people let their boards made by Seeedstudio in Shenzhen.
  • In the img folder some pictures of the project.

If you have suggestions or questions, open an issue or contribute via a PR!



  • PN532 NFC RFID (Elechouse module v3)
  • ESP8266 (NodeMCU v1.0)
NFC reader NodeMCU / ESP8266
SS (CS) D2 (GPIO4)

How to setup

  • You need Arduino IDE to configure some files, and use the serial monitor (other IDE's are okey).
  • You need the PN532, PubSubClient, SPI and ESP8266WiFi library.

Further down this page you will find all information about which adjustments you have to make.

NFC Tags

At NUM_ACCEPTED_UIDS you indicate how many NFC tags/cards you will use. Then enter the UID values of your NFC tags/cards and give each tag/card its own name. If you are going to make multiple nfc scanners, you can indicate in which room the scanner is present with the LOCATION variable.

#define NUM_ACCEPTED_UIDS 2 //<-----------------CHANGE THIS IF ADDING CARDS!!
  // It is neccessary to account for UID length since a 7 byte ID could contain a 4 byte ID, which would cause a misfire
 //  #0    #1    #2    #3    #4    #5    #6   #Tagname
  {{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}, "Tag1", false, 0, false, {0}},
  {{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}, "Tag2", false, 0, false, {0}},

// Location of the NFC scanner
#define LOCATION "living_room"

Finding the UIDs

You can find your UID value in different ways, such as via your phone through certain apps from the app / play store. But to make it easy for yourself, it is possible to read only the UID tags / cards, via the same .ino script.

You start this mode by setting readUIDMode to true, in the ha_nfc_scanner.ino file.

// False wil start de main function, True will start the UID read script so you can find out wich UID's your NFC tags have on the serial monitor.
bool readUIDMode = true;

This way the MQTT and WIFI are switched off and you can read your UID values using the serial monitor.


Enter the details of your Wi-Fi network and login details of your MQTT client account and the IP address of the MQTT broker. Also provide a hostname and password for the Over The Air(OTA) feature.

// OTAupdate
#define OTA_HOSTNAME      ""
#define OTA_PASSWORD      ""

// Wi-Fi credentials
#define WIFI_SSID         ""
#define WIFI_PASSWORD     ""

#define MQTT_USERNAME     ""
#define MQTT_PASSWORD     ""
#define MQTT_SERVER       ""
#define MQTT_SERVER_PORT  1883

Home Assistant - Binary Sensor

in Home Assistant we can create a binary sensor that will respond when a tag is recognized and is in the UID list.

To retrieve and use the results obtained with the NFC scanner into Home Assistant, please edit and add this snippet into your configuration. Make sure to replace <CHIP_ID, <LOCATION> and <NFC_TAG_NAME> with the values defined in config.h.

# Example configuration.yaml entry
  - platform: mqtt
    name: 'NFC Tag 1'
    state_topic: '<CHIP_ID>/sensor/<LOCATION>/<NFC_TAG_NAME>/state'
    availability_topic: '<CHIP_ID>/availability'
  - platform: mqtt
    name: 'NFC Tag 2'
    state_topic: '<CHIP_ID>/sensor/<LOCATION>/<NFC_TAG_NAME>/state'
    availability_topic: '<CHIP_ID>/availability'

PCB Design

Do you live in the Netherlands and you want a PCB? Contact me I have number of PCB's.


If you get an error, create then an issue so that I can sort things out for you. Below the solution for errors that I have encountered.

Not Enough Space

If you get the error message [ERROR]: Bad Answer: ERR: ERROR[4]: Not Enough Space, change in the Arduino IDE the Flash Size to 4M (1M SPIFFS).


A big ⭐️ for mertenats, the script of this repo is based on his.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
C Plus Plus (369,542) 
Arduino (21,651) 
Iot (5,822) 
Mqtt (2,998) 
Home Assistant (2,501) 
Scanner (1,026) 
Pcb (744) 
Stl (434) 
Nfc (331) 
Related Projects
Advertising 📦 9
All Projects
Application Programming Interfaces 📦 120
Applications 📦 181
Artificial Intelligence 📦 72
Blockchain 📦 70
Build Tools 📦 111
Cloud Computing 📦 79
Code Quality 📦 28
Collaboration 📦 30
Command Line Interface 📦 48
Community 📦 81
Companies 📦 60
Compilers 📦 60
Computer Science 📦 74
Configuration Management 📦 39
Content Management 📦 167
Control Flow 📦 197
Data Formats 📦 77
Data Processing 📦 266
Data Storage 📦 132
Economics 📦 60
Frameworks 📦 198
Games 📦 122
Graphics 📦 103
Hardware 📦 148
Integrated Development Environments 📦 47
Learning Resources 📦 147
Legal 📦 28
Libraries 📦 119
Lists Of Projects 📦 21
Machine Learning 📦 336
Mapping 📦 61
Marketing 📦 15
Mathematics 📦 55
Media 📦 228
Messaging 📦 97
Networking 📦 304
Operating Systems 📦 84
Operations 📦 120
Package Managers 📦 52
Programming Languages 📦 229
Runtime Environments 📦 96
Science 📦 42
Security 📦 375
Social Media 📦 26
Software Architecture 📦 70
Software Development 📦 68
Software Performance 📦 57
Software Quality 📦 127
Text Editors 📦 45
Text Processing 📦 131
User Interface 📦 310
User Interface Components 📦 465
Version Control 📦 29
Virtualization 📦 68
Web Browsers 📦 38
Web Servers 📦 25
Web User Interface 📦 194