This section includes Acknowledgments and Getting Started.

Join the chat on Discord

The latest version of this guide will always be available here. At the top of the left sidebar there is a version option if you are running an older version of EdgeTX or OpenTX and need the docs for that specific version.

Please feel free to make suggestions or corrections to the documentation on GitHub, but the prefered method of editing is to use GitBook, so all changes will need to be made by someone who is authorized as a writer there.

This guide covers the development of user-written scripts for R/C transmitters running the EdgeTX 2.5 operating system with Lua support. Readers should be familiar with EdgeTX/OpenTX, the OpenTX Companion, and know how to transfer files the SD card in the transmitter.

If you are new to Lua programming, you may also find the Lua Reference Manual of assistance

Part I is an overview of the different script types, along with basic examples of each.

Part II is a programming guide that introduces the types of EdgeTX Lua scripts and how to use them.

Part III is the EdgeTX Lua API Reference

Part IV covers advanced topics with examples

The EdgeTX team has no intention of making a profit from their work. EdgeTX is free and open source and will remain free and open source. But EdgeTX is more expensive to maintain than most open source projects. The reason is that there is a never ending flood of hardware to integrate and maintain code for. Hardware that costs.

TODO: Need to determine status of wizard in 2.2

Downloading EdgeTX Companion

EdgeTX Companion 2.5 is available for download here (pick the version for your operating system from Assets heading at the bottom of the page).

Updating firmware with Lua option selected

If you intend to use mixer scripts, when updating the firmware on your transmitter you need to make sure the lua option is checked in the settings for your radio profile (Main menu -> Settings ->Settings...) as shown below. This is not required if you only intend to run telemetry, one-time and function scripts, support for those is included by default.

Also note that the SD Structure path should contain a valid path to a copy of your transmitter's SD card contents, although that's not specific to Lua.

This functions allows for sending SPORT / ACCESS telemetry data toward the receiver, and more generally, to anything connected SPORT bus on the receiver or transmitter.

When called without parameters, it will only return the status of the output buffer without sending anything.

@status current Introduced in 2.3

Parameters

Get channel assigned to stick. See Default Channel Order in General Settings

@status current Introduced in 2.0.0

Parameters

• stick (number) stick number (from 0 to 3)

Raises a pop-up on screen that asks for confirmation

@status current Introduced in 2.2.0, changed from (title, event) to (title, message, event) in 2.3.8

Parameters

• title (string) title to display

This function reads/writes the Multi protocol buffer to interact with a protocol².

@status current Introduced in 2.3.2

Parameters

• address to read/write in the buffer

Clear all flightModes

@status current Introduced in 2.3.10

Parameters

none

Get RSSI value as well as low and critical RSSI alarm levels (in dB)

@status current Introduced in 2.2.0

Parameters

none

Return rotary encoder current speed

@status current Introduced in 2.3.10

Parameters

none

Delete mixer line from specified Channel

@status current Introduced in 2.0.0

Parameters

• channel (unsigned number) channel number (use 0 for CH1)

Resets the radio global timer to 0.

@status current Introduced in 2.2.2, param added in 2.3

Parameters

• (optional) : if set to 'all', throttle ,throttle percent and session timers are reset too

Return current RTC system date as unix timstamp (in seconds since 1. Jan 1970)

Please note the RTC timestamp is kept internally as a 32bit integer, which will overflow in 2038.

Parameters

none

Play a time value (text to speech)

@status current Introduced in 2.1.0

Parameters

• duration (number) number of seconds to play. Only integral part is used.

Generate haptic feedback

@status current Introduced in 2.2.0

Parameters

• duration (number) length of the haptic feedback in milliseconds

Return flight mode data.

@status current Introduced in 2.1.7

Parameters

• mode (number) flight mode number to return (0 - 8). If mode parameter

Change the working directory

@status current Introduced in 2.3.0

Parameters

• directory (string) New working directory

Return value

none

Return the RAS value or nil if no valid hardware found

@status current Introduced in 2.2.0

Parameters

none

Return value

• number representing RAS value. Value bellow 0x33 (51 decimal) are all ok, value above 0x33 indicate a hardware antenna issue.

  This is just a hardware pass/fail measure and does not represent the quality of the radio link

Notice

RAS was called SWR in the past

This section describes the Lua libraries, functions and constants that are provided by EdgeTX.

Delete all Inputs

@status current Introduced in 2.0.0

Parameters

none

Return value

none

This functions allows for sending telemetry data toward the TBS Crossfire link.

When called without parameters, it will only return the status of the output buffer without sending anything.

@status current Introduced in 2.2.0, retval nil added in 2.3.4

Parameters

• command command

• data table of data bytes

Return value

• boolean data queued in output buffer or not.

• nil incorrect telemetry protocol.

Get available memory remaining in the Heap for Lua.

Parameters

none

Return value

• usage (number) a value returned in b

Set all inputs to defaults

@status current Introduced in 2.0.0

Parameters

none

Return value

none

Remove all mixers

@status current Introduced in 2.0.0

Parameters

none

Return value

none

Return the time since the radio was started in multiple of 10ms

The timer internally uses a 32-bit counter which is enough for 497 days so overflows will not happen.

@status current Introduced in 2.0.0

Parameters

none

Return value

• number Number of 10ms ticks since the radio was started Example:

  run time: 12.54 seconds, return value: 1254

Insert a mixer line into Channel

@status current Introduced in 2.0.0, parameters below multiplex added in 2.0.13

Parameters

• channel (unsigned number) channel number (use 0 for CH1)

• line (unsigned number) mix number (use 0 for first line(mix))

• value (table) see model.getMix() for table format

Return value

none

Insert an Input at specified line

@status current Introduced in 2.0.0, curveType/curveValue/carryTrim added in 2.3, inputName added 2.3.10

Parameters

• input (unsigned number) input number (use 0 for Input1)

• line (unsigned number) input line (use 0 for first line)

• value (table) input data, see model.getInput()

Return value

none

Play a file from the SD card

@status current Introduced in 2.0.0, changed in 2.1.0

Parameters

• path (string) full path to wav file (i.e. “/SOUNDS/en/system/tada.wav”)

  Introduced in 2.1.0: If you use a relative path, the current language is appended

  to the path (example: for English language: /SOUNDS/en is appended)

Return value

none

Set Custom Function parameters

@status current Introduced in 2.0.0, TODO rename function

Parameters

• function (unsigned number) custom function number (use 0 for CF1)

• value (table) custom function parameters, see model.getCustomFunction() for table format

Return value

none

Notice

If a parameter is missing from the value, then that parameter remains unchanged.

Set baudrate for serial port(s) affected to LUA

@status current Introduced in 2.3.12

Parameters

baudrate Desired baudrate

Return value

none

This section provides more specifics on the EdgeTX Lua implementation. Here you will find syntax rules for interface tables and functions.

Returns gray value which can be used in LCD functions

@status current Introduced in 2.0.13

Parameters

none

Return value

• (number) a value that represents amount of greyness (from 0 to 15)

Notice

Only available on Taranis

Reset Telemetry Sensor parameters

@status current Introduced in 2.3.11

Parameters

• sensor (unsigned number) sensor number (use 0 for sensor 1)

Return value

• nil

Set Flight mode parameters

@status current Introduced in 2.3.10

Parameters

• index (unsigned number) flight mode number (use 0 for FM0)

• params see model.getFlightMode return format for table format.

Return value

none

The loadScript(<file>) function will load a script from a the file and return a function that is the body of the script, as described in the previous section. So you could have the following Lua script file saved on the SD card:

-- /SCRIPTS/TestScript.lua
local c = ...

local function f(x)
  return x + c
end

return f

You can load and use the above file with the following code:

local chunk = loadScript("/SCRIPTS/TestScript.lua")

local f1 = chunk(1)
local y = f1(5)
-- y = 5 + 1

local f2 = chunk(3)
local z = f2(5)
-- z = 5 + 3

So here we put together what we learned in the previous section. The body of the script is an anonymous function returned by loadScript and stored in the variable chunk. It returns the function f when it is called. The local variable c in the script is assigned to the first vararg passed to the call. Since a new closure is created every time we call chunk, f1 and f2 have different closures with different values of c.

Return current global variable value

Example:

  -- get GV3 (index = 2) from Flight mode 0 (FM0)
  val = model.getGlobalVariable(2, 0)

Parameters

• index zero based global variable index, use 0 for GV1, 8 for GV9

• flight_mode Flight mode number (0 = FM0, 8 = FM8)

Return value

• nil requested global variable does not exist

• number current value of global variable

Notice

a simple warning or notice

Overview

Function scripts are invoked via the 'Lua Script' option of Special Functions configuration page.

Typical uses of Function scripts are:

• specialized handling in response to switch position changes

• customized announcements

Please be aware that:

• all function scripts are stopped if a One-Time Lua script is running

• Function scripts DO NOT HAVE ACCESS TO LCD DISPLAY

Lifetime

• init function is called once when the model is selected

• depending on the switch associated with the Special Function, either the run function (switch = on) or the background function (switch = off) is called periodically

• the script is stopped and disabled if it misbehaves (e.g. run-time error or low memory)

File Location

Scripts are located on the SD card in the folder /SCRIPTS/FUNCTIONS/<name>.lua. File name length (without extension) must be 6 characters or less (this limit was 8 characters in OpenTX 2.1).

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:

• init function (optional)

• run function

• background function (optional)

Example

Return current system date and time that is kept by the RTC unit

Parameters

none

Return value

• table current date and time, table elements:

  • year (number) year

  • mon (number) month

Returns (some of) the general radio settings

@status current Introduced in 2.0.6, imperial added in TODO, language and voice added in 2.2.0, gtimer added in 2.2.2.

Parameters

none

Return value

• table with elements:

  • battWarn (number) radio battery range - warning value

  • battMin (number) radio battery range - minimum value

Return the internal GPS position or nil if no valid hardware found

@status current Introduced in 2.2.2

Parameters

none

Return value

• table representing the current radio position

  • lat (number) internal GPS latitude, positive is North

  • lon (number) internal GPS longitude, positive is East

Play a tone

@status current Introduced in 2.1.0

Parameters

• frequency (number) tone frequency in Hz (from 150 to 15000)

• duration (number) length of the tone in milliseconds

• pause (number) length of the silence after the tone in milliseconds

• flags (number):

  • 0 or not present play with normal priority.

  • PLAY_BACKGROUND play in background (built in vario function uses this context)
• freqIncr (number) positive number increases the tone pitch (frequency with time), negative number decreases it. The frequency changes every 10 milliseconds, the change is freqIncr * 10Hz. The valid range is from -127 to 127.

Return value

none

Pops a received Crossfire Telemetry packet from the queue.

@status current Introduced in 2.2.0

Parameters

none

Return value

• nil queue does not contain any (or enough) bytes to form a whole packet

• multiple returns 2 values:

  • command (number)

Play a numerical value (text to speech)

@status current Introduced in 2.0.0

Parameters

• value (number) number to play. Value is interpreted as integer.

• unit (number) unit identifier [Full list]((../appendix/units.html))

• attributes (unsigned number) possible values:

  • 0 or not present plays integral part of the number (for a number 123 it plays 123)

  • PREC1 plays a number with one decimal place (for a number 123 it plays 12.3)

Return value

none

Pops a received SPORT packet from the queue. Please note that only packets using a data ID within 0x5000 to 0x50FF (frame ID == 0x10), as well as packets with a frame ID equal 0x32 (regardless of the data ID) will be passed to the LUA telemetry receive queue.

@status current Introduced in 2.2.0

Parameters

none

Return value

• nil queue does not contain any (or enough) bytes to form a whole packet

• multiple returns 4 values:

  • sensor ID (number)

Returns radio timers

@status current Introduced added in 2.3.0.

Parameters

none

Return value

• table with elements:

• gtimer (number) radio global timer in seconds

• session (number) radio session in seconds

Overview

Telemetry scripts are used for building customized screens. Each model can have up to three active scripts as configured on the model's telemetry configuration page. The same script can be assigned to multiple models.

Please note: Telemetry scripts are only available on radios with telemetry screens, such as e.g. FrSky Taranis models (including Xlite), Radiomaster TX12 and and Jumper T12.

WARNING - Running a One-Time script will suspend execution of all other currently loaded Lua scripts (Custom, Telemetry, and Functions)

Overview

One-Time scripts start when called upon by a specific radio function or when the user selects them from a contextual menu. They do their task and are then terminated and unloaded. Please note that all persistent scripts are halted during the execution of One-Time scripts. They are automatically restarted once the One-Time script is finished. This is done to provide enough system resources to execute the one time script.

Raises a pop-up on screen that shows a warning

@status current Introduced in 2.2.0

Parameters

• title (string) text to display

Delete line from specified input

@status current Introduced in 2.0.0

Parameters

• input (unsigned number) input number (use 0 for Input1)

@param str (string) String to be written to the serial port.

Writes a string to the serial port. The string is allowed to contain any character, including 0.

@status current Introduced in 2.3.10

Parameters

none

Get Telemetry Sensor parameters

@status current Introduced in 2.3.0

Parameters

• sensor (unsigned number) sensor number (use 0 for sensor 1)

@param num (optional): maximum number of bytes to read. If non-zero, serialRead will read up to num characters from the buffer. If 0 or left out, serialRead will read up to and including the first newline character or the end of the buffer. Note that the returned string may not end in a newline if this character is not present in the buffer.

Reads characters from the serial port. The string is allowed to contain any character, including 0.

@status current Introduced in 2.3.8

Parameters

none

Raises a pop-up on screen that allows uses input

@status current Introduced in 2.0.0

Parameters

• title (string) text to display

Get Custom Function parameters

@status current Introduced in 2.0.0, TODO rename function

Parameters

• function (unsigned number) custom function number (use 0 for CF1)

Stops key state machine. See for the detailed description.

@status current Introduced in 2.0.0

Parameters

• key (number) key to be killed, can also include event type (only the key part is used)

@status current Introduced in 2.2.0

Parameters

• id Id of the sensor, valid range is from 0 to 0xFFFF

Get the number of Mixer lines that the specified Channel has

@status current Introduced in 2.0.0

Parameters

• channel (unsigned number) channel number (use 0 for CH1)

Return number of lines for given input

@status current Introduced in 2.0.0

Parameters

• input (unsigned number) input number (use 0 for Input1)

Get stick that is assigned to a channel. See Default Channel Order in General Settings.

@status current Introduced in 2.0.0

Parameters

• channel (number) channel number (0 means CH1)

Get Logical Switch parameters

@status current Introduced in 2.0.0

Parameters

• switch (unsigned number) logical switch number (use 0 for LS1)

This functions allows for sending SPORT telemetry data toward the receiver, and more generally, to anything connected SPORT bus on the receiver or transmitter.

When called without parameters, it will only return the status of the output buffer without sending anything.

@status current Introduced in 2.2.0, retval nil added in 2.3.4

Parameters

Set Curve parameters

The first and last x value must -100 and 100 and x values must be monotonically increasing

@status current Introduced in 2.2.0

Example setting a 4-point custom curve:

setting a 6-point standard smoothed curve

Parameters

Get current Model information

@status current Introduced in 2.0.6, changed in 2.2.0

Parameters

none

Return input data for given input and line number

@status current Introduced in 2.3.10

Parameters

• index (unsigned number) flight mode number (use 0 for FM0)

Return input data for given input and line number

@status current Introduced in 2.0.0, curveType/curveValue/carryTrim added in 2.3, inputName added 2.3.10, flighmode reworked in 2.3.11

Parameters

• input

Get percent of already used Lua instructions in current script execution cycle.

@status current Introduced in 2.2.1

Parameters

none

Return value

• usage (number) a value from 0 to 100 (percent)

Reset model timer to a startup value

@status current Introduced in TODO

Parameters

• timer (number) timer index (0 for Timer 1)

Return value

none

Return detailed information about field (source)

The list of valid sources is available:

@status current Introduced in 2.0.8, 'unit' field added in 2.2.0

Parameters

• name (string) name of the field

Return value

• table information about requested field, table elements:

  • id (number) field identifier

  • name (string) field name

Return OpenTX version

@status current Introduced in 2.0.0, expanded in 2.1.7, radio type strings changed in 2.2.0, os name added in EdgeTX 2.4.0

Example

This example also runs in OpenTX versions where the function returned only one value:

local function run(event)
  local ver, radio, maj, minor, rev, osname = getVersion()
  print("version: "..ver)
  if radio then print ("radio: "..radio) end
  if maj then print ("maj: "..maj) end
  if minor then print ("minor: "..minor) end
  if rev then print ("rev: "..rev) end
  if osname then print ("osname: "..osname) end
  return 1
end

return {  run=run }

Output of the above script in simulator:

Parameters

none

Return value

• string OpenTX version (ie "2.1.5")

• multiple values (available since 2.1.7):

  • (string) OpenTX version (ie "2.1.5")

Get Curve parameters

Note that functions returns the tables starting with index 0 contrary to LUA's usual index starting with 1

@status current Introduced in 2.0.12

Parameters

• curve (unsigned number) curve number (use 0 for Curve1)

Return value

• nil requested curve does not exist

• table curve data:

  • name (string) name

Get RF module parameters

Type values:

• 0 NONE

• 1 PPM

• 2 XJT_PXX1

• 3 ISRM_PXX2

• 4 DSM2

• 5 CROSSFIRE

• 6 MULTIMODULE

• 7 R9M_PXX1

• 8 R9M_PXX2

• 9 R9M_LITE_PXX1

• 10 R9M_LITE_PXX2

• 11 R9M_LITE_PRO_PXX1

• 12 R9M_LITE_PRO_PXX2

• 13 SBUS

• 14 XJT_LITE_PXX2

subType values for XJT_PXX1:

• -1 OFF

• 0 D16

• 1 D8

• 2 LR12

@status current Introduced in 2.2.0

Parameters

• index (number) module index (0 for internal, 1 for external)

Return value

• nil requested module does not exist

• table module parameters:

  • subType (number) protocol index

Load a Lua script file. This is similar to Lua's own loadfile() API method, but it uses OpenTx's optional pre-compilation feature to save memory and time during load.

Return values are same as from Lua API loadfile() method: If the script was loaded w/out errors then the loaded script (or "chunk") is returned as a function. Otherwise, returns nil plus the error message.

@status current Introduced in 2.2.0

Example

Parameters

• file (string) Full path and file name of script. The file extension is optional and ignored (see mode param to control which extension will be used). However, if an extension is specified, it should be ".lua" (or ".luac"), otherwise it is treated as part of the file name and the .lua/.luac will be appended to that.

• mode (string) (optional) Controls whether to force loading the text (.lua) or pre-compiled binary (.luac) version of the script. By default OTx will load the newest version and compile a new binary if necessary (overwriting any existing .luac version of the same script, and stripping some debug info like line numbers). You can use mode to control the loading behavior more specifically. Possible values are:

Return value

• function The loaded script, or nil if there was an error (e.g. file not found or syntax error).

• string Error message(s), if any. Blank if no error occurred.

Notice

Note that you will get an error if you specify mode as "b" or "t" and that specific version of the file does not exist (eg. no .luac file when "b" is used). Also note that mode is NOT passed on to Lua's loader function, so unlike with loadfile() the actual file content is not checked (as if no mode or "bt" were passed to loadfile()).

Get servo parameters

@status current Introduced in 2.0.0

Parameters

• index (unsigned number) output number (use 0 for CH1)

Return value

• nil requested output does not exist

• table output parameters:

  • name (string) name

Get model timer parameters

@status current Introduced in 2.0.0, name added in 2.3.6

Parameters

• timer (number) timer index (0 for Timer 1)

Return value

• nil requested timer does not exist

• table timer parameters:

  • mode (number) timer trigger source: off, abs, stk, stk%, sw/!sw, !m_sw/!m_sw

Get configuration for specified Mix

@status current Introduced in 2.0.0, parameters below multiplex added in 2.0.13

Parameters

• channel (unsigned number) channel number (use 0 for CH1)

• line (unsigned number) mix number (use 0 for first line(mix))

Return value

• nil requested channel or line does not exist

• table mix data:

  • name (string) mix line name

An argument with drawing flags can be given to the various functions that draw on the LCD screen. The lower half of the flags (bits 1-16) are the flag attributes shown below, and the upper half of the flags (bits 17-32) are a color value.

Not all of the flags below should be directly manipulated from Lua, but those that are meant to be set directly by Lua, are accessible by the .

Since the flags are bits, you can add them up to combine, as long as you only add each flag one time. If you add the same flag twice, then it will add up to the next bit over, e.g. INVERS + INVERS = VCENTER. If you want to add a flag to a value where it may already be set, then use flags = bit32.bor(flags, INVERS).

RGB_FLAG decides how the color value is encoded into the upper half (bits 17-32).

If RGB_FLAG = 0, then an index into a color table is stored. This color table holds a default color (index 0), the theme colors, and CUSTOM_COLOR. The entries in the color table can be changed with the function

WARNING - Do not use Lua Custom scripts for controlling any aspect of your model that could cause a crash if the script stops executing!

Overview

Each model can have several custom scripts associated with it, and these scripts are run periodically. They behave similarly to standard OpenTX mixers, but at the same time they provide a much more flexible and powerful tool. Custom scripts take one or more values as inputs, do some processing in Lua code, and output one or more values.

Please note: the firmware must be compiled with the option LUA=YES for Custom scripts to be available.

Please note: the scripts should be as short as possible, to avoid delays. It is also important to keep in mind that other loaded Telemetry and Function scripts can add to the response time, or worse: hang the system!

Typical uses

• replacement for complex mixes that are not critical to model function

• complex processing of inputs and reaction to their current state and/or their history

• filtering of telemetry values

Limitations

• cannot update LCD screen or perform user input.

• should not exceed allowed run-time/ number of instructions.

• custom scripts are run with less priority than built-in mixes. Their execution period is around 30ms and is not guaranteed!

• can be disabled/killed anytime due to logic errors in script, not enough free memory, etc...)

Lifetime

• Custom scripts are loaded from SD card when model is selected

• init __function is called first

• run function is called periodically (about 30 times per second)

Disabled script

If the script output is used as a mixer source , and the script is killed for whatever reason, then the whole mixer line is disabled ! This can be used for example to provide a fallback in case Lua Custom script is killed.

Example where Lua mix script is used to drive ailerons in some clever way, but control falls back to the standard aileron mix if script is killed. Second mixer line replaces the first one when the script is alive:

File Location

Place them on SD card in folder /SCRIPTS/MIXES/. File name length (without extension) must be 6 characters or less (this limit was 8 characters in OpenTX 2.1).

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:

• input table (optional)

• output table (optional)

• init function (optional)

Example

Input table

The input table defines what values are available as input(s) to custom scripts. There are two forms of input table entries.

SOURCE inputs provide the current value of a selected OpenTX variable. The source must be selected by the user when the script is configured. Source can be any value that EdgeTX knows about (inputs, channels, telemetry values, switches, custom functions etc.). Note: the typical input range is -1024 thru +1024. Simply divide the input value by 10.24 to convert to a percentage from -100% to +100%.

VALUE inputs provide a constant value that is set by the user when the script is configured.

• name - maximum length of 8 characters

• min - minimum value of -128

• max - maximum value of 127

• default - must be within the valid range specified

Output table

The output table defines only name(s), as the actual values are returned by the script's run function.

Note: the above names are only visible as source values on the radio screen when the script is running. If the model is edited in Companion, then the values show as LUA1a and LUA1b etc.

Introduction

Lua was chosen for OpenTX, and hence also EdgeTX, because it is a small language designed to be highly extensible by libraries written in C and C++, so it can be integrated into other systems like EdgeTX. It is also relatively efficient, both in terms of memory and CPU usage, and hence well suited for the radios.

In addition to the provided libraries, Lua has a very elegant mechanism for loading new Lua code modules during run-time. A lot of the elegance comes from the way that the loading mechanism meshes with another concept supported by Lua: first class functions with closures.

First Class Functions

Computer science pioneer Christopher Strachey introduced the concept of functions as first-class objects in his paper F from 1967. What it means is that functions can be treated as other variables: as arguments passed in function calls, as results returned from function calls, and a function identifier can be re-assigned to another chunk of function code, just like a variable ca be assigned to a new value.

In Lua, a function declaration is really "syntactic sugar" for assigning a variable to the chunk of code that is called when the function is invoked, i.e.

local function f(x) return x + 1 end

is the same as

local f = function(x) return x + 1 end

You can even add functions to Lua tables, i.e.

t = { f = f }

will add the above function to the table t, as a field that is also called f. Does that look familiar to the return statement required at the end of a Lua script?

Yes indeed, because a script is really an anonymous function that returns a list of functions to the system. The function declarations assign variables to chunks of function code, these variables are added to the list returned at the end of the script, and the system then calls the functions periodically to run the script. So the script itself is run one time initially, and subsequently the functions returned by the last statement are called periodically.

Closures

Another important concept that goes with first-class functions, is closures. This is the environment of the function with the variable names that the function can see. Please consider the following function counter that returns another function:

The function is returned directly without being assigned to a variable name. The closure of the function returned is the body of the function counter, containing both the arguments start and step, and the local variable x. So if c1 = counter(1, 1) then c1() will return 1, 2, 3, ... when called repeatedly, and if c2 = counter(2, 3) then c2() will return 2, 5, 8, ...

Likewise, the local variables that you declare outside the functions of your script can be used by all of the functions in your script, and they persist between function calls, but they are not visible to other scripts.

The are a little trickier, as you can register multiple instances of the same widget script, and all of these instances run within the same Lua closure. Therefore, local variables declared outside any functions in a widget script are shared among all of the instances of that script. But each call to the create(...) function returns a new widget list to the system. And since this list is unique to each instance, you can add private instance variables to it.

Functions with Variable Number of Arguments

Please consider this function:

It takes an argument x and a list ... A vararg list is just like a list of arguments separated by commas, and you can call the function with any number of arguments greater than 1. Inside the function, you can also treat ... like a comma separated list of variables, e.g. in the above function, ... is converted to a table by {...} just like you could construct a table by e.g. {a, b, c}. The table is iterated with the ipairs function to look for an element matching the first argument x. So e.g. the following statement

if event == EVT_VIRTUAL_ENTER or event == EVT_VIRTUAL_EXIT then

can be replaced by

if match(event, EVT_VIRTUAL_ENTER, EVT_VIRTUAL_EXIT) then

You can also use ... directly as a comma separated list of values, e.g. local a, b, c = ... will assign the three variables to the three first arguments following x, or nil if none are given.

References

The helpful, both if you want to learn more about Lua, and if you want to search for answers to specific questions.

There are two types of color constants: one that is an index into a table holding a palette of theme colors, and one that is just a color.

Indexed colors

These are the theme colors plus CUSTOM_COLOR, and they can be changed with the function lcd.setColor(color_index, color). Please note: if an indexed color is changed, then it changes everywhere that it is used. For the theme colors, this is not only in other widgets, but everywhere throughout the radio's user interface!

• COLOR_THEME_PRIMARY1

• COLOR_THEME_PRIMARY2

• COLOR_THEME_PRIMARY3

• COLOR_THEME_SECONDARY1

• COLOR_THEME_SECONDARY2

• COLOR_THEME_SECONDARY3

• COLOR_THEME_FOCUS

• COLOR_THEME_EDIT

• COLOR_THEME_ACTIVE

• COLOR_THEME_WARNING

• COLOR_THEME_DISABLED

• CUSTOM_COLOR

Literal colors

These color constants cannot be changed:

• BLACK

• WHITE

• LIGHTWHITE

• YELLOW

Deprecated color constants

These should no longer be used, but they are included for backwards compatibility. The old OpenTX API had a large number of indexed theme colors, and these have been mapped to the new theme colors as follows:

• ALARM_COLOR -> COLOR_THEME_WARNING

• BARGRAPH_BGCOLOR -> COLOR_THEME_SECONDARY3

• BARGRAPH1_COLOR -> COLOR_THEME_SECONDARY1

• BARGRAPH2_COLOR -> COLOR_THEME_SECONDARY2

The following touch events are passed in the event argument to the widget script refresh function (when in full screen mode), just like the key events. The following touch events are provided:

In addition to the above touch events a touchState table is passed to refresh with the following addional data fields:

Notes:

• touchState is nil if event is not a touch event. This can be used to test if we have a touch event or a key event.

  • Since Lua evaluates a nil value to false and everything else to true:

Returns the value of a source.

The list of fixed sources:

In OpenTX 2.1.x the telemetry sources no longer have a predefined name. To get a telemetry value simply use it's sensor name. For example:

• Altitude sensor has a name "Alt"

• to get the current altitude use the source "Alt"

• to get the minimum altitude use the source "Alt-", to get the maximum use "Alt+"

@status current Introduced in 2.0.0, changed in 2.1.0, Cels+ and Cels- added in 2.1.9

Parameters

• source can be an identifier (number) (which was obtained by the getFieldInfo())

  or a name (string) of the source.

Return value

• value current source value (number). Zero is returned for:

  • non-existing sources

  • for all telemetry source when the telemetry stream is not received

Notice

Getting a value by its numerical identifier is faster then by its name. While Cels sensor returns current values of all cells in a table, a Cels+ or Cels- will return a single value - the maximum or minimum Cels value.

Flags

Patterns

The key event mechanism

Each time a key is pressed, held and released a number of events get generated. Here is a typical flow:

• when a key is pressed a FIRST event is generated

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. Full screen mode can be entered by selecting the widget, pressing ENTER and selecting Full screen on the widget menu, or by double tapping the widget on radios with a touch screen. Full screen mode can be exited by long pressing the RETURN button, or by calling the Lua function lcd.exitFullScreen()

Regarding memory, the situation is a bit different for the radios with black/white or grey scale screens and telemetry scripts, and the radios with color screens and widget scripts. The telemetry script radios only have 128-192 KB RAM memory - that is very small! The widget script radios have 8 MB RAM memory. But the way that widgets are designed means that all widget scripts present on the SD card will be loaded into memory, whether or not they are actually used. Therefore, different strategies should be applied to save memory for the two different types of radios and scripts.

Telemetry Script Radios

Radios with black/white or grey scale screens and telemetry scripts such as e.g. FrSky Taranis, Xlite, Jumper T12 and Radiomaster TX16 have extremely small RAM memories, and therefore it may be necessary to divide up your script into smaller loadable modules.

The two Lua widgets EventDemo and LibGUI are provided on the SD card content for color screen radios. EventDemo is just a small widget showing off how key, and especially touch events, can be used. LibGUI contains a globally available library, and a widget showing how the library can be used by other widgets. This section will discuss these two widgets for color screen radios, but generally, what is stated about key events here also applies to the run function in Telemetry and One-Time scripts.

EventDemo Widget

This widget uses the design pattern for saving memory by loadable files discussed in the so all of the action takes place in the file