Bambu Lab Filament RFID Reader for Flipper Zero

This folder contains a Flipper Zero application for reading and decoding Bambu Lab filament RFID tags, with JSON export capabilities for integration with external systems.

Screenshots

Main Menu	Reading Tag	Success

Filament Info	Export Options	HTTP Settings

Contents

bambu_filament/ - Standalone FAP Application

A full-featured application with UI for reading, displaying, and exporting filament data.

bambu_kdf_plugin/ - KDF Plugin for NFC App

A lightweight plugin that integrates with Flipper's built-in NFC app to enable reading Bambu Lab tags directly.

bridge/ - USB-to-API Bridge Scripts

Python scripts for receiving data from Flipper and forwarding to your API.

Building

Prerequisites

1. Python 3.10+ - Required for uFBT
2. Git - For cloning firmware SDK
3. uFBT (micro Flipper Build Tool) - Main build tool

Install uFBT

pip install --upgrade ufbt

Build the Standalone App

cd bambu_filament
ufbt

The compiled .fap file will be in dist/.

Build the KDF Plugin

cd bambu_kdf_plugin
ufbt

The compiled .fal file will be in dist/.

Installation

Method 1: Flipper Application Catalog (Recommended)

The easiest way to install is through the official Flipper Application Catalog:

1. Open qFlipper on your computer or the Flipper Mobile App
2. Go to Apps > NFC
3. Search for "Bambu Filament"
4. Click Install

The app will be automatically installed and updated.

Method 2: Manual Installation

If you prefer to install manually or want to use a custom build:

Standalone App

1. Download bambu_filament.fap from the Releases page (or build from source)
2. Connect your Flipper Zero via USB
3. Open qFlipper and go to the File Manager tab
4. Navigate to SD Card/apps/NFC/
5. Drag and drop bambu_filament.fap into this folder

Alternatively, copy the file directly to your SD card:

/ext/apps/NFC/bambu_filament.fap

KDF Plugin

1. Download bambulab_kdf.fal from Releases
2. Copy to your Flipper's SD card at:

/ext/apps_data/nfc/plugins/bambulab_kdf.fal

Note: Create the plugins directory if it doesn't exist.

Usage

Standalone App

1. Navigate to Apps > NFC > Bambu Filament
2. Select Read Tag
3. Place a Bambu Lab filament spool's RFID tag on the back of your Flipper
4. View the decoded filament information
5. Press Export button to export data

KDF Plugin

1. Open the built-in NFC app
2. Select Read
3. Place a Bambu Lab filament tag on the Flipper
4. The plugin will automatically derive keys and read the tag

JSON Export Feature

After reading a tag, press the Export button to access export options:

Export to SD Card

Saves JSON file to: /ext/apps_data/bambu_filament/{UID}_{timestamp}.json

Export via USB Serial

Streams JSON over USB to a companion script on your computer.

USB-to-API Bridge

The bridge script listens for JSON data from Flipper over USB and forwards it to your API.

Setup

cd bridge
pip install -r requirements.txt

Usage

1. Start your API server (or use the example):

   python example_server.py

2. Connect Flipper Zero via USB

3. Run the bridge script:

   # Auto-detect Flipper port
   python bambu_bridge.py --api http://localhost:8080/api/filament
   
   # Or specify port manually
   python bambu_bridge.py --port COM3 --api http://localhost:8080/api/filament
   python bambu_bridge.py --port /dev/ttyACM0 --api http://192.168.1.100:8080/api/filament

4. On Flipper: Read a tag, then select Export > Send via USB

Bridge Options

--port, -p     Serial port (auto-detect if not specified)
--baudrate, -b Baud rate (default: 115200)
--api, -a      API endpoint URL (required)
--list, -l     List available serial ports
--debug, -d    Enable debug logging

WiFi Export (FlipperHTTP)

⚠️ Note: The HTTP/WiFi export feature requires additional work and is currently in active development. Functionality may be incomplete or unstable.

Export filament data directly over WiFi without needing a USB connection. Requires a WiFi devboard running FlipperHTTP firmware.

Requirements

• WiFi devboard (ESP32-based) with FlipperHTTP firmware
• WiFi network connection configured on the devboard
• HTTP endpoint to receive the data

Configuration

1. Navigate to Apps > NFC > Bambu Filament
2. Select HTTP Settings from the main menu
3. Configure:
   • URL: Your API endpoint (e.g., http://192.168.1.100:8080/filament)
   • API Key: Optional authentication key (sent as X-API-Key header)
   • Enabled: Toggle WiFi export on/off

Settings are saved to /ext/apps_data/bambu_filament/http.conf.

Usage

1. Read a filament tag
2. Select Export > Send via WiFi
3. The app will POST JSON data to your configured endpoint

HTTP Request Format

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-API-Key: your-api-key-here

{JSON payload - same format as file export}

Testing

Use the included test server to verify your setup:

cd bridge
python example_server.py

The server displays your local IP address - use this in the Flipper's HTTP settings.

HID Keyboard Export

Export filament data by emulating a USB keyboard. The Flipper types the JSON directly into any focused text field - no drivers or software required on the host computer.

How It Works

1. Read a filament tag
2. Select Export > Type via HID
3. Click into a text field on your computer (notepad, web form, terminal, etc.)
4. The Flipper switches to HID keyboard mode and types the JSON

Output Format

The HID export types a single-line compact JSON string (no whitespace or line breaks):

{"tag_uid":"AABBCCDD","filament_type":"PLA Basic","detailed_type":"PLA Matte","material_id":"GFA50","variant_id":"A50-K0","color":{"hex":"#00AE42","r":0,"g":174,"b":66,"a":255},"color2":null,"spool":{"weight_g":1000,"length_m":330,"width_mm":66.25,"diameter_mm":1.75},"temperatures":{"nozzle_min_c":190,"nozzle_max_c":230,"bed_c":55,"drying_c":55,"drying_hours":8},"production":{"date":"2024_03_15_14_30"},"export_timestamp":1234567890}

Use Cases

• Web forms - Paste directly into inventory management systems
• No-install environments - Works on locked-down computers without admin access
• Quick testing - Paste into any text editor to inspect data
• Automation - Type into scripts or terminal commands

Notes

• Typing takes a few seconds depending on JSON length
• The Flipper will wait ~1 second before typing to give you time to focus a text field
• USB mode switches temporarily; returns to normal after export
• Works with any OS that supports USB HID keyboards

JSON Format

{
  "tag_uid": "AABBCCDD",
  "filament_type": "PLA Basic",
  "detailed_type": "PLA Matte",
  "material_id": "GFA50",
  "variant_id": "A50-K0",
  "color": {
    "hex": "#00AE42",
    "r": 0, "g": 174, "b": 66, "a": 255
  },
  "color2": null,
  "spool": {
    "weight_g": 1000,
    "length_m": 330,
    "width_mm": 66.25,
    "diameter_mm": 1.75
  },
  "temperatures": {
    "nozzle_min_c": 190,
    "nozzle_max_c": 230,
    "bed_c": 55,
    "drying_c": 55,
    "drying_hours": 8
  },
  "production": {
    "date": "2024_03_15_14_30",
    "tray_uid": "..."
  },
  "export_timestamp": 1234567890
}

Workflow for 3D Printing Business

1. Read filament tag with Flipper Zero
2. Export via USB to bridge script
3. Bridge forwards JSON to your local API
4. API stores data in your database
5. Server confirms receipt to bridge
6. Bridge logs successful transfer

Duplicate Handling

• The app tracks exported UIDs in a local log
• Your API should handle duplicates (update vs. reject)
• The example server updates existing entries with same UID

App Icon

The app requires a 10x10 pixel icon at bambu_filament/icons/bambu_10px.png.

Create a simple 10x10 1-bit PNG icon (black and white) representing a filament spool.

Features

• Read Tag: Read Bambu Lab filament RFID tags
• Display Info: Show filament type, color, weight, temperatures, etc.
• Export to SD: Save JSON to Flipper's SD card
• Export via USB Serial: Stream JSON to computer for API forwarding
• Export via HID: Type JSON as keyboard input into any text field
• Export via WiFi: Send JSON directly to HTTP endpoint (requires WiFi devboard)
• HTTP Settings: Configure WiFi export URL and API key
• About: Information about the app

Planned Features

• Load Saved: Load previously saved .nfc files
• Write: Clone tags to blank MIFARE Classic cards

Technical Details

• Tag Type: MIFARE Classic 1K (13.56 MHz)
• Encryption: Per-UID derived keys using HKDF-SHA256
• Key Derivation: Uses Bambu Lab's master key to derive 16 sector keys from tag UID

Limitations

• Tags are RSA-signed by Bambu Lab
• Modified or cloned tags will not work with Bambu Lab printers
• Cloning requires magic cards with matching UID (Gen1a/Gen2)

File Structure

FZBambuFilamentReader/
├── README.md
├── bambu_filament/           # Main Flipper app
│   ├── application.fam
│   ├── bambu_filament.c/h    # Main app entry point
│   ├── bambu_keys.c/h        # Key derivation
│   ├── bambu_parser.c/h      # Data parsing
│   ├── bambu_export.c/h      # JSON export
│   ├── bambu_http.c/h        # WiFi/HTTP export
│   ├── flipper_http.c/h      # FlipperHTTP library
│   ├── crypto/
│   │   ├── sha256.c/h
│   │   └── hkdf.c/h
│   ├── scenes/
│   │   ├── scene_main_menu.c
│   │   ├── scene_read_tag.c
│   │   ├── scene_display_info.c
│   │   ├── scene_export.c
│   │   ├── scene_http_settings.c
│   │   └── scene_about.c
│   ├── icons/
│   └── dist/                 # Compiled .fap file
├── bambu_kdf_plugin/         # NFC app plugin
│   ├── application.fam
│   ├── bambulab_plugin.c
│   └── dist/                 # Compiled .fal file
└── bridge/                   # Python bridge scripts
    ├── requirements.txt
    ├── bambu_bridge.py       # USB-to-API bridge
    └── example_server.py     # Example API server

Developer Guide

Building from Source

1. Install uFBT (micro Flipper Build Tool):

   pip install --upgrade ufbt

2. Clone this repository:

   git clone https://github.com/little-did-I-know/FZBambuFilamentReader.git
   cd FZBambuFilamentReader

3. Build the app:

   cd bambu_filament
   ufbt

4. Deploy to Flipper (connected via USB):

   ufbt launch

Code Architecture

The app follows Flipper Zero's standard scene-based architecture:

File	Purpose
bambu_filament.c/h	Main app entry, initialization, and cleanup
bambu_keys.c/h	HKDF key derivation from tag UID
bambu_parser.c/h	Parse raw tag data into structured filament info
bambu_export.c/h	JSON generation, SD/Serial/HID export
bambu_http.c/h	WiFi HTTP export via FlipperHTTP
flipper_http.c/h	FlipperHTTP library for WiFi devboard communication

Scene Flow:

Main Menu
├── Read Tag → Display Info → Export Options
├── HTTP Settings
└── About

Extending the App

Adding a New Export Method

1. Add your export function to bambu_export.c:

   BambuExportStatus bambu_export_to_xxx(const BambuFilamentData* data) {
       // Generate JSON
       char* json = malloc(BAMBU_JSON_MAX_SIZE);
       bambu_export_to_json(data, json, BAMBU_JSON_MAX_SIZE);
   
       // Your export logic here
   
       free(json);
       return BambuExportOk;
   }

2. Add the function declaration to bambu_export.h

3. Add a menu option in scenes/scene_export.c

Adding a New Data Field

1. Add the field to BambuFilamentData struct in bambu_parser.h
2. Parse the field in bambu_parser.c (check the tag data format)
3. Add the field to JSON output in bambu_export.c
4. Display it in scenes/scene_display_info.c

Adding a New Scene

1. Create scenes/scene_your_scene.c
2. Add the scene enum to the scene list in bambu_filament.h
3. Register callbacks in bambu_filament.c
4. Add navigation from other scenes

Debugging

Enable debug logging:

ufbt cli
log

Logs are prefixed with BambuFilament, BambuExport, BambuKeys, etc.

Troubleshooting

Tag Not Reading

• Ensure proper positioning: Center the tag on the back of the Flipper, near the NFC antenna
• Check tag type: Only MIFARE Classic 1K tags are supported
• Try multiple angles: Slowly rotate the tag while keeping it close
• Verify it's a Bambu tag: Third-party or refilled spools may use different tag formats

HID Export Not Working

• Focus a text field first: Click into Notepad, a browser text box, or terminal before exporting
• Wait for connection: The Flipper needs ~1 second to establish HID connection
• Check USB cable: Some cables are charge-only; use a data cable
• Try a different USB port: Some USB hubs don't support HID properly

WiFi Export Failing

• Check devboard connection: Ensure WiFi devboard is properly seated
• Verify WiFi connection: The devboard must be connected to your WiFi network
• Test endpoint: Use curl to verify your server is reachable:

  curl -X POST http://your-server:8080/endpoint -d '{"test":true}'

• Check URL format: Must include http:// or https:// prefix
• Firewall: Ensure your server allows incoming connections

USB Serial Export Not Receiving Data

• Correct serial port: Use --list flag to find the right port
• Baud rate: Default is 115200, ensure your listener matches
• USB mode: Flipper must be in CLI/serial mode, not mass storage

Build Errors

• Update uFBT: pip install --upgrade ufbt
• Clean build: ufbt clean && ufbt
• Check SDK version: Run ufbt update to get latest SDK

Contributing

Contributions are welcome! Here's how to help:

Reporting Issues

1. Check existing issues first
2. Include your Flipper firmware version
3. Describe steps to reproduce the problem
4. Include relevant log output if possible

Submitting Changes

1. Fork the repository
2. Create a branch for your feature:

   git checkout -b feature/your-feature-name

3. Make your changes following the existing code style
4. Test thoroughly on actual hardware
5. Commit with clear messages:

   git commit -m "Add: brief description of change"

6. Push and create a Pull Request

Code Style

• Use 4-space indentation
• Follow existing naming conventions (bambu_ prefix for functions)
• Add comments for non-obvious logic
• Keep functions focused and reasonably sized
• Test on real hardware before submitting

Areas for Contribution

• Load saved .nfc files
• Tag writing/cloning support
• Additional filament type mappings
• Localization/translations
• UI improvements

Credits

Based on research from the Bambu Research Group RFID Tag Guide.

License

This project is licensed under the MIT License - see the LICENSE file for details.