It's easy to use the optical fingerprint sensor with Python and CircuitPython, and the Adafruit CircuitPython Fingerprint module. This module allows you to easily write Python code that reads, enrolls or deletes fingerprints.
You can use this sensor with any CircuitPython microcontroller board or with a computer that has GPIO and Python thanks to Adafruit_Blinka, our CircuitPython-for-Python compatibility library.
If your sensor has different wires, The first wire from the left should be the black wire ground, then the two data pins, RX is the white wire, TX is the green wire then the red power wire. You'll have to cut, strip and solder thicker gauge wires to the current wires.
If your sensor has all the same-color wires, The first wire from the left is ground, then the two data pins, then power. You'll have to cut, strip and solder the wires.
RX is the same as the White wire
TX is the same as the Green wire
CircuitPython Microcontroller Wiring
First wire up the fingerprint sensor to your board exactly as shown on the previous pages for Arduino. Here's an example of wiring a Feather M4 to the sensor with UART:
- Board GND to sensor GND (black wire)
- Board TX to sensor RX (white wire)
- Board RX to sensor TX (green wire)
- Board 3.3v to sensor VCC (red wire)
Every CircuitPython board has a hardware UART. Check the product page or look for RX and TX written on the board. Remember that the RX from the sensor goes to the TX on the board! If you have problems try swapping them, it's a common mistake.
Python Computer Wiring
Since there's dozens of Linux computers/boards you can use we will show wiring for Raspberry Pi. For other platforms, please visit the guide for CircuitPython on Linux to see whether your platform is supported.
Here you have two options: An external USB-to-serial converter, or the built-in UART on the Pi's TX/RX pins. Here's an example of wiring up the USB-to-serial converter:
- Sensor VCC (red wire) to USB 5V or 3V (red wire on USB console cable)
- Sensor GND (black wire) to USB Ground (black wire)
- Sensor RX (white wire) to USB TX (green wire)
- Sensor TX (green wire) to USB RX (white wire)
Here's an example using the Pi's built-in UART:
- Pi GND to sensor GND (black wire)
- Pi TX to sensor RX (white wire)
- Pi RX to sensor TX (green wire)
- Pi 3.3v to sensor VCC (red wire)
If you want to use the built-in UART, you'll need to disable the serial console and enable the serial port hardware in raspi-config. See the UART/Serial section of the CircuitPython on Raspberry Pi guide for detailed instructions on how to do this.
CircuitPython Fingerprint Library Installation
To use the Fingerprint sensor you'll need to install the Adafruit CircuitPython Fingerprint library on your CircuitPython board.
First make sure you are running the latest version of Adafruit CircuitPython for your board.
Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle. Our introduction guide has a great page on how to install the library bundle for both express and non-express boards.
Copy the necessary file from the library bundle to the lib folder on your CIRCUITPY drive:
- adafruit_fingerprint.mpy
Before continuing make sure your board's lib folder has the adafruit_fingerprint.mpy file copied over.
Next connect to the board's serial REPL so you are at the CircuitPython >>> prompt.
Python Installation of Fingerprint Library
You'll need to install the Adafruit_Blinka library that provides the CircuitPython support in Python. This may also require enabling the hardware UART on your platform (see red note above) and verifying you are running Python 3. Since each platform is a little different, and Linux changes often, please visit the CircuitPython on Linux guide to get your computer ready!
Once that's done, from your command line run the following command:
sudo pip3 install adafruit-circuitpython-fingerprint
If your default Python is version 3 you may need to run 'pip' instead. Just make sure you aren't trying to use CircuitPython on Python 2.x, it isn't supported!
CircuitPython & Python Usage
To demonstrate the usage of the sensor, we'll use the example python script included with the library. This sensor is fairly complex so its hard to run it just from the REPL.
CircuitPython Microcontroller Usage
Once you've installed the library, run this code.py example on your CircuitPython board.
Linux/Computer/Raspberry Pi with Python
On the Raspberry Pi, comment out the uart = busio.UART(...) line, and uncomment the applicable import serial and uart = serial.Serial(...) lines, depending on whether you're using USB serial or hardware UART. Now you can run the program with the following command:
python3 fingerprint_simpletest.py
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
import time
import board
import busio
from digitalio import DigitalInOut, Direction
import adafruit_fingerprint
led = DigitalInOut(board.D13)
led.direction = Direction.OUTPUT
uart = busio.UART(board.TX, board.RX, baudrate=57600)
# If using with a computer such as Linux/RaspberryPi, Mac, Windows with USB/serial converter:
# import serial
# uart = serial.Serial("/dev/ttyUSB0", baudrate=57600, timeout=1)
# If using with Linux/Raspberry Pi and hardware UART:
# import serial
# uart = serial.Serial("/dev/ttyS0", baudrate=57600, timeout=1)
finger = adafruit_fingerprint.Adafruit_Fingerprint(uart)
##################################################
def get_fingerprint():
"""Get a finger print image, template it, and see if it matches!"""
print("Waiting for image...")
while finger.get_image() != adafruit_fingerprint.OK:
pass
print("Templating...")
if finger.image_2_tz(1) != adafruit_fingerprint.OK:
return False
print("Searching...")
if finger.finger_search() != adafruit_fingerprint.OK:
return False
return True
# pylint: disable=too-many-branches
def get_fingerprint_detail():
"""Get a finger print image, template it, and see if it matches!
This time, print out each error instead of just returning on failure"""
print("Getting image...", end="")
i = finger.get_image()
if i == adafruit_fingerprint.OK:
print("Image taken")
else:
if i == adafruit_fingerprint.NOFINGER:
print("No finger detected")
elif i == adafruit_fingerprint.IMAGEFAIL:
print("Imaging error")
else:
print("Other error")
return False
print("Templating...", end="")
i = finger.image_2_tz(1)
if i == adafruit_fingerprint.OK:
print("Templated")
else:
if i == adafruit_fingerprint.IMAGEMESS:
print("Image too messy")
elif i == adafruit_fingerprint.FEATUREFAIL:
print("Could not identify features")
elif i == adafruit_fingerprint.INVALIDIMAGE:
print("Image invalid")
else:
print("Other error")
return False
print("Searching...", end="")
i = finger.finger_fast_search()
# pylint: disable=no-else-return
# This block needs to be refactored when it can be tested.
if i == adafruit_fingerprint.OK:
print("Found fingerprint!")
return True
else:
if i == adafruit_fingerprint.NOTFOUND:
print("No match found")
else:
print("Other error")
return False
# pylint: disable=too-many-statements
def enroll_finger(location):
"""Take a 2 finger images and template it, then store in 'location'"""
for fingerimg in range(1, 3):
if fingerimg == 1:
print("Place finger on sensor...", end="")
else:
print("Place same finger again...", end="")
while True:
i = finger.get_image()
if i == adafruit_fingerprint.OK:
print("Image taken")
break
if i == adafruit_fingerprint.NOFINGER:
print(".", end="")
elif i == adafruit_fingerprint.IMAGEFAIL:
print("Imaging error")
return False
else:
print("Other error")
return False
print("Templating...", end="")
i = finger.image_2_tz(fingerimg)
if i == adafruit_fingerprint.OK:
print("Templated")
else:
if i == adafruit_fingerprint.IMAGEMESS:
print("Image too messy")
elif i == adafruit_fingerprint.FEATUREFAIL:
print("Could not identify features")
elif i == adafruit_fingerprint.INVALIDIMAGE:
print("Image invalid")
else:
print("Other error")
return False
if fingerimg == 1:
print("Remove finger")
time.sleep(1)
while i != adafruit_fingerprint.NOFINGER:
i = finger.get_image()
print("Creating model...", end="")
i = finger.create_model()
if i == adafruit_fingerprint.OK:
print("Created")
else:
if i == adafruit_fingerprint.ENROLLMISMATCH:
print("Prints did not match")
else:
print("Other error")
return False
print("Storing model #%d..." % location, end="")
i = finger.store_model(location)
if i == adafruit_fingerprint.OK:
print("Stored")
else:
if i == adafruit_fingerprint.BADLOCATION:
print("Bad storage location")
elif i == adafruit_fingerprint.FLASHERR:
print("Flash storage error")
else:
print("Other error")
return False
return True
##################################################
def get_num():
"""Use input() to get a valid number from 1 to 127. Retry till success!"""
i = 0
while (i > 127) or (i < 1):
try:
i = int(input("Enter ID # from 1-127: "))
except ValueError:
pass
return i
while True:
print("----------------")
if finger.read_templates() != adafruit_fingerprint.OK:
raise RuntimeError("Failed to read templates")
print("Fingerprint templates:", finger.templates)
print("e) enroll print")
print("f) find print")
print("d) delete print")
print("----------------")
c = input("> ")
if c == "e":
enroll_finger(get_num())
if c == "f":
if get_fingerprint():
print("Detected #", finger.finger_id, "with confidence", finger.confidence)
else:
print("Finger not found")
if c == "d":
if finger.delete_model(get_num()) == adafruit_fingerprint.OK:
print("Deleted!")
else:
print("Failed to delete")
It's fairly long but it will help you set-up and test your sensor!
When you first start up, you should get something like this:
If you get an error like RuntimeError: Failed to read data from sensor it means something went wrong - check your wiring and baud rate!
This menu system is fairly simple, you have three things you can do
- Enroll print - you will use your finger to take images and 'store' the model in the sensor
- Find print - determine whether a fingerprint is known and stored
- Delete print - clear out a model
Enrolling Prints
Enrolling a finger print is easy. Type e to start the process. You'll need to select a location. The sensor can store up to 127 print locations. Pick a valid number, then place your finger twice to enroll.
Note that after success, the Fingerprint templates: [...] printout will include the new template id.
If an error occurs, the sensor will give you an error, such as if the two prints don't match, or if it failed to store or generate a model:
Finding Prints
Once you've enrolled fingerprints you can then test them. Run the find command, and try various fingers! Once the fingerprint id identified it will tell you the location number, in this case #5
Deleting Fingerprints
If you made a mistake you can remove fingerprint models from the database. For example, here's how to delete #5. Note the Fingerprint templates: [...] printout changes!
Page last edited January 22, 2025
Text editor powered by tinymce.
