Fingerprint unit. More...

#include <unit_Finger2.hpp>

Inheritance diagram for m5::unit::UnitFinger2:

Classes
struct	config_t
	Settings for begin. More...

Public Types
using	Packet = std::vector<uint8_t>

Public Member Functions
virtual bool	begin () override
	Begin communication with the unit.

bool	readModuleStatus (bool &awake)
	Read the module status.

bool	wakeup ()
	Wakeup.

bool	readInformationPage (uint8_t info[512])
	Read the the information page in FLASH( 512 bytes)

bool	readRandomNumber (uint32_t &value)
	Read the random number (32bits)

bool	handshake (bool &status)
	Verify that the module is working properly.

bool	checkSensor (bool &status)
	Verify whether the sensor is working properly.

bool	readSerialNumber (uint8_t sn[32])
	Read the serial number (32 bytes)

bool	readFirmwareVersion (uint8_t &ver)
	Read the firmware version.

Settings for begin
config_t	config ()
	Gets the configuration.

void	config (const config_t &cfg)
	Set the configuration.

Properties
uint32_t	deviceAddress () const
	Get the device address.

constexpr uint16_t	imageWidth () const
	Get the image width.

constexpr uint16_t	imageHeight () const
	Get the image height.

uint16_t	capacity () const
	Get the capacity of templates.

Settings
bool	readWorkMode (finger2::WorkMode &wm)
	Read the work mode.

bool	writeWorkMode (const finger2::WorkMode wm)
	Write the work mode.

bool	saveWorkMode ()
	Write the current work mode to internal flash.

bool	readSleepTime (uint8_t &sec)
	Read the time to go to sleep (second)

bool	writeSleepTime (const uint8_t sec)
	Write the time to go to sleep (second)

bool	saveSleepTime ()
	Write the current sleep time to internal flash.

bool	readSystemParams (finger2::SystemBasicParams &params)
	Read the system basic parameters.

bool	writeSystemRegister (const finger2::RegisterID reg_id, const uint8_t value)
	Write the value to register for settings.

bool	writeControlLED (const finger2::LEDMode mode, const finger2::LEDColor clr, const uint8_t cycle=0, const finger2::LEDColor eclr=finger2::LEDColor::Black)
	Write the LED control.

bool	writeControlLEDRainbow (const uint8_t tm, const finger2::LEDColor *colors, const uint8_t colors_num, const uint8_t cycle)
	Write the LED control for LEDMode::Rainbow.

Finger
Warning Returns an error when device is sleeping
bool	capture (bool &detected, const bool enroll=false)
	Capture the fingerprint image.

bool	readImageInformation (uint8_t &percentage, bool &quality)
	Capture the fingerprint and read image information.

bool	readImage (std::vector< uint8_t > &img)
	Read the finger image.

bool	generateCharacteristic (const uint8_t buffer_id=1)
	Generate characteristic from captured image.

bool	generateTemplate ()
	Generate template from merged characteristics.

bool	storeTemplate (const uint16_t page_id, const uint8_t buffer_id=1)
	Store template.

bool	match (bool &matched, uint16_t &score)
	Is match buffer 1 and 2? (1:1)

bool	search (bool &matched, uint16_t &matching_page_id, uint16_t &score, const uint8_t buffer_id=1, const uint16_t start_page=0, const uint16_t page_num=0)
	Search for matching template (1:N)

bool	searchNow (bool &matched, uint16_t &matching_page_id, uint16_t &score, const uint16_t start_page=0, const uint16_t page_num=0)
	Search for matching template using the last extracted template (1:N)

Template
Warning Returns an error when device is sleeping
bool	loadTemplate (const uint8_t buffer_id, const uint16_t page_id)
	Load template to buffer.

bool	readTemplate (uint16_t &actual_size, uint8_t *buf, const uint16_t buf_size, const uint16_t offset)
	Read the specific size template from the specific offset.

bool	readTemplateAllBatches (uint16_t &actual_size, uint8_t *buf, const uint16_t buf_size, const uint16_t batch_size=128, finger2::batch_callback_t callback=nullptr)
	Read the template.

bool	writeTemplate (const uint16_t offset, const uint8_t *buf, const uint16_t buf_size)
	Write the specific size template to the specific offset.

bool	writeTemplateAllBatches (const uint8_t *buf, const uint16_t buf_size, const uint16_t batch_size=128, finger2::batch_callback_t callback=nullptr)
	Write the template.

bool	deleteTemplate (const uint16_t page_id, const uint16_t num=1)
	Delete templates.

bool	clear ()
	Clear fingerprint database (delete all templates)

bool	readValidTemplates (uint16_t &num)
	Read the number of valid templates.

bool	readIndexTable (uint8_t table[32])
	Read the index table (Bits of existing templates)

bool	existsTemplate (const uint16_t page_id)
	Exists template?

bool	findLowestAvailablePage (uint16_t &page)
	Find the lowest available page number.

bool	findHighestAvailablePage (uint16_t &page)
	Find the highest available page number.

Automatic function
Warning Returns an error when device is sleeping
bool	autoEnroll (finger2::ConfirmCode &confirm, const uint16_t page_id, const uint8_t capture_times=5, const finger2::auto_enroll_flag_t flags=0, finger2::auto_enroll_callback_t callback=nullptr)
	Automatic registration.

bool	autoIdentify (bool &matched, uint16_t &matching_page_id, uint16_t &score, const uint16_t page_id=0xFFFF, const uint8_t security_level=0, finger2::auto_identify_flag_t flags=0, const finger2::auto_identify_callback_t callback=nullptr)
	Automatic identify (1:1, 1:N)

bool	cancel ()
	Abort automatic functions.

Notepad
bool	readNotepad (uint8_t buf[32], const uint8_t page)
	Read the notepad(Flash) data.

bool	writeNotepad (const uint8_t page, const uint8_t *buf, const uint8_t len)
	Write the notepad(Flash) data.

Static Public Attributes
static constexpr uint32_t	DEFAULT_MODULE_ADDRESS {0xFFFFFFFF}
	Default device address.

static constexpr uint16_t	IMAGE_WIDTH {80}
	Capture image width.

static constexpr uint16_t	IMAGE_HEIGHT {208}
	Captured image height.

static constexpr uint16_t	TEMPLATE_SIZE {7262}
	Template size.

Protected Member Functions
	UnitFinger2 (const uint32_t device_address)

bool	write_command (const uint8_t cmd, const uint32_t addr, const uint8_t *payload=nullptr, const uint16_t payload_len=0)

finger2::ConfirmCode	read_response (Packet &rbuf)

bool	transceive_command (Packet &rbuf, const uint8_t cmd, const uint32_t addr, const uint8_t *payload=nullptr, const uint16_t payload_len=0)

bool	transceive_command8 (Packet &rbuf, const uint8_t cmd, const uint32_t addr, const uint8_t value)

uint8_t	read_data (Packet &rbuf)

Detailed Description

Fingerprint unit.

Member Function Documentation

◆ autoEnroll()

bool m5::unit::UnitFinger2::autoEnroll	(	finger2::ConfirmCode &	confirm,
		const uint16_t	page_id,
		const uint8_t	capture_times = 5,
		const finger2::auto_enroll_flag_t	flags = 0,
		finger2::auto_enroll_callback_t	callback = nullptr )

Automatic registration.

PS_AutoEnroll

Perform capture and generate characteristic operations for the specified number of times, merge them, and store template to the specified page_id

Parameters

[out]	confirm	ConfirmCode
	page_id	Page number
	capture_times	Number of finger captures for registration
	flags	Operation Control Flag
	callback	Callback function that receives and processes intermediate results

Returns: True if successful

Warning: This feature is supported when the security level is 0 or 1

◆ autoIdentify()

bool m5::unit::UnitFinger2::autoIdentify	(	bool &	matched,
		uint16_t &	matching_page_id,
		uint16_t &	score,
		const uint16_t	page_id = 0xFFFF,
		const uint8_t	security_level = 0,
		finger2::auto_identify_flag_t	flags = 0,
		const finger2::auto_identify_callback_t	callback = nullptr )

Automatic identify (1:1, 1:N)

PS_AutoIdentify

Parameters

[out]	matched	true if matched
[out]	matching_page_id	Matching page number
[out]	score	Matching score (lowest: 0)
	page_id	Verification target page number(1:1), All page if page_id is 0xFFFF (1:N)
	security_level	Security level (0 -1)
	flags	Operation Control Flag
	callback	Callback function that receives and processes intermediate results

Returns: True if successful

Warning: This feature is supported when the security level is 0 or 1

◆ cancel()

bool m5::unit::UnitFinger2::cancel ( )

Abort automatic functions.

Returns: True if successful

Warning: This feature is supported when the security level is 0 or 1

◆ capacity()

uint16_t m5::unit::UnitFinger2::capacity ( ) const

inline

Get the capacity of templates.

Warning: Returns the correct value after begin() succeeds

◆ capture()

bool m5::unit::UnitFinger2::capture	(	bool &	detected,
		const bool	enroll = false )

Capture the fingerprint image.

PS_GetImage or PS_GetEnrollImage

Parameters

[out]	detected	true if finger detected
	enroll	true for register(PS_GetEnrollImage), false for detection(PS_GetImage)

Returns: True if successful

◆ checkSensor()

bool m5::unit::UnitFinger2::checkSensor ( bool & status )

Verify whether the sensor is working properly.

PS_CheckSensor

Parameters

[out] status OK if true

Returns: True if successful

Warning: Returns an error when device is sleeping

◆ clear()

bool m5::unit::UnitFinger2::clear ( )

Clear fingerprint database (delete all templates)

PS_Empty

Deleting all fingerprint modules in flash database

Returns: True if successful

◆ deleteTemplate()

bool m5::unit::UnitFinger2::deleteTemplate	(	const uint16_t	page_id,
		const uint16_t	num = 1 )

Delete templates.

PS_DeletChar

Parameters

page_id	First page to be deleted
num	How many to delete starting from the first target

Returns: True if successful

◆ deviceAddress()

uint32_t m5::unit::UnitFinger2::deviceAddress ( ) const

inline

Get the device address.

Note: Changing the device address is not permitted

◆ existsTemplate()

bool m5::unit::UnitFinger2::existsTemplate ( const uint16_t page_id )

Exists template?

Parameters

page_id Page number

Return values

True	if exists
False	if not exists or failed

Note: Internally calling readIndexTable(); Therefore, when checking whether a large number of templates are existed,; it is better to call readIndexTable once and verify table yourself

◆ findHighestAvailablePage()

bool m5::unit::UnitFinger2::findHighestAvailablePage ( uint16_t & page )

Find the highest available page number.

Parameters

[out] page Page number (Not exists if 0xFFFF)

Returns: True if successful

◆ findLowestAvailablePage()

bool m5::unit::UnitFinger2::findLowestAvailablePage ( uint16_t & page )

Find the lowest available page number.

Parameters

[out] page Page number (Not exists if 0xFFFF)

Returns: True if successful

◆ generateCharacteristic()

bool m5::unit::UnitFinger2::generateCharacteristic ( const uint8_t buffer_id = 1 )

Generate characteristic from captured image.

PS_GenChar

Generating the original image in ImageBuffer to fingerprint feature file and store it in CharBuffer

Parameters

buffer_id Buffer number (1 - 5)

Returns: True if successful

Precondition: capture() succeeded

◆ generateTemplate()

bool m5::unit::UnitFinger2::generateTemplate ( )

Generate template from merged characteristics.

PS_RegModel

After merging the characteristics, generate a template.

Returns: True if successful

Precondition: generateCharacteristic() succeeded

◆ handshake()

bool m5::unit::UnitFinger2::handshake ( bool & status )

Verify that the module is working properly.

PS_HandShake

Parameters

[out] status OK if true

Returns: True if successful

Warning: Returns an error when device is sleeping

◆ loadTemplate()

bool m5::unit::UnitFinger2::loadTemplate	(	const uint8_t	buffer_id,
		const uint16_t	page_id )

Load template to buffer.

PS_LoadChar

Reading the fingerprint templates which appointed page_id in flash database to template buffer

Parameters

buffer_id	Target buffer number (1 - 5)
page_id	Source page number

Returns: True if successful

◆ match()

bool m5::unit::UnitFinger2::match	(	bool &	matched,
		uint16_t &	score )

Is match buffer 1 and 2? (1:1)

PS_Match

Parameters

[out]	matched	true if matched
[out]	score	Matching score (lowest: 0)

Precondition: Buffer IDs 1 and 2 contain template

Returns: True if successful

Warning: This feature is supported when the security level is 0 or 1

◆ readFirmwareVersion()

bool m5::unit::UnitFinger2::readFirmwareVersion ( uint8_t & ver )

Read the firmware version.

PS_GetFirmwareVersion

Parameters

[out] ver Version

Returns: True if successful

◆ readImage()

bool m5::unit::UnitFinger2::readImage ( std::vector< uint8_t > & img )

Read the finger image.

PS_UpImage

Uploading data in image buffer to the host

Parameters

[out] img Image vector (4 bits grayscale)

Returns: True if successful

◆ readImageInformation()

bool m5::unit::UnitFinger2::readImageInformation	(	uint8_t &	percentage,
		bool &	quality )

Capture the fingerprint and read image information.

PS_GetImageInfo

Parameters

[out]	percentage	Image area
[out]	quality	Image quality (true : pass, false: fail)

Returns: True if successful

Precondition: capture() succeeded

◆ readIndexTable()

bool m5::unit::UnitFinger2::readIndexTable ( uint8_t table[32] )

Read the index table (Bits of existing templates)

PS_ReadIndexTable

Bit-level information for registered templates is retrieved

Parameters

[out] table Table data (at least 32 bytes)

Returns: True if successful

◆ readInformationPage()

bool m5::unit::UnitFinger2::readInformationPage ( uint8_t info[512] )

Read the the information page in FLASH( 512 bytes)

PS_ReadINFpage

Parameters

info	Buffer (at least 512 bytes)

Returns: True if successful

◆ readModuleStatus()

bool m5::unit::UnitFinger2::readModuleStatus ( bool & awake )

Read the module status.

PS_GetFingerprintModuleStatus

Parameters

[out] awake true if awake

Returns: True if successful

◆ readNotepad()

bool m5::unit::UnitFinger2::readNotepad	(	uint8_t	buf[32],
		const uint8_t	page )

Read the notepad(Flash) data.

PS_ReadNotepad

Parameters

[out]	buf	Buffer (at least 32 bytes)
	page	Notepad page number (0 - 7)

Returns: True if successful

Note: Notepad is an area of 8 pages totaling 256 bytes in 32 byte units

Warning: Returns an error when device is sleeping

◆ readRandomNumber()

bool m5::unit::UnitFinger2::readRandomNumber ( uint32_t & value )

Read the random number (32bits)

PS_GetRandomCode

Making chip generate a random code and return to the host

Parameters

[out] value Number

Returns: True if successful

Warning: Returns an error when device is sleeping

◆ readSerialNumber()

bool m5::unit::UnitFinger2::readSerialNumber ( uint8_t sn[32] )

Read the serial number (32 bytes)

PS_GetChipSN

Parameters

[out] sn serial number buffer (at least 32 bytes)

Returns: True if successful

Warning: Returns an error when device is sleeping

◆ readSleepTime()

bool m5::unit::UnitFinger2::readSleepTime ( uint8_t & sec )

Read the time to go to sleep (second)

PS_GetSleepTime

Parameters

[out] sec Time (second)

Returns: True if successful

◆ readSystemParams()

bool m5::unit::UnitFinger2::readSystemParams ( finger2::SystemBasicParams & params )

Read the system basic parameters.

PS_ReadSysPara

Parameters

[out] params SystemBasicParams

Returns: True if successful

Warning: Returns an error when device is sleeping

◆ readTemplate()

bool m5::unit::UnitFinger2::readTemplate	(	uint16_t &	actual_size,
		uint8_t *	buf,
		const uint16_t	buf_size,
		const uint16_t	offset )

Read the specific size template from the specific offset.

PS_UpTemplet

Uploading the feature files in feature buffer to the host

Parameters

[out]	actual_size	Actual size
[out]	buf	Output buffer (at least buf_size bytes)
	buf_size	size of buf
	offset	Offset address

Returns: True if successful

Precondition: The template exists in the buffer

◆ readTemplateAllBatches()

bool m5::unit::UnitFinger2::readTemplateAllBatches	(	uint16_t &	actual_size,
		uint8_t *	buf,
		const uint16_t	buf_size,
		const uint16_t	batch_size = 128,
		finger2::batch_callback_t	callback = nullptr )

Read the template.

Parameters

[out]	actual_size	Actual size
[out]	buf	Output buffer (at least 7262 bytes)
	batch_size	Processing size per batch
	callback	Callback invoked for each batch processing

Returns: True if successful

Precondition: The template exists in the buffer

◆ readValidTemplates()

bool m5::unit::UnitFinger2::readValidTemplates ( uint16_t & num )

Read the number of valid templates.

PS_ValidTemplateNum

Parameters

[out] num Number

Returns: True if successful

◆ readWorkMode()

bool m5::unit::UnitFinger2::readWorkMode ( finger2::WorkMode & wm )

Read the work mode.

PS_GetWorkMode

Parameters

[out] wm WorkMode

Returns: True if successful

◆ saveSleepTime()

bool m5::unit::UnitFinger2::saveSleepTime ( )

Write the current sleep time to internal flash.

PS_SaveConfigurationToFlash

Returns: True if successful

Note: It will be the default sleep time at startup

Warning: This API will affect the life of the device. Do not use it frequently.

◆ saveWorkMode()

bool m5::unit::UnitFinger2::saveWorkMode ( )

Write the current work mode to internal flash.

PS_SaveConfigurationToFlash

Returns: True if successful

Note: It will be the default work mode at startup

Warning: This API will affect the life of the device. Do not use it frequently.

◆ search()

bool m5::unit::UnitFinger2::search	(	bool &	matched,
		uint16_t &	matching_page_id,
		uint16_t &	score,
		const uint8_t	buffer_id = 1,
		const uint16_t	start_page = 0,
		const uint16_t	page_num = 0 )

Search for matching template (1:N)

PS_Search

Parameters

[out]	matched	true if matched
[out]	matching_page_id	Matching page number
[out]	score	Matching score (lowest: 0)
	buffer_id	Buffer number (comparison target)
	start_page	Search start page
	page_num	Number of search pages (0: From start_page to end)

Returns: True if successful

Precondition: The data exists in the specified buffer

Warning: This feature is supported when the security level is 0 or 1

◆ searchNow()

bool m5::unit::UnitFinger2::searchNow	(	bool &	matched,
		uint16_t &	matching_page_id,
		uint16_t &	score,
		const uint16_t	start_page = 0,
		const uint16_t	page_num = 0 )

Search for matching template using the last extracted template (1:N)

PS_SearchNow

Parameters

[out]	matched	true if matched
[out]	matching_page_id	Matching page number
[out]	score	Matching score (lowest: 0)
	start_page	Search start page
	page_num	Number of search pages (0: From start_page to end)

Returns: True if successful

Precondition: The data exists in the specified buffer

Warning: This feature is supported when the security level is 0 or 1

◆ storeTemplate()

bool m5::unit::UnitFinger2::storeTemplate	(	const uint16_t	page_id,
		const uint8_t	buffer_id = 1 )

Store template.

PS_StoreChar

Store the template at the buffer_id position into the page_id position in the database

Parameters

page_id	Page number
buffer_id	Buffer number (1 - 5)

Returns: True if successful

Precondition: generateTemplate() succeeded

Warning: This feature is supported when the security level is 0 or 1

◆ wakeup()

bool m5::unit::UnitFinger2::wakeup ( )

Wakeup.

PS_ActivateModule

Returns: True if successful

Note: If WorkMode is ScheduledSleep, the device goes to sleep if fingerprints remain undetected

◆ writeControlLED()

bool m5::unit::UnitFinger2::writeControlLED	(	const finger2::LEDMode	mode,
		const finger2::LEDColor	clr,
		const uint8_t	cycle = 0,
		const finger2::LEDColor	eclr = finger2::LEDColor::Black )

Write the LED control.

PS_ControlBLN

Parameters

mode	LEDMode (Ignore LEDMode::Rainbow)
clr	Start LEDColor
cycle	Cycle count, infinity if zero. Valid for LEDMode::Breath, LEDMode::Blink
eclr	End LEDColor (Valid for LEDMode::Breath)

Returns: True if successful

Warning: Returns an error when device is sleeping

◆ writeControlLEDRainbow()

bool m5::unit::UnitFinger2::writeControlLEDRainbow	(	const uint8_t	tm,
		const finger2::LEDColor *	colors,
		const uint8_t	colors_num,
		const uint8_t	cycle )

Write the LED control for LEDMode::Rainbow.

PS_ControlBLN

Parameters

tm	Color change time (decisecond)
colors	LEDColor array (maximum 10)
colors_num	Number of the colors (maximum 10)
cycle	Cycle count, infinity if zero. Valid for LEDMode::Breath, LEDMode::Blink

Returns: True if successful

Warning: Returns an error when device is sleeping

◆ writeNotepad()

bool m5::unit::UnitFinger2::writeNotepad	(	const uint8_t	page,
		const uint8_t *	buf,
		const uint8_t	len )

Write the notepad(Flash) data.

PS_WriteNotepad

Parameters

page	Notepad page number (0 - 7)
buf	Input buffer
len	buffer length (1 - 32) If larger than 32 bytes, write up to 32 bytes

Returns: True if successful

Note: Notepad is an area of 8 pages totaling 256 bytes in 32 byte units

Warning: Returns an error when device is sleeping; When less than 32 bytes are written, the missing bytes are filled with zeros

◆ writeSleepTime()

bool m5::unit::UnitFinger2::writeSleepTime ( const uint8_t sec )

Write the time to go to sleep (second)

PS_SetSleepTime

Parameters

sec	Time that valid range 10-254 (second)

Returns: True if successful

◆ writeSystemRegister()

bool m5::unit::UnitFinger2::writeSystemRegister	(	const finger2::RegisterID	reg_id,
		const uint8_t	value )

Write the value to register for settings.

PS_WriteReg

Parameters

reg_id	Target RegisterID
value	Value

Returns: True if successful

Note: See also the the protocol specification document

◆ writeTemplate()

bool m5::unit::UnitFinger2::writeTemplate	(	const uint16_t	offset,
		const uint8_t *	buf,
		const uint16_t	buf_size )

Write the specific size template to the specific offset.

Parameters

offset	Offset address
buf	Input buffer
buf_size	size of buf

Returns: True if successful

◆ writeTemplateAllBatches()

bool m5::unit::UnitFinger2::writeTemplateAllBatches	(	const uint8_t *	buf,
		const uint16_t	buf_size,
		const uint16_t	batch_size = 128,
		finger2::batch_callback_t	callback = nullptr )

Write the template.

Parameters

buf	Input buffer
buf_size	size of buf
batch_size	Processing size per batch
callback	Callback invoked for each batch processing

Returns: True if successful

◆ writeWorkMode()

bool m5::unit::UnitFinger2::writeWorkMode ( const finger2::WorkMode wm )

Write the work mode.

PS_SetWorkMode

Parameters

wm WorkMode

Returns: True if successful

Classes

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Member Function Documentation

◆ autoEnroll()

◆ autoIdentify()

◆ cancel()

◆ capacity()

◆ capture()

◆ checkSensor()

◆ clear()

◆ deleteTemplate()

◆ deviceAddress()

◆ existsTemplate()

◆ findHighestAvailablePage()

◆ findLowestAvailablePage()

◆ generateCharacteristic()

◆ generateTemplate()

◆ handshake()

◆ loadTemplate()

◆ match()

◆ readFirmwareVersion()

◆ readImage()

◆ readImageInformation()

◆ readIndexTable()

◆ readInformationPage()

◆ readModuleStatus()

◆ readNotepad()

◆ readRandomNumber()

◆ readSerialNumber()

◆ readSleepTime()

◆ readSystemParams()

◆ readTemplate()

◆ readTemplateAllBatches()

◆ readValidTemplates()

◆ readWorkMode()

◆ saveSleepTime()

◆ saveWorkMode()

◆ search()

◆ searchNow()

◆ storeTemplate()

◆ wakeup()

◆ writeControlLED()

◆ writeControlLEDRainbow()

◆ writeNotepad()

◆ writeSleepTime()

◆ writeSystemRegister()

◆ writeTemplate()

◆ writeTemplateAllBatches()

◆ writeWorkMode()