m100_frame.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_RFID_UNIT_M100_FRAME_HPP
#define M5_UNIT_RFID_UNIT_M100_FRAME_HPP
 
#include <cstddef>
#include <cstdint>
#include <vector>
 
#include "uhf/uhf.hpp"
 
namespace m5 {
namespace unit {
namespace m100 {
 
namespace jrd {
constexpr uint8_t FRAME_HEADER{0xBB};
constexpr uint8_t FRAME_END{0x7E};
}  // namespace jrd
 
inline uint8_t checksum(const uint8_t* body, const size_t len)
{
    uint32_t sum{};
    for (size_t i = 0; i < len; ++i) {
        sum += body[i];
    }
    return static_cast<uint8_t>(sum & 0xFF);
}
 
constexpr uint16_t MAX_PARAMETER_LENGTH{512};
 
inline bool build_frame(std::vector<uint8_t>& out, const uint8_t type, const uint8_t command, const uint8_t* param,
                        const uint16_t param_len, const uint8_t header = jrd::FRAME_HEADER,
                        const uint8_t end = jrd::FRAME_END)
{
    if (param_len > MAX_PARAMETER_LENGTH || (param == nullptr && param_len != 0)) {
        return false;
    }
 
    out.clear();
    out.reserve(static_cast<size_t>(param_len) + 7);
    out.push_back(header);
    out.push_back(type);
    out.push_back(command);
    out.push_back(static_cast<uint8_t>(param_len >> 8));
    out.push_back(static_cast<uint8_t>(param_len & 0xFF));
    for (uint16_t i = 0; i < param_len; ++i) {
        out.push_back(param[i]);
    }
    // The checksum covers Type through the last Parameter byte (index 1 onwards)
    out.push_back(checksum(out.data() + 1, out.size() - 1));
    out.push_back(end);
    return true;
}
 
constexpr size_t FRAME_OVERHEAD{7};
constexpr size_t FRAME_TYPE_OFFSET{1};
constexpr size_t FRAME_PARAMETER_OFFSET{5};
 
constexpr uint8_t TYPE_COMMAND{0x00};
constexpr uint8_t TYPE_RESPONSE{0x01};
constexpr uint8_t TYPE_NOTIFICATION{0x02};
 
struct Frame {
    uint8_t type{};                    
    uint8_t command{};                 
    std::vector<uint8_t> parameter{};  
};
 
inline bool parse_frame(Frame& out, const uint8_t* raw, const size_t len, const uint8_t header = jrd::FRAME_HEADER,
                        const uint8_t end = jrd::FRAME_END)
{
    if (raw == nullptr || len < FRAME_OVERHEAD) {
        return false;
    }
    if (raw[0] != header || raw[len - 1] != end) {
        return false;
    }
 
    const uint16_t param_len = static_cast<uint16_t>((raw[3] << 8) | raw[4]);
    if (param_len > MAX_PARAMETER_LENGTH || len != static_cast<size_t>(param_len) + FRAME_OVERHEAD) {
        return false;
    }
    // The checksum covers Type through the last Parameter byte
    if (raw[len - 2] != checksum(raw + FRAME_TYPE_OFFSET, len - 3)) {
        return false;
    }
 
    out.type    = raw[1];
    out.command = raw[2];
    out.parameter.assign(raw + FRAME_PARAMETER_OFFSET, raw + FRAME_PARAMETER_OFFSET + param_len);
    return true;
}
 
enum class FrameExtract : uint8_t {
    Ok,        
    NeedMore,  
};
 
inline FrameExtract extract_frame(Frame& out, std::vector<uint8_t>& buffer, size_t& discarded, const uint8_t header,
                                  const uint8_t end)
{
    discarded = 0;
    for (;;) {
        // Nothing before a header byte can be the start of a frame
        size_t start = 0;
        while (start < buffer.size() && buffer[start] != header) {
            ++start;
        }
        if (start) {
            discarded += start;
            buffer.erase(buffer.begin(), buffer.begin() + static_cast<long>(start));
        }
        if (buffer.size() < FRAME_PARAMETER_OFFSET) {
            return FrameExtract::NeedMore;
        }
        const uint16_t param_len = static_cast<uint16_t>((buffer[3] << 8) | buffer[4]);
        const size_t total       = static_cast<size_t>(param_len) + FRAME_OVERHEAD;
        if (param_len > MAX_PARAMETER_LENGTH) {
            // A length no frame can have says this header byte was data
            discarded += 1;
            buffer.erase(buffer.begin());
            continue;
        }
        if (buffer.size() < total) {
            return FrameExtract::NeedMore;
        }
        if (parse_frame(out, buffer.data(), total, header, end)) {
            buffer.erase(buffer.begin(), buffer.begin() + static_cast<long>(total));
            return FrameExtract::Ok;
        }
        // The checksum or the end byte disagreed, so this was not a frame either
        discarded += 1;
        buffer.erase(buffer.begin());
    }
}
 
constexpr uint8_t COMMAND_SINGLE_POLLING{0x22};
constexpr uint8_t COMMAND_MULTIPLE_POLLING{0x27};
 
constexpr uint8_t COMMAND_READ_TAG_MEMORY{0x39};
constexpr uint8_t COMMAND_WRITE_TAG_MEMORY{0x49};
constexpr uint8_t COMMAND_KILL_TAG{0x65};
constexpr uint8_t COMMAND_LOCK_TAG_MEMORY{0x82};
constexpr uint8_t COMMAND_BLOCK_PERMALOCK{0xD3};
constexpr uint8_t COMMAND_BLOCK_PERMALOCK_LOCK_ANSWER{0xD4};
constexpr uint8_t COMMAND_NXP_CHANGE_CONFIG{0xE0};
constexpr uint8_t COMMAND_NXP_READ_PROTECT{0xE1};
constexpr uint8_t COMMAND_NXP_CHANGE_EAS{0xE3};
constexpr uint8_t COMMAND_NXP_EAS_ALARM{0xE4};
constexpr uint8_t COMMAND_MONZA_QT{0xE5};
constexpr uint8_t COMMAND_MONZA_QT_WRITE_ANSWER{0xE6};
constexpr size_t TAG_NOTIFICATION_OVERHEAD{5};
 
inline bool parse_tag_notification(m5::uhf::Tag& out, const uint8_t* param, const size_t len)
{
    if (param == nullptr || len <= TAG_NOTIFICATION_OVERHEAD) {
        return false;
    }
 
    const size_t epc_len = len - TAG_NOTIFICATION_OVERHEAD;
    // An EPC longer than the standard allows means the frame is not what it claims to be
    if (!out.epc.assign(param + 3, epc_len)) {
        return false;
    }
    out.rssi = static_cast<int8_t>(param[0]);
    out.pc   = static_cast<uint16_t>((param[1] << 8) | param[2]);
    out.crc  = static_cast<uint16_t>((param[3 + epc_len] << 8) | param[4 + epc_len]);
    return true;
}
 
constexpr uint8_t MEMBANK_RESERVED{0x00};
constexpr uint8_t MEMBANK_EPC{0x01};
constexpr uint8_t MEMBANK_TID{0x02};
constexpr uint8_t MEMBANK_USER{0x03};
 
constexpr uint8_t SELECT_TRUNCATE_OFF{0x00};
constexpr uint8_t SELECT_TRUNCATE_ON{0x80};
 
constexpr uint8_t SELECT_MODE_ALWAYS{0x00};         
constexpr uint8_t SELECT_MODE_NEVER{0x01};          
constexpr uint8_t SELECT_MODE_NON_INVENTORY{0x02};  
 
constexpr size_t WRITE_MAX_WORDS{32};
constexpr size_t SELECT_MASK_MAX_BITS{255};
 
inline uint8_t select_parameter_byte(const uint8_t target, const uint8_t action, const uint8_t membank)
{
    return static_cast<uint8_t>(((target & 0x07) << 5) | ((action & 0x07) << 2) | (membank & 0x03));
}
 
inline bool build_select_parameter(std::vector<uint8_t>& out, const uint8_t sel_param, const uint32_t pointer_bits,
                                   const uint8_t mask_length_bits, const uint8_t truncate, const uint8_t* mask,
                                   const size_t mask_len)
{
    if ((sel_param & 0x03) == MEMBANK_RESERVED) {
        return false;
    }
    if (mask_len == 0 || mask == nullptr || mask_length_bits == 0) {
        return false;
    }
    // SELECT_MASK_MAX_BITS is the whole range of the length field, so the type already keeps
    // the mask inside it; only the mask actually being that long still has to be checked
    if ((mask_length_bits + 7U) / 8U > mask_len) {
        return false;
    }
 
    out.clear();
    out.reserve(7 + mask_len);
    out.push_back(sel_param);
    out.push_back(static_cast<uint8_t>(pointer_bits >> 24));
    out.push_back(static_cast<uint8_t>(pointer_bits >> 16));
    out.push_back(static_cast<uint8_t>(pointer_bits >> 8));
    out.push_back(static_cast<uint8_t>(pointer_bits));
    out.push_back(mask_length_bits);
    out.push_back(truncate);
    out.insert(out.end(), mask, mask + mask_len);
    return true;
}
 
inline bool parse_select_parameter(m5::uhf::SelectParameter& out, const uint8_t* param, const size_t len)
{
    // SelParam, a four byte pointer, the mask length, the truncate flag, then the mask itself
    constexpr size_t HEADER_LENGTH{7};
    if (param == nullptr || len < HEADER_LENGTH) {
        return false;
    }
    const size_t mask_len = len - HEADER_LENGTH;
    if (mask_len > m5::uhf::SELECT_MASK_MAX_BYTES) {
        return false;
    }
    // The mask travels as whole bytes, so the length in bits has to account for exactly the
    // bytes that arrived (protocol 2.6.2: a mask of 96 bits comes with twelve of them). Taking
    // a frame where the two disagree would hand the caller a length its own mask cannot back up
    if ((static_cast<size_t>(param[5]) + 7U) / 8U != mask_len) {
        return false;
    }
    out.target       = static_cast<uint8_t>((param[0] >> 5) & 0x07);
    out.action       = static_cast<uint8_t>((param[0] >> 2) & 0x07);
    out.bank         = static_cast<m5::uhf::Bank>(param[0] & 0x03);
    out.pointer_bits = (static_cast<uint32_t>(param[1]) << 24) | (static_cast<uint32_t>(param[2]) << 16) |
                       (static_cast<uint32_t>(param[3]) << 8) | param[4];
    out.mask_length_bits = param[5];
    out.truncate         = param[6] != SELECT_TRUNCATE_OFF;
    out.mask.fill(0);
    for (size_t i = 0; i < mask_len; ++i) {
        out.mask[i] = param[HEADER_LENGTH + i];
    }
    out.mask_size = static_cast<uint8_t>(mask_len);
    return true;
}
 
inline bool build_read_tag_memory(std::vector<uint8_t>& out, const uint32_t access_password, const uint8_t membank,
                                  const uint16_t word_address, const uint16_t word_count)
{
    if (word_count == 0) {
        return false;
    }
    out.clear();
    out.reserve(9);
    out.push_back(static_cast<uint8_t>(access_password >> 24));
    out.push_back(static_cast<uint8_t>(access_password >> 16));
    out.push_back(static_cast<uint8_t>(access_password >> 8));
    out.push_back(static_cast<uint8_t>(access_password));
    out.push_back(membank);
    out.push_back(static_cast<uint8_t>(word_address >> 8));
    out.push_back(static_cast<uint8_t>(word_address));
    out.push_back(static_cast<uint8_t>(word_count >> 8));
    out.push_back(static_cast<uint8_t>(word_count));
    return true;
}
 
inline bool build_write_tag_memory(std::vector<uint8_t>& out, const uint32_t access_password, const uint8_t membank,
                                   const uint16_t word_address, const uint8_t* data, const size_t len)
{
    if (data == nullptr || len == 0 || (len % 2) != 0 || len / 2 > WRITE_MAX_WORDS) {
        return false;
    }
    const uint16_t word_count = static_cast<uint16_t>(len / 2);
    if (!build_read_tag_memory(out, access_password, membank, word_address, word_count)) {
        return false;
    }
    out.insert(out.end(), data, data + len);
    return true;
}
 
inline bool build_lock_tag(std::vector<uint8_t>& out, const uint32_t access_password, const uint32_t payload)
{
    if (payload > 0x000FFFFFU) {
        return false;
    }
    out.clear();
    out.reserve(7);
    out.push_back(static_cast<uint8_t>(access_password >> 24));
    out.push_back(static_cast<uint8_t>(access_password >> 16));
    out.push_back(static_cast<uint8_t>(access_password >> 8));
    out.push_back(static_cast<uint8_t>(access_password));
    out.push_back(static_cast<uint8_t>(payload >> 16));
    out.push_back(static_cast<uint8_t>(payload >> 8));
    out.push_back(static_cast<uint8_t>(payload));
    return true;
}
 
inline bool build_kill_tag(std::vector<uint8_t>& out, const uint32_t kill_password)
{
    if (kill_password == 0) {
        return false;
    }
    out.clear();
    out.reserve(4);
    out.push_back(static_cast<uint8_t>(kill_password >> 24));
    out.push_back(static_cast<uint8_t>(kill_password >> 16));
    out.push_back(static_cast<uint8_t>(kill_password >> 8));
    out.push_back(static_cast<uint8_t>(kill_password));
    return true;
}
 
struct TagOperationResult {
    uint16_t pc{};          
    m5::uhf::Epc epc{};     
    const uint8_t* data{};  
    size_t data_len{};      
};
 
constexpr uint8_t TAG_OPERATION_SUCCESS{0x00};
 
inline bool parse_tag_operation(TagOperationResult& out, const uint8_t* param, const size_t len)
{
    if (param == nullptr || len < 4) {
        return false;
    }
    const size_t ul = param[0];
    // The count covers the two PC bytes as well, so anything smaller cannot be a valid answer
    if (ul < 2 || ul + 1U > len) {
        return false;
    }
    out.pc = static_cast<uint16_t>((param[1] << 8) | param[2]);
    if (!out.epc.assign(param + 3, ul - 2)) {
        return false;
    }
    out.data     = param + 1 + ul;
    out.data_len = len - 1 - ul;
    return true;
}
 
inline void build_nxp_change_config(std::vector<uint8_t>& out, const uint32_t access_password, const uint16_t toggle)
{
    out.clear();
    out.reserve(6);
    out.push_back(static_cast<uint8_t>(access_password >> 24));
    out.push_back(static_cast<uint8_t>(access_password >> 16));
    out.push_back(static_cast<uint8_t>(access_password >> 8));
    out.push_back(static_cast<uint8_t>(access_password));
    out.push_back(static_cast<uint8_t>(toggle >> 8));
    out.push_back(static_cast<uint8_t>(toggle));
}
 
inline void build_nxp_password_and_flag(std::vector<uint8_t>& out, const uint32_t access_password, const uint8_t flag)
{
    out.clear();
    out.reserve(5);
    out.push_back(static_cast<uint8_t>(access_password >> 24));
    out.push_back(static_cast<uint8_t>(access_password >> 16));
    out.push_back(static_cast<uint8_t>(access_password >> 8));
    out.push_back(static_cast<uint8_t>(access_password));
    out.push_back(flag);
}
 
inline bool parse_nxp_change_config(uint16_t& config, const uint8_t* param, const size_t len)
{
    config = 0;
    TagOperationResult r{};
    if (!parse_tag_operation(r, param, len) || r.data_len < 2) {
        return false;
    }
    config = static_cast<uint16_t>((r.data[0] << 8) | r.data[1]);
    return true;
}
 
inline bool parse_nxp_eas_alarm(std::vector<uint8_t>& alarm, const uint8_t* param, const size_t len)
{
    alarm.clear();
    if (param == nullptr || len == 0) {
        return false;
    }
    alarm.assign(param, param + len);
    return true;
}
 
inline bool parse_block_permalock_lock(const uint8_t* param, const size_t len)
{
    TagOperationResult r{};
    if (!parse_tag_operation(r, param, len)) {
        return false;
    }
    return r.data_len >= 1 && r.data[0] == TAG_OPERATION_SUCCESS;
}
 
inline bool parse_block_permalock_read(std::vector<uint8_t>& mask, const uint8_t* param, const size_t len)
{
    mask.clear();
    TagOperationResult r{};
    if (!parse_tag_operation(r, param, len)) {
        return false;
    }
    if (r.data_len < 1) {
        return false;
    }
    const size_t range = r.data[0];
    if (range == 0 || r.data_len < 1 + range * 2) {
        return false;
    }
    mask.assign(r.data + 1, r.data + 1 + range * 2);
    return true;
}
 
constexpr uint8_t QUERY_Q_SHIFT{3};
constexpr uint8_t QUERY_TARGET_SHIFT{7};
constexpr uint8_t QUERY_SESSION_SHIFT{8};
constexpr uint8_t QUERY_SEL_SHIFT{10};
 
inline void parse_query_parameters(m5::uhf::QueryParameters& qp, const uint16_t raw)
{
    qp.q       = static_cast<uint8_t>((raw >> QUERY_Q_SHIFT) & 0x0F);
    qp.target  = static_cast<m5::uhf::Target>((raw >> QUERY_TARGET_SHIFT) & 0x01);
    qp.session = static_cast<m5::uhf::Session>((raw >> QUERY_SESSION_SHIFT) & 0x03);
    qp.filter  = static_cast<m5::uhf::SelectFilter>((raw >> QUERY_SEL_SHIFT) & 0x03);
}
 
inline uint16_t build_query_parameters(const m5::uhf::QueryParameters& qp, const uint16_t current)
{
    uint16_t raw = current;
    raw &= static_cast<uint16_t>(~((0x03U << QUERY_SEL_SHIFT) | (0x03U << QUERY_SESSION_SHIFT) |
                                   (0x01U << QUERY_TARGET_SHIFT) | (0x0FU << QUERY_Q_SHIFT)));
    raw |= static_cast<uint16_t>((static_cast<uint8_t>(qp.filter) & 0x03) << QUERY_SEL_SHIFT);
    raw |= static_cast<uint16_t>((static_cast<uint8_t>(qp.session) & 0x03) << QUERY_SESSION_SHIFT);
    raw |= static_cast<uint16_t>((static_cast<uint8_t>(qp.target) & 0x01) << QUERY_TARGET_SHIFT);
    raw |= static_cast<uint16_t>((qp.q & 0x0F) << QUERY_Q_SHIFT);
    return raw;
}
 
enum class MixerGain : uint8_t {
    dB0,   
    dB3,   
    dB6,   
    dB9,   
    dB12,  
    dB15,  
    dB16,  
};
 
enum class IFGain : uint8_t {
    dB12,  
    dB18,  
    dB21,  
    dB24,  
    dB27,  
    dB30,  
    dB36,  
    dB40,  
};
 
constexpr uint16_t DEMODULATOR_THRESHOLD_DEFAULT{0x01B0};
 
struct DemodulatorParameters {
    MixerGain mixer_gain{MixerGain::dB9};
    IFGain if_gain{IFGain::dB36};
    uint16_t threshold{DEMODULATOR_THRESHOLD_DEFAULT};
};
 
inline uint8_t mixerGainDb(const MixerGain gain)
{
    static const uint8_t db[] = {0, 3, 6, 9, 12, 15, 16};
    const uint8_t i           = static_cast<uint8_t>(gain);
    return i < sizeof(db) ? db[i] : 0;
}
 
inline uint8_t ifGainDb(const IFGain gain)
{
    static const uint8_t db[] = {12, 18, 21, 24, 27, 30, 36, 40};
    const uint8_t i           = static_cast<uint8_t>(gain);
    return i < sizeof(db) ? db[i] : 0;
}
constexpr uint8_t MIXER_GAIN_MAX{0x06};
constexpr uint8_t IF_GAIN_MAX{0x07};
constexpr size_t DEMODULATOR_PARAMETER_LENGTH{4};
 
inline bool parse_demodulator_parameters(DemodulatorParameters& dp, const uint8_t* param, const size_t len)
{
    if (param == nullptr || len < DEMODULATOR_PARAMETER_LENGTH) {
        return false;
    }
    if (param[0] > MIXER_GAIN_MAX || param[1] > IF_GAIN_MAX) {
        return false;
    }
    dp.mixer_gain = static_cast<MixerGain>(param[0]);
    dp.if_gain    = static_cast<IFGain>(param[1]);
    dp.threshold  = static_cast<uint16_t>((param[2] << 8) | param[3]);
    return true;
}
 
inline bool build_demodulator_parameters(std::vector<uint8_t>& out, const DemodulatorParameters& dp)
{
    const uint8_t mixer = static_cast<uint8_t>(dp.mixer_gain);
    const uint8_t amp   = static_cast<uint8_t>(dp.if_gain);
    if (mixer > MIXER_GAIN_MAX || amp > IF_GAIN_MAX) {
        return false;
    }
    out.clear();
    out.reserve(DEMODULATOR_PARAMETER_LENGTH);
    out.push_back(mixer);
    out.push_back(amp);
    out.push_back(static_cast<uint8_t>(dp.threshold >> 8));
    out.push_back(static_cast<uint8_t>(dp.threshold));
    return true;
}
 
constexpr uint8_t COMMAND_ERROR{0xFF};
 
enum class Error : uint8_t {
    WatchDogReset        = 0x05,  
    ReadFail             = 0x09,  
    InvalidParameter     = 0x0E,  
    WriteFail            = 0x10,  
    KillFail             = 0x12,  
    LockFail             = 0x13,  
    BlockPermalockFail   = 0x14,  
    InventoryFail        = 0x15,  
    AccessFail           = 0x16,  
    CommandError         = 0x17,  
    ChangeConfigFail     = 0x1A,  
    ChangeEASFail        = 0x1B,  
    EASAlarmFail         = 0x1D,  
    FHSSFail             = 0x20,  
    ReadProtectFail      = 0x2A,  
    ResetReadProtectFail = 0x2B,  
    QTFail               = 0x2E,  
};
 
inline bool is_error_frame(const uint8_t command)
{
    return command == COMMAND_ERROR;
}
 
inline bool is_no_tag(const uint8_t error_code)
{
    return error_code == static_cast<uint8_t>(Error::InventoryFail);
}
 
constexpr uint8_t TAG_ERROR_READ{0xA0};
constexpr uint8_t TAG_ERROR_WRITE{0xB0};
constexpr uint8_t TAG_ERROR_LOCK{0xC0};
constexpr uint8_t TAG_ERROR_KILL{0xD0};
constexpr uint8_t TAG_ERROR_BLOCK_PERMALOCK{0xE0};
 
inline bool is_tag_error(const uint8_t error_code)
{
    return error_code >= TAG_ERROR_READ && error_code <= (TAG_ERROR_BLOCK_PERMALOCK | 0x0F);
}
 
inline const char* error_description(const uint8_t error_code)
{
    if (is_tag_error(error_code)) {
        switch (error_code & 0x0F) {
            case 0x00:
                return "Tag: other error";
            case 0x03:
                return "Tag: memory overrun";
            case 0x04:
                return "Tag: memory locked";
            case 0x0B:
                return "Tag: insufficient power";
            case 0x0F:
                return "Tag: non-specific error";
            default:
                return "Tag: unlisted error";
        }
    }
    switch (static_cast<Error>(error_code)) {
        case Error::WatchDogReset:
            return "The module's watchdog timed out and reset it";
        case Error::InvalidParameter:
            return "A parameter in the command frame is wrong";
        case Error::ReadFail:
            return "Read failed: no answer, or a CRC error";
        case Error::WriteFail:
            return "Write failed: no answer, or a CRC error";
        case Error::KillFail:
            return "Kill failed: no answer, or a CRC error";
        case Error::LockFail:
            return "Lock failed: no answer, or a CRC error";
        case Error::BlockPermalockFail:
            return "BlockPermalock failed: no answer, or a CRC error";
        case Error::InventoryFail:
            return "No tag answered, or a CRC error";
        case Error::AccessFail:
            return "Access failed; the password may be wrong";
        case Error::CommandError:
            return "Command error in the command frame";
        case Error::FHSSFail:
            return "Frequency hopping channel search timed out";
        case Error::ChangeConfigFail:
            return "ChangeConfig failed: no answer, or a CRC error";
        case Error::ChangeEASFail:
            return "Change EAS failed: no answer, or a CRC error";
        case Error::EASAlarmFail:
            return "EAS_Alarm found no tag answering with an alarm code";
        case Error::ReadProtectFail:
            return "ReadProtect failed: no answer, or a CRC error";
        case Error::ResetReadProtectFail:
            return "Reset ReadProtect failed: no answer, or a CRC error";
        case Error::QTFail:
            return "Monza QT failed: no answer, or a CRC error";
        default:
            return "Unlisted error";
    }
}
 
inline bool error_answers_command(const uint8_t error_code, const uint8_t command)
{
    if (is_tag_error(error_code)) {
        switch (error_code & 0xF0) {
            case TAG_ERROR_READ:
                return command == COMMAND_READ_TAG_MEMORY;
            case TAG_ERROR_WRITE:
                return command == COMMAND_WRITE_TAG_MEMORY;
            case TAG_ERROR_LOCK:
                return command == COMMAND_LOCK_TAG_MEMORY;
            case TAG_ERROR_KILL:
                return command == COMMAND_KILL_TAG;
            case TAG_ERROR_BLOCK_PERMALOCK:
                return command == COMMAND_BLOCK_PERMALOCK;
            default:
                return true;
        }
    }
    switch (static_cast<Error>(error_code)) {
        case Error::ReadFail:
            return command == COMMAND_READ_TAG_MEMORY;
        case Error::WriteFail:
            return command == COMMAND_WRITE_TAG_MEMORY;
        case Error::KillFail:
            return command == COMMAND_KILL_TAG;
        case Error::LockFail:
            return command == COMMAND_LOCK_TAG_MEMORY;
        case Error::BlockPermalockFail:
            // A lock is answered under a code of its own, so both can be waited on
            return command == COMMAND_BLOCK_PERMALOCK || command == COMMAND_BLOCK_PERMALOCK_LOCK_ANSWER;
        case Error::InventoryFail:
            return command == COMMAND_SINGLE_POLLING || command == COMMAND_MULTIPLE_POLLING;
        case Error::AccessFail:
            // Every tag operation is preceded by an access, so any of them can end here
            return command == COMMAND_READ_TAG_MEMORY || command == COMMAND_WRITE_TAG_MEMORY ||
                   command == COMMAND_LOCK_TAG_MEMORY || command == COMMAND_KILL_TAG ||
                   command == COMMAND_BLOCK_PERMALOCK;
        case Error::ChangeConfigFail:
            return command == COMMAND_NXP_CHANGE_CONFIG;
        case Error::ChangeEASFail:
            return command == COMMAND_NXP_CHANGE_EAS;
        case Error::EASAlarmFail:
            return command == COMMAND_NXP_EAS_ALARM;
        case Error::ReadProtectFail:
        case Error::ResetReadProtectFail:
            return command == COMMAND_NXP_READ_PROTECT;
        case Error::QTFail:
            // A write is answered under a code of its own, so both can be waited on
            return command == COMMAND_MONZA_QT || command == COMMAND_MONZA_QT_WRITE_ANSWER;
        case Error::WatchDogReset:
            // The command in flight died with the reset and will never be answered
            return true;
        default:
            // A command error, a wrong parameter or a failed hop answers whatever was sent, and
            // so does a code this table does not name
            return true;
    }
}
 
enum class FrameRoute : uint8_t {
    TagNotification,  
    Response,         
    Drop,             
    Unexpected,       
};
 
inline FrameRoute route_for(const Frame& f, const bool response_pending, const uint8_t awaiting_command)
{
    // The protocol document is inconsistent about the Type byte of a tag notification, so the
    // command code is what routes it
    if (f.command == COMMAND_SINGLE_POLLING || f.command == COMMAND_MULTIPLE_POLLING) {
        return FrameRoute::TagNotification;
    }
    if (is_error_frame(f.command)) {
        const uint8_t code = f.parameter.empty() ? 0x00 : f.parameter[0];
        // Inventory Fail answers a polling command and nothing else: every tag operation has a
        // failure code of its own. It arrives once per empty round, and the rounds already under
        // way keep arriving after a stop, so anywhere but in front of a polling command it is a
        // leftover rather than the answer to whatever was sent last
        const bool awaiting_inventory = response_pending && (awaiting_command == COMMAND_SINGLE_POLLING ||
                                                             awaiting_command == COMMAND_MULTIPLE_POLLING);
        if (is_no_tag(code) && !awaiting_inventory) {
            return FrameRoute::Drop;
        }
        if (!response_pending) {
            return FrameRoute::Drop;
        }
        return error_answers_command(code, awaiting_command) ? FrameRoute::Response : FrameRoute::Drop;
    }
    if (response_pending && f.command == awaiting_command) {
        return FrameRoute::Response;
    }
    // A module answering under a command code nobody is waiting for is exactly how an exchange
    // slips by one frame, so this is worth saying out loud rather than dropping quietly
    return FrameRoute::Unexpected;
}
 
inline bool is_worth_retrying(const uint8_t error_code)
{
    if (is_tag_error(error_code)) {
        return false;
    }
    switch (static_cast<Error>(error_code)) {
        case Error::ReadFail:
        case Error::WriteFail:
        case Error::KillFail:
        case Error::LockFail:
        case Error::BlockPermalockFail:
        case Error::ChangeConfigFail:
        case Error::ChangeEASFail:
        case Error::ReadProtectFail:
        case Error::ResetReadProtectFail:
        case Error::QTFail:
            return true;
        case Error::WatchDogReset:
            // A reset loses the mask, so the same command again would address whichever tag
            // answers rather than the one that was chosen
            return false;
        default:
            return false;
    }
}
 
}  // namespace m100
}  // namespace unit
}  // namespace m5
#endif