ndef.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_UNIFIED_NFC_NDEF_NDEF_HPP
#define M5_UNIT_UNIFIED_NFC_NDEF_NDEF_HPP
 
#include <cstdint>
#include <vector>
#include <m5_utility/stl/extension.hpp>
#include <m5_utility/log/library_log.hpp>
 
namespace m5 {
namespace nfc {
namespace ndef {
 
constexpr uint8_t NDEF_MAJOR_VERSION{1};     
constexpr uint8_t NDEF_MINOR_VERSION{0};     
constexpr uint8_t MAGIC_NO_CC4{0xE1};        
constexpr uint8_t MAGIC_NO_CC8{0xE2};        
constexpr uint8_t ACCESS_FREE{0x00};         
constexpr uint8_t ACCESS_PROPRIETARY{0x02};  
 
constexpr uint8_t TYPE2_CC_BLOCK{3};           
constexpr uint16_t CC4_MAX_NDEF_LENGTH{2040};  
 
enum class Tag : uint8_t {
    Null,                
    LockControl,         
    MemoryControl,       
    Message,             
    Proprietary = 0xFD,  
    Terminator           
};
 
using TagBits = uint8_t;
 
constexpr inline TagBits tag_to_tagbit(const Tag t)
{
    return (t == Tag::Null)            ? (1u << 0)
           : (t == Tag::LockControl)   ? (1u << 1)
           : (t == Tag::MemoryControl) ? (1u << 2)
           : (t == Tag::Message)       ? (1u << 3)
           : (t == Tag::Proprietary)   ? (1u << 4)
           : (t == Tag::Terminator)    ? (1u << 5)
                                       : 0u;
}
 
template <typename... Ts>
struct are_all_tag : std::true_type { 
};
template <typename T, typename... Ts>
struct are_all_tag<T, Ts...> : std::integral_constant<bool, std::is_same<Tag, T>::value && are_all_tag<Ts...>::value> {
};
 
constexpr TagBits make_tag_bits_impl(TagBits acc)
{
    return acc;
}
 
template <typename... Rest>
constexpr TagBits make_tag_bits_impl(TagBits acc, Tag head, Rest... rest)
{
    return make_tag_bits_impl(acc | tag_to_tagbit(head), rest...);
}
 
template <typename... T>
constexpr TagBits make_tag_bits(T... tags)
{
    static_assert(sizeof...(tags) > 0, "At least one Tag is required");
    static_assert(are_all_tag<T...>::value, "Arguments must be Tag");
    return make_tag_bits_impl(0u, tags...);
}
 
inline constexpr bool contains_tag(const TagBits tb, const Tag t)
{
    return (tb & tag_to_tagbit(t)) != 0;
}
 
constexpr TagBits tagBitsAll =
    make_tag_bits(m5::nfc::ndef::Tag::LockControl, m5::nfc::ndef::Tag::MemoryControl, m5::nfc::ndef::Tag::Message,
                  m5::nfc::ndef::Tag::Proprietary, m5::nfc::ndef::Tag::Terminator);
constexpr TagBits tagBitsMessage = make_tag_bits(m5::nfc::ndef::Tag::Message);
 
inline bool is_valid_tag(const uint8_t t)
{
    return t <= m5::stl::to_underlying(Tag::Message) || t == m5::stl::to_underlying(Tag::Proprietary) ||
           t == m5::stl::to_underlying(Tag::Terminator);
}
 
inline bool is_terminator_tag(const uint8_t t)
{
    return t == m5::stl::to_underlying(Tag::Terminator);
}
 
enum class URIProtocol : uint8_t {
    NA,           
    HTTP_WWW,     
    HTTPS_WWW,    
    HTTP,         
    HTTPS,        
    TEL,          
    MAILTO,       
    FTP_AA,       
    FTP_FTP,      
    FTPS,         
    SFTP,         
    SMB,          
    NFS,          
    FTP,          
    DEV,          
    NEWS,         
    TELNET,       
    IMAP,         
    RSTP,         
    URN,          
    POP,          
    SIP,          
    SIPS,         
    TFTP,         
    BTSPP,        
    BTL2CAP,      
    BTGOEP,       
    TCPOBEX,      
    IRDAOBEX,     
    FILE,         
    URN_EPC_ID,   
    URN_EPC_TAG,  
    URN_EPC_PAT,  
    URN_EPC_RAW,  
    URN_EPC,      
    NFC,          
};
 
const char* get_uri_idc_string(const URIProtocol protocol);
 
namespace type2 {
struct CapabilityContainer {
    uint8_t block[4]{};
 
    inline bool valid() const
    {
        return (block[0] == MAGIC_NO_CC4) && (major_version() >= NDEF_MAJOR_VERSION) &&
               ((int16_t)minor_version() >= NDEF_MINOR_VERSION) && ndef_size();
    }
    inline bool can_read() const
    {
        return read_access() == ACCESS_FREE;
    }
    inline bool can_write() const
    {
        return write_access() == ACCESS_FREE;
    }
 
    // Getter
    inline uint8_t major_version() const
    {
        return (block[1] >> 4) & 0x0F;
    }
    inline uint8_t minor_version() const
    {
        return block[1] & 0x0F;
    }
    inline uint16_t ndef_size() const
    {
        return (uint16_t)block[2] << 3;
    }
    inline uint8_t read_access() const
    {
        return (block[3] >> 4) & 0x0F;
    }
    inline uint8_t write_access() const
    {
        return block[3] & 0x0F;
    }
    // Setter
    inline void major_version(const uint8_t v)
    {
        block[1] = (block[1] & 0x0F) | ((v & 0x0F) << 4);
    }
    inline void minor_version(const uint8_t v)
    {
        block[1] = (block[1] & 0xF0) | (v & 0x0F);
    }
    inline void ndef_size(const uint16_t sz)
    {
        block[2] = (sz > 2040) ? 0 : (sz >> 3);
    }
    inline void read_access(const uint8_t a)
    {
        block[3] = (block[3] & 0x0F) | ((a & 0x03) << 4);
    }
    inline void write_access(const uint8_t a)
    {
        block[3] = (block[3] & 0xF0) | (a & 0x03);
    }
};
}  // namespace type2
 
namespace type3 {
struct AttributeBlock {
    uint8_t block[16]{};
 
    static constexpr uint8_t DEFAULT_VERSION{0x10};
 
    enum class WriteFlag : uint8_t {
        Done,               
        InProgress = 0x0F,  
    };
 
    enum class AccessFlag : uint8_t {
        ReadOnly,   
        ReadWrite,  
    };
    AttributeBlock() : block{DEFAULT_VERSION}
    {
    }
 
    // Getter
    inline uint8_t version() const
    {
        return block[0];
    }
    inline uint8_t max_block_to_read() const
    {
        return block[1];
    }
    inline uint8_t max_block_to_write() const
    {
        return block[2];
    }
    inline uint16_t blocks_for_ndef_storage() const
    {
        return ((uint16_t)block[3] << 8) | block[4];
    }
    inline WriteFlag write_flag() const
    {
        return (block[9] == 0) ? WriteFlag::Done : WriteFlag::InProgress;
    }
    inline AccessFlag access_flag() const
    {
        return (AccessFlag)block[10];
    }
    inline uint32_t current_ndef_message_length() const
    {
        return ((uint32_t)block[11] << 16) | ((uint32_t)block[12] << 8) | block[13];
    }
    inline uint16_t check_sum() const
    {
        return ((uint16_t)block[14] << 8) | block[15];
    }
 
    // Setter
    inline void version(const uint8_t ver)
    {
        block[0] = ver;
    }
    inline void max_block_to_read(const uint8_t b)
    {
        block[1] = b;
    }
    inline void max_block_to_write(const uint8_t b)
    {
        block[2] = b;
    }
    inline void blocks_for_ndef_storage(const uint16_t s)
    {
        block[3] = s >> 8;
        block[4] = s & 0xFF;
    }
    inline void write_flag(const WriteFlag f)
    {
        block[9] = m5::stl::to_underlying(f);
    }
    inline void access_flag(const AccessFlag f)
    {
        block[10] = m5::stl::to_underlying(f);
    }
    inline void current_ndef_message_length(const uint32_t len)
    {
        block[11] = len >> 16;
        block[12] = len >> 8;
        block[13] = len & 0xFF;
    }
 
    //
    bool valid() const;
    uint16_t calculate_check_sum() const;
    uint16_t update_check_sum();
};
 
}  // namespace type3
 
namespace type4 {
 
constexpr uint16_t CC_FILE_ID{0xE103};                                      
constexpr uint8_t NDEF_AID[] = {0xD2, 0x76, 0x00, 0x00, 0x85, 0x01, 0x01};  
constexpr uint16_t NDEF_APP_FID{0xE110};                                    
constexpr uint16_t NDEF_FILE_ID{0xE104};                                    
 
enum class FileControlTag : uint8_t {
    Message     = 0x04,  
    Proprietary = 0x05,  
    //    Extended    = 0x06,  //!< Extended NDEF (Over 32KB) Type 4 Tag Specification v2.0 or later
    Invalid = 0xFF,  
};
 
using FileControlTagBits = uint8_t;
 
constexpr inline FileControlTagBits fc_to_fcbit(const FileControlTag t)
{
    return (t == FileControlTag::Message) ? (1u << 0) : ((t == FileControlTag::Proprietary) ? (1u << 1) : 0u);
}
 
template <typename... Ts>
struct are_all_fc : std::true_type { 
};
template <typename T, typename... Ts>
struct are_all_fc<T, Ts...>
    : std::integral_constant<bool, std::is_same<FileControlTag, T>::value && are_all_fc<Ts...>::value> { 
};
 
constexpr FileControlTagBits make_fc_bits_impl(FileControlTagBits acc)
{
    return acc;
}
 
template <typename... Rest>
constexpr FileControlTagBits make_fc_bits_impl(FileControlTagBits acc, FileControlTag head, Rest... rest)
{
    return make_fc_bits_impl(acc | fc_to_fcbit(head), rest...);
}
 
template <typename... T>
constexpr FileControlTagBits make_fc_bits(T... fcs)
{
    static_assert(sizeof...(fcs) > 0, "At least one Fc is required");
    static_assert(are_all_fc<T...>::value, "Arguments must be Fc");
    return make_fc_bits_impl(0u, fcs...);
}
 
inline constexpr bool contains_file_control_tag(const FileControlTagBits tb, const FileControlTag t)
{
    return (tb & fc_to_fcbit(t)) != 0;
}
 
constexpr FileControlTagBits fcBitsAll = make_fc_bits(FileControlTag::Message, FileControlTag::Proprietary);
constexpr FileControlTagBits fcBitsMessage = make_fc_bits(FileControlTag::Message);
 
struct FileControlTLV {
    uint8_t tag{};              
    uint8_t len{};              
    uint16_t ndef_file_id{};    
    uint16_t ndef_file_size{};  
    uint8_t read_access{};      
    uint8_t write_access{};     
 
    inline FileControlTag fctag() const
    {
        if (this->tag == 0x04 || this->tag == 0x05) {
            return static_cast<FileControlTag>(this->tag);
        }
        return FileControlTag::Invalid;
    }
};
 
struct CapabilityContainer {
    uint16_t cclen{};           
    uint8_t mapping_version{};  
    uint16_t mle{};             
    uint16_t mlc{};             
    std::vector<FileControlTLV> fctlvs{};
 
    inline uint8_t major_version() const
    {
        return (mapping_version >> 4) & 0x0F;
    }
    inline uint8_t minor_version() const
    {
        return mapping_version & 0x0F;
    }
    inline bool valid() const
    {
        return cclen > 7 && !this->fctlvs.empty();
    }
 
    inline FileControlTLV fctlv(const uint8_t index) const
    {
        return index < this->fctlvs.size() ? this->fctlvs[index] : FileControlTLV{};
    }
    FileControlTLV fctlv(const FileControlTag fc = FileControlTag::Message) const;
 
    bool parse(const uint8_t* buf, const uint16_t len);
};
 
}  // namespace type4
 
namespace type5 {
struct CapabilityContainer {
    uint8_t block[8]{};
 
    inline bool valid() const
    {
        return ((block[0] == MAGIC_NO_CC4) || (block[0] == MAGIC_NO_CC8)) && (major_version() >= NDEF_MAJOR_VERSION) &&
               ((int16_t)minor_version() >= NDEF_MINOR_VERSION) && ndef_size();
    }
    inline bool can_read() const
    {
        return read_access() == ACCESS_FREE;
    }
    inline bool can_write() const
    {
        return write_access() == ACCESS_FREE;
    }
    inline uint8_t size() const
    {
        return (block[0] == MAGIC_NO_CC4) ? 4 : ((block[0] == MAGIC_NO_CC8) ? 8 : 0);
    }
    // Getter
    inline uint8_t major_version() const
    {
        return (block[1] >> 6) & 0x03;
    }
    inline uint8_t minor_version() const
    {
        return (block[1] >> 4) & 0x03;
    }
    inline uint16_t ndef_size() const
    {
        // MLEN counts the memory in units of 8 bytes whatever the size of the CC
        return (block[0] == MAGIC_NO_CC4)   ? ((uint16_t)block[2] << 3)
               : (block[0] == MAGIC_NO_CC8) ? ((uint16_t)(((uint16_t)block[6] << 8) | block[7]) << 3)
                                            : 0;
    }
    inline uint8_t read_access() const
    {
        return (block[1] >> 2) & 0x03;
    }
    inline uint8_t write_access() const
    {
        return block[1] & 0x03;
    }
    inline uint8_t additional_feature() const
    {
        return block[3];
    }
    // Setter
    inline void major_version(const uint8_t v)
    {
        block[1] = (block[1] & 0x3F) | ((v & 0x03) << 6);
    }
    inline void minor_version(const uint8_t v)
    {
        block[1] = (block[1] & 0xCF) | ((v & 0x03) << 4);
    }
    inline void ndef_size(const uint16_t sz)
    {
        if (block[0] == MAGIC_NO_CC4 && sz <= 2040) {
            block[2] = (sz >> 3);
        } else if (block[0] == MAGIC_NO_CC8) {
            const uint16_t mlen = sz >> 3;
            block[6]            = (mlen >> 8);
            block[7]            = mlen & 0xFF;
        } else {
            // A four byte container holds MLEN in one byte, so anything above 2040 needs the eight
            // byte form. Say so rather than leave the caller thinking the size was taken
            M5_LIB_LOGW("Cannot store %u bytes in a %02X capability container", sz, block[0]);
        }
    }
    inline void read_access(const uint8_t a)
    {
        block[1] = (block[1] & 0xF3) | ((a & 0x03) << 2);
    }
    inline void write_access(const uint8_t a)
    {
        block[1] = (block[1] & 0xFC) | (a & 0x03);
    }
    inline void additional_feature(const uint8_t af)
    {
        block[3] = af;
    }
};
}  // namespace type5
 
}  // namespace ndef
}  // namespace nfc
}  // namespace m5
 
#endif