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

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

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

Delete all Inputs

@status current Introduced in 2.0.0

Parameters

none

Return value

none

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

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

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

Parameters

• command command

• data table of data bytes

Return value

• boolean data queued in output buffer or not.

• nil incorrect telemetry protocol.

Change the working directory

@status current Introduced in 2.3.0

Parameters

• directory (string) New working directory

Return value

none

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

  Copy

    return 0 on radio without rotary encoder

Remove all mixers

@status current Introduced in 2.0.0

Parameters

none

Return value

none

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

@status current Introduced in 2.2.0

Parameters

none

Return value

• rssi RSSI value (0 if no link)

• alarm_low Configured low RSSI alarm level

• alarm_crit Configured critical RSSI alarm level

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

Clear all flightModes

@status current Introduced in 2.3.10

Parameters

none

Return value

none

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

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.

Stops key state machine. See 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

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

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)

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

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

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

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

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

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

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

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.

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.

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.

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

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

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)

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.

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)

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.

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

Display a value formatted as time at (x,y)

@status current Introduced in 2.0.0, SHADOWED introduced in 2.2.1

Parameters

• x,y (positive numbers) starting coordinate

• value (number) time in seconds

• flags (unsigned number) drawing flags:

  • 0 or not specified normal representation (minutes and seconds)

  • TIMEHOUR display hours

  • other general LCD flag also apply

  • SHADOWED Horus only, apply a shadow effect

Return value

none

Draw a straight line on LCD

@status current Introduced in 2.0.0, flags introduced in 2.3.6

Parameters

• x1,y1 (positive numbers) starting coordinate

• x2,y2 (positive numbers) end coordinate

• pattern SOLID or DOTTED

• flags lcdflags

Return value

none

Notice

If the start or the end of the line is outside the LCD dimensions, then the whole line will not be drawn (starting from OpenTX 2.1.5)

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.

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

Clear the LCD screen

@status current Introduced in 2.0.0, color parameter introduced in 2.2.0 RC12

Parameters

• color (optional, only on color screens)

Return value

none

Notice

This function only works in stand-alone and telemetry scripts.

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

Draw a simple gauge that is filled based upon fill value

@status current Introduced in 2.0.0, changed in 2.2.0

Parameters

• x,y (positive numbers) top left corner position

• w (number) width in pixels

• h (number) height in pixels

• fill (number) amount of fill to apply

• maxfill (number) total value of fill

• flags (unsigned number) drawing flags

Return value

none

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

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)

Display a number at (x,y)

@status current Introduced in 2.0.0, SHADOWED introduced in 2.2.1

Parameters

• x,y (positive numbers) starting coordinate

• value (number) value to display

• flags (unsigned number) drawing flags:

  • 0 or not specified display with no decimal (like abs())

  • PREC1 display with one decimal place (number 386 is displayed as 38.6)

  • PREC2 display with tow decimal places (number 386 is displayed as 3.86)

  • other general LCD flag also apply

  • SHADOWED Horus only, apply a shadow effect

Return value

none

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

@status current Introduced in 2.0.0, changed in 2.2.0

Parameters

• x,y (positive numbers) top left corner position

• w (number) width in pixels

• h (number) height in pixels

• flags (unsigned number) drawing flags

• t (number) thickness in pixels, defaults to 1 (only on Horus)

Return value

none

Returns the rightmost x position from previous output

@status current Introduced in 2.0.0

Parameters

none

Return value

• number (integer) x position

Notice

Only available on Taranis

For added clarity, it is recommended to use lcd.getLastRightPos()

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)

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.

Draw a bitmap at (x,y)

@status current Introduced in 2.0.0

Parameters

• x,y (positive numbers) starting coordinates

• name (string) full path to the bitmap on SD card (i.e. “/IMAGES/test.bmp”)

Return value

none

Notice

Maximum image size is [display width / 2] x [display height] pixels.

Return current global variable value

Example:

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

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)

@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

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

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

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

Display a telemetry value at (x,y)

@status current Introduced in 2.0.6, changed in 2.1.0 (only telemetry sources are valid)

Parameters

• x,y (positive numbers) starting coordinate

• source can be a source identifier (number) or a source name (string). See getValue()

• flags (unsigned number) drawing flags

Return value

none

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

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

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

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

@status current Introduced in 2.0.0

Parameters

• x,y (positive numbers) top left corner position

• w (number) width in pixels

• h (number) height in pixels

• flags (unsigned number) drawing flags

Return value

none

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

Draw a text beginning at (x,y)

@status current Introduced in 2.0.0, SHADOWED introduced in 2.2.1

Parameters

• x,y (positive numbers) starting coordinate

• text (string) text to display

• flags (unsigned number) drawing flags. All values can be combined together using the + character. ie BLINK + DBLSIZE. See the Appendix for available characters in each font set.

  • 0 or not specified normal font

  • XXLSIZE jumbo sized font

  • DBLSIZE double size font

  • MIDSIZE mid sized font

  • SMLSIZE small font

  • INVERS inverted display

  • BLINK blinking text

  • SHADOWED Horus only, apply a shadow effect

Return value

none

Returns the rightest x position from previous drawtext or drawNumber output

@status current Introduced in 2.2.0

Parameters

none

Return value

• number (integer) x position

Notice

Only available on Taranis

This is strictly equivalent to former lcd.getLastPos()

Get the color for specific area : see lcd.setColor for area list

@status current Introduced in 2.3.11

Parameters

none

Return value

none

Notice

Only available on Colorlcd radios

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

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

Draw a single pixel at (x,y) position

@status current Introduced in 2.0.0

Parameters

• x (positive number) x position

• y (positive number) y position

• flags (optional) lcdflags

Return value

none

Notice

Taranis has an LCD display width of 212 pixels and height of 64 pixels. Position (0,0) is at top left. Y axis is negative, top line is 0, bottom line is 63. Drawing on an existing black pixel produces white pixel (TODO check this!)

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.

Returns a 5/6/5 rgb color code, that can be used with lcd.setColor

@status current Introduced in 2.2.0

Parameters

• r (integer) a number between 0x00 and 0xff that expresses te amount of red in the color

• g (integer) a number between 0x00 and 0xff that expresses te amount of green in the color

• b (integer) a number between 0x00 and 0xff that expresses te amount of blue in the color

Return value

• number (integer) rgb color expressed in 5/6/5 format

Notice

Only available on Colorlcd radios

Displays a bitmap at (x,y)

@status current Introduced in 2.2.0

Parameters

• bitmap (pointer) point to a bitmap previously opened with Bitmap.open()

• x,y (positive numbers) starting coordinates

• scale (positive numbers) scale in %, 50 divides size by two, 100 is unchanged, 200 doubles size. Omitting scale draws image in 1:1 scale and is faster than specifying 100 for scale.

Return value

none

Notice

Only available on Horus

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

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

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

Returns the leftmost x position from previous drawtext or drawNumber output

@status current Introduced in 2.2.0

Parameters

none

Return value

• number (integer) x position

Notice

Only available on Taranis

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

Reset model timer to a startup value

@status current Introduced in TODO

Parameters

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

Return value

none

Set all inputs to defaults

@status current Introduced in 2.0.0

Parameters

none

Return value

none

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

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.

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

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.

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

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

@status current Introduced in 2.0.0

Parameters

• x,y (positive numbers) starting coordinate

• switch (number) number of switch to display, negative number displays negated switch

• flags (unsigned number) drawing flags, only SMLSIZE, BLINK and INVERS.

Return value

none

Return input data for given input and line number

@status current Introduced in 2.3.10

Parameters

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

Return 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

Reset the backlight timeout

@status current Introduced in 2.3.6

Parameters

none

Return value

none

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

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

  • desc (string) field description

  • 'unit' (number) unit identifier Full list

• nil the requested field was not found

This page describes the value that is passed to scripts in the event parameter. It is used in and 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 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

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

• 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

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:

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)

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

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

Draw a combo box

@status current Introduced in 2.0.0

Parameters

• x,y (positive numbers) top left corner position

• w (number) width of combo box in pixels

• list (table) combo box elements, each element is a string

• idx (integer) index of entry to highlight

• flags (unsigned number) drawing flags, the flags can not be combined:

  • BLINK combo box is expanded

  • INVERS combo box collapsed, text inversed

  • 0 or not present combo box collapsed, text normal

Return value

none

Notice

Only available on Taranis

Draw a title bar

@status current Introduced in 2.0.0

Parameters

• title (string) text for the title

• page (number) page number

• pages (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

Notice

Only available on Taranis

Refresh the LCD screen

@status current Introduced in 2.2.0

Parameters

none

Return value

none

Notice

This function only works in stand-alone and telemetry scripts.

Displays the name of the corresponding input as defined by the source at (x,y)

@status current Introduced in 2.0.0

Parameters

• x,y (positive numbers) starting coordinate

• source (number) source index

• flags (unsigned number) drawing flags

Return value

none

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

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

Description

Lcd functions allow scripts to interact with the transmitter display. This access is limited to the 'run' functions of One-Time and Telemetry scripts. Widget scripts on the Horus (X10 and X12S) can make use of the lcd functions as well.

Notes:

The run function is periodically called when the screen is visible. In OpenTX 2.0 each invocation starts with a blank screen (unless lcd.lock() is used). Under OpenTX 2.1 screen state is always persisted across calls to the run function. Many scripts originally written for OpenTX 2.0 require a call to lcd.clear() at the beginning of their run function in order to display properly under 2.1 and 2.2.

Many of the lcd functions accept parameters named flags and patterns. The names and their meanings are described below.

Flags Constants

Patterns Constants

Screen Constants

Screen Information