Bambu-Research-Group · exiom-xyz · Jun 20, 2025 · Jun 20, 2025 · Jun 23, 2025 · Jun 24, 2025
diff --git a/.github/workflows/auto_toc_update.yml b/.github/workflows/auto_toc_update.yml
@@ -19,7 +19,9 @@ jobs:
       - run: |
           curl https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc -o gh-md-toc
           chmod a+x gh-md-toc
-          ./gh-md-toc --insert --no-backup --hide-footer --skip-header README.md
+          for file in "**/*.md"; do
+            ./gh-md-toc --insert --no-backup --hide-footer --skip-header $file
+          done
           rm gh-md-toc
       - uses: stefanzweifel/git-auto-commit-action@v4
         with:

diff --git a/OpenSourceRfid.md b/OpenSourceRfid.md
diff --git a/README.md b/README.md
@@ -1,8 +1,7 @@
 # Bambu Lab RFID Tag Guide
+This repository contains the collective research of the Bambu Lab Filament RFID Tags and serves as a guide to give you a basic overview how you can decrypt and read your tags.
 
-This guide gives you a basic overview how you can decrypt and read your tags.
-
-[View Collection of Tags](https://github.com/queengooborg/Bambu-Lab-RFID-Library)
+Please visit the [Bambu Lab RFID Library Repository](https://github.com/queengooborg/Bambu-Lab-RFID-Library) to view our collection of tags.
 
 [![Link to Discord](https://img.shields.io/badge/Discord-join_now-blue?style=flat-square&logo=discord&logoColor=white&label=Discord&color=blue)](https://discord.gg/zVfCVubwr7)
 
@@ -16,13 +15,10 @@ This guide gives you a basic overview how you can decrypt and read your tags.
    * [Requirements](#requirements)
       * [Proxmark3 compatible readers](#proxmark3-compatible-readers)
          * [Proxmark3 Easy](#proxmark3-easy)
-   * [Hacking a Bambu Lab Tag and readout of its data](#hacking-a-bambu-lab-tag-and-readout-of-its-data)
-      * [Deriving the keys](#deriving-the-keys)
-      * [Proxmark3 fm11rf08s recovery script](#proxmark3-fm11rf08s-recovery-script)
-      * [Sniffing the tag data with a Proxmark3 (legacy method)](#sniffing-the-tag-data-with-a-proxmark3-legacy-method)
    * [Tag Documentation](#tag-documentation)
    * [How do RFID tags work?](#how-do-rfid-tags-work)
-   * [Compatible RFID tags - By generation](#compatible-rfid-tags---by-generation)
+   * [Hacking a Bambu Lab Tag and readout of its data](#hacking-a-bambu-lab-tag-and-readout-of-its-data)
+   * [RFID Tag Cloning](#rfid-tag-cloning)
    * [Reverse engineering RFID Board](#reverse-engineering-rfid-board)
 <!--te-->
 
@@ -44,7 +40,8 @@ This is a research group dedicated to documenting the data structures used by Ba
 
 ### How to contribute
 
-If you have a Proxmark3 (or other RFID debugging tool), you can decrypt the contents of your Bambu Lab RFID tags and submit them via [Discord](https://discord.gg/zVfCVubwr7).
+If you have a Proxmark3 (or other RFID debugging tool), you can decrypt the contents of your Bambu Lab RFID tags and submit them via [Discord](https://discord.gg/zVfCVubwr7), or alternatively submit a Pull Request to the [Bambu Lab RFID Library Repository](https://github.com/queengooborg/Bambu-Lab-RFID-Library).
+
 A lot of the contents have been deciphered, but the more data we have, the easier it is to compare differences to learn what each byte represents and double-check our answers.
 
 ### Todos/Timeline/Next steps
@@ -55,13 +52,14 @@ A lot of the contents have been deciphered, but the more data we have, the easie
 
 ## Requirements
 
+- Basic command line knowledge
 - A computer running macOS or Linux, or a Windows computer with a WSL installation
 - Python 3.6 or higher
 - Bambu Lab Filament spool **or** the related tags
 - An NFC/RFID reader that can read encrypted tags, such as...
   - A Proxmark3-compatible RFID reader (recommended)
     - The [proxmark3 (Iceman fork) software](https://github.com/RfidResearchGroup/proxmark3)
-      - Requires v4.18994 (codename "Backdoor") or higher
+      - Requires v4.20469 or higher
       - You MUST use the Iceman fork as the original version of the software is unmaintained; all instructions and scripts are written for the Iceman fork and will not work on the original version
   - A Flipper Zero
 
@@ -73,73 +71,13 @@ A lot of the contents have been deciphered, but the more data we have, the easie
 
 A Proxmark3 Easy is sufficient for all the tasks that need to be done. You can buy a clone from Alixepress, Amazon or Dangerous Things.
 
-## Hacking a Bambu Lab Tag and readout of its data
-
-We document here the most simple approach to get all required A-Keys and the data of the tag. The easiest way is to derive the keys using the Python script in this repository.
-
-### Deriving the keys
-
-A way to derive the keys from the UID of an RFID tag was discovered, which unlocked the ability to scan and scrape RFID tag data without sniffing, as well as with other devices like the Flipper Zero. A script is included in the repository to derive the keys from the UID of a tag.
-
-First, obtain the tag's UID:
-
-- Proxmark3
-  1. Run the Proxmark3 software by running `pm3` in the terminal
-  2. Place the Proxmark3 device on the RFID tag of the spool
-  3. Run `hf mf info` and look for the UID line item
-- Flipper Zero
-  1. Open the NFC app and scan the tag
-  2. The Flipper will attempt to decrypt the tag, but you can skip the "Nested Dictionary (Backdoor)" step for speed
-  3. The UID of the tag will appear on-screen
-- Bambu Lab AMS
-  1. Load the spool into an AMS slot and wait for it to finish loading
-  2. View the spool's details on the printer's touchscreen, Bambu Studio or Bambu Handy
-  3. The UID is the first eight characters of the spool's serial number
-
-Next, run the key derivation script and pipe its output to a file by running `python3 deriveKeys.py [UID] > ./keys.dic`.
-
-Then, use the keys file to extract the data from the RFID tag:
-
-- Proxmark3
-  1. Run the Proxmark3 software by running `pm3` in the terminal
-  2. Place the Proxmark3 device on the RFID tag of the spool
-  3. Run `hf mf dump -k ./keys.dic` to dump the RFID tag's contents
-- Flipper Zero
-  1. Open the qFlipper program and connect your Flipper to your computer
-    - You may also connect the SD card directly to your computer
-  2. Navigate to `SD Card/nfc/assets/`
-  3. Copy the `mf_classic_dict_user.nfc` file to your computer
-  4. Copy the contents of `keys.dic` to `mf_classic_dict_user.nfc`
-  5. Copy `mf_classic_dict_user.nfc` back onto your Flipper
-  6. Use the NFC app to scan your tag
-
-### Proxmark3 fm11rf08s recovery script
-
-In 2024, a new backdoor[^rfid-backdoor] was found that makes it much easier to obtain the data from the RFID tags. A script is included in the proxmark3 software since v4.18994 (nicknamed "Backdoor"), which allows us to utilize this backdoor. Before this script was implemented, the tag had to be sniffed by placing the spool in the AMS and sniffing the packets transferred between the tag and the AMS.
-
-Place your reader on the tag, start proxmark3 (run `pm3`) and run the following command:
-
-`script run fm11rf08s_recovery`
-
-This script takes about 15-20 minutes to complete. Once it has finished, you will receive a binary key file and a dump.
-
-To visualize the data on the tag, run the following:
-
-`script run fm11rf08s_full -b`
-
-### Sniffing the tag data with a Proxmark3 (legacy method)
-
-Before the above methods were developed, tag data had to be obtained by sniffing the data between the RFID tag and the AMS using a Proxmark3-compatible device.
-
-To read how to obtain the tag data using the legacy sniffing method, see the [TagSniffing.md](./TagSniffing.md).
-
 ## Tag Documentation
 
-For a description of the blocks of a Bambu Lab RFID tag, see [BambuLabRfid.md](./BambuLabRfid.md).
+For a description of the blocks of a Bambu Lab RFID tag, see [docs/BambuLabRfid.md](./docs/BambuLabRfid.md).
 
-For a description of the blocks of a Creality RFID tag, see [CrealityRfid.md](./CrealityRfid.md).
+For a description of the blocks of a Creality RFID tag, see [docs/CrealityRfid.md](./docs/CrealityRfid.md).
 
-An open-source standard proposal, Open 3D-RFID, is being incubated in this repository.  For a description of the standard, see [OpenSourceRfid.md](./OpenSourceRfid.md).
+An open-source standard proposal, OpenTag, is being incubated in this repository.  For a description of the standard, see [docs/OpenTag.md](./docs/OpenTag.md).
 
 ## How do RFID tags work?
 
@@ -172,23 +110,13 @@ Here's a high-level summary of how everything works:
     - RSA Signature Private Key. You'd have to get this from bambu, good luck
   - Since Bambu Lab will likely not remove the signature requirement, you would need custom AMS firmware to read tags and ignore the signature
 
-## Compatible RFID tags - By generation
-
-There are tags known as "Magic Tags" which allow functionality that's not part of the classic MIFARE spec.
-One example is that most Magic Tags allow the UID to be changed, which is normally read-only on MIFARE tags.
-Magic tags are often refered to by their "generation", eg "Magic Gen 1". Each newer generation increases the functionality, but tends to also be more expensive)
-
-Gen 1 --> **Not compatible**(due to AMS checking if tag is unlockable with command 0x40)
-
-Gen 2 --> **Works**
-
-Gen 2 OTW --> **Not tested**
+## Hacking a Bambu Lab Tag and readout of its data
 
-Gen 3 --> **Not tested**
+Please visit [docs/ReadTags.md](./docs/ReadTags.md), where we documented all the approaches we discovered along the way to get all required keys and data out of the tag.
 
-Gen 4 --> **Not tested**(The best option but pricey and hard to source in small chip formfactor)
+## RFID Tag Cloning
 
-FUID --> **Works** "Fused UID" aka "write-once UID". Once a UID is written, it cannot be changed
+Please visit [docs/WriteTags.md](./docs/WriteTags.md), where we documented all the current and past ways of cloning Bambu Lab filament RFID tags and compatible RFID tags used to clone them.
 
 ## Reverse engineering RFID Board
 

diff --git a/BambuLabRfid.md → docs/BambuLabRfid.md b/BambuLabRfid.md → docs/BambuLabRfid.md
diff --git a/CrealityRfid.md → docs/CrealityRfid.md b/CrealityRfid.md → docs/CrealityRfid.md
diff --git a/OpenTag.md → docs/OpenTag.md b/OpenTag.md → docs/OpenTag.md
diff --git a/docs/ReadTags.md b/docs/ReadTags.md
@@ -0,0 +1,118 @@
+# Hacking a Bambu Lab Tag and readout of its data
+
+This document describes the various approaches for scanning Bambu Lab RFID tags.
+If you have a Proxmark3 device, the easiest way to scan tags is using the built-in `bambukeys` function. Otherwise, if you have another RFID scanning device like a Flipper Zero, a Python script is provided in order to derive the keys from the UID of the tag.
+
+> [!NOTE]
+> Please consider submitting your scanned tags to the [Bambu Lab RFID Library](https://github.com/queengooborg/Bambu-Lab-RFID-Library) repository!
+
+# Table of contents
+
+<!--ts-->
+* [Dumping Tags using Proxmark3](#dumping-tags-using-proxmark3)
+* [Deriving the keys](#deriving-the-keys)
+* [Proxmark3 fm11rf08s recovery script (legacy method)](#proxmark3-fm11rf08s-recovery-script-legacy-method)
+* [Sniffing the tag data with a Proxmark3 (legacy method)](#sniffing-the-tag-data-with-a-proxmark3-legacy-method)
+<!--te-->
+
+### Dumping Tags using Proxmark3
+
+As of Proxmark3 v4.20469, a new command has been implemented to scan a Bambu Lab RFID tag and automatically derive the keys, offering a fast, one-command way to scan tags.
+
+To scan a tag with this method, place the Proxmark3 device on the tag and run `pm3` in the terminal. Then, in the `pm3` prompt, run:
+
+```
+hf mf bambukeys -r -d;hf mf dump
+```
+or
+```
+hf mf bambukeys -r -d
+hf mf dump
+```
+
+This process should only take a few seconds with an expected output similar to below, (to keep things short, dumps of keys and data were truncated)
+
+```
+[=] -----------------------------------
+[=]  UID 4b... XX XX XX XX
+[=] -----------------------------------
+
+[+] Saved 192 bytes to binary file `Path\to\your\ProxSpace\pm3/hf-mf-XXXXXXXX-key.bin`
+[+] Loaded binary key file `Path\to\your\ProxSpace\pm3/hf-mf-XXXXXXXX-key.bin`
+[=] Reading sector access bits...
+[=] .................
+[+] Finished reading sector access bits
+[=] Dumping all blocks from card...
+[-] Sector... 15 block... 3 ( ok )
+[+] Succeeded in dumping all blocks
+
+[+] time: 10 seconds
+
+[=] -----+-----+-------------------------------------------------+-----------------
+[=]  sec | blk | data                                            | ascii
+[=] -----+-----+-------------------------------------------------+-----------------
+
+[+] Saved 1024 bytes to binary file `Path\to\your\ProxSpace\pm3/hf-mf-XXXXXXXX-dump.bin`
+[+] Saved to json file Path\to\your\ProxSpace\pm3/hf-mf-XXXXXXXX-dump.json
+```
+Once the above command is completed you will see that the data dump and keys will have been saved to the working directory of PM3.
+
+You can find out what each block of data means here, [Bambu Lab Filament Tag Documentation](/BambuLabRfid.md)
+
+Below continues with more technical explainations and legacy methods. If that doesn't interests you, your instructions are complete here.
+
+### Deriving the keys
+
+A way to derive the keys from the UID of an RFID tag was discovered, which unlocked the ability to scan and scrape RFID tag data without sniffing, as well as with other devices like the Flipper Zero. A script is included in the repository to derive the keys from the UID of a tag.
+
+First, obtain the tag's UID:
+
+- Proxmark3
+  1. Run the Proxmark3 software by running `pm3` in the terminal
+  2. Place the Proxmark3 device on the RFID tag of the spool
+  3. Run `hf mf info` and look for the UID line item
+- Flipper Zero
+  1. Open the NFC app and scan the tag
+  2. The Flipper will attempt to decrypt the tag, but you can skip the "Nested Dictionary (Backdoor)" step for speed
+  3. The UID of the tag will appear on-screen
+- Bambu Lab AMS
+  1. Load the spool into an AMS slot and wait for it to finish loading
+  2. View the spool's details on the printer's touchscreen, Bambu Studio or Bambu Handy
+  3. The UID is the first eight characters of the spool's serial number
+
+Next, run the key derivation script and pipe its output to a file by running `python3 deriveKeys.py [UID] > ./keys.dic`.
+
+Then, use the keys file to extract the data from the RFID tag:
+
+- Proxmark3
+  1. Run the Proxmark3 software by running `pm3` in the terminal
+  2. Place the Proxmark3 device on the RFID tag of the spool
+  3. Run `hf mf dump -k ./keys.dic` to dump the RFID tag's contents
+- Flipper Zero
+  1. Open the qFlipper program and connect your Flipper to your computer
+    - You may also connect the SD card directly to your computer
+  2. Navigate to `SD Card/nfc/assets/`
+  3. Copy the `mf_classic_dict_user.nfc` file to your computer
+  4. Copy the contents of `keys.dic` to `mf_classic_dict_user.nfc`
+  5. Copy `mf_classic_dict_user.nfc` back onto your Flipper
+  6. Use the NFC app to scan your tag
+
+### Proxmark3 fm11rf08s recovery script (legacy method)
+
+In 2024, a new backdoor[^rfid-backdoor] was found that makes it much easier to obtain the data from the RFID tags. A script is included in the proxmark3 software since v4.18994 (nicknamed "Backdoor"), which allows us to utilize this backdoor. Before this script was implemented, the tag had to be sniffed by placing the spool in the AMS and sniffing the packets transferred between the tag and the AMS.
+
+Place your reader on the tag, start proxmark3 (run `pm3`) and run the following command:
+
+`script run fm11rf08s_recovery`
+
+This script takes about 15-20 minutes to complete. Once it has finished, you will receive a binary key file and a dump.
+
+To visualize the data on the tag, run the following:
+
+`script run fm11rf08s_full -b`
+
+### Sniffing the tag data with a Proxmark3 (legacy method)
+
+Before the above methods were developed, tag data had to be obtained by sniffing the data between the RFID tag and the AMS using a Proxmark3-compatible device.
+
+To read how to obtain the tag data using the legacy sniffing method, see the [TagSniffing.md](./TagSniffing.md).
diff --git a/TagSniffing.md → docs/TagSniffing.md b/TagSniffing.md → docs/TagSniffing.md