From 17653ee6d7fceb570cd85688ecdd8f6034375445 Mon Sep 17 00:00:00 2001 From: andy Date: Fri, 11 Sep 2026 14:56:40 +0100 Subject: [PATCH] Rewrite README around the full-stack BLE firmware, detail every app Recentre the README on Flipper Blue++ as a custom full-stack Bluetooth firmware plus its app suite, rather than a single BT Inspector app that grew extra sections. New structure: intro, build/install (with the env-var table), a detailed per-app section for all ten apps (what each does, controls, logs), then the firmware internals (full stack, exported API + flash table, extra exports, sub-GHz unlock), how the BLE apps work, limitations, troubleshooting and repo layout. --- README.md | 737 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 380 insertions(+), 357 deletions(-) diff --git a/README.md b/README.md index b5d69a0..54e3f93 100644 --- a/README.md +++ b/README.md @@ -1,92 +1,40 @@ -# Flipper Zero BLE tools +# Flipper Blue++ -A suite of BLE, sub-GHz and power tools for the Flipper Zero. The BLE apps -share one central/GATT layer (`libble/`). +A custom Flipper Zero firmware build that turns the Bluetooth radio from an +advertise-only peripheral into a full Bluetooth Low Energy platform, plus a +suite of apps that use it. -**Bluetooth (need the `build.sh` firmware)** +Stock Flipper firmware runs ST's "BLE Light" coprocessor stack, which can only +advertise. Flipper Blue++ swaps in ST's **full** BLE stack (observer + central + +GATT client), **exports the ST BLE command API to apps** so ordinary `.fap` +files can scan, connect and run GATT, and throws in a few related unlocks +(selected firmware internals, and the sub-GHz region gate). On top of that +firmware it ships ten apps: a BLE scanner/explorer, a HID host, a sensor +dashboard, a tracker detector, a GATT fuzzer, a beacon broadcaster, a GATT +server, two sub-GHz tools and a battery monitor. -* **BT Inspector** — BLE scanner and GATT explorer, in the spirit of - BTInspector for iOS: discover devices, decode everything they broadcast, then - connect and inspect/read/write/subscribe, and log it all. -* **BLE HID Host** — connect a Bluetooth keyboard or mouse and watch its input - reports decoded live. -* **BLE Sensor Dashboard** — connect a sensor and watch its known-service - readings (battery, heart rate, temperature, humidity, pressure, ...) decoded - and updating live. -* **BLE Tracker Detector** — passively flag nearby item trackers (Apple Find - My / AirTag, Tile, Samsung SmartTag) with a "following you" warning. -* **BLE GATT Fuzzer** — enumerate a peripheral's whole GATT database, read every - readable value, and fuzz writable characteristics with boundary payloads, - logging every response. For authorised testing of devices you own. -* **BLE Beacon Toolkit** — broadcast an iBeacon or a raw advertising payload - with a chosen random MAC. -* **BLE GATT Server** — advertise the Flipper as a connectable serial GATT - peripheral and echo whatever a central writes. +Repo: `github.com/andydixon/flipper-bluepp` (the slug drops the `++` because +GitHub repo names cannot contain `+`). -**Sub-GHz (need the region unlock, on by default)** +> **Read this first.** These apps do **not** run on stock Flipper firmware. They +> need the firmware `build.sh` produces (full BLE stack + exported command API, +> and for the sub-GHz tools the region unlock). Battery Health is the only app +> that would also run on stock firmware. Flashing this firmware also installs a +> different radio stack; going back to official firmware restores the stock one. -* **Sub-GHz Scanner** — sweep RSSI across the full CC1101 range and log active - frequencies. -* **Sub-GHz Spectrum** — live spectrum bar graph and waterfall over a tunable - centre/span window. +--- -**Tools** +## Contents -* **Battery Health** — live fuel-gauge readings (voltage, current, temperature, - capacity, health, wear) with a voltage graph. Read-only. +- [Building and installing](#building-and-installing) +- [The apps](#the-apps) — detailed per-app docs +- [The firmware](#the-firmware) — full stack, exported APIs, sub-GHz unlock +- [How the BLE apps work](#how-the-ble-apps-work) +- [Limitations](#limitations) +- [Troubleshooting](#troubleshooting) +- [Repository layout](#repository-layout) -> **Read this first.** These apps do not run on stock Flipper firmware. The -> Flipper's radio coprocessor ships with ST's "BLE Light" stack (advertise-only: -> it cannot scan or connect), and the sub-GHz region check blocks transmit -> off-region. They are delivered as a **custom firmware build** that swaps in -> ST's full BLE stack, exports the BLE command API to apps, and unlocks the -> sub-GHz region; the apps themselves are ordinary `.fap` files. `build.sh` does -> all of this. See [Why a custom firmware build](#why-a-custom-firmware-build). -> Battery Health is the only one that would also run on stock firmware. - -## Features - -* **Live scan list.** Every BLE advertiser in range, sorted by RSSI, refreshed - every 300 ms as you move around. Shows name (or "(no name)"), RSSI in dBm - with signal bars, address and vendor. Devices unseen for 60 s drop off. -* **Device page.** Address and address type, current/best RSSI and packet - count, advertising type (connectable or not), flags, advertised service UUIDs - (16/32/128-bit, named when known), service data, Tx power, appearance, - manufacturer data and raw advertisement / scan-response bytes. Updates live. -* **Identification.** Manufacturer IDs map to vendor names. Decoders for: - * Apple Continuity: iBeacon (UUID/major/minor/Tx), Proximity Pairing with - AirPods/Beats **model name** and **left / right / case battery** and - charging state, Nearby Info (device activity), Nearby Action, Find My, - AirDrop, Handoff, AirPlay, tethering. - * Microsoft Connected Devices beacon: device type (Windows desktop/laptop, - Xbox, Surface Hub, Android, iPhone, ...). - * Google Fast Pair model ID, Eddystone UID/URL/TLM (URL decoded), COVID - Exposure Notification. -* **Connect and interrogate.** OK on a connectable device connects (MTU is - negotiated), discovers all primary services, then characteristics with their - properties (`R`ead, `W`rite, `w`rite-without-response, `N`otify, `I`ndicate, - `B`roadcast). -* **Read device info** (first item in the service list): reads every readable - characteristic of the Generic Access, Device Information and Battery services - in one go: device name, appearance, model number, serial number, firmware / - hardware / software revision, manufacturer name, PnP ID, battery level. -* **Characteristic page.** Read any characteristic, including custom 128-bit - ones. Values are shown as hex plus decoded forms: printable string, u8/i8, - u16, u32, and SIG-specific formats (battery %, appearance, preferred - connection parameters, PnP ID, heart rate, temperature, humidity, pressure, - Tx power, date/time). Long values are fetched with read-long. -* **Write** a value back as text, hex bytes or a number (little-endian, sized to - the current value or the magnitude). Uses write-with-response when the - characteristic supports it, otherwise write-without-response. A readable - characteristic is re-read after a write. -* **Subscribe** to notifications / indications (the CCCD is located - automatically). Incoming values update the page and the history. -* **Value history.** Each value seen for the open characteristic (reads and - notifications) is kept with a timestamp, newest first. -* **Session log.** Every event is written with a date/time stamp to - `SD:/apps_data/bt_inspector/bti_YYYYMMDD_HHMMSS.log`: devices found (and - renamed), connects, services, characteristics, reads, writes, notifications, - errors. Copy it off the SD card (or via qFlipper) for analysis. +--- ## Building and installing @@ -94,29 +42,32 @@ Requirements: Linux or macOS with `git`, `python3` and a few GB of disk. The firmware build system downloads its own ARM toolchain. ```sh -./build.sh # clone firmware 1.4.3, export the BLE API, build firmware + .fap +./build.sh # clone firmware 1.4.3, apply the patches, build firmware + apps ./build.sh flash # same, then flash over USB (Flipper connected, qFlipper closed) -./build.sh fap # rebuild only the .fap after editing the app +./build.sh fap # rebuild only the apps (firmware already built once) ``` -Options via environment variables: `FW_TAG` (firmware tag, default `1.4.3`), -`FW_DIR` (where to clone), `JOBS` (parallel compile jobs, default 4), -`BLE_API` (which ST API to export, see below). +Environment variables: + +| Var | Default | Effect | +|---|---|---| +| `BLE_API` | `hci,gatt` | Which ST command groups to export (`min`, `all`, or any comma list of `hci,gap,gatt,hal,l2cap`). | +| `EXPORT_FLASH` | `1` | Export the raw flash / option-byte API (set `0` to omit). | +| `SUBGHZ_UNLOCK` | `1` | Remove the sub-GHz region gate (set `0` to keep it). | +| `FW_TAG` | `1.4.3` | Firmware tag to clone. | +| `FW_DIR` | `./flipperzero-firmware` | Where to clone. | +| `JOBS` | `4` | Parallel compile jobs. | The result is a standard update package in -`flipperzero-firmware/dist/f7-C/f7-update-local/`. It contains the firmware, -the **full radio stack**, and the app as `apps/Bluetooth/bt_inspector.fap` in -its resources. To install without USB flashing, copy that folder to the SD card -(for example `SD:/update/`) and open it in the Flipper's file browser. -Installing an official firmware later restores the light stack the same way. +`flipperzero-firmware/dist/f7-C/f7-update-local/`, containing the firmware, the +**full radio stack**, and every app under `apps/` in its resources. To install +without USB flashing, copy that folder to the SD card (e.g. `SD:/update/`) and +open it in the Flipper's file browser. The individual `.fap` files are in +`flipperzero-firmware/build/f7-firmware-C/.extapps/`; once the firmware is +installed, app updates are just a file copy to the SD card. -The `.fap` alone is at `flipperzero-firmware/build/f7-firmware-C/.extapps/`; -after the firmware is installed once, app updates are just a file copy to -`SD:/apps/Bluetooth/`. It only loads on this firmware (API version 87.2 with -the exported symbols); the stock loader rejects it with an API mismatch. - -To build the app with `ufbt` instead of the firmware tree, point `ufbt` at the -SDK the build produces: +To iterate on an app with `ufbt` instead of the whole firmware tree, point it at +the SDK the build emits: ```sh ufbt update --local=flipperzero-firmware/dist/f7-C/flipper-z-f7-sdk-local.zip @@ -125,307 +76,379 @@ cd bt_inspector && ufbt # -> dist/bt_inspector.fap ; `ufbt launch` instal The first build takes 5-15 minutes; later builds are incremental. -## Using the app +While any BLE app runs, the Flipper's own advertising is stopped (and any phone +link dropped), then restored on exit. Only one app owns the radio at a time. -BT Inspector appears in the Flipper's main menu. While it runs, the Flipper's -own BLE advertising is stopped (and any phone connection dropped); it is -restored on exit. +--- -| Screen | Up / Down | OK | Left | Right | Back | +## The apps + +All ten install to the Flipper's app menu. The BLE apps share one +central/GATT-client layer (`libble/`) and follow the same pattern: a live scan +list you pick a device from, then a per-app action. On the scan list, **Up/Down** +move the selection, **OK** acts on the highlighted device, **Back** exits. + +### BT Inspector + +A full BLE scanner and GATT explorer, in the spirit of BTInspector for iOS. + +- **Scan list** — every advertiser in range, sorted by RSSI and refreshed every + 300 ms, showing name (or "(no name)"), RSSI in dBm with signal bars, address + and vendor. Devices unseen for 60 s drop off. +- **Device page** (OK on a device) — address and address type, current and best + RSSI, packet count, advertising type (and whether it is connectable), and a + decode of everything in the advertisement and scan response: + - flags; advertised service UUIDs (16/32/128-bit, named when known); service + data; Tx power; appearance; + - manufacturer data, with decoders for **Apple Continuity** (iBeacon + UUID/major/minor/Tx; Proximity Pairing with AirPods/Beats **model name** and + **left / right / case battery** and charging state; Nearby Info and Action; + Find My; AirDrop; Handoff; AirPlay; tethering), **Microsoft CDP** device + type, **Google Fast Pair**, **Eddystone** (UID/URL/TLM, URL expanded), and + **Exposure Notification**; + - the raw advertisement and scan-response bytes. +- **Connect** (OK on a connectable device) — negotiates MTU, discovers all + primary services, and lists them. The first entry, **Read device info**, reads + every readable characteristic of the Generic Access, Device Information and + Battery services at once (name, appearance, model/serial numbers, firmware / + hardware / software revisions, manufacturer, PnP ID, battery level). +- **Characteristics** — each service opens to its characteristics with property + flags: `R`ead, `W`rite, `w`rite-without-response, `N`otify, `I`ndicate, + `B`roadcast. +- **Characteristic page** — Read (OK), including custom 128-bit characteristics + and long values (read-long). Values show as hex plus decoded forms: printable + string, u8/i8, u16, u32, and SIG formats (battery %, appearance, preferred + connection parameters, PnP ID, heart rate, temperature, humidity, pressure, Tx + power, date/time). **Write** (Right) a value as text, hex bytes, or a number; + **Notify/Unsub** (Left) subscribes to notifications/indications, locating the + CCCD automatically. A timestamped **history** of every value seen for the open + characteristic is kept, newest first. +- **Log** — everything is written with timestamps to + `SD:/apps_data/bt_inspector/bti__