Widget Scripts
Overview
Most of the time, widget scripts show some info in a zone either in the top bar or in one of the user defined main views, and they cannot receive direct input from the user via key events like e.g. Telemetry scripts.
But widgets on the main views can also be shown in full screen mode, where they take over the entire screen area. And here they receive user input via key events, and for radios with touch screen, also touch events.
Each model can have up to five main views, with up to 8 widgets per screen, depending on their size and layout. Each instance of a widget has his own options table.
Please note: Widget scripts are only available on radios with color screens, e.g. FrSky Horus models, Radiomaster TX16 and Jumper T16.
Lifetime
All widget scripts on the SD card are loaded into memory when the model is selected; even widgets that are not used. This has the side effect that any global functions defined in a widget script will always be available to other widget scripts. It also means that any script on the SD card will consume part of the radio's memory - even if it is not being used. Therefore, it is important to either keep widget scripts small, or to use Lua's loadScript() function to load code dynamically.
They can be added to the top bar or a main view through the telemetry setup menu. When a widget has been added to a screen, then the widget functions are called as follows:
create
is called once when the widget instance is registered (started).update
is called when widget settings are changed by the user.background
is called periodically when the widget instance is not visible. Note: this is different from the way that telemetry scripts are handled.refresh
is called periodically when the widget instance is visible. Note: if you wantbackground
to run when the widget is visible, then call it fromrefresh
.A widget script is stopped and disabled if it misbehaves (e.g. too long runtime, run-time error, or low memory)
All widgets are stopped while a One-Time script is running (see One-Time scripts).
File Location
Widgets are located on the SD card, each in their specific folder /WIDGETS/<name>/main.lua (<name> must be in 8 characters or less).
Interface
Every script must include a return
statement at the end, defining its interface to EdgeTX. This statement returns a table with the following fields:
name
stringoptions
tablecreate
functionupdate
functionbackground
function (optional)refresh
function
Example
Notes
The
name
must be max. 10 characters long.options
is passed tocreate
and then stored in Lua. Changing it has no effect on EdgeTX.If
options
is changed by the user in the Widget Settings menu, thenupdate
will be called with a newoptions
table, unaffected by any changes made by Lua code to the oldoptions
table.Maximum five
options
are allowed, with names of max. 10 characters, and no spaces.If local variables are declared outside functions in the widget script, then they are shared between all instances of the widget.
Therefore, local variables that are private for each instance should be added to the
widget
table in thecreate
function before returning thewidget
table to EdgeTX.When the widget is in fullscreen mode, then
event
is either 0, a key event value, or a touch event value.If
event
is a touch event value, thentouchState
is a table. Otherwise, it isnil
.When the widget is not in fullscreen mode, then both
event
andtouchState
arenil
.The size of the widget's screen area is as follows:
Fullscreen mode:
LCD_W
byLCD_H
Not fullscreen mode:
zone.w
byzone.h
Last updated