From 87c8251c172ffad9fe1611d865332189c7a7eae3 Mon Sep 17 00:00:00 2001 From: Jon Date: Sat, 2 May 2026 22:37:20 +0100 Subject: [PATCH] Updated README --- README.md | 52 +++++++++++++++--- .../75c3eb86-5541-4c01-93ed-b0988b43bef0.png | Bin 0 -> 4474 bytes .../f311fb4e-8450-4b78-95a0-c938be21250f.png | Bin 0 -> 4960 bytes 3 files changed, 44 insertions(+), 8 deletions(-) create mode 100644 screenshots/75c3eb86-5541-4c01-93ed-b0988b43bef0.png create mode 100644 screenshots/f311fb4e-8450-4b78-95a0-c938be21250f.png diff --git a/README.md b/README.md index f7c6296..4a7b406 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -![bthome app](screenshots/bthome_app.png) +![BT Home Controller in Bluetooth menu](screenshots/75c3eb86-5541-4c01-93ed-b0988b43bef0.png) +![BT Home Controller app UI](screenshots/f311fb4e-8450-4b78-95a0-c938be21250f.png) This application turns the Flipper Zero into a [BTHome](https://bthome.io) beacon, and can be used to integrate the Flipper with home automation systems @@ -9,19 +10,54 @@ over Bluetooth Low Energy (BLE). It allows devices to transmit sensor readings (temperature, humidity, battery level, button events, etc.) without requiring pairing or an active connection. -The BTHome beacon is triggered when pressing the Flipper Zero "OK" button -and currently includes the Flipper's battery percentage as a sensor. +Pressing any direction on the Flipper Zero D-pad (Up, Down, Left, Right, OK) +sends a BTHome button event. Each direction maps to a separate BTHome button +object, so Home Assistant sees them as `button`, `button_2`, `button_3`, +`button_4`, and `button_5` (OK, Up, Down, Left, Right respectively). Short and +long presses are both supported. The Flipper's battery percentage is also +included in each beacon. -Unfortunately, due to the limited size of BLE packets the Flipper Zero can send -there isn't much room left to add more sensors without removing the existing -one. +### Building + +Install [ufbt](https://github.com/flipperdevices/ufbt) into a virtual +environment: + +```bash +python3 -m venv .venv +.venv/bin/pip install ufbt +``` + +Then build from the project root: + +```bash +.venv/bin/ufbt +``` + +The first run downloads the Flipper SDK and compiler toolchain automatically. +The finished app is written to: + +``` +dist/bt_home_controller.fap +``` + +### Installing on the Flipper + +Open [qFlipper](https://flipperzero.one/update), connect your Flipper via USB, +and use the file manager to copy `dist/bt_home_controller.fap` to: + +``` +SD:/apps/Bluetooth/ +``` + +The app will then appear in **Apps → Bluetooth → BT Home Controller** on the +Flipper. ### Home Assistant setup The first step is setting up the [BTHome](https://www.home-assistant.io/integrations/bthome/) integration in Home Assistant. -Once setup, the Flipper should be automatically discovered after pressing the -center button once: +Once setup, the Flipper should be automatically discovered after pressing any +D-pad button once: ![home assistant discovered](screenshots/home_assistant_discovered.png) diff --git a/screenshots/75c3eb86-5541-4c01-93ed-b0988b43bef0.png b/screenshots/75c3eb86-5541-4c01-93ed-b0988b43bef0.png new file mode 100644 index 0000000000000000000000000000000000000000..7469b381987b5ca49352c9f7a8e6eea411a98415 GIT binary patch literal 4474 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 literal 0 HcmV?d00001