Flipper Zero Control Skill

intent

control a flipper zero hardware hacking tool via usb serial cli or bluetooth low energy (ble), with direct machine-to-flipper communication and full access to subghz, ir, nfc, rfid, badusb, gpio, file system, screen capture, and input control. use this skill when you need wireless or wired control of flipper hardware without android or intermediary apps. choose usb for subghz/ir operations and raw cli access; choose ble for wireless file management, gpio, app control, screen streaming, and input automation.

inputs

hardware:

• flipper zero device with usb-c cable and/or bluetooth enabled
• firmware: tested with momentum (mntm-008); should work with official and community firmwares
• optional: external cc1101 module (e.g., rabbit labs flux capacitor) for amplified subghz transmission

software environment:

• python 3.10 or higher
• python virtual environment (recommended: ~/flipper-env)
• python packages: pyserial, bleak, protobuf, grpcio-tools, pillow
• os: macos or linux (windows ble via bleak may need adjustments)

environment variables (optional):

• FLIPPER_PORT , usb serial port override (default: auto-detect /dev/cu.usbmodem*)
• FLIPPER_BAUD , serial baud rate (default: 230400)
• FLIPPER_BLE_ADDRESS , skip ble scan, connect directly to device address
• FLIPPER_BLE_NAME , ble device name to search for (default: auto-detect)

external connections:

• flipper zero usb serial service (via usb-c cable at 230400 baud)
• flipper zero ble serial service (uuid: 0000ffe1-0000-1000-8000-00805f9b34fb)
• optional protobuf definitions from github.com/flipperdevices/flipperzero-protobuf

setup:

python3 -m venv ~/flipper-env
~/flipper-env/bin/pip install pyserial bleak protobuf grpcio-tools pillow

procedure

transport selection

step 0: decide whether to use usb or ble based on your operation type.

• input: operation type (subghz tx, file read, gpio control, screen capture, app launch, input navigation)
• output: transport choice (usb or ble)
• guidance: usb for subghz/ir raw operations and high-speed cli access; ble for wireless, app control, screen streaming, input automation, and gpio full control

usb serial cli transport (flipper_cli.py)

step 1: verify flipper usb connection and auto-detect serial port.

• input: flipper zero connected via usb-c cable, powered on, cli accessible
• command: ~/flipper-env/bin/python3 scripts/flipper_cli.py detect
• output: "flipper found at /dev/cu.usbmodem..." or connection error
• edge case: if no port found, check ls /dev/cu.usbmodem* manually or reconnect usb cable

step 2: retrieve device info and storage status.

• input: usb connection confirmed from step 1
• command: ~/flipper-env/bin/python3 scripts/flipper_cli.py info
• output: device name, firmware version, storage capacity, free space
• edge case: if timeout, flipper may be in an app; press Back to return to cli

step 3: perform file operations (list, read, write, mkdir, remove).

• input: flipper path (e.g., /ext/subghz, /ext/file.sub), data to write (if write operation)
• command examples:
  • flipper_cli.py storage list /ext/subghz , list directory contents
  • flipper_cli.py storage read /ext/file.sub , read file as text
  • flipper_cli.py storage write /ext/path "data" , write text to file
  • flipper_cli.py storage mkdir /ext/new_dir , create directory
  • flipper_cli.py storage remove /ext/old_file , delete file (high risk, requires confirmation)
  • flipper_cli.py storage info /ext , get storage stats
• output: file contents (read), confirmation message (write/mkdir), storage stats, or error
• edge case: write operations may fail if partition is full; check storage info first

step 4: perform subghz operations (rx, tx, scan).

• input: frequency in hz (e.g., 433920000), device (0=internal, 1=external cc1101), duration in seconds, payload (for tx)
• command examples:
  • flipper_cli.py subghz rx 433920000 0 10 , listen on 433.92mhz with internal radio for 10 seconds
  • flipper_cli.py subghz rx 433920000 1 15 , listen with external cc1101 module for 15 seconds
  • flipper_cli.py subghz rx_raw 433920000 10 , raw capture (no protocol decoding)
  • flipper_cli.py subghz tx AABBCC 433920000 400 3 1 , transmit payload at frequency (high risk, requires confirmation)
  • flipper_cli.py subghz tx_from_file /ext/subghz/file.sub 1 0 , transmit saved .sub file (high risk, requires confirmation)
  • flipper_cli.py scan_subghz 433920000 30 1 , scan for 30 seconds with external module
• output: captured packets (rx/scan) or transmission confirmation (tx), or error
• edge case: no packets captured if nothing is transmitting nearby (normal behavior); try scanning during active transmission or near a remote control

step 5: perform ir operations (tx from file).

• input: ir file path (e.g., /ext/infrared/remote.ir)
• command: flipper_cli.py ir tx /ext/infrared/remote.ir
• output: transmission confirmation or error
• edge case: if file not found, check file path and ensure file exists

step 6: perform gpio operations (set, read).

• input: pin name (e.g., PA7, PB3), value (0 or 1 for set)
• command examples:
  • flipper_cli.py gpio set PA7 1 , set pin high
  • flipper_cli.py led b 255 , set blue led (channels: r, g, b, bl; value 0-255)
  • flipper_cli.py led off , turn all leds off
  • flipper_cli.py vibro 1 , vibration on
  • flipper_cli.py power 5v 1 , enable 5v gpio power (for external modules)
• output: confirmation or error
• edge case: 5v power must be enabled before using external cc1101 modules

step 7: send raw cli passthrough for unsupported commands.

• input: raw flipper cli command string
• command: flipper_cli.py raw "any flipper cli command"
• output: raw cli response
• note: use only when standard commands don't apply

ble protobuf rpc transport (flipper_ble.py)

step 8: scan for and discover flipper ble devices.

• input: flipper zero with ble enabled, usb cable unplugged, powered on
• command: ~/flipper-env/bin/python3 scripts/flipper_ble.py scan
• output: list of discovered ble devices with mac addresses and names
• edge case: if no devices found, press any button on flipper to wake it, ensure ble is on in settings

step 9: verify ble connection and protocol compatibility.

• input: flipper ble address (from scan or env var FLIPPER_BLE_ADDRESS)
• command: flipper_ble.py ping or flipper_ble.py info or flipper_ble.py protobuf_version
• output: "pong" (ping), device info, or protocol version
• edge case: ble drops after idle; this is normal and requires reconnection

step 10: retrieve device and power status.

• input: ble connection from step 9
• command: flipper_ble.py info or flipper_ble.py power_info
• output: device name, firmware, serial number, battery level, voltage
• note: battery level is critical for long operations

step 11: perform file operations over ble (list, read, write, mkdir, delete, rename, md5).

• input: flipper file path, local file path (for write)
• command examples:
  • flipper_ble.py storage list /ext/subghz , list directory
  • flipper_ble.py storage read /ext/file.txt , read file from flipper
  • flipper_ble.py storage write /ext/path local.txt , upload local file to flipper
  • flipper_ble.py storage mkdir /ext/new_dir , create directory
  • flipper_ble.py storage delete /ext/file , delete file (high risk, requires confirmation)
  • flipper_ble.py storage md5 /ext/file , get file checksum
  • flipper_ble.py storage rename /ext/old /ext/new , rename or move file
  • flipper_ble.py storage info /ext , storage stats
• output: file contents (read), confirmation (write/mkdir), checksum (md5), or error
• edge case: large file transfers may timeout; retry or split into smaller uploads

step 12: perform gpio operations over ble (read, write, mode, otg).

• input: pin name (e.g., PA7), mode (input/output), value (0 or 1), or otg state (on/off)
• command examples:
  • flipper_ble.py gpio read PA7 , read pin state
  • flipper_ble.py gpio write PA7 1 , write pin high
  • flipper_ble.py gpio mode PA7 output , set pin as output
  • flipper_ble.py gpio otg on , enable 5v otg power for external modules
• output: pin state (read), confirmation (write/mode/otg), or error
• edge case: otg power enables 5v on gpio; ensure external modules support this voltage

step 13: launch and control flipper apps.

• input: app name (e.g., "SubGHz"), actions (optional)
• command examples:
  • flipper_ble.py app start SubGHz , launch app
  • flipper_ble.py app exit , exit current app
• output: confirmation or error
• note: only available over ble; not available via usb cli

step 14: send device alerts (led, vibro, sound).

• input: alert trigger
• command: flipper_ble.py alert
• output: led flash, vibration, and sound on device
• use case: confirm receipt of command or get user attention

step 15: system operations (reboot, datetime).

• input: (optional) new datetime for set operation
• command examples:
  • flipper_ble.py datetime , get current date/time
  • flipper_ble.py reboot , reboot flipper (high risk, requires confirmation)
• output: datetime string or reboot confirmation
• edge case: reboot will drop ble connection; reconnect after 30 seconds

screen capture and input automation (flipper_screen.py)

step 16: capture flipper screen as png or ascii art.

• input: output file path (optional, defaults to flipper_screen.png)
• command examples:
  • flipper_screen.py screenshot [output.png] , capture as 4x scaled png (flipper orange on black)
  • flipper_screen.py ascii , capture as unicode half-block ascii art
• output: png file or text art to stdout
• edge case: static screens won't produce new frames; only changes trigger captures

step 17: send input commands (button presses and sequences).

• input: button name (up, down, left, right, ok, back), press type (short or long)
• command examples:
  • flipper_screen.py press ok , press ok button (short press)
  • flipper_screen.py press back long , long press back button
  • flipper_screen.py navigate ok down down ok , sequence of button presses
• output: confirmation or error
• note: use for menu navigation and app control

step 18: launch app, perform actions, and capture results.

• input: app name, action sequence (combinations of button presses, waits, screenshots)
• command: flipper_screen.py app_control SubGHz wait:1 screenshot
• output: executed actions and final screenshot
• example: launch subghz app, wait 1 second for ui to render, capture screen

step 19: stream screen frames for real-time monitoring.

• input: duration in seconds, output directory (optional)
• command: flipper_screen.py watch 10 [output_dir]
• output: 10 seconds of consecutive png frames saved to directory
• edge case: high cpu usage; use sparingly and close other apps on flipper

subghz operations over ble (flipper_subghz_ble.py)

step 20: perform subghz operations wirelessly via app navigation and screen reads.

• input: operation type (read, read_raw, frequency_analyzer, saved, transmit, status), duration (optional), filename (for transmit)
• command examples:
  • flipper_subghz_ble.py read [duration_sec] , open subghz app in read/decoder mode, capture for N seconds
  • flipper_subghz_ble.py read_raw [duration_sec] , open subghz in raw mode
  • flipper_subghz_ble.py frequency_analyzer [dur] , frequency analyzer mode
  • flipper_subghz_ble.py saved , browse saved signals menu
  • flipper_subghz_ble.py transmit <filename> , open saved file for transmission (high risk, requires confirmation)
  • flipper_subghz_ble.py status , screenshot current screen
• output: png/ascii screenshots of screen state (results are visual, not parsed)
• limitation: results are visual screenshots rather than structured data; use usb transport for parsed subghz data

decision points

if operation is subghz or ir transmission (high risk):

• do: require explicit user confirmation before executing
• reason: transmitting on regulated frequencies without authorization is illegal in most jurisdictions

if operation is delete, reboot, or power off (high risk):

• do: require explicit user confirmation before executing
• reason: data loss or system unavailability risk

if operation is medium risk (write, mkdir, gpio set, ir tx, nfc emulate):

• do: log the action and notify user; execute if user acknowledges
• reason: potential device state change or unintended behavior

if operation is read-only (info, list, read, scan, datetime, power_info):

• do: execute freely without confirmation
• reason: no device state change

if transport not specified by user:

• do: recommend usb for subghz/ir, ble for wireless/app/screen operations
• reason: transport has capability differences (see transport comparison table below)

if usb port not found:

• do: check ls /dev/cu.usbmodem* manually; advise user to reconnect usb cable or check permissions
• reason: auto-detection may fail on some systems or after reconnection

if ble device not found:

• do: advise user to wake flipper (press any button), verify ble is on in settings, retry scan
• reason: ble sleep mode prevents discovery; manual wake required

if ble connection drops after use:

• do: reconnect; this is normal behavior
• reason: flipper sleeps after idle to save battery

if subghz rx captures no packets:

• do: continue listening; normal if nothing is transmitting nearby
• reason: confirm with user that they should trigger nearby remote or other transmitter during capture window

if external cc1101 module used:

• do: ensure 5v gpio power is enabled before transmission
• do: require antenna connection before any transmission
• reason: transmitting without antenna damages module; power must be enabled for module operation

if ble file transfer times out:

• do: retry or split transfer into smaller chunks
• reason: large transfers may exceed ble timeout window

if flipper is in an app (usb cli timeout):

• do: advise user to press Back to return to cli
• reason: cli is only accessible at main menu

output contract

usb serial operations:

• read operations return file contents as text or raw data
• write operations return confirmation message or error
• info operations return key-value pairs (device name, firmware, storage)
• subghz rx returns captured packet data or error
• subghz tx returns transmission confirmation or error
• gpio operations return current state or confirmation
• all responses include status code (0 for success, non-zero for error)

ble protobuf operations:

• file read returns file contents as bytes or text
• file write returns confirmation or error
• info operations return structured device metadata (protobuf message)
• storage operations return confirmation or file stats
• gpio operations return pin state or confirmation
• app control returns confirmation; results captured via screenshots
• screen capture returns png file at specified path or ascii text to stdout
• all responses include status code (0 for success, non-zero for error)

screen capture:

• png output: 512x256 pixels (4x scaled from 128x64 display), flipper orange (#ff8800) on black background
• ascii output: unicode half-block art (160x64 chars) suitable for terminal display
• watch mode: numbered png sequence (frame_0.png, frame_1.png, ...)

file locations:

• usb/ble uploads to flipper: /ext/ (external storage), /int/ (internal storage, limited)
• local output files: current working directory or specified path
• protobuf definitions: scripts/proto/ (auto-generated from flipper zero protobuf repo)

error handling:

• all commands return non-zero exit code on error
• error messages include reason (timeout, connection lost, invalid argument, permission denied, etc.)
• subghz commands may return "no packets received" (normal if no transmitters active)

outcome signal

success indicators:

• device info command returns firmware version and storage stats
• detect command confirms usb or ble connection established
• file read command returns file contents without errors
• file write command returns confirmation message
• screen capture command produces png file or ascii output
• subghz rx command returns captured packet data or "no packets" message (both valid)
• subghz tx command shows transmission confirmation (only after user confirms high risk)
• gpio operation shows pin state or confirmation
• app launch shows app running on device screen (via screenshot)
• input navigation shows menu changes on screen (via screenshot)
• alert command triggers led/vibro/sound on physical device
• ble connection persists across multiple commands (until idle timeout)

failure indicators:

• commands timeout (>10 seconds for usb, >30 seconds for ble)
• connection errors ("device not found", "permission denied", "connection refused")
• invalid arguments (wrong pin name, malformed frequency, missing file path)
• device response errors ("storage full", "invalid operation", "app not found")
• empty result sets (file read returns 0 bytes, subghz scan returns no packets after legitimate wait)
• ble connection drops unexpectedly (not idle timeout)
• screen capture produces empty or corrupted png

user experience:

• user receives confirmation before high-risk operations (delete, transmit, reboot)
• user sees captured screen images or terminal output within seconds of request
• user knows connection status (connected, disconnected, idle sleep)
• user knows operation risk level (low, medium, high) before execution
• user can interrupt long operations (watch, rx_raw) via ctrl-c

---