[!CAUTION]
🚨 SECURITY WARNING — DO NOT FLASH "L15Dev" FIRMWARE 🚨
A firmware build distributed under the name "L15Dev" / "Bitwire" has been reported to contain malware (a virus) and a backdoor. Do not download, flash, or run it under any circumstances.
Only use the official builds from this repository / the web flasher. If you already flashed an "L15Dev" image, re-flash a clean official build and treat any credentials/data on the device (WiFi passwords, captures) as compromised.
WARNING: I do not take responsibility if you damage your board or property. This guide is for educational purposes only — proceed at your own risk.
Flipper Zero ESP32 Port
A port of the Flipper Zero firmware to ESP32-based development boards. This project brings the Flipper Zero UI, services, and application framework to affordable ESP32 hardware — no Flipper Zero required.
Discord
Join the Flipper Zero meets ESP32 - Discord for support and announcements.
Supported Boards
| Board | MCU | Display | Input | SubGHz | NFC | IR | SD Card |
|---|---|---|---|---|---|---|---|
| LilyGo T-Embed CC1101 | ESP32-S3 (Xtensa LX7) | ST7789 320×170 | Rotary encoder + button | CC1101 | PN532 (I2C) | RMT TX + RX | SPI |
| Paradoxt | ESP32-S3 N16R8 (Xtensa LX7) | ST7789 320×170 | 6 buttons (4-way D-pad + OK + Back) | CC1101 + NRF24 | PN532 (I2C) | RMT TX + RX | SPI |
| Waveshare ESP32-C6-LCD-1.9 | ESP32-C6 (RISC-V) | ST7789V2 320×172 | CST816S touch | — | — | — | SPI |
| Waveshare ESP32-C6-LCD-1.47 ⚠️ | ESP32-C6 (RISC-V) | JD9853 320×172 | AXS5106L touch | — | — | — | SPI |
| DIY ESP32-S3 (N16R8) | ESP32-S3 (Xtensa LX7) | ST7789 320×172 | 6× Tactile buttons | CC1101 (+ NRF24) | PN532 (I2C) | TX + RX | SPI |
| Fatal Core / FATALCORE BTW (hardware) | ESP32-S3 (Xtensa LX7, 16 MB flash / 8 MB PSRAM) | ST7789 320×172 | 6× Tactile buttons (4-way D-pad + OK + Back/Power) | CC1101 (shared SPI) + nRF24 | ST25R3916 (SPI) | TX + RX | SPI (shared, hardened) |
| ThorChimera | ESP32-S3 (Xtensa LX7) | ST7789 320×170 | Rotary encoder + button | CC1101 + NRF24 | PN532 (I2C) | RMT TX + RX | SPI |
| ThorMini | ESP32-S3 (Xtensa LX7) | SSD1306 / SH1106 OLED (I²C) | 6× buttons | CC1101 + NRF24 | PN532 (I2C) | TX + RX | SPI |
| M5Stack M5Stick S3 † | ESP32-S3-PICO (8 MB PSRAM) | ST7789 135×240 | 2 buttons + BMI270 tilt-to-wake | CC1101 + NRF24 † | PN532 (I2C) † | RMT TX + RX | SPI (+ LittleFS) |
| M5Stack Cardputer ADV † | ESP32-S3FN8 (no PSRAM) | ST7789V2 240×135 | TCA8418 QWERTY keyboard | CC1101 + NRF24 † | PN532 (I2C) † | RMT TX + RX | SPI |
† M5Stick S3 and Cardputer ADV are early bring-up (added in #112). Display, input, IR and BLE work; the SubGHz / NFC / nRF24 subsystems are present in the board profile but not yet hardware-validated on these M5 devices.
⚠️ Waveshare ESP32-C6-LCD-1.47 — supported but barely usable. The board builds, boots and the UI/touch work, but the ESP32-C6 has only 512 KB SRAM and no PSRAM. RAM-heavy apps are effectively non-functional. In particular WiFi: a normal AP scan works, but monitor mode / handshake capture fails — by the time the app's buffers are allocated the WiFi driver can no longer allocate its DMA buffers (esf_buf_setup_static: alloc eb fail → ESP_ERR_NO_MEM), so no frames are received. Treat this board as usable only for lightweight apps until the WiFi app's memory footprint is reduced (it was designed for the PSRAM-equipped T-Embed).
🔧 DIY board — edit Pinout.txt in the repository root to match your wiring, then build with ./build_diy.sh. board_DIY.h is generated from it automatically and the pins are validated at configure time.
How to Flash
The easiest way is the web flasher — no toolchain required, just a Chrome/Edge browser and a USB cable:
Flash via Browser
Connect your board, click flash, done. After flashing, copy the contents of sdcard.zip onto a FAT32 SD card and insert it — most apps need files there to function.
Firmware Update
Since v2.0.0 the T-Embed can update itself — no PC toolchain or re-flashing required:
- Over WiFi (OTA): Settings → Update Firmware checks the release server for a newer build,
downloads and installs it in the background, then reboots. It also keeps your SD card files in sync.
- Over USB: use the qT-Embed desktop companion (a
qFlipper-style app for this port) to stream the display, manage SD files and flash firmware over
USB — including a Full flash option (bootloader + partition table + firmware) to recover a device.
Requires the dual-OTA partition layout. A device on the old single-app layout has to be flashed
once via the web flasher (or qT-Embed's Full flash) before wireless OTA updates work.
Apps
📡 Wireless / RF
Sub-GHz
External CC1101 receiver/transmitter for 433–868 MHz signals.
- Receive & decode
- Read RAW: capture unknown waveforms to
.sub files for later analysis
- Frequency analyzer with sweep & live RSSI
- RF Spectrum Analyzer — colorful, HackRF-style live spectrum view
- Hopper: scan all preset bands during receive
- Transmit saved files; manual signal creation (frequency, modulation, protocol, key/serial/counter)
- Brute force / sub-brute attack with manufacturer dictionary
- Playlist for sequential transmit
- Jammer — continuous carrier/noise jammer on a selected frequency
- External FAP launchers — the Sub-GHz menu also shows ProtoPirate and wM-Burst entries when those FAPs are installed on the SD card
- More protocols — added KeeLoq variants (ERREKA, PUJOL, AERF, SIMPLE_JCM), Agilize Key Pro and Holtek HT6P20B
- TPMS decoding — tire-pressure sensors: Schrader GG4, Citroën, Ford, Renault, Toyota (PMV107J) and a generic decoder; dedicated info view with editable sensor data
- Limitation: AES-encrypted manufacturer keystores (
keeloq_mfcodes, nice_flor_s, alutech_at_4n) are not decryptable on this port — only the plain-text keeloq_mfcodes_user works for Keeloq decoding.
Sub-GHz Remote
Multi-button remote layouts that batch saved .sub files. Map Up/Down/Left/Right/OK to individual transmit signals; switch between persistent remote profiles.
WiFi
Full WiFi pentest toolkit.
- Scanner — SSID, BSSID, channel, RSSI, auth mode
- WiFi Live Scan — passive monitor-mode view of beacon/probe-response AP announcements; records up to 64 APs in RAM with BSSID, SSID, RSSI, channel, security and vendor details. It does not save a scan file and can disconnect an active WiFi station connection while taking over the radio.
- Connect — auto-detect WPA/WPA2/WPA3, password input or saved password lookup (
/ext/wifi/<ssid>.txt)
- Deauther — scanner, SSID-mode (single AP) or Channel-mode (all on channel)
- Smart Deauth — scans APs and observed stations, offers a selected target view and a monitor view with RSSI/PMF information
- Sniffer — capture packets to PCAP (saved to
/ext/wifi/)
- Deauth All — scans APs on start, then cycles through that AP list sending deauthentication/disassociation traffic. Optional periodic rescans use a saved 10–60 second interval. The implementation does not enumerate associated client stations; use only on networks you own or are authorized to test.
- Handshake capture — record EAPOL 4-way handshakes, optionally with deauth trigger
- AirSnitch — auto-bruteforce target with password list
- Beacon Spam — Funny SSIDs / Rickroll / Random / Custom
- Network Scan / Port Scan — host discovery + 19 common-port probe on the connected network
- MITM — ARP-spoof man-in-the-middle on the connected LAN: live credential capture and HTML/JS code injection into a target's web traffic
- Evil Portal — captive portal with credential harvesting
- Built-in templates: Google login, Router firmware update
- Custom templates from
/ext/wifi/evil_portal/login_template/*.html and /ext/wifi/evil_portal/router_template/*.html (filename = template name in dropdown)
- Marker substitution:
%ERROR%, %SSID_OPTIONS% (live AP scan)
- Router-style verify flow: dropdown of real SSIDs, live WLAN re-auth check, captured-credentials screen on success, retry with error banner on fail
- Pause/Resume of the AP from the run screen
- Captured creds saved to
/ext/wifi/evil_portal/<ssid>_creds.csv
- Internet bridge (new) — optional STA uplink with NAPT + DNS forwarding so victims get real internet behind the portal; iOS captive-portal "Success" handling; uplink SSID/password configured in-app
- Web-Filesystem — HTTP file server for the SD card; open it in a browser (device hotspot or your existing WiFi) to upload, download, rename and delete files, with drag & drop for whole folders
- SMB Browser — browse and download from SMB2/3 network shares (Windows / macOS / NAS) straight to the SD card; guest or password login
- Android TV Remote — control any Android / Google TV (Sony, NVIDIA Shield, Xiaomi Mi Box, Chromecast, …): scan → pair once with the on-screen PIN → on-screen remote (D-Pad, volume, media, power)
- AirPrint — virtual AirPrint/IPP network printer; advertises over mDNS and saves incoming print jobs to the SD card
- Global toggle — WiFi is now an on/off switch like Bluetooth (from the lock menu); the connection persists across apps and reconnects automatically after a reboot
Mesh / Buddy (ESP-NOW)
Pair cheap headless ESP32 boards (buddies) to the T-Embed (master) over ESP-NOW to offload WiFi capture and run remote actions.
- Buddy discovery, pair/remove and live status from the lock menu → Mesh Clients
- Device Identify — make a paired buddy blink to locate it
- WiFi handshake capture — buddy passively captures EAPOL handshakes on a chosen channel (1–13)
- Store-and-forward — the buddy holds each complete handshake (M1–M4 + beacon) durably (RAM + NVS) per BSSID and delivers it as one acknowledged unit, surviving master absence and buddy reboots
- One
.pcap per network written to /ext/wifi/buddy_<name>_<ssid>.pcap; "Handshake received" overlay on all mesh views
- Buddy firmware ships in this repo under
buddy_firmware/ (standalone headless ESP-IDF project)
Bluetooth
- BLE Spam — Apple Continuity (Pair/Action/NotYourDevice), Google FastPair (455+ models), Microsoft SwiftPair, Samsung Buds & Watch, Xiaomi QuickConnect
- BLE Walk — passive scanner with GATT service/characteristic inspection
- Auto Walk — automated BLE walk with logging
- Tracker — BLE tracker scanner with a "geiger" proximity view
- Airoha RACE — detector for the Airoha RACE GATT service (CVE-2025-20700)
- FindMy — emulate Apple AirTag, Samsung SmartTag, Tile beacons (clone or generate keypairs)
- HID (see below) — keyboard/mouse/media remote over BLE
- Bad USB — via USB or BLE
NRF24 (2.4 GHz, external nRF24L01)
- Spectrum analyzer — live 2.4 GHz channel activity
- Jammer (rewritten) — one engine with switchable channel sources (Protocol / WiFi / Activity scan), strategies (CW / Flood / Turbo / AFH) and presets; configuration persists per source
- MouseJacker — inject keystrokes into vulnerable wireless mice/keyboards
- Also available as a FAP (
nRF24_jammer)
Infrared
RMT-based TX + RX.
- Learn signals (auto-decoded or raw)
- Browse, edit, and send saved remotes
- Universal remotes: TV, AC, audio, projectors, fans, LED controllers (databases on SD)
- Brute force category-based databases
- Configurable IR pin and 5 V GPIO power
- Protocols: NEC, NEC42, Samsung32, RC5/RC5X, RC6, SIRC 12/15/20, Kaseikyo, RCA, Pioneer
🪪 NFC
NFC (PN532 over I2C)
- Read, save, emulate, write NFC cards/tags
- Manual card generation (custom UID/ATQA/SAK)
- Mifare Classic dictionary attack (system + user dictionaries)
- Mifare Ultralight-C dictionary unlock
- ISO15693 SLIX unlock with manual or stored DEF key
- FeliCa system info, MIFARE DESFire app inspection, EMV transaction history
- 14 supported protocols: ISO14443-3A/3B/4A/4B, ISO15693-3, FeliCa, MIFARE Classic/Ultralight/Plus/DESFire, SLIX, ST25TB, NTAG4xx, Type-4
- 30+ supported card auto-parsers (Charlie Card, Clipper, EMV, Gallagher, HID, Opal, Skylanders, Troika, …)
Passy (FAP)
Biometric passport (MRTD) reader — reads and displays data groups from ePassports over NFC. Shipped as a prebuilt FAP in sdcard.zip.
TagTinker (FAP)
Infrared ESL (Electronic Shelf Label) research toolkit. Transmits custom images/text to graphics tags via IR. RLE streaming, Android companion app for image editing, monochrome + accent-color support.
⌨️ HID / USB
Bad USB
HID payload runner for Ducky-script (.txt) files from /ext/badusb/.
- 16+ Ducky commands (DELAY, STRING, REPEAT, HOLD/RELEASE, MEDIA keys, mouse, ALT-CHAR/ALT-STRING, SYSRQ)
- Layouts under
/ext/badusb/assets/layouts/*.kl (~30 included)
- Configurable USB VID/PID + device name
- BLE bonding with custom MAC and PIN-verify pairing
- Mouse movement, scroll, button emulation; per-character typing delay
- Transport: USB OTG (TinyUSB) on T-Embed, BLE on Waveshare
U2F (USB FIDO)
USB HID FIDO U2F authenticator for configured ESP32-S3 profiles. Supports U2F registration and authentication with on-device user confirmation and a persistent signature counter; it does not implement CTAP2/WebAuthn passkeys. When no usable attestation certificate is present, the app offers a Generate button that creates a device-specific self-signed P-256 certificate/key on the device — no PC tooling or manual file copying required (you can still install your own pair). Certificate provisioning, USB ownership constraints and recovery notes are in the U2F guide.
🛠 System / Tools
Lock Menu / System Toggles
The desktop lock menu doubles as the central system control panel (board-dependent, scrollable):
- qFlipper — enable the qFlipper desktop bridge (VID/PID spoof + CDC RPC) so the official qFlipper app can connect (USB-OTG boards)
- USB Storage — expose the SD card as a USB mass-storage device (USB-OTG boards)
- Bluetooth — toggle BLE on/off
- WiFi — toggle WiFi on/off (mutually exclusive with Bluetooth; reconnects to the last network automatically)
- Web-Filesystem — start the SD-card web file server (see WiFi above)
- Mesh Clients — buddy discovery & control (see Mesh / Buddy above)
Archive
SD-card file browser with tabs per media type: Favorites, Sub-GHz, Sub-GHz Remote, NFC, LF-RFID, Infrared, iButton, Bad USB, U2F, Apps, Internal, Browser. Pin/unpin favorites; copy, paste, rename, delete, create folder.
JS Runner
mJS-based JavaScript runtime for user scripts in /ext/apps/Scripts/*.js.
- Available modules:
gui (loading/menu/dialogs/text+byte input/popup/file picker/widget), notification, math, storage, event_loop, subghz, infrared, badusb, blebeacon
- Excluded on this port (need HAL porting):
js_serial, js_gpio, js_i2c, js_spi
🎵 Media
Streaming
Unified music & video player (replaces the old separate MP3/Video apps). Browse .mp3 and .mp4
files from /ext/apps_data/medien.
- Music — play locally through the speaker, or stream to AirPlay speakers
- Cast to your network — Chromecast / Google Cast and DLNA devices, including TVs (music & video)
🎮 Games
Doom
Full DOOM port. Place doom1.wad at /ext/apps_data/doom/doom1.wad. Encoder turns; click fires (short) / walks forward (long). Side-button uses doors/switches (short) / opens menu (long).
Wolf3D
Wolfenstein 3D port (T-Embed only — same PSRAM, 320×N display and I2S requirements as Doom).
Snake
Classic snake game.
⚙ Settings & General
Bluetooth, backlight, clock, dolphin/passport, notification, power, storage, system info, factory reset. Animated dolphin desktop on idle. File-pack manifest at /ext/Manifest (qFlipper-style asset list — its presence suppresses the "No DB" boot animation).
- Desktop — configure the desktop PIN, automatic lock timeout and USB-session auto-lock behavior; assign favorite apps and Dummy Mode actions to button shortcuts.
- Update Firmware — wireless OTA firmware + SD-card update (see Firmware Update above)
- Interface — customize the main menu and its layout
- Spoofing — change the device name and the shell/terminal color
SD Card Layout
| Path | Used by |
|---|---|
| /ext/Manifest | Desktop (presence check) |
| /ext/dolphin/ + manifest.txt | Idle animations |
| /ext/asset_packs/<pack>/ | Custom desktop animation packs selected in Settings → Interface → Graphics → Asset Pack. The pack manifest may be in the pack root or its Anims/ subfolder. |
| /ext/apps_assets/fmtx/ | MP3 tracks required by the FMTX FAP. |
| /ext/apps_assets/proto_pirate/ | ProtoPirate plugins, model database, and keystore data; keep with the updated ProtoPirate FAP. |
| /ext/apps_assets/nfc/plugins/ | NFC protocol plugins (.fal) |
| /ext/apps_data/nfc/plugins/ | NFC card-parser plugins (.fal) |
| /ext/apps_data/js_app/plugins/ | JS module bindings (.fal), including the updated js_badusb.fal (replace the older file; other plugins are unchanged). |
| /ext/apps_data/doom/doom1.wad | Doom |
| /ext/badusb/ | Bad USB scripts + assets/layouts/*.kl |
| /ext/infrared/assets/ | Universal remote DBs (tv.ir, ac.ir, audio.ir, projectors.ir, fans.ir, leds.ir) |
| /ext/nfc/assets/ | MIFARE & EMV dictionaries |
| /ext/subghz/assets/ | SubGHz keystores + dangerous_settings |
| /ext/u2f/assets/ | Updated U2F certificate/key pair; replace an older pair together (see sdcard/README.md) |
| /ext/wifi/<ssid>.txt | Saved WiFi passwords |
| /ext/wifi/deauth_all.cfg | Deauth All scan settings |
| /ext/wifi/buddy_<name>_<ssid>.pcap | Mesh/Buddy handshake captures |
| /ext/wifi/evil_portal/login_template/ | Custom captive-portal templates (no verify) |
| /ext/wifi/evil_portal/router_template/ | Custom captive-portal templates (with WLAN verify) |
SD card files included in this repository
The sdcard/ directory mirrors the root of an SD card and keeps files that developers may need to copy or package with the firmware. Copy the contents of this directory to the card root; do not create an extra sdcard/ directory on the card.
| Repository path | SD card path | Contents |
|---|---|---|
| sdcard/apps/ | /apps/ | Prebuilt FAP packages included with this project. FAP source, where available, is kept under applications_user/. |
| sdcard/asset_packs/ | /asset_packs/ | 35 desktop animation packs from the supplied SD card; select them in Settings → Interface → Graphics → Asset Pack. |
| sdcard/u2f/assets/ | /u2f/assets/ | Matching cert.der and cert_key.u2f files required by U2F. On first use, firmware imports and encrypts the certificate key; see the U2F guide. |
A complete starter kit is in sdcard.zip — extract it onto a FAT32 SD.
The repository-side SD card files, including the FAP binaries required on the card, are documented in sdcard/README.md.
Building
Prerequisites
- ESP-IDF v5.4.1 (exact version required)
- ESP-IDF export script sourced (default:
~/esp/esp-idf/export.sh)
Build & Flash (Linux / macOS)
# T-Embed (auto-detects /dev/cu.usbmodem*)
./buildAndFlash_T-Embed.sh
# Build only
./buildAndFlash_T-Embed.sh --build-only
# Waveshare ESP32-C6
./buildAndFlash_Waveshare_c6_1.47.sh
./buildAndFlash_Waveshare_c6_1.9.sh
#DIY ESP32-S3
./build_diy.sh
# Fatal Core / FATALCORE BTW (ST25R3916 NFC over SPI)
./build.sh --board fatalcore --build-only
# Generic builder for the other boards: ./build.sh --board <name>
# supported: t_embed, esp32s3, fatalcore, paradoxt, waveshare_c6, waveshare_c6_1.9, waveshare_c6_1.47
./build.sh --board paradoxt
The newer ThorChimera, ThorMini, M5Stick S3 and Cardputer ADV targets do not yet have a
dedicated shell script — build them through winbuild.py (python winbuild.py build --board <name>).
Build & Flash (Windows)
Use winbuild.py — a single CLI that wraps build, flash and serial-monitor steps for cmd.exe / PowerShell. Requires Python 3 and ESP-IDF v5.4.1 installed at C:\Espressif\frameworks\esp-idf-v5.4.1 (or override via ESP_IDF_DIR).
:: One-time: install ESP-IDF python env
python winbuild.py setup
:: Verify the toolchain activates
python winbuild.py check
:: Build T-Embed CC1101 (default board)
python winbuild.py build
:: Build Waveshare ESP32-C6
python winbuild.py build --board waveshare_c6
:: Flash (port defaults to %ESPPORT% or COM14)
python winbuild.py flash --port COM14
:: Stream serial output for N seconds
python winbuild.py monitor --duration 30
:: Build + flash + monitor in one go
python winbuild.py all --port COM14
Boards: t_embed (default), esp32s3, paradoxt, thorchimera, thormini, m5stick_s3, cardputer_adv, waveshare_c6 (or waveshare_c6_1.9), waveshare_c6_1.47. Override defaults with ESP_IDF_DIR and ESPPORT env vars. monitor --reset only works on USB-UART bridges, not on the ESP32-S3 native USB-Serial/JTAG — use flash or all to capture boot logs.
Build a FAP
# Firmware must be built first (Linux/macOS)
./buildFap.sh applications/main/my_app
Debug: light-sleep telemetry
Idle light sleep (screen off, on battery) is gated at runtime and runs silently.
To measure it, build with CONFIG_PM_LIGHT_SLEEP_CALLBACKS=y (menuconfig, or add
it to sdkconfig.defaults.esp32s3). The input service then logs a line every 5s:
lightsleep: allow=1 count=1234 slept=48000ms/50000ms (96%) wake[t=1230 g=4 o=0]
Counters persist while the device stays powered, so idling on battery and then
reconnecting USB reports the sleep accumulated during the battery window. Leave
the option off for normal builds; it adds a small always-on callback.
Porting Approach
This port preserves the original Flipper Zero architecture as closely as possible:
- Furi OS runs on FreeRTOS with the same thread/mutex/event/record API
- Services (GUI, Input, Storage, Loader, Desktop, BT) use the same message-queue and record-system patterns
- HAL maps STM32 peripherals to ESP-IDF drivers (SPI →
esp_lcd, I2C → CST816S/PN532, RMT → IR, Bluedroid → BLE, TinyUSB → USB-HID)
- Display renders the original 128×64 mono framebuffer, then 2× upscales to RGB565 for the color LCD
- Applications compile with minimal changes (
#include path adjustments, no-op stubs for missing hardware like 1-Wire)
malloc is redefined to calloc — STM32 heap starts zeroed, ESP32 does not
- Crypto is stubbed (no Flipper-Enclave key) — affects encrypted SubGHz keystores; everything else uses real mbedtls
T-Embed Native Tools integration proposal
See the developer review guide for the
consolidated app inventory, firmware changes, build instructions, provenance,
validation status, and remaining hardware acceptance work.