extend hidprox scan with match info

Add optional HIDPROX_SCAN flags for match metadata, align HPP32 with Proxmark3, and score 32-bit auto-detect to prefer the closest format. CLI shows all matches with confidence when no format hint is provided. Accept zero-length HIDPROX_SCAN payloads for GUI compatibility.

Author: vidonnus

firmware/application/src/app_cmd.c

@@ -14,6 +14,8 @@
 #include "settings.h"
 #include "delayed_reset.h"
 #include "netdata.h"
+#include "protocols/hidprox.h"
+#include "protocols/wiegand.h"
 
 
 #define NRF_LOG_MODULE_NAME app_cmd
@@ -705,13 +707,57 @@ static data_frame_tx_t *cmd_processor_hidprox_write_to_t55xx(uint16_t cmd, uint1
     return data_frame_make(cmd, status, 0, NULL);
 }
 
+#define HIDPROX_SCAN_FLAG_ALL_MATCHES (0x01)
+
+static uint16_t append_hidprox_matches(uint8_t *buffer, uint16_t buffer_size) {
+    wiegand_match_info_t info = {0};
+    if (!wiegand_get_match_info(&info)) {
+        return 0;
+    }
+
+    uint16_t index = 13;
+    if (index + 8 > buffer_size) {
+        return 0;
+    }
+
+    buffer[index++] = 0xD2;
+    buffer[index++] = info.count;
+    num_to_bytes(info.raw, 6, buffer + index);
+    index += 6;
+
+    for (uint8_t i = 0; i < info.count; i++) {
+        if (index + 9 > buffer_size) {
+            break;
+        }
+        buffer[index++] = info.entries[i].format;
+        buffer[index++] = info.entries[i].has_parity;
+        buffer[index++] = info.entries[i].fixed_mismatches;
+        num_to_bytes(info.entries[i].repacked, 6, buffer + index);
+        index += 6;
+    }
+
+    return index;
+}
+
 static data_frame_tx_t *cmd_processor_hidprox_scan(uint16_t cmd, uint16_t status, uint16_t length, uint8_t *data) {
-    uint8_t card_data[16] = {0x00};
-    status = scan_hidprox(card_data, data[0]);
+    uint8_t card_data[HIDPROX_DATA_SIZE] = {0x00};
+    if (length > 2) {
+        return data_frame_make(cmd, STATUS_PAR_ERR, 0, NULL);
+    }
+    uint8_t format_hint = (length >= 1) ? data[0] : 0;
+    uint8_t flags = (length == 2) ? data[1] : 0;
+    status = scan_hidprox(card_data, format_hint);
     if (status != STATUS_LF_TAG_OK) {
         return data_frame_make(cmd, status, 0, NULL);
     }
-    return data_frame_make(cmd, STATUS_LF_TAG_OK, sizeof(card_data), card_data);
+    uint16_t out_len = 13;
+    if ((flags & HIDPROX_SCAN_FLAG_ALL_MATCHES) != 0) {
+        uint16_t matches_len = append_hidprox_matches(card_data, sizeof(card_data));
+        if (matches_len > 0) {
+            out_len = matches_len;
+        }
+    }
+    return data_frame_make(cmd, STATUS_LF_TAG_OK, out_len, card_data);
 }
 
 static data_frame_tx_t *cmd_processor_viking_scan(uint16_t cmd, uint16_t status, uint16_t length, uint8_t *data) {

firmware/application/src/rfid/nfctag/lf/protocols/hidprox.h

@@ -4,7 +4,7 @@
 #include "utils/fskdemod.h"
 #include "wiegand.h"
 
-#define HIDPROX_DATA_SIZE (16)
+#define HIDPROX_DATA_SIZE (80)
 
 typedef enum {
     STATE_SOF,
@@ -30,4 +30,4 @@ typedef struct {
 
 extern const protocol hidprox;
 
-uint8_t hidprox_t55xx_writer(wiegand_card_t *card, uint32_t *blks);
+uint8_t hidprox_t55xx_writer(wiegand_card_t *card, uint32_t *blks);

firmware/application/src/rfid/nfctag/lf/protocols/wiegand.c

@@ -35,12 +35,64 @@ const uint8_t indasc27_cn_map[14] = {3, 15, 5, 8, 24, 1, 13, 6, 9, 12, 11, 23, 2
 const uint8_t tecom27_fc_map[11] = {24, 23, 12, 16, 20, 8, 4, 3, 2, 7, 11};
 const uint8_t tecom27_cn_map[16] = {21, 22, 15, 18, 19, 1, 5, 9, 10, 6, 0, 17, 14, 13, 25, 26};
 
+static wiegand_match_info_t g_wiegand_match_info = {0};
+
+static void match_reset(uint64_t raw) {
+    g_wiegand_match_info.valid = 1;
+    g_wiegand_match_info.count = 0;
+    g_wiegand_match_info.raw = raw;
+    memset(g_wiegand_match_info.entries, 0, sizeof(g_wiegand_match_info.entries));
+}
+
+static void match_add(uint8_t format, bool has_parity, uint8_t fixed_mismatches, uint64_t repacked) {
+    if (!g_wiegand_match_info.valid) {
+        return;
+    }
+    if (g_wiegand_match_info.count >= WIEGAND_MATCH_MAX_FORMATS) {
+        return;
+    }
+    wiegand_match_entry_t *entry = &g_wiegand_match_info.entries[g_wiegand_match_info.count++];
+    entry->format = format;
+    entry->has_parity = has_parity ? 1 : 0;
+    entry->fixed_mismatches = fixed_mismatches;
+    entry->repacked = repacked;
+}
+
+static uint64_t validation_mask(uint8_t length, card_format_t format) {
+    if (length != 32) {
+        return (1ULL << 38) - 1; // HID Prox payload size (preamble + Wiegand)
+    }
+
+    switch (format) {
+        case HCP32:
+            return ((1ULL << 24) - 1) << 7; // CN bits (30..7)
+        case HPP32:
+            return (1ULL << 31) - 1; // FC+CN bits (30..0)
+        case KANTECH:
+            return ((1ULL << 24) - 1) << 1; // FC+CN bits (24..1)
+        case WIE32:
+            return (1ULL << 28) - 1; // FC+CN bits (27..0)
+        case KASTLE:
+            return (1ULL << 32) - 1; // full payload (parity + fixed bit)
+        default:
+            return (1ULL << 38) - 1;
+    }
+}
+
 wiegand_card_t *wiegand_card_alloc() {
     wiegand_card_t *card = (wiegand_card_t *)malloc(sizeof(wiegand_card_t));
     memset(card, 0, sizeof(wiegand_card_t));
     return card;
 }
 
+bool wiegand_get_match_info(wiegand_match_info_t *out) {
+    if (!g_wiegand_match_info.valid || out == NULL) {
+        return false;
+    }
+    *out = g_wiegand_match_info;
+    return true;
+}
+
 static uint64_t get_nonlinear_fields(uint64_t n, const uint8_t *map, size_t size) {
     uint64_t bits = 0x0;
     for (int i = 0; (i < size) && (n > 0); i++) {
@@ -276,14 +328,14 @@ static uint64_t pack_hpp32(wiegand_card_t *card) {
     uint64_t bits = PREAMBLE_32BIT;
     bits <<= 1;
     bits = (bits << 12) | (card->facility_code & 0xfff);
-    bits = (bits << 19) | (card->card_number & 0x7ffff);
+    bits = (bits << 19) | ((card->card_number >> 10) & 0x7ffff);
     return bits;
 }
 
 static wiegand_card_t *unpack_hpp32(uint64_t hi, uint64_t lo) {
     wiegand_card_t *d = wiegand_card_alloc();
     d->facility_code = (lo >> 19) & 0xfff;
-    d->card_number = (lo >> 0) & 0x7ffff;
+    d->card_number = ((lo >> 0) & 0x7ffff) << 10;
     return d;
 }
 
@@ -831,7 +883,7 @@ static const card_format_table_t formats[] = {
     {ATSW30, pack_atsw30, unpack_atsw30, 30, {1, 0xFFF, 0xFFFF, 0, 0}},          // ATS Wiegand 30-bit
     {ADT31, pack_adt31, unpack_adt31, 31, {0, 0xF, 0x7FFFFF, 0, 0}},             // HID ADT 31-bit
     {HCP32, pack_hcp32, unpack_hcp32, 32, {0, 0, 0x3FFF, 0, 0}},                 // HID Check Point 32-bit
-    {HPP32, pack_hpp32, unpack_hpp32, 32, {0, 0xFFF, 0x7FFFF, 0, 0}},            // HID Hewlett-Packard 32-bit
+    {HPP32, pack_hpp32, unpack_hpp32, 32, {0, 0xFFF, 0x1FFFFFFF, 0, 0}},         // HID Hewlett-Packard 32-bit
     {KASTLE, pack_kastle, unpack_kastle, 32, {1, 0xFF, 0xFFFF, 0x1F, 0}},        // Kastle 32-bit
     {KANTECH, pack_kantech, unpack_kantech, 32, {0, 0xFF, 0xFFFF, 0, 0}},        // Indala/Kantech KFS 32-bit
     {WIE32, pack_wie32, unpack_wie32, 32, {0, 0xFFF, 0xFFFF, 0, 0}},             // Wiegand 32-bit
@@ -868,6 +920,13 @@ uint64_t pack(wiegand_card_t *card) {
 }
 
 wiegand_card_t *unpack(uint8_t format_hint, uint8_t length, uint64_t hi, uint64_t lo) {
+    if (length == 32 && format_hint == 0) {
+        match_reset(lo);
+    } else {
+        g_wiegand_match_info.valid = 0;
+    }
+    wiegand_card_t *best_card = NULL;
+    uint8_t best_mismatches = 0xFF;
     for (int i = 0; i < ARRAY_SIZE(formats); i++) {
         if (format_hint != 0 && format_hint != formats[i].format) {
             continue;
@@ -883,7 +942,40 @@ wiegand_card_t *unpack(uint8_t format_hint, uint8_t length, uint64_t hi, uint64_
             continue;
         }
         card->format = formats[i].format;
+        if (formats[i].pack != NULL) {
+            uint64_t repacked = formats[i].pack(card);
+            if (repacked == 0) {
+                free(card);
+                continue;
+            }
+            uint64_t mask = validation_mask(length, formats[i].format);
+            bool passed = ((repacked & mask) == (lo & mask));
+            if (!passed) {
+                free(card);
+                continue;
+            }
+            if (length == 32 && format_hint == 0) {
+                uint64_t payload_mask = (1ULL << 38) - 1;
+                uint64_t fixed_mask = payload_mask & ~mask;
+                uint64_t fixed_diff = (repacked ^ lo) & fixed_mask;
+                uint8_t mismatches = (uint8_t)__builtin_popcountll(fixed_diff);
+                match_add(formats[i].format, formats[i].fields.has_parity, mismatches, repacked);
+                if (mismatches < best_mismatches) {
+                    if (best_card != NULL) {
+                        free(best_card);
+                    }
+                    best_card = card;
+                    best_mismatches = mismatches;
+                    continue;
+                }
+                free(card);
+                continue;
+            }
+        }
         return card;
     }
+    if (best_card != NULL) {
+        return best_card;
+    }
     return NULL;
 }

firmware/application/src/rfid/nfctag/lf/protocols/wiegand.h

@@ -84,6 +84,23 @@ typedef struct {
     card_format_descriptor_t fields;
 } card_format_table_t;
 
+#define WIEGAND_MATCH_MAX_FORMATS (5)
+
+typedef struct {
+    uint8_t format;
+    uint8_t has_parity;
+    uint8_t fixed_mismatches;
+    uint64_t repacked;
+} wiegand_match_entry_t;
+
+typedef struct {
+    uint8_t valid;
+    uint8_t count;
+    uint64_t raw;
+    wiegand_match_entry_t entries[WIEGAND_MATCH_MAX_FORMATS];
+} wiegand_match_info_t;
+
 extern uint64_t pack(wiegand_card_t *card);
 extern wiegand_card_t *unpack(uint8_t format_hint, uint8_t length, uint64_t hi, uint64_t lo);
-extern wiegand_card_t *wiegand_card_alloc();
+extern wiegand_card_t *wiegand_card_alloc();
+extern bool wiegand_get_match_info(wiegand_match_info_t *out);

software/script/chameleon_cli_unit.py

@@ -440,7 +440,7 @@ def check_limits(format: int, fc: Union[int, None], cn: Union[int, None], il: Un
             HIDFormat.ATSW30: [0xFFF, 0xFFFF, 0, 0],
             HIDFormat.ADT31: [0xF, 0x7FFFFF, 0, 0],
             HIDFormat.HCP32: [0, 0x3FFF, 0, 0],
-            HIDFormat.HPP32: [0xFFF, 0x7FFFF, 0, 0],
+            HIDFormat.HPP32: [0xFFF, 0x1FFFFFFF, 0, 0],
             HIDFormat.KASTLE: [0xFF, 0xFFFF, 0x1F, 0],
             HIDFormat.KANTECH: [0xFF, 0xFFFF, 0, 0],
             HIDFormat.WIE32: [0xFFF, 0xFFFF, 0, 0],
@@ -3864,11 +3864,18 @@ def args_parser(self) -> ArgumentParserNoExit:
 
     def on_exec(self, args: argparse.Namespace):
         format = 0
+        include_matches = args.format is None
         if args.format is not None:
             format = HIDFormat[args.format].value
-        (format, fc, cn1, cn2, il, oem) = self.cmd.hidprox_scan(format)
+        resp = self.cmd.hidprox_scan(format, include_matches=include_matches)
+
+        (format, fc, cn1, cn2, il, oem) = resp['fields']
         cn = (cn1 << 32) + cn2
-        print(f"HIDProx/{HIDFormat(format)}")
+        try:
+            format_label = str(HIDFormat(format))
+        except ValueError:
+            format_label = f"Unknown({format})"
+        print(f"HIDProx/{format_label}")
         if fc > 0:
             print(f" FC: {color_string((CG, fc))}")
         if il > 0:
@@ -3877,6 +3884,38 @@ def on_exec(self, args: argparse.Namespace):
             print(f" OEM: {color_string((CG, oem))}")
         print(f" CN: {color_string((CG, cn))}")
 
+        if include_matches and resp.get('matches'):
+            def confidence_label(has_parity: int, mismatches: int) -> str:
+                if mismatches == 0 and has_parity:
+                    return 'high'
+                if mismatches == 0 or mismatches == 1:
+                    return 'medium'
+                return f"low (mismatch {mismatches})"
+
+            raw = resp.get('raw')
+            if raw is not None:
+                print(f" Raw: 0x{raw:012X}")
+
+            print(" Matches:")
+            matches = sorted(
+                resp['matches'],
+                key=lambda item: (item['mismatches'], -item['has_parity'])
+            )
+            for item in matches:
+                fmt = item['format']
+                mismatches = item['mismatches']
+                has_parity = item['has_parity']
+                repacked = item['repacked']
+                try:
+                    fmt_name = str(HIDFormat(fmt))
+                except ValueError:
+                    fmt_name = f"format({fmt})"
+                confidence = confidence_label(has_parity, mismatches)
+                parity_label = "parity" if has_parity else "no parity"
+                print(
+                    f"  {fmt_name}: confidence={confidence}, {parity_label}, repacked=0x{repacked:012X}"
+                )
+
 @lf_hid_prox.command("write")
 class LFHIDProxWriteT55xx(LFHIDIdArgsUnit, ReaderRequiredUnit):
     def args_parser(self) -> ArgumentParserNoExit:

software/script/chameleon_cmd.py

@@ -485,15 +485,50 @@ def em410x_write_to_t55xx(self, id_bytes: bytes):
         raise ValueError("The id bytes length must equal 5 (EM410X) or 13 (Electra)")
 
     @expect_response(Status.LF_TAG_OK)
-    def hidprox_scan(self, format: int):
+    def hidprox_scan(self, format: int, include_matches: bool = False):
         """
         Read the length, facility code and card number of HID Prox.
 
         :return:
         """
-        resp = self.device.send_cmd_sync(Command.HIDPROX_SCAN, struct.pack('!B', format))
+        if include_matches:
+            flags = 0x01
+            payload = struct.pack('!BB', format, flags)
+        else:
+            payload = struct.pack('!B', format)
+        resp = self.device.send_cmd_sync(Command.HIDPROX_SCAN, payload)
         if resp.status == Status.LF_TAG_OK:
-            resp.parsed = struct.unpack('>BIBIBH', resp.data[:13])
+            fields = struct.unpack('>BIBIBH', resp.data[:13])
+            matches = []
+            if len(resp.data) >= 21 and resp.data[13] == 0xD2:
+                count = resp.data[14]
+                raw = int.from_bytes(resp.data[15:21], 'big')
+                offset = 21
+                for _ in range(count):
+                    if offset + 9 > len(resp.data):
+                        break
+                    fmt = resp.data[offset]
+                    has_parity = resp.data[offset + 1]
+                    mismatches = resp.data[offset + 2]
+                    repacked = int.from_bytes(resp.data[offset + 3:offset + 9], 'big')
+                    matches.append({
+                        'format': fmt,
+                        'has_parity': has_parity,
+                        'mismatches': mismatches,
+                        'repacked': repacked,
+                    })
+                    offset += 9
+                resp.parsed = {
+                    'fields': fields,
+                    'matches': matches,
+                    'raw': raw,
+                }
+            else:
+                resp.parsed = {
+                    'fields': fields,
+                    'matches': matches,
+                    'raw': None,
+                }
         return resp
 
     @expect_response(Status.LF_TAG_OK)