A complete system for reading and writing Creality CFS (Creality Filament System) NFC tags used in K2 Plus/Pro 3D printers.
This project provides both hardware and software to read, write, and clone Creality CFS tags. Each spool of Creality filament comes with two NFC tags (front and back) containing encrypted information about the filament type, color, length, and serial number.
- ✅ Read CFS Tags - Decode all tag information (material, length, color, serial)
- ✅ Write Dual Tags - Program matching front/back tag pairs
- ✅ Blank Tag Detection - Identify empty tags ready for writing
- ✅ Mac App Interface - User-friendly macOS application
- ✅ OTA Updates - Update firmware wirelessly from GitHub releases
- ✅ Material Database - Expandable database of filament types
- ✅ AES Encryption - Full encryption/decryption support
- ✅ BLE Communication - Wireless connection to Mac app
| Component | Specification | Notes |
|---|---|---|
| Microcontroller | ESP32-S3 | Any variant with WiFi + BLE |
| NFC Reader | PN532 | I2C mode only |
| Display | SH1106 128x64 OLED | I2C |
| LED | WS2812B RGB | Single addressable LED |
| Tags | MIFARE Classic 1K | For writing new tags |
PN532 NFC Reader:
SDA → ESP32 GPIO 8
SCL → ESP32 GPIO 9
VCC → 3.3V
GND → GND
SH1106 OLED:
SDA → ESP32 GPIO 8 (shared with PN532)
SCL → ESP32 GPIO 9 (shared with PN532)
VCC → 3.3V
GND → GND
WS2812B LED:
DIN → ESP32 GPIO 48
VCC → 5V
GND → GND
Located in firmware/
- Written in Arduino/C++
- Handles NFC read/write operations
- BLE communication with Mac app
- OTA firmware updates via WiFi
- Version: 1.2.0
Located in mac-app/
- Native SwiftUI application
- Connects via Bluetooth LE
- Material database management
- WiFi configuration
- OTA update manager
- Version: 1.2.0
Located in docs/
FIRMWARE.md- Complete firmware documentationTAG_FORMAT.md- CFS tag format specificationAPI.md- BLE protocol referenceGITHUB_SETUP.md- OTA update setup guide
- Wire components according to diagram above
- Ensure PN532 is in I2C mode (check DIP switches)
- Power via USB-C
# Clone repository
git clone https://github.com/yourusername/cfs-programmer.git
cd cfs-programmer
# Open firmware in Arduino IDE
open firmware/CFS_Handheld_v1.2_OTA/CFS_Handheld_v1.2_OTA.ino
# CRITICAL: Apply library patch (see firmware/README.md)
# Install required libraries via Library Manager:
# - Adafruit PN532
# - U8g2
# - Adafruit NeoPixel
# - AESLib
# - ArduinoJson
# Select board: ESP32S3 Dev Module
# Upload to device⚠� IMPORTANT: You must apply the PN532 library patch or authentication will fail. See firmware/README.md for details.
# Open Xcode project
open mac-app/CFS\ Programmer.xcodeproj
# Build and run (⌘R)- Power on ESP32 device
- Open Mac app
- App auto-connects to device
- Configure WiFi (Settings → WiFi Setup)
- Ready to read/write tags!
- Click Read Tag in Mac app
- Place CFS tag on PN532 reader
- Tag information displays immediately
- View material, length, color, and serial number
- Click Write Tags in Mac app
- Select material from database
- Choose weight (250g, 500g, 1kg, etc.)
- Pick color
- Enter serial (or auto-generate)
- Click Write Both Tags
- Place first blank tag → writes
- Place second blank tag → writes
- Done! Both tags have identical data
- Settings → WiFi Setup → Configure network
- Settings → Check for Updates
- If available, click Install Update
- Wait 30-60 seconds
- Device reboots with new firmware
cfs-programmer/
├── firmware/ # ESP32 firmware
│ ├── CFS_Handheld_v1.2_OTA/
│ │ └── CFS_Handheld_v1.2_OTA.ino
│ └── README.md
├── mac-app/ # macOS application
│ ├── CFS Programmer.xcodeproj
│ └── CFS Programmer/
│ ├── ContentView.swift
│ ├── CFS_ProgrammerApp.swift
│ └── Assets.xcassets
├── hardware/ # Hardware documentation
│ └── wiring-diagrams/
├── docs/ # Documentation
│ ├── FIRMWARE.md
│ ├── TAG_FORMAT.md
│ ├── API.md
│ └── GITHUB_SETUP.md
├── .github/
│ └── workflows/
│ └── release-firmware.yml # Auto-build on release
├── .gitignore
├── README.md
└── LICENSE
CFS tags are MIFARE Classic 1K NFC tags containing 48 bytes of encrypted data:
[Date][Vendor][??][Film ID][Color ][Length][Serial][Reserved]
5 4 2 6 7 4 6 14 bytes
Example:
ABC2112 0276 A2 101001 0FFFFFF 0330 123456 00000000000000
│ │ │ │ │ │ │ └─ Reserved
│ │ │ │ │ │ └─ Serial number
│ │ │ │ │ └─ Length (816m hex)
│ │ │ │ └─ Color (#FFFFFF)
│ │ │ └─ Film ID (PLA = 101001)
│ │ └─ Batch code
│ └─ Vendor (Creality = 0276)
└─ Date code
- Algorithm: AES-128 CBC
- Keys: Hardcoded (same as Creality printers)
- IV: All zeros
- UID-based authentication: MIFARE keys derived from tag UID
Full Tag Format Documentation →
- ✅ Creality K2 Plus
- ✅ Creality K2 Pro
- ⚠� Creality K1 Series (may work, needs testing)
- ⚠� CR-Series with CFS retrofit (untested)
For writing new tags:
- ✅ MIFARE Classic 1K (NXP original)
- ✅ MIFARE Classic 1K S50 (Chinese clones)
- ✅ FM11RF08 (compatible IC)
- � MIFARE Ultralight (too small)
- � NTAG215/216 (different protocol)
arduino-cli compile --fqbn esp32:esp32:esp32s3 firmware/CFS_Handheld_v1.2_OTA/# Update version in firmware code
# Commit changes
git add firmware/
git commit -m "Release firmware v1.3.0"
# Create tag
git tag -a fw-v1.3.0 -m "Firmware v1.3.0 - New features"
# Push (triggers GitHub Actions)
git push origin main
git push origin fw-v1.3.0GitHub Actions automatically builds and creates release with .bin file.
- Hardware: Test on real ESP32 + PN532
- Tags: Test with genuine Creality tags and blanks
- BLE: Test Mac app connection and commands
- OTA: Test update from previous version
Solution: Apply the PN532 library patch (see firmware/README.md). This is the #1 issue.
Solutions:
- Restart ESP32 device
- Restart Mac Bluetooth
- Check device is advertising (Serial Monitor)
Solutions:
- Verify WiFi credentials
- Check WiFi signal strength
- Ensure GitHub release has .bin file
- Monitor Serial output for errors
Full Troubleshooting Guide →
- PN532 library timing bug (fixed with SLOWDOWN patch)
- Some Chinese MIFARE clones may have authentication issues
- First BLE connection after boot can be slow (~5 seconds)
- ESP32-2432S028R support (touchscreen version)
- Write function implementation in firmware
- Tag history/database in Mac app
- Batch write mode (multiple sets)
- iOS app version
- Web interface for device
- Material profiles from cloud
- Tag usage analytics
Contributions welcome!
- Fork the repository
- Create feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open Pull Request
- ESP32-2432S028R migration
- iOS app development
- Additional material profiles
- Documentation improvements
- Testing with different tag brands
MIT License
Copyright (c) 2025 CFS Programmer Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
This project is for educational and personal use only. Use responsibly:
- ✅ Clone your own tags for backup
- ✅ Create custom tags for personal use
- � Don't counterfeit commercial tags
- � Don't violate Creality's intellectual property
The developers are not responsible for misuse of this software.
- Creality for creating an interesting NFC tag system
- Adafruit for the PN532 library
- ESP32 community for excellent documentation
- All contributors and testers
- Documentation: See
docs/folder - Issues: GitHub Issues
- Discussions: GitHub Discussions
Created by the maker community for the maker community.
Made with �� for the 3D printing community