Understanding ExpressLRS Lua Scripts

CoreWingAbout 6 minRemote ControlELRSLua 脚本遥控器配置ExpressLRS参数调整

How to Install Lua Scripts

Connect the RC transmitter to the computer via USB, and find the RC transmitter's SD card folder on this computer.
Find the Scripts folder in the SD card, enter the Tools folder, and download the ELRS v3 Lua script to the RC transmitter's SD card folder.
Turn on the RC transmitter, press the SYS key. You are now in the Tools menu, scroll down and select ExpressLRS.
Screen for monochrome RC transmitter:

Screen for color RC transmitter:
Hold down the Enter key to load, and the Lua script page will be displayed.

If the page is stuck on Loading...

Return to the RC transmitter home page, press the MDL key, enter the set up page, and ensure that the built-in RF is turned on.
Set the built-in RF mode to CRSF to turn it on.

If the script still fails to load after correctly configuring the mode, set the built-in or external RF baud rate to a higher value.

Starting from version 3.3.0:

500Hz or higher packet rates require a baud rate greater than 400K.
When using 400K baud rate, 333Hz is the fastest packet rate you can use.

III. Receiver Options

After the RC transmitter successfully connects to the receiver, click Other Devices, then select the receiver device to see the receiver-related options

3.1 Protocol

This setting controls the output of the connected receiver. The following options are available:

CRSF: Standard CRSF protocol output, recommended for most applications.
Inverted CRSF: Inverted CRSF protocol, used for flight controllers without other available UARTs, where the only option is to connect the receiver's TX pin to the SBUS pin (inverted RX). This is a legacy option.
SBUS: Makes the receiver output SBUS signal for devices that do not support CRSF protocol, such as gimbals, helicopter controllers, etc.
Inverted SBUS: Same as above, but with inverted output.
SUMD: Makes the receiver output Graupner HoTT SUMD signal for devices that do not support CRSF protocol, such as gimbals, helicopter controllers, etc.
DJI RS2 Pro: Mainly used for RS2 Pro gimbals.
HoTT Telemetry: Allows for telemetry sensors enabled with Graupner HoTT (Graupner and third-party sensors).
MAVLINK: Introduced in ExpressLRS 3.5.0, allows the receiver to output native MAVLink to the flight controller.

This setting only applies to receivers based on ESP32. This includes True Diversity receivers such as RP4TD, Super D, Super P, and EP Dual. These receivers have a second UART that can be used for the same purposes as the main UART.
Note that not all ESP32-based receivers expose additional UART pins or connectors for convenient use.

Available options are the same as the above settings, with the following additional options:

Tramp: If you want to directly control a VTX using Tramp protocol through VTX Admin in ExpressLRS Lua scripts.
SmartAudio: If you want to directly control a VTX using SmartAudio protocol through VTX Admin in ExpressLRS Lua scripts.
Off: Set when the auxiliary UART is not in use.

3.3 SBUS failsafe

SBUS Failsafe is used to set the failsafe behavior of receivers using SBUS protocol for output. The following options are available:

No Pulses: When a failsafe occurs, the receiver will stop sending any signals.
Last Pos: When a failsafe occurs, the receiver will continue to send the last channel position it received.

3.4 Antenna Mode

This setting only applies to receivers with antenna diversity. The following options are available:

Diversity: Both antennas will be enabled, and the receiver will switch to the antenna with better signal strength (based on RSSI).
Ant1/Ant2: Only one antenna is enabled (for RC command reception and telemetry transmission).

3.5 Receiver Mode

This setting only applies to True Diversity receivers. The following options are available:

Gemini: Receives signals on both receiver antennas simultaneously, with a frequency difference of 40MHz (for 2.4GHz) or approximately 10MHz (for 900MHz). Works best when using a TX module that supports Gemini.
Diversity: Both antennas will be enabled, and the receiver will switch to the antenna with better signal strength (based on RSSI).

3.6 Tlm Power

Telemetry Power setting is used to adjust the telemetry transmission power of the receiver. This option is only available for receivers equipped with a Power Amplifier.

In MatchTX mode, the receiver will automatically adjust the telemetry output power to match the power reported by the transmitter. In MatchTX mode, the receiver will use the default power output (usually maximum power) at startup until it receives a power update from the transmitter. This feature is only available in Wide Switch Mode or any FullRes mode.

3.7 Init Rate

Removed in ExpressLRS 3.4, see Init Rate. This setting controls the packet rate at which the receiver starts checking for sync packets. At startup, the receiver will begin listening for sync packets at the fastest RF mode or packet rate, gradually stepping down to the slowest rate, then cycling, until it finally syncs and binds.
Setting this parameter to the same or close to the packet rate you set for the TX module can make the receiver complete binding or connection faster.

3.8 Team Race

Team Racing allows selection between multiple connected models, with all unselected models set to failsafe.

TeamRace Channel (default CH11 / AUX7): This channel is checked on the receiver to determine the currently selected model. This setting is invalid if TeamRace Position is set to Disabled.
TeamRace Position (default Disabled): Specifies which position of the TeamRace Channel activates this model. Supports 6-position switches (positions 1-6), as well as Low/Mid/High positions for 2-position or 3-position switches.

3.9 Loan Model/Return Model

These commands allow users to borrow/return models. For more information, refer to the Loan Model guide.
This feature was deprecated and removed in ExpressLRS 3.4.0, replaced by the new binding process. For details, see the binding page or the Bind Storage section below.

3.10 Output Mapping

This folder only applies to PWM receivers. It allows users to set options for each output pin of the PWM receiver.

Output Ch: Select the channel or pin in the PWM receiver to change settings for.
Input Ch: Select which channel on the Radio Mix to send its output to the receiver's PWM channel.
Output Mode: Select the command rate for the output pin. It's best to set this to the refresh rate of the servo or device.
Invert: Set this option to On or Off to invert the direction of the output channel.

3.11 Bind Storage

Persistent: Binding information remains after power-off and is not lost.
Volatile: Binding information is lost after power-off.
This option is available in ExpressLRS 3.4.0 and later versions. For more details, see here.
Returnable: Introduced in ExpressLRS 3.5.0. This option allows a model to be safely borrowed from the fleet via OTA without being bound. A Binding Phrase must be set for this feature to work properly.

3.12 Enter Bind Mode command

This command will make the receiver enter Bind Mode. It works even if the receiver has already been flashed with a binding phrase or has been bound through traditional means.
This command is available in ExpressLRS 3.4.0 and later versions.

3.13 Model ID

This line displays the Model ID currently set on the receiver when Model Matching is enabled. This number should match the Receiver ID set on the currently active model on the transmitter, otherwise a Model Mismatch will occur.

4. Q&A

Q1: ExpressLRS Lua script stuck at Loading...
A1: Return to the RC transmitter setup guide and ensure your radio is prepared for ExpressLRS. Check if the ExpressLRS TX module is enabled - otherwise the script cannot be loaded.
Additionally, ensure your module has been flashed with v3.0 firmware. V3 Lua is for modules flashed with v3.0, V2 Lua is for modules flashed with v2.x
Q2: Cannot change Switch Mode
A2: Switch Mode requires no connection between the TX module and receiver (no "C" displayed in the top-right corner of the Lua script). First, turn off the receiver, then change the switch mode through the Lua script, and restart the receiver. The new switch mode will now take effect.
Q3: Cannot change packet rate to F1000
A3: F1000 mode requires a baud rate higher than 400K. First, update your baud rate settings in the Model Setup menu or System Menu -> Hardware, restart the RC transmitter to ensure the baud rate settings are applied, and then change the packet rate.
Note that not all RC transmitters support baud rates over 400K.
Q4: Cannot change to full resolution
A4: Since Full Resolution Rates require completely different Switch Modes, you need to first disconnect the receiver and TX module, similar to the process for changing Switch Modes.
First, turn off the receiver, then change the packet rate to Full Resolution mode, select your Switch Mode scheme, and restart the receiver or aircraft.
Q5: VTX Admin is not working properly, but I can change VTX channels through the OSD menu
A5: Since VTX Admin depends on MSP, which in turn depends on telemetry, ensure telemetry is enabled in the flight controller configuration and that more than 10 telemetry sensors are received on the RC transmitter (can be viewed in Model Setup → Telemetry page; if you need to refresh the sensor list, delete and rediscover new sensors). Additionally, ensure the Telem Ratio setting is not Off.
Q6: No C in the top-right corner, no telemetry on my RC transmitter
A6: Ensure Telem Ratio is not set to Off. Set it to Std or any other value instead of Off.
Q7: In v1.x versions, I could select 2W in TX power, but after updating the script I can't do this anymore
A7: This means your module cannot achieve such high or low power levels. The power levels available for selection in the new Lua script are based on the power levels supported by your module. This also applies to other options such as Enable Backpack WiFi, BLE, and Joystick. If your module does not support these features, they will not appear in the Lua script.