Widget Scripts

Purpose

Widget scripts are avaiable on radios equiped with color LCD. They are designed to run constantly in the background performinfg various task. Widget scripts are mostly used to extend EdgeTX functionality via Widgets that are places by user on Main Views. They are equivalent of Telemetry Scripts on radios equiped with B&W LCD.

Most of the time, widget scripts show some info in a Widget's zone in one of the user defined Main Views. They cannot receive direct input from the user via key events with exeption of being displayed in so called Full Screen mode. Full screen mode can be entered by selecting the widget, pressing ENTER and selecting Full screen from the widget's contextual menu, or by double tapping the widget on radios with a touch screen. Full screen mode can be exited by long pressing the EXIT (RTN) button, or by calling the Lua function lcd.exitFullScreen().

Each model can have up to nine 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.

Widget scripts are only available on radios with color LCD screens, such as e.g. FrSky X10 or X12, Radiomaster TX16S, Jumper T16 or T18, Flysky NV14., etc. Read more about radios.

Execution & 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 Widget Script placed in proper location on the SD card will consume part of the radio's memory - even if it is not being used.

It is important to either keep Widget Scripts small, or to use Lua's loadScript() function to load code dynamically

Script executes until:

• it misbehaves (e.g. too long runtime, run-time error, or low memory)

• One-Time script is running. When One-time script finishes execution, Wigdet Script resumes execution.

File Location

Widget scripts are located on the SD card, each one in their specific folder: /WIDGETS/<folder name>/

Widget script folder name length must be 8 characters or less

Widget script name is constant and has to be named main.lua

Example of proper Widget script placement to be registered by EdgeTX as valid Widget script available to user in Widgets selection menu: /WIDGETS/MYWGT/main.lua

Try to use unique folder name. In case of naming clash, previously installed widget will be overwritten.

Interface

Every Widget Script must include a return statement at the end, defining its interface to EdgeTX. This statement returns a table with the following fields:

Field	Type	Required	Desctiption
name	string		This variable holds a name that is displayed to user as Widget scripts name in available Widgets list.

The name length must be 10 characters or less.

Field	Type	Required	Desctiption
options	table		Options table is to store Widget's options available to EdgeTX user via Widget's Settings menu. To see valid options read Widget Options Constants.

options table is passed to create function when invoked and then stored in Lua. Changing options table values while Widget script is running has no effect. This table is designed to be changed with EdgeTX system menus.

If options is changed by the user in the Widget Settings menu, then update will be called with a new options table, unaffected by any changes made by Lua code to the old options table.

Field	Type	Required	Desctiption
create	function		function is called once when the widget instance is registered (started).

Parameters

zone table	This parameter will hold visible dimensions of Widget (height & width)
options table	Initial options table as described above

Return values

widget table	Create function will return table that has to be later passed to update , background & refresh functions allowing to access widget's unique variables

The size of the widget's zone area is as follows:

• Full screen mode: LCD_W by LCD_H

• Not full screen mode: zone.w by zone.h (updated if screen options are changed)

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 the create function before returning the widget table to EdgeTX.

Field	Type	Required	Desctiption
update	function		This function is called when Widget's Settings are changed by the user. It is mostly used to modify Widget Script variables or behaviour basing on options values entered by user.

Parameters

widget table	Widget's table returned by create function, decribed above.
options table	Initial options table as described above

Return values none

Field	Type	Required	Desctiption
background	function		This function is called periodically when the widget instance is NOT VISIBLE.

Parameters

widget table	Widget's table returned by create function, decribed above.

Return values none

Field	Type	Required	Desctiption
refresh	function		This function is called periodically when the widget instance IS VISIBLE.

Parameters

widget table	Widget's table returned by create function, decribed above.
event number	When Widget Script is in full screen mode, then event is either 0, a key event value, or a touch event value. When the widget is not in full screen mode, then event is nil See Key Events.
touchState table	This parameter is only present when radio is equiped with touch interface and event is a touch event. If event is a touch event value, then touchState is a table. Otherwise, it is nil. When the widget is not in full screen mode then touchState is nil See Touch State Events.

Return values none

if you want background function to run when the widget is visible, then call it from refresh function.

Examples

local name = "WidgetName"

-- Create a table with default options
-- Options can be changed by the user from the Widget Settings menu
-- Notice that each line is a table inside { }
local options = {
  { "Source", SOURCE, 1 },
  -- BOOL is actually not a boolean, but toggles between 0 and 1
  { "Boolean", BOOL, 1 },
  { "Value", VALUE, 1, 0, 10},
  { "Color", COLOR, ORANGE },
  { "Text", STRING, "Max8chrs" }
}

local function create(zone, options)
  -- Runs one time when the widget instance is registered
  -- Store zone and options in the widget table for later use
  local widget = {
    zone = zone,
    options = options
  }
  -- Add local variables to the widget table,
  -- unless you want to share with other instances!
  widget.someVariable = 3
  -- Return widget table to EdgeTX
  return widget
end

local function update(widget, options)
  -- Runs if options are changed from the Widget Settings menu
  widget.options = options
end

local function background(widget)
  -- Runs periodically only when widget instance is not visible
end

local function refresh(widget, event, touchState)
  -- Runs periodically only when widget instance is visible
  -- If full screen, then event is 0 or event value, otherwise nil
end

return {
  name = name,
  options = options,
  create = create,
  update = update,
  refresh = refresh,
  background = background
}