BF Telemetry Widget

An EdgeTX full-screen telemetry widget for Betaflight/ELRS aircraft. Supports multiple radio screens with responsive layout:

Radiomaster TX16S MK III (800×480 touchscreen) — 12 hex tiles, touchscreen navigation
Radiomaster TX16S MK II (480×272 touchscreen) — 8 hex tiles, touch + scroll wheel navigation
Jumper T16 (480×272 scroll wheel only) — 8 hex tiles, scroll wheel + button navigation

Displays live telemetry in a hex honeycomb layout with TX/RX battery bars, time-of-day clock, and persistent GPS status.

Supported radio: Radiomaster TX16S MK III. Support for the Radiomaster T15 Max, TX16S MK II, and Jumper T16 is currently in development.

Requirements

Requirement	Version
EdgeTX	2.12+
Lua	5.3
Radio	Any of: • Radiomaster TX16S MK III (800×480, touchscreen) • Radiomaster TX16S MK II (480×272, touchscreen + scroll wheel) • Jumper T16 (480×272, scroll wheel only)
Telemetry	Betaflight + ExpressLRS (ELRS) or compatible FC

Auto-Detection: The widget automatically detects your radio's screen size and input type. No configuration needed beyond standard installation.

Installation

Safe Installation (macOS Recommended) 🆕

If you're on macOS and have other Lua scripts on your SD card (Yaapu, iNav, etc.), use the included safe installer script to merge files without deleting anything:

cd /path/to/BF-Telemetry
./install-to-sd.sh

The script will:

Ask you to select your SD card mount path
Safely merge files using rsync (no deletes, only updates)
Preserve all existing scripts (Yaapu, iNav, custom Lua, etc.)
Show a summary before confirming

This is the safest method and fully automated. No need for Finder drag-and-drop.

One-step command mode (no prompts)

If you already know your SD mount path, run one command:

./install-to-sd.sh --sd /Volumes/EDGETX --yes

That installs only WIDGETS/BFTelem (recommended).

To also include optional extras in the same one-step command:

./install-to-sd.sh --sd /Volumes/EDGETX --yes --with-sounds --with-scripts

Safe Installation (Windows) 🆕

Windows users without bash: Use File Explorer (safe, no file deletion):

Connect your SD card to your Windows PC (via USB card reader or built-in SD slot)
Extract the repository (right-click → Extract All)
In File Explorer, navigate to the extracted folder and open the WIDGETS folder
Drag BFTelem folder into your SD card's WIDGETS folder
- If prompted "Replace folder?" → click Skip (keeps existing files intact)
- If prompted "Merge?" → click Yes
(Optional) Repeat step 4 with SOUNDS folder if you want custom voice overrides

Result: [SD Card]\WIDGETS\BFTelem\main.lua is now on your radio.

Command-line alternative (Windows PowerShell)

If you prefer the command line:

# Navigate to extracted BF-Telemetry folder
cd C:\Users\YourName\Downloads\BF-Telemetry

# Copy only the widget (recommended)
robocopy WIDGETS E:\WIDGETS /E /NFL /NDL /NJH /NJS

Replace E: with your SD card's actual drive letter. The /NFL and similar flags suppress verbose output.

To also include sounds:

robocopy WIDGETS E:\WIDGETS /E /NFL /NDL /NJH /NJS
robocopy SOUNDS E:\SOUNDS /E /NFL /NDL /NJH /NJS

Recommended (Like Other Telemetry Widgets)

Copy only the widget folder:

WIDGETS/BFTelem  ->  [SD CARD]/WIDGETS/BFTelem

This is the same low-risk pattern used by most telemetry widgets (copy one script/widget folder into the existing SD card parent folder).

SOUNDS/ is optional and only needed if you want custom voice overrides.

Note for Jumper T16 users: This widget is fully compatible with Jumper T16's 480×272 screen and scroll wheel input. No additional steps needed beyond standard installation — the widget auto-detects your radio and adjusts layout and input handling accordingly.

Alternate (Drag-and-Drop Repo Top-Level Folders)

⚠️ macOS/Windows Users: See the Safe Installation sections above first. Dragging top-level SOUNDS/WIDGETS folders onto your SD card root may show replace/merge prompts. Prefer copying only WIDGETS/BFTelem (recommended above), or use the safe install methods for merge behavior.

This repository now includes top-level EdgeTX SD folders:

WIDGETS/
SOUNDS/
SCRIPTS/

After downloading and unzipping, if you use this alternate method, copy these folders directly to the root of your EdgeTX SD card.

Main widget path after copy:

/WIDGETS/BFTelem/main.lua

Square theme variant is also included at:

/WIDGETS/BFTelem/main.square.lua

If you want the square theme, replace main.lua with main.square.lua.

Manual (Single File)

Copy main.lua into a new folder on your radio's SD card:
```
/WIDGETS/BFTelem/main.lua
```
On the radio, navigate to Screen Setup → Add Widget and select BF Telemetry.

Only main.lua is needed on the radio for the default theme. The emulator files, screenshots, and launcher are development-only and do not need to be copied to the SD card.

Supported Radios

Radiomaster TX16S MK III (800×480, touchscreen)

Tiles: 12 hex tiles in 6×2 honeycomb grid
Input: Touchscreen (primary), Scroll wheel + buttons (alternative)
Navigation: Touch any tile to open metric picker menu

Radiomaster TX16S MK II (480×272, touchscreen + scroll wheel)

Tiles: 8 hex tiles in 4×2 honeycomb grid (responsive layout)
Input: Touchscreen (primary), Scroll wheel + buttons (alternative)
Navigation: Touch tiles OR use scroll wheel + Enter button

Jumper T16 (480×272, scroll wheel only)

Tiles: 8 hex tiles in 4×2 honeycomb grid (responsive layout)
Input: Scroll wheel + buttons only (no touchscreen)
Navigation: Scroll wheel to focus tile, Enter button to open metric picker

Layout Themes

Two layout variants are available. Choose the one you prefer by using the corresponding main.lua:

Theme	File	Description
Hex Honeycomb (default)	`main.lua`	12 flat-top hexagonal tiles in a staggered grid. Touchscreen tile reassignment, dropdown metric menu.
Square Tiles	`Other Themes/Square_tiles/main.lua`	Classic 4×3 recessed rectangular tile grid with cyan corner accents.

Both themes support all three display modes (numeric / bar / gauge), TX and RX battery sidebar bars, and the same sensor/color logic.

To use the Square Tiles theme, copy Other Themes/Square_tiles/main.lua to your SD card instead:

/WIDGETS/BFTelem/main.lua

Telemetry Tiles

The widget shows 12 tiles populated automatically from your ELRS/Betaflight telemetry stream:

Tile	Sensor	Unit
Link Quality	`RQly`	%
Battery	`RxBt`	V (pack + per-cell)
Current	`Curr`	A
Flight Timer	arm/disarm event	mm:ss
RSSI	`1RSS` / `2RSS`	dBm
Cell Voltage	`RxBt` ÷ Cells	V/cell
Capacity Used	`Capa`	mAh
Throttle	`thr` (stick)	%
TX Power	`TPWR`	mW
Altitude	`Alt`	m
Distance	`Dist`	m
RF Mode	`RFMD`	—

The header bar shows model name, flight mode, armed/disarmed status, TX battery voltage, active display mode, and time of day.

Widget Setup (Options Wizard)

When you first add the widget, open its Options panel on the radio (long-press the widget area while not in full-screen, or go to Model → Screen Setup → Edit Widget).

Set these values to match your aircraft and battery:

Option	Default	Range	Description
`FullV`	42	30 – 50	Full cell voltage × 10 (42 = 4.2 V/cell; use 42 for standard LiPo)
`WarnV`	36	30 – 42	Warning voltage × 10 (36 = 3.6 V — tile turns yellow below this)
`CritV`	34	30 – 42	Critical voltage × 10 (34 = 3.4 V — tile turns red below this)
`LQWrn`	70	10 – 99	Link quality % below which LINK Q turns yellow/red
`SndEn`	1	0 – 1	Master sound alerts (`0` off, `1` on)
`SndArmd`	0	0 – 1	Play ARMED / DISARMED voice alerts
`SndBatt`	1	0 – 1	Play battery low/critical voice alerts
`SndRSSI`	1	0 – 1	Play low RSSI voice alerts
`RSSIWrn`	90	60 – 120	RSSI warning threshold in absolute dBm (e.g. 90 = -90 dBm)
`SndRpt`	15	5 – 120	Repeat period (seconds) while an alert condition persists
`TmrRed`	180	30 – 900	Flight timer (seconds) at which the timer tile turns red
`DistRed`	100	20 – 2000	Distance (metres) at which the DIST tile turns red
`ScreenType`	0	0 – 2	Display style: `0` = numeric, `1` = bar, `2` = arc gauge
`ThrOn`	5	0 – 50	Throttle % threshold to start the flight timer

Note: Battery cell count is now always auto-detected from pack voltage. There is no manual cell count or override option. The widget will automatically determine the correct cell count for any battery type (1S–8S) and fall back safely if telemetry is inconsistent.

Removed options: Craft Batt Cells, T1–T12 tile assignments, and ArmSrc are no longer present. The widget now uses a minimal, robust setup for all users.

Sound Files

By default, BF Telemetry uses existing EdgeTX system voice files for all announcements, so you get audio alerts automatically without any setup.

Voice file lookup order:

Custom widget sounds in /WIDGETS/BFTelem/sounds/ (override EdgeTX system voices)
EdgeTX system voices in /SOUNDS/en/ (default; built into EdgeTX)
Tone beep fallback (if neither above exists)

Default EdgeTX system voice mappings:

Alert	System Voice	Fallback
ARMED	`armed.wav`	2200 Hz tone
DISARMED	`disarmed.wav`	1200 Hz tone
Battery Low	`bat1.wav`	1300 Hz tone
Battery Critical	`bat0.wav`	900 Hz tone
Low RSSI	`rssiloss.wav`	1600 Hz tone
No GPS Fix (arm attempt)	(none — triple buzzer beep)	descending 3-tone beep

Optional: To override with custom voices, place WAV files in /WIDGETS/BFTelem/sounds/ with these names:

armed.wav
disarmed.wav
batlow.wav
batcrit.wav
lowrssi.wav
nogpsfix.wav (optional custom voice, e.g. "Not ready to arm, waiting for GPS")

The widget will use custom files in preference to EdgeTX system voices.

Usage Instructions

Switching Display Modes

The widget has three display modes, each showing the same 12 metrics (or 8 on smaller screens) in a different visual style:

[ NUM ] — Numeric: large value text with label and unit.
[ BAR ] — Bar graph: horizontal progress bar with compact value/unit text.
[GAUGE] — Arc gauge: semicircular arc that grows with the value.

On TX16S MK III (touchscreen):

Turn the scroll wheel to cycle through modes, or
Long-press the scroll wheel (hold ~1 second) to open the tile assignment menu.

On TX16S MK II (touchscreen + scroll wheel):

Touch and hold a tile for metric assignment (same as MK III), or
Use scroll wheel + Enter for scroll wheel-only navigation

On Jumper T16 (scroll wheel only):

Use scroll wheel to focus a tile (bright cyan ring shows focus)
Press Enter/OK to open metric picker
Scroll wheel in menu to select metric, Enter to apply

In the emulator: Press N, B, or G on your keyboard.

Reassigning Tiles — Touchscreen (TX16S MK III / TX16S MK II)

Each hex tile can be set to display any metric you want.

On the radio:

Touch and hold a hex tile on the touchscreen.
Wait until the EdgeTX system logo in the top-left corner disappears — this confirms the widget's touch UI has taken over (takes ~0.5 s).
A scrollable dropdown menu appears listing all available metrics.
Scroll by dragging your finger up or down inside the menu.
Tap any metric name to assign it to that tile. The menu closes immediately.
Tap outside the menu (anywhere on the hex grid) to dismiss without changing anything.

The menu opens with the currently-assigned metric already highlighted so you can confirm what is assigned before changing it.

In the emulator (legacy mode): Click a tile to open the metric menu. Click a metric name to assign it, or click outside the menu to dismiss.

Reassigning Tiles — Scroll Wheel (TX16S MK II / Jumper T16)

Use scroll wheel + buttons for metric assignment on radios without convenient touchscreen access:

On the radio:

Scroll wheel rotates through tiles — a bright cyan focus ring shows the currently-focused tile
Press Enter/OK button on the focused tile — metric picker menu opens
Scroll wheel in the menu rotates through available metrics (first visible metric is highlighted)
Press Enter/OK to assign the highlighted metric and close the menu
Press Return/Exit to dismiss the menu without changing anything

This same scroll wheel navigation is also available as an alternative on TX16S MK III if you prefer not to use the touchscreen.

Side Battery Bars

Two vertical bar graphs run along the left and right edges of the screen:

Left bar — RX batt: Your drone's LiPo pack level, calculated from per-cell voltage with auto cell-count detection (Cells=0) or manual override.
Right bar — TX batt: Your radio's internal 2S LiPo level, estimated from the TX voltage.

Both bars use 10 color-coded segments: green (top) → yellow (middle) → red (bottom). The percentage is shown below each bar. The bars update live during flight.

Header Bar

Region	Content
Far left	Model name (e.g. `AIR65`)
Center-left	Current Betaflight flight mode (e.g. `ANGLE`, `ACRO`)
Center-right	Armed / disarmed status
Far right	TX battery voltage · active display mode badge · time of day

DISARMED is shown in green. The flight timer shows --:--.
ARMED turns red. The flight timer starts once throttle rises above ThrOn.

Tile Color Semantics

Color	Meaning
Green	Good / nominal
Yellow	Caution / approaching threshold
Orange	Warning
Red	Critical / threshold exceeded

High-is-good (green at high values): Link Quality, Battery, RSSI, Cell Voltage, TX Power
High-is-bad (red at high values): Current, Capacity Used, Throttle, Altitude, Distance
Timer: green → turns yellow as it approaches TmrRed → red when it hits TmrRed

Customizing Sensor Names

If your FC reports telemetry under different names, edit the constants near the top of main.lua:

local SN_LQ    = "RQly"   -- Link quality
local SN_RSSI1 = "1RSS"   -- RSSI antenna 1
local SN_RSSI2 = "2RSS"   -- RSSI antenna 2
local SN_VOLT  = "RxBt"   -- Battery voltage
local SN_CURR  = "Curr"   -- Current
local SN_CAPA  = "Capa"   -- Capacity used
local SN_ALT   = "Alt"    -- Altitude
local SN_FM    = "FM"     -- Flight mode
local SN_TPWR  = "TPWR"  -- TX power
local SN_RFMD  = "RFMD"  -- RF mode
local SN_DIST  = "Dist"   -- Distance

Sensor names can be found in EdgeTX under Model → Telemetry → Discovered sensors.

Running the Emulator

A Python-based desktop emulator lets you preview the widget without a physical radio.

Prerequisites

Python 3.8+
pygame (required)
lupa (optional — enables Lua-driven hot-reload mode)

pip install pygame lupa

Launch

python dist/launcher.py

Emulator Keyboard Controls

Key	Action
`N`	Switch to Numeric mode
`B`	Switch to Bar mode
`G`	Switch to Gauge mode
`A`	Toggle armed / disarmed
`R`	Reload `main.lua` from disk (Lua-driven mode only)
`S`	Save a screenshot to `assets/screenshots/`
`Q`	Quit

Mouse: Click any hex tile to open the metric assignment dropdown. Click a metric name to assign it. Click outside to dismiss.

Lua-driven vs Legacy mode

Lua-driven (requires lupa): runs main.lua directly; hot-reloads on every file save — edit and see changes immediately.
Legacy Python (no lupa needed): Python-native renderer that mirrors the Lua layout and behavior.

Multi-Screen Testing

In Lua-driven mode, press these keys to switch between screen sizes and device types:

Key	Screen	Device	Notes
`1`	800×480	TX16S MK III	Default; 12-tile layout, touchscreen
`2`	480×272	TX16S MK II	8-tile layout, touchscreen + scroll wheel
`3`	480×272	Jumper T16	8-tile layout, scroll wheel only

The screen configuration is remembered for the next launch, so you can switch between devices and test the responsive layout without restarting.

Generating Screenshots

To regenerate all display mode screenshots for all supported screen sizes automatically (no window needed):

python dist/take_screenshots.py

This generates screenshots for:

800×480 (TX16S MK III): BF Telem lua screenshot_{num|bar|gauge}.png
480×272 (TX16S MK II / Jumper T16): BF Telem lua screenshot_{num|bar|gauge}_480x272.png

Output is saved to assets/screenshots/.

Screenshot font mapping follows the Lua widget flags used in main.lua (SMLSIZE, MIDSIZE, DBLSIZE, and BOLD) and scales responsively for each screen size.

Screenshots

These are the latest regenerated emulator captures, including the updated font sizing pass (larger header text across modes, larger BAR numeric values, and enlarged NUM/GAUGE value text).

Numeric Mode

Large value readout with label and unit. RX batt (left) and TX batt (right) bars are visible on the side rails, with the time shown in the top-right gap. The persistent GPS status is now shown in the bottom left, as seen below.

Bar Mode

Horizontal progress bars for at-a-glance percentage comparison across all tiles, while keeping value/unit text readable. RX batt (left) and TX batt (right) bars are visible on the side rails, with the time shown in the top-right gap. The persistent GPS status is now shown in the bottom left, as seen below.

Gauge Mode

Semicircular arc gauges that grow as the value increases. Arc color follows the metric's threshold semantics (green / yellow / red), with a consistent flat hex border style. RX batt (left) and TX batt (right) bars are visible on the side rails, with the time shown in the top-right gap. The persistent GPS status is now shown in the bottom left, as seen below.

The RX batt (left) and TX batt (right) vertical bars are always visible on the side rails in all three modes. The persistent GPS status display is also always visible in the bottom left.

480×272 Responsive Layout (TX16S MK II / Jumper T16)

The widget automatically scales to smaller screens, maintaining the same three display modes with a 4-column honeycomb grid (8 tiles instead of 12):

Numeric Mode (480×272)

Bar Mode (480×272)

Gauge Mode (480×272)

The layout automatically detects your radio's screen size and adjusts:

Hex grid: 6 columns (12 tiles) on 800×480, 4 columns (8 tiles) on 480×272
Font sizes: Proportionally scaled (~60% on smaller screens)
UI elements: Responsive positioning and sizing for all screen sizes

License

MIT — use freely, modify to suit your build.

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
.github/workflows		.github/workflows
Other Themes/Square_tiles		Other Themes/Square_tiles
SCRIPTS		SCRIPTS
SOUNDS/en		SOUNDS/en
WIDGETS/BFTelem		WIDGETS/BFTelem
assets/screenshots		assets/screenshots
dist		dist
.gitignore		.gitignore
README.MD		README.MD
install-to-sd.sh		install-to-sd.sh
option		option

Folders and files

Latest commit

History

Repository files navigation

BF Telemetry Widget

Requirements

Installation

Safe Installation (macOS Recommended) 🆕

One-step command mode (no prompts)

Safe Installation (Windows) 🆕

Command-line alternative (Windows PowerShell)

Recommended (Like Other Telemetry Widgets)

Alternate (Drag-and-Drop Repo Top-Level Folders)

Manual (Single File)

Supported Radios

Radiomaster TX16S MK III (800×480, touchscreen)

Radiomaster TX16S MK II (480×272, touchscreen + scroll wheel)

Jumper T16 (480×272, scroll wheel only)

Layout Themes

Telemetry Tiles

Widget Setup (Options Wizard)

Sound Files

Usage Instructions

Switching Display Modes

Reassigning Tiles — Touchscreen (TX16S MK III / TX16S MK II)

Reassigning Tiles — Scroll Wheel (TX16S MK II / Jumper T16)

Side Battery Bars

Header Bar

Tile Color Semantics

Customizing Sensor Names

Running the Emulator

Prerequisites

Launch

Emulator Keyboard Controls

Lua-driven vs Legacy mode

Multi-Screen Testing

Generating Screenshots

Screenshots

Numeric Mode

Bar Mode

Gauge Mode

480×272 Responsive Layout (TX16S MK II / Jumper T16)

Numeric Mode (480×272)

Bar Mode (480×272)

Gauge Mode (480×272)

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages