Lua Script Reference

General syntax

###Local variables Script can have any number of local variables, their value is preserved between each call to run function. They are defined as:

local simple_number = 4
local some_array = {1, 2, 120}

Scripts can't share local variables. They can however use other mechanisms such as global variables (GVARS), model settings, mixers, etc...

Local functions

Script can have any number of local functions:

local function some_function(a, b, c)
    value1 = a + b * c
    return value1
end

The use of global variables an functions should be avoided, because all scripts share the same environment.

OpenTX extension to LUA language

Inputs syntax

Input are only used in model scripts. However same number format is used when using function getValue().

Number format

Inputs are analog values from opentTX that converted to 16 bit signed integers before they reach Lua script.

Analog values such as sticks and sliders have value multiplied by 10. Examples:

alieron stick value	input value to script
0	0
60.5	650
-100.0	-1000

Switches (real and logical) are represented as:

switch position	input value to script
down	-1000
middle	0
up	1000

Telemetry values TODO

telemetry value	input value to script
altitude 120.5m	TODO
A1 voltage 5.47V	TODO
consumption 1260mAh	TODO

Types of inputs

There are two kinds of inputs:

SOURCE
VALUE

SOURCE

Source type provides current value of selected openTX variable (stick position, slider, channel). User assings assigns actual source for this input in Custom script menu. Source can be any value openTX knows about (inputs, channels, telemetry values, switches, custom functions,...).

Syntax: { "Aileron", SOURCE }

Defines SOURCE input with name Aileron. Name length is limited to TODO.

VALUE

Value type provides constant value that user sets in Custom script menu

Syntax: { "Ratio", VALUE, -100, 100, 0 }

Defines VALUE input with name Ratio that has limits -100 and 100 and default value of 0. Name lengths is limited to TODO.

Outputs syntax

Outputs are only used in model scripts.

Number format

Outputs are 16 bit signed integers when they leave Lua script and are then divided by 10 to produce output value. Examples:

output from script	output as seen from openTX
0	0.0
996	96.6
-1256	-125.6

General functions

getTime()

Returns the time since radio start in multiple of 10ms

    Parameters:      none
    Return value:    (number) time time since radio start in multiple of 10ms

getVersion()

Returns OpenTX version

    Parameters:      none
    Return value:    (number) version (i.e. 2.0)

Notice: Lua does not differentiate between integer and float numbers.

getValue(source)

Returns the value of a source

    Parameters:      source   (number) can be constant (i.e. STICK_RUDDER)
                              (string) or a string name (i.e. “altitude”)
    Return value:    (number) value of source or nil if value is not available

Suported source names are:

name	value	examle
"altitude"	barometric altutude in meters	120.56
"latitude"	GPS latitude in degrees, North is positive	45.5667
"longitude"	GPS longitude in degrees, East is positive	120.5677
"pilot latitude"	first GPS value (usually pilot position) format same as "latitude"	-12.567
"pilot longitude"	first GPS value (usually pilot position) format same as "longitude"	-0.567

playFile(path)

Plays a file from the SD card

    Parameters:      path     (string) full path to wav file (i.e. “/SOUNDS/en/system/tada.wav”)
    Return value:    none

popupInput(title, event, current-value, min, max)

Raises a popup on screen to ask the user a value

    Parameters:      title    TODO
    Return value:    (number) value that user selected

Model functions

Display functions

lcd.lock()

Prevents main OpenTX code from modifying LCD screen. This lock is reset every time script is run and must be set again if script wants LCD to be locked one more iteration.

    Parameters:      none
    Return value:    none

lcd.clear()

Clears LCD screen

    Parameters:      none
    Return value:    none

lcd.drawPoint(x, y)

Draws a single pixel at (x,y) position

    Parameters:      x        (number) x position in pixels 
                     y        (number) y position in pixels 
    Return value:    none

Notice: Taranis has LCD display width of 212 pixels and height of 64 pixels. Position (0,0) is at top left. Y axis is negative, top line iz 0, botom line is 63.

lcd.drawLine(x1, y1, x2, y2)

Draws a line from (x1,y1) to (x2,y2)

    Parameters:      <four>   (numbers) same as lcd.drawPoint()
    Return value:    none

lcd.drawRectangle(x, y, width, height)

Draws a rectangle from top left corner (x,y) of specified width and height

    Parameters:      <x,y>    (numbers) top left corner position, same as lcd.drawPoint()
                     width    (number) width in pixels
                     height   (number) height in pixels
    Return value:    none

lcd.drawText(x, y, text, att)

Draws a text begginging at (x,y)

    Parameters:      <x,y>    (numbers) top left text position, same as lcd.drawPoint()
                     text     (string) text to display
                     att      (number) text attribute TODO
    Return value:    none

    att values:      0        normal font
                     DBLSIZE  dobule size font
                     MIDSIZE  mid size font
                     SMLSIZE  small font
                     INVERS   inverted display
                     BLINK    blinking text

    All att values can be combined together using "or" operator 
    although DBLSIZE, MIDSIZE and SMLSIZE kind of contradict them self

Notice:

TODO codes for special characters

lcd.drawSwitch(x, y, switch, att)

Draws a text representation of switch at (x,y)

    Parameters:      <x,y>    (numbers) top left text position, same as lcd.drawPoint()
                     switch   (number) number of switch to display, negative number
                              displays negated switch 
                     att      (number) text attribute TODO
    Return value:    none

    switch values:   TODO mapping between switch number

lcd.drawPixmap(x, y, path)

Draws a bitmap at (x,y)

    Parameters:      <x,y>    (numbers) top left bitmap position, same as lcd.drawPoint()
                     path     (string) full path to the bitmap on SD card (i.e. “/BMP/test.bmp”)
    Return value:    none

lcd.drawScreenTitle(title, idx, cnt)

Draws a title bar

    Parameters:      title    (string) text for the title
                     idx      (number) page number
                     cnt      (number) total number of pages. Only used as indicator 
                              on the right side of title bar (i.e. idx=2, cnt=5, display "2/5")

    Return value:    none