ZFM20 Class Reference

C++ API for the ZFM-20 fingerprint sensor module. More...

Detailed Description

• ID: zfm20
• Name: ZFM-20 Fingerprint Sensor Module
• Other Names: Grove Fingerprint Sensor
• Category: touch
• Manufacturer: seeed
• Connection: uart

This class was tested on the Grove Fingerprint Sensor Module. It can store up to 163 fingerprints.

It is connected via a UART at 57600 baud.

This example demonstrates how to register and store a new fingerprint

  // Instantiate a ZFM20 Fingerprint reader on UART 0

  upm::ZFM20* fp = new upm::ZFM20(0);

  // make sure port is initialized properly.  57600 baud is the default.
  if (!fp->setupTty(B57600))
    {
      cerr << "Failed to setup tty port parameters" << endl;
      return 1;
    }

  // This example demonstrates registering a fingerprint on the zfm20
  // module.  The procedure is as follows:
  //
  // 1. get an image, store it in characteristics buffer 1
  // 2. get another image, store it in characteristics buffer 2
  // 3. store the image, assuming the two fingerprints match

  // first, we need to register our address and password
  
  fp->setPassword(ZFM20_DEFAULT_PASSWORD);
  fp->setAddress(ZFM20_DEFAULT_ADDRESS);
  
  // now verify the password.  If this fails, any other commands
  // will be ignored, so we just bail.
  if (fp->verifyPassword())
    {
      cout << "Password verified." << endl;
    }
  else
    {
      cerr << "Password verification failed." << endl;
      return 1;
    }
  
  cout << endl;

  uint8_t rv;
  // get the first image

  cout << "Place a finger on the sensor." << endl;
  while (fp->generateImage() != ZFM20::ERR_OK)
    ;

  // in theory, we have an image
  cout << "Image captured, converting..." << endl;

  if ((rv = fp->image2Tz(1)) != ZFM20::ERR_OK)
    {
      cerr << "Image conversion failed with error code " << int(rv) <<endl;
      return 1;
    }

  cout << "Image conversion succeeded, remove finger." << endl;
  sleep(1);

  while (fp->generateImage() != ZFM20::ERR_NO_FINGER)
    ;
  
  cout << endl;
  cout << "Now place the same finger on the sensor." << endl;

  while (fp->generateImage() != ZFM20::ERR_OK)
    ;

  cout << "Image captured, converting..." << endl;

  // save this one in slot 2
  if ((rv = fp->image2Tz(2)) != ZFM20::ERR_OK)
    {
      cerr << "Image conversion failed with error code " << int(rv) <<endl;
      return 1;
    }

  cout << "Image conversion succeeded, remove finger." << endl;
  cout << endl;

  cout << "Storing fingerprint at id 1" << endl;
  
  // create the model
  if ((rv = fp->createModel()) != ZFM20::ERR_OK)
    {
      if (rv == ZFM20::ERR_FP_ENROLLMISMATCH)
        cerr << "Fingerprints did not match." << endl;
      else
        cerr << "createModel failed with error code " << int(rv) <<endl;
 
      return 1;
    }
  
  // now store it, we hard code the id (second arg) to 1 here
  if ((rv = fp->storeModel(1, 1)) != ZFM20::ERR_OK)
    {
      cerr << "storeModel failed with error code " << int(rv) <<endl;
      return 1;
    }

  cout << endl;
  cout << "Fingerprint stored at id 1." << endl;
  

This example demonstrates reading a fingerprint and locating it in the DB

  // Instantiate a ZFM20 Fingerprint reader on UART 0

  upm::ZFM20* fp = new upm::ZFM20(0);

  // make sure port is initialized properly.  57600 baud is the default.
  if (!fp->setupTty(B57600))
    {
      cerr << "Failed to setup tty port parameters" << endl;
      return 1;
    }

  // first, set the default password and address
  fp->setPassword(ZFM20_DEFAULT_PASSWORD);
  fp->setAddress(ZFM20_DEFAULT_ADDRESS);
      
  // now verify the password.  If this fails, any other commands
  // will be ignored, so we just bail.
  if (fp->verifyPassword())
    {
      cout << "Password verified." << endl;
    }
  else
    {
      cerr << "Password verification failed." << endl;
      return 1;
    }

  // how many valid stored templates (fingerprints) do we have?
  cout << "Total stored templates: " << fp->getNumTemplates() << endl;
  cout << endl;

  // now spin waiting for a fingerprint to successfully image
  cout << "Waiting for finger print..." << endl;

  while (fp->generateImage() == ZFM20::ERR_NO_FINGER)
    ;

  // in theory, we have an image
  cout << "Image captured, converting..." << endl;

  uint8_t rv;
  if ((rv = fp->image2Tz(1)) != ZFM20::ERR_OK)
    {
      cerr << "Image conversion failed with error code " << int(rv) <<endl;
      return 1;
    }

  cout << "Image conversion succeeded." << endl;
  cout << "Searching database..." << endl;

  uint16_t id = 0;
  uint16_t score = 0;

  // we search for a print matching slot 1, where we shored our last
  // converted fingerprint
  if ((rv = fp->search(1, &id, &score)) != ZFM20::ERR_OK)
    {
      if (rv == ZFM20::ERR_FP_NOTFOUND)
        {
          cout << "Finger Print not found" << endl;
          return 0;
        }
      else
        {
          cerr << "Search failed with error code " << int(rv) <<endl;
          return 1;
        }
    }

  cout << "Fingerprint found!" << endl;
  cout << "ID: " << int(id) << ", Score: " << int(score) << endl;

Public Types
enum	ZFM20_COMMAND_T {   CMD_GEN_IMAGE = 0x01, CMD_IMG2TZ = 0x02, CMD_MATCH = 0x03, CMD_SEARCH = 0x04,   CMD_REGMODEL = 0x05, CMD_STORE = 0x06, CMD_LOAD_TMPL = 0x07, CMD_UPLOAD_TMPL = 0x08,   CMD_DOWNLOAD_TMPL = 0x09, CMD_UPLOAD_IMAGE = 0x0a, CMD_DOWNLOAD_IMAGE = 0x0b, CMD_DELETE_TMPL = 0x0c,   CMD_EMPTYDB = 0x0d, CMD_SET_SYSPARAMS = 0x0e, CMD_GET_SYSPARAMS = 0x0f, CMD_SET_PASSWORD = 0x12,   CMD_VERIFY_PASSWORD = 0x13, CMD_GET_RANDOM_NUMBER = 0x14, CMD_SET_ADDRESS = 0x15, CMD_GET_TMPL_COUNT = 0x1d,   CMD_GET_INDEX_TABLE = 0x1f }
enum	ZFM20_ERRORS_T {   ERR_OK = 0x00, ERR_PACKET_RX_ERROR = 0x01, ERR_NO_FINGER = 0x02, ERR_FP_IMAGE_FAILED = 0x03,   ERR_FP_TOO_MESSY = 0x06, ERR_FP_IMAGE_FEW_FEATURES = 0x07, ERR_FP_NOMATCH = 0x08, ERR_FP_NOTFOUND = 0x09,   ERR_FP_ENROLLMISMATCH = 0x0a, ERR_BAD_LOCATION = 0x0b, ERR_DB_ERROR = 0x0c, ERR_UPLOAD_FEAT_FAILED = 0x0d,   ERR_NO_MORE_PACKETS = 0x0e, ERR_UPLOAD_IMG_FAILED = 0x0f, ERR_RM_TMPL_FAILED = 0x10, ERR_EMPTY_DB_FAILED = 0x11,   ERR_INVALID_PWD = 0x13, ERR_INVALID_IMAGE = 0x15, ERR_RW_FLASH_ERROR = 0x18, ERR_INVALID_REG = 0x1a,   ERR_INVALID_ADDR = 0x20, ERR_NEEDS_PWD = 0x21, ERR_INTERNAL_ERR = 0xff }
enum	ZFM20_PKTCODES_T { PKT_COMMAND = 0x01, PKT_DATA = 0x02, PKT_ACK = 0x07, PKT_END_DATA = 0x08 }

Public Member Functions
	ZFM20 (int uart)
	~ZFM20 ()
bool	dataAvailable (unsigned int millis)
int	readData (char *buffer, size_t len)
int	writeData (char *buffer, size_t len)
bool	setupTty (speed_t baud=B57600)
int	writeCmdPacket (unsigned char *pkt, int len)
bool	verifyPacket (unsigned char *pkt)
uint32_t	getMillis ()
void	initClock ()
void	setAddress (uint32_t addr)
void	setPassword (uint32_t pw)
bool	getResponse (unsigned char *pkt, int len)
bool	verifyPassword ()
int	getNumTemplates ()
bool	setNewPassword (uint32_t pwd)
bool	setNewAddress (uint32_t addr)
uint8_t	generateImage ()
uint8_t	image2Tz (int slot)
uint8_t	createModel ()
uint8_t	storeModel (int slot, uint16_t id)
uint8_t	deleteModel (uint16_t id)
uint8_t	deleteDB ()
uint8_t	search (int slot, uint16_t *id, uint16_t *score)
uint8_t	match (uint16_t *score)

Protected Member Functions
int	ttyFd ()
int	setTtyFd (int fd)

Constructor & Destructor Documentation

ZFM20

(

int

uart

)

ZFM20 module constructor

Parameters

uart	default uart to use (0 or 1)

~ZFM20

(

)

ZFM20 module Destructor

Member Function Documentation

bool dataAvailable

(

unsigned int

millis

)

check to see if there is data available for reading

Parameters

millis

number of milliseconds to wait, 0 means no wait.

Returns

true if there is data available to be read

int readData	(	char *	buffer,
		size_t	len
	)

read any available data into a user-supplied buffer. Note, the call will block until data is available to be read. Use dataAvailable() to determine whether there is data available beforehand, to avoid blocking.

Parameters

buffer	the buffer to hold the data read
len	the length of the buffer

Returns

the number of bytes read

int writeData	(	char *	buffer,
		size_t	len
	)

write the data in buffer to the device

Parameters

buffer	the buffer to hold the data read
len	the length of the buffer

Returns

the number of bytes written

bool setupTty

(

speed_t

baud = B57600

)

setup the proper tty i/o modes and the baudrate. The default baud rate is 57600 (B57600) for this device.

Parameters

baud	the desired baud rate.

Returns

true if successful

int writeCmdPacket	(	unsigned char *	pkt,
		int	len
	)

compose and write a command packet

Parameters

pkt	the packet
len	length of packet

Returns

the number of bytes written

bool verifyPacket

(

unsigned char *

pkt

)

verify the packet header and indicate it's validity

Parameters

pkt	the packet to check

Returns

true if valid checksum, false otherwise

uint32_t getMillis

(

)

Return the number of milliseconds elapsed since initClock() was last called.

Returns

elapsed milliseconds

void initClock

(

)

Reset the Clock

void setAddress ( uint32_t  addr )

inline

set the address that should be used to access the module

Parameters

addr	the address to use

void setPassword ( uint32_t  pw )

inline

set the password that should be used to access the module

Parameters

pw	password to use

bool getResponse	(	unsigned char *	pkt,
		int	len
	)

get the returned data from a request

Parameters

pkt	the buffer to store the returned data into
len	the expected response length. pkt should be at least this big.

Returns

true if successful

bool verifyPassword

(

)

verify and authenticate to the module. The password used is the one last set by setPassword().

Returns

true if successful

int getNumTemplates

(

)

query the module for the number of stored templates (fingerprints).

Returns

the number of currently stored templates

bool setNewPassword

(

uint32_t

pwd

)

set a new password for the module. This passowrd will be stored on the module, and will be required in order to access the module in the future.

Parameters

pwd	the new password to set on the module

Returns

true if successful

bool setNewAddress

(

uint32_t

addr

)

set a new address for the module. This address will be stored on the module, and will be required in order to access the module in the future.

Parameters

addr	the new address to set on the module

Returns

true if successful

uint8_t generateImage

(

)

generate a new fingerprint image (scan a fingerprint)

Returns

one of the ZFM20_ERRORS_T values

uint8_t image2Tz

(

int

slot

)

convert the image in the image buffer (generated by generateImage()) and store it in one of the two characteristics buffers, 1 or 2

Parameters

slot	the characteristics buffer to use. Must be 1 or 2.

Returns

one of the ZFM20_ERRORS_T values

uint8_t createModel

(

)

based on the two characteristics bufferes (1 & 2), create a fingerprint model. Once a model has been successfully created, it can be stored in the module with storeModel().

Returns

one of the ZFM20_ERRORS_T values

uint8_t storeModel	(	int	slot,
		uint16_t	id
	)

once a fingerprint model has been created, this method can be used to store it (via one of the characteristics buffers) in a given location.

Parameters

slot	the characteristics buffer to store (1 or 2)
id	the location in which to store the model

Returns

one of the ZFM20_ERRORS_T values

uint8_t deleteModel

(

uint16_t

id

)

delete a stored model.

Parameters

id	the location containing the model to delete

Returns

one of the ZFM20_ERRORS_T values

uint8_t deleteDB

(

)

delete the model database

Returns

one of the ZFM20_ERRORS_T values

uint8_t search	(	int	slot,
		uint16_t *	id,
		uint16_t *	score
	)

search the fingerprint DB and return the id and score, if found

Parameters

slot	the slot containing a converted image to search for
id	the returned id if found, 0 otherwise
score	the returned score if found, 0 otherwise

Returns

one of the ZFM20_ERRORS_T values

uint8_t match

(

uint16_t *

score

)

compares the features in characteristic buffers 1 and 2 and returns a score if they match

Parameters

score

the returned score

Returns

one of the ZFM20_ERRORS_T values

---

The documentation for this class was generated from the following files:

• /var/lib/jenkins/workspace/upm-doc-stable/src/zfm20/zfm20.h
• /var/lib/jenkins/workspace/upm-doc-stable/src/zfm20/zfm20.cxx