{"id":47580828,"url":"https://github.com/LucaTomei/flipper-miband-nfc-writer","last_synced_at":"2026-04-15T17:00:47.922Z","repository":{"id":317714759,"uuid":"1068510714","full_name":"LucaTomei/flipper-miband-nfc-writer","owner":"LucaTomei","description":"Complete NFC toolkit for Xiaomi Mi Band devices on Flipper Zero - Read, write, emulate and verify Mi Band NFC data","archived":false,"fork":false,"pushed_at":"2026-02-07T12:53:55.000Z","size":253,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-07T20:23:04.191Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LucaTomei.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-02T13:49:13.000Z","updated_at":"2026-02-07T12:53:58.000Z","dependencies_parsed_at":"2025-10-02T16:33:00.408Z","dependency_job_id":null,"html_url":"https://github.com/LucaTomei/flipper-miband-nfc-writer","commit_stats":null,"previous_names":["lucatomei/flipper-miband-nfc-writer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/LucaTomei/flipper-miband-nfc-writer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucaTomei%2Fflipper-miband-nfc-writer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucaTomei%2Fflipper-miband-nfc-writer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucaTomei%2Fflipper-miband-nfc-writer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucaTomei%2Fflipper-miband-nfc-writer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LucaTomei","download_url":"https://codeload.github.com/LucaTomei/flipper-miband-nfc-writer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LucaTomei%2Fflipper-miband-nfc-writer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31851057,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-31T19:00:24.234Z","updated_at":"2026-04-15T17:00:47.909Z","avatar_url":"https://github.com/LucaTomei.png","language":"C","funding_links":[],"categories":["NFC"],"sub_categories":[],"readme":"# Mi Band NFC Writer v1.0\n\nA comprehensive Flipper Zero application for managing NFC data on Xiaomi Mi Band devices with advanced features including automatic backups, detailed logging, and progress tracking.\n\n## Overview\n\nThis application provides a complete toolkit for reading, writing, emulating, and verifying NFC data on Mi Band smart bands. It supports the full workflow from preparing a blank Mi Band to writing custom NFC dumps with real-time progress feedback and automatic verification.\n\n## Features\n\n### Core Operations\n- **Quick UID Check**: Instantly read card UID and scan disk for matching dumps\n- **Load NFC Dumps**: Browse and load Mifare Classic dumps from `/ext/nfc` folder\n- **Magic Card Emulation**: Create blank template with 0xFF keys for Mi Band initialization\n- **Write Original Data**: Write dump data to Mi Band with intelligent key detection\n- **Automatic Backup**: Optional pre-write backup with timestamp\n- **Verify Write**: Read and compare written data with original dump\n- **Difference Viewer**: Detailed hex comparison of mismatched blocks\n- **Save Magic Dumps**: Convert dumps to magic format with 0xFF keys\n\n### Advanced Features\n- **Settings System**: Persistent configuration storage\n  - Auto-backup before write\n  - Automatic verification after write\n  - Detailed progress display\n  - Enable/disable logging\n- **Logging System**: Complete operation logging with export capability\n  - Timestamped log entries\n  - Exportable to text files\n  - Up to 500 entries stored\n  - Debug, Info, Warning, Error levels\n- **Progress Tracking**: Real-time feedback with ASCII progress bars\n  - Sector-by-sector progress\n  - Percentage completion\n  - Authentication statistics\n  - Operation status messages\n\n## Architecture\n\n### File Structure\n\n```\nmiband_nfc_writer/\n├── miband_nfc.c                      # Main entry point and lifecycle\n├── miband_nfc.h                      # Public header (opaque type)\n├── miband_nfc_i.h                    # Internal header (structures)\n├── miband_logger.c                   # Logging system implementation\n├── miband_logger.h                   # Logging system interface\n├── progress_tracker.c                # Progress tracking utilities\n├── progress_tracker.h                # Progress tracker interface\n├── miband_nfc_scene.c                # Scene handler arrays\n├── miband_nfc_scene.h                # Scene declarations\n├── miband_nfc_scene_config.h         # Scene configuration (X-Macro)\n├── miband_nfc_scene_main_menu.c      # Main menu\n├── miband_nfc_scene_file_select.c    # File browser\n├── miband_nfc_scene_magic_emulator.c # Magic card emulation with stats\n├── miband_nfc_scene_writer.c         # Data writing with progress\n├── miband_nfc_scene_backup.c         # Automatic backup system\n├── miband_nfc_scene_verify.c         # Data verification\n├── miband_nfc_scene_diff_viewer.c    # Detailed difference display\n├── miband_nfc_scene_magic_saver.c    # Magic dump converter\n├── miband_nfc_scene_uid_check.c      # Quick UID reader and scanner\n├── miband_nfc_scene_settings.c       # Settings configuration\n├── miband_nfc_scene_about.c          # Help/documentation\n└── miband_nfc_icons.c                # Icon assets\n```\n\n### Key Components\n\n#### Scene Manager Pattern\nUses Flipper's scene manager with X-Macro pattern for scalable scene handling:\n- Each scene has three handlers: `on_enter`, `on_event`, `on_exit`\n- Scenes defined once in `miband_nfc_scene_config.h`\n- Automatic generation of handler arrays and enumerations\n\n#### NFC Operations\n- **Scanner**: Detects and identifies NFC cards\n- **Poller**: Reads data from physical cards\n- **Listener**: Emulates NFC cards with real-time statistics\n- Uses synchronous polling API for reliable read/write operations\n\n#### Logging System\n- Circular buffer with 500 entry capacity\n- Automatic log rotation (keeps newest 75% when full)\n- Timestamped entries with log levels\n- Export to `/ext/apps_data/miband_nfc/logs/`\n- Enable/disable via settings\n\n#### Settings System\n- Persistent storage in `/ext/apps_data/miband_nfc/settings.bin`\n- Magic number validation\n- Auto-load on startup\n- Configurable options:\n  - Auto backup enabled\n  - Verify after write\n  - Show detailed progress\n  - Enable logging\n\n## Operations\n\n### 0. Quick UID Check\n\n**Purpose**: Rapidly identify a card and find matching dumps on disk.\n\n**Process**:\n1. Reads Block 0 from placed card\n2. Displays UID, BCC, SAK, ATQA\n3. Scans `/ext/nfc` directory (non-recursive)\n4. Lists all matching dump files\n5. Shows manufacturer data\n\n**Use Case**: Quick identification before operations, find which dumps match your Mi Band.\n\n### 1. Emulate Magic Card\n\n**Purpose**: Prepare a new Mi Band for writing by emulating a blank template.\n\n**Process**:\n1. Loads selected dump file\n2. Preserves original UID from dump\n3. Zeros all data blocks\n4. Sets all keys to `FF FF FF FF FF FF`\n5. Configures magic access bits\n6. Emulates the template via NFC\n7. Shows real-time statistics:\n   - Authentication attempts and successes\n   - Connection count\n   - Last activity status\n\n**Use Case**: Use this BEFORE first write to initialize a blank Mi Band with magic keys.\n\n**UI Features**:\n- Real-time auth counter\n- Success/fail statistics\n- Status messages\n- Animated dolphin icon\n- Back button to stop\n\n### 2. Write Original Data\n\n**Purpose**: Write actual dump data to Mi Band NFC chip.\n\n**Process**:\n1. Optional automatic backup (if enabled in settings)\n2. Detects card and determines current key state\n3. Preserves Block 0 UID (read-only)\n4. Writes all data blocks (1-15 for each sector)\n5. Writes sector trailers with keys and access bits\n6. Uses intelligent authentication:\n   - First write scenario: tries 0xFF keys first\n   - Rewrite scenario: tries dump keys first\n7. Real-time progress display:\n   - ASCII progress bar\n   - Percentage completion\n   - Current sector number\n8. Optional automatic verification (if enabled)\n\n**Key Features**:\n- Automatic pre-write backup with timestamp\n- Automatic key detection (magic vs original)\n- Block 0 UID preservation\n- Retry logic for reliability\n- Progress bar updates every sector\n- Logged to system if enabled\n\n### 3. Save Magic Dump\n\n**Purpose**: Convert dump file to magic format for easy handling.\n\n**Process**:\n1. Loads original dump\n2. Shows conversion progress per sector\n3. Modifies all sector trailers:\n   - Key A: `FF FF FF FF FF FF`\n   - Key B: `FF FF FF FF FF FF`\n   - Access bits: `FF 07 80 69`\n4. Saves with `_magic.nfc` suffix\n5. Progress bar during conversion\n\n**Use Case**: Create magic-compatible versions of dumps for testing or simplified writing.\n\n### 4. Verify Write\n\n**Purpose**: Confirm data was written correctly to Mi Band.\n\n**Process**:\n1. Reads all sectors from Mi Band\n2. Shows detailed progress:\n   - Sector-by-sector reading\n   - Authentication statistics\n   - Progress bar and percentage\n3. Tries dump keys first, falls back to 0xFF keys\n4. Compares data intelligently:\n   - Block 0: **SKIPPED** (UID is preserved, not compared)\n   - Sector trailers: **SKIPPED** (keys are expected to differ)\n   - Data blocks: Full comparison (16 bytes)\n5. Reports differences if found\n6. Can show detailed difference viewer\n\n**Key Fix**: The verify operation now:\n- Skips Block 0 completely (UID preservation)\n- Skips all sector trailers (key differences expected)\n- Only compares actual data blocks\n- Handles both key scenarios gracefully\n\n### 5. Difference Viewer\n\n**Purpose**: Show detailed hex comparison of mismatched blocks.\n\n**Features**:\n- Lists all differing blocks\n- Shows expected vs found data in hex\n- Highlights different bytes with `[XX]` notation\n- Displays block types (Data/Trailer/UID)\n- Shows byte-level differences\n- Scrollable text view\n\n### 6. Automatic Backup\n\n**Purpose**: Create timestamped backups before write operations.\n\n**Process**:\n1. Triggered automatically if enabled in settings\n2. Reads current Mi Band data\n3. Creates backup in `/ext/nfc/backups/`\n4. Filename: `backup_YYYYMMDD_HHMMSS.nfc`\n5. Shows progress during backup\n6. Proceeds to write after successful backup\n\n**Safety**: Ensures you can always restore original data.\n\n### 7. Settings\n\n**Configurable Options**:\n- **Auto Backup**: Create backup before each write\n- **Verify After Write**: Automatically verify after writing\n- **Detailed Progress**: Show progress bars and percentages\n- **Enable Logging**: Log all operations to file\n- **Export Logs**: Export current logs with timestamp\n- **Clear Logs**: Reset log buffer\n\n**Persistence**: Settings saved to persistent storage and loaded on app start.\n\n## Technical Details\n\n### Authentication Strategy\n\nThe writer implements a three-tier authentication strategy:\n\n```c\n// Priority order for authentication:\n1. Try 0xFF keys (if pre-check indicates magic state)\n2. Try dump Key A\n3. Try dump Key B\n4. Try 0xFF keys as last resort (if not already tried)\n```\n\n### Block 0 Handling\n\nBlock 0 is special because it contains the UID which is typically read-only:\n\n```c\n// Block 0 structure:\n// [0-3]   UID (4 bytes)\n// [4]     BCC (1 byte) = UID[0] ^ UID[1] ^ UID[2] ^ UID[3]\n// [5]     SAK\n// [6-7]   ATQA\n// [8-15]  Manufacturer data\n```\n\nThe writer:\n1. Reads current Block 0\n2. Preserves existing UID\n3. Writes only blocks 1-2 in sector 0\n4. Writes sector 0 trailer\n5. **NEVER compares Block 0 during verification**\n\n### Sector Trailer Format\n\nMagic card format:\n```\nBytes 0-5:   Key A = FF FF FF FF FF FF\nBytes 6-9:   Access bits = FF 07 80 69\nBytes 10-15: Key B = FF FF FF FF FF FF\n```\n\nThese access bits allow read/write with any key, perfect for magic cards.\n\n### Verification Comparison Logic\n\n```c\nif (block_index == 0) {\n    // SKIP - UID block is preserved, not compared\n    continue;\n} else if (is_sector_trailer(block_index)) {\n    // SKIP - keys are expected to differ\n    continue;\n} else {\n    // Full comparison for data blocks only\n    compare(original[0:16], read[0:16]);\n}\n```\n\nThis ensures only actual data is compared, avoiding false mismatches from UID preservation or key changes.\n\n### Progress Display\n\nAll long operations show real-time progress:\n```\nWriting sector 12/16\n\n[============\u003e       ]\n75%\n```\n\nASCII progress bar with:\n- Current/total items\n- Visual progress bar (20 characters)\n- Percentage completion\n\n### Logging System\n\n```c\n// Log levels\nLogLevelDebug   - Detailed debugging information\nLogLevelInfo    - General information messages\nLogLevelWarning - Warning conditions\nLogLevelError   - Error conditions\n\n// Log format\nYYYY-MM-DD HH:MM:SS [LEVEL] Message\n\n// Example\n2024-12-27 14:32:15 [INFO] Write started: /ext/nfc/miband.nfc\n2024-12-27 14:32:45 [INFO] Write completed successfully\n```\n\nLogs are:\n- Circular buffer (500 entries)\n- Auto-rotating when full\n- Exportable with timestamp\n- Enable/disable in settings\n\n## Troubleshooting\n\n### Write Fails\n\n**Problem**: \"All authentication methods FAILED\"\n\n**Solutions**:\n1. Ensure Mi Band is a magic card type\n2. Check card positioning (hold steady)\n3. Run \"Emulate Magic Card\" first\n4. Verify dump file is valid Mifare Classic\n5. Check logs if enabled\n\n### Verify Shows Differences\n\n**Problem**: \"Data mismatch found\"\n\n**Check Logs/Difference Viewer**:\n- Use difference viewer to see exactly what differs\n- Check if only specific sectors differ\n- Verify original dump is correct\n- Try rewriting the affected sectors\n\n**Note**: Verify now skips Block 0 and trailers, so any reported differences are real data mismatches.\n\n### Backup Fails\n\n**Problem**: \"Cannot create backup\"\n\n**Solutions**:\n1. Check SD card has free space\n2. Ensure `/ext/nfc/backups/` directory exists\n3. Verify card can be read\n4. Check file permissions\n\n### Emulation Issues\n\n**Problem**: \"Too many auth attempts\" (stops at 100)\n\n**Cause**: Reader continuously authenticating without reading\n\n**Solution**: \n1. Check that dump file is valid\n2. Verify UID is correct\n3. Try with different dump file\n4. Check emulation statistics for patterns\n\n### Settings Not Saving\n\n**Problem**: Settings reset after closing app\n\n**Solutions**:\n1. Check `/ext/apps_data/miband_nfc/` exists\n2. Verify SD card is not write-protected\n3. Check logs for save errors\n4. Reinstall app if structure corrupted\n\n## Usage Workflow\n\n### First-Time Write to Blank Mi Band\n\n1. **Prepare**: Load your dump file\n   - Main Menu → \"Write Original Data\" → Select file\n2. **Initialize**: Emulate magic template\n   - Main Menu → \"Emulate Magic Card\"\n   - Place Mi Band near Flipper\n   - Watch auth counter reach ~16-32\n   - Remove Mi Band, press Back\n3. **Write**: Write actual data\n   - Main Menu → \"Write Original Data\"\n   - (Automatic backup if enabled)\n   - Place Mi Band near Flipper\n   - Watch progress bar complete\n   - Wait for \"Success\" message\n4. **Verify**: Confirm write\n   - (Automatic if enabled in settings)\n   - Or manually: \"Verify Write\"\n   - Check for any differences\n\n### Rewriting Mi Band (Data Already Present)\n\n1. Choose \"Write Original Data\"\n2. Select dump file\n3. Auto-backup runs (if enabled)\n4. Place Mi Band near Flipper\n5. Write automatically detects existing keys\n6. Auto-verify runs (if enabled)\n7. Check results\n\n### Quick Card Identification\n\n1. Choose \"Quick UID Check\"\n2. Place any NFC card near Flipper\n3. View UID and card information\n4. See list of matching dumps on SD card\n5. Press Back to return\n\n### Creating Magic Dumps\n\n1. Choose \"Save Magic Dump\"\n2. Select source dump file\n3. Watch conversion progress\n4. New file created with `_magic.nfc` suffix\n5. Use this file for easier magic card operations\n\n### Managing Logs\n\n1. Settings → \"Enable Logging\" (ON)\n2. Perform operations\n3. Settings → \"Export Logs\"\n4. Find in `/ext/apps_data/miband_nfc/logs/log_YYYYMMDD_HHMMSS.txt`\n5. Settings → \"Clear Logs\" to reset\n\n## File Locations\n\n```\n/ext/nfc/                          - NFC dump files\n/ext/nfc/backups/                  - Automatic backups\n/ext/apps_data/miband_nfc/         - App data directory\n/ext/apps_data/miband_nfc/logs/    - Exported log files\n/ext/apps_data/miband_nfc/settings.bin - Settings file\n```\n\n## Development Notes\n\n### Adding New Scenes\n\n1. Add scene entry to `miband_nfc_scene_config.h`:\n   ```c\n   ADD_SCENE(miband_nfc, my_new_scene, MyNewScene)\n   ```\n\n2. Create `miband_nfc_scene_my_new_scene.c` with handlers:\n   ```c\n   void miband_nfc_scene_my_new_scene_on_enter(void* context);\n   bool miband_nfc_scene_my_new_scene_on_event(void* context, SceneManagerEvent event);\n   void miband_nfc_scene_my_new_scene_on_exit(void* context);\n   ```\n\n3. Handlers are automatically registered via X-Macro pattern\n\n### Progress Display Guidelines\n\nFor long operations, update UI frequently:\n```c\n// Update text every iteration\npopup_set_text(app-\u003epopup, progress_text, 64, 18, AlignCenter, AlignTop);\n\n// Use delays to allow GUI updates\nfuri_delay_ms(100);\n\n// Don't call popup_reset() during progress\n// Set header/icon once at start, update text only\n```\n\n### Memory Management\n\n- All allocations in `miband_nfc_app_alloc()`\n- All deallocations in `miband_nfc_app_free()`\n- Scene-specific resources allocated in `on_enter`\n- Scene-specific resources freed in `on_exit`\n- Logger allocated before settings load\n\n### Logging Best Practices\n\n```c\n// Log important operations\nmiband_logger_log(app-\u003elogger, LogLevelInfo, \"Operation started\");\n\n// Log errors with details\nmiband_logger_log(app-\u003elogger, LogLevelError, \"Failed: sector %zu\", sector);\n\n// Check if logging enabled before expensive operations\nif(app-\u003eenable_logging) {\n    // Prepare detailed message\n}\n```\n\n## Performance Notes\n\n- Progress updates every 50-100ms for smooth display\n- Maximum 20 tool calls for file operations\n- Circular log buffer prevents memory exhaustion\n- Non-recursive directory scanning for speed\n- Settings cached in memory, saved on change\n\n## Credits\n\nDeveloped for Flipper Zero by LucasMac.\n\nBased on official Flipper NFC APIs and extensive testing with Mi Band devices.\n\n## License\n\nCheck Flipper Zero application license requirements.\n\n---\n\n**Version**: 1.0  \n**Last Updated**: 20251002  \n**Compatibility**: Flipper Zero Official Firmware","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLucaTomei%2Fflipper-miband-nfc-writer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLucaTomei%2Fflipper-miband-nfc-writer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLucaTomei%2Fflipper-miband-nfc-writer/lists"}