uhf.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_HPP
#define M5_UNIT_RFID_UHF_UHF_HPP
 
#include <array>
#include <cstddef>
#include <cstdint>
#include <string>
#include <vector>
 
#include <m5_utility/crc.hpp>
 
namespace m5 {
namespace uhf {
 
enum class Bank : uint8_t {
    Reserved,  
    Epc,       
    Tid,       
    User,      
};
 
enum class Region : uint8_t {
    Unspecified = 0x00,  
    China900MHz = 0x01,
    America     = 0x02,
    Europe      = 0x03,
    China800MHz = 0x04,
    SouthKorea  = 0x06,
};
 
enum class Session : uint8_t { S0, S1, S2, S3 };
 
enum class Target : uint8_t { A, B };
 
enum class SelectFilter : uint8_t {
    All,          
    AllAlias,     
    NotSelected,  
    Selected,     
};
 
enum class Reason : uint8_t {
    // Nothing went out over the air
    NoSelection,  
    BadArgument,  
    Busy,         
    Unsupported,  
 
    // The tag answered and declined, in the terms EPC Gen2 Annex I sets out
    Locked,             
    InsufficientPower,  
    MemoryOverrun,      
    Refused,            
 
    // What became of it is not known
    NoAnswer,      
    AccessFailed,  
    ReaderFault,   
    Malformed      
};
 
inline bool tagUnchanged(const Reason reason)
{
    return reason < Reason::NoAnswer;
}
 
inline const char* reasonAsString(const Reason reason)
{
    switch (reason) {
        case Reason::NoSelection:
            return "no tag selected";
        case Reason::BadArgument:
            return "the request cannot succeed as asked";
        case Reason::Busy:
            return "the reader could not make room to send it";
        case Reason::Unsupported:
            return "this chip does not have the command";
        case Reason::Locked:
            return "the memory is locked";
        case Reason::InsufficientPower:
            return "the tag has not the power";
        case Reason::MemoryOverrun:
            return "past the end of the memory";
        case Reason::Refused:
            return "the tag declined";
        case Reason::NoAnswer:
            return "nobody answered";
        case Reason::AccessFailed:
            return "the tag would not be accessed; the password may be wrong";
        case Reason::ReaderFault:
            return "the reader did not carry it out";
        default:
            return "the answer could not be read";
    }
}
 
constexpr size_t EPC_MAX_BYTES{62};
constexpr size_t TID_MAX_BYTES{40};
 
struct Epc {
    std::array<uint8_t, EPC_MAX_BYTES> data{};  
    uint8_t size{};                             
 
    inline uint8_t operator[](const size_t i) const
    {
        return data[i];
    }
    inline uint8_t& operator[](const size_t i)
    {
        return data[i];
    }
    inline const uint8_t* begin() const
    {
        return data.data();
    }
    inline const uint8_t* end() const
    {
        return data.data() + size;
    }
    inline bool empty() const
    {
        return size == 0;
    }
    bool assign(const uint8_t* src, const size_t len);
    bool operator==(const Epc& o) const;
    std::string toString() const;
};
 
struct Tid {
    std::array<uint8_t, TID_MAX_BYTES> data{};  
    uint8_t size{};                             
 
    inline uint8_t operator[](const size_t i) const
    {
        return data[i];
    }
    inline uint8_t& operator[](const size_t i)
    {
        return data[i];
    }
    inline const uint8_t* begin() const
    {
        return data.data();
    }
    inline const uint8_t* end() const
    {
        return data.data() + size;
    }
    inline bool empty() const
    {
        return size == 0;
    }
    bool assign(const uint8_t* src, const size_t len);
    bool operator==(const Tid& o) const;
    std::string toString() const;
};
 
enum class Vendor : uint16_t {
    Unknown               = 0x000,
    Impinj                = 0x001,
    TexasInstruments      = 0x002,
    Alien                 = 0x003,
    Atmel                 = 0x005,
    NXP                   = 0x006,
    STMicroelectronics    = 0x007,
    EPMicroelectronics    = 0x008,
    EMMicroelectronic     = 0x00B,
    Quanray               = 0x00F,
    Fujitsu               = 0x010,
    Nationz               = 0x01B,
    Invengo               = 0x01C,
    RFMicron              = 0x024,
    FudanMicroelectronics = 0x027,
    AMS                   = 0x02F,
    HuadaSemiconductor    = 0x032,
    Mikron                = 0x034,
};
 
namespace detail {
inline uint16_t word_at(const uint8_t* data, const size_t word_index)
{
    return static_cast<uint16_t>((data[word_index * 2] << 8) | data[word_index * 2 + 1]);
}
 
struct VendorEntry {
    Vendor vendor;     
    const char* name;  
};
 
inline const VendorEntry* vendorEntries(size_t& count)
{
    static const VendorEntry entries[] = {
        {Vendor::Impinj, "Impinj"},
        {Vendor::TexasInstruments, "Texas Instruments"},
        {Vendor::Alien, "Alien Technology"},
        {Vendor::Atmel, "Atmel"},
        {Vendor::NXP, "NXP Semiconductors"},
        {Vendor::STMicroelectronics, "ST Microelectronics"},
        {Vendor::EPMicroelectronics, "EP Microelectronics"},
        {Vendor::EMMicroelectronic, "EM Microelectronic"},
        {Vendor::Quanray, "Quanray Electronics"},
        {Vendor::Fujitsu, "Fujitsu"},
        {Vendor::Nationz, "Nationz"},
        {Vendor::Invengo, "Invengo"},
        {Vendor::RFMicron, "RFMicron"},
        {Vendor::FudanMicroelectronics, "Shanghai Fudan Microelectronics Group"},
        {Vendor::AMS, "ams AG"},
        {Vendor::HuadaSemiconductor, "Huada Semiconductor"},
        {Vendor::Mikron, "PJSC Mikron"},
    };
    count = sizeof(entries) / sizeof(entries[0]);
    return entries;
}
}  // namespace detail
 
enum class Chip : uint8_t {
    Unknown,
    AlienHiggs3,
    AlienHiggs4,
    AlienHiggs9,
    Em4423SmallEpc,
    Em4423LargeEpc,
    ImpinjMonza4D,
    ImpinjMonza4E,
    ImpinjMonza4i,
    ImpinjMonza4QT,
    ImpinjM730,
    ImpinjM750,
    ImpinjM770,
    ImpinjM780,
    ImpinjM781,
    NxpUcodeG2iM,
    NxpUcodeG2iMPlus,
    NxpUcode7,
    NxpUcode7xm1k,
    NxpUcode7xm2k,
    NxpUcode7xmPlus,
    NxpUcode8,
    NxpUcode8m,
    NxpUcode9,
    NxpUcode9xe,
};
 
struct Tag {
    // Filled in by detection
    uint16_t pc{};   
    uint16_t crc{};  
    int8_t rssi{};   
    Epc epc{};       
 
    // Filled in by identification
    Tid tid{};                       
    Chip chip{Chip::Unknown};        
    Vendor vendor{Vendor::Unknown};  
    uint16_t mdid{};                 
    uint16_t model_number{};         
    uint16_t serial_bits{};          
    uint32_t user_memory_bits{};
    uint32_t epc_max_bits{};          
    uint32_t permalock_block_bits{};  
    bool has_xtid{};                  
    bool supports_security{};         
    bool supports_file{};             
    bool supports_block_permalock{};
 
    inline bool valid() const
    {
        return !epc.empty();
    }
    std::string vendorAsString() const;
    std::string chipAsString() const;
};
 
inline uint32_t chipUserMemoryBits(const Chip chip)
{
    switch (chip) {
        case Chip::AlienHiggs9:
            // ALC-390 offers "688 bit user memory", which a tag holds only while its EPC is
            // the 96 bit it leaves the factory with. chipSharedUserMemoryBits is what sizes
            // this chip; this is the figure to fall back on when the PC is unknown
            return 688;
        case Chip::AlienHiggs4:
            return 128;  // Higgs 4 V1.3.6 3: "128 bits of NVM for User data"
        // EM4423 4423-DS-02 v6.0 7: "The small EPC memory configuration provides 128 bits for
        // encoding and 160 bits of USER memory", and 224 with 64 for the large one. Which of
        // the two a tag is, is in its model number, so neither size has to be shared
        case Chip::Em4423SmallEpc:
            return 160;
        case Chip::Em4423LargeEpc:
            return 64;
        // Monza 4 V10.0 Table 2-8
        case Chip::ImpinjMonza4D:
            return 32;
        case Chip::ImpinjMonza4E:
            return 128;
        case Chip::ImpinjMonza4i:
            return 480;
        case Chip::ImpinjMonza4QT:
            return 512;  // Monza 4 Rev8.0 2.3.1: "512 bits of user memory". 32 words, confirmed
        // M700 Series v6.4 1, and M780 / M781 v1.1 1
        case Chip::ImpinjM750:
            return 32;
        case Chip::ImpinjM770:
            return 32;
        case Chip::ImpinjM780:
            return 128;
        case Chip::ImpinjM781:
            return 512;
        case Chip::NxpUcode8m:
            return 32;  // SL3S1205_15 Rev3.6 Table 7: "User Memory 32 bit"
        // SL3S10X4 memory tables
        case Chip::NxpUcode7xm1k:
            return 1024;
        case Chip::NxpUcode7xm2k:
        case Chip::NxpUcode7xmPlus:
            return 2048;
        case Chip::NxpUcodeG2iM:
            // Rev3.7 Table 7 and Table 15. The "640 bit configurable User Memory" of the
            // general description is the whole pool, and this part keeps its EPC fixed at
            // 256 bit, which takes 128 of those bits away
            return 512;
        case Chip::NxpUcodeG2iMPlus:
            // Rev3.7 Table 16, which is what it ships with. The EPC can be taken up to 448 bit
            // and the User bank shrinks by as much, so chipSharedUserMemoryBits is what sizes
            // this chip; this is the figure to fall back on when the PC is unknown
            return 640;
        default:
            return 0;
    }
}
 
inline uint32_t chipEpcMaxBits(const Chip chip)
{
    switch (chip) {
        case Chip::AlienHiggs9:
            return 496;  // ALC-390: "Supports EPC size up to 496b"
        case Chip::AlienHiggs4:
            return 128;  // Higgs 4 V1.3.6 3: "128 bits of NVM for Electronic Product Code"
        // EM4423 4423-DS-02 v6.0 7
        case Chip::Em4423SmallEpc:
            return 128;
        case Chip::Em4423LargeEpc:
            return 224;
        // Monza 4 V10.0 Table 2-8
        case Chip::ImpinjMonza4D:
            return 128;
        case Chip::ImpinjMonza4E:
            return 496;
        case Chip::ImpinjMonza4i:
            return 256;
        case Chip::ImpinjMonza4QT:
            return 128;  // Monza 4 Rev8.0 2.3.1: "128 bits of EPC memory"
        // M700 Series v6.4 1, and M780 / M781 v1.1 1
        case Chip::ImpinjM730:
            return 128;
        case Chip::ImpinjM750:
            return 96;
        case Chip::ImpinjM770:
            return 128;
        case Chip::ImpinjM780:
            return 496;
        case Chip::ImpinjM781:
            return 128;
        case Chip::NxpUcode7:
            return 128;  // SL3S1204 Rev4.0 Table 8
        case Chip::NxpUcode8m:
            return 96;  // SL3S1205_15 Rev3.6 Table 7
        case Chip::NxpUcode7xm1k:
        case Chip::NxpUcode7xm2k:
        case Chip::NxpUcode7xmPlus:
            return 448;  // SL3S10X4 memory tables: "EPC (excluding CRC, PC) 448 bit"
        case Chip::NxpUcode8:
            // SL3S1205_15 Rev3.6 Table 6 gives 128 bit, and a real tag takes a PC of eight
            // words and refuses nine
            return 128;
        case Chip::NxpUcode9:
            return 96;  // SL3S1206 Rev3.5 Table 5: "EPC (excluding 16 bit CRC-16 and 16-bit PC) 96 bit"
        case Chip::NxpUcode9xe:
            return 128;  // SL3S1216 Rev3.3 2.1.1: "128-bit of EPC memory"
        case Chip::NxpUcodeG2iM:
            return 256;  // G2iM Rev3.7: "256 bit of EPC memory"
        case Chip::NxpUcodeG2iMPlus:
            return 448;  // G2iM Rev3.7: "up to 448 bit EPC for UCODE G2iM+"
        default:
            return 0;
    }
}
 
inline uint16_t chipTidWords(const Chip chip)
{
    switch (chip) {
        case Chip::AlienHiggs3:
            // Higgs 3 IC Datasheet Supplement, TID Bank rows 0 to 5: the first two words name
            // the chip and the four after them are Unique ID Word 0 to 3. Row 6 onwards is
            // reserved, and the XTID indicator of this chip reads zero
            return 6;
        case Chip::NxpUcodeG2iM:
        case Chip::NxpUcodeG2iMPlus:
            // SL3S1003_1013 Rev3.7 Table 8: 30h to 5Fh is a permalocked serial number, under an
            // XTID header that reads 00h. The TID ends there; 60h onwards is User TID memory
            return 6;
        default:
            return 0;
    }
}
 
inline uint16_t chipPermalockBlockCount(const Chip chip)
{
    switch (chip) {
        case Chip::ImpinjMonza4QT:
            return 4;  // Monza 4 V10.0 2.3.1: "four fixed, 128-bit sections of user memory"
        case Chip::ImpinjMonza4i:
            return 4;  // Monza 4 V10.0 Table 2-16
        case Chip::AlienHiggs3:
            // Higgs 3 Supplement: "BlockPermaLock: Block lengths are 32 bits and a total of
            // 4 blocks"
            return 4;
        // EM4423 4423-DS-02 v6.0, the Gen2V2config word: the small EPC layout names Block 0
        // Locked through Block 4 Locked, and the large one stops at Block 1 Locked
        case Chip::Em4423SmallEpc:
            return 5;
        case Chip::Em4423LargeEpc:
            return 2;
        default:
            return 0;
    }
}
 
enum class Support : uint8_t {
    Unknown,  
    No,       
    Yes       
};
 
inline const char* supportAsString(const Support support)
{
    switch (support) {
        case Support::Yes:
            return "yes";
        case Support::No:
            return "no";
        default:
            return "unknown";
    }
}
 
inline Support chipBlockPermalockSupport(const Chip chip)
{
    switch (chip) {
        case Chip::NxpUcodeG2iM:
        case Chip::NxpUcodeG2iMPlus:
            // SL3S1003_1013 Rev3.7 Table 13: "BlockPermalock ... yes ... yes"
            return Support::Yes;
        case Chip::ImpinjMonza4QT:
            // Monza 4 V10.0 2.3.1, the four 128-bit sections it can lock
            return Support::Yes;
        case Chip::ImpinjMonza4i:
            // Monza 4 V10.0 Table 2-14: "User Memory in Monza 4QT (in Private mode) and
            // Monza 4i only"
            return Support::Yes;
        case Chip::NxpUcode7xm1k:
        case Chip::NxpUcode7xm2k:
        case Chip::NxpUcode7xmPlus:
            return Support::Yes;  // SL3S10X4 p.3 and p.12
        case Chip::AlienHiggs3:
            return Support::Yes;  // Higgs 3 Supplement, optional commands
        case Chip::Em4423SmallEpc:
        case Chip::Em4423LargeEpc:
            // EM4423 4423-DS-02 v6.0 8: "BlockPermalock '11001001' Optional"
            return Support::Yes;
        case Chip::NxpUcode8:
        case Chip::NxpUcode8m:
        case Chip::NxpUcode9:
        case Chip::NxpUcode9xe:
            // The optional commands these list are Access, BlockWrite and Untraceable
            return Support::No;
        default:
            return Support::Unknown;
    }
}
 
inline Support chipQTSupport(const Chip chip)
{
    switch (chip) {
        case Chip::ImpinjMonza4QT:
            // Monza 4 V10.0 Table 2-8, the only part of the family with the column ticked
            return Support::Yes;
        case Chip::Em4423SmallEpc:
        case Chip::Em4423LargeEpc:
            // EM4423 4423-DS-02 v6.0 8 sets out "all implemented commands", and QT is not one
            return Support::No;
        default:
            return Support::Unknown;
    }
}
 
inline Support chipNxpCustomCommandSupport(const Chip chip)
{
    switch (chip) {
        case Chip::NxpUcodeG2iM:
        case Chip::NxpUcodeG2iMPlus:
            // SL3S1003_1013 Rev3.7 8: the custom commands, "backward compatible to UCODE G2X".
            // The G2X and G2iL that line came from are not in this table
            return Support::Yes;
        case Chip::NxpUcode8:
        case Chip::NxpUcode8m:
            // SL3S1205_15 Rev3.6 9.4: ACCESS, Block Write and Untraceable, and nothing else
            return Support::No;
        case Chip::Em4423SmallEpc:
        case Chip::Em4423LargeEpc:
            // EM4423 4423-DS-02 v6.0 8 sets out "all implemented commands", and none of these
            // is one. They are NXP's, and this chip is EM Microelectronic's
            return Support::No;
        default:
            return Support::Unknown;
    }
}
 
inline uint32_t chipPermalockBlockBits(const Chip chip)
{
    switch (chip) {
        case Chip::ImpinjMonza4QT:
            // Monza 4 V10.0 2.3.1: "four fixed, 128-bit sections of user memory"
            return 128;
        case Chip::NxpUcode7xm1k:
        case Chip::NxpUcode7xm2k:
        case Chip::NxpUcode7xmPlus:
            // SL3S10X4: "BlockPermalock (block size of 256-bit)". The UCODE G2iM has the command
            // as well, but its datasheet does not give a block size
            return 256;
        case Chip::ImpinjMonza4i:
            // Monza 4 V10.0 Table 2-16: three blocks of 128 bits and a fourth of 96, which is
            // 128 all along with the user memory running out 32 bits into the last one
            return 128;
        case Chip::AlienHiggs3:
            return 32;  // Higgs 3 Supplement: "Block lengths are 32 bits"
        case Chip::Em4423SmallEpc:
        case Chip::Em4423LargeEpc:
            // EM4423 4423-DS-02 v6.0 8: "USER memory block size is two words."
            return 32;
        default:
            return 0;
    }
}
 
inline uint32_t chipPermalockLastBlockBits(const Chip chip)
{
    const uint32_t bits  = chipPermalockBlockBits(chip);
    const uint16_t count = chipPermalockBlockCount(chip);
    if (bits == 0 || count == 0) {
        return 0;
    }
    const uint32_t user = chipUserMemoryBits(chip);
    const uint32_t upto = bits * count;
    // Blocks that stop short of the bank cover the whole of themselves; Alien's Higgs-3 has
    // four 32-bit blocks over 512 bits of user memory and none of them is cut off
    if (user == 0 || user >= upto) {
        return bits;
    }
    return user - bits * (count - 1);
}
 
inline bool chipHasNoUserMemory(const Chip chip)
{
    switch (chip) {
        case Chip::NxpUcode8:
            // SL3S1205_15 Rev3.6 Table 8: the memory map has no Bank 11 and the UMI bit of the
            // PC is "hardwired to 0"
            return true;
        case Chip::NxpUcode9:
            return true;  // SL3S1206 Rev3.5 Table 6, the same way
        case Chip::NxpUcode9xe:
            return true;  // SL3S1216 Rev3.3 Table 5, the same way
        case Chip::NxpUcode7:
            return true;  // SL3S1204 Rev4.0 features: "No User Memory"
        case Chip::ImpinjM730:
            return true;  // M700 Series v6.4 1: "128 bits of EPC memory, 0 bits of user memory"
        default:
            return false;
    }
}
 
inline uint32_t chipSharedUserMemoryBits(const Chip chip, const uint16_t pc)
{
    // ALC-390: 6 words of EPC and 43 of User as it ships, and every word the EPC grows by is a
    // word the User bank loses
    constexpr uint16_t HIGGS9_POOL_WORDS{49};
    // Rev3.7 Tables 16 and 17: 128 bit of EPC with 640 of User, or 448 with 320. Both come to
    // 768 bit, which the datasheet says moves "in steps of 64 bit"
    constexpr uint16_t G2IM_PLUS_POOL_WORDS{48};
 
    uint16_t pool{};
    switch (chip) {
        case Chip::AlienHiggs9:
            pool = HIGGS9_POOL_WORDS;
            break;
        case Chip::NxpUcodeG2iMPlus:
            pool = G2IM_PLUS_POOL_WORDS;
            break;
        default:
            return 0;
    }
    // A tag selected by its TID reaches identify() with no PC, and a bank sized from a length
    // of zero would be the whole pool. Returning 0 rather than a wrong size
    if (pc == 0) {
        return 0;
    }
    const uint16_t epc_words = static_cast<uint16_t>((pc >> 11) & 0x1F);
    return epc_words < pool ? static_cast<uint32_t>(pool - epc_words) * 16U : 0U;
}
 
constexpr uint8_t TID_CLASS_EPCGLOBAL{0xE2};
 
inline bool tidHasXtid(const uint8_t* tid, const size_t len)
{
    return tid != nullptr && len >= 2 && (tid[1] & 0x80) != 0;
}
 
inline uint16_t xtidSerialBits(const uint16_t xtid_header)
{
    const uint8_t v = static_cast<uint8_t>((xtid_header >> 13) & 0x07);
    return v == 0 ? 0U : static_cast<uint16_t>(48 + (v - 1) * 16);
}
 
constexpr uint16_t XTID_OPTIONAL_COMMAND_SUPPORT{0x1000};    
constexpr uint16_t XTID_BLOCKWRITE_BLOCKERASE{0x0800};       
constexpr uint16_t XTID_USER_MEMORY_BLOCKPERMALOCK{0x0400};  
constexpr uint16_t XTID_LOCK_BIT{0x0200};                    
constexpr uint16_t XTID_EXTENDED_HEADER{0x0001};             
 
constexpr size_t TID_FIXED_WORDS{2};
constexpr size_t XTID_FIXED_WORDS{3};
 
inline size_t xtidTotalWords(const uint16_t xtid_header)
{
    size_t words = XTID_FIXED_WORDS + xtidSerialBits(xtid_header) / 16;
    if (xtid_header & XTID_OPTIONAL_COMMAND_SUPPORT) {
        words += 1;
    }
    if (xtid_header & XTID_BLOCKWRITE_BLOCKERASE) {
        words += 4;
    }
    if (xtid_header & XTID_USER_MEMORY_BLOCKPERMALOCK) {
        words += 2;
    }
    if (xtid_header & XTID_LOCK_BIT) {
        words += 1;
    }
    return words;
}
 
constexpr size_t TID_CHIP_WORDS{3};
 
inline bool tidTellsTagsApart(const uint8_t* tid, const size_t len)
{
    if (tid == nullptr || len <= TID_CHIP_WORDS * 2) {
        return false;
    }
    for (size_t i = TID_CHIP_WORDS * 2; i < len; ++i) {
        if (tid[i] != 0x00) {
            return true;
        }
    }
    return false;
}
 
inline Vendor resolveVendor(const uint16_t mdid)
{
    size_t count{};
    const detail::VendorEntry* entries = detail::vendorEntries(count);
    for (size_t i = 0; i < count; ++i) {
        if (static_cast<uint16_t>(entries[i].vendor) == mdid) {
            return entries[i].vendor;
        }
    }
    return Vendor::Unknown;
}
 
inline Chip resolveChip(const Vendor vendor, const uint16_t model_number)
{
    switch (vendor) {
        case Vendor::Impinj:
            switch (model_number) {
                // Monza 4 datasheet V10.0 Table 4-8
                case 0x100:
                    return Chip::ImpinjMonza4D;
                case 0x105:
                    return Chip::ImpinjMonza4QT;
                case 0x10C:
                    return Chip::ImpinjMonza4E;
                case 0x114:
                    return Chip::ImpinjMonza4i;
                // M700 Series datasheet v6.4 Table 23
                case 0x190:
                    return Chip::ImpinjM750;
                case 0x191:
                    return Chip::ImpinjM730;
                case 0x1A0:
                    return Chip::ImpinjM770;
                // M780 / M781 datasheet v1.1 Table 21
                case 0x1C0:
                    return Chip::ImpinjM780;
                case 0x1C1:
                    return Chip::ImpinjM781;
                default:
                    return Chip::Unknown;
            }
        case Vendor::Alien:
            switch (model_number) {
                case 0x412:
                    return Chip::AlienHiggs3;  // Higgs 3 IC datasheet, Table 1
                case 0x414:
                    // Higgs 4 IC Datasheet V1.3.6 TID table: "1 / 0x3414 / Alien Manufacturer
                    // Code lower bits, Higgs 4 IC"
                    return Chip::AlienHiggs4;
                case 0x821:
                    // Neither Alien nor the GS1 registry publishes this one; it comes from
                    // third-party tables, and was read off a real Higgs 9 whose TID is
                    // E2803821 2000 6820042E3E3B
                    return Chip::AlienHiggs9;
                default:
                    return Chip::Unknown;
            }
        case Vendor::EMMicroelectronic:
            switch (model_number) {
                // EM4423 4423-DS-02 v6.0, the TID memory bank: word 1 holds "Tag MDID LSB's
                // (Bh)" and then the model number, whose last bit is note 1, "EPC size, where
                // 0 indicates small EPC memory and 1 indicates large EPC memory"
                case 0x0A0:
                    return Chip::Em4423SmallEpc;
                case 0x0A1:
                    return Chip::Em4423LargeEpc;
                default:
                    return Chip::Unknown;
            }
        case Vendor::NXP:
            switch (model_number) {
                case 0x80A:
                    return Chip::NxpUcodeG2iM;  // UCODE G2iM datasheet Rev 3.7
                case 0x80B:
                    return Chip::NxpUcodeG2iMPlus;
                case 0x890:
                    return Chip::NxpUcode7;  // SL3S1204 Rev4.0 Table 12: "E28068902000"
                // SL3S10X4 TID table: E2806D12, E2806F12 and E2806D92
                case 0xD12:
                    return Chip::NxpUcode7xm1k;
                case 0xF12:
                    return Chip::NxpUcode7xm2k;
                case 0xD92:
                    return Chip::NxpUcode7xmPlus;
                case 0x894:
                    return Chip::NxpUcode8;  // SL3S1205/1215 datasheet
                case 0x994:
                    return Chip::NxpUcode8m;  // SL3S1205_15 Rev3.6, the 8m of the same datasheet
                case 0xA16:
                case 0xA96:
                    // The same change of model number, made to this part at the same time. Its
                    // datasheet gives both TIDs outright: "HEX E280 6A16 ... or HEX E280 6A96"
                    // (SL3S1216 Rev3.3 Table 5 note 1)
                    return Chip::NxpUcode9xe;
                case 0x995:
                case 0x915:
                    // The model number changed without the part being renamed, and the
                    // datasheet gives both TIDs: "HEX E280 6995 ... or HEX E280 6915 ..."
                    // (SL3S1206 Rev3.5 Table 6 note 1)
                    return Chip::NxpUcode9;
                default:
                    return Chip::Unknown;
            }
        default:
            return Chip::Unknown;
    }
}
 
inline void fillSizesFromChip(Tag& tag)
{
    if (tag.user_memory_bits == 0) {
        // A chip that shares a pool has no one size to look up, so the PC is asked first
        tag.user_memory_bits = chipSharedUserMemoryBits(tag.chip, tag.pc);
    }
    if (tag.user_memory_bits == 0) {
        tag.user_memory_bits = chipUserMemoryBits(tag.chip);
    }
    if (tag.epc_max_bits == 0) {
        tag.epc_max_bits = chipEpcMaxBits(tag.chip);
    }
    if (tag.permalock_block_bits == 0) {
        tag.permalock_block_bits = chipPermalockBlockBits(tag.chip);
    }
}
 
inline Chip chipFromTid(const uint8_t* tid, const size_t len)
{
    if (tid == nullptr || len < TID_FIXED_WORDS * 2 || tid[0] != TID_CLASS_EPCGLOBAL) {
        return Chip::Unknown;
    }
    const uint16_t mdid  = static_cast<uint16_t>(((tid[1] & 0x1F) << 4) | (tid[2] >> 4));
    const uint16_t model = static_cast<uint16_t>(((tid[2] & 0x0F) << 8) | tid[3]);
    return resolveChip(resolveVendor(mdid), model);
}
 
struct TidReadPlan {
    uint16_t word_address{};  
    uint16_t words{};         
    bool fits{true};          
};
 
inline TidReadPlan tidReadPlan(const uint8_t* tid, const size_t len)
{
    TidReadPlan plan{};
    if (len < TID_FIXED_WORDS * 2) {
        plan.words = static_cast<uint16_t>(TID_FIXED_WORDS);
        return plan;
    }
    if (!tidHasXtid(tid, len)) {
        // No header to say how long the TID is. The chip may still be one that keeps a serial
        // past the words that name it, and that serial is the whole point of reading a TID
        const size_t total = chipTidWords(chipFromTid(tid, len));
        const size_t held  = len / 2;
        if (total > held) {
            plan.word_address = static_cast<uint16_t>(held);
            plan.words        = static_cast<uint16_t>(total - held);
        }
        return plan;
    }
    if (len < XTID_FIXED_WORDS * 2) {
        plan.word_address = static_cast<uint16_t>(TID_FIXED_WORDS);
        plan.words        = static_cast<uint16_t>(XTID_FIXED_WORDS - TID_FIXED_WORDS);
        return plan;
    }
    const uint16_t header = static_cast<uint16_t>((tid[TID_FIXED_WORDS * 2] << 8) | tid[TID_FIXED_WORDS * 2 + 1]);
    const size_t total    = xtidTotalWords(header);
    if (total * 2 > TID_MAX_BYTES) {
        plan.fits = false;
        return plan;
    }
    const size_t have = len / 2;
    if (have < total) {
        plan.word_address = static_cast<uint16_t>(have);
        plan.words        = static_cast<uint16_t>(total - have);
    }
    return plan;
}
 
inline bool decodeTid(Tag& tag, const uint8_t* tid, const size_t len)
{
    if (tid == nullptr || len < 4 || tid[0] != TID_CLASS_EPCGLOBAL) {
        return false;
    }
    tag.has_xtid          = (tid[1] & 0x80) != 0;
    tag.supports_security = (tid[1] & 0x40) != 0;
    tag.supports_file     = (tid[1] & 0x20) != 0;
    tag.mdid              = static_cast<uint16_t>(((tid[1] & 0x1F) << 4) | (tid[2] >> 4));
    tag.vendor            = resolveVendor(tag.mdid);
    tag.model_number      = static_cast<uint16_t>(((tid[2] & 0x0F) << 8) | tid[3]);
    tag.chip              = resolveChip(tag.vendor, tag.model_number);
 
    tag.serial_bits              = 0;
    tag.epc_max_bits             = 0;
    tag.user_memory_bits         = 0;
    tag.permalock_block_bits     = 0;
    tag.supports_block_permalock = false;
    if (!tag.has_xtid || len < XTID_FIXED_WORDS * 2) {
        fillSizesFromChip(tag);
        return true;
    }
 
    const uint16_t header = detail::word_at(tid, 2);
    tag.serial_bits       = xtidSerialBits(header);
 
    // The segments sit past the serial, in the order the header lists them. Each one is stepped
    // over whether or not the caller read far enough to hold it, so the offsets of the segments
    // below it stay right even when only part of the TID is in hand
    size_t word = XTID_FIXED_WORDS + tag.serial_bits / 16;
    if (header & XTID_OPTIONAL_COMMAND_SUPPORT) {
        if ((word + 1) * 2 <= len) {
            const uint16_t ocs = detail::word_at(tid, word);
            // Max EPC Size is what fits in the length field of the PC, so it counts words
            tag.epc_max_bits             = static_cast<uint32_t>(ocs & 0x1F) * 16U;
            tag.supports_block_permalock = (ocs & 0x1000) != 0;
        }
        word += 1;
    }
    if (header & XTID_BLOCKWRITE_BLOCKERASE) {
        word += 4;
    }
    if (header & XTID_USER_MEMORY_BLOCKPERMALOCK) {
        if ((word + 2) * 2 <= len) {
            // The lower address holds bits 31 to 16 and the higher one bits 15 to 0, so the
            // block size comes first and the user memory size second (TDS Table 16-2)
            tag.permalock_block_bits = static_cast<uint32_t>(detail::word_at(tid, word)) * 16U;
            tag.user_memory_bits     = static_cast<uint32_t>(detail::word_at(tid, word + 1)) * 16U;
        }
        word += 2;
    }
    fillSizesFromChip(tag);
    return true;
}
 
enum class LockTarget : uint8_t { KillPassword, AccessPassword, Epc, Tid, User };
 
enum class LockAction : uint8_t {
    Open          = 0x00,  
    PermanentOpen = 0x01,  
    Lock          = 0x02,  
    PermanentLock = 0x03,  
};
 
struct LockSetting {
    LockTarget target{};
    LockAction action{};
 
    LockSetting() = default;
    // Written out because the members carry defaults, which stops C++11 from treating the
    // struct as an aggregate and so rules out LockSetting{target, action} without it
    LockSetting(const LockTarget t, const LockAction a) : target{t}, action{a}
    {
    }
};
 
inline bool isPermanent(const LockAction action)
{
    return action == LockAction::PermanentOpen || action == LockAction::PermanentLock;
}
 
inline uint32_t buildLockPayload(const LockSetting* settings, const size_t count)
{
    uint32_t payload{};
    for (size_t i = 0; i < count; ++i) {
        const uint8_t slot         = static_cast<uint8_t>(settings[i].target);  // 0:Kill ... 4:User
        const uint8_t action       = static_cast<uint8_t>(settings[i].action);
        const uint8_t mask         = static_cast<uint8_t>(0x02 | (action & 0x01));
        const uint8_t mask_shift   = static_cast<uint8_t>(18 - slot * 2);
        const uint8_t action_shift = static_cast<uint8_t>(8 - slot * 2);
        payload |= static_cast<uint32_t>(mask) << mask_shift;
        payload |= static_cast<uint32_t>(action) << action_shift;
    }
    return payload;
}
 
struct QueryParameters {
    uint8_t q{};                   
    Session session{Session::S0};  
    Target target{Target::A};      
    SelectFilter filter{SelectFilter::All};
};
 
constexpr size_t SELECT_MASK_MAX_BYTES{32};
 
constexpr uint16_t NXP_CONFIG_TAMPER_ALARM{0x8000};       
constexpr uint16_t NXP_CONFIG_EXTERNAL_SUPPLY{0x4000};    
constexpr uint16_t NXP_CONFIG_INVERT_OUTPUT{0x0800};      
constexpr uint16_t NXP_CONFIG_TRANSPARENT_MODE{0x0400};   
constexpr uint16_t NXP_CONFIG_RAW_DATA_MODE{0x0200};      
constexpr uint16_t NXP_CONFIG_CONDITIONAL_RANGE{0x0100};  
constexpr uint16_t NXP_CONFIG_CONDITIONAL_SHORT{0x0080};  
constexpr uint16_t NXP_CONFIG_MAX_BACKSCATTER{0x0040};    
constexpr uint16_t NXP_CONFIG_DIGITAL_OUTPUT{0x0020};     
constexpr uint16_t NXP_CONFIG_RANGE_REDUCTION{0x0010};    
constexpr uint16_t NXP_CONFIG_PROTECT_USER{0x0008};       
constexpr uint16_t NXP_CONFIG_PROTECT_EPC{0x0004};        
constexpr uint16_t NXP_CONFIG_PROTECT_TID{0x0002};        
constexpr uint16_t NXP_CONFIG_PSF_ALARM{0x0001};          
 
struct NxpConfigWord {
    bool tamper_alarm{};     
    bool external_supply{};  
    bool invert_output{};
    bool transparent_mode{};
    bool raw_data_mode{};
    bool conditional_range{};  
    bool conditional_short{};  
    bool max_backscatter{};    
    bool digital_output{};
    bool range_reduction{};  
    bool protect_user{};     
    bool protect_epc{};      
    bool protect_tid{};      
    bool psf_alarm{};        
};
 
inline NxpConfigWord decodeNxpConfigWord(const uint16_t word)
{
    NxpConfigWord out{};
    out.tamper_alarm      = (word & NXP_CONFIG_TAMPER_ALARM) != 0;
    out.external_supply   = (word & NXP_CONFIG_EXTERNAL_SUPPLY) != 0;
    out.invert_output     = (word & NXP_CONFIG_INVERT_OUTPUT) != 0;
    out.transparent_mode  = (word & NXP_CONFIG_TRANSPARENT_MODE) != 0;
    out.raw_data_mode     = (word & NXP_CONFIG_RAW_DATA_MODE) != 0;
    out.conditional_range = (word & NXP_CONFIG_CONDITIONAL_RANGE) != 0;
    out.conditional_short = (word & NXP_CONFIG_CONDITIONAL_SHORT) != 0;
    out.max_backscatter   = (word & NXP_CONFIG_MAX_BACKSCATTER) != 0;
    out.digital_output    = (word & NXP_CONFIG_DIGITAL_OUTPUT) != 0;
    out.range_reduction   = (word & NXP_CONFIG_RANGE_REDUCTION) != 0;
    out.protect_user      = (word & NXP_CONFIG_PROTECT_USER) != 0;
    out.protect_epc       = (word & NXP_CONFIG_PROTECT_EPC) != 0;
    out.protect_tid       = (word & NXP_CONFIG_PROTECT_TID) != 0;
    out.psf_alarm         = (word & NXP_CONFIG_PSF_ALARM) != 0;
    return out;
}
 
struct QTParameters {
    bool short_range{};
    bool public_memory{};
};
 
struct SelectParameter {
    uint8_t target{};            
    uint8_t action{};            
    Bank bank{Bank::Epc};        
    uint32_t pointer_bits{};     
    uint8_t mask_length_bits{};  
    bool truncate{};             
    std::array<uint8_t, SELECT_MASK_MAX_BYTES> mask{};  
    uint8_t mask_size{};                                
 
    std::string maskAsString() const;
};
 
struct ModuleInformation {
    std::string hardware_version{};
    std::string software_version{};
    std::string manufacturer{};
};
 
struct ChannelLevels {
    uint8_t first_channel{};    
    std::vector<int8_t> dbm{};  
};
 
namespace detail {
inline std::string to_hex(const uint8_t* data, const size_t len)
{
    static const char digits[] = "0123456789ABCDEF";
    std::string s{};
    s.reserve(len * 2);
    for (size_t i = 0; i < len; ++i) {
        s += digits[(data[i] >> 4) & 0x0F];
        s += digits[data[i] & 0x0F];
    }
    return s;
}
}  // namespace detail
 
inline bool Epc::assign(const uint8_t* src, const size_t len)
{
    if (!src || len > EPC_MAX_BYTES) {
        return false;
    }
    data.fill(0);
    for (size_t i = 0; i < len; ++i) {
        data[i] = src[i];
    }
    size = static_cast<uint8_t>(len);
    return true;
}
 
inline bool Epc::operator==(const Epc& o) const
{
    if (size != o.size) {
        return false;
    }
    for (size_t i = 0; i < size; ++i) {
        if (data[i] != o.data[i]) {
            return false;
        }
    }
    return true;
}
 
inline std::string Epc::toString() const
{
    return detail::to_hex(data.data(), size);
}
 
inline bool Tid::assign(const uint8_t* src, const size_t len)
{
    if (!src || len > TID_MAX_BYTES) {
        return false;
    }
    data.fill(0);
    for (size_t i = 0; i < len; ++i) {
        data[i] = src[i];
    }
    size = static_cast<uint8_t>(len);
    return true;
}
 
inline bool Tid::operator==(const Tid& o) const
{
    if (size != o.size) {
        return false;
    }
    for (size_t i = 0; i < size; ++i) {
        if (data[i] != o.data[i]) {
            return false;
        }
    }
    return true;
}
 
inline std::string SelectParameter::maskAsString() const
{
    return detail::to_hex(mask.data(), mask_size);
}
 
inline std::string Tid::toString() const
{
    return detail::to_hex(data.data(), size);
}
 
inline std::string Tag::vendorAsString() const
{
    size_t count{};
    const detail::VendorEntry* entries = detail::vendorEntries(count);
    for (size_t i = 0; i < count; ++i) {
        if (entries[i].vendor == vendor) {
            return entries[i].name;
        }
    }
    return "Unknown";
}
 
inline Support tagBlockPermalockSupport(const Tag& tag)
{
    if (tag.supports_block_permalock) {
        return Support::Yes;
    }
    return chipBlockPermalockSupport(tag.chip);
}
 
inline Support tagQTSupport(const Tag& tag)
{
    if (tag.vendor != Vendor::Unknown && tag.vendor != Vendor::Impinj) {
        return Support::No;
    }
    return chipQTSupport(tag.chip);
}
 
inline Support tagNxpCustomCommandSupport(const Tag& tag)
{
    if (tag.vendor != Vendor::Unknown && tag.vendor != Vendor::NXP) {
        return Support::No;
    }
    return chipNxpCustomCommandSupport(tag.chip);
}
 
inline std::string Tag::chipAsString() const
{
    switch (chip) {
        case Chip::AlienHiggs3:
            return "Alien Higgs-3";
        case Chip::AlienHiggs9:
            return "Alien Higgs-9";
        case Chip::AlienHiggs4:
            return "Alien Higgs-4";
        case Chip::Em4423SmallEpc:
            return "EM Microelectronic EM4423 (small EPC)";
        case Chip::Em4423LargeEpc:
            return "EM Microelectronic EM4423 (large EPC)";
        case Chip::ImpinjMonza4D:
            return "Impinj Monza 4D";
        case Chip::ImpinjMonza4E:
            return "Impinj Monza 4E";
        case Chip::ImpinjMonza4i:
            return "Impinj Monza 4i";
        case Chip::ImpinjMonza4QT:
            return "Impinj Monza 4QT";
        case Chip::ImpinjM730:
            return "Impinj M730";
        case Chip::ImpinjM750:
            return "Impinj M750";
        case Chip::ImpinjM770:
            return "Impinj M770";
        case Chip::ImpinjM780:
            return "Impinj M780";
        case Chip::ImpinjM781:
            return "Impinj M781";
        case Chip::NxpUcodeG2iM:
            return "NXP UCODE G2iM";
        case Chip::NxpUcodeG2iMPlus:
            return "NXP UCODE G2iM+";
        case Chip::NxpUcode7:
            return "NXP UCODE 7";
        case Chip::NxpUcode8:
            return "NXP UCODE 8";
        case Chip::NxpUcode7xm1k:
            return "NXP UCODE 7xm-1k";
        case Chip::NxpUcode7xm2k:
            return "NXP UCODE 7xm-2k";
        case Chip::NxpUcode7xmPlus:
            return "NXP UCODE 7xm+";
        case Chip::NxpUcode8m:
            return "NXP UCODE 8m";
        case Chip::NxpUcode9:
            return "NXP UCODE 9";
        case Chip::NxpUcode9xe:
            return "NXP UCODE 9xe";
        default:
            return "Unknown";
    }
}
 
constexpr uint16_t GEN2_CRC16_INIT{0xFFFF};
constexpr uint16_t GEN2_CRC16_POLYNOMIAL{0x1021};
constexpr uint16_t GEN2_CRC16_XOROUT{0xFFFF};
 
inline uint16_t gen2_crc16(const uint8_t* data, const size_t len)
{
    m5::utility::CRC16 crc{GEN2_CRC16_INIT, GEN2_CRC16_POLYNOMIAL, false, false, GEN2_CRC16_XOROUT};
    return crc.range(data, len);
}
 
inline bool verify_tag_crc(const Tag& tag)
{
    if (tag.epc.empty()) {
        return false;
    }
    // The Gen2 CRC-16 covers the PC followed by the EPC, so they are laid out contiguously
    uint8_t buf[2 + EPC_MAX_BYTES]{};
    buf[0] = static_cast<uint8_t>(tag.pc >> 8);
    buf[1] = static_cast<uint8_t>(tag.pc & 0xFF);
    for (size_t i = 0; i < tag.epc.size; ++i) {
        buf[2 + i] = tag.epc[i];
    }
    return gen2_crc16(buf, tag.epc.size + 2U) == tag.crc;
}
 
inline uint8_t pcEPCLengthWords(const uint16_t pc)
{
    return static_cast<uint8_t>((pc >> 11) & 0x1F);
}
 
inline bool pcUserMemoryIndicator(const uint16_t pc)
{
    return (pc & 0x0400) != 0;
}
 
inline bool pcXPCIndicator(const uint16_t pc)
{
    return (pc & 0x0200) != 0;
}
 
inline bool pcToggle(const uint16_t pc)
{
    return (pc & 0x0100) != 0;
}
 
inline uint16_t pcNumberingSystemIdentifier(const uint16_t pc)
{
    return static_cast<uint16_t>(pc & 0x01FF);
}
 
inline bool append_unique(std::vector<Tag>& dst, const Tag& tag)
{
    if (tag.epc.empty()) {
        return false;
    }
    for (size_t i = 0; i < dst.size(); ++i) {
        if (dst[i].epc == tag.epc) {
            return false;
        }
    }
    dst.push_back(tag);
    return true;
}
 
}  // namespace uhf
}  // namespace m5
#endif