ZFM20 Class Reference

API for the ZFM-20 Fingerprint Sensor Module. More...

Detailed Description

• ID: zfm20
• Name: ZFM-20 Fingerprint Sensor
• 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 57,600 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, int len)
int	writeData (char *buffer, int len)
bool	setupTty (speed_t baud=B57600)
int	writeCmdPacket (uint8_t *pkt, int len)
bool	verifyPacket (uint8_t *pkt, int len)
uint32_t	getMillis ()
void	initClock ()
void	setAddress (uint32_t addr)
void	setPassword (uint32_t pw)
bool	getResponse (uint8_t *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 ()

Constructor & Destructor Documentation

ZFM20

(

int

uart

)

ZFM20 constructor

Parameters

uart	Default UART to use (0 or 1)

~ZFM20

(

)

ZFM20 destructor

Member Function Documentation

bool dataAvailable

(

unsigned int

millis

)

Checks to see if there is data available for reading

Parameters

millis

Number of milliseconds to wait; 0 means no waiting

Returns

true if there is data available for reading

int readData	(	char *	buffer,
		int	len
	)

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

Parameters

buffer	Buffer to hold the data read
len	Length of the buffer

Returns

Number of bytes read

int writeData	(	char *	buffer,
		int	len
	)

Writes the data in the buffer to the device

Parameters

buffer	Buffer to hold the data read
len	Length of the buffer

Returns

Number of bytes written

bool setupTty

(

speed_t

baud = B57600

)

Sets up proper tty I/O modes and the baud rate. For this device, the default baud rate is 57,600 (B57600).

Parameters

baud	Desired baud rate.

Returns

True if successful

int writeCmdPacket	(	uint8_t *	pkt,
		int	len
	)

Composes and writes a command packet

Parameters

pkt	Packet
len	Length of packet

Returns

Number of bytes written

bool verifyPacket	(	uint8_t *	pkt,
		int	len
	)

Verifies the packet header and indicates its validity

Parameters

pkt	Packet to check
len	Length of packet

Returns

True if the packet is valid, false otherwise

uint32_t getMillis

(

)

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

Returns

Elapsed milliseconds

void initClock

(

)

Resets the clock

void setAddress ( uint32_t  addr )

inline

Sets the address that should be used to access the module

Parameters

addr	Address to use

void setPassword ( uint32_t  pw )

inline

Sets the password that should be used to access the module

Parameters

pw	Password to use

bool getResponse	(	uint8_t *	pkt,
		int	len
	)

Gets the returned data from a request

Parameters

pkt	Buffer to store the returned data
len	Expected response length; pkt should be at least this large

Returns

True if successful

bool verifyPassword

(

)

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

Returns

True if successful

int getNumTemplates

(

)

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

Returns

Number of currently stored templates

bool setNewPassword

(

uint32_t

pwd

)

Sets a new password for the module. This passowrd is stored in the module, and is required to access the module in the future.

Parameters

pwd	New password to set on the module

Returns

True if successful

bool setNewAddress

(

uint32_t

addr

)

Sets a new address for the module. This address is stored in the module, and is required to access the module in the future.

Parameters

addr	New address to set on the module

Returns

True if successful

uint8_t generateImage

(

)

Generates a new fingerprint image (scans a fingerprint)

Returns

One of the ZFM20_ERRORS_T values

uint8_t image2Tz

(

int

slot

)

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

Parameters

slot	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 buffers (1 & 2), creates a fingerprint model. Once a model is 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 is created, this method can be used to store it (via one of the characteristics buffers) in a given location.

Parameters

slot	Characteristics buffer to store the model, 1 or 2
id	Location to store the model

Returns

One of the ZFM20_ERRORS_T values

uint8_t deleteModel

(

uint16_t

id

)

Deletes a stored model

Parameters

id	Location containing the model to delete

Returns

One of the ZFM20_ERRORS_T values

uint8_t deleteDB

(

)

Deletes the model database (DB)

Returns

One of the ZFM20_ERRORS_T values

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

Searches the fingerprint DB and returns an ID and score, if found

Parameters

slot	Slot containing a converted image to search for
id	ID if found, 0 otherwise
score	Score if found, 0 otherwise

Returns

One of the ZFM20_ERRORS_T values

uint8_t match

(

uint16_t *

score

)

Compares the features in characteristics buffers 1 and 2 and returns a score if they match

Parameters

score

Score

Returns

One of the ZFM20_ERRORS_T values

---

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

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