pyFlipper Python Wrapper for Flipper Zero

pyFlipper is an unofficial Python wrapper for the Flipper Zero command-line interface (CLI). It allows developers to interact with a Flipper Zero device through Python code, making it easier to automate device management, access storage, and perform supported power and firmware operations.

The project supports direct serial communication and a WebSocket client interface for connecting through a remote serial-to-WebSocket server. This makes pyFlipper useful for scripting, prototyping, and authorized hardware research.

Key Features of pyFlipper

• Serial CLI wrapper: Communicate with a Flipper Zero through a local serial connection.
• WebSocket client: Connect to a remote serial-to-WebSocket server.
• Power management: Retrieve device power information, shut down, reboot, or enter DFU mode.
• Update and backup operations: Install supported update files and back up or restore device storage.
• Storage management: Browse directories, inspect files, read and write data, and perform common filesystem operations.
• Python integration: Incorporate device operations into scripts and automation workflows.

Requirements and Tested Platforms

The project was tested in the following environments, according to its documentation:

• Python 3.8.10 on Linux 5.4.0 x86_64
• Python 3.9.10 on Windows 10
• Python 3.10.5 on Android 12 using Termux and OTGSerial2WebSocket, without requiring root access

These are reported test environments, not a guarantee of compatibility with every operating system or Flipper Zero firmware version. Review the project’s documentation for current requirements.

How to Install pyFlipper

Clone the repository, create a Python virtual environment, activate it, and install the required dependencies.

git clone https://github.com/wh00hw/pyFlipper.git
cd pyFlipper
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

The activation command above is intended for Linux and macOS shells. On Windows, activate the environment with the appropriate command for your terminal, such as:

venv\Scripts\activate

Official project repository: pyFlipper on GitHub.

Connecting to a Flipper Zero

Import the PyFlipper class and create a connection using either a local serial port or a remote WebSocket endpoint.

Local Serial Connection

from pyflipper import PyFlipper

flipper = PyFlipper(com="/dev/ttyACM0")

Replace /dev/ttyACM0 with the serial port assigned to your device.

Remote WebSocket Connection

from pyflipper import PyFlipper

flipper = PyFlipper(ws="ws://192.168.1.5:1337")

Replace the example address and port with the values used by your serial-to-WebSocket server. Restrict access to trusted devices and avoid exposing an unauthenticated endpoint to untrusted networks.

Power Management

pyFlipper provides methods for retrieving power information and performing supported device power operations.

# Get power information
info = flipper.power.info()

# Shut down the device
flipper.power.off()

# Reboot the device
flipper.power.reboot()

# Reboot into DFU mode
flipper.power.reboot2dfu()

Shutdown, reboot, and DFU operations interrupt active device sessions. Use them only when appropriate for your workflow.

Firmware Updates and Backups

The wrapper includes methods for installing an update file, creating a backup archive, and restoring a backup.

# Install an update file
flipper.update.install(fuf_file="/ext/update.fuf")

# Back up the device
flipper.update.backup(dest_tar_file="/ext/backup.tar")

# Restore a backup
flipper.update.restore(bak_tar_file="/ext/backup.tar")

Confirm the expected file format and paths in the installed version’s documentation. Back up important data before updating or restoring the device, and use firmware files from trusted sources.

Storage and File Management

pyFlipper exposes methods for inspecting the device’s storage filesystem, exploring directories, and managing files under paths such as /ext.

Filesystem and Directory Operations

# Get filesystem information
ext_info = flipper.storage.info(fs="/ext")

# List directory contents
ext_list = flipper.storage.list(path="/ext")

# Retrieve a directory tree
ext_tree = flipper.storage.tree(path="/ext")

# Get file information
file_info = flipper.storage.stat(file="/ext/foo/bar.txt")

# Create a directory
flipper.storage.mkdir(new_dir="/ext/foo")

Read, Copy, Rename, and Remove Files

# Read a file
plain_text = flipper.storage.read(file="/ext/foo/bar.txt")

# Remove a file
flipper.storage.remove(file="/ext/foo/bar.txt")

# Copy a file
flipper.storage.copy(
    src="/ext/foo/source.txt",
    dest="/ext/bar/destination.txt"
)

# Rename a file
flipper.storage.rename(
    file="/ext/foo/bar.txt",
    new_file="/ext/foo/rab.txt"
)

# Calculate the file's MD5 hash
md5_hash = flipper.storage.md5(file="/ext/foo/bar.txt")

Check the target paths before removing, copying, or renaming files. The MD5 operation provides a checksum for basic file comparison; MD5 is not suitable for modern security-sensitive integrity or authenticity verification.

Writing Files

The project documents a direct write method for sending text to a file in one operation. The exact method signature should be verified against the installed version.

file_path = "/ext/bar.txt"
text = """Example text stored on the Flipper Zero.
This file can contain multiple lines.
"""

flipper.storage.write(file_path, text)

For larger or streamed content, the project also describes a listener-based workflow using start(), send(), and stop().

import time

file_path = "/ext/foo.txt"

flipper.storage.write.start(file_path)

try:
    flipper.storage.write.send("First block of text.\n")
    time.sleep(2)
    flipper.storage.write.send("Second block of text.\n")
finally:
    flipper.storage.write.stop()

Confirm the correct argument format for these write methods in the repository before using the examples. The original documentation’s write examples may depend on the project’s specific API version.

Practical Uses and Safety Considerations

pyFlipper can help developers automate repetitive device tasks, organize storage operations, and build Python-based workflows around Flipper Zero. It may also be useful when testing integrations in a controlled hardware lab.

Use the wrapper only with devices you own or are authorized to manage. Protect remote WebSocket connections, verify update files, and keep backups before modifying device storage or firmware.

For additional security tools and practical research resources, explore the forensic toolkit collection on Kali Linux Tutorials.