uhf_layer.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_RFID_UHF_UHF_LAYER_HPP
#define M5_UNIT_RFID_UHF_UHF_LAYER_HPP
 
#include "uhf.hpp"
#include "unit/unit_UHFRFID.hpp"
 
namespace m5 {
namespace uhf {
 
using Result = m5::stl::expected<void, Reason>;
 
class UHFLayer {
public:
    explicit UHFLayer(m5::unit::UHFRFIDComponent& u) : _u{u}
    {
    }
    UHFLayer(const UHFLayer&) = delete;
    UHFLayer& operator=(const UHFLayer&) = delete;
 
 
    bool detect(std::vector<Tag>& tags, const uint32_t timeout_ms = 1000U);
    bool detect(Tag& tag, const uint32_t timeout_ms = 500U);
 
 
    bool select(const Tag& tag, const uint32_t access_password = 0, const bool verify = true);
    bool select(const Epc& epc, const uint32_t access_password = 0, const bool verify = true);
    bool select(const Tid& tid, const uint32_t access_password = 0, const bool verify = true);
    bool deselect();
    inline bool isSelected() const
    {
        return _has_selection;
    }
    inline const Tag& selectedTag() const
    {
        return _selected;
    }
    bool identify(Tag& tag);
 
 
    bool dump();
    bool dump(const Bank bank);
    bool dump(const Bank bank, const uint16_t word_address, const uint16_t words);
 
 
    Result readBank(std::vector<uint8_t>& out, const Bank bank, const uint16_t word_address, const uint16_t word_count);
    Result readBank(uint8_t* out, uint16_t& out_len, const Bank bank, const uint16_t word_address,
                    const uint16_t word_count);
    Result writeBank(const Bank bank, const uint16_t word_address, const uint8_t* data, const uint16_t data_len);
    Result lock(const std::vector<LockSetting>& settings, const bool allow_permanent = false);
    Result kill(const Tag& tag, const uint32_t kill_password);
    Result readBlockPermalock(std::vector<uint8_t>& mask, const Bank bank, const uint16_t block_pointer = 0,
                              const uint8_t block_range = 1);
    Result blockPermalock(const Bank bank, const uint8_t* mask, const size_t mask_len, const bool allow_permanent,
                          const uint16_t block_pointer = 0, const uint8_t block_range = 1);
    Result readQTParameters(QTParameters& qt);
    Result writeQTParameters(const QTParameters& qt, const bool persistent = false);
    Result readNxpConfigWord(uint16_t& config);
    Result toggleNxpConfigWord(uint16_t& config, const uint16_t toggle);
    Result writeNxpEAS(const bool enable);
    bool nxpEASAlarm(std::vector<uint8_t>& alarm);
    Result nxpReadProtect(const bool protect);
 
private:
    // Store a mask, switch the module over to it, and optionally prove a tag answers
    bool apply_selection(const Bank bank, const uint32_t pointer_bits, const uint8_t* mask, const size_t mask_len,
                         const uint32_t access_password, const bool verify);
    // Read one word of the EPC bank to prove the selected tag is there and answering
    bool verify_selection();
    // Drop the selection when a write has replaced the bytes its mask matches on
    void drop_selection_if_mask_rewritten(const Bank bank);
    // Store the mask of the selected tag again, so a lost singulation can be regained
    bool reapply_selection();
    // How many words of a bank there are to read, 0 when that is not known
    uint16_t bank_words(const Bank bank);
    // Print a stretch of one bank, sixteen bytes to a line
    bool dump_words(const char* what, const Bank bank, const uint16_t word_address, const uint16_t words);
    /*
      Pass on a reader's failure in terms the caller can act on
      @param result What the reader answered
      @return The same success, or what its error code means
     */
    Result relay(const m5::unit::TagResult& result) const;
    /*
      Stop polling for as long as a tag is being addressed
      @details An inventory round leaves every tag it saw flagged as already counted, and a tag
      in that state answers nothing until the flag decays. Letting polling run between two tag
      operations therefore breaks the second one, so it stays stopped from select() until
      deselect() rather than being stopped and restarted around each operation
      @return False when polling was running and would not stop. The module is still running
      rounds, and a tag operation attempted now would be answering into them
     */
    bool pause_polling();
    // Put polling back the way select() found it
    void resume_polling();
 
    m5::unit::UHFRFIDComponent& _u;
    Tag _selected{};
    uint32_t _access_password{};
    // Bank the stored mask matches against, which decides whether an EPC rewrite invalidates it
    Bank _mask_bank{Bank::Epc};
    bool _has_selection{};
    // Was polling running when the tag currently being addressed was selected?
    bool _resume_polling{};
};
 
}  // namespace uhf
}  // namespace m5
#endif