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

TODO: Need to determine status of wizard in 2.2

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

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

This section includes Acknowledgments and Getting Started.

This section introduces the types of Lua scripts supported by OpenTX and how they may be used.

If defined, init function is called right after the script is loaded from SD card and begins execution. Init is called only once before the run function is called for the first time.

local function <init_function_name>()
  -- code here runs only once when the model is loaded
end

• Input Parameters:

  none

• Return values:

  none

Downloading OpenTX Companion

OpenTX Companion 2.2 is available for download at http://www.open-tx.org/downloads.html

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.

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.

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

The return statment is the last statement in an OpenTX Lua script. It defines the input/output table values and functions used to run the script.

Parameters init, input and output are optional. If a script doesn't use them, they can be omitted from return statement.

Example without init and output:

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.

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

Returns radio timers

@status current Introduced added in 2.3.0.

Parameters

none

The OpenTX team has no intention of making a profit from their work. OpenTX is free and open source and will remain free and open source. But OpenTX 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.

Another reason is that OpenTX maintains a build server that serves firmware compiled on demand. This is where OpenTX Companion orders your customized firmware. The server is not for free and the bandwidth is ever increasing with tens of thousands of firmware downloads each month.

The OpenTX team is grateful to those who have donated to the project. You have helped making OpenTX and OpenTX Companion great.

The is updated at each OpenTX release.

If you would like to contribute to OpenTX, donations are welcome and appreciated:

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

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

Generate haptic feedback

@status current Introduced in 2.2.0

Parameters

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

Get current Model information

@status current Introduced in 2.0.6, changed in 2.2.0

Parameters

none

Reset Telemetry Sensor parameters

@status current Introduced in 2.3.11

Parameters

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

Return the RAS value or nil if no valid hardware found

@status current Introduced in 2.2.0

Parameters

none

Change the working directory

@status current Introduced in 2.3.0

Parameters

• directory (string) New working directory

Delete mixer line from specified Channel

@status current Introduced in 2.0.0

Parameters

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

Set all inputs to defaults

@status current Introduced in 2.0.0

Parameters

none

Set RF module parameters

@status current Introduced in TODO

Parameters

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

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

Resets the radio global timer to 0.

@status current Introduced in 2.2.2, param added in 2.3

Parameters

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

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

@status current Introduced in 2.2.1

Parameters

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)

Set Flight mode parameters

@status current Introduced in 2.3.10

Parameters

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

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)

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.

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)

Return value

• number channel assigned to this stick (from 0 to 3)

• nil stick not found

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)

Return value

• number Stick assigned to this channel (from 0 to 3)

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

@status current Introduced in 2.2.0

Parameters

none

Return value

• rssi RSSI value (0 if no link)

• alarm_low Configured low RSSI alarm level

• alarm_crit Configured critical RSSI alarm level

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 number of lines for given input

@status current Introduced in 2.0.0

Parameters

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

Return value

• number number of configured lines for given input

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

Raises a pop-up on screen that shows a warning

@status current Introduced in 2.2.0

Parameters

• title (string) text to display

• event (number) the event variable that is passed in from the run function (key pressed)

Return value

• "CANCEL" user pushed EXIT key

Notice

Use only from stand-alone and telemetry scripts.

TODO: describe how theme scripts work on Horus type transmitters.

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

  @param (optional): value to write in the buffer

Return value

• buffer value (number)

Clear all flightModes

@status current Introduced in 2.3.10

Parameters

none

Return value

none

Set the current Model information

@status current Introduced in 2.0.6, changed in TODO

Parameters

• value model information data, see model.getInfo()

Return value

none

Notice

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

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

@status current Introduced in TODO

Parameters

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

Return value

none

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 value

• number number of mixes for requested channel

Set Logical Switch parameters

@status current Introduced in 2.0.0

Parameters

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

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

Return value

none

Notice

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

To set the and member (which is Lua keyword) use the following syntax: model.setLogicalSwitch(30, {func=4,v1=1,v2=-99, ["and"]=24})

Reads characters from the serial port. The string is allowed to contain any character, including 0. Note that the returned string may not end in a newline if this character is not present in the buffer.

@status current Introduced in 2.3.8

Parameters

• 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.

Return value

• string Empty if no new characters were available.

Set servo parameters

@status current Introduced in 2.0.0

Parameters

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

• value (table) servo parameters, see model.getOutput() for table format

Return value

none

Notice

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

Remove all mixers

@status current Introduced in 2.0.0

Parameters

none

Return value

none

Join the chat on Discord

Go to https://doc.open-tx.org/opentx-2-3-lua-reference-guide/ for the latest published version of this guide.

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

Part I of the guide shows how to enable Lua support for Taranis and includes basic examples of each types of script.

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

Part III is the OpenTX Lua API Reference

Part IV addresses common issues in converting Lua scripts that were originally written for OpenTX 2.0

Part V addresses common issues in converting Lua scripts that were originally written for OpenTX 2.1

Part VI covers advanced topics with examples

last updated on 2021/01/09 17:57:00 UTC

Telemetry Scripts

General description

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.

File Location

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

Lifetime of telemetry script

Telemetry scripts are started when the model is loaded.

• script init function is called

• script background function is periodically called when custom telemetry screen is not visible. Notice:

  • In OpenTX 2.0 this function is not called when the custom telemetry screen is visible.

Script interface definition

Every script must include a return statement at the end, that defines its interface to the rest of OpenTX code. This statement defines:

• script init function (optional)

• script background function

• script run function

Example (interface only):

Notes:

• init_func() function is called once when script is loaded and begins execution.

• bg_func() is called periodically, the screen visibility does not matter.

• run_func(event) function is called periodically when custom telemetry screen is visible. The event

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

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

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

Return rotary encoder current speed

@status current Introduced in 2.3.10

Parameters

none

Return value

• number in list: ROTENC_LOWSPEED, ROTENC_MIDSPEED, ROTENC_HIGHSPEED

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 (unsigned number) input number (use 0 for Input1)

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

Return value

• nil requested input or line does not exist

• table input data:

  • name (string) input line name

@status current Introduced in 2.2.0

Parameters

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

• subID subID of the sensor, usually 0, valid range is from 0 to 7

• instance instance of the sensor (SensorID), valid range is from 0 to 0xFF

• value fed to the sensor

• unit unit of the sensor

• precision the precision of the sensor

  • 0 or not present no decimal precision.

  • != 0 value is divided by 10^precision, e.g. value=1000, prec=2 => 10.00.

• name (string) Name of the sensor if it does not yet exist (4 chars).

  • not present Name defaults to the Id.

  • present Sensor takes name of the argument. Argument must have name surrounded by quotes: e.g., "Name"

Return value

• true, if the sensor was just added. In this case the value is ignored (subsequent call will set the value)

Notice

All three parameters id, subID and instance can't be zero at the same time. At least one of them must be different from zero.

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

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

The run function is the function that is periodically called for the lifetime of script execution. Syntax of the run function is different between mix scripts and telemetry scripts.

Run Function for Mix Scripts

• Input parameters:

  zero or more input values, their names are arbitrary, their meaning and order is defined by the input table. (see )

• Return values:

  • none - if output table is empty (i.e. script has no output)

    values

    • or -

Run Function for Telemetry Scripts

• Input parameters:

  The key-event parameter indicates which transmitter button has been pressed (see )

• Return values:

  A non-zero return value will halt the script

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

Get Logical Switch parameters

@status current Introduced in 2.0.0

Parameters

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

Return value

• nil requested logical switch does not exist

• table logical switch data:

  • func (number) function index

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)

Overview

Outputs are only used in mix scripts. The output table defines only name(s), the actual values are determined by the script's .

Example:

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)

Get RF module parameters

Type values:

• 0 NONE

• 1 PPM

Raises a pop-up on screen that allows uses input

@status current Introduced in 2.0.0

Parameters

• title (string) text to display

Return OpenTX version

@status current Introduced in 2.0.0, expanded in 2.1.7, radio type strings changed in 2.2.0

Example

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

Output of the above script in simulator:

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)

Return current global variable value

Example:

Parameters

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

Insert a mixer line into Channel

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

Parameters

• channel

Delete line from specified input

@status current Introduced in 2.0.0

Parameters

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

Get Telemetry Sensor parameters

@status current Introduced in 2.3.0

Parameters

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

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)

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

Sets current global variable value. See also model.getGlobalVariable()

Parameters

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

Delete all Inputs

@status current Introduced in 2.0.0

Parameters

none

Get servo parameters

@status current Introduced in 2.0.0

Parameters

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

Set 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 flight mode data.

@status current Introduced in 2.1.7

Parameters

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

  is not specified (or contains invalid value), then the current flight mode data is returned.

Return value

• multiple returns 2 values:

  • (number) (current) flight mode number (0 - 8)

  • (string) (current) flight mode name

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.

Overview

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

• SOURCE syntax

  Copy

  { "<name>", SOURCE }

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

• VALUE syntax

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

  • name - maximum length of 8 characters

  • min - minimum value of -128
• Maximum of 6 inputs per script (warning : was 8 in 2.1)

Example using a SOURCE and a VALUE

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

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()).

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 value

• nil requested input or line does not exist

• table input data:

  • name (string) input line name

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

Description

Each model can have several mix scripts associated with it. These scripts are run periodically for entire time that model is selected. These scripts behave similar to standard OpenTX mixers but at the same time provide much more flexible and powerful tool.

Mix scripts take one or more values as inputs, do some calculation or logic processing based on them and output one or more values. Each run of a script should be as short as possible. Exceeding the script execution runtime limit will result in the script being forcefully stopped and disabled.

This page describes the value that is passed to scripts in the event parameter. It is used in Telemetry and One-Time scripts.

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

• if the key continues to be pressed, then after a while a LONG event is generated

• if the key continues to be pressed, then a REPEAT events are being generated

• when the key is released a BREAK event is generated

Couple of examples:

• a short press on key would generate: FIRST, BREAK

• a longer pres on key would generate: FIRST, LONG, BREAK

This normal key event sequence can be altered with the function. Any time this function is called (after the FIRST event) all further key events for this key will be suppressed until the next key press of this key. Examples:

• kill immediately after the key press would generate: FIRST

• kill after the long key press would generate: FIRST, LONG

Constants

The event parameter in the and scripts run function actually carries two pieces of information:

• key number

• type of event

The two fields are combined into one single number. Some of these combinations are defined as constants and are available to Lua scripts:

Radios with rotary encoder (X7 and Horus) have also:

Virtual events

Given the large number of radios supported by OpenTX, and the large difference in keys available on those, a set of VIRTUAL KEYS has been defined and are mapped to best fit available hardware

General description

Widgets are small scripts that show some info in a 'zone' in one of the model specific user defined (telemetry) screens. You can define those screens within the telemetry menu on the HORUS.

Each model can have up to five custom screens, with up to 8 widgets per screen, depending on their size and layout. Each instance of a widget has his own custom settings.

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).

Lifetime of widgets

Widgets need to be registered through the telemetry setup menu.

• widget create function is called

• widget update function is called upon registration and at change of settings in the telemetry setup menu.

• widget background function is periodically called when custom telemetry screen is not visible. Notice:

Once registered, widgets are started when the model is loaded.

Script interface definition

Every widget must include a return statement at the end, that defines its interface to the rest of OpenTX code. This statement defines:

• widget name (name must be a string of 10 characters or less)

• widget options array (maximum five options are allowed, 10 character names max, no spaces!)

• widget create function

Example (draws a moving counter that counts only when not visible):

Notes:

• options are only passed through to OpenTX to be used on widget creation. Don't change them during operation, this has no effect.

• create() function is called once when widget is loaded and begins execution.

• update() function is called once when widget is loaded and begins execution.

Overview

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