Flipper Zero
@magistr/flipper-zerov2026.10.25.10
01README
Control a Flipper Zero over its USB serial CLI from swamp.
Model:
@magistr/flipper-zero— one instance per Flipper (identified by its serial port, or auto-detected). Methods drive the device's text CLI (the>:prompt) and RPC protocol, persisting structured results as swamp data:detect— find the serial port without talking to the device.info— read device/firmware/power info (info device, with adevice_infofallback) parsed into attributes.exec— run any single CLI command and capture its output.storage-list— list an SD-card directory (storage list <path>).storage-read— read a file's contents (storage read <path>).apps— list the built-in loader apps (loader list).installed-apps— list SD-card apps/scripts under /ext/apps grouped by category, each with a launchable path (storage tree).launch— launch an app by path/name (loader open), refusing to open over a running app unless force is set.close— close the running app: softloader close, escalating to a simulated long Back press for apps (games) that ignore it.running— report the currently-running app (loader info).screenshot— capture the 128x64 screen over RPC (start_rpc_session + Gui screen stream) and render it as ASCII and braille.listen— receive-only capture on sub-GHz, infrared, 125kHz RFID or NFC (which runs through the device's[nfc]sub-shell).transmit— owner-operated emit on IR (protocol or universal remote), sub-GHz (replay a saved capture or a raw key), or RFID emulate. Sub-GHz TX is region-restricted by the firmware. RX and TX only; no jamming or brute-force tooling.reboot— reboot the device (power reboot).
Cross-platform serial handling: macOS cu.usbmodemflip* and Linux ttyACM*
nodes are auto-detected; the line is put into raw, no-echo mode via stty and
each exchange syncs to a fresh prompt before sending a single, newline-free
command. All device I/O goes through subprocesses (macOS requires --allow-all
for /dev, which swamp models are not granted). Captured output is bounded to
guard against huge reads.
02Release Notes
2026.10.25.10
- Repo-wide republish; no functional change.
03Behaviors
@magistr/flipper-zerov2026.10.25.10extensions/models/flipper_zero.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| port? | string | Serial device path, e.g. /dev/cu.usbmodemflip_Zilxi1 (macOS) or |
| baud? | string | Baud rate for stty. The Flipper is USB-CDC so this is cosmetic, but must |
| timeoutMs? | number | Per-command read timeout in milliseconds. |
fn detect()
Find the Flipper's serial port (no device communication). Writes the
fn info()
Read device, firmware and power information (info device, with a
fn exec(command: string)
Run a single Flipper CLI command (e.g. "storage info /ext",
| Argument | Type | Description |
|---|---|---|
| command | string | A single CLI command line. Run "help" to list commands. |
fn storage-list(path?: string)
List a directory on the SD card (storage list <path>).
| Argument | Type | Description |
|---|---|---|
| path? | string | Storage path to list (default /ext, the SD-card root). |
fn storage-read(path: string)
Read a file's contents from the SD card (storage read <path>).
| Argument | Type | Description |
|---|---|---|
| path | string | Storage path of the file to read, e.g. /ext/subghz/foo.sub. |
fn apps()
List the built-in loader applications (loader list). For apps you
fn installed-apps(path?: string, kind?: enum)
List every app/script installed on the SD card by walking an apps
| Argument | Type | Description |
|---|---|---|
| path? | string | SD-card apps directory to scan (default /ext/apps). |
| kind? | enum | Optional filter: only return apps of this kind. |
fn launch(app: string, force?: boolean)
Launch an app (loader open). Pass a full .fap path from installed-apps
| Argument | Type | Description |
|---|---|---|
| app | string | App path (e.g. /ext/apps/Games/snake_game.fap) or built-in name. |
| force? | boolean | Close any already-running app first (default false). |
fn close()
Close the currently-running app. Tries a soft loader close, then
fn running()
Report which app is currently running, if any (loader info).
fn screenshot()
Capture the 128x64 device screen over RPC and render it as ASCII and
fn show-image(ascii?: string, framebufferBase64?: string, seconds?: number, scale?: number, invert?: boolean)
Draw an image on the Flipper's screen via an RPC virtual display.
| Argument | Type | Description |
|---|---|---|
| ascii? | string | ASCII art to draw; blank chars are ' ', '.', '·', '_' and '0'. |
| framebufferBase64? | string | Raw 1024-byte 128x64 framebuffer, base64 (e.g. from screenshot). |
| seconds? | number | How long to hold the image on screen (default 5). |
| scale? | number | Pixels per ASCII character (default: auto-fit). |
| invert? | boolean | Invert the image. |
fn play-snake(seconds?: number, appPath?: string)
Play the bundled Snake game autonomously. Runs a survival bot that
| Argument | Type | Description |
|---|---|---|
| seconds? | number | How long to play, in seconds (default 60). |
| appPath? | string | Path to the Snake .fap on the device. |
fn listen(source?: enum, seconds?: number, frequency?: number, raw?: boolean, external?: boolean)
Listen on one of the device's receivers for a fixed window and capture
| Argument | Type | Description |
|---|---|---|
| source? | enum | Which receiver to listen on. |
| seconds? | number | How long to listen (default 15). |
| frequency? | number | Sub-GHz frequency in Hz (default 433920000 = 433.92MHz). |
| raw? | boolean | Capture raw timings instead of decoded packets (subghz/ir). |
| external? | boolean | Use an external CC1101 module (device 1) instead of the internal. |
fn transmit(source: enum, protocol?: string, address?: string, command?: string, universalRemote?: string, signal?: string, file?: string, key?: string, frequency?: number, te?: number, keyType?: string, keyData?: string, repeat?: number, seconds?: number, external?: boolean)
Emit on one of the device's radios (owner-operated): send an infrared
| Argument | Type | Description |
|---|---|---|
| source | enum | Which radio to emit on. |
| protocol? | string | IR protocol, e.g. NEC, Samsung32, RC5 (with address+command). |
| address? | string | IR address, hex. |
| command? | string | IR command, hex. |
| universalRemote? | string | Bundled universal remote: tv, audio, ac, or projector (with signal). |
| signal? | string | Universal-remote signal name, e.g. Power, Mute, Vol_up. |
| file? | string | Path to a saved capture to replay, e.g. /ext/subghz/gate.sub. |
| key? | string | Raw sub-GHz key, hex (with frequency+te). |
| frequency? | number | Sub-GHz frequency in Hz (for a raw key). |
| te? | number | Sub-GHz timing element in microseconds (for a raw key). |
| keyType? | string | RFID key type to emulate, e.g. EM4100, H10301, Indala26. |
| keyData? | string | RFID key data, hex. |
| repeat? | number | Repeat count for sub-GHz transmits (default 1). |
| seconds? | number | How long to emulate, for RFID (default 10). |
| external? | boolean | Use an external CC1101 module (sub-GHz). |
fn reboot()
Reboot the device (power reboot). The port drops during reboot, so no
Resources
device-port(infinite)— Resolved serial port and detection candidates
device-info(infinite)— Parsed device/firmware/power information
command-output(infinite)— Output of an arbitrary CLI command
storage-listing(infinite)— Directory listing from the SD card
file-content(infinite)— Contents of a file read from the SD card
app-list(infinite)— Installed applications from loader list
reboot-result(infinite)— Outcome of a reboot request
installed-apps(infinite)— Installed apps/scripts found on the SD card
launch-result(infinite)— Outcome of launching an app via loader open
close-result(infinite)— Outcome of closing the running app
loader-info(infinite)— Currently-running application, per loader info
image-shown(infinite)— An image pushed to the device's virtual display
snake-game(infinite)— Result of an autonomous Snake session
transmit-result(infinite)— Outcome of an emit/transmit on a radio
listen-result(infinite)— What a receiver picked up during a listen window
screenshot(infinite)— Rendered capture of the 128x64 device screen
04Previous Versions
2026.10.15.9MIT
2026.10.15.9
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.8MIT
2026.10.15.8
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.6MIT
2026.10.15.6
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.5MIT
2026.10.15.5
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.4MIT
2026.10.15.4
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.3MIT
2026.10.15.3
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.2MIT
2026.10.15.2
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.1MIT
2026.10.15.1
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.14.2MIT(was none)
2026.10.14.2
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
Modified 1 behaviors
2026.09.19.2
2026.09.19.2
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.09.17.1
2026.09.17.1
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.08.19.1
2026.07.24.1
Merge pull request #55 from umag/feat/flipper-zero-extension
feat(flipper-zero): owner-operated transmit (IR / sub-GHz / RFID)
Modified 1 behaviors
2026.07.23.6
Merge pull request #53 from umag/feat/flipper-zero-extension
feat(flipper-zero): receive-only listen (sub-GHz / IR / RFID / NFC)
Modified 1 behaviors
2026.07.23.4
Merge pull request #52 from umag/feat/flipper-zero-extension
feat(flipper-zero): new @magistr/flipper-zero extension
05Stats
A
100 / 100
Downloads
36
Archive size
46.3 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Docs keep secrets in a vault1/1earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned
Repository
https://github.com/umag/swamp-workspace06Platforms
07Labels