README.md

micropython-fingerprint

MicroPython library for reading ZhianTec finger print sensors.

This MicroPython library is a slightly modified version of the pyfingerprint for the Raspberry Pi and has the same German free software license.

As with the original library it should work with ZFM-20, ZFM-60, etc sensors. I have been testing with the R503 sensor.

A small test program to verify that the sensor is communicating. Depending on what development board is in use, the UART instance may have to be differently configured. Note that the baud rate MUST be a multiple of 9600.

from pyfingerprint import PyFingerprint
from machine import UART

sensorSerial = UART(1)
# ESP32 (pins 12, 13)
sensorSerial.init(57600, bits=8, parity=None, stop=1, rx=13, tx=12)
# pyboard v1.1 (pins X9, X10)
# sensorSerial.init(57600, bits=8, parity=None, stop=1)

f = PyFingerprint(sensorSerial)
f.verifyPassword() # should return True

Further example programs which should be easily adapted can be found with the original pyfingerprint library.

Trouble Shooting

Download characteristics packet corruption

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pyfingerprint.py", line 1461, in downloadCharacteristics
  File "pyfingerprint.py", line 372, in __readPacket
Exception: The received packet is corrupted (the checksum is wrong)!

Solution - reduce baud rate

Documentation

• pyfingerprint
  • FINGERPRINT_SETSYSTEMPARAMETER_BAUDRATE
  • FINGERPRINT_SETSYSTEMPARAMETER_SECURITY_LEVEL
  • FINGERPRINT_SETSYSTEMPARAMETER_PACKAGE_SIZE
  • FINGERPRINT_LED_BREATHING
  • FINGERPRINT_LED_FLASHING
  • FINGERPRINT_LED_CONTINUOUS
  • FINGERPRINT_LED_OFF
  • FINGERPRINT_LED_GRADUAL_ON
  • FINGERPRINT_LED_GRADUAL_OFF
  • FINGERPRINT_LED_RED
  • FINGERPRINT_LED_BLUE
  • FINGERPRINT_LED_PURPLE
  • FINGERPRINT_CHARBUFFER1
  • FINGERPRINT_CHARBUFFER2
  • PyFingerprint
    • __init__
    • __del__
    • verifyPassword
    • setPassword
    • setAddress
    • setSystemParameter
    • setBaudRate
    • setSecurityLevel
    • setMaxPacketSize
    • getSystemParameters
    • getStorageCapacity
    • getSecurityLevel
    • getMaxPacketSize
    • getBaudRate
    • getTemplateIndex
    • getTemplateCount
    • readImage
    • convertImage
    • createTemplate
    • storeTemplate
    • searchTemplate
    • loadTemplate
    • deleteTemplate
    • clearDatabase
    • compareCharacteristics
    • uploadCharacteristics
    • generateRandomNumber
    • downloadCharacteristics
    • softReset
    • checkSensor
    • handshake
    • cancelInstruction
    • ledOn
    • ledOff

pyfingerprint

PyFingerprint Copyright (C) 2015 Bastian Raschke bastian.raschke@posteo.de All rights reserved.

FINGERPRINT_SETSYSTEMPARAMETER_BAUDRATE

Set the baud rate.

FINGERPRINT_SETSYSTEMPARAMETER_SECURITY_LEVEL

Set the security level.

FINGERPRINT_SETSYSTEMPARAMETER_PACKAGE_SIZE

Set the package size.

FINGERPRINT_LED_BREATHING

Breathing LED.

FINGERPRINT_LED_FLASHING

Flashing LED.

FINGERPRINT_LED_CONTINUOUS

Continuous LED.

FINGERPRINT_LED_OFF

LED off.

FINGERPRINT_LED_GRADUAL_ON

Turn LED on gradually.

FINGERPRINT_LED_GRADUAL_OFF

Turn LED off gradually.

FINGERPRINT_LED_RED

Red LED.

FINGERPRINT_LED_BLUE

Blue LED.

FINGERPRINT_LED_PURPLE

Purple LED.

FINGERPRINT_CHARBUFFER1

Char buffer 1

FINGERPRINT_CHARBUFFER2

Char buffer 2

PyFingerprint

class PyFingerprint(object)

Manages ZhianTec fingerprint sensors.

__init__

 | __init__(uart, address=0xFFFFFFFF, password=0x00000000)

Constructor.

Arguments:

• uart - Instance of machine.UART. The baud rate set in the UART instance MUST be a multiple of 9600. Passing in a UART instance enables different flavors of MicroPython to be supported.
• address int - The sensor address
• password int - The sensor password

Raises:

• ValueError - if address or password are invalid

__del__

 | __del__()

Destructor.

verifyPassword

 | verifyPassword()

Verifies password of the sensor.

Returns:

True if password is correct or False otherwise.

Raises:

• Exception - if an error occured

setPassword

 | setPassword(newPassword)

Sets the password of the sensor.

Arguments:

• newPassword int - The new password to use.

Returns:

True if password was set correctly or False otherwise.

Raises:

• Exception - if an error occured

setAddress

 | setAddress(newAddress)

Sets the sensor address.

Arguments:

• newAddress int - The new address to use.

Returns:

True if address was set correctly or False otherwise.

Raises:

• Exception - if any error occurs

setSystemParameter

 | setSystemParameter(parameterNumber, parameterValue)

Set a system parameter of the sensor.

Arguments:

• parameterNumber int - The parameter number. Use one of FINGERPRINT_SETSYSTEMPARAMETER_* constants.
• parameterValue int - The value

Returns:

True if successful or False otherwise.

Raises:

• ValueError - if any passed parameter is invalid
• Exception - if any error occurs

setBaudRate

 | setBaudRate(baudRate)

Sets the baud rate.

Arguments:

• baudRate int - The baud rate

Raises:

• ValueError - if passed baud rate is no multiple of 9600
• Exception - if any error occurs

setSecurityLevel

 | setSecurityLevel(securityLevel)

Sets the security level of the sensor.

Arguments:

• securityLevel int - Value between 1 and 5 where 1 is lowest and 5 highest.

Raises:

• Exception - if any error occurs

setMaxPacketSize

 | setMaxPacketSize(packetSize)

Sets the maximum packet size of sensor.

Arguments:

• packetSize int - 32, 64, 128 and 256 are supported.

Raises:

• ValueError - if passed packet size is invalid
• Exception - if any error occurs

getSystemParameters

 | getSystemParameters()

Gets all available system information of the sensor.

Returns:

A tuple that contains the following information:

• 0 - integer(2 bytes) The status register.
• 1 - integer(2 bytes) The system id.
• 2 - integer(2 bytes) The storage capacity.
• 3 - integer(2 bytes) The security level.
• 4 - integer(4 bytes) The sensor address.
• 5 - integer(2 bytes) The packet length.
• 6 - integer(2 bytes) The baud rate.

Raises:

• Exception - if any error occurs

getStorageCapacity

 | getStorageCapacity()

Gets the sensor storage capacity.

Returns:

The storage capacity (int).

Raises:

• Exception - if any error occurs

getSecurityLevel

 | getSecurityLevel()

Gets the security level of the sensor.

Returns:

The security level (int).

Raises:

• Exception - if any error occurs

getMaxPacketSize

 | getMaxPacketSize()

Gets the maximum allowed size of a single packet.

Returns:

Return the max size (int).

Raises:

• ValueError - if packet size is invalid
• Exception - if any error occurs

getBaudRate

 | getBaudRate()

Gets the baud rate.

Returns:

The baud rate (int).

Raises:

• Exception - if any error occurs

getTemplateIndex

 | getTemplateIndex(page)

Gets a list of the template positions with usage indicator.

Arguments:

• page int - The page (value between 0 and 3).

Returns:

The list.

Raises:

• ValueError - if passed page is invalid
• Exception - if any error occurs

getTemplateCount

 | getTemplateCount()

Gets the number of stored templates.

Returns:

The template count (int).

Raises:

• Exception - if any error occurs

readImage

 | readImage()

Reads the image of a finger and stores it in image buffer.

Returns:

True if image was read successfully or False otherwise.

Raises:

• Exception - if any error occurs

convertImage

 | convertImage(charBufferNumber=FINGERPRINT_CHARBUFFER1)

Converts the image in image buffer to characteristics and stores it in specified char buffer.

Arguments:

• charBufferNumber int - The char buffer. Use FINGERPRINT_CHARBUFFER1 or FINGERPRINT_CHARBUFFER2.

Returns:

True if successful or False otherwise.

Raises:

• ValueError - if passed char buffer is invalid
• Exception - if any error occurs

createTemplate

 | createTemplate()

Combines the characteristics which are stored in char buffer 1 and char buffer 2 into one template. The created template will be stored again in char buffer 1 and char buffer 2 as the same.

Returns:

True if successful or False otherwise.

Raises:

• Exception - if any error occurs

storeTemplate

 | storeTemplate(positionNumber=-1, charBufferNumber=FINGERPRINT_CHARBUFFER1)

Stores a template from the specified char buffer at the given position.

Arguments:

• positionNumber int - The position
• charBufferNumber int - The char buffer. Use FINGERPRINT_CHARBUFFER1 or FINGERPRINT_CHARBUFFER2.

Returns:

The position number (int) of the stored template.

Raises:

• ValueError - if passed position or char buffer is invalid
• Exception - if any error occurs

searchTemplate

 | searchTemplate(charBufferNumber=FINGERPRINT_CHARBUFFER1, positionStart=0, count=-1)

Searches inside the database for the characteristics in char buffer.

Arguments:

• charBufferNumber int - The char buffer. Use FINGERPRINT_CHARBUFFER1 or FINGERPRINT_CHARBUFFER2.
• positionStart int - The position to start the search
• count int - The number of templates

Returns:

A tuple that contain the following information:

• 0 - integer(2 bytes) The position number of found template.
• 1 - integer(2 bytes) The accuracy score of found template.

Raises:

• Exception - if any error occurs

loadTemplate

 | loadTemplate(positionNumber, charBufferNumber=FINGERPRINT_CHARBUFFER1)

Loads an existing template specified by position number to specified char buffer.

Arguments:

• positionNumber int - The position
• charBufferNumber int - The char buffer. Use FINGERPRINT_CHARBUFFER1 or FINGERPRINT_CHARBUFFER2.

Returns:

True if successful or False otherwise.

Raises:

• ValueError - if passed position or char buffer is invalid
• Exception - if any error occurs

deleteTemplate

 | deleteTemplate(positionNumber, count=1)

Deletes templates from fingerprint database. Per default one.

Arguments:

• positionNumber int - The position
• count int - The number of templates to be deleted.

Returns:

True if successful or False otherwise.

Raises:

• ValueError - if passed position or count is invalid
• Exception - if any error occurs

clearDatabase

 | clearDatabase()

Deletes all templates from the fingeprint database.

Returns:

True if successful or False otherwise.

Raises:

• Exception - if any error occurs

compareCharacteristics

 | compareCharacteristics()

Compare the finger characteristics of char buffer 1 with char buffer 2 and returns the accuracy score.

Returns:

The accuracy score (int). 0 means fingers are not the same.

Raises:

• Exception - if any error occurs

uploadCharacteristics

 | uploadCharacteristics(charBufferNumber=FINGERPRINT_CHARBUFFER1, characteristicsData=[0])

Uploads finger characteristics to specified char buffer.

Author: David Gilson davgilson@live.fr

Arguments:

• charBufferNumber int - The char buffer. Use FINGERPRINT_CHARBUFFER1 or FINGERPRINT_CHARBUFFER2.
• characteristicsData list - The characteristics

Returns:

True if everything is right.

Raises:

• ValueError - if passed char buffer or characteristics are invalid
• Exception - if any error occurs

generateRandomNumber

 | generateRandomNumber()

Generates a random 32-bit decimal number.

Author: Philipp Meisberger team@pm-codeworks.de

Returns:

The generated random number (int).

Raises:

• Exception - if any error occurs

downloadCharacteristics

 | downloadCharacteristics(charBufferNumber=FINGERPRINT_CHARBUFFER1)

Downloads the finger characteristics from the specified char buffer.

Arguments:

• charBufferNumber int - The char buffer. Use FINGERPRINT_CHARBUFFER1 or FINGERPRINT_CHARBUFFER2.
• characteristicsData list - The characteristics

Returns:

The characteristics (list).

Raises:

• ValueError - if passed char buffer is invalid
• Exception - if any error occurs

softReset

 | softReset()

Soft reset the sensor.

Author: Chris Borrill chris.borrill@gmail.com

checkSensor

 | checkSensor()

Check the sensor is in a working state.

Author: Chris Borrill chris.borrill@gmail.com

Returns:

True if the sensor is working correctly.

handshake

 | handshake()

Hand sake with the sensor.

Author: Chris Borrill chris.borrill@gmail.com

Returns:

True if the sensor is working normally.

cancelInstruction

 | cancelInstruction()

Cancel last intruction to the sensor.

Author: Chris Borrill chris.borrill@gmail.com

ledOn

 | ledOn(colour=FINGERPRINT_LED_RED, control=FINGERPRINT_LED_BREATHING, flashSpeed=0x7D, flashCount=0x00)

Turn on sensor LED.

Author: Chris Borrill chris.borrill@gmail.com

Arguments:

• colour - one of FINGERPRINT_LED_RED (default), FINGERPRINT_LED_BLUE, FINGERPRINT_LED_PURPLE
• control - one of FINGERPRINT_LED_BREATHING (default), FINGERPRINT_LED_BLUE, FINGERPRINT_LED_PURPLE FINGERPRINT_LED_CONTINUOUS, FINGERPRINT_LED_OFF, FINGERPRINT_LED_GRADUAL_ON, FINGERPRINT_LED_GRADUAL_OFF
• flashSpeed - 0 (fast) to 255 (slow) (default 125)
• flashCount - 0 (infinite) to 255 (default 0)

Raises:

• Exception - if an error occured

ledOff

 | ledOff()

Turn off sensor LED.

Author: Chris Borrill chris.borrill@gmail.com

Raises:

• Exception - if an error occured