TumoCompanion

A native iOS companion for Flipper Zero — BLE/USB SD file access, screen mirror, Sub-GHz/NFC, a Sber smart-relay failsafe, Marauder log analysis, ESP32 firmware flashing, and live Claude Code status on your Flipper.

---

Contents

• Install
• Screenshots
• Features
• Field Services
• App Bridge (FAB1 / FAB2)
• Firmware packages (atomic updater)
• How the relay state works
• Privacy
• Build from source
• Requirements

Install (Feather / AltStore)

Add the source, then install — Feather signs it with your own certificate and auto-updates on each release:

https://raw.githubusercontent.com/squazaryu/TumoCompanion/main/apps.json

Unsigned IPA, sideloaded. Built for the independent Tumoflip firmware — its App Bridge BLE service is what most integrations use. Works as a plain BLE file/screen client on stock firmware too.

Screenshots

_{Onboarding · Home dashboard · Relay control · Settings (themes + app-icon styles). Home/Relay are shown without a Flipper paired — the live-data screens (device info, files, screen mirror, WiFi/Marauder, AI Radar, Claude Buddy) look best on a connected device.}

Features

📱 Device & files

• Connect over Bluetooth LE for live control, App Bridge, screen mirror and RPC actions.
• Browse the SD card over BLE or USB SD Mode, create folders, upload files and whole folders, multi-select and move items in bulk; one-tap macOS-junk cleanup (._*, .DS_Store).
• USB SD Mode uses iOS file-provider access: select the Flipper SD card folder in Files once, then the app will try to restore that USB channel on later launches.
• Screen mirror with live remote control (D-pad / OK / Back).
• Full Device Info (hardware, firmware, radio stack, battery) at a glance.

📡 Sub-GHz · NFC · RFID

• Transmit saved Sub-GHz signals and emulate NFC / RFID via the companion .fap.
• Remotes list for your everyday captures.

📶 WiFi / Marauder analysis

• Auto-aggregates every Marauder scan, sniff and Evil Portal log on the SD into one Overview — networks → clients → vendors (OUI-resolved), with channel-distribution and top-vendor charts.
• Opens tumoflip WiFi Mapper GeoJSON exports from /ext/apps_data/wifi_mapper/exports on an interactive map, with clean/raw support, RSSI filtering, observed points, and estimated AP locations from repeated RSSI observations.
• Surfaces Evil Portal captured credentials.
• Compact filter (Useful / Captures / Scans / Portal / All) with the statistics pinned at the top; the (often hundreds-strong) file list is collapsed below — tap any single capture to inspect it on its own.
• Parses classic .pcap (802.11 / radiotap) and Marauder text logs; finds them in the real pcaps/ · logs/ · dumps/ subfolders automatically.

Field Services

• TumoSurvey asks the iPhone for one GPS fix when a survey starts; firmware uses it only for Wi-Fi rows that do not already contain Module One coordinates.
• Flipper Companion exposes named Weather, Place and latest stable-release lookups without accepting arbitrary service URLs from Flipper.
• Existing .sub, .nfc and .rfid captures can receive a separate transactional .tumoflip.json location sidecar; the source file is never modified.
• Optional one-record last-known BLE location and a 200-entry field journal are visible and clearable on iPhone. All related switches are off by default.
• Optional journal delivery uses an iPhone-configured HTTPS webhook. Its bearer token stays in Keychain and is never sent to Flipper.

🔌 ESP32 Marauder firmware

• Checks ESP32Marauder releases, detects your board from the esp_flasher layout, downloads the matching image and stages a flash folder over BLE or USB SD — with size guard + MD5 verify.
• Archives outdated staged flash folders into /ext/apps_data/esp_flasher/_archive so old Marauder builds do not clutter the normal flashing list; archived folders can be restored or deleted from the ESP32 screen.
• Shows a per-board-key firmware version manager, so C5/WROOM modules keep separate versioned folders and an older build can be restored before flashing from the Flipper.

🛰️ Sber relay failsafe

• Toggle a Sber smart relay straight from the Flipper via App Bridge events.
• Auto route: local Home Assistant webhook first, automatic failover to the Sber cloud — so the Mac/HA isn't required.
• In-app Sber login (OAuth Authorization Code + PKCE) — tokens live in the iOS Keychain, never in the build.
• Siri App Intents: "toggle the relay."

🤖 Claude Buddy

• Live Claude Code status on the Flipper screen — thinking / running tool / turn complete — plus a session token counter, streamed over BLE serial through a small Mac relay daemon.
• Mic button toggles Claude Code's in-app dictation (⌘D), layout-independent.

🔔 Quality of life

• all-the-plugins auto-updater and ~daily background notifications for new plugin packs and ESP32 firmware (local only, no account).
• Live Activity for installs (plugin packs and firmware packages) — live per-file progress on the lock screen and Dynamic Island, with a screen-awake guard so a long BLE install isn't interrupted.
• Live Activity — accurate install progress on the Lock Screen and Dynamic Island for firmware packages, firmware staging, and plugin installs.
• Card-based UI; 4 app-icon styles — Light, Dark, Liquid Glass, Liquid Glass · Dark — plus an Auto icon that follows the system appearance; light/dark themes.

App Bridge (FAB1 / FAB2)

Most integrations talk to a small BLE service in the tumoflip firmware. The app negotiates the wire version automatically and shows it in Settings (v2 (FAB2) / v1 (FAB1)):

• FAB2 — correlated request/response. Each request carries a monotonic, nonzero id; replies are matched back to it; ordered chunks are reassembled (≤ 512 B); frames are strictly validated (lengths, flags, reserved byte, UTF-8, exact size); firmware errors surface as typed errors; pending requests are cleaned up on timeout or disconnect. v2 is enabled only on a valid runtime/capabilities response, and unknown capability keys are preserved.
• FAB1 — legacy single-frame fallback used for unsolicited events (the Relay and AI Radar event path), so stock / older firmware keeps working.

Firmware packages (atomic updater)

Updates → Firmware packages installs the Base / ARF / Module One / Protocol Pack files from the latest tumoflip release onto the Flipper SD over BLE or USB SD Mode as one crash-consistent transaction:

• the release manifest (schema v2) is validated and every target path is sanitised;
• each file is staged, SHA-256-checked on download and MD5-verified on the device before any live path is touched;
• activation is write-ahead journalled into dual, checksummed state slots — the Flipper's storage rename is copy + remove (not atomic), so an interrupted install is recovered or fully rolled back;
• Install and Clean Up are separate reversible transactions: installing never deletes legacy paths implicitly, while cleanup verifies the canonical replacement's on-device MD5 before removing an obsolete duplicate;
• the connected firmware's target / API / version must match the manifest before any FAP/FAL is written.

Needs a firmware release that publishes tumoflip-packages.zip; until then the screen shows “no install archive yet”. Firmware (DFU) flashing is a separate, explicit step and is not done here.

How the relay state works

The Sber relay doesn't report a reliable steady state back to Home Assistant (the sberdevices entity reverts to off seconds after an on command; the template-switch mirror sticks). So the on/off pill follows your last command — from the app or the Flipper — and is persisted across launches. The optional "Test read state" in Relay Settings is a comparison-only diagnostic.

Privacy

• No telemetry, no analytics, no account.
• Sber / Home Assistant tokens are stored in the iOS Keychain and entered by you — nothing personal is baked into the build.
• Field Services are opt-in. Weather and place lookup share the requested coordinates only with their named public provider; last-known storage, journal storage and webhook delivery have separate switches and clear controls.
• Update notifications are local (BGAppRefreshTask + local notifications); they only fetch public GitHub release tags.
• Bundles the public Russian Trusted Root CA so Sber's TLS validates — no private keys involved.

Build from source

The repository contains the complete SwiftUI application, Live Activity extension, tests, Feather source metadata and release scripts. The internal Xcode target remains unchanged internally to preserve the existing iOS update identity.

Prerequisites: Xcode 16+, XcodeGen and Swift Protobuf.

brew install xcodegen swift-protobuf protobuf
./scripts/build_ipa.sh

The unsigned IPA is written to build/TumoCompanion-unsigned.ipa. Sign it with your own certificate using Feather, SideStore, AltStore or Sideloadly.

Requirements

• iPhone on iOS 17+, a Flipper Zero, and (for most integrations) the independent Tumoflip firmware with App Bridge.
• Optional: a Mac running the AI Radar / Claude Buddy relay daemon for the Claude Code features and the HA relay bridge.

Releases

See Releases for the changelog and IPAs. apps.json is the Feather source manifest.

_{Built for personal use with the Flipper Zero community. Not affiliated with Flipper Devices, Sber, or Anthropic.}