unit_UHFRFID.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_RFID_UNIT_UNIT_UHFRFID_HPP
#define M5_UNIT_RFID_UNIT_UNIT_UHFRFID_HPP
 
#include <memory>
#include <vector>
 
#include <M5UnitComponent.hpp>
#include <m5_utility/container/circular_buffer.hpp>
#include <m5_utility/stl/expected.hpp>
 
#include "uhf/uhf.hpp"
 
namespace m5 {
namespace uhf {
class UHFLayer;
}  // namespace uhf
 
namespace unit {
 
using TagResult = m5::stl::expected<void, uint8_t>;
 
constexpr uint8_t READER_SILENT{0xFF};   
constexpr uint8_t READER_BALKED{0xFE};   
constexpr uint8_t READER_GARBLED{0xFD};  
constexpr uint8_t NOT_SELECTED{0xFC};    
constexpr uint8_t BAD_ARGUMENT{0xFB};    
constexpr uint8_t READER_BUSY{0xFA};     
 
class UHFRFIDComponent : public Component {
public:
    struct config_t {
        uint16_t polling_count{128};
        m5::uhf::Region region{m5::uhf::Region::Unspecified};
        uint16_t tag_queue_size{32};
        uint32_t command_timeout_ms{1000};
        uint8_t auto_sleep_minutes{0};
    };
 
    virtual ~UHFRFIDComponent() = default;
 
    inline config_t config() const
    {
        return _cfg;
    }
    inline void config(const config_t& cfg)
    {
        _cfg = cfg;
    }
 
 
    bool startPolling(const uint16_t count);
    bool stopPolling();
    inline bool inPolling() const
    {
        return _polling;
    }
    inline unsigned long lastFrameAt() const
    {
        return _last_frame_at;
    }
 
    inline size_t available() const
    {
        return _tags ? _tags->size() : 0U;
    }
    inline const m5::uhf::Tag& oldest() const
    {
        return (*_tags)[0];
    }
    inline void discard()
    {
        if (_tags && !_tags->empty()) {
            _tags->pop_front();
        }
    }
    inline void flush()
    {
        if (_tags) {
            _tags->clear();
        }
    }
    inline uint32_t dropped() const
    {
        return _dropped;
    }
    inline void clearDropped()
    {
        _dropped = 0;
    }
 
    virtual bool readModuleInformation(m5::uhf::ModuleInformation& info) = 0;
    virtual bool readTransmitPower(int16_t& dbm100) = 0;
    virtual bool writeTransmitPower(const int16_t dbm100) = 0;
    virtual bool readRegion(m5::uhf::Region& region) = 0;
    virtual bool writeRegion(const m5::uhf::Region region) = 0;
    virtual bool readChannel(uint8_t& index) = 0;
    virtual bool writeChannel(const uint8_t index) = 0;
    virtual bool writeAutomaticFrequencyHopping(const bool enable) = 0;
    virtual bool writeContinuousCarrier(const bool enable) = 0;
    virtual bool readQueryParameters(m5::uhf::QueryParameters& qp) = 0;
    virtual bool writeQueryParameters(const m5::uhf::QueryParameters& qp) = 0;
    virtual bool writeAutoSleepTime(const uint8_t minutes) = 0;
    virtual bool writeIdle(const bool enter, const uint8_t minutes = 0) = 0;
    virtual bool sleep() = 0;
    virtual bool wake() = 0;
    virtual bool writeOperatingChannels(const std::vector<uint8_t>& channels) = 0;
    virtual bool readBlockingSignal(m5::uhf::ChannelLevels& levels) = 0;
    virtual bool readChannelRSSI(m5::uhf::ChannelLevels& levels) = 0;
    virtual bool readSelectParameter(m5::uhf::SelectParameter& sp) = 0;
 
 
    virtual bool writeSelectParameter(const m5::uhf::Bank bank, const uint32_t pointer_bits, const uint8_t* mask,
                                      const size_t mask_len) = 0;
    virtual bool writeSelectEnabled(const bool enable) = 0;
    virtual TagResult readTagMemory(std::vector<uint8_t>& out, const m5::uhf::Bank bank, const uint16_t word_address,
                                    const uint16_t word_count, const uint32_t access_password) = 0;
    virtual TagResult writeTagMemory(const m5::uhf::Bank bank, const uint16_t word_address, const uint8_t* data,
                                     const size_t len, const uint32_t access_password) = 0;
    virtual TagResult lockTagMemory(const uint32_t payload, const uint32_t access_password) = 0;
    virtual TagResult killTag(const uint32_t kill_password) = 0;
    virtual TagResult blockPermalock(std::vector<uint8_t>& out, const m5::uhf::Bank bank, const uint16_t block_pointer,
                                     const uint8_t block_range, const uint8_t* mask, const size_t mask_len,
                                     const uint32_t access_password, const bool allow_permanent) = 0;
    virtual TagResult qtCommand(uint16_t& control, const bool write, const bool persistent,
                                const uint32_t access_password) = 0;
    virtual TagResult nxpChangeConfig(uint16_t& config, const uint16_t toggle, const uint32_t access_password) = 0;
    virtual TagResult nxpChangeEAS(const bool enable, const uint32_t access_password) = 0;
    virtual bool nxpEASAlarm(std::vector<uint8_t>& alarm) = 0;
    virtual TagResult nxpReadProtect(const bool protect, const uint32_t access_password) = 0;
    virtual m5::uhf::Reason classify(const uint8_t error_code) const = 0;
 
    virtual bool begin() override;
    virtual void update(const bool force = false) override;
 
protected:
    explicit UHFRFIDComponent(const uint8_t addr = 0x00) : Component(addr)
    {
    }
 
    // Pump the UART stream and route frames. Returns true if any frame was handled
    virtual bool pump(const uint32_t timeout_ms) = 0;
    // Issue the multiple polling command
    virtual bool start_polling_command(const uint16_t count) = 0;
    // Issue the stop polling command
    virtual bool stop_polling_command() = 0;
 
    /*
      Refuse a reader setting while polling is running
      @param what Name of the operation, used in the warning
      @return True when the caller must give up
      @details The module answers unreliably while it is running inventory rounds, so reader
      settings are rejected outright instead of failing later with a timeout
     */
    bool reject_while_polling(const char* what) const;
 
    /*
      Refuse a tag operation while no mask is picking a tag out
      @param what Name of the operation, used in the warning
      @return True when the caller must give up
      @details A mask of zero length matches every tag rather than none, so an operation sent
      without one does not fail: it succeeds against whichever tag answers. A write lands on a
      tag nobody chose and a kill cannot be taken back, so these are rejected outright
     */
    bool reject_without_selection(const char* what) const;
 
    // Push a tag into the queue, counting a drop when it overflows
    void push_tag(const m5::uhf::Tag& tag);
    // Note that a frame arrived (exposed through lastFrameAt)
    void note_frame_arrival();
    // Reissue the polling command before its round count runs out
    void reissue_polling_if_needed();
 
    config_t _cfg{};
    std::unique_ptr<m5::container::CircularBuffer<m5::uhf::Tag>> _tags{};
    uint32_t _dropped{};
    // Whether polling should be renewed. Cleared as soon as a stop is asked for
    bool _polling{};
    // Whether the module is believed to still be running rounds. Only a confirmed stop clears it
    bool _rounds_running{};
    // Whether a mask of some length has been stored in the module
    bool _select_mask_stored{};
    // Whether the stored mask is being applied to tag operations
    bool _select_enabled{};
    uint16_t _polling_count{};
    unsigned long _last_frame_at{};
    unsigned long _polling_issued_at{};
 
    friend class m5::uhf::UHFLayer;
};
 
}  // namespace unit
}  // namespace m5
#endif