Read real Toy Pad tag content; document known issues

The Toy Pad's READ command args were documented as
[mode, tagIndex, page] in the reference projects we copied from;
the actual order is [mode, page, tagIndex]. With the wrong order,
the portal silently returns pages 0-3 regardless of the requested
page — so the driver had literally never been reading real NTAG213
content past page 3, just pages 0-3 repeated 11x and labeled a
"character." Correcting the order yields genuine 180-byte NTAG213
dumps with unique CRCs per tag.

While here, make the scanner actually useful for non-Lego tags:

- Classify tags using the marker byte from the portal's 0x56 event:
  NTAG (Lego), MIFARE Classic Disney, foreign MIFARE, 4-byte MIFARE.
  Non-Lego tags short-circuit with device-agnostic messages instead
  of being labeled as Lego characters.
- Validate the returned page-0 UID against the anti-collision UID,
  because the portal doesn't reliably honor tagIndex when multiple
  tags are on the pad — it returns data for whichever tag its NFC
  controller happens to be locked onto. Mismatches now show
  "another tag on the portal is blocking this read" instead of
  silently presenting another tag's bytes.
- Clear the failed-UID cache when a non-NTAG tag is removed, so a
  Disney tag being lifted off unblocks NTAG tags that had been
  failing via NFC coexistence.
- Display the UID in the error state.
- Tighten the portal-command msg-id range to 0x20..0x7F so late
  auto-read responses (which the portal sends with IDs starting at
  0x86) can't masquerade as our outstanding READ.

Plus a top-of-file TODO block in the driver cataloguing the known
limitations that weren't fixed in this pass: no multi-tag
addressing, Disney coexistence poisoning NTAG reads, unverified
PWD_AUTH arg order, leaked HID listener on reconnect, no auto-
retry after coexistence clears, Amiibo content not read.

Author: pathawks

src/components/wizard/toypad-scanner.tsx

@@ -88,7 +88,12 @@ function PadCard({ padId, state }: { padId: PadId; state: PadState }) {
         )}
 
         {state.phase === "error" && (
-          <p className="py-4 text-sm text-destructive">{state.error}</p>
+          <div className="flex flex-col gap-2 py-4">
+            <p className="text-sm text-destructive">{state.error}</p>
+            {state.uid && (
+              <InfoLine label="UID" value={formatUid(state.uid)} mono />
+            )}
+          </div>
         )}
 
         {state.phase === "done" && state.result && (
@@ -145,6 +150,10 @@ function PadResultCard({
   );
 }
 
+function formatUid(hex: string): string {
+  return hex.match(/.{2}/g)?.join(":") ?? hex;
+}
+
 function InfoLine({
   label,
   value,

src/hooks/use-toypad-scanner.ts

@@ -1,7 +1,11 @@
 import { useState, useEffect, useCallback, useMemo } from "react";
 import type { DeviceDriver, OutputFile, VerificationHashes } from "@/lib/types";
 import type { ToyPadDriver } from "@/lib/drivers/toypad/toypad-driver";
-import type { PadId, TagEvent } from "@/lib/drivers/toypad/toypad-commands";
+import type {
+  PadId,
+  TagEvent,
+  TagKind,
+} from "@/lib/drivers/toypad/toypad-commands";
 import {
   PAD_CENTER,
   PAD_LEFT,
@@ -75,19 +79,42 @@ export function useToyPadScanner(
     const readingPads = new Set<PadId>();
 
     const handleTag = async (event: TagEvent) => {
-      const { pad, action, uid, index } = event;
+      const { pad, action, uid, index, kind } = event;
       const uidHex = toHex(uid);
 
       if (action === "removed") {
         failedUids.delete(uidHex);
         readingPads.delete(pad);
         updatePad(pad, EMPTY_PAD);
         tpDriver.setLed(pad, ...LED_IDLE).catch(() => {});
+        // Removing a non-NTAG tag often unblocks NTAG reads that were failing
+        // because the portal's NFC controller can't juggle both families at
+        // once — clear failedUids so the user doesn't have to re-lift every
+        // Lego figure that happened to collide with a Disney / Skylanders tag.
+        //
+        // TODO: auto-retry pads currently in error state here. Right now
+        // clearing `failedUids` is necessary-but-not-sufficient — the UI
+        // still shows the old error until the user physically lifts and
+        // re-places each affected tag to trigger a fresh "placed" event.
+        if (kind !== "ntag") failedUids.clear();
         return;
       }
 
       if (failedUids.has(uidHex) || readingPads.has(pad)) return;
 
+      // Only NTAG tags are readable through the Toy Pad. For anything else
+      // the portal detected (Disney Infinity MIFARE, Skylanders, hotel keys)
+      // the READ command either errors or returns stale data from a prior
+      // tag — so short-circuit and show what the portal already told us.
+      if (kind !== "ntag") {
+        const msg = unreadableMessage(kind);
+        log(msg, "warn");
+        failedUids.add(uidHex);
+        updatePad(pad, { phase: "error", uid: uidHex, error: msg });
+        tpDriver.setLed(pad, ...LED_ERROR).catch(() => {});
+        return;
+      }
+
       readingPads.add(pad);
       updatePad(pad, {
         phase: "reading",
@@ -105,6 +132,30 @@ export function useToyPadScanner(
           throw new Error("Could not read any data from this tag.");
         }
 
+        // The Toy Pad's READ command doesn't reliably honor the tagIndex arg
+        // when multiple tags are on the portal — it silently returns whichever
+        // tag the NFC controller is currently locked onto. Detect that by
+        // confirming the page-0 UID matches the anti-collision UID we got in
+        // the tag event, and fail loudly if they diverge.
+        //
+        // TODO: find a portal-level "select tag N" command so multi-tag reads
+        // actually work. Until then, users can only reliably read one tag
+        // at a time even though the portal tracks multiple indices.
+        const page0Uid = new Uint8Array([
+          rawData[0],
+          rawData[1],
+          rawData[2],
+          rawData[4],
+          rawData[5],
+          rawData[6],
+          rawData[7],
+        ]);
+        if (!uidsEqual(page0Uid, uid)) {
+          throw new Error(
+            "Another tag on the portal is blocking this read — try removing other tags.",
+          );
+        }
+
         const isPartial = rawData.length < NTAG213_SIZE;
         const parsed = parseLegoDimensionsData(rawData);
         const config = ldSystem.buildReadConfig({ uid, padIndex: index });
@@ -154,3 +205,20 @@ function toHex(bytes: Uint8Array): string {
     .join("")
     .toUpperCase();
 }
+
+function uidsEqual(a: Uint8Array, b: Uint8Array): boolean {
+  return a.length === b.length && a.every((x, i) => x === b[i]);
+}
+
+function unreadableMessage(kind: TagKind): string {
+  switch (kind) {
+    case "mifare-disney":
+      return "Disney Infinity figure — use the Disney Infinity Base to read.";
+    case "mifare-foreign":
+      return "Unsupported MIFARE Classic tag (Skylanders or similar). The Toy Pad can't read MIFARE block data.";
+    case "mifare-4byte":
+      return "Unsupported 4-byte MIFARE Classic tag (e.g. hotel key). The Toy Pad can't read MIFARE block data.";
+    default:
+      return "Unsupported tag type.";
+  }
+}

src/lib/drivers/toypad/toypad-commands.ts

@@ -37,11 +37,46 @@ export const PAD_NAMES: Record<PadId, string> = {
   3: "Right",
 };
 
+/**
+ * Portal's own classification of a detected tag (byte 3 of the 0x56 event).
+ * Same scheme as the Disney Infinity Base portal — both use the PDP NFC
+ * front-end. Only `ntag` tags are readable through the Toy Pad's command
+ * surface; the firmware won't authenticate MIFARE Classic tags, so all
+ * other kinds are informational only (UID via the event, no block data).
+ */
+export type TagKind =
+  | "ntag" // 0x00: NTAG21x / NDEF tag (Lego Dimensions figures)
+  | "mifare-foreign" // 0x01: MIFARE Classic with 7-byte UID (Skylanders etc.)
+  | "mifare-4byte" // 0x08: MIFARE Classic with 4-byte UID (hotel keys etc.)
+  | "mifare-disney" // 0x09: MIFARE Classic authenticated as Disney Infinity
+  | "unknown";
+
+export const MARKER_NTAG = 0x00;
+export const MARKER_MIFARE_FOREIGN = 0x01;
+export const MARKER_MIFARE_4BYTE = 0x08;
+export const MARKER_MIFARE_DISNEY = 0x09;
+
+export function kindFromMarker(marker: number): TagKind {
+  switch (marker) {
+    case MARKER_NTAG:
+      return "ntag";
+    case MARKER_MIFARE_FOREIGN:
+      return "mifare-foreign";
+    case MARKER_MIFARE_4BYTE:
+      return "mifare-4byte";
+    case MARKER_MIFARE_DISNEY:
+      return "mifare-disney";
+    default:
+      return "unknown";
+  }
+}
+
 export interface TagEvent {
   pad: PadId;
   uid: Uint8Array;
   action: "placed" | "removed";
   index: number;
+  kind: TagKind;
 }
 
 // "(c) LEGO 2014" init payload — the portal requires this exact sequence to activate