nfc_layer_a.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_NFC_NFC_LAYER_NFC_LAYER_A_HPP
#define M5_UNIT_NFC_NFC_LAYER_NFC_LAYER_A_HPP
 
#include "nfc/layer/nfc_layer.hpp"
#include "nfc/a/nfca.hpp"
#include "nfc/isoDEP/isoDEP.hpp"
#include "nfc/layer/ndef_layer.hpp"
#include "nfc/ndef/ndef.hpp"
#include <vector>
#include <memory>
 
namespace m5 {
 
namespace unit {
class UnitMFRC522;  // M5Unit-RFID
class UnitWS1850S;  // M5Unit-RFID
class UnitST25R3916;
class CapST25R3916;
}  // namespace unit
 
namespace nfc {
 
class NFCLayerA : public m5::nfc::NFCLayerInterface {
public:
    struct Adapter;
    explicit NFCLayerA(m5::unit::UnitMFRC522& u);  // The implementation of this function is located in M5Unit-RFID
    explicit NFCLayerA(m5::unit::UnitWS1850S& u);  // The implementation of this function is located in M5Unit-RFID
    explicit NFCLayerA(m5::unit::UnitST25R3916& u);
    explicit NFCLayerA(m5::unit::CapST25R3916& u);
    virtual ~NFCLayerA();
 
 
    virtual bool transceive(uint8_t* rx, uint16_t& rx_len, const uint8_t* tx, const uint16_t tx_len,
                            const uint32_t timeout_ms) override;
    // virtual bool transmit(const uint8_t* tx, const uint16_t tx_len, const uint32_t timeout_ms) override;
    // virtual bool receive(uint8_t* rx, uint16_t& rx_len, const uint32_t timeout_ms) override;
    virtual m5::nfc::NFCForumTag supportsNFCTag() const override;
    virtual file_system_feature_t supportsFilesystem() const override;
    virtual m5::nfc::isodep::IsoDEP* isoDEP() override
    {
        return &_isoDEP;
    }
    virtual uint16_t maximum_fifo_depth() const override;
 
    inline bool isActive(const m5::nfc::a::PICC& picc) const
    {
        return _activePICC.valid() && _activePICC == picc;
    }
    const m5::nfc::a::PICC& activatedPICC() const
    {
        return _activePICC;
    }
    inline m5::nfc::a::config_t config() const
    {
        return _cfg;
    }
    void config(const m5::nfc::a::config_t& cfg);
 
 
    bool request(uint16_t& atqa);
    bool wakeup(uint16_t& atqa);
 
    bool detect(m5::nfc::a::PICC& picc, const uint32_t timeout_ms = 100U);
    bool detect(std::vector<m5::nfc::a::PICC>& piccs, const uint32_t timeout_ms = 1000U);
    bool select(m5::nfc::a::PICC& picc);
    bool activate(const m5::nfc::a::PICC& picc, const bool force_rats = false);
    bool reactivate(const m5::nfc::a::PICC& picc, const bool force_rats = false);
    inline bool reactivate()
    {
        return reactivate(_activePICC);
    }
 
 
    bool deactivate();
 
    bool identify(m5::nfc::a::PICC& picc);
 
    bool read4(uint8_t rx[4], const uint8_t addr);
    bool read16(uint8_t rx[16], const uint8_t addr);
    bool read(uint8_t* rx, uint16_t& rx_len, const uint8_t saddr,
              const m5::nfc::a::mifare::classic::Key& key = m5::nfc::a::mifare::classic::DEFAULT_KEY);
    bool read(uint8_t* rx, uint16_t& rx_len, const uint8_t saddr, const m5::nfc::a::mifare::plus::AESKey& key);
 
    bool write4(const uint8_t addr, const uint8_t* tx, const uint16_t tx_len, const bool safety = true);
    bool write16(const uint8_t addr, const uint8_t* tx, const uint16_t tx_len, const bool safety = true);
    bool write(const uint8_t saddr, const uint8_t* tx, const uint16_t tx_len,
               const m5::nfc::a::mifare::classic::Key& key = m5::nfc::a::mifare::classic::DEFAULT_KEY);
    bool write(const uint8_t addr, const uint8_t* tx, const uint16_t tx_len,
               const m5::nfc::a::mifare::plus::AESKey& key);
 
    bool dump(const m5::nfc::a::mifare::classic::Key& mkey = m5::nfc::a::mifare::classic::DEFAULT_KEY);
    bool dump(const uint8_t block);
 
 
    bool mifareClassicAuthenticateA(
        const uint8_t block, const m5::nfc::a::mifare::classic::Key& key = m5::nfc::a::mifare::classic::DEFAULT_KEY);
    bool mifareClassicAuthenticateB(
        const uint8_t block, const m5::nfc::a::mifare::classic::Key& key = m5::nfc::a::mifare::classic::DEFAULT_KEY);
 
    bool mifareClassicReadAccessCondition(uint8_t& c123, const uint8_t block);
    bool mifareClassicWriteAccessCondition(const uint8_t block, const uint8_t c123,
                                           const m5::nfc::a::mifare::classic::Key& akey,
                                           const m5::nfc::a::mifare::classic::Key& bkey);
 
    bool mifareClassicIsValueBlock(bool& is_value_block, const uint8_t block);
    bool mifareClassicReadValueBlock(int32_t& value, const uint8_t block);
    bool mifareClassicWriteValueBlock(const uint8_t block, const int32_t value);
    bool mifareClassicDecrementValueBlock(const uint8_t block, const uint32_t delta, const bool transfer = true);
    bool mifareClassicIncrementValueBlock(const uint8_t block, const uint32_t delta, const bool transfer = true);
    bool mifareClassicTransferValueBlock(const uint8_t block);
    bool mifareClassicRestoreValueBlock(const uint8_t block);
 
 
    bool mifareUltralightChangeFormatToNDEF();
 
 
    bool mifareUltralightCAuthenticate(const uint8_t key[16]);
 
 
    bool mifarePlusUpgradeSecurityLevel1(
        const m5::nfc::a::mifare::plus::AESKey& card_config_key = m5::nfc::a::mifare::plus::DEFAULT_KEY,
        const m5::nfc::a::mifare::plus::AESKey& card_master_key = m5::nfc::a::mifare::plus::DEFAULT_KEY,
        const m5::nfc::a::mifare::plus::AESKey& l2_switch_key   = m5::nfc::a::mifare::plus::DEFAULT_KEY,
        const m5::nfc::a::mifare::plus::AESKey& l3_switch_key   = m5::nfc::a::mifare::plus::DEFAULT_KEY,
        const m5::nfc::a::mifare::plus::AESKey& aes_sector_key  = m5::nfc::a::mifare::plus::DEFAULT_FF_KEY,
        const m5::nfc::a::mifare::classic::Key& key_a           = m5::nfc::a::mifare::classic::DEFAULT_KEY,
        const m5::nfc::a::mifare::classic::Key& key_b           = m5::nfc::a::mifare::classic::DEFAULT_KEY);
    bool mifarePlusUpgradeSecurityLevel2(
        const m5::nfc::a::mifare::plus::AESKey& sl2_switch_key = m5::nfc::a::mifare::plus::DEFAULT_KEY);
    bool mifarePlusUpgradeSecurityLevel3(
        const m5::nfc::a::mifare::plus::AESKey& l3_switch_key = m5::nfc::a::mifare::plus::DEFAULT_KEY);
 
 
 
    bool ndefIsValidFormat(bool& valid);
    bool ndefPrepareDesfireLight();
    bool ndefPrepareDesfire(const uint32_t max_ndef_size);
    bool ndefRead(m5::nfc::ndef::TLV& msg);
    bool ndefRead(std::vector<m5::nfc::ndef::TLV>& tlvs,
                  const m5::nfc::ndef::TagBits tagBits = m5::nfc::ndef::tagBitsAll);
    bool ndefWrite(const m5::nfc::ndef::TLV& msg);
    bool ndefWrite(const std::vector<m5::nfc::ndef::TLV>& tlvs);
 
protected:
    virtual bool read(uint8_t* rx, uint16_t& rx_len, const uint16_t saddr) override;
    virtual bool write(const uint16_t saddr, const uint8_t* tx, const uint16_t tx_len) override;
    inline virtual uint16_t first_user_block() const override
    {
        return _activePICC.firstUserBlock();
    }
    inline virtual uint16_t last_user_block() const override
    {
        return _activePICC.lastUserBlock();
    }
    inline virtual uint16_t user_area_size() const override
    {
        return _activePICC.userAreaSize();
    }
    inline virtual uint16_t unit_size_read() const override
    {
        return _activePICC.supportsNFC() ? (_activePICC.isMifareUltralight() ? 16 : 4) : 16;
    }
    inline virtual uint16_t unit_size_write() const override
    {
        return (_activePICC.supportsNFC()) ? 4 : 16;
    }
 
    bool identify_picc(m5::nfc::a::PICC& picc);
    m5::nfc::a::Type identify_picc_st25ta();
    uint8_t identify_plus_sl03();
 
    bool read_using_fast(uint8_t* rx, uint16_t& rx_len, const uint8_t saddr);
    bool read_using_read16(uint8_t* rx, uint16_t& rx_len, const uint8_t saddr,
                           const m5::nfc::a::mifare::classic::Key& key);
    bool write_using_write4(const uint8_t addr, const uint8_t* tx, const uint16_t tx_len);
    bool write_using_write16(const uint8_t addr, const uint8_t* tx, const uint16_t tx_len,
                             const m5::nfc::a::mifare::classic::Key& key);
 
    bool nfca_request_ats(m5::nfc::a::ATS& ats, const uint8_t fsdi = 5, const uint8_t cid = 0);
    bool nfca_deselect();
 
    bool mifare_get_version_L3(uint8_t ver[8]);
    bool mifare_get_version_L4_raw(uint8_t* ver, uint16_t& ver_len);
    bool mifare_get_version_L4_wrapped(uint8_t* ver, uint16_t& ver_len);
 
    bool mifare_plus_authenticateAES(const uint16_t key_no, const m5::nfc::a::mifare::plus::AESKey& key);
    bool mifare_plus_authenticateAES_L3(const uint16_t key_no, const m5::nfc::a::mifare::plus::AESKey& key);
    bool mifare_plus_read_plain_nomac(const uint16_t block, const uint8_t count, std::vector<uint8_t>& out);
    bool mifare_plus_read_plain_mac(const uint16_t block, const uint8_t count, std::vector<uint8_t>& out);
    bool mifare_plus_read_mac_l4(const uint16_t block, const uint8_t count, std::vector<uint8_t>& out,
                                 const bool plain);
    bool mifare_plus_write_mac_l4(const uint16_t block, const uint8_t* data, const uint16_t data_len, const bool plain);
 
    bool mifare_classic_value_block(const m5::nfc::a::Command cmd, const uint8_t block, const uint32_t arg = 0);
 
    bool mifare_ultralightC_authenticate1(uint8_t ek[8]);
    bool mifare_ultralightC_authenticate2(uint8_t rx_ek[8], const uint8_t tx_ek[16]);
 
    bool ntag_read_page(uint8_t* rx, uint16_t& rx_len, const uint8_t spage, const uint8_t epage);
    bool ntag_write_page(const uint8_t page, const uint8_t tx[4]);  // NTAG,UL,ULC
 
    bool dump_sector_structure(const m5::nfc::a::PICC& picc, const m5::nfc::a::mifare::classic::Key& key);
    bool dump_sector(const uint8_t sector);
    bool dump_sector_mifare_plus_sl3(const uint8_t sector);
    bool dump_page_structure(const uint16_t maxPage);
    bool dump_page(const uint8_t page, const uint16_t maxPage);
    bool dump_mifare_plus_sl3(const m5::nfc::a::mifare::plus::AESKey& key);
    bool dump_desfire();
    bool dump_desfire_light();
    bool dump_st25ta();
 
    static bool push_back_picc(std::vector<m5::nfc::a::PICC>& v, const m5::nfc::a::PICC& picc);
 
protected:
    m5::nfc::a::PICC _activePICC{};
    m5::nfc::a::config_t _cfg{};
    m5::nfc::ndef::NDEFLayer _ndef;
    m5::nfc::isodep::IsoDEP _isoDEP;
 
private:
    bool mifare_plus_transceive_raw(uint8_t* rx, uint16_t& rx_len, const uint8_t* tx, const uint16_t tx_len);
 
    // Session state for MIFARE Plus
    struct MifarePlusSession {
        bool authenticated{};
        uint16_t key_no{};
        uint16_t r_ctr{};
        uint16_t w_ctr{};
        uint8_t frame_num{};
        std::array<uint8_t, 4> ti{};
        std::array<uint8_t, 16> kenc{};
        std::array<uint8_t, 16> kmac{};
    };
 
    MifarePlusSession _mfp_session{};
    std::unique_ptr<Adapter> _impl;
};
 
// Impl for units
struct NFCLayerA::Adapter {
    virtual ~Adapter() = default;
 
    virtual uint16_t max_fifo_depth() const = 0;
 
    virtual bool transceive(uint8_t* rx, uint16_t& rx_len, const uint8_t* tx, const uint16_t tx_len,
                            const uint32_t timeout_ms) = 0;
 
    virtual bool request(uint16_t& atqa) = 0;
    virtual bool wakeup(uint16_t& atqa)  = 0;
 
    virtual bool select(m5::nfc::a::PICC& picc)         = 0;
    virtual bool activate(const m5::nfc::a::PICC& picc) = 0;
    virtual bool hlt()                                  = 0;
 
    virtual bool nfca_read_block(uint8_t rx[16], const uint8_t addr)                      = 0;
    virtual bool nfca_write_block(const uint8_t addr, const uint8_t tx[16])               = 0;
    virtual bool mifare_classic_authenticate(const bool auth_a, const m5::nfc::a::PICC& picc, const uint8_t block,
                                             const m5::nfc::a::mifare::classic::Key& key) = 0;
    virtual bool mifare_classic_value_block(const m5::nfc::a::Command cmd, const uint8_t block,
                                            const uint32_t arg = 0)                       = 0;
};
 
}  // namespace nfc
}  // namespace m5
 
#endif