How To Guides

How to build a WiFi connected Fingerprint Sensor with Home Assistant

A Wifi enabled fingerprint sensor with Home Assistant showing

When I posted some update videos on Reddit and Twitter (make sure to follow me there for more updates!) earlier this week about the Fingerprint Sensor update, the reaction was so wonderfully positive that I knew I had to get onto this guide as soon as possible! Here was one of the videos showing the fingerprint sensor connected to Home Assistant over WiFi:

A bit of back story on this project and how it came about – I’ve had these fingerprint sensors for about 5 years now just sitting in a box, I had played with them initially and got them working but to me they were inconvenient because you couldn’t easily add and delete prints without reprogramming them and if you had multiple sensors you’d have to add a new print at each sensor individually – this was before I’d heard of any ESP8266 boards and was working with Arduino boards only.

At the time I searched for ways to use the fingerprint sensor as a scanner, while storing the print data in some sort of database. I couldn’t find anything at all and so I put them back in the box and moved onto other projects. Fast forward 5 years and I decided to take another crack at them, ideally integrating this fingerprint sensor directly with Home Assistant.

Not much has changed in terms of the information online, except I see more and more people asking how to connect them to a network to be able to manage them, but no answers!

So that’s where this guide comes from, I wanted to provide answers and a method for those people asking how to do it that never got their answer. To be clear, you notice I said above I wanted to store the print data in a database – this guide does not solve that aspect (although it wouldn’t be hard to do from here), but it does allow you to manage it from a central location and easily add and remove prints.

Let’s get into it!


Video Guide


If you have not yet checked out the simpler version of this guide yet, I’d suggest following that first so that you are familiar with some of the concepts of enrolling and checking prints, I go over the concepts in a bit more detail there. This guide will move at a bit of quicker pace than that one.

Similarly, we are using MQTT as our method of communicating with Home Assistant, if you do not have an MQTT broker installed or don’t know what one is, check out this guide here for everything you need to know and how to install.

Finally, we are going to be adding various sensors to Home Assistant via the config files, be sure you are familiar with how to do that by reading the Getting Started with Home Assistant series. Of course you can use any other MQTT compatible Home Automation software you wish, that’s the beauty of MQTT!

Parts List

If you followed the Arduino version of this guide, the parts list is similar with a few exceptions:


Wiring the Fingerprint Sensor is a pretty easy job with just 4 wires required (despite there being 6 pins on the board). First lets take a look at an overview of the sensor:

And here is some of the specifications of this sensor from the Adafruit listing:

  • Supply voltage: 3.6 – 6.0VDC
  • Operating current: 120mA max
  • Peak current: 150mA max
  • Fingerprint imaging time: <1.0 seconds
  • Storage capacity: 162 templates
  • Safety ratings (1-5 low to high safety)
  • False Acceptance Rate: <0.001% (Security level 3)
  • False Reject Rate: <1.0% (Security level 3)

As you can see, its a pretty capable sensor for the price!

Firstly, here is the wiring diagram we are going to be working with:

One thing to bear in mind here is that the pins marked on the ESP8266 boards do not translate directly into the Arduino IDE – i.e D4 is not pin 4 in the IDE – Arduino IDE uses GPIO so make sure to look up the GPIO output for your board. In my case, I’m using pins D5 and D6 on the Wemos, which translates to GPIO 14 and GPIO 12, which is the pins we use in the code for the TX and RX pins.

And here is a close up of the sensor with each pin labelled:

Go ahead and wire everything up, connect your Wemos via USB to your computer and startup the Arduino IDE.


Arduino IDE

Firstly, make sure you have esp8266 boards added to Arduino IDE. Follow this super quick guide to do that (takes less than a minute). Once you’ve done that, we need to add some additional libraries which are as follows:

  • Adafruit Fingerprint Sensor Library – allows us to easily interface with the fingerprint sensor
  • PubSubClient – provides the MQTT connectivity
  • ArduinoJSON – provides the framework for sending JSON message to Home Assistant

One other important thing to check, make sure the Arduino IDE is up to date, I had real issues with the SoftwareSerial library (included in core) using an esp8266, the Wemos D1 would lose connection to the sensor all the time, I eventually found I was using version 5.x of the SoftwareSerial library which worked fine with Arduino but not with esp8266 – updating to 6.8.1 immediately fixed all these issues.

With that out the way, we can now continue to load the code into the IDE. You will find the latest code on GitHub here.

Load the fingerprint_mqtt sketch and be sure to select the correct board from the boards menu, “LOLIN(WEMOS) D1 R2 & mini” for Wemos D1 Mini, and also make sure to select the COM port.

Change the variables at the top to suit your environment, making sure to set the SSID, WiFi password, MQTT topics and MQTT credentials. Again if you are unsure, check the MQTT guide for details.

You can now upload the code to the board and open the serial monitor, you should see something like this:

Which is perfect, the device is now awaiting for a finger to be placed on the sensor. If you receive a message that the sensor is not found, double and triple check the wiring, particularly the RX and TX lines – it’s very easy to get them the wrong way round.

Hopefully you followed the Arduino guide and you have enrolled some prints. If you haven’t we can do it later but you can still test the scanner by placing a finger on it:

If all is successful, we are ready to add it to Home Assistant!

Home Assistant

We need to create a few sensors in Home Assistant, make sure to check GitHub for the latest code but add the following to the configuration.yaml file (make sure you have added MQTT broker to Home Assistant first):


  - platform: mqtt
    name: "Fingerprint"
    state_topic: "/fingerprint/mode/status"
    value_template: "{{value_json.state}}"
    json_attributes_topic: "/fingerprint/mode/status"
    json_attributes_template: "{{value_json | tojson}}"
  - platform: template
        friendly_name: "Fingerprint Sensor Mode"
        value_template: >-
          {{state_attr('sensor.fingerprint', 'mode')}}
        icon_template: >-
          {% if is_state('sensor.fingerprint_mode', 'reading') %}
          {% elif is_state('sensor.fingerprint_mode', 'learning') %}
          {% endif %}
        friendly_name: "Fingerprint State"
        value_template: >-
        icon_template: >-
          {% if is_state('sensor.fingerprint', 'Waiting') %}
          {% elif is_state('sensor.fingerprint', 'Matched') %}
          {% elif is_state('sensor.fingerprint', 'Not matched') %}
          {% endif %}
        friendly_name: "Fingerprint ID"
        value_template: >-
          {{state_attr('sensor.fingerprint', 'id')}}
        friendly_name: "Fingerprint Person"
        value_template: >-
          {% if is_state('sensor.fingerprint_id', '1') %}
          {% elif states.sensor.fingerprint_id.state | int > 1 %}
          {% elif is_state('sensor.fingerprint', 'Waiting') %}
          {% elif is_state('sensor.fingerprint', 'Not matched') %}
            Not matched
          {% endif %}
        icon_template: >-
          {% if is_state('sensor.fingerprint', 'Waiting') %}
          {% elif is_state('sensor.fingerprint', 'Matched') %}
          {% elif is_state('sensor.fingerprint', 'Not matched') %}
          {% endif %}

You can see from the code that the first sensor we create, we stores the state of the fingerprint, then everything else as attributes. Then the template sensors are used to bring the attributes out into their own sensors so we can display them in Lovelace.

Make sure to restart Home Assistant to add the sensors, then make sure you are receiving data using the Dev Tools for those sensors.

Next, we need to create an input box which will allow us to tell the sensor which ID we want to either add a fingerprint as, or which fingerprint we want to delete. In Home Assistant, head over to Configuration > Helper and add a new helper. Select number from the list. Fill out the details as follows:

Make sure to set the minimum and maximum numbers to 1 and 127, this is the range of IDs that the sensor can accept.

Once you have created your helper, you will notice the entity ID has been generated, be sure to take a note of this for the next step.

Then, we need to create 2 scripts to allow for learning and deletions of prints. In Home Assistant, head over to Configuration > Scripts and add a new script for learning which looks like this:

You can see we are using the MQTT publish service to trigger our esp8266 into learning mode, sending the ID to use as the payload.

Note how the payload of the message is the input helper we created, expressed as an integer, which is what our MQTT topic is expecting.

Do the same for the deletion, being sure to change the topic:

If you are using config files for scripts, the code looks like this:

  alias: Fingerprint learning mode
  - data:
      payload_template: '{{states(''input_number.fingerprint_learning_id'') | int}}'
      topic: fingerprint/mode/learning
    service: mqtt.publish
  alias: Fingerprint Delete Print
  - data:
      payload_template: '{{states(''input_number.fingerprint_learning_id'') | int}}'
      topic: fingerprint/mode/delete
    service: mqtt.publish

And finally, head to Lovelace and add your entities and buttons (for the learn script and delete script) like so:

The way I am achieving this is using a glance card with the 3 entities along the top – Fingerprint Mode, Fingerprint State and Fingerprint Person – then the bottom card is a horizontal stack card with an entity card for the ID text box, then a vertical stack card with 2 button cards, one for each script.

If all goes well, you should now have everything working!

Adding/Deleting prints

Now that you have completed the above, we should now have the ability to add and delete fingerprints from the fingerprint sensor using Home Assistant.

The following video shows how to add and delete prints:

Go ahead and enter an ID in the input box, from 1 to 127, and hit learn. You will see the state box changes state to tell you to place the finger. Once placed, the fingerprint sensor will take an image, ask you to remove the finger then replace the same finger again to make sure it matches. Once you remove the finger a second time the print will be stored.

Deletion is as easy as entering the ID you want to delete and hitting delete, a message will appear instantly telling you its been deleted.


As always, be sure to check wiring, in particular the TX and RX pins are the correct way round.

Ensure that you are getting power to the sensor, there are testing pads on the back that you can check the voltage, you should be receiving 3.3v at the pads.

Make sure the SoftwareSerial library within Arduino IDE is on the latest version!

In Home Assistant, go to Dev Tools > MQTT and subscribe to the state topic to ensure events are coming through correctly, if they are then you know data is being published from the esp8266 correctly.


There are a couple of improvements that can be done to make things a bit nicer, you can change the colour of the icons depending on a match or fail by using the “Custom UI” add-on for Home Assistant, you can find it on Github here.

I’ve also been trying to think of a way to be able to store the fingerprint sensor ID numbers and a persons name in Home Assistant so that they can be used on match but I haven’t figured out a way to do that yet unfortunately.

For example, I’d like to have a text box next to the ID box that you could enter a name in on the learning process that would create a sensor in Home Assistant called “sensor.fingerprint.id.x” where x is the ID number, then the state of that would be the name in the box so “Lewis”. Then when the ID is sent from the sensor, it would match up and display the persons name in the UI. You can do this manually by adding this to the person sensor in the config file:

        friendly_name: "Fingerprint Person"
        value_template: >-
          {% if is_state('sensor.fingerprint_id', '1') %}
          {% elif states.sensor.fingerprint_id.state | int > 1 %}
          {% elif is_state('sensor.fingerprint', 'Waiting') %}
          {% elif is_state('sensor.fingerprint', 'Not matched') %}
            Not matched
          {% endif %}

But its tedious to add one every time. If anyone discovers a good way, please do let me know!


Community member James has kindly designed 2 enclosures for this project, one as a standalone case and one that will fit inside a wall plate. You can check them out here and here.

Thanks also to LuckyPants for designing this enclosure which clips together and mounts to a wall.


I hope you enjoyed this project and you have successfully managed to add a fingerprint sensor to Home Assistant, it was surprisingly a lot of fun making it, and I really appreciated all the message/comments/general enthusiasm I got from everyone.

I’d love to see what you guys make with this, please tweet or send photos to me of what you make and come up with!

Any problems, let me know in the comments, make sure to subscribe below for instant updates on future posts!

Want to support me?

If you like the content I put out and would like to support me, you can do so using the options below.

I can't state enough how much any support is greatly appreciated and will go directly back into funding new/bigger projects and website upkeep.

Tagged , , ,
  1. Easwaran C

    Great work, I tried it today it works like a charm in the first test.
    I was trying to implement this in ESP Home but due to my lack of coding skill I couldn’t
    Thanks a lot.

    I observed that scripts .yaml says learning & deleting MQTT topics as home/fingerprint/mode/learning
    but as per the code its /fingerprint/mode/learning

    It would be great if you change the documentation , it will be helpful for new people who tries this code


  2. Easwaran C

    Also I see the LED on the Fingerprint sensor blinking always (Waiting to scan). Is there a way we can have a MQTT topic that can be triggered ON to make the sensor wake for scanning & OFF after xx seconds to make it sleep mode so LED doesn’t blink always?

    That would be a great feature.

    1. Lewis Barclay

      Possibly a good idea, if I get the time I will see if it can be implemented or feel free to put in a PR if you wish on GitHub! Thanks again for the support, appreciate it!

  3. Denis

    Good afternoon. Thank you very much. Great job !!!
    I’m trying to repeat Your project. I haven’t finished yet, but so far everything is going fine. At the end, I will definitely write about my results.
    The project will be very popular with the community.
    It would be great to integrate it into ESPHOME.

    1. Lewis Barclay

      Hi Denis,

      Thank you for your kind words, make sure to send me your project when you are done, I would love to see what you do with it!

      ESPHome integration would be great I agree, hopefully we can do that one day!

  4. Adam

    Great tutorial, followed it and everything worked perfectly!

    I think there’s still a bit of misalignment between the mqtt topics across the files on github and the pastes in here though (might be easier just link to the github ones!)

    I’ve just seen someone else has commented this but I’ve managed to setup the LED to come on/off over a mqtt channel based on the motion sensor state in the hallway. I’ll get a PR up for it before the end of the weekend if I get a chance? (although does require a few changes to the library files themselves as it’s not natively supported). Also trying to design a nice little 3D case to house it all but not a great designer myself ha

    1. Lewis Barclay

      Hey Adam, glad you manged to follow through, great to hear!

      Thanks for that, I’ve updated the Github topics, I forgot initially when I saw the other comment.

      Sure, feel free to put a PR in, perhaps we can add it as an additional sketch?

      I was going to try and get a 3D printed case up also, but also I amn’t very great at it yet, very new to the 3D world! But if you manage to get one done before me, feel free to let me know and I will be happy to link it!

      Thanks for the feedback!

  5. Adam

    Raised a PR into yours when you get a chance to look. My 3D skills are pretty poor too haha so whenever I get one I’m somewhat happy with I’ll upload to thingiverse and chuck a link in here for anyone who’s worse than me ha.

    I don’t suppose you get loads of “communication errors” in your d1 mini log? I get absolutely loads, the scanner still works as expected unless you happen to scan the finger whilst it’s also throwing the error. Not sure what it is as it seems to work as expected apart from that. Seems to be very intermittent.

    1. Lewis Barclay

      Hey Adam,

      Nice work thanks, will check it out.

      I do get them, not “lots” but occasionally and for me they don’t interrupt the scanning for more than 1 cycle/loop. I think its to do with the SoftwareSerial implementation for esp boards – searched around and found lots of issues with them. Don’t get that at all using the same code on Arduino. What baudrate are you using? The same as in the Github code?


  6. Adam

    I guess “lots” isn’t that useful a measurement… I’ve just timed it and I got 68 within a 10 minute window (a couple of “unknown errors” in there too) and as you said it doesn’t break but if I happen to scan and get one at the same time I’ve gotta do it again. Sadly an arduino is probably a bit overkill for this as I want the smallest fully encased form factor as possible!

    I’ve not really made that many changes to the code and even if I run the code with no modifications (same baudrate etc) I still get them so it’s not that. I’m hoping to use it to arm/disarm the home security system (indoors) so I’ve attached a small OLED panel to display status etc. Will pop a pic in when it’s all happily running.

    1. Lewis Barclay

      That’s possibly slightly more than I was getting, but I haven’t timed it. I suppose if you work out how many loops you are doing in a 10 minute window then compare that to the 68 you got that would give you a percentage! But I agree its annoying, I’m pretty sure its the SoftwareSerial implementation!

      Please do, that would be awesome!

  7. James

    I’m having some problems and hopefully you can help me here. Whenever i try to upload the sketch im met with an error

    exit status 1
    redefinition of ‘SoftwareSerial mySerial’

    i uninstalled arduino IDE and reinstalled it using the latest directly from the download page. Went through all of the steps you outlines before. I dont have my fingerprint sensor yet so i havent hooked one up to the board would that cause the issue?

  8. James

    I was trying it out with these specific boards


    It wasnt working for me so i decided to go ahead and grab some of these instead


    they should arrive today and i can try it again. Hopefully it works out well. im planning on making electromagnetic door locks with fingerprint readers to disengage the lock.

    this is the power supply i went with for the lock itself


    and this is the lock i chose


    and this is the fingerprint sensor i purchased


  9. James

    Just got my wemos d1 minis in today and all worked well finally. I have the fingerprint scanner working now.

    I designed a 3d print for a box to contain the scanner and the wemos. It’s printing now so I’ll post the thingiverse file once I know all works well.

    1. Lewis Barclay

      Hi James,

      Thanks for the information, that looks really great! I’ve been wanting to try with a lock also, will hopefully get round to that. The NodeMCU board should have worked, did you make sure to select the right one from the boards menu?

      If your 3D print goes well, send me it and I will link it here!

      Thanks for sharing!

  10. James

    using this power supply for the lock


    Is there a way to have the fingerprint sensor send the command to the power supply to open the lock? This power supply can be used with nfc/numeric keypads and buttons to open the lock. Right now my plan is just to use a smart plug connected to the power supply to cut the power to the power supply to open the lock but this doesnt seem optimal. But i personally have no idea how to write the code needed for this to function and also have no clue how it would be wired up.

    1. Lewis Barclay

      Hi James,

      Definitely seems do-able, can you not wire it directly to the Wemos? It seems quite simple (just from a quick glance!) but you should be able to use the GPIO as a “signal” wire to the push input which should trigger the lock to operate. But always test with a meter first to make sure the voltages are within safe limits of the device and they are what you expect.

  11. james

    Okay just finished up the case for this project. Let me know if you have any issues or suggestions for it and ill be sure to fix it up.


    Could you explain in further detail what exactly i would need to do to get this hooked up properly to the door lock system im using?

    I have it working great right now just flipping the power on and off but im afraid this approach is going to harm the power supply.

    1. Lewis Barclay

      Thanks for the case!

      It’s hard for me to say without seeing it but looking at the diagram it looks like the normal access pad that they supply, it sends a signal to the “push” terminal on the power supply when access is approved. In theory you might be able to use a digital output on the Wemos to replicate the access pad. To test you could try connecting the push pin to the a digital output on the wemos, ground to ground. Then set the output on the Wemos high and see what happens. Be careful you don’t damage the Wemos with too much voltage. Measure that there is 0v on the push terminal before connecting it.

  12. James

    Whoops i didnt even see your previous comment. Which pin on the wemos would you suggest hookinh the wire to? I just need 1 wire from the wemos to the push then thats it? nothing i need to add to the sketch to make it work properly?

    Maybe i wasnt being clear but what i need is as follows

    I put finger on sensor and home assistant detects that it is me. Home assistant sends signal to wemos to pass the signal from the wemos to the push function of the power supply which then opens the lock. Could you help me with getting this working properly? In a couple weeks i could possibly donate some of the hardware needed for the project.

    1. Lewis Barclay

      Any of the free/available digital pins will work. Yes there changes that will need to be made to the sketch for sure, but in the meantime I would suggest getting it working without the fingerprint sketch, just make another sketch that sets the digital pin you’ve chosen high and see if that does anything to the lock. Obviously you need the powers and grounds connected as normal but if we look at the diagram from the listing it shows that the only pin that comes from the keypad to the power supply other than power and ground is the “push” pin, so trying that first is probably the best place to start!

  13. James

    Alright ill get to work on that. might take me a while since ive never done anything with the arduino sketch stuff before this tutorial. Ill def give it a try though. I did find my volt meters and checked the push part of the supply and its putting out 5v.

    1. Lewis Barclay

      Ah sorry, assumed you had. That’s even more impressive what you’ve done then!

      Is 5v coming out of the push pin on the power supply? If so don’t connect it to a digital pin on the arduino. Or did you mean the key pad outputs 5v?

      I can help on discord

  14. Douglas


    I’m having the same problem as Jaime and I’m using the “NodeMCU” model.

    D: \ Douglas \ OneDrive \ Automation \ FingerPrint \ fingerprint-mqtt-master \ fingerprint-mqtt-master \ fingerprint-mqtt \ fingerprint-mqtt-led.ino: In function ‘void callback (char *, byte *, unsigned int) ‘:
    fingerprint-mqtt-led: 412: 6: error: redefinition of ‘void callback (char *, byte *, unsigned int)’
    fingerprint-mqtt: 402: 6: error: ‘void callback (char *, byte *, unsigned int)’ previously defined here
    exit status 1
    redefinition of ‘SoftwareSerial mySerial’

  15. Jeff Alperin

    I’ve spent many hours changing pins and boards attempting to overcome the dreaded sensor not found message. I finally get something different:
    10:23:15.772 -> Welcome to the MQTT Fingerprint Sensor program!
    10:23:16.769 -> ⸮⸮⸮⸮⸮
    This is now consistent. I get the same special characters each time, but what is it? Any suggestions?

  16. Douglas


    Eu tentei as placas:
    – Generic ESP 8266 Module
    – Generic ESP 8265 Module
    – NodeMCU 0.9 (ESP-12 Module)
    – NodeMCU 1.0 (ESP-12E Module)

    Sempre o mesmo problema com “SoftwareSerial”.

  17. Douglas

    In English, sorry

    I tried the plates:
    – Generic ESP 8266 Module
    – Generic ESP 8265 Module
    – NodeMCU 0.9 (ESP-12 Module)
    – NodeMCU 1.0 (ESP-12E Module)

    Always the same problem with “SoftwareSerial”.

    1. Lewis Barclay

      Hi Douglas,

      Sorry I only just saw your other comment with the boards.

      Which board are you using for your project? I know which board you are selecting in the project but which board do you physically have?

    1. Lewis Barclay

      Hi Douglas,

      I notice you are using the fingerprint-mqtt-led script – can you try the standard one? I have not tried the LED version of the script so I have no way of confirming if it works.

      You can catch me on discord I am sure we can get it to work 🙂

    2. Lewis Barclay

      I re-read the error you are getting – the SoftwareSerial is a red-herring, this does not appear to be the error. The issue is with the callback line for the MQTT callback

  18. Douglas

    It seems to be moving towards the solution.

    Using “fingerprint-mqtt” he uploaded without the error “SoftwareSerial”. I checked and connected to MQTT as well, but the message did not appear, but strange characters.

    Example: ⸮⸮⸮ ⸮xf

    These characters appear whenever I put the fingerprint.

  19. Douglas

    The reason for the strange characters is that in the console (log) the field was set to “115200 baud”. Changing to 57600 the information appeared correctly, but SCRIPT is not putting it in “learning” mode.

  20. Jeff Alperin

    Hello Lewis
    Thanks for responding.
    My board is an esp8266mod. I’ve used generic 8266, nodemcu 0.9 and nodemcu 1.0. Same results with all.
    There are actually 10 special characters, but they don’t all show after copy/paste.
    My debug mode is everything, but that doesn’t seem to have any impact. No messages show up. I don’t really know how to use it.
    The monitor is set to 57600.

  21. Adam

    Did you ever manage to find a way of storing and using an array of id’s and names rather than needing to manually handle it all?

  22. Steven Rollason

    I’ve not actually tried building this myself, but I have worked out a way that you can store and retrieve the fingerprint ids and names.
    You would need two new text Helpers (named “Fingerprint Data” and “Fingerprint Learning Name” in my example here) and add the following to the end of the learning script:

    – service: input_text.set_value
    entity_id: input_text.fingerprint_data
    data_template: >
    {%- set print_id = states(“input_number.fingerprint_learning_id”)|string -%}
    {%- set print_name = states(“input_text.fingerprint_learning_name”) -%}
    {%- set prints = states(“input_text.fingerprint_data”) | from_json
    if states(“input_text.fingerprint_data”)
    else [] -%}
    {{ (prints|rejectattr(‘id’, ‘eq’, print_id) | list + [{“id”: print_id, “name”: print_name}]) | tojson }}

    This parses JSON data from the Fingerprint Data helper, removes the print with that id (if present), adds the new print id and name to the list, and writes it back as JSON to the helper.
    and this to your delete print script:

    – service: input_text.set_value
    entity_id: input_text.fingerprint_data
    data_template: >
    {%- set print_id = states(“input_number.fingerprint_learning_id”)|string -%}
    {%- set prints = states(“input_text.fingerprint_data”) | from_json
    if states(“input_text.fingerprint_data”)
    else [] -%}
    {{ (prints|rejectattr(‘id’, ‘eq’, print_id)) | tojson }}

    This does similar, but just removes the existing print and writes the list as JSON to the Fingerprint Data helper.

    Your sensor can then be like this:

    friendly_name: “Fingerprint Person”
    value_template: >-
    {% if states(‘sensor.fingerprint_id’) | int >= 1 %}
    {%- set prints = states(“input_text.fingerprint_data”) | from_json
    if states(“input_text.fingerprint_data”)
    else [] -%}
    {%- set fingerprint = prints|selectattr(‘id’, ‘eq’, states(‘sensor.fingerprint_id’)) | first -%}
    {{ fingerprint[“name”] if fingerprint else states(‘sensor.fingerprint_id’) }}
    {% elif is_state(‘sensor.fingerprint’, ‘Waiting’) %}
    {% elif is_state(‘sensor.fingerprint’, ‘Not matched’) %}
    Not matched
    {% endif %}

    If the value of the fingerprint id sensor is greater than or equal to 1, this finds the details in the JSON data in the text helper, and return the name if it finds it otherwise it will return the fingerprint id.

    (I tried simplifying these by using a JSON dictionary instead of an arrary of objects, but there doesn’t appear to be a way to update dictionaries in templates in Home Assistant).

  23. Raymond-NL

    Hi Lewis, Is it working the script from Steven?
    If I have a little more time, I will try it too.
    First make the 3D prints for the FPM 😉
    Thanks Mate

  24. Marcos

    Hi Lewis, Im always had same message “Hard resetting via RTS pin”.

    I dont understand what is wrong, i select my board and COM in arduino, I have installed all libraries included Software Serial.

    But same error. This is my conf is sketch:

    // MQTT Settings
    #define HOSTNAME “fingerprint-sensor”
    #define MQTT_SERVER “”
    #define STATE_TOPIC “/fingerprint/mode/status”
    #define MODE_LEARNING “/fingerprint/mode/learning”
    #define MODE_READING “/fingerprint/mode/reading”
    #define MODE_DELETE “/fingerprint/mode/delete”
    #define AVAILABILITY_TOPIC “/fingerprint/available”
    #define mqtt_username “hassio”
    #define mqtt_password “uBsN9nWkYtDGwEWCS1gb”

    I dont know if quotes “” must be necessary or not and if the mqtt server need port too “”

    Pls can help me

  25. Adam

    Hi Steven, just went to try out your code but the formatting on here is so out of place it just doesn’t work when copied over. I don’t know enough about templating to correct it, could you upload to pastebin or something please?

  26. maurizio

    where am i wrong?

    16:37:14.141 -> Welcome to the MQTT Fingerprint Sensor program!
    16:37:15.167 -> Found fingerprint sensor!
    16:37:15.261 -> Connecting……….
    16:37:19.594 -> Connected, IP address:
    16:37:19.594 -> Attempting MQTT connection…connected
    16:37:37.978 -> Image taken
    16:37:38.443 -> Image converted
    16:37:38.443 -> Unknown error
    16:37:42.956 -> Image taken
    16:37:43.472 -> Image converted
    16:37:43.472 -> Unknown error
    16:37:43.846 -> Image taken
    16:37:44.360 -> Image converted
    16:37:44.360 -> Unknown error
    16:37:44.736 -> Image taken
    16:37:45.250 -> Image converted
    16:37:45.250 -> Unknown error
    16:37:45.624 -> Image taken
    16:37:46.137 -> Image converted
    16:37:46.137 -> Unknown error
    16:37:46.510 -> Image taken
    16:37:46.977 -> Image converted
    16:37:46.977 -> Unknown error
    16:37:47.351 -> Image taken
    16:37:47.865 -> Image converted
    16:37:47.865 -> Unknown error
    16:37:48.238 -> Image taken
    16:37:48.741 -> Image converted
    16:37:48.741 -> Unknown error
    16:37:49.115 -> Image taken
    16:37:49.629 -> Image converted
    16:37:49.629 -> Unknown error
    16:37:50.003 -> Image taken
    16:37:50.518 -> Image converted
    16:37:50.518 -> Unknown error
    16:37:50.894 -> Image taken
    16:37:51.362 -> Image converted
    16:37:51.362 -> Unknown error
    16:38:04.881 -> Communication error
    16:38:12.900 -> Communication error
    16:38:29.381 -> Image taken
    16:38:29.894 -> Image converted
    16:38:29.894 -> Unknown error
    16:38:32.923 -> Image taken
    16:38:33.391 -> Image converted
    16:38:33.391 -> Unknown error
    16:38:55.567 -> Communication error
    16:38:59.804 -> Communication error

  27. maurizio

    I can store and delete fingerprints via home hassistant. I cannot read for stored fingerprints. it gives me back Unkown error.
    if it can be useful I customized all the error messages.
    random gives me this error message:
    13:43:35.792 -> Communication error_A

    in code:

    uint8_t getFingerprintID() {
    uint8_t p = finger.getImage();
    switch (p) {
    Serial.println(“Image taken”);
    //Serial.println(“No finger detected”);
    return p;
    Serial.println(“Communication error_A”);
    return p;
    Serial.println(“Imaging error 1”);
    return p;
    Serial.println(“Unknown error 2”);
    return p;

    while when I read the fingerprint it gives me this error:

    in code:
    // OK converted!
    p = finger.fingerFastSearch();
    if (p == FINGERPRINT_OK) {
    Serial.println(“Found a print match!”);
    lastID = finger.fingerID;
    lastConfidenceScore = finger.confidence;
    return p;
    Serial.println(“Communication error 2”);
    return p;
    } else if (p == FINGERPRINT_NOTFOUND) {
    Serial.println(“Did not find a match”);
    return p;
    } else {
    Serial.println(“Unknown error 4”);
    return p;

    I state that with another simple sketch the tellor works correctly.

  28. cseb

    Hi thanks for this project !

    I’m a newbie with HA, could you share the configuration for the button in lovelace ?


  29. separate function or still connected to PC?

    Hi, sorry for some stupid question. I play with homeassistanten, I have no experience with anduino. When I connect according to your instructions, everything needed is loaded into the andruino board and andruino, ESP, the fingerprint reader then works independently (power only, data is sent via wifi to mqtt), or it is still necessary to be connected via usb to the computer (andruino accesses the necessary libraries via a computer)? Thanks for the reply.

  30. Ian

    Hi Lewis,

    Great guide and I managed to get it working, albeit with a few struggles due to my lack of knowledge.

    I’m now trying the more advanced one of only having the light on when a fingerprint is detected. I’ve amended the library as per your instructions and it all compiles and uploads and I get no errors.

    The problem is that using this, it no longer seems to detect the fingerprint. I suspect it has something to do with the /fingerprint/available MQTT topic showing as offline but, other than manually publishing it as online, which doesn’t help, I can’t see where I’ve gone wrong.

    Any pointers?

  31. separate function or still connected to PC?

    Arduino: 1.8.13 (Windows 10), Vývojová deska: “LOLIN(WEMOS) D1 R2 & mini, 80 MHz, Flash, Legacy (new can return nullptr), All SSL ciphers (most compatible), 4MB (FS:2MB OTA:~1019KB), v2 Lower Memory, Disabled, None, Only Sketch, 921600”

    C:\Users\nickk\Plocha\fingerprint-mqtt-led-touch-oled\fingerprint-mqtt-led-touch-oled.ino: In function ‘void loop()’:

    fingerprint-mqtt-led-touch-oled:204:12: error: ‘class Adafruit_Fingerprint’ has no member named ‘CloseLED’



    exit status 1

    ‘class Adafruit_Fingerprint’ has no member named ‘CloseLED’


  32. František Kroupa

    I add lines that are in the code (github)

    if (fingerState == HIGH) {
    } else {

  33. Franta

    Please is this a live topic?
    Is there anyone who can help, advise?
    I solved the code by rewriting the line. I’ll load it and turn on the serial monitor. But the program does not find, only this list is displayed

    20:28:29.229 ->
    20:28:29.229 -> ets Jan 8 2013,rst cause:2, boot mode:(3,6)
    20:28:29.262 ->
    20:28:29.262 -> load 0x4010f000, len 3584, room 16
    20:28:29.262 -> tail 0
    20:28:29.262 -> chksum 0xb0
    20:28:29.262 -> csum 0xb0
    20:28:29.262 -> v2843a5ac
    20:28:29.262 -> ~ld

  34. Hugo Stegeman


    I have linked the finger scanner to my home assistant and i like it a lot.
    But I actually want to place the scanner at my garage and then open the door with it.
    Unfortunately my internet connection is not always that strong in the garage.
    Is there a way to run the scanner standalone to switch a relay or something?
    But to send data via home assistant when wifi is available?
    So I can keep track of who goes in and out the door.

  35. Usman Aslam

    worked for me. Please share the code to unlock a lock with D1Mini GPIo trigger, (offcourse through 3v to 12 relay);

  36. Ville Westerholm

    Thousand thank Lewis, now I have a device that turns off alarm system at my home. Exactly like you described in that earlier video

    I used 1″ OLED display showing the status sent to MQTT and used https://www.thingiverse.com/thing:4577094 as the case. Was really tight, had to learn soldering and destroyed one D1 and one display on the way.

  37. Usman Aslam

    can you share link of the OLED you are using. Also the code to unlock the aalrm system with the biometric.

  38. Usman Aslam

    hi, i have changed the code to active the GPIO on D1 mini based on the finger print ok or not found. It works independently very well even when HA is down. What i am looking for is to use HA to trigger the GPIO on the D1 mini through MQTT but all in vain.
    I tried example at


    and it worked. But when i try to integrate the similar code in the Finger print code , i dont get mqtt message published to D1 mini. I spend plenty of time trying diffrent ways but to no avail. I am not a coder.
    Basically i am try to open the lock from HA by activating the GPIO on D1 mini.

    Appreciate if someone can help me.

  39. Ville Westerholm

    “can you share link of the OLED you are using. Also the code to unlock the aalrm system with the biometric.”

    I used https://www.az-delivery.de/en/collections/more-products-4/products/0-96zolldisplay,
    You can find similar displays e.g. from eBay.

    Now I replaced the fingerprint reader with this https://www.dfrobot.com/product-2051.html The earlier one (described above) gives me continuously communication errors and does not recognize finger always.

    Had to learn to draw cases with CAD…

  40. Dion

    @maurizio I am also getting the “Unknown error” problem when trying to read a print. Did you resolve this problem?

  41. Dion

    I changed the code from:
    in the getFingerprintID function
    and I no longer get the Unknown error problem

  42. Usman Aslam

    i am trying the LED touch version. The issue i am facing is that when LED is off as there is no finger on the sensor, learning and delete commands dont work looks like sensor dont receive mqtt messages while LED is off. I also tried sending sensorOn command through mqtt in HA but no response from the sensor, can any one help please

  43. MisterP

    Hey guys, everything works finde. but no connection towards WIFI Checked the SSID and PW Seriell monitor answers he found the fingerprint, then connecting……………………………(endless points) Any ideas or does someone have the same problem? Thanks and Kind Regards Peter

Leave a Reply

Your email address will not be published. Required fields are marked *