# OpenTX 2.3 Lua Reference Guide [Join the chat on Discord](https://discord.gg/CZCwVx2) Go to 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 # Introduction This section includes Acknowledgments and Getting Started. # Acknowledgments 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 [Github Donor List](https://github.com/opentx/opentx/blob/master/DONATIONS.txt) is updated at each OpenTX release. If you would like to contribute to OpenTX, donations are welcome and appreciated: [![](https://github.com/opentx/lua-reference-guide/tree/89b65e383782af902c0528c648021268417248da/btn_donate_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\&hosted_button_id=DJ9MASSKVW8WN) # Getting Started ## Downloading OpenTX Companion OpenTX Companion 2.2 is available for download at ## 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. ![Edit Settings dialog from OpenTX Companion](https://github.com/opentx/opentx-2-3-lua-reference-guide/tree/0d355d19f1961b689994cf78b84005864d33f9b5/companion-settings.png) # Part I - Script Type Overview This section introduces the types of Lua scripts supported by OpenTX and how they may be used. # Mix Scripts ***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. ## 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. * mix 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...) ## 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). ## Lifetime * script is loaded from SD card when model is selected * script *init* function is called * script *run* function is periodically called (inside GUI thread, period cca 30ms) * script is killed (stopped and disabled) if it misbehaves (too long runtime, error in code, low memory) * all mix scripts are stopped while one-time script is running (see Lua One-time scripts) ### Disabled script If as script output is used as a `mixer source` and the script is killed for what ever reason, then `the whole mixer line is disabled`! This can be used for example to provide a fall-back in case Lua mixer script gets 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: ``` CH1 [I4]Ail Weight(+100%) := LUA4b Weight(+100%) ``` ## 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 *input* table (optional, see [Input Table Syntax](/opentx_2.3/part_ii_-_opentx_lua_api_programming_guide/input_table_syntax)) * script *output* table (optional, see [Output Table Syntax](https://github.com/opentx/opentx-2-3-lua-reference-guide/tree/0d355d19f1961b689994cf78b84005864d33f9b5/output_table_syntax.md)) * script *init* function (optional, see [Init Function Syntax](https://github.com/opentx/opentx-2-3-lua-reference-guide/tree/0d355d19f1961b689994cf78b84005864d33f9b5/init_function_syntax.md)) * script *run* function (see [Run Function Syntax](https://github.com/opentx/opentx-2-3-lua-reference-guide/tree/0d355d19f1961b689994cf78b84005864d33f9b5/run_function_syntax.md)) ### Example (interface only): ```lua local input {} local output {} local function init_func() end local function run_func() end return { input=input, output=output, run=run_func, init=init_func } ``` ### Notes: * inputs table defines input parameters (name and source) to run function ([see Input Table Syntax](/opentx_2.3/part_ii_-_opentx_lua_api_programming_guide/input_table_syntax)) * outputs table defines names for values returned by run function (see [Output Table Syntax](https://github.com/opentx/opentx-2-3-lua-reference-guide/tree/0d355d19f1961b689994cf78b84005864d33f9b5/output_table_syntax.md)) * init\_func() function is called once when script is loaded. * run\_func() function is called periodically # Telemetry Scripts ## 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. * Starting from OpenTX 2.1 this function is **always called** no matter if the custom screen is visible or not. * script run function is periodically called when custom telemetry screen is **visible** * script is stopped and disabled if it misbehaves (too long runtime, error in code, low memory) * all telemetry scripts are stopped while one-time script is running (see Lua One-time scripts) ## 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): ```lua local function init_func() -- init_func is called once when model is loaded end local function bg_func() -- bg_func is called periodically (always, the screen visibility does not matter) end local function run_func(event) -- run_func is called periodically only when screen is visible end return { run=run_func, background=bg_func, init=init_func } ``` ### 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` parameter indicates which transmitter button has been pressed (see [Key Events](/opentx_2.3/part_iii_-_opentx_lua_api_reference/constants/key_events)). This is the time when the script has full control of the LCD screen and keys and should draw something on the screen. # One-Time Scripts ## 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. ## ***WARNING! -*** * Running a One-Time script will suspend execution of all other currently loaded Lua scripts (Mix, Telemetry, and Functions) ## File Location Place them anywhere on SD card, the folder /SCRIPTS/ is recommended. The only exception is official model wizard script, that should be put into /SCRIPTS/WIZARD/ folder that way it will start automatically when new model is created. ## Lifetime of One-Time scripts Script is executed when user selects Execute on a script file from SD card browser screen. Script executes until: * it returns value different from 0 * is forcefully closed by user by long press of EXIT key * is forcefully closed by system if if it misbehaves (too long runtime, error in code, low memory) # Wizard Script TODO: Need to determine status of wizard in 2.2 # Function Scripts ## Overview Function scripts are invoked via the **'Lua Script'** option of Special Functions configuration page. ![Companion Special Functions Window](https://github.com/opentx/opentx-2-3-lua-reference-guide/tree/0d355d19f1961b689994cf78b84005864d33f9b5/CompanionSpecialFunctions.png) ![Taranis Special Functions Display](https://github.com/opentx/opentx-2-3-lua-reference-guide/tree/0d355d19f1961b689994cf78b84005864d33f9b5/RadioSpecialFunctions.png) ## Typical uses * specialized handling in response to switch position changes * customized announcements ## Limitations * should not exceed allowed run-time/ number of instructions. * all function scripts are stopped while one-time script is running (see Lua One-time scripts) * Function scripts **DO NOT HAVE ACCESS TO LCD DISPLAY** ## Location Place them on SD card in folder /SCRIPTS/FUNCTIONS/ ## Lifetime * script *init* function is called once when model is loaded * script *run* function is periodically called as long as switch condition is true * script is stopped and disabled if it misbehaves (too long runtime, error in code, low memory) ## 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, see [Init Function Syntax](https://github.com/opentx/opentx-2-3-lua-reference-guide/tree/0d355d19f1961b689994cf78b84005864d33f9b5/init_function_syntax.md)) * script *run* function (see [Run Function Syntax](https://github.com/opentx/opentx-2-3-lua-reference-guide/tree/0d355d19f1961b689994cf78b84005864d33f9b5/run_function_syntax.md)) ## Example (interface only): ```lua local function init_func() end local function run_func() end return { run=run_func, init=init_func } ``` ## Notes: * local variables retain their values for as long as the model is loaded regardless of switch condition value ## Advanced example (save as /SCRIPTS/FUNCTIONS/cntdwn.lua) The script below is an example of customized countdown announcements. Note that the init function determines which version of OpenTX is running and sets the unit parameter for playNumber() accordingly. ```lua local lstannounce local target local running = false local duration = 120 -- two minute countdown local announcements = { 120, 105, 90, 75, 60, 55, 50, 45, 40, 35, 30, 29, 28, 27, 26, 25, 24, 23, 22, 21, 20, 19, 18, 17, 16, 15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0} local annIndex local minUnit local function init() local version = getVersion() if version < "2.1" then minUnit = 16 -- unit for minutes in OpenTX 2.0 elseif version < "2.2" then minUnit = 23 -- unit for minutes in OpenTX 2.1 else minUnit = 25 -- unit for minutes in OpenTX 2.2 end end local function run() local timenow = getTime() -- 10ms tick count local remaining local minutes local seconds if not running then running = true target = timenow + (duration * 100) annIndex = 1 end remaining = math.floor(((target - timenow) / 100) + .7) -- +.7 adjust for announcement lag if remaining < 0 then running = false -- we were 'paused' and missed zero return end while remaining < announcements[annIndex] do annIndex = annIndex + 1 -- catch up in case we were paused end if remaining == announcements[annIndex] then minutes = math.floor(remaining / 60) seconds = remaining % 60 if minutes > 0 then playNumber(minutes, minUnit, 0) end if seconds > 0 then playNumber(seconds, 0, 0) end annIndex = annIndex + 1 end if remaining <= 0 then playNumber(0,0,0) running = false end end return { init=init, run=run } ``` # Widget Scripts ## 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*: * This is different from the way telemetry scripts are handled * widget refresh function is periodically called when custom telemetry screen is **visible** * widget is stopped and disabled if it misbehaves (too long runtime, error in code, low memory) * all widgets are stopped while one-time script is running (see Lua One-time scripts) 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 * widget **update** function * script **background** function * script **refresh** function ### Example (draws a moving counter that counts only when not visible): ```lua local defaultOptions = { { "ControlX", SOURCE, 1 }, { "ScrollZ", BOOL, 1 }, -- BOOL is actually not a boolean, but toggles between 0 and 1 { "StepZ", VALUE, 1, 0, 10}, { "COLOR", COLOR, RED }, } local function createWidget(zone, options) lcd.setColor( CUSTOM_COLOR, options.COLOR ) -- the CUSTOM_COLOR is foreseen to have one color that is not radio template related, but it can be used by other widgets as well! local someVariable = 0 local anotherVariable = {xWidget=0, yWidget = 0} return { zone=zone, options=options , someVariable = someVariable, anotherVariable=anotherVariable } end local function updateWidget(widgetToUpdate, newOptions) widgetToUpdate.options = newOptions lcd.setColor( CUSTOM_COLOR, widgetToUpdate.options.COLOR ) -- the CUSTOM_COLOR is foreseen to have one color that is not radio template related, but it can be used by other widgets as well! end local function backgroundProcessWidget(widgetToProcessInBackground) local function process(...) return ... + 1 end widgetToProcessInBackground.someVariable = process (widgetToProcessInBackground.someVariable) end local function refreshWidget(widgetToRefresh) local counterLength = 50 local counterHeight = 30 --backgroundProcessWidget(widgetToRefresh) --background is not called automatically in display mode, so do it here if you need it. local function anotherProcess(parameter,step,maxParameter) return (parameter + step) % maxParameter end widgetToRefresh.anotherVariable.xWidget = anotherProcess ( widgetToRefresh.anotherVariable.xWidget ,getValue(widgetToRefresh.options.ControlX)/10.24/20 ,widgetToRefresh.zone.w-counterLength) widgetToRefresh.anotherVariable.yWidget = anotherProcess ( widgetToRefresh.anotherVariable.yWidget ,(widgetToRefresh.options.ScrollZ==1) and widgetToRefresh.options.StepZ or 0 ,widgetToRefresh.zone.h-counterHeight) lcd.drawNumber(widgetToRefresh.anotherVariable.xWidget + widgetToRefresh.zone.x , widgetToRefresh.anotherVariable.yWidget + widgetToRefresh.zone.y , widgetToRefresh.someVariable , LEFT + DBLSIZE + CUSTOM_COLOR); end return { name="MovingCntr", options=defaultOptions, create=createWidget, update=updateWidget , refresh=refreshWidget, background=backgroundProcessWidget } ``` ## 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. * *background()* is called periodically when custom telemetry screen containing widget is not visible. * *refresh()* function is called periodically when custom telemetry screen containing wodget is visible. * in the example given, you can see that no global variables or functions are needed to operate the widget. * variables that are used throughout the widget, can best be declared *inside* the create function as local variables * those local variablkes can then be passed through to the other functions as an element of the widget array that is returned # Theme Scripts TODO: describe how theme scripts work on Horus type transmitters. # Part II - OpenTX Lua API Programming Guide This section provides more specifics on the OpenTX Lua implementation. Here you will find syntax rules for interface tables and functions. # Input Table Syntax ## Overview The input table defines what values are available as input(s) to [mix scripts](/opentx_2.3/part_i_-_script_type_overview/mix). There are two forms of input table entries. * **SOURCE syntax** ```lua { "", 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** ```lua { "", VALUE, , , } ``` 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 * *max* - maximum value of 127 * *default* - must be within the valid range specified * **Maximum of 6 inputs per script (warning : was 8 in 2.1)** ## Example using a SOURCE and a VALUE ```lua local input = { { "Strength", SOURCE}, -- user selects source (typically slider or knob) { "Interval", VALUE, 0, 100, 0 } -- interval value, default = 0. } local function run(strength, interval) -- variable strength will contain the current slider value -- variable interval is set by the user and constant through script lifetime -- this script has no return value but may use playFile() to alert user return end return {input=input, run=run} ``` # Output Table Syntax ## Overview Outputs are only used in mix scripts. The output table defines only name(s), the actual values are determined by the script's [run function](/opentx_2.3/part_ii_-_opentx_lua_api_programming_guide/run_function_syntax). ```lua { "", "" } ``` Example: ```lua local output { "Val1", "Val2" } local function run() return 0, -1024 -- these values will be available in OpenTX as Val1 and Val2 end return {output=output, run=run} ``` ## Notes: * Output name is limited to four characters. * A maximum of 6 outputs are supported * Number Format Outputs are 16 bit signed integers when they leave Lua script and are then divided by 10.24 to produce output value in percent: | Script Return Value | Mix Value in OpenTX | | ------------------- | ------------------- | | 0 | 0% | | 996 | 97.2% | | 1024 | 100% | | -1024 | -100% | # Init Function Syntax 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. ```lua local function () -- code here runs only once when the model is loaded end ``` * **Input Parameters:** none * **Return values:** none # Run Function Syntax 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](/opentx_2.3/part_i_-_script_type_overview/mix) and [telemetry scripts](/opentx_2.3/part_i_-_script_type_overview/telemetry). ## Run Function for Mix Scripts ```lua local function ([first input, [second input], …]) -- if mix has no return values return -- if mix has two return values return value1, value2 end ``` * **Input parameters:** zero or more input values, their names are arbitrary, their meaning and order is defined by the input table. (see [Input Table Syntax](/opentx_2.3/part_ii_-_opentx_lua_api_programming_guide/input_table_syntax)) * **Return values:** * none - if output table is empty (i.e. script has no output) values * or - * comma separated list of output values, their order and meaning is defined by the output table. (see [Output Table Syntax](/opentx_2.3/part_ii_-_opentx_lua_api_programming_guide/output_table_syntax)) ## Run Function for Telemetry Scripts ```lua local function (key-event) return 0 -- values other than zero will halt the script end ``` * **Input parameters:** The *key-event* parameter indicates which transmitter button has been pressed (see [Key Events](/opentx_2.3/part_iii_-_opentx_lua_api_reference/constants/key_events)) * **Return values:** A non-zero return value will halt the script # Return Statement Syntax 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*: ```lua local inputs = { { "Aileron", SOURCE }, { "Ail. ratio", VALUE, -100, 100, 0 } } local function run_func(ail, ratio) -- do some stuff if (ail > 50) and ( ratio < 40) then playFile("foo.wav") end end -- script that only uses input and run return { run=run_func, input=inputs } ``` # Included Lua Libraries | Lua Standard Libraries | Included | | ----------------------------------------------------------------------------------------------------------- | ------------------------------------- | | package | - | | coroutine | - | | table | - | | [io](https://github.com/opentx/lua-reference-guide/tree/89b65e383782af902c0528c648021268417248da/lib/io.md) | since OpenTX 2.1.0 (with limitations) | | os | - | | string | since OpenTX 2.1.7 | | bit32 | since OpenTX 2.1.0 | | math | since OpenTX 2.0.0 | | debug | - | # io Library # io.open() # io.close() # io.read() # io.write() # io.seek() # Part III - OpenTX Lua API Reference This section describes the Lua libraries, functions and constants that are provided by OpenTX. # Constants # Key Event Constants This page describes the value that is passed to scripts in the `event` parameter. It is used in [Telemetry](/opentx_2.3/part_i_-_script_type_overview/telemetry) and [One-Time](https://github.com/opentx/opentx-2-3-lua-reference-guide/tree/0d355d19f1961b689994cf78b84005864d33f9b5/one-time_scripts.md) 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` * even longer press: `FIRST`, `LONG`, `REPEAT,`REPEAT, ..., `BREAK` This normal key event sequence can be altered with the [killEvents(key)](/opentx_2.3/part_iii_-_opentx_lua_api_reference/general-functions-less-than-greater-than-luadoc-begin-general/killevents) 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 [Telemetry](/opentx_2.3/part_i_-_script_type_overview/telemetry) and [One-Time](https://github.com/opentx/opentx-2-3-lua-reference-guide/tree/0d355d19f1961b689994cf78b84005864d33f9b5/one-time_scripts.md) 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: | Key Event Name | Comments | | :---------------: | :---------------------: | | EVT\_MENU\_BREAK | **MENU** key release | | EVT\_PAGE\_BREAK | **PAGE** key release | | EVT\_PAGE\_LONG | **MENU** key long press | | EVT\_ENTER\_BREAK | **ENT** key release | | EVT\_ENTER\_LONG | **ENT** key long press | | EVT\_EXIT\_BREAK | **EXIT** key release | | EVT\_PLUS\_BREAK | **+** key release | | EVT\_MINUS\_BREAK | **-** key release | | EVT\_PLUS\_FIRST | **+** key press | | EVT\_MINUS\_FIRST | **-** key press | | EVT\_PLUS\_REPT | **+** key repeat | | EVT\_MINUS\_REPT | **-** key repeat | Radios with rotary encoder (X7 and Horus) have also: | Key Event Name | Comments | | :-------------: | :--------------------------: | | EVT\_ROT\_BREAK | rotary encoder release | | EVT\_ROT\_LONG | rotary encoder long press | | EVT\_ROT\_LEFT | rotary encoder rotated left | | EVT\_ROT\_RIGHT | rotary encoder rotated right | ## 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 | Virtual Key Event Name | Comments | | :--------------------------: | :-------------------: | | EVT\_VIRTUAL\_NEXT\_PAGE | for PAGE navigation | | EVT\_VIRTUAL\_PREVIOUS\_PAGE | for PAGE navigation | | EVT\_VIRTUAL\_ENTER | | | EVT\_VIRTUAL\_ENTER\_LONG | | | EVT\_VIRTUAL\_MENU | | | EVT\_VIRTUAL\_MENU\_LONG | | | EVT\_VIRTUAL\_NEXT | for FIELDS navigation | | EVT\_VIRTUAL\_NEXT\_REPT | for FIELDS navigation | | EVT\_VIRTUAL\_PREVIOUS | for FIELDS navigation | | EVT\_VIRTUAL\_PREV\_REPT | for FIELDS navigation | | EVT\_VIRTUAL\_INC | for VALUES navigation | | EVT\_VIRTUAL\_INC\_REPT | for VALUES navigation | | EVT\_VIRTUAL\_DEC | for VALUES navigation | | EVT\_VIRTUAL\_DEC\_REPT | for VALUES navigation | # General Functions \[//]: <> (LUADOC-BEGIN:general) # GREY() 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 # accessTelemetryPush() 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 * `module` module index (0 = internal, 1 = external) * `rxUid` receiver index * `sensorId` physical sensor ID * `frameId` frame ID * `dataId` data ID * `value` value ## Return value * `boolean` data queued in output buffer or not. # chdir(directory) Change the working directory @status current Introduced in 2.3.0 ## Parameters * `directory` (string) New working directory ## Return value none # crossfireTelemetryPop() 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) * packet (table) data bytes # crossfireTelemetryPush() 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. # defaultChannel(stick) 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 # defaultStick(channel) 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) # getDateTime() 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 * `day` (number) day of month * `hour` (number) hours * `hour12` (number) hours in US format * `min` (number) minutes * `sec` (number) seconds * `suffix` (text) am or pm # getFieldInfo(name) Return detailed information about field (source) The list of valid sources is available: | OpenTX Version | Radio | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 2.0 | [all](http://downloads-20.open-tx.org/firmware/lua_fields.txt) | | 2.1 | [X9D and X9D+](http://downloads-21.open-tx.org/firmware/lua_fields_taranis.txt), [X9E](http://downloads-21.open-tx.org/firmware/lua_fields_taranis_x9e.txt) | | 2.2 | [X9D and X9D+](http://downloads.open-tx.org/2.2/release/firmware/lua_fields_x9d.txt), [X9E](http://downloads.open-tx.org/2.2/release/firmware/lua_fields_x9e.txt), [Horus](http://downloads.open-tx.org/2.2/release/firmware/lua_fields_x12s.txt) | | 2.3 | [X9D and X9D+](http://downloads.open-tx.org/2.3/release/firmware/lua_fields_x9d.txt), [X9E](http://downloads.open-tx.org/2.3/release/firmware/lua_fields_x9e.txt), [X7](http://downloads.open-tx.org/2.3/release/firmware/lua_fields_x7.txt), [Horus](http://downloads.open-tx.org/2.3/release/firmware/lua_fields_x12s.txt) | @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 * `desc` (string) field description * 'unit' (number) unit identifier [Full list](https://github.com/opentx/opentx-2-3-lua-reference-guide/tree/0d355d19f1961b689994cf78b84005864d33f9b5/appendix/units.html) * `nil` the requested field was not found # getFlightMode(mode) 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 # getGeneralSettings() 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 * `battMax` (number) radio battery range - maximum value * `imperial` (number) set to a value different from 0 if the radio is set to the IMPERIAL units * `language` (string) radio language (used for menus) * `voice` (string) voice language (used for speech) * `gtimer` (number) radio global timer in seconds (does not include current session) # getGlobalTimer() 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 * `ttimer` (number) radio throttle timer in seconds * `tptimer` (number) radio throttle percent timer in seconds # getRAS() 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 # getRSSI() 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 # getRotEncSpeed() 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 0 on radio without rotary encoder ``` # getRtcTime() 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 ## Return value * `number` Number of seconds elapsed since 1. Jan 1970 # getTime() 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 # getTxGPS() 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 * 'numsat' (number) current number of sats locked in by the GPS sensor * 'fix' (boolean) fix status * 'alt' (number) internal GPS altitude in 0.1m * 'speed' (number) internal GPSspeed in 0.1m/s * 'heading' (number) internal GPS ground course estimation in degrees \* 10 * 'hdop' (number) internal GPS horizontal dilution of precision # getUsage() 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) # getValue(source) Returns the value of a source. The list of fixed sources: | OpenTX Version | Radio | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 2.0 | [all](http://downloads-20.open-tx.org/firmware/lua_fields.txt) | | 2.1 | [X9D and X9D+](http://downloads-21.open-tx.org/firmware/lua_fields_taranis.txt), [X9E](http://downloads-21.open-tx.org/firmware/lua_fields_taranis_x9e.txt) | | 2.2 | [X9D and X9D+](http://downloads.open-tx.org/2.2/release/firmware/lua_fields_x9d.txt), [X9E](http://downloads.open-tx.org/2.2/release/firmware/lua_fields_x9e.txt), [Horus](http://downloads.open-tx.org/2.2/release/firmware/lua_fields_x12s.txt) | | 2.3 | [X9D and X9D+](http://downloads.open-tx.org/2.3/release/firmware/lua_fields_x9d.txt), [X9E](http://downloads.open-tx.org/2.3/release/firmware/lua_fields_x9e.txt), [X7](http://downloads.open-tx.org/2.3/release/firmware/lua_fields_x7.txt), [Horus](http://downloads.open-tx.org/2.3/release/firmware/lua_fields_x12s.txt) | 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 * far all non allowed sensors while FAI MODE is active * `table` GPS position is returned in a table: * `lat` (number) latitude, positive is North * `lon` (number) longitude, positive is East * `pilot-lat` (number) pilot latitude, positive is North * `pilot-lon` (number) pilot longitude, positive is East * `table` GPS date/time, see getDateTime() * `table` Cells are returned in a table (except where no cells were detected in which case the returned value is 0): * table has one item for each detected cell: * key (number) cell number (1 to number of cells) * value (number) current cell voltage ### 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. # getVersion() 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: ```lua local function run(event) local ver, radio, maj, minor, rev = 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 return 1 end return { run=run } ``` Output of the above script in simulator: ``` version: 2.1.7 radio: taranis-simu maj: 2 minor: 1 rev: 7 ``` ### Parameters none ### Return value * `string` OpenTX version (ie "2.1.5") * `multiple` (available since 2.1.7) returns 5 values: * (string) OpenTX version (ie "2.1.5") * (string) radio type: `x12s`, `x10`, `x9e`, `x9d+`, `x9d` or `x7`. If running in simulator the "-simu" is added * (number) major version (ie 2 if version 2.1.5) * (number) minor version (ie 1 if version 2.1.5) * (number) revision number (ie 5 if version 2.1.5) # killEvents(key) Stops key state machine. See [Key Events](/opentx_2.3/part_iii_-_opentx_lua_api_reference/constants/key_events) 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 value none # loadScript(file \[, mode], \[,env]) Load a Lua script file. This is similar to Lua's own [loadfile()](https://www.lua.org/manual/5.2/manual.html#pdf-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 ```lua fun, err = loadScript("/SCRIPTS/FUNCTIONS/print.lua") if (fun ~= nil) then fun("Hello from loadScript()") else print(err) end ``` ### 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: * `b` only binary. * `t` only text. * `T` (default on simulator) prefer text but load binary if that is the only version available. * `bt` (default on radio) either binary or text, whichever is newer (binary preferred when timestamps are equal). * Add `x` to avoid automatic compilation of source file to .luac version. Eg: "tx", "bx", or "btx". * Add `c` to force compilation of source file to .luac version (even if existing version is newer than source file). Eg: "tc" or "btc" (forces "t", overrides "x"). * Add `d` to keep extra debug info in the compiled binary. Eg: "td", "btd", or "tcd" (no effect with just "b" or with "x"). * `env` (integer) See documentation for Lua function loadfile(). ### 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()). # multiBuffer(address\[,value]) 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) # playDuration(duration \[, hourFormat]) 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. * `hourFormat` (number): * `0 or not present` play format: minutes and seconds. * `!= 0` play format: hours, minutes and seconds. ## Return value none # playFile(name) 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 # playHaptic(duration, pause \[, flags]) Generate haptic feedback @status current Introduced in 2.2.0 ## Parameters * `duration` (number) length of the haptic feedback in milliseconds * `pause` (number) length of the silence after haptic feedback in milliseconds * `flags` (number): * `0 or not present` play with normal priority * `PLAY_NOW` play immediately ## Return value none # playNumber(value, unit \[, attributes]) 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) * `PREC2` plays a number with two decimal places (for a number 123 it plays 1.23) ## Return value none # playTone(frequency, duration, pause \[, flags \[, freqIncr]]) 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) * `PLAY_NOW` play immediately * `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 # popupInput(title, event, input, min, max) Raises a pop-up on screen that allows uses input @status current Introduced in 2.0.0 ## Parameters * `title` (string) text to display * `event` (number) the event variable that is passed in from the run function (key pressed) * `input` (number) value that can be adjusted by the +/­- keys * `min` (number) min value that input can reach (by pressing the -­ key) * `max` (number) max value that input can reach ## Return value * `number` result of the input adjustment * `"OK"` user pushed ENT key * `"CANCEL"` user pushed EXIT key ### Notice Use only from stand-alone and telemetry scripts. # popupWarning(title, event) 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. # resetGlobalTimer(\[type]) 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. if set to 'session', radio session timer is reset too if set to 'ttimer', radio throttle timer is reset too if set to 'tptimer', radio throttle percent timer is reset too ## Return value none # serialRead(\[num]) 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. # serialWrite(str) 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 # setTelemetryValue(id, subID, instance, value \[, unit \[, precision \[, 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 [Full list](https://github.com/opentx/opentx-2-3-lua-reference-guide/tree/0d355d19f1961b689994cf78b84005864d33f9b5/appendix/units.html) * `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. # sportTelemetryPop() 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) * frame ID (number) * data ID (number) * value (number) # sportTelemetryPush() 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 * `sensorId` physical sensor ID * `frameId` frame ID * `dataId` data ID * `value` value ## Return value * `boolean` data queued in output buffer or not. * `nil` incorrect telemetry protocol. # Model Functions \[//]: <> (LUADOC-BEGIN:model) # model.defaultInputs() Set all inputs to defaults @status current Introduced in 2.0.0 ## Parameters none ## Return value none # model.deleteFlightModes() Clear all flightModes @status current Introduced in 2.3.10 ## Parameters none ## Return value none # model.deleteInput(input, line) Delete line from specified input @status current Introduced in 2.0.0 ## Parameters * `input` (unsigned number) input number (use 0 for Input1) * `line` (unsigned number) input line (use 0 for first line) ## Return value none # model.deleteInputs() Delete all Inputs @status current Introduced in 2.0.0 ## Parameters none ## Return value none # model.deleteMix(channel, line) Delete mixer line from specified Channel @status current Introduced in 2.0.0 ## Parameters * `channel` (unsigned number) channel number (use 0 for CH1) * `line` (unsigned number) mix number (use 0 for first line(mix)) ## Return value none # model.deleteMixes() Remove all mixers @status current Introduced in 2.0.0 ## Parameters none ## Return value none # model.getCurve(curve) 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 * `type` (number) type * `smooth` (boolean) smooth * `points` (number) number of points * `y` (table) table of Y values: * `key` is point number (zero based) * `value` is y value * `x` (table) **only included for custom curve type**: * `key` is point number (zero based) * `value` is x value # model.getCustomFunction(function) 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) ## Return value * `nil` requested custom function does not exist * `table` custom function data: * `switch` (number) switch index * `func` (number) function index * `name` (string) Name of track to play (only returned only returned if action is play track, sound or script) * `value` (number) value (only returned only returned if action is **not** play track, sound or script) * `mode` (number) mode (only returned only returned if action is **not** play track, sound or script) * `param` (number) parameter (only returned only returned if action is **not** play track, sound or script) * `active` (number) 0 = disabled, 1 = enabled # model.getFlightMode(index) 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 * `switch` (number) input switch index * `fadeIn` (number) fade in value (in 0.1s) * `fadeOut` (number) fade out value (in 0.1s) * `trimsValues` (table) table of trim values: * `key` is trim number (zero based) * `value` is trim value * `trimsModes` (table) table of trim mode: * `key` is trim number (zero based) * `value` is trim mode # model.getGlobalVariable(index, flight\_mode) Return current global variable value Example: ```lua -- 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 # model.getInfo() Get current Model information @status current Introduced in 2.0.6, changed in 2.2.0 ## Parameters none ## Return value * `table` model information: * `name` (string) model name * `bitmap` (string) bitmap name (not present on X7) # model.getInput(input, line) 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 * `inputName` (string) input input name * `source` (number) input source index * `weight` (number) input weight * `offset` (number) input offset * `switch` (number) input switch index * `curveType` (number) curve type (function, expo, custom curve) * `curveValue` (number) curve index * `carryTrim` (boolean) input trims applied * 'flightModes' (number) bit-mask of active flight modes # model.getInputsCount(input) 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 # model.getLogicalSwitch(switch) 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 * `v1` (number) V1 value (index) * `v2` (number) V2 value (index or value) * `v3` (number) V3 value (index or value) * `and` (number) AND switch index * `delay` (number) delay (time in 1/10 s) * `duration` (number) duration (time in 1/10 s) # model.getMix(channel, line) 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 * `source` (number) source index * `weight` (number) weight (1024 == 100%) value or GVAR1..9 = 4096..4011, -GVAR1..9 = 4095..4087 * `offset` (number) offset value or GVAR1..9 = 4096..4011, -GVAR1..9 = 4095..4087 * `switch` (number) switch index * `multiplex` (number) multiplex (0 = ADD, 1 = MULTIPLY, 2 = REPLACE) * `curveType` (number) curve type (function, expo, custom curve) * `curveValue` (number) curve index * `flightModes` (number) bit-mask of active flight modes * `carryTrim` (boolean) carry trim * `mixWarn` (number) warning (0 = off, 1 = 1 beep, .. 3 = 3 beeps) * `delayUp` (number) delay up (time in 1/10 s) * `delayDown` (number) delay down * `speedUp` (number) speed up * `speedDown` (number) speed down # model.getMixesCount(channel) 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 # model.getModule(index) 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 TODO ## 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 * `modelId` (number) receiver number * `firstChannel` (number) start channel (0 is CH1) * `channelsCount` (number) number of channels sent to module * `Type` (number) module type * if the module type is Multi additional information are available * `protocol` (number) protocol number * `subProtocol` (number) sub-protocol number * `channelsOrder` (number) first 4 channels expected order # model.getOutput(index) 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 * `min` (number) Minimum % \* 10 * `max` (number) Maximum % \* 10 * `offset` (number) Subtrim \* 10 * `ppmCenter` (number) offset from PPM Center. 0 = 1500 * `symetrical` (number) linear Subtrim 0 = Off, 1 = On * `revert` (number) irection 0 = ­­­---, 1 = INV * `curve` * (number) Curve number (0 for Curve1) * or `nil` if no curve set # model.getSensor(sensor) Get Telemetry Sensor parameters @status current Introduced in 2.3.0 ## Parameters * `sensor` (unsigned number) sensor number (use 0 for sensor 1) ## Return value * `nil` requested sensor does not exist * `table` with sensor data: * `type` (number) 0 = custom, 1 = calculated * `name` (string) Name * `unit` (number) See list of units in the appendix of the OpenTX Lua Reference Guide * `prec` (number) Number of decimals * `id` (number) Only custom sensors * `instance` (number) Only custom sensors * `formula` (number) Only calculated sensors. 0 = Add etc. see list of formula choices in Companion popup # model.getTimer(timer) 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 * `start` (number) start value \[seconds], 0 for up timer, 0> down timer * `value` (number) current value \[seconds] * `countdownBeep` (number) countdown beep (0­ = silent, 1 =­ beeps, 2­ = voice) * `minuteBeep` (boolean) minute beep * `persistent` (number) persistent timer * `name` (string) timer name # model.insertInput(input, line, value) 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 # model.insertMix(channel, line, value) 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 # model.resetSensor(sensor) 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` # model.resetTimer(timer) Reset model timer to a startup value @status current Introduced in TODO ## Parameters * `timer` (number) timer index (0 for Timer 1) ## Return value none # model.setCurve(curve, params) 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: ```lua params = {} params["x"] = {-100, -34, 77, 100} params["y"] = {-70, 20, -89, -100} params["smooth"] = true params["type"] = 1 val = model.setCurve(2, params) ``` setting a 6-point standard smoothed curve ```lua val = model.setCurve(3, {smooth=true, y={-100, -50, 0, 50, 100, 80}}) ``` ## Parameters * `curve` (unsigned number) curve number (use 0 for Curve1) * `params` see model.getCurve return format for table format. setCurve uses standard lua array indexing and arrays start at index 1 ## Return value * \`\` 0 - Everything okay ``` 1 - Wrong number of points 2 - Invalid Curve number 3 - Cuve does not fit anymore 4 - point of out of index 5 - x value not monotonically increasing 6 - y value not in range [-100;100] 7 - extra values for y are set 8 - extra values for x are set ``` # model.setCustomFunction(function, value) 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. # model.setFlightMode(index, params) 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 # model.setGlobalVariable(index, flight\_mode, value) Sets current global variable value. See also model.getGlobalVariable() ## Parameters * `index` zero based global variable index, use 0 for GV1, 8 for GV9 * `flight_mode` Flight mode number (0 = FM0, 8 = FM8) * `value` new value for global variable. Permitted range is from -1024 to 1024. ## Return value none ### Notice Global variable can only store integer values, any floating point value is converted into integer value by truncating everything behind a floating point. # model.setInfo(value) 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. # model.setLogicalSwitch(switch, value) 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})` # model.setModule(index, value) Set RF module parameters @status current Introduced in TODO ## Parameters * `index` (number) module index (0 for internal, 1 for external) * `value` module parameters, see model.getModule() ## Return value none ### Notice If a parameter is missing from the value, then that parameter remains unchanged. # model.setOutput(index, value) 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. # model.setTimer(timer, value) 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) * `value` timer parameters, see model.getTimer() ## Return value none ### Notice If a parameter is missing from the value, then that parameter remains unchanged. --- [Next Page](/llms-full.txt/1)