This is a driver for communicating with and controlling a GT-511C fingerprint scanner. More...

Data Structures
struct	GT511_Info_t
	Structure that holds the fingerprint sensor info data that is returned during "open". More...

Macros
#define	GT511_NUM_SLOTS
	Set the number of supported fingerprint slots. More...

Enumerations
enum	GT511_Error_t { GT511_ERR_NONE, GT511_ERR_TIMEOUT, GT511_ERR_INVALID_BAUDRATE, GT511_ERR_INVALID_POS, GT511_ERR_IS_NOT_USED, GT511_ERR_IS_ALREADY_USED, GT511_ERR_COMM_ERR, GT511_ERR_VERIFY_FAILED, GT511_ERR_IDENTIFY_FAILED, GT511_ERR_DB_IS_FULL, GT511_ERR_DB_IS_EMPTY, GT511_ERR_TURN_ERR, GT511_ERR_BAD_FINGER, GT511_ERR_ENROLL_FAILED, GT511_ERR_IS_NOT_SUPPORTED, GT511_ERR_DEV_ERR, GT511_ERR_CAPTURE_CANCELED, GT511_ERR_INVALID_PARAM, GT511_ERR_FINGER_IS_NOT_PRESSED, GT511_ERR_OTHER_ERROR }
	Possible error codes that can be returned by the GT-511C driver API functions. More...

enum	GT511_Mode_t { GT511_MODE_IDLE, GT511_MODE_IDENTIFY, GT511_MODE_VERIFY, GT511_MODE_CAPTURE, GT511_MODE_ENROLL }
	Identifies the different possible modes of the driver when the callback function GT511_UserCallback() is called. More...

enum	GT511_UserInfo_t { GT511_UI_PRESS, GT511_UI_RELEASE, GT511_UI_TIMEOUT, GT511_UI_ACCEPT, GT511_UI_REJECT, GT511_UI_ERROR }
	Identifies an event when the callback function GT511_UserCallback() is called. More...

Functions
const char *	GT511_ErrorString (GT511_Error_t err)
	Return string representation of error code. More...

GT511_Error_t	GT511_Open (GT511_Info_t *pInfo)
	Open the fingerprint reader for operation. More...

GT511_Error_t	GT511_Close (void)
	Close the fingerprint reader for operation. More...

GT511_Error_t	GT511_CmosLed (bool on)
	Control the LED backlight. More...

GT511_Error_t	GT511_IsPressFinger (bool *pIsPressed)
	Check to see if a finger is pressed. More...

GT511_Error_t	GT511_CaptureFinger (bool highQuality)
	Capture a finger print. More...

GT511_Error_t	GT511_Identify (uint32_t *pId)
	Identify a fingerprint. More...

GT511_Error_t	GT511_EnrollStart (uint32_t id)
	Start enrollment. More...

GT511_Error_t	GT511_Enroll1 (void)
	Enroll step 1. More...

GT511_Error_t	GT511_Enroll2 (void)
	Enroll step 2. More...

GT511_Error_t	GT511_Enroll3 (void)
	Enroll step 3. More...

GT511_Error_t	GT511_DeleteAll (void)
	Delete all enrolled IDs. More...

GT511_Error_t	GT511_DeleteID (uint32_t id)
	Delete specific enrolled ID. More...

GT511_Error_t	GT511_GetEnrollCount (uint32_t *pEnrolledCount)
	Get the count of enrolled IDs. More...

GT511_Error_t	GT511_CheckEnrolled (uint32_t id)
	Check if a specific ID is enrolled. More...

GT511_Error_t	GT511_Verify (uint32_t id)
	Verify fingerprint for specific ID. More...

GT511_Error_t	GT511_FindAvailable (uint32_t *pId)
	Find an unused ID index. More...

GT511_Error_t	GT511_RunIdentify (uint32_t *pId)
	Run the identification process. More...

GT511_Error_t	GT511_RunVerify (uint32_t id)
	Run the verification process. More...

GT511_Error_t	GT511_RunEnroll (uint32_t *pId)
	Run the enrollment process. More...

bool	GT511_SendMessage (uint8_t *pMessage, uint32_t length)
	Send message to sensor (implemented by application). More...

uint32_t	GT511_ReceiveMessage (uint8_t *pMessage, uint32_t length)
	Receive message from the sensor (implemented by application). More...

void	GT511_UserCallback (GT511_Mode_t mode, GT511_UserInfo_t ui)
	Notify the application/user of a driver event (implemented by application) More...

void	GT511_SetTimeout (GT511_Mode_t mode)
	Ask application to start a timeout (implemented by application) More...

bool	GT511_CheckTimeout (GT511_Mode_t mode)
	Check for timeout expiration (implemented by application). More...

Detailed Description

This is a driver for communicating with and controlling a GT-511C fingerprint scanner.

It is specifically for a GT-511C1R which is the version that holds only 20 fingerprints. However it should also work for the GT-511C3 although it has not been tested. These fingerprint sensors are relatively inexpensive and available from places like (Sparkfun)[http://www.sparkfun.com/].

This particular driver was been written for a Silicon Labs EFM32 Wonder Gecko. Link: http://www.silabs.com/products/mcu/lowpower/Pages/efm32wg-wonder-gecko.aspx However it was designed to be hardware and application indepedent so it should be usable on any modern microcontroller, especially any based on Cortex-M.

Features

direct functions to map to each GT-511C command
macro functions for performing enrollment and identification
abstracted hardware interface using application-provided read and write functions
callback functions to inform application of progress and status

Please refer to the GT-511C sensor data sheet to understand how the functions of this driver should be used.

Hardware Abstraction

To avoid the need to code to any particular kind of hardware, this driver uses application-provided functions to write and read messages to the GT-511C hardware. Normally this is a serial port of the host microcontroller. The application must implement the following functions:

These can be as simple as polling-loop functions to copy bytes to and from the serial port, or more sophisticated that utilize interrupts and buffered IO with timeouts.

The driver also needs a way to check for a timeout. So the applciation must also implement the following functions to support a timeout:

The application design can use these in any way needed. It can create different timeout periods based on the context, or just use one timeout for all cases, or not use any timeouts. The driver will call these functions to setup a timeout when it is about to do something that requires a wait (such as waiting for a person to touch the sensor). This allows the application to control how long the driver will wait for such events to occur.

Application Callback

The driver will call an application-provided callback function to supply status. The function is named GT511_UserCallback(). This will be called at various points during driver operation and can be used by the application to know at what points it is appropriate to prompt the user to do some action such as touch the sensor.

Typical API Usage

All of the functions are written using the same style and all have the same return type GT511_Error_t to indicate the success or error code for an operation. When any operation is successful the return code will be GT511_ERR_NONE. The remaining error codes map to codes returned from the GT-511C, or GT511_ERR_OTHER_ERROR for all other error conditions (such as a communication error). If the function needs to return a value, that is done through pointer function parameters.

Example

// example to open and init the fingerprint sensor
// Structure to hold returned sensor info
GT511_Info_t sensorInfo;
// call function to open the sensor
GT511_Error_t err = GT511_Open(&sensorInfo);
// check for errors
if (err != GT511_ERR_NONE)
{
    // open was not successful
    // so handle error
}
else
{
    // open was successful and sensor info is now contained
    // in sensorInfo structure
    ...
}

Macro Definition Documentation

#define GT511_NUM_SLOTS

Set the number of supported fingerprint slots.

This should match the capability of your sensor hardware.

Enumeration Type Documentation

enum GT511_Error_t

Possible error codes that can be returned by the GT-511C driver API functions.

Most of these map directly to errors produced by the hardware sensor. Refer to the Gt-511C data sheet for more details.

Enumerator
GT511_ERR_NONE	no error; success
GT511_ERR_TIMEOUT	obsolete; timeout during capture
GT511_ERR_INVALID_BAUDRATE	obsolete; invalid baud rate
GT511_ERR_INVALID_POS	specified ID is not between 0~19
GT511_ERR_IS_NOT_USED	specified ID is not in use
GT511_ERR_IS_ALREADY_USED	specified ID is already in use
GT511_ERR_COMM_ERR	communication error
GT511_ERR_VERIFY_FAILED	verification failed
GT511_ERR_IDENTIFY_FAILED	identification failed
GT511_ERR_DB_IS_FULL	database is full
GT511_ERR_DB_IS_EMPTY	database is empty
GT511_ERR_TURN_ERR	obsolete; bad enrollment order
GT511_ERR_BAD_FINGER	bad fingerprint
GT511_ERR_ENROLL_FAILED	enrollment failed
GT511_ERR_IS_NOT_SUPPORTED	unsupported command was used
GT511_ERR_DEV_ERR	hardware device error
GT511_ERR_CAPTURE_CANCELED	obsolete; capture is cancelled
GT511_ERR_INVALID_PARAM	invalid parameter
GT511_ERR_FINGER_IS_NOT_PRESSED	finger not pressed
GT511_ERR_OTHER_ERROR	non-hardware driver error

enum GT511_Mode_t

Identifies the different possible modes of the driver when the callback function GT511_UserCallback() is called.

Enumerator
GT511_MODE_IDLE	driver is idle
GT511_MODE_IDENTIFY	driver is performing identification process
GT511_MODE_VERIFY	driver is performing verification process
GT511_MODE_CAPTURE	driver is performing capture process
GT511_MODE_ENROLL	driver is performing enrollment process

enum GT511_UserInfo_t

Identifies an event when the callback function GT511_UserCallback() is called.

Enumerator
GT511_UI_PRESS	user should press the sensor
GT511_UI_RELEASE	user should release the sensor
GT511_UI_TIMEOUT	timeout occurred waiting for press or release
GT511_UI_ACCEPT	fingerprint was accepted (identify or enrollment)
GT511_UI_REJECT	fingerprint was rejected (identify or enrollment)
GT511_UI_ERROR	processing error occurred

Function Documentation

const char* GT511_ErrorString ( GT511_Error_t err )

Return string representation of error code.

Parameters

err	the error code to check

This can be used for debugging to print a string name of the error code.

Returns: A string representation of the error code. If the error code does not match any known value then "UNKNOWN" is returned.

GT511_Error_t GT511_Open ( GT511_Info_t * pInfo )

Open the fingerprint reader for operation.

Parameters

pInfo optional pointer for retrieving sensor info

The pInfo parameter is optional and can be NULL. If not NULL, then it will be populated with the information returned from the sensor.

Returns: GT511_ERR_NONE if no errors occurred.

GT511_Error_t GT511_Close ( void )

Close the fingerprint reader for operation.

Returns: GT511_ERR_NONE if no errors occurred.

GT511_Error_t GT511_CmosLed ( bool on )

Control the LED backlight.

Parameters

on	set to true to turn on the backlight, or false for off

Returns: GT511_ERR_NONE if no errors occurred.

GT511_Error_t GT511_IsPressFinger ( bool * pIsPressed )

Check to see if a finger is pressed.

Parameters

pIsPressed storage for returned value

The parameter pIsPressed points at a flag to contain the returned value. It will be set to true if a finger press is detected, or false if no finger press is detected.

Returns: GT511_ERR_NONE if no errors occurred.

GT511_Error_t GT511_CaptureFinger ( bool highQuality )

Capture a finger print.

Parameters

highQuality true to use a high quality capture

According to the sensor data sheet, a high quality capture should be used for enrollment while a normal capture used for identification.

Returns: GT511_ERR_NONE if no errors occurred.

GT511_Error_t GT511_Identify ( uint32_t * pId )

Identify a fingerprint.

Parameters

pId	pointer to the ID value of the identified fingerprint

If a captured fingerprint is successfully identified, then the index ID of the fingerprint will be stored at _*pId_. You must check the function return value to make sure that the returned ID value is valid.

Returns: GT511_ERR_NONE if no errors occurred.

GT511_Error_t GT511_EnrollStart ( uint32_t id )

Start enrollment.

Parameters

id	index ID to use for fingerprint enrollment

This will start the enrollment process, using the specified ID index to store the enrolled fingerprint. This will not work if there is already a fingerprint enrolled at that index. You can use GT511_CheckEnrolled() to make sure the index is available.

Note: Please see the sensor data sheet to understand the enrollment process. There are several steps.

Returns: GT511_ERR_NONE if no errors occurred.

GT511_Error_t GT511_Enroll1 ( void )

Enroll step 1.

Enroll a captured fingerprint, first step.

Note: Please see the sensor data sheet to understand the enrollment process. There are several steps.

Returns: GT511_ERR_NONE if no errors occurred.

GT511_Error_t GT511_Enroll2 ( void )

Enroll step 2.

Enroll a captured fingerprint, second step.

Note: Please see the sensor data sheet to understand the enrollment process. There are several steps.

Returns: GT511_ERR_NONE if no errors occurred.

GT511_Error_t GT511_Enroll3 ( void )

Enroll step 3.

Enroll a captured fingerprint, third and final step.

Note: Please see the sensor data sheet to understand the enrollment process. There are several steps.

Returns: GT511_ERR_NONE if no errors occurred.

GT511_Error_t GT511_DeleteAll ( void )

Delete all enrolled IDs.

Returns: GT511_ERR_NONE if no errors occurred.

GT511_Error_t GT511_DeleteID ( uint32_t id )

Delete specific enrolled ID.

Parameters

id	index of ID to delete

Returns: GT511_ERR_NONE if no errors occurred.

GT511_Error_t GT511_GetEnrollCount ( uint32_t * pEnrolledCount )

Get the count of enrolled IDs.

Parameters

pEnrolledCount pointer to storage for the enrolled count

This function will query the fingerprint reader for the total number of enrollments and return the count through the pEnrolledCount argument. The value is only meaningful if the function return code is GT511_ERR_NONE.

Returns: GT511_ERR_NONE if no errors occurred.

GT511_Error_t GT511_CheckEnrolled ( uint32_t id )

Check if a specific ID is enrolled.

Parameters

id	index of ID to check for enrollment

This function will query the fingerprint reader to find out if the the specific ID is enrolled.

Returns: GT511_ERR_NONE if the specified index IS enrolled. GT511_ERR_IS_NOT_USED if the specified index IS NOT enrolled. Any other return value indicates an error.

GT511_Error_t GT511_Verify ( uint32_t id )

Verify fingerprint for specific ID.

Parameters

id	index of ID to verify

This function will check a fingerprint match of a specific ID.

Returns: GT511_ERR_NONE if the specified index has a fingerprint match. GT511_ERR_VERIFY_FAILED if the specified index does not match the fingerprint. Any other return value indicates an error.

GT511_Error_t GT511_FindAvailable ( uint32_t * pId )

Find an unused ID index.

Parameters

pId	pointer to available ID index

Will check each ID index (slot) in sequence until an unused one is found. It will return the available index number through the pointer pId.

Returns: GT511_ERR_NONE if an empty index was found. If no empty slot is found then GT511_ERR_INVALID_POS is returned.

GT511_Error_t GT511_RunIdentify ( uint32_t * pId )

Run the identification process.

Parameters

pId	points to the ID index match, if any

This function runs through all of the steps needed for fingerprint identification, and returns the ID index of the match if one is found. The user/app will be notified of progress as needed by calling GT511_UserCallback(). For example, the callback function will be called to inform the app/user when the finger should be pressed to the sensor. It will be up to the application how this prompt is manifested to the user.

The following table shows how the callback is used for the various steps. In all cases, the mode parameter of the callback function will be GT511_MODE_IDENTIFY.

callback parameter	event
GT511_UI_PRESS	user should press the sensor
GT511_UI_RELEASE	user should release the sensor
GT511_UI_TIMEOUT	timed out waiting for press or release
GT511_UI_ACCEPT	the fingerprint was identified
GT511_UI_REJECT	no fingerprint match was found
GT511_UI_ERROR	some error occurred (see this function return value)

Returns: GT511_ERR_NONE if a fingerprint match was found, in which case the ID index value will be stored at *pId. If the fingerprint was read but no match was found, then **GT511_ERR_IDENTIFY_FAILED is returned. Any other return value means that no match was found and may indicate another kind of error.

GT511_Error_t GT511_RunVerify ( uint32_t id )

Run the verification process.

Parameters

id	is the ID index to verify

This function runs through all of the steps needed for fingerprint verification. The user/app will be notified of progress as needed by calling GT511_UserCallback(). For example, the callback function will be called to inform the app/user when the finger should be pressed to the sensor. It will be up to the application how this prompt is manifested to the user.

The following table shows how the callback is used for the various steps. In all cases, the mode parameter of the callback function will be GT511_MODE_VERIFY.

callback parameter	event
GT511_UI_PRESS	user should press the sensor
GT511_UI_RELEASE	user should release the sensor
GT511_UI_TIMEOUT	timed out waiting for press or release
GT511_UI_ACCEPT	the fingerprint was identified
GT511_UI_REJECT	no fingerprint match was found
GT511_UI_ERROR	some error occurred (see this function return value)

Returns: GT511_ERR_NONE if the fingerprint is verified. If the fingerprint was read but does not match the specified index, then **GT511_ERR_IDENTIFY_FAILED is returned. Any other return value means that no match was found and may indicate another kind of error.

GT511_Error_t GT511_RunEnroll ( uint32_t * pId )

Run the enrollment process.

Parameters

pId	points to the ID index to use for enrollment

This function runs through all of the steps needed for fingerprint enrollment using the ID index specified through pId. The user/app will be notified of progress as needed by calling GT511_UserCallback(). For example, the callback function will be called to inform the app/user when the finger should be pressed to the sensor. It will be up to the application how this prompt is manifested to the user.

The following table shows how the callback is used for the various steps. In all cases, the mode parameter of the callback function will be GT511_MODE_ENROLL.

callback parameter	event
GT511_UI_PRESS	user should press the sensor
GT511_UI_RELEASE	user should release the sensor
GT511_UI_TIMEOUT	timed out waiting for press or release
GT511_UI_ACCEPT	the fingerprint was enrolled
GT511_UI_REJECT	the fingerprint was not enrolled
GT511_UI_ERROR	some error occurred (see this function return value)

Returns: GT511_ERR_NONE if the fingerprint was enrolled. If the fingerprint was not enrolled for some reason, then **GT511_ERR_ENROLL_FAILED is returned. Any other return value means that there was no enrollment due to another kind of error.

bool GT511_SendMessage	(	uint8_t *	pMessage,
		uint32_t	length
	)

Send message to sensor (implemented by application).

Parameters

pMessage	points at packet to be sent to sensor
length	number of bytes in the packet

This function is used by the GT-511C fingerprint sensor driver to send command packets to the sensor. This is normally done via a serial port. This function must be implemented by the application. This can be as simple or sophisticated as needed. For example it may just use poll-waiting to copy bytes to the serial output. Or it may be interrupt driven with buffering and timeouts.

Note: This function is implemented by the application.

Returns: true if the message was sent and false if there was any error sending the message.

uint32_t GT511_ReceiveMessage	(	uint8_t *	pMessage,
		uint32_t	length
	)

Receive message from the sensor (implemented by application).

Parameters

pMessage	points at storage for the incoming message packet
length	number of expected bytes in the packet

This function is used by the GT-511C fingerprint sensor driver to read an incoming message from the sensor. This is normally done via a serial port. This function must be implemented by the application and can be as simple or sophisticated as needed. For example it may just use poll-waiting to copy bytes from the serial input. Or it may be interrupt driven with buffering and timeouts.

Note: This function is implemented by the application.

Returns: The number of bytes that were actually read and stored at pMessage. Anything other than the requested length is considered an error.

void GT511_UserCallback	(	GT511_Mode_t	mode,
		GT511_UserInfo_t	ui
	)

Notify the application/user of a driver event (implemented by application)

Parameters

mode	the current processing mode of the driver
ui	the user event or notification information

This function is used to notify the user or application of a driver event during a process such as enrollment or identification. The main purpose is to provide a way for the driver to request an action such as to press or release the sensor.

Note: This function is implemented by the application.

void GT511_SetTimeout ( GT511_Mode_t mode )

Ask application to start a timeout (implemented by application)

Parameters

mode	the current processing mode of the driver

This function is called by the driver before it enters a process where it must wait for something to occur (such as waiting for a touch). The application must use it to set an appropriate timeout period according to the mode. The same timeout value can be used in all cases, or even no timeout used.

Note: This function is implemented by the application.

bool GT511_CheckTimeout ( GT511_Mode_t mode )

Check for timeout expiration (implemented by application).

Parameters

mode	the current processing mode of the driver

This function is called repeatedly by the driver when it is performing a process that requires waiting for an external event (such as waiting for a touch). The application can return true to indicate that a timeout occurred thus canceling the wait. The application can use a different timeout for each mode, or the same value for all modes, or not even use timeouts if not needed.

Note: This function is implemented by the application.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Features

Hardware Abstraction

Application Callback

Typical API Usage

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation