unit_Finger2.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_FINGER_UNIT_FINGER2_HPP
#define M5_UNIT_FINGER_UNIT_FINGER2_HPP
 
#include <M5UnitComponent.hpp>
#include <vector>
#include <array>
 
namespace m5 {
namespace unit {
namespace finger2 {
 
enum class WorkMode : uint8_t {
    ScheduledSleep,  
    AlwaysActive,    
};
 
enum class LEDMode : uint8_t {
    None,             
    Breath,           
    Blink,            
    On,               
    Off,              
    Fadein,           
    Fadeout,          
    Rainbow,          
    Bleath = Breath,  
};
 
enum class LEDColor : uint8_t {
    Black,    
    Blue,     
    Green,    
    Cyan,     
    Red,      
    Magenta,  
    Yellow,   
    White     
};
 
enum class RegisterID : uint8_t {
    PacketSize = 6,  
};
 
struct SystemBasicParams {
    uint16_t status{};             
    uint16_t sensor_type{};        
    uint16_t database_capacity{};  
    uint16_t score_level{};        
    uint32_t address{};            
    uint16_t packet_size{};        
    uint16_t baud_rate{};          
} __attribute__((packed));
 
using auto_enroll_flag_t   = uint16_t;  
using auto_identify_flag_t = uint16_t;  
 
namespace auto_enroll_flag {
constexpr auto_enroll_flag_t DONT_RETURN_INTERMEDIATE_RESULTS{1U << 2};  
constexpr auto_enroll_flag_t ALLOW_OVERWRITE_PAGE{1U << 3};              
constexpr auto_enroll_flag_t PROHIBIT_DUPLICATE_TEMPLATE{1U << 4};       
constexpr auto_enroll_flag_t NO_NEED_RELEASE_FINGER{1U << 5};            
 
[[deprecated("use NO_NEED_RELEASE_FINGER")]] constexpr auto_enroll_flag_t NO_NEED_RELAESE_FINGER =
    NO_NEED_RELEASE_FINGER;
 
}  // namespace auto_enroll_flag
 
namespace auto_identify_flag {
constexpr auto_identify_flag_t DONT_RETURN_INTERMEDIATE_RESULTS{1U << 2};  
}  // namespace auto_identify_flag
 
enum class AutoEnrollStage : uint8_t {
    VerifyCommand,           
    GetImage,                
    GenerateCharacteristic,  
    ReleasedFinger,          
    MergeTemplate,           
    Inspection,              
    StoreTemplate,           
};
 
enum class AutoIdentifyStage : uint8_t {
    VerifyCommand,  
    GetImage,       
    Result = 0x05,  
};
 
enum class ConfirmCode : uint8_t {
    OK,                  
    PacketError,         
    NoFinger,            
    ImageFailed,         
    ImageTooDry,         
    ImageTooHumid,       
    ImageTooAmorphous,   
    ImageTooFew,         
    Unmatched,           
    NotFound,            
    MergeFailed,         
    AddressOverflow,     
    ReadTemplateFailed,  
    UploadFailed,        
    ReceiveFailed,       
    UploadImageFailed,   
    DeleteFailed,        
    ClearFailed,         
    LowPowerFailed,      
    PasswordIncorrect,   
    ResetFailed,         
    ResettFailed = ResetFailed,  
    NoValidImage,                
    UpgradeFailed,               
    IncompleteFinger,      
    FlashError,            
    RandomError,           
    InvalidRegister,       
    RegisterError,         
    NotepadPageError,      
    PortError,             
    AutoEnrollFailed,      
    DatabaseFull,          
    IncorrectAddress,      
    VerifyPassword,        
    TemplateNotEmpty,      
    TemplateEmpty,         
    DatabaseEmpty,         
    IncorrectEnrollCount,  
    Timeout,               
    AlreadyExists,         
    FeatureAssociated,     
    InitializeFailed,      
    initializeFailed = InitializeFailed,  
    InformationNotEmpty,                  
    InformationEmpty,                     
    OTPFailed,                            
    KeyGenerateFailed,                    
    KeyNotExist,                          
    AlgorithmFailed,                      
    IncorrectResult,           
    MismatchFunction,          
    KeyLocked,                 
    SmallImage,                
    StaticObjectInImage,       
    IllegalData,               
    PacketTimeout = 0xF9,      
    PacketBad,                 
    PacketOverflow,            
    OperationBlocked,          
    ParameterError,            
    NotActive,                 
    PassiveActivation = 0xFF,  
};
 
using auto_enroll_callback_t = bool (*)(const uint16_t call_times, const uint16_t page_id, const ConfirmCode confirm,
                                        const AutoEnrollStage stage, const uint8_t state);
using auto_identify_callback_t = bool (*)(const uint16_t call_times, const ConfirmCode confirm,
                                          const AutoIdentifyStage stage);
 
using batch_callback_t = bool (*)(const uint16_t call_times, const uint16_t actual_size, const uint16_t batch_size,
                                  const uint16_t total_size, const uint16_t planned_size, const bool completed);
 
}  // namespace finger2
 
class UnitFinger2 : public Component {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitFinger2, 0x00);
 
public:
    static constexpr uint32_t DEFAULT_MODULE_ADDRESS{0xFFFFFFFF};  
    using Packet = std::vector<uint8_t>;
 
    static constexpr uint16_t IMAGE_WIDTH{80};      
    static constexpr uint16_t IMAGE_HEIGHT{208};    
    static constexpr uint16_t TEMPLATE_SIZE{7262};  
 
protected:
    explicit UnitFinger2(const uint32_t device_address) : Component(DEFAULT_ADDRESS), _address{device_address}
    {
    }
 
public:
    UnitFinger2() : UnitFinger2(DEFAULT_MODULE_ADDRESS)
    {
    }
 
    virtual ~UnitFinger2() = default;
 
    virtual bool begin() override;
 
    struct config_t {
        uint32_t timeout_ms{1000 * 4};                                   
        finger2::WorkMode work_mode{finger2::WorkMode::ScheduledSleep};  
        uint8_t sleep_time{10};                                          
    };
 
 
    inline config_t config()
    {
        return _cfg;
    }
    inline void config(const config_t& cfg)
    {
        _cfg = cfg;
    }
 
 
    uint32_t deviceAddress() const
    {
        return _address;
    }
    inline constexpr uint16_t imageWidth() const
    {
        return IMAGE_WIDTH;
    }
    inline constexpr uint16_t imageHeight() const
    {
        return IMAGE_HEIGHT;
    }
    inline uint16_t capacity() const
    {
        return _pageCapacity;
    }
 
    bool readModuleStatus(bool& awake);
 
    bool wakeup();
 
 
    bool readWorkMode(finger2::WorkMode& wm);
    bool writeWorkMode(const finger2::WorkMode wm);
    bool saveWorkMode();
 
    bool readSleepTime(uint8_t& sec);
    bool writeSleepTime(const uint8_t sec);
    bool saveSleepTime();
 
    bool readSystemParams(finger2::SystemBasicParams& params);
 
    bool writeSystemRegister(const finger2::RegisterID reg_id, const uint8_t value);
 
    bool writeControlLED(const finger2::LEDMode mode, const finger2::LEDColor clr, const uint8_t cycle = 0,
                         const finger2::LEDColor eclr = finger2::LEDColor::Black);
 
    bool writeControlLEDRainbow(const uint8_t tm, const finger2::LEDColor* colors, const uint8_t colors_num,
                                const uint8_t cycle);
 
 
    bool capture(bool& detected, const bool enroll = false);
 
    bool readImageInformation(uint8_t& percentage, bool& quality);
 
    bool readImage(std::vector<uint8_t>& img);
 
    bool generateCharacteristic(const uint8_t buffer_id = 1);
 
    bool generateTemplate();
 
    bool storeTemplate(const uint16_t page_id, const uint8_t buffer_id = 1);
 
    bool match(bool& matched, uint16_t& score);
 
    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);
 
    bool searchNow(bool& matched, uint16_t& matching_page_id, uint16_t& score, const uint16_t start_page = 0,
                   const uint16_t page_num = 0);
 
 
 
    bool loadTemplate(const uint8_t buffer_id, const uint16_t page_id);
 
    bool readTemplate(uint16_t& actual_size, uint8_t* buf, const uint16_t buf_size, const uint16_t 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);
    bool writeTemplate(const uint16_t offset, const uint8_t* buf, const uint16_t buf_size);
    bool writeTemplateAllBatches(const uint8_t* buf, const uint16_t buf_size, const uint16_t batch_size = 128,
                                 finger2::batch_callback_t callback = nullptr);
 
    bool deleteTemplate(const uint16_t page_id, const uint16_t num = 1);
 
    bool clear();
 
    bool readValidTemplates(uint16_t& num);
 
    bool readIndexTable(uint8_t table[32]);
 
    bool existsTemplate(const uint16_t page_id);
 
    bool findLowestAvailablePage(uint16_t& page);
 
    bool findHighestAvailablePage(uint16_t& page);
 
 
    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);
 
    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);
 
    bool cancel();
 
 
    bool readNotepad(uint8_t buf[32], const uint8_t page);
    bool writeNotepad(const uint8_t page, const uint8_t* buf, const uint8_t len);
 
    bool readInformationPage(uint8_t info[512]);
 
    bool readRandomNumber(uint32_t& value);
 
    bool handshake(bool& status);
    bool checkSensor(bool& status);
 
    bool readSerialNumber(uint8_t sn[32]);
 
    bool readFirmwareVersion(uint8_t& ver);
 
protected:
    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);
 
private:
    config_t _cfg{};
    uint32_t _address{};
    uint16_t _pageCapacity{};
};
 
namespace finger2 {
namespace command {
constexpr uint8_t CMD_GET_IMAGE{0x01};
constexpr uint8_t CMD_GET_ENROLL_IMAGE{0x29};
constexpr uint8_t CMD_GENERATE_CHARACTERISTIC{0x02};
constexpr uint8_t CMD_MATCH{0x03};
constexpr uint8_t CMD_SEARCH{0x04};
constexpr uint8_t CMD_SEARCH_NOW{0x3E};
constexpr uint8_t CMD_REGISTER_MODEL{0x05};
constexpr uint8_t CMD_STORE_TEMPLATE{0x06};
constexpr uint8_t CMD_LOAD_TEMPLATE{0x07};
 
constexpr uint8_t CMD_UPLOAD_IMAGE{0x0A};
constexpr uint8_t CMD_DELETE_TEMPLATE{0x0C};
constexpr uint8_t CMD_EMPTY{0x0D};
 
constexpr uint8_t CMD_WRITE_REGISTER{0x0E};
constexpr uint8_t CMD_READ_SYSTEM_PARAMETER{0x0F};
constexpr uint8_t CMD_GET_RANDOM{0x14};
constexpr uint8_t CMD_READ_FLASH_INFORMATION{0x16};
constexpr uint8_t CMD_WRITE_NOTEPAD{0x18};
constexpr uint8_t CMD_READ_NOTEPAD{0x19};
 
constexpr uint8_t CMD_READ_VALID_TEMPLATE_NUMBER{0x1D};
constexpr uint8_t CMD_READ_INDEX_TABLE{0x1F};
 
constexpr uint8_t CMD_CANCEL{0x30};
constexpr uint8_t CMD_AUTO_ENROLL{0x31};
constexpr uint8_t CMD_AUTO_IDENTIFY{0x32};
 
constexpr uint8_t CMD_GET_SERIAL{0x34};
constexpr uint8_t CMD_HANDSHAKE{0x35};
constexpr uint8_t CMD_CHECK_SENSOR{0x36};
constexpr uint8_t CMD_CONTROL_BLN{0x3C};
constexpr uint8_t CMD_GET_IMAGE_INFORMATION{0x3D};
 
constexpr uint8_t CMD_UPLOAD_TEMPLATE{0x7A};
constexpr uint8_t CMD_DOWNLOAD_TEMPLATE{0x7B};
 
constexpr uint8_t CMD_SET_SLEEP_TIME{0xD0};
constexpr uint8_t CMD_GET_SLEEP_TIME{0xD1};
constexpr uint8_t CMD_SET_WORK_MODE{0xD2};
constexpr uint8_t CMD_GET_WORK_MODE{0xD3};
constexpr uint8_t CMD_ACTIVATE_MODULE{0xD4};
constexpr uint8_t CMD_GET_MODULE_STATUS{0xD5};
constexpr uint8_t CMD_SAVE_CONFIGURATION{0xD6};
constexpr uint8_t CMD_GET_FIRMWARE_VERSION{0xD7};
}  // namespace command
}  // namespace finger2
 
}  // namespace unit
}  // namespace m5
#endif