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

Detailed Description

ID: zfm20
Name: Fingerprint Sensor Module
Other Names: Grove Fingerprint Sensor
Category: touch
Manufacturer: seeed
Link: http://wiki.seeed.cc/Grove-Fingerprint_Sensor/
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(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;
    upm_delay(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(0);
    // make sure port is initialized properly.  57600 baud is the default.
    if (!fp.setupTty(57600)) {
        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, int baud=57600)

	ZFM20 (std::string uart_raw, int baud=57600)

virtual	~ZFM20 ()

int	readData (char *buffer, int len)

int	writeData (char *buffer, int len)

bool	setupTty (uint32_t baud=57600)

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)

Constructor & Destructor Documentation

ZFM20	(	int	uart,
		int	baud = `57600`
	)

ZFM20 constructor

Parameters

uart	Target mraa UART index to use (0 or 1)
baud	Desired baud rate

Here is the call graph for this function:

ZFM20	(	std::string	uart_raw,
		int	baud = `57600`
	)

ZFM20 constructor

Parameters

uart	File path (/dev/ttyXXX to uart
baud	Desired baud rate

Here is the call graph for this function:

virtual ~ZFM20 ( )

inlinevirtual

ZFM20 destructor

Here is the call graph for this function:

Member Function Documentation

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

Here is the caller graph for this function:

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

Here is the caller graph for this function:

bool setupTty ( uint32_t baud = 57600 )

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

Parameters

baud	Desired baud rate.

Returns: True if successful

Here is the caller graph for this function:

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

Here is the call graph for this function:

Here is the caller graph for this function:

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

Here is the caller graph for this function:

uint32_t getMillis ( )

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

Returns: Elapsed milliseconds

Here is the caller graph for this function:

void initClock ( )

Resets the clock

Here is the caller graph for this function:

void setAddress ( uint32_t addr )

inline

Sets the address that should be used to access the module

Parameters

addr	Address to use

Here is the caller graph for this function:

void setPassword ( uint32_t pw )

inline

Sets the password that should be used to access the module

Parameters

pw	Password to use

Here is the call graph for this function:

Here is the caller graph for this function:

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

Here is the call graph for this function:

Here is the caller graph for this function:

bool verifyPassword ( )

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

Returns: True if successful

Here is the call graph for this function:

Here is the caller graph for this function:

int getNumTemplates ( )

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

Returns: Number of currently stored templates

Here is the call graph for this function:

Here is the caller graph for this function:

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

Here is the call graph for this function:

Here is the caller graph for this function:

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

Here is the call graph for this function:

Here is the caller graph for this function:

uint8_t generateImage ( )

Generates a new fingerprint image (scans a fingerprint)

Returns: One of the ZFM20_ERRORS_T values

Here is the call graph for this function:

Here is the caller graph for this function:

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

Here is the call graph for this function:

Here is the caller graph for this function:

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().