unit_FPC1xxx.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_FINGER_UNIT_FPC1XXX_HPP
#define M5_UNIT_FINGER_UNIT_FPC1XXX_HPP
 
#include <M5UnitComponent.hpp>
#include <array>
#include <vector>
 
namespace m5 {
namespace unit {
namespace fpc1xxx {
 
enum class ACK : uint8_t {
    Success,           
    Fail,              
    Full = 0x04,       
    NoUser,            
    Occupied,          
    ExistUser = 0x07,  
    Timeout,           
};
 
enum class BaudRate : uint8_t {
    Baud9600 = 1,  
    Baud19200,     
    Baud38400,     
    Baud57600,     
    Baud115200,    
};
 
enum class Mode : uint8_t {
    AllowDuplicate,     
    ProhibitDuplicate,  
};
 
struct User {
    User(const uint16_t i, const uint8_t p) : id{i}, permission{p}
    {
    }
    uint16_t id{};         
    uint8_t permission{};  
};
 
}  // namespace fpc1xxx
 
class UnitFPC1XXX : public Component {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitFPC1XXX, 0x00);
 
public:
    // The following variables must be defined in the derived class
    static constexpr uint16_t RESOLUTION_WIDTH{0};
    static constexpr uint16_t RESOLUTION_HEIGHT{0};
    static constexpr uint16_t MINIMUM_USER_ID{0};
    static constexpr uint16_t MAXIMUM_USER_ID{0};
 
protected:
    UnitFPC1XXX() : Component(DEFAULT_ADDRESS)
    {
    }
 
public:
    using Frame         = std::array<uint8_t, 8>;  //    0xF5 CMD P1 P2 P3 0 CHK 0xF5
    using VariableFrame = std::vector<uint8_t>;    //    0xF5 CMD LEN(MSB) LEN(LSB) 0 0 CHK 0xF5,...
 
    virtual ~UnitFPC1XXX() = default;
 
    virtual bool begin() override;
 
    struct config_t {
        uint32_t timeout_ms{1000 * 4};  
    };
 
 
    inline config_t config()
    {
        return _cfg;
    }
    inline void config(const config_t& cfg)
    {
        _cfg = cfg;
    }
 
    inline virtual uint16_t resolutionWidth() const
    {
        return 0;
    }
    inline virtual uint16_t resolutionHeight() const
    {
        return 0;
    }
    inline uint16_t imageWidth(const bool raw) const
    {
        return resolutionWidth() >> (raw ? 0 : 1);
    }
    inline uint16_t imageHeight(const bool raw) const
    {
        return resolutionHeight() >> (raw ? 0 : 1);
    }
    inline virtual uint16_t minimumUserID() const
    {
        return MINIMUM_USER_ID;
    }
    inline virtual uint16_t maximumUserID() const
    {
        return MAXIMUM_USER_ID;
    }
 
 
    bool readRegistrationMode(fpc1xxx::Mode& mode);
    bool writeRegistrationMode(const fpc1xxx::Mode mode);
    bool readComparisonLevel(uint8_t& lv);
    bool writeComparisonLevel(const uint8_t lv);
    bool writeBaudRate(const fpc1xxx::BaudRate baud);
    bool readTimeout(uint8_t& timeout);
    bool writeTimeout(const uint8_t timeout);
 
 
    bool readRegisteredUserCount(uint16_t& count);
    bool readUser(uint8_t& permission, const uint16_t user_id);
    bool readAllUser(std::vector<fpc1xxx::User>& v);
    bool readUserCharacteristic(uint8_t characteristic[193], const uint16_t user_id);
    bool findAvailableUserID(uint16_t& user_id, const uint16_t low = 0, const uint16_t high = 0);
    bool deleteUser(const uint16_t user_id);
    bool deleteAllUsers();
 
 
    bool registerFinger(const uint16_t user_id, const uint8_t permission, const uint8_t step = 4);
    bool verifyFinger(bool& match, const uint16_t user_id);
    bool identifyFinger(uint16_t& user_id, uint8_t& permission);
    bool scanCharacteristic(uint8_t characteristic[193]);
    inline virtual bool captureImage(std::vector<uint8_t>& img, const bool raw = false)
    {
        return capture_image(img, raw);
    }
    bool registerCharacteristic(const uint16_t user_id, const uint8_t permission, const uint8_t characteristic[193]);
    bool verifyCharacteristic(bool& match, const uint16_t user_id, const uint8_t characteristic[193]);
    bool identifyCharacteristic(uint16_t& user_id, const uint8_t characteristic[193]);
    bool compareCharacteristic(bool& match, const uint8_t characteristic[193]);
 
    bool readSerialNumber(uint32_t& no);
    bool readVersion(char str[9]);
 
    bool sleep(void);
 
protected:
    inline bool is_valid_user_id(const uint16_t user_id) const
    {
        return user_id >= minimumUserID() && user_id <= maximumUserID();
    }
    bool transceive_command(Frame& res, const uint8_t cmd, const uint8_t p1 = 0, const uint8_t p2 = 0,
                            const uint8_t p3 = 0);
    bool capture_image(std::vector<uint8_t>& img, const bool full = false);
 
private:
    config_t _cfg{};
};
 
class UnitFPC1020A : public UnitFPC1XXX {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitFPC1020A, 0x00);
 
public:
    static constexpr uint16_t RESOLUTION_WIDTH{160};
    static constexpr uint16_t RESOLUTION_HEIGHT{160};
    static constexpr uint16_t MINIMUM_USER_ID{1};
    static constexpr uint16_t MAXIMUM_USER_ID{150};
 
    UnitFPC1020A() : UnitFPC1XXX()
    {
    }
    virtual ~UnitFPC1020A() = default;
 
    virtual bool begin() override;
 
    inline virtual uint16_t resolutionWidth() const override
    {
        return this->RESOLUTION_WIDTH;
    }
    inline virtual uint16_t resolutionHeight() const override
    {
        return this->RESOLUTION_HEIGHT;
    }
    inline virtual uint16_t minimumUserID() const override
    {
        return MINIMUM_USER_ID;
    }
    inline virtual uint16_t maximumUserID() const override
    {
        return MAXIMUM_USER_ID;
    }
};
 
namespace fpc1xxx {
namespace command {
 
constexpr uint8_t CMD_REGISTER_FINGER_FIRST{0x01};
constexpr uint8_t CMD_REGISTER_FINGER_STEP{0x02};
constexpr uint8_t CMD_REGISTER_FINGER_LAST{0x03};
constexpr uint8_t CMD_VERIFY_FINGER{0x0B};
constexpr uint8_t CMD_IDENTIFY_FINGER{0x0C};
 
constexpr uint8_t CMD_DELETE_USER{0x04};
constexpr uint8_t CMD_DELETE_ALL_USERS{0x05};
constexpr uint8_t CMD_READ_REGISTERED_USER_COUNT{0x09};
constexpr uint8_t CMD_READ_USER_PERMISSION{0x0A};
constexpr uint8_t CMD_READ_ALL_USER_DATA{0x2B};
constexpr uint8_t CMD_FIND_UNREGISTERD_USER_ID{0x47};
 
constexpr uint8_t CMD_BAUD_RATE{0x21};
constexpr uint8_t CMD_READ_VERSION{0x26};
constexpr uint8_t CMD_COMPARISON_LEVEL{0x28};
constexpr uint8_t CMD_REGISTRATION_MODE{0x2D};
constexpr uint8_t CMD_TIMEOUT{0x2E};
constexpr uint8_t CMD_READ_SERIAL_NO{0x2A};
 
constexpr uint8_t CMD_SLEEP{0x2C};
 
constexpr uint8_t CMD_CAPTURE_IMAGE{0x24};
 
constexpr uint8_t CMD_SCAN_CHARACTERISTIC{0x23};
constexpr uint8_t CMD_READ_USER_CHARACTERISTIC{0x31};
constexpr uint8_t CMD_REGISTER_CHARACTERISTIC{0x41};
constexpr uint8_t CMD_VERIFY_CHARACTERISTIC{0x42};
constexpr uint8_t CMD_IDENTIFY_CHARACTERISTIC{0x43};
constexpr uint8_t CMD_COMPARE_CHARACTERISTIC{0x44};
 
}  // namespace command
namespace detail {
using Frame = UnitFPC1XXX::Frame;
 
constexpr uint8_t MARKER{0xF5};  
 
uint8_t xorSum(const uint8_t* data, const uint16_t len);
bool is_valid_sum(const Frame response, const bool check_marker = true);
bool is_valid_payload(const uint8_t* data, const uint16_t len);
}  // namespace detail
 
}  // namespace fpc1xxx
 
}  // namespace unit
}  // namespace m5
 
#endif