r503 module

class r503.R503(port, baud=57600, pw=0, addr=4294967295, timeout=1, recv_size=128)

Bases: object

R503 class for interacting with R503 fingerprint sensor module.

auto_enroll(location_id, duplicate_id=1, duplicate_fp=1, ret_status=1, finger_leave=1)

Automatically register a fingerprint template. :param location_id: The location ID to store the template. :type location_id: int :param duplicate_id: The duplicate check method. :type duplicate_id: int :param duplicate_fp: Whether to return duplicate finger status. :type duplicate_fp: int :param ret_status: Return registration status. :type ret_status: int :param finger_leave: Whether finger leaves sensor during registration. :type finger_leave: int

Returns:

The confirmation code 0 if success

auto_identify(security_lvl=3, start_pos=0, end_pos=199, ret_key_step=0, num_of_fp_errors=1)

Search and verify a fingerprint return: (tuple) fp store location, match score

cancel()

Cancel instruction returns: (int) confirmation code

check_sensor()

Check whether the sensor is normal returns: (int) confirmation code

static conf_codes()

Read confirmation codes from the json file. This function opens the ‘confirmation_codes.json’ file, loads the JSON data from it, and returns the loaded JSON object. :param self: The R503 class instance.

Returns:

The loaded JSON object containing the confirmation codes.

Return type:

jsob

confirmation_decode(c_code)

Decode confirmation code to understandable string parameter: (int) c_code - confirmation code returns: (str) decoded confirmation code

delete_char(page_num, num_of_temps_to_del=1)

Delete stored fingerprint templates.

Parameters:

• page_num – The page number to delete templates from.

• num_of_temps_to_del – The number of templates to delete. Default is 1.

Returns:

Confirmation code integer.

This function will:

• Pack the page number and number of templates to delete into a packet.

• Send the delete instruction packet to the sensor.

• Return the confirmation code response from the sensor.

down_char(img_data, buffer_id=1)

Download a fingerprint template to the sensor module buffer.

Parameters:

• img_data (list) – The fingerprint template data split into packets.

• buffer_id (int) – The buffer ID to download to. Default is 1.

Returns:

The confirmation code from the module.

Return type:

int

This function downloads a full fingerprint template in packets to the specified buffer on the sensor module.

down_image(img_data)

Download image from the upper computer to the image buffer parameters: img_data (list of lists) image data as a list of lists returns: confirmation code

down_packet(img_pkt, end=False)

Send a downlink data packet to the sensor module.

Parameters:

• img_pkt (bytes) – The image packet data to send.

• end (bool) – Whether this packet indicates the end of the image. Default is False.

Returns:

None

empty_finger_lib()

Empty all stored fingerprints.

This function will:

• Send the empty library instruction to the sensor.

• Return the confirmation code response.

Returns:

Confirmation code integer.

get_alg_ver()

Get the algorithm version from the fingerprint sensor. :param self: The R503 instance. :type self: R503

Returns:

A tuple containing the algorithm version. The confirmation code is returned as the first tuple value. The algorithm version is returned as the second tuple value.

Return type:

(int, int)

get_available_location(index_page=0)

Provides next available location in fingerprint library parameters: (int) index_page Returns: (int) next available location

get_fw_ver()

Get firmware version. :param self: The R503 instance. :type self: R503

Returns:

A tuple containing the confirmation code and firmware version.

The serial number is returned in recv_data[4]. The firmware version is returned in recv_data[5].

Return type:

(int, int)

get_image_ex()

Detect a finger and store it in image_buffer return 0x07 if image poor quality returns: (int) confirmation code

get_img()

Detect a finger and store it in image_buffer returns: (int) confirmation code

get_random_code()

Generate a random 32-bit integer from the sensor module. :returns: The 32-bit random integer value if success else 99 :rtype: random_num (int)

handshake()

Send handshake instructions to the module, Confirmation code 0 receives if the sensor is normal returns: (int) confirmation code

header = b'\xef\x01'

img2tz(buffer_id)

Generate character file from the original image in Image Buffer and store the file in CharBuffer 1 or 2 parameter: (int) buffer_id, 1 or 2 returns: (int) confirmation code

led_control(ctrl=3, speed=0, color=1, cycles=0)

ctrl: (int) 1 to 6 1: breathing light, 2: flashing light, 3: always on, 4: always off, 5: gradually on, 6: gradually off speed: (int) 0 to 255 color: (int) 0 to 7 cycles: (int) 0 to 255 returns: confirmation code

load_char(page_id, buffer_id=1)

Load template ath the specified location of flash library to template buffer parameters: page_id => (int) page number

buffer id => (int) character buffer id

manual_enroll(location, buffer_id=1, timeout=10, num_of_fps=4, loop_delay=0.3)

Manually enroll a new fingerprint.

Parameters:

• location – The memory location to store the fingerprint.

• buffer_id – The buffer id to store intermediate data. Default 1.

• timeout – The timeout in seconds. Default 10.

• num_of_fps – The number of fingerprints to capture. Default 4.

• loop_delay – The delay between capture attempts in seconds. Default 0.3.

This function will:

• Prompt the user to place their finger on the sensor and capture fingerprints.

• Generate character files from the fingerprints.

• Register a fingerprint model once num_of_fps prints are captured.

• Store the fingerprint model in the specified memory location.

• Timeout after timeout seconds if fingerprints are not captured.

match()

Compare the recently extracted character with the templates in the ModelBuffer, providing matching result. returns: (tuple) status: [0: matching, 1: error, 8: not matching], match score

pid_cmd = 1

read_index_table(index_page=0)

Read the fingerprint template index table parameters: (int) index_page = 0/1/2/3 returns: (list) index which fingerprints saved already

read_info_page()

Read the information page returns: (int) confirmation code or (bytearray) info page contents

read_msg(data_stream)

Unpack byte stream to readable data returns: (tuple) header, address, package id, package len, confirmation code, package, checksum

read_notepad(page_no)

Read data from a specific notepad page in module memory. :param page_no: The page number to read, 0-15 :type page_no: int

Returns:

Status code, -1 if invalid page data (bytearray): Data read from the page

Return type:

status (int)

read_prod_info()

Read product information from the fingerprint sensor.

It sends the command, checks the confirmation code, and if successful, slices the info byte string into 9 parts:

• Manufacturer name:

• Model number:

• Serial number:

• Hardware version:

• Sensor type:

• Sensor image width:

• Sensor image height:

• Template size:

• Fingerprint database size:

Parameters:

self – The R503 instance

Returns:

Tuple of 9 info strings if successful, else 99

read_prod_info_decode()

Decode raw product info into a human-readable dictionary.

This calls read_prod_info() to get the raw info bytes. If it returns 99 (error), this returns 99.

Otherwise, it decodes the raw bytes into a dictionary:

• module_type: ASCII string

• batch_number: ASCII string

• serial_number: ASCII string

• hw_main_version: Integer

• hw_sub_version: Integer

• sensor_type: ASCII string

• image_width: Integer

• image_height: Integer

• template_size: Integer

• fp_database_size: Integer

Parameters:

self – The R503 instance

Returns:

Decoded product info if successful, else 99

Return type:

dict

read_sys_para()

Status register and other basic configuration parameters returns: (list) status_reg, sys_id_code, finger_lib_size, security_lvl, device_addr, data_packet_size, baud_rate

read_sys_para_decode()

Get system parameters in a decoded, human-readable format.

Otherwise, it returns a dictionary with the parameters decoded:

• system_busy: boolean

• matching_finger_found: boolean

• pw_verified: boolean

• valid_image_in_buffer: boolean

• system_id_code: int

• finger_library_size: int

• security_level: int

• device_address: int

• data_packet_size: int

• baud_rate: int

Parameters:

self – The R503 instance.

Returns:

Decoded system parameters if successful, else 99.

Return type:

dict

read_valid_template_num()

Read number of valid templates stored in module. :returns: Number of valid templates stored. :rtype: num_templates (int)

reg_model()

Combine info of character files in CharBuffer 1 and 2 and generate a template which is stored back in both CharBuffer 1 and 2 input parameters: None returns: (int) confirmation code

search(buff_num=1, start_id=0, para=200)

Search the whole finger library for the template that matches the one in CharBuffer 1 or 2 parameters: buff_num = character buffer id, start_id = starting from, para = end position returns: (tuple) status [success:0, error:1, no match:9], template number, match score

ser_close()

Closes the serial port

ser_send(pkg_len, instr_code, pid=1, pkg=None, timeout=1)

Send a command packet to the R503 module and receive response. :param pkg_len: Length of the payload :type pkg_len: int :param instr_code: Instruction code :type instr_code: int :param pid: Packet ID, default is command packet ID :type pid: int :param pkg: Payload data :type pkg: bytes :param timeout: Serial timeout in seconds :type timeout: int

Returns:

Parsed response packet:

[header, address, pid, pkg_len, conf_code, payload, checksum] If no response, an error list is returned.

Return type:

result (list)

set_address(new_addr)

Set module address Set the new address when setting the class object next time parameter: (int) new_addr returns: (int) confirmation code => 0 [success], 1, 24, 99

set_baud(baud=57600)

Set the baud rate for serial communication.

This function sets the baud rate for serial communication to one of the allowed values: 9600, 19200, 38400, 57600 (default), 115200.

Parameters:

• self – The R503 class instance.

• baud (int) – The desired baud rate. Default is 57600.

Returns:

The confirmation code received after setting

the baud rate. 0 means success.

Return type:

conf_code (int)

It calculates the baud rate divisor, checks if it is valid, sends the set baud rate command, updates the self.ser.baudrate if successful, and returns the confirmation code.

set_pkg_length(pkg_len=128)

Set the package length for serial communication.

This function sets the package length to one of the allowed values: 32, 64, 128 (default), 256 bytes.

Parameters:

• self – The R503 class instance.

• pkg_len (int) – The desired package length. Default is 128.

Returns:

The confirmation code received after setting

the package length. 0 means success.

Return type:

conf_code (int)

It maps the package lengths to index values, checks if valid, sends the set command, updates self.recv_size if successful, and returns the confirmation code response.

set_pw(new_pw)

Set modules handshaking password parameters: (int) new_pw - New password returns: (int) confirmation code

set_security(lvl=3)

Set the security level of the fingerprint sensor.

This function sets the security level to one of 5 levels: 1: Low 2: Medium 3: High (default) 4: Higher 5: Highest

Parameters:

• self – The R503 class instance.

• lvl (int) – The desired security level, 1-5. Default is 3.

Returns:

The confirmation code received after setting the security level. 0 means success.

Return type:

conf_code (int)

It checks if the security level is valid, sends the set security command with the level, and returns the confirmation code response.

soft_reset()

Perform a soft reset of the R503 module. :param self: The R503 instance. :type self: R503

Returns:

The confirmation code received after

resetting the module. 0 means success.

Return type:

conf_code (int)

store(buffer_id, page_id, timeout=2)

Store a fingerprint template to the module’s flash library.

This function stores the template from the specified buffer (buffer1 or buffer2) to the page number in the flash library.

Parameters:

• buffer_id (int) – 1 for buffer1, 2 for buffer2

• page_id (int) – Page number to store the template

• timeout (int) – Timeout in seconds. Default is 2.

Returns:

The confirmation code received after storing.

0 means success.

Return type:

conf_code (int)

It packs the buffer and page IDs into a package, sends the store command with the package, and returns the confirmation code response.

up_char(timeout=5, raw=False)

Upload the data in template buffer to the upper computer parameter: (int) timeout: timeout could vary if you change the baud rate, for 57600baud 5seconds is sufficient If you use a lower baud rate timeout may have to be increased. returns: (bytearray) if raw == True

else (list of lists)

In raw mode returns the data with all headers (address byte, status bytes etc.) raw == False mode only returns the image data [all other header bytes are filtered out]

up_image(timeout=5, raw=False)

Upload the image in Img_Buffer to upper computer every image contains the data around 20kilo bytes parameter: (int) timeout: timeout could vary if you change the baud rate, for 57600baud 5seconds is sufficient If you use a lower baud rate timeout may have to be increased. returns: (bytesarray) if raw == True

else (list of lists)

In raw mode returns the data with all headers (address byte, status bytes etc.) raw == False mode only returns the image data [all other header bytes are filtered out]

verify_pw(pw=0)

Verify modules handshaking password returns: (int) confirmation code

write_notepad(page_no, content)

Write data to the specific flash pages: 0 to 15, each page contains 32bytes of data, any data type is given to the content will be converted to the string data type before writing to the notepad. :param page_no: (int) 1 - 15, page number :param content: (any) data to write to the flash

returns: (int) status code => 0 - success, 1 - error when receiving pkg, 18 - error when write flash,