Widget Scripts¶

Purpose¶

Widget scripts are available on radios equipped with color LCD. They are designed to run constantly in the background performing various tasks. Widget scripts are mostly used to extend EdgeTX functionality via Widgets that are placed by the user on Main Views. They are the equivalent of Telemetry Scripts on radios equipped 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 exception 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 its own options table.

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

Script executes until:

• it misbehaves (e.g. too long runtime, run-time error, or low memory)
• a One-Time script is running. When the One-Time script finishes execution, the Widget Script resumes execution.

File Location¶

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

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

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:

Parameters

Return values

Parameters

Return values
none

Parameters

Return values
none

Parameters

Return values
none

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
}