fix: send the magic UID frames exactly as the tag vendor documents

The rfidfriend.com instruction sheet shipped with the magic SLIX-L tags
specifies `hf 15 raw -akrc` for both UID frames, step 1 = the 0x41 half
(first four UID bytes), step 2 = the 0x40 half. This repo sent `-acw`,
in the opposite order, and — worse — as two separate pm3 invocations,
which drops the RF field between the halves and can leave the UID
half-written.

- build_uid_frames() now emits `-akrc` and returns the frames in vendor
  order; the byte mapping was already correct and is unchanged.
- write_uid() and `doctor --probe-magic` pass both frames to a single
  pm3 session so `-k` can keep the field up between them.
- HARDWARE.md: correct the flag reference, document the single-session
  requirement, and stop claiming that `csetuid` without `--v2` is
  harmless — the vendor warns against csetuid in any form, and the gen1
  path writes config blocks 0x3E/0x3F.
- CLAUDE.md: add the frame order/session invariant as a hard rule.
- Tests cover the vendor sheet's worked example (E0 04 03 50 12 34 56 78)
  and assert both frames share one session.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012caw768bkSR8AKYiFQh77W

Author: claude

CLAUDE.md

@@ -41,11 +41,14 @@ Preview without touching hardware: `./tonie write "Zuma" --dry-run`.
    layout command `02 E0 09 47 …`, which **permanently bricks magic SLIX-L tags**. The
    UID is written with two raw frames instead; `tonie_writer/proxmark.py` already does
    this correctly. See "Why this repo never calls `csetuid`" in `docs/HARDWARE.md`.
-2. **Data blocks are written before the UID.** Once the tag carries a foreign UID the
+2. **The two UID frames go out together, `0x41` half first** (`-akrc`, one pm3 session),
+   exactly as the rfidfriend.com instruction sheet documents. Splitting them across two
+   pm3 invocations power-cycles the tag mid-write.
+3. **Data blocks are written before the UID.** Once the tag carries a foreign UID the
    blocks may no longer be writable. Do not reorder.
-3. **Block writes are non-addressed** (`hf 15 wrbl --ua`, flags `0x02`, retry with `-o`
+4. **Block writes are non-addressed** (`hf 15 wrbl --ua`, flags `0x02`, retry with `-o`
    = `0x42`). `-*` means "scan, then write addressed" and is not the verified sequence.
-4. **Never write SLIX passwords or enable privacy mode** (`slixwritepwd`,
+5. **Never write SLIX passwords or enable privacy mode** (`slixwritepwd`,
    `passprotectafi`, `passprotecteas`). These are irreversible and are not needed —
    genuine Tonie dumps have `Privacy Mode: false`.
 

docs/HARDWARE.md

@@ -117,14 +117,15 @@ instead.
 | `hf 15 info` | tag present? shows UID, chip type |
 | `hf 15 wrbl --ua -b <0-7> -d AABBCCDD` | write one 4-byte block, non-addressed (flags `0x02`) |
 | `hf 15 wrbl --ua -o -b <0-7> -d AABBCCDD` | same with the OPTION flag (`0x42`) — retry variant |
-| `hf 15 raw -acw -d 02E00940<b7><b6><b5><b4>` | magic UID write, high half |
-| `hf 15 raw -acw -d 02E00941<b3><b2><b1><b0>` | magic UID write, low half |
+| `hf 15 raw -akrc -d 02E00941<b3><b2><b1><b0>` | magic UID write, step 1 (first four UID bytes) |
+| `hf 15 raw -akrc -d 02E00940<b7><b6><b5><b4>` | magic UID write, step 2 (last four UID bytes) |
 | `hf 15 rdbl --ua -b <0-7>` | read one block back (verification) |
 | `hf 15 dump --ns` | read all blocks, don't save to file |
 
-`hf 15 raw` flags: `-a` activate field, `-c` append CRC, `-w` wait longer
-(writes). `--ua` means unaddressed; without it, `hf 15` scans for a tag and
-writes *addressed*, which is not what we want here.
+`hf 15 raw` flags: `-a` activate field, `-k` keep the field on after the
+frame, `-r` don't wait for a reply (the magic UID write doesn't send one),
+`-c` append CRC. `--ua` means unaddressed; without it, `hf 15` scans for a
+tag and writes *addressed*, which is not what we want here.
 
 ### ⚠️ Why this repo never calls `csetuid`
 
@@ -135,27 +136,35 @@ reference implementation, sends only the two UID frames and states
 explicitly that the layout command is "intentionally NOT sent... will brick
 SLIX-L magic cards."
 
-The safe equivalent — what this repo actually sends — is those two frames by
-hand:
+The safe equivalent — what this repo actually sends, and what the printed
+instruction sheet shipped with the rfidfriend.com tags documents — is those
+two frames by hand:
 
 ```
-hf 15 raw -acw -d 02E00940<uid[7]><uid[6]><uid[5]><uid[4]>
-hf 15 raw -acw -d 02E00941<uid[3]><uid[2]><uid[1]><uid[0]>
+hf 15 raw -akrc -d 02E00941<uid[3]><uid[2]><uid[1]><uid[0]>
+hf 15 raw -akrc -d 02E00940<uid[7]><uid[6]><uid[5]><uid[4]>
 ```
 
 Each half is sent **reversed** (`uid[0]` = the first byte of the `.nfc`
 file's `UID:` line = `E0`), because the card stores the UID LSB-first. For
 `UID: E0 04 03 50 20 30 36 1D`:
 
 ```
-hf 15 raw -acw -d 02E009401D363020
-hf 15 raw -acw -d 02E00941500304E0
+hf 15 raw -akrc -d 02E00941500304E0
+hf 15 raw -akrc -d 02E009401D363020
 ```
 
-`hf 15 csetuid` *without* `--v2` is a different, older magic protocol. It
-won't brick the tag, but it doesn't work on these tags either. There is
-deliberately no `--gen2` flag or automatic gen1→gen2 fallback anywhere in
-this CLI — only the two raw frames above are ever sent.
+Both frames go out in a **single** `pm3 -c` session, and `-k` keeps the
+field up between them. Sending them as two separate pm3 invocations power-
+cycles the tag in between, which can leave the UID half-written.
+
+`hf 15 csetuid` *without* `--v2` is a different, older magic protocol —
+it writes tag blocks `0x3E`/`0x3F` (config) plus `0x38`/`0x39`. The vendor
+sheet warns against `csetuid` in *any* form, saying it destroys
+configuration properties and internally reformats the tag; assume that
+covers the gen1 path too. There is deliberately no `--gen1`/`--gen2` flag
+or automatic fallback anywhere in this CLI — only the two raw frames above
+are ever sent.
 
 Do **not** use `hf 15 restore -f …` either: it requires a full binary tag
 struct dump whose layout changes between Proxmark3 releases.

tests/test_proxmark.py

@@ -38,19 +38,25 @@
 class TestBuildUidFrames(unittest.TestCase):
     def test_known_vector_from_plan(self):
         uid = bytes.fromhex("E00403502030361D")
-        high, low = build_uid_frames(uid)
-        self.assertEqual(high, "hf 15 raw -acw -d 02E009401D363020")
-        self.assertEqual(low, "hf 15 raw -acw -d 02E00941500304E0")
+        first, last = build_uid_frames(uid)
+        self.assertEqual(first, "hf 15 raw -akrc -d 02E00941500304E0")
+        self.assertEqual(last, "hf 15 raw -akrc -d 02E009401D363020")
+
+    def test_matches_vendor_documented_example(self):
+        """The worked example on the rfidfriend.com instruction sheet:
+        UID E0 04 03 50 12 34 56 78, step 1 then step 2."""
+        first, last = build_uid_frames(bytes.fromhex("E004035012345678"))
+        self.assertEqual(first, "hf 15 raw -akrc -d 02E00941500304E0")
+        self.assertEqual(last, "hf 15 raw -akrc -d 02E0094078563412")
 
     def test_rejects_wrong_length(self):
         with self.assertRaises(ValueError):
             build_uid_frames(bytes.fromhex("E00403"))
 
     def test_never_mentions_csetuid(self):
         uid = bytes.fromhex("E00403502030361D")
-        high, low = build_uid_frames(uid)
-        self.assertNotIn("csetuid", high)
-        self.assertNotIn("csetuid", low)
+        for frame in build_uid_frames(uid):
+            self.assertNotIn("csetuid", frame)
 
 
 class TestBuildCommands(unittest.TestCase):

tests/test_writer.py

@@ -17,8 +17,8 @@
     "hf 15 wrbl --ua -b 5 -d 2FB3911D",
     "hf 15 wrbl --ua -b 6 -d 982C1C55",
     "hf 15 wrbl --ua -b 7 -d 00F20064",
-    "hf 15 raw -acw -d 02E009401D363020",
-    "hf 15 raw -acw -d 02E00941500304E0",
+    "hf 15 raw -akrc -d 02E00941500304E0",
+    "hf 15 raw -akrc -d 02E009401D363020",
 ]
 
 
@@ -83,15 +83,33 @@ class TestWriteUid(unittest.TestCase):
     def test_success_on_first_attempt(self):
         tag = parse_nfc_file(FIXTURES / "Zuma.nfc")
         responses = [
-            Pm3Result("", "", 0),  # high frame
-            Pm3Result("", "", 0),  # low frame
+            Pm3Result("", "", 0),  # both UID frames, one session
             Pm3Result("[+] UID.................. E0 04 03 50 20 30 36 1D", "", 0),  # info
         ]
         runner = FakeRunner(responses=responses)
         result = writer.write_uid(tag, WriteOptions(), run_fn=runner, sleep_fn=lambda s: None)
         self.assertTrue(result.ok)
         self.assertEqual(result.read_back_uid, tag.uid)
 
+    def test_both_frames_share_one_session(self):
+        """The field must stay up between the two halves — one pm3 call, in
+        vendor order (0x41 first)."""
+        tag = parse_nfc_file(FIXTURES / "Zuma.nfc")
+        runner = FakeRunner(
+            responses=[
+                Pm3Result("", "", 0),
+                Pm3Result("[+] UID.................. E0 04 03 50 20 30 36 1D", "", 0),
+            ]
+        )
+        writer.write_uid(tag, WriteOptions(), run_fn=runner, sleep_fn=lambda s: None)
+        self.assertEqual(
+            runner.calls[0],
+            [
+                "hf 15 raw -akrc -d 02E00941500304E0",
+                "hf 15 raw -akrc -d 02E009401D363020",
+            ],
+        )
+
     def test_failure_when_uid_never_matches(self):
         tag = parse_nfc_file(FIXTURES / "Zuma.nfc")
         info_unchanged = Pm3Result("[+] UID.................. E0 04 02 11 22 33 44 55", "", 0)

tonie_writer/cli.py

@@ -388,17 +388,15 @@ def cmd_doctor(args: argparse.Namespace) -> int:
                 confirm = ""
             if confirm == "y":
                 test_uid = bytes.fromhex("E004030000000001")
-                high, low = proxmark.build_uid_frames(test_uid)
-                proxmark.run([high], port=args.port, pm3_bin=pm3_bin)
-                proxmark.run([low], port=args.port, pm3_bin=pm3_bin)
+                frames = list(proxmark.build_uid_frames(test_uid))
+                proxmark.run(frames, port=args.port, pm3_bin=pm3_bin)
                 check = proxmark.run(["hf 15 info"], port=args.port, pm3_bin=pm3_bin)
                 new_uid = proxmark.parse_info_uid(check.stdout)
                 if new_uid == test_uid.hex().upper():
                     print("✅ magic write succeeded — this is a magic tag.")
                     if uid:
-                        orig_high, orig_low = proxmark.build_uid_frames(bytes.fromhex(uid))
-                        proxmark.run([orig_high], port=args.port, pm3_bin=pm3_bin)
-                        proxmark.run([orig_low], port=args.port, pm3_bin=pm3_bin)
+                        orig = list(proxmark.build_uid_frames(bytes.fromhex(uid)))
+                        proxmark.run(orig, port=args.port, pm3_bin=pm3_bin)
                         print(f"Restored original UID {_format_uid(uid)}.")
                 else:
                     print("❌ UID unchanged — this tag's UID cannot be written (fixed-UID tag).")

tonie_writer/proxmark.py

@@ -115,19 +115,25 @@ def build_rdbl_command(block: int) -> str:
 
 
 def build_uid_frames(uid_bytes: bytes) -> tuple[str, str]:
-    """The two safe raw magic-UID frames from plan §4.4. Never `csetuid`.
+    """The two safe raw magic-UID frames, in the order and with the flags the
+    tag vendor (rfidfriend.com) documents. Never `csetuid`.
 
     Each half is sent reversed (the card stores the UID LSB-first):
-      high frame (0x40): uid[7] uid[6] uid[5] uid[4]
-      low  frame (0x41): uid[3] uid[2] uid[1] uid[0]
+      step 1 (0x41): uid[3] uid[2] uid[1] uid[0]  — the first four UID bytes
+      step 2 (0x40): uid[7] uid[6] uid[5] uid[4]  — the last four UID bytes
+
+    `-akrc` = activate field, keep it on after the frame, don't wait for a
+    reply (the magic write doesn't send one), append CRC. Both frames must
+    reach the tag in one field session, so callers pass them to `run()`
+    together — see `writer.write_uid`.
     """
     if len(uid_bytes) != 8:
         raise ValueError(f"UID must be 8 bytes, got {len(uid_bytes)}")
-    high = bytes([uid_bytes[7], uid_bytes[6], uid_bytes[5], uid_bytes[4]])
-    low = bytes([uid_bytes[3], uid_bytes[2], uid_bytes[1], uid_bytes[0]])
-    frame_high = "hf 15 raw -acw -d 02E00940" + high.hex().upper()
-    frame_low = "hf 15 raw -acw -d 02E00941" + low.hex().upper()
-    return frame_high, frame_low
+    first = bytes([uid_bytes[3], uid_bytes[2], uid_bytes[1], uid_bytes[0]])
+    last = bytes([uid_bytes[7], uid_bytes[6], uid_bytes[5], uid_bytes[4]])
+    frame_first = "hf 15 raw -akrc -d 02E00941" + first.hex().upper()
+    frame_last = "hf 15 raw -akrc -d 02E00940" + last.hex().upper()
+    return frame_first, frame_last
 
 
 def parse_info_uid(output: str) -> str | None:

tonie_writer/writer.py

@@ -78,17 +78,15 @@ def ok(self) -> bool:
 def plan_write_commands(tag: TonieTag, options: WriteOptions) -> list[str]:
     """The exact, ordered pm3 command list a real write would send.
 
-    Data blocks are written before the UID (§4.4/§8.5): once the tag carries
-    a foreign UID, the blocks may no longer be writable. Never reorder this.
+    Data blocks are written before the UID: once the tag carries a foreign
+    UID, the blocks may no longer be writable. Never reorder this.
     """
     commands: list[str] = []
     if not options.uid_only:
         for block, data in enumerate(tag.blocks):
             commands.append(proxmark.build_wrbl_command(block, data))
     if not options.blocks_only:
-        high, low = proxmark.build_uid_frames(tag.uid_bytes)
-        commands.append(high)
-        commands.append(low)
+        commands.extend(proxmark.build_uid_frames(tag.uid_bytes))
     return commands
 
 
@@ -132,15 +130,16 @@ def write_uid(
     run_fn: RunFn = proxmark.run,
     sleep_fn: Callable[[float], None] = time.sleep,
 ) -> UidWriteResult:
-    """Write the target UID using the two safe raw frames from §4.4 — never
-    csetuid. Confirms via `hf 15 info` read-back, which is the only success
-    signal these raw frames give. Retries up to 3 times with a short delay."""
-    high, low = proxmark.build_uid_frames(tag.uid_bytes)
+    """Write the target UID using the two safe raw frames — never csetuid.
+    Both frames go into a single pm3 session so the field stays up between
+    them (`-k`); a power cycle in between can leave the UID half-written.
+    Confirms via `hf 15 info` read-back, which is the only success signal
+    these raw frames give. Retries up to 3 times with a short delay."""
+    frames = list(proxmark.build_uid_frames(tag.uid_bytes))
     read_back: str | None = None
     max_attempts = 3
     for attempt in range(1, max_attempts + 1):
-        run_fn([high], port=options.port, pm3_bin=options.pm3_bin)
-        run_fn([low], port=options.port, pm3_bin=options.pm3_bin)
+        run_fn(frames, port=options.port, pm3_bin=options.pm3_bin)
         info = run_fn(["hf 15 info"], port=options.port, pm3_bin=options.pm3_bin)
         read_back = proxmark.parse_info_uid(info.stdout)
         if read_back == tag.uid: