⚙️ DIY Flipper Zero (OLED Version)

Custom firmware fork supporting standard I2C OLED screens (SH1106 and SSD1306) on DIY Flipper hardware.

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.

Tip

❓ Need help or have questions about building/flashing the DIY Flipper? Join our community Q&A and troubleshooting discussion: GitHub Q&A Discussion #1

📷 Hardware Showcase

Here is the physical DIY board in action:

🔍 Summary

This project implements a custom target for a DIY Flipper-style board based on the WeAct STM32WB55CGU6 board. It integrates the following components:

Display: I2C OLED display (SH1106 / SSD1306)
Sensors: INA219 / INA226 power & battery monitor (I2C) with hardware Alert (PB1)
I/O Expander: MCP23017 (handles buttons, RGB LED, and vibration motor)
Storage: microSD slot (SPI)
Radio: CC1101 sub-GHz module (SPI)
NFC: ST25R3916 Elechouse module (SPI)
LF-RFID (125 kHz): Antenna coil driver & envelope detector (PA5 Carrier TX / PA1 Data RX)
Peripherals: Speaker/buzzer, IR transmitter/receiver, vibration motor

📐 System Architecture

This diagram visualizes how the different components interface with the STM32WB55 MCU over I2C, SPI, and GPIO.

graph TD
    subgraph MCU [STM32WB55CGU6]
        I2C1[I2C1 Bus]
        SPI1[SPI1 Bus]
        GPIO[Direct GPIO]
    end

    %% I2C Bus Devices
    I2C1 --> OLED[OLED Display <br> SH1106 / SSD1306]
    I2C1 --> INA[INA219 / INA226 <br> Battery Monitor]
    I2C1 --> MCP[MCP23017 <br> I/O Expander]

    %% MCP23017 Expanders
    MCP --> Buttons[6-Way Buttons + Back]
    MCP --> RGB[RGB Status LED]
    MCP --> Vibro[Vibration Motor]

    %% SPI Bus Devices
    SPI1 --> SD[MicroSD Card CS: PA10]
    SPI1 --> CC1101[CC1101 Radio CS: PA15]
    SPI1 --> NFC[ST25R3916 NFC CS: PE4]

    %% GPIO
    GPIO --> IR_RX[IR Receiver PA0]
    GPIO --> IR_TX[IR Transmitter PA8]
    GPIO --> Speaker[Speaker PB8]
    GPIO --> OneWire[1-Wire iButton PA3]
    GPIO --> RFID_TX[LF-RFID TX PA5]
    GPIO --> RFID_RX[LF-RFID RX PA1]

✅ What Works and Limitations

Core Systems: All official Flipper firmware features compile and function.
I2C Devices: OLED, INA219 / INA226, and MCP23017 are multiplexed onto the primary I2C1 bus to preserve SPI resources.
Power Monitoring: Automatic dual INA219 / INA226 detection with hardware overcurrent/undervoltage Alert interrupt on PB1.
NFC Support: Verified working with Elechouse ST25R3916 modules.
LF-RFID (125 kHz): Reading, writing, and emulation verified for EM4100, HID Generic, Indala26, Keri, NexWatch, Noralsy, Viking, and IDTeck.
Sub-GHz: CC1101 module tested and fully functional.

📌 Key Pins and Wiring

Component	Bus / Interface	MCU pin (macro)	Notes
I2C1 (Power/Default)	I2C	SCL: PA9, SDA: PB9	Used by INA219, MCP23017, and OLED
I2C3 (External)	I2C	SCL: PA7, SDA: PB4	Reserved for external modules/sensors
SPI1 (Shared)	SPI	MOSI: PB5, SCK: PB3	Shared SCK/MOSI bus for CC1101, NFC, and SD card
CC1101	SPI + IRQ	CS: PA15, MISO: PA6, G0: PA1	Sub-GHz transceiver (G0 uses PA1 / TIM2_CH2; shared with LF-RFID RX)
SD card	SPI	CS: PA10, MISO: PA6	MicroSD module
NFC	SPI	CS: PE4, MISO: PB4, IRQ: PA2	Elechouse ST25R3916 reader (Uses dedicated MISO)
MCP23017 Interrupt	GPIO	INT: PB0	Signals button state changes
IR	GPIO	RX: PA0, TX: PA8	Safe IR transmitter & receiver
LF-RFID (125 kHz)	PWM / Timer	TX Carrier: PA5 (TIM2_CH1), RX Data: PA1	125 kHz coil driver + envelope demodulator (COMP1, shares PA1 with CC1101 G0)
Speaker	PWM	PB8 (TIM16)	Sound buzzer
iButton	1-Wire	PA3	Dallas 1-Wire keys

🔌 External GPIO Header Pinout (18-Pin)

The DIY Flipper Zero features a standard 18-pin expansion header fully compatible with Flipper Zero accessories. Below is the exact hardware routing and peripheral mapping:

Header Pin	Flipper OS Name	Physical MCU Pin	Available Hardware Functions	Notes & Usage
1	5V	—	+5V Power Output (from USB VBUS)	Power external modules
2	A7 (PA7)	PB5	GPIO, PWM (TIM1), SPI1 MOSI	Shared with on-board SPI1 MOSI bus (SD / CC1101)
3	A6 (PA6)	PA6	GPIO, ADC (CH11), SPI1 MISO	Shared with on-board SPI1 MISO bus (SD / CC1101)
4	A4 (PA4)	PA4	GPIO, ADC (CH9), PWM (LPTIM2)	Dedicated free GPIO / ADC / PWM
5	B3 (PB3)	PB3	GPIO, SPI1 SCK	Shared with on-board SPI1 SCK clock line
6	B2 (PB2)	PB2	GPIO	Dedicated free GPIO
7	C3 (PC3)	PA5	GPIO, ADC (CH4), TIM2_CH1	Routed to PA5 (used internally for LF-RFID 125 kHz TX carrier)
8	GND	—	Ground (GND)	Common ground
9	3V3	—	+3.3V Power Output	Main regulated 3.3V power rail
10	SWCLK	PA14	SWD Clock, Debug GPIO	Hardware debug / ST-Link SWD clock
11	GND	—	Ground (GND)	Common ground
12	SWDIO	PA13	SWD Data, Debug GPIO	Hardware debug / ST-Link SWD data
13	TX	PB6	USART1 TX, GPIO	Hardware UART Transmit (Serial CLI / external sensors)
14	RX	PB7	USART1 RX, GPIO	Hardware UART Receive (Serial CLI / external sensors)
15	C1 (PC1)	PB4	GPIO, ADC (CH2), I2C3 SDA	Shared internally with I2C3 SDA and NFC MISO
16	C0 (PC0)	PA7	GPIO, ADC (CH1), I2C3 SCL	Shared internally with I2C3 SCL
17	1W (iButton)	PA3	1-Wire, GPIO	Dallas 1-Wire key read & emulation (DS1990)
18	GND	—	Ground (GND)	Common ground

Tip

Recommended General-Purpose Pins: Pins 4 (PA4) and 6 (PB2) are completely unshared and ideal for relays, servos, buttons, or custom sensors.
External SPI Modules: When connecting external SPI devices to Pins 2 (MOSI), 3 (MISO), and 5 (SCK), use Pin 4 (PA4) or Pin 6 (PB2) as a dedicated Chip Select (CS) line.

🎛️ MCP23017 Wiring Guide

The MCP23017 handles all buttons, status LEDs, and haptic feedback. Connect them in an active-low configuration (connecting to GND when pressed/active).

Port A (Button Inputs):
- GPA0 -> Up Button
- GPA1 -> Right Button
- GPA2 -> OK Button
- GPA3 -> Back Button
- GPA4 -> Down Button
- GPA5 -> Left Button
Port B (Outputs):
- GPB0 -> Haptic Vibration Motor (Use an N-channel MOSFET; do not drive directly!)
- GPB1 -> RGB Red Channel
- GPB2 -> RGB Green Channel
- GPB3 -> RGB Blue Channel

🛠️ How to Build and Flash

1. Build from Source

To compile the firmware for the OLED hardware target, use the Flipper Build Tool:

# Build the target DFU package
./fbt

2. Configure & Flash OTP (One-Time Programmable) Memory

Caution

OTP memory can only be written ONCE. It cannot be erased or changed. Proceed at your own risk.

Open generate_otp_gui.exe (found in the mics/FlipperOTP/ folder). No installation required.
Set your Device Name (max 8 ASCII characters) and Board Version (12 for WeAct STM32WB55).
Select Display Type: MGG (Monochrome Glass Grid) — required for the SSD1306 OLED screen.
Put the MCU into DFU mode: hold BOOT0, connect USB, release BOOT0. The app status will show 🟢 Connected.
Click "2. Flash (DFU)" — the tool writes OTP directly to 0x1FFF7000.

Tip

Alternatively, click "1. Save .bin" to generate the file, then flash it manually via STM32CubeProgrammer.

3. Flash Firmware

Choose the appropriate method depending on whether you are setting up the board for the first time or just updating the firmware.

Method A: First-Time Setup (or after a Full Flash Erase)

Use this method if the board is blank, has no bootloader, or was fully erased.

Put the board in DFU mode (hold BOOT0, connect USB, release BOOT0).
Open the qFlipper desktop application.
qFlipper will detect the board and display "RECOVERY MODE" (or "Update & Recovery Mode DFU started").
Click the "REPAIR" button. qFlipper will automatically restore the official bootloader and partition the internal Flash.
Once the recovery is complete, the screen might remain blank (since the official firmware lacks OLED drivers), but the device will now connect to qFlipper.
Now, put the board back into DFU mode again (so it doesn't freeze under the official firmware).
Click "Install from file" in qFlipper.
Choose your preferred update style:
- Using the .tgz package (Recommended): Select the .tgz archive. qFlipper will flash the firmware (the OLED screen will turn on), reboot into normal mode, and then copy the required resource files to your SD card automatically.
- Using the .dfu file (Manual): Select the .dfu firmware file to flash it (OLED turns on). After it boots, you will need to manually unzip the resources package and copy the files to the root of your microSD card.

Method B: Regular Firmware Updates

Use this method to update an already working DIY Flipper.

Using the .tgz package: Connect the Flipper to your PC via USB, open qFlipper, click "Install from file", and select the updated .tgz archive. qFlipper will automatically flash the MCU and update all SD card files in one go.
Using the .dfu file: Put the board in DFU mode, open qFlipper, click "Install from file", and select the updated .dfu firmware file.

Option C: Flashing via STM32CubeProgrammer / ST-Link (Advanced)

Warning

DO NOT use "Full Chip Erase" in STM32CubeProgrammer! Doing a full chip erase will wipe out the emulation OTP structures, flash partition tables, and calibration settings. If these are wiped, the firmware will freeze early during boot (leading to a blank screen and USB connection loss).

Set the Erase option to "Sector Erase" (only erase sectors occupied by the firmware).
If you did a full chip erase by mistake, follow Method A (First-Time Setup) to rebuild the device partitions first.

🔌 Schematic & Hardware Circuit

A complete wiring schematic is available in the repository:

📻 LF-RFID (125 kHz) Circuit Details & Schematic:

📄 Schematic PDF: Download 125kHz LF-RFID Subsystem Schematic (PDF)

Component Bill of Materials (BOM) from KiCad Schematic:

Stage	Component	Value / Part	Description
Transmitter Driver [1]	`PA5` (PWM)	MCU `TIM2_CH1`	125 kHz Carrier PWM Drive
	`Q1`	BC337 / S8050 / 2N2222	NPN Push-Pull Transistor
	`Q2`	BC327 / S8550 / 2N2907	PNP Push-Pull Transistor
	`C1`	2.2 nF	Drive Coupling Capacitor
Resonant Tank [2]	`L1`	1.2 mH / 95T	Antenna Coil
	`PA2` (Emulate)	MCU `TIM2_CH3`	Emulation Pulse Driver (`R2` 1k, `R8` 10k)
	`Q3`	2N2222	Emulation Switch Transistor (`R1` 100 Ohm)
Demodulator [3]	`D1`	1N4148 / BAT54S	Envelope Schottky Diode
	`C3`, `R3`	1 nF, 10 kOhm	RC Low-Pass Filter
	`C4`, `R4`	22 nF, 10 kOhm	AC Coupling Stage
	`U1`	LM2904 / LM358 / MCP6002	Op-Amp Signal Amplifier (`R5`-`R7` 100k, `R9` 50k)
	`PA1` (Data In)	MCU `COMP1 (IO3)`	Demodulated RX Envelope Input

🤝 Credits and Support

Special thanks to:

Nucleus Dark & Lamtran for their design inspiration and code contributions.

☕ Support this Project

If you find this project useful and would like to support its development, you can buy me a coffee here:

Ko-fi: Support artema0g on Ko-fi

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
applications		applications
applications_user		applications_user
assets		assets
disabled_apps		disabled_apps
documentation		documentation
furi		furi
lib		lib
mics		mics
misc		misc
resources		resources
scripts		scripts
site_scons		site_scons
targets		targets
.clang-format		.clang-format
.clangd		.clangd
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
.pvsconfig		.pvsconfig
.pvsoptions		.pvsoptions
.sublime-project		.sublime-project
CHANGELOG.md		CHANGELOG.md
CODING_STYLE.md		CODING_STYLE.md
FUNDING.yml		FUNDING.yml
LICENSE		LICENSE
ReadMe.md		ReadMe.md
SConstruct		SConstruct
faq_diy_flipper.md		faq_diy_flipper.md
fbt		fbt
fbt.cmd		fbt.cmd
fbt_options.py		fbt_options.py
firmware.scons		firmware.scons
social_preview.png		social_preview.png
tsconfig.json		tsconfig.json

Navigation Menu

Repository navigation

About

Repository files navigation

⚙️ DIY Flipper Zero (OLED Version)

📷 Hardware Showcase

📚 Table of Contents

🔍 Summary

📐 System Architecture

✅ What Works and Limitations

📌 Key Pins and Wiring

🔌 External GPIO Header Pinout (18-Pin)

🎛️ MCP23017 Wiring Guide

🛠️ How to Build and Flash

1. Build from Source

2. Configure & Flash OTP (One-Time Programmable) Memory

3. Flash Firmware

Method A: First-Time Setup (or after a Full Flash Erase)

Method B: Regular Firmware Updates

Option C: Flashing via STM32CubeProgrammer / ST-Link (Advanced)

🔌 Schematic & Hardware Circuit

📻 LF-RFID (125 kHz) Circuit Details & Schematic:

Component Bill of Materials (BOM) from KiCad Schematic:

🤝 Credits and Support

☕ Support this Project

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

⚙️ DIY Flipper Zero (OLED Version)

📷 Hardware Showcase

📚 Table of Contents

🔍 Summary

📐 System Architecture

✅ What Works and Limitations

📌 Key Pins and Wiring

🔌 External GPIO Header Pinout (18-Pin)

🎛️ MCP23017 Wiring Guide

🛠️ How to Build and Flash

1. Build from Source

2. Configure & Flash OTP (One-Time Programmable) Memory

3. Flash Firmware

Method A: First-Time Setup (or after a Full Flash Erase)

Method B: Regular Firmware Updates

Option C: Flashing via STM32CubeProgrammer / ST-Link (Advanced)

🔌 Schematic & Hardware Circuit

📻 LF-RFID (125 kHz) Circuit Details & Schematic:

Component Bill of Materials (BOM) from KiCad Schematic:

🤝 Credits and Support

☕ Support this Project

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages