fingerprint4.h

Go to the documentation of this file.

/****************************************************************************
** Copyright (C) 2020 MikroElektronika d.o.o.
** Contact: https://www.mikroe.com/contact
**
** Permission is hereby granted, free of charge, to any person obtaining a copy
** of this software and associated documentation files (the "Software"), to deal
** in the Software without restriction, including without limitation the rights
** to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
** copies of the Software, and to permit persons to whom the Software is
** furnished to do so, subject to the following conditions:
** The above copyright notice and this permission notice shall be
** included in all copies or substantial portions of the Software.
**
** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
** EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
** OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
** IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
** DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
** OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
**  USE OR OTHER DEALINGS IN THE SOFTWARE.
****************************************************************************/
 
#ifndef FINGERPRINT4_H
#define FINGERPRINT4_H
 
#ifdef __cplusplus
extern "C"{
#endif
 
#ifdef PREINIT_SUPPORTED
#include "preinit.h"
#endif
 
#ifdef MikroCCoreVersion
    #if MikroCCoreVersion >= 1
        #include "delays.h"
    #endif
#endif
 
#include "drv_digital_out.h"
#include "drv_digital_in.h"
#include "drv_spi_master.h"
#include "spi_specifics.h"
#include "drv_uart.h"
 
#define FINGERPRINT4_CMD_NONE                   0x0000
#define FINGERPRINT4_CMD_CAPTURE                0x0001
#define FINGERPRINT4_CMD_ENROLL                 0x0002
#define FINGERPRINT4_CMD_IDENTIFY               0x0003
#define FINGERPRINT4_CMD_MATCH                  0x0004
#define FINGERPRINT4_CMD_IMAGE                  0x0005
#define FINGERPRINT4_CMD_TEMPLATE               0x0006
#define FINGERPRINT4_CMD_WAIT                   0x0007
#define FINGERPRINT4_CMD_SETTINGS               0x0008
#define FINGERPRINT4_CMD_NAVIGATE               0x1001
#define FINGERPRINT4_CMD_SENSOR                 0x1002
#define FINGERPRINT4_CMD_DEADPIXELS             0x1003
#define FINGERPRINT4_CMD_CONNECT                0x2001
#define FINGERPRINT4_CMD_RECONNECT              0x2002
#define FINGERPRINT4_CMD_RESET                  0x3002
#define FINGERPRINT4_CMD_CANCEL                 0x3003
#define FINGERPRINT4_CMD_INFO                   0x3004
#define FINGERPRINT4_CMD_STORAGE_TEMPLATE       0x4002
#define FINGERPRINT4_CMD_STORAGE_CALIBRATION    0x4003
#define FINGERPRINT4_CMD_STORAGE_LOG            0x4004
#define FINGERPRINT4_CMD_STORAGE_SETTINGS       0x4005
#define FINGERPRINT4_CMD_TEST                   0x5001
#define FINGERPRINT4_CMD_MCU                    0x5002
#define FINGERPRINT4_CMD_GPIO                   0x5003
#define FINGERPRINT4_CMD_COMMUNICATION          0x6001
#define FINGERPRINT4_CMD_APP_BASE               0xE000
#define FINGERPRINT4_CMD_DIAG                   0xF003
#define FINGERPRINT4_CMD_FFFF                   0xFFFF
 
#define FINGERPRINT4_ARG_NONE                   0x0000
#define FINGERPRINT4_ARG_FINGER_DOWN            0x0001
#define FINGERPRINT4_ARG_FINGER_UP              0x0002
#define FINGERPRINT4_ARG_START                  0x0003
#define FINGERPRINT4_ARG_ADD                    0x0004
#define FINGERPRINT4_ARG_FINISH                 0x0005
#define FINGERPRINT4_ARG_ID                     0x0006
#define FINGERPRINT4_ARG_ALL                    0x0007
#define FINGERPRINT4_ARG_EXTRACT                0x0008
#define FINGERPRINT4_ARG_MATCH_IMAGE            0x0009
#define FINGERPRINT4_ARG_MATCH                  0x000A
#define FINGERPRINT4_ARG_ACQUIRE                0x1001
#define FINGERPRINT4_ARG_RELEASE                0x1002
#define FINGERPRINT4_ARG_SET                    0x1003
#define FINGERPRINT4_ARG_GET                    0x1004
#define FINGERPRINT4_ARG_UPLOAD                 0x1005
#define FINGERPRINT4_ARG_DOWNLOAD               0x1006
#define FINGERPRINT4_ARG_CREATE                 0x1007
#define FINGERPRINT4_ARG_SAVE                   0x1008
#define FINGERPRINT4_ARG_DELETE                 0x1009
#define FINGERPRINT4_ARG_DATA                   0x100A
#define FINGERPRINT4_ARG_UPDATE                 0x100B
#define FINGERPRINT4_ARG_SEQ_NR                 0x100C
#define FINGERPRINT4_ARG_SEQ_LEN                0x100D
#define FINGERPRINT4_ARG_RESULT                 0x2001
#define FINGERPRINT4_ARG_COUNT                  0x2002
#define FINGERPRINT4_ARG_SIZE                   0x2003
#define FINGERPRINT4_ARG_LEVEL                  0x2004
#define FINGERPRINT4_ARG_FORMAT                 0x2005
#define FINGERPRINT4_ARG_FLAG                   0x2006
#define FINGERPRINT4_ARG_PROPERTIES             0x2007
#define FINGERPRINT4_ARG_SPEED                  0x2008
#define FINGERPRINT4_ARG_PROD_TEST              0x2009
#define FINGERPRINT4_ARG_SENSOR_TYPE            0x3001
#define FINGERPRINT4_ARG_WIDTH                  0x3002
#define FINGERPRINT4_ARG_HEIGHT                 0x3003
#define FINGERPRINT4_ARG_RESET                  0x3004
#define FINGERPRINT4_ARG_DPI                    0x3005
#define FINGERPRINT4_ARG_MAX_SPI_CLOCK          0x3006
#define FINGERPRINT4_ARG_NUM_SUB_AREAS_WIDTH    0x3007
#define FINGERPRINT4_ARG_NUM_SUB_AREAS_HEIGHT   0x3008
#define FINGERPRINT4_ARG_IRQ_STATUS             0x3009
#define FINGERPRINT4_ARG_RESET_HARD             0x300A
#define FINGERPRINT4_ARG_IDLE                   0x4001
#define FINGERPRINT4_ARG_SLEEP                  0x4002
#define FINGERPRINT4_ARG_DEEP_SLEEP             0x4003
#define FINGERPRINT4_ARG_POWER_MODE             0x4004
#define FINGERPRINT4_ARG_BUSY_WAIT              0x4005
#define FINGERPRINT4_ARG_TIMEOUT                0x5001
#define FINGERPRINT4_ARG_DONE                   0x5002
#define FINGERPRINT4_ARG_BOOT                   0x6001
#define FINGERPRINT4_ARG_STATUS                 0x6002
#define FINGERPRINT4_ARG_VERSION                0x6003
#define FINGERPRINT4_ARG_UNIQUE_ID              0x6004
#define FINGERPRINT4_ARG_APP_BASE               0x7000
#define FINGERPRINT4_ARG_NONCE                  0x8001
#define FINGERPRINT4_ARG_MAC                    0x8002
#define FINGERPRINT4_ARG_RANDOM                 0x8003
#define FINGERPRINT4_ARG_CLAIM                  0x8004
#define FINGERPRINT4_ARG_PUBLIC_KEY             0x8005
#define FINGERPRINT4_ARG_CIPHERTEXT             0x8006
#define FINGERPRINT4_ARG_MTU                    0x9001
#define FINGERPRINT4_ARG_STACK                  0xE001
#define FINGERPRINT4_ARG_FILL                   0xE002
#define FINGERPRINT4_ARG_HEAP                   0xE003
#define FINGERPRINT4_ARG_MODE                   0xF001
#define FINGERPRINT4_ARG_DEBUG                  0xF002
#define FINGERPRINT4_ARG_FFFF                   0xFFFF
 
 // fingerprint4_reg
 
#define FINGERPRINT4_ARG_PAYLOAD_MAX_SIZE       234
#define FINGERPRINT4_PHY_MTU_SIZE               256
#define FINGERPRINT4_TRANSPORT_LAYER_PLD_SIZE   242
 
#define FINGERPRINT4_ACK_BYTES                  0x7F01FF7Ful
 
#define FINGERPRINT4_NUM_IMAGES                 3
 
#define FINGERPRINT4_DEFAULT_PHY_RX_TIMEOUT_MS  3000
#define FINGERPRINT4_INFINITE_TIMEOUT           0
 
#define FINGERPRINT4_DRV_INTERFACE_UART         0
#define FINGERPRINT4_DRV_INTERFACE_SPI          1
#define FINGERPRINT4_DRV_INTERFACE              FINGERPRINT4_DRV_INTERFACE_SPI
 
#define FINGERPRINT4_SET_DATA_SAMPLE_EDGE       SET_SPI_DATA_SAMPLE_EDGE
#define FINGERPRINT4_SET_DATA_SAMPLE_MIDDLE     SET_SPI_DATA_SAMPLE_MIDDLE
 
 // fingerprint4_set
 
#if ( FINGERPRINT4_DRV_INTERFACE == FINGERPRINT4_DRV_INTERFACE_SPI )
#define FINGERPRINT4_MAP_MIKROBUS( cfg, mikrobus ) \
    cfg.miso = MIKROBUS( mikrobus, MIKROBUS_MISO ); \
    cfg.mosi = MIKROBUS( mikrobus, MIKROBUS_MOSI ); \
    cfg.sck  = MIKROBUS( mikrobus, MIKROBUS_SCK ); \
    cfg.cs   = MIKROBUS( mikrobus, MIKROBUS_CS ); \
    cfg.rst  = MIKROBUS( mikrobus, MIKROBUS_RST ); \
    cfg.irq  = MIKROBUS( mikrobus, MIKROBUS_INT )
#elif ( FINGERPRINT4_DRV_INTERFACE == FINGERPRINT4_DRV_INTERFACE_UART )
#define FINGERPRINT4_MAP_MIKROBUS( cfg, mikrobus ) \
    cfg.tx_pin = MIKROBUS( mikrobus, MIKROBUS_TX ); \
    cfg.rx_pin = MIKROBUS( mikrobus, MIKROBUS_RX ); \
    cfg.rst  = MIKROBUS( mikrobus, MIKROBUS_RST );
#endif
 
 // fingerprint4_map
 // fingerprint4
 
typedef struct
{
    uint16_t arg;           
    uint16_t size;          
    uint8_t payload[ FINGERPRINT4_ARG_PAYLOAD_MAX_SIZE ];   
} fingerprint4_hcp_arg_data_t;
 
typedef struct
{
    uint16_t cmd_id;        
    uint16_t num_args;      
    uint8_t args[ FINGERPRINT4_ARG_PAYLOAD_MAX_SIZE + 4 ];  
} fingerprint4_hcp_packet_t;
 
typedef struct
{
    uint16_t lnk_chn;       
    uint16_t lnk_size;      
    uint16_t t_size;        
    uint16_t t_seq_nr;      
    uint16_t t_seq_len;     
    fingerprint4_hcp_packet_t hcp_packet;   
    uint32_t crc;           
} fingerprint4_packet_t;
 
typedef struct
{
    // Output pins
    digital_out_t rst;          
#if ( FINGERPRINT4_DRV_INTERFACE == FINGERPRINT4_DRV_INTERFACE_SPI )
    // Input pins
    digital_in_t irq;           
    // Modules
    spi_master_t spi;           
    pin_name_t   chip_select;   
#elif ( FINGERPRINT4_DRV_INTERFACE == FINGERPRINT4_DRV_INTERFACE_UART )
    // Modules
    uart_t uart;                
    // Buffers
    char uart_rx_buffer[ FINGERPRINT4_PHY_MTU_SIZE ]; 
    char uart_tx_buffer[ FINGERPRINT4_PHY_MTU_SIZE ]; 
#endif
    uint32_t phy_rx_timeout;    
    fingerprint4_hcp_arg_data_t arg;    
    fingerprint4_packet_t phy_pkt;      
} fingerprint4_t;
 
typedef struct
{
#if ( FINGERPRINT4_DRV_INTERFACE == FINGERPRINT4_DRV_INTERFACE_SPI )
    // Communication gpio pins    
    pin_name_t miso;            
    pin_name_t mosi;            
    pin_name_t sck;             
    pin_name_t cs;              
    // static variable
    uint32_t                          spi_speed;    
    spi_master_mode_t                 spi_mode;     
    spi_master_chip_select_polarity_t cs_polarity;  
    // Additional gpio pins
    pin_name_t rst;             
    pin_name_t irq;             
#elif ( FINGERPRINT4_DRV_INTERFACE == FINGERPRINT4_DRV_INTERFACE_UART )
    // Communication gpio pins    
    pin_name_t rx_pin;          
    pin_name_t tx_pin;          
    // static variable
    uint32_t         baud_rate;         
    bool             uart_blocking;     
    uart_data_bits_t data_bit;          
    uart_parity_t    parity_bit;        
    uart_stop_bits_t stop_bit;          
    // Additional gpio pins
    pin_name_t rst;             
#endif
 
} fingerprint4_cfg_t;
 
typedef enum
{
    FINGERPRINT4_RES_OK = 0,                        
    FINGERPRINT4_RES_ERROR = -1,                    
    FINGERPRINT4_RES_INTERNAL_ERROR = -2,           
    FINGERPRINT4_RES_INVALID_ARGUMENT = -3,         
    FINGERPRINT4_RES_NOT_IMPLEMENTED = -4,          
    FINGERPRINT4_RES_CANCELLED = -5,                
    FINGERPRINT4_RES_NO_MEMORY = -6,                
    FINGERPRINT4_RES_NO_RESOURCE = -7,              
    FINGERPRINT4_RES_IO_ERROR = -8,                 
    FINGERPRINT4_RES_BROKEN_SENSOR = -9,            
    FINGERPRINT4_RES_WRONG_STATE = -10,             
    FINGERPRINT4_RES_TIMEOUT = -11,                 
    FINGERPRINT4_RES_ID_NOT_UNIQUE = -12,           
    FINGERPRINT4_RES_ID_NOT_FOUND = -13,            
    FINGERPRINT4_RES_INVALID_FORMAT = -14,          
    FINGERPRINT4_RES_IMAGE_CAPTURE_ERROR = -15,     
    FINGERPRINT4_RES_SENSOR_MISMATCH = -16,         
    FINGERPRINT4_RES_INVALID_PARAMETER = -17,       
    FINGERPRINT4_RES_MISSING_TEMPLATE = -18,        
    FINGERPRINT4_RES_INVALID_CALIBRATION = -19,     
    FINGERPRINT4_RES_STORAGE_NOT_FORMATTED = -20,   
    FINGERPRINT4_RES_SENSOR_NOT_INITIALIZED = -21,  
    FINGERPRINT4_RES_TOO_MANY_BAD_IMAGES = -22,     
    FINGERPRINT4_RES_CRYPTO_ERROR = -23,            
    FINGERPRINT4_RES_NOT_SUPPORTED = -24,           
    FINGERPRINT4_RES_FINGER_NOT_STABLE = -25,       
    FINGERPRINT4_RES_NOT_INITIALIZED = -26,         
} fingerprint4_return_value_t;
 
void fingerprint4_cfg_setup ( fingerprint4_cfg_t *cfg );
 
err_t fingerprint4_init ( fingerprint4_t *ctx, fingerprint4_cfg_t *cfg );
 
err_t fingerprint4_generic_write ( fingerprint4_t *ctx, uint8_t *data_in, uint16_t len );
 
err_t fingerprint4_generic_read ( fingerprint4_t *ctx, uint8_t *data_out, uint16_t len );
 
void fingerprint4_set_rst_pin ( fingerprint4_t *ctx, uint8_t state );
 
#if ( FINGERPRINT4_DRV_INTERFACE == FINGERPRINT4_DRV_INTERFACE_SPI )
uint8_t fingerprint4_get_irq_pin ( fingerprint4_t *ctx );
#endif
 
void fingerprint4_reset_device ( fingerprint4_t *ctx );
 
err_t fingerprint4_init_cmd ( fingerprint4_t *ctx, uint16_t cmd, uint16_t arg_key );
 
err_t fingerprint4_add_arg ( fingerprint4_t *ctx, uint16_t arg_key, void *arg_data, uint16_t arg_size );
 
err_t fingerprint4_get_arg ( fingerprint4_t *ctx, uint16_t arg_key );
 
err_t fingerprint4_copy_arg ( fingerprint4_t *ctx, uint16_t arg_key, void *arg_data, uint16_t arg_size );
 
err_t fingerprint4_transceive ( fingerprint4_t *ctx );
 
err_t fingerprint4_receive ( fingerprint4_t *ctx );
 
err_t fingerprint4_send ( fingerprint4_t *ctx );
 
err_t fingerprint4_send_cmd ( fingerprint4_t *ctx, uint16_t cmd, uint16_t arg_key );
 
err_t fingerprint4_send_cmd_arg ( fingerprint4_t *ctx, uint16_t cmd, uint16_t arg1_key, 
                                  uint16_t arg2_key, void *arg2_data, uint16_t arg2_length );
 
err_t fingerprint4_identify_finger ( fingerprint4_t *ctx, uint32_t timeout, uint16_t *template_id, bool *match );
 
err_t fingerprint4_wait_finger_present ( fingerprint4_t *ctx, uint32_t timeout );
 
err_t fingerprint4_wait_finger_not_present ( fingerprint4_t *ctx, uint32_t timeout );
 
err_t fingerprint4_image_get_size ( fingerprint4_t *ctx, uint32_t *size );
 
err_t fingerprint4_image_create ( fingerprint4_t *ctx );
 
err_t fingerprint4_image_delete ( fingerprint4_t *ctx );
 
err_t fingerprint4_image_get ( fingerprint4_t *ctx, uint8_t *data_out, uint32_t size );
 
err_t fingerprint4_image_put ( fingerprint4_t *ctx, uint8_t *data_in, uint32_t size );
 
err_t fingerprint4_image_extract ( fingerprint4_t *ctx );
 
err_t fingerprint4_identify ( fingerprint4_t *ctx );
 
err_t fingerprint4_template_save ( fingerprint4_t *ctx, uint16_t template_id );
 
err_t fingerprint4_template_remove_ram ( fingerprint4_t *ctx );
 
err_t fingerprint4_template_get ( fingerprint4_t *ctx, uint8_t *data_out, uint32_t size );
 
err_t fingerprint4_template_put ( fingerprint4_t *ctx, uint8_t *data_in, uint16_t size );
 
err_t fingerprint4_template_remove ( fingerprint4_t *ctx, uint16_t template_id );
 
err_t fingerprint4_template_remove_all ( fingerprint4_t *ctx );
 
err_t fingerprint4_template_load_storage ( fingerprint4_t *ctx, uint16_t template_id );
 
err_t fingerprint4_template_get_count ( fingerprint4_t *ctx, uint16_t *count );
 
err_t fingerprint4_template_get_ids ( fingerprint4_t *ctx );
 
err_t fingerprint4_sw_reset ( fingerprint4_t *ctx );
 
err_t fingerprint4_sensor_calibrate ( fingerprint4_t *ctx );
 
err_t fingerprint4_sensor_calibrate_remove ( fingerprint4_t *ctx );
 
err_t fingerprint4_version ( fingerprint4_t *ctx, char *version, uint8_t len );
 
err_t fingerprint4_unique_id_get ( fingerprint4_t *ctx, uint8_t *unique_id );
 
err_t fingerprint4_uart_speed_set ( fingerprint4_t *ctx, uint32_t speed );
 
err_t fingerprint4_uart_speed_get ( fingerprint4_t *ctx, uint32_t *speed );
 
err_t fingerprint4_sensor_reset ( fingerprint4_t *ctx );
 
#ifdef __cplusplus
}
#endif
#endif // FINGERPRINT4_H
 
 // fingerprint4
 
// ------------------------------------------------------------------------ END