了解和使用ExpressLRS Lua脚本

2025/5/22大约 21 分钟

一、如何安装Lua脚本

1.将遥控器通过USB接口连接到电脑，在此电脑中找到遥控器SD卡的文件夹

2. 找到SD卡中的Scripts，进入Tools文件，将 ELRS v3 Lua 脚本下载到遥控器的 SD 卡中的文件夹下。

3.打开遥控器，按 SYS键。您现在位于 Tools 菜单中，向下滚动并选择 ExpressLRS。

单色遥控器的屏幕：

彩色遥控器的屏幕：

4.按住 Enter键 加载，就可以显示Lua脚本页面

如果页面一直卡在Loading...

1）请返回 遥控器首页，按下 MDL键， 进 set up页面，确保内置RF是否打开

2）将内置RF 的模式设置成 CRSF 即为打开。

如果在正确配置模式后脚本仍无法加载，请将 内置或外部 RF 波特率 设置为更高的值。

从 3.3.0 版本 开始：

500Hz 或更高的数据包速率需要 大于 400K 的波特率。
使用 400K 波特率 时， 333Hz 是您可以使用的最快数据包速率。

二、了解和使用Lua脚本

2.1 标头

模块标识符

显示当前活动的遥控器模块或设备的名称。

数据包计数器

此指示器显示 TX 模块 从遥控器接收到的 坏数据包（Bad Packets） 和 好数据包（Good Packets） 的数量。第二组数字应与您选择的 数据包速率 一致。

例如，如果您将数据包速率设置为 500Hz，则数据包计数器应显示 0/500，表示您没有收到任何坏数据包（0 坏数据包），并且只接收到好数据包（500 好数据包）。

任何小的波动都是正常的，并且在您更改设置并将其提交到内存后，通常会恢复为 100% 好数据包。

如果指示器开始显示坏数据包，并且好数据包的数量下降，那就不太好了。请确保您的模块没有过热，并且仍与遥控器保持良好的连接。这种情况在您已经解锁并飞行几个公里/英里时尤为危险，因为这可能意味着突然的 Failsafe（失控保护）。

连接指示灯

显示当前 RC Link 状态。当未连接到任何接收器时，它将显示一个破折号 —;而在绑定和连接时显示 C。

Model Mismatch

该消息显示，表明您已连接到接收器，但在对讲机上选择的型号不正确。

Armed

如果您激活了 Arming Switch，则会显示该消息。这是为了警告用户，更改参数可能会导致与接收器不同步或断开连接，从而导致故障保护。

如果您不打算让您的系统布防并准备好飞行，请确保将此开关切换到 Disarm 位置。更新收音机上的 CH5 设置，以便此开关的输出正确

请勿在 ARMED 时更改参数。当参数发生更改时，模块将进入 Parameter Commit 模式，从而中断正常循环。这可能会导致某些硬件组合不同步，从而导致 FAILSAFE。

2.2 版本行

Version Line 位于 Lua 脚本底部附近，表示烧录到设备中的固件版本。该信息适用于 TX 模块 和 接收机。

彩色遥控器的屏幕显示：

单色遥控器的屏幕显示：

从上面的照片中可以看出：

3.3.0- 数字版本号。
ISM2G4- 器件中设置的 Regulatory Domain。TX 和 RX Regulatory Domains 应匹配。
ae9df3- 该版本或分支的 Git 提交hash值。

2.3 Packet Rate

Packet Rate（数据包速率）设置数据包的发送速度。更高的速率意味着数据包发送得更频繁，延迟更低。

彩色遥控器的屏幕显示:

单色遥控器的屏幕显示：

2.4GHz 频段的选项：

50Hz, 150Hz, 250Hz, 500Hz：基于 LoRa 的选项，较高的速率意味着较低的延迟，但牺牲了灵敏度。从 v1.0 开始。
F500 & F1000：纯 FLRC 模式，提供最低的延迟，但比 LoRa 的范围更小，支持 500Hz 和 1000Hz。
D250 & D500：冗余传输的 FLRC 模式。代表 D，250Hz 和 500Hz。具有更高的延迟、更低的包抖动和更高的 LQ，与其他 FLRC 模式相同的范围。
100Hz Full & 333Hz Full：基于 LoRa 的 10 位全分辨率模式，支持 8ch/12ch/16 切换模式选项。
K1000：2.4GHz 的 K 模式为 FSK+FEC（前向纠错，也称自愈数据包），仅在 LR1121 硬件上可用。K 模式与 FLRC 在空中性能上非常相似，设计用于高噪音环境，如赛车事件。
DK250 & DK500：这些模式提供与 D 模式相同的冗余，但使用 K 模式（FSK+FEC）。

900MHz 频段的选项：

25Hz, 50Hz, 100Hz, 200Hz：基于 LoRa 的选项，较高的速率意味着较低的延迟，但牺牲了灵敏度。从 v1.0 开始。
100Hz Full：基于 LoRa 的 10 位全分辨率模式，支持 8ch/12ch/16 切换模式选项。
D50Hz：基于 LoRa 的冗余传输模式，通过 DVDA 实现。
250Hz：仅适用于 GemX 设备。
200Hz Full：仅适用于 GemX 设备。
K1000 Full：SubGHz 的 K 模式为 FSK，仅适用于 LR1121 硬件。该模式设计用于使用 MAVLink 等协议时实现最高的数据吞吐量。

GemX 设备的选项：

X150Hz：跨频模式，将 900MHz 和 2.4GHz 结合在 Gemini Mode 模式下。
X100Hz Full：跨频模式，将 900MHz 和 2.4GHz 结合在 Gemini Mode 模式下，支持 8ch/12ch/16 切换模式选项。

飞行时切勿更改数据包速率，因为这会强制 TX 和 RX 断开连接。

2.4 Telem Ratio

设置每个数据包中用于发送遥测数据的比例。按遥测速率递增的选项依次为：

Off、1:128、1:64、1:32、1:16、1:8、1:4、1:2

一个 1:64 的遥测比率意味着每 64 个数据包中有 1 个用于遥测数据。

v3.0 提供了 Std 和 RaceStd 选项。 RaceStd 会根据 数据包速率 自动调整遥测比率，功能与 Std 相同，但在飞行解锁时会禁用遥测和同步。

2.5 Switch Mode

Switch Mode 设置控制 AUX1-AUX8 通道如何传输到接收机（4 个主通道始终是 10 位）。可选的模式有：

Hybrid：6 个 2、3 或 6 位位置开关 + 1 个 16 位位置开关。
Wide：7 个 64 或 128 位位置开关。

2.6 Antenna Mode

此选项仅适用于支持 Gemini 的 TX 模块。请参阅 Gemini 页面 了解更多详细信息。

可用选项：

Gemini：同时在两个 TX 天线上传输，频率相差 40MHz（适用于 2.4GHz）或约 10MHz（适用于 900MHz）。
Ant 1/Ant 2：仅在一个天线（Ant 1 或 Ant 2）上进行传输。
Switch：在两个天线之间交替传输。

2.7Link Mode

在 3.5.0 版本 中引入的 Link Mode 更改了 TX 模块 的主要协议和功能。

Normal：这是默认配置。TX 模块仅发送遥控器的命令，接收来自接收机的遥测数据并将其发送到遥控器。
MAVLink：此选项启用原生 MAVLink 遥测下行链路和无线电控制上行链路，使 TX 模块和遥控器成为 GCS（地面控制站）与 MAVLink 能力飞行器之间的中介。

2.8 Model Match

ExpressLRS 支持多个配置文件，配置文件通过在遥控器的模型设置中设置 "Receiver ID" 属性来选择。路径为： Model Setup -> Internal/External RF -> Receiver (number)。

Model Match 用于防止在遥控器中意外选择错误的模型并飞行时使用意外的遥控器或 ELRS 配置。

设置为 On 时，当接收机连接时，它将仅与当前的 Receiver ID 配对连接。
设置为 Off 时，将允许与任何已绑定的接收机连接（包括使用绑定短语的接收机）。

连接的两端必须在 Model Match 设置上达成一致。

有关此设置如何限制连接的详细说明，请参见 Model Match。

活动模型的 Receiver ID 会在选项值后显示。

2.9 文件夹标题

以 < 符号开头的项目表示一个文件夹，当选择时，会显示另一级的自定义选项。例如， TX Power、 VTX Administrator、 WiFi Connectivity 都是这样的项目。

这些项目现在会显示当前设置的项目信息。例如， TX Power 项目将显示当前的功率设置，如果启用了 动态功率（Dynamic Power），它将显示当前设置的最大功率，并附带 TX Power Dyn 指示器。

2.9.1 TX Power

TX Power 文件夹是您可以更改 TX 模块 传输功率设置的地方。按一次 TX Power 键进入设置，按 RTN 键返回上一页。

Max Power 设置您 TX 传输的最大功率。选择一个比您 TX 支持的功率高或低的设置时，将自动恢复为最接近的支持级别。

可选的功率级别为：10mW, 25mW, 50mW, 100mW, 250mW, 500mW, 1000mW 和 2000mW。如果 Dynamic Power 设置为 Off，则 TX 将始终使用此最大功率级别。

Dynamic Power 启用时，Dynamic Power 功能将使 TX 在不需要最大功率时动态降低功率以节省能源。 Max Power 表示 TX 将始终以最大功率传输。

Dynamic Power 表示 TX 会根据需要动态调整功率，通常通过开关的位置来控制： HIGH (>1500us) = 动态功率 LOW (<1500us) = 最大功率。

Fan Thresh 设置风扇的启动功率阈值。例如，如果设置为 100mW，则当功率设置为 100mW 且 Fan Thresh 设置为 Off 时，风扇会在短时间延迟后启动。

即使功率下降到阈值以下，风扇仍会继续运行一段时间。并非所有模块都有风扇接口可以从此设置中受益。默认风扇阈值为 250mW。

彩色遥控器的屏幕显示：

单色遥控器的屏幕显示：

TX Power 文件夹是您可以更改 TX 模块 传输功率设置的地方。按一次 TX Power 键进入设置，按 RTN 键返回上一页。

Max Power 设置您 TX 传输的最大功率。选择一个比您 TX 支持的功率高或低的设置时，将自动恢复为最接近的支持级别。可选的功率级别为：10mW, 25mW, 50mW, 100mW, 250mW, 500mW, 1000mW 和 2000mW。

如果 Dynamic Power 设置为 Off，则 TX 将始终使用此最大功率级别。

Dynamic Power 启用时，Dynamic Power 功能将使 TX 在不需要最大功率时动态降低功率以节省能源。
- Max Power 表示 TX 将始终以最大功率传输。
- Dynamic Power 表示 TX 会根据需要动态调整功率，通常通过开关的位置来控制： HIGH (>1500us) = 动态功率，LOW (<1500us) = 最大功率
Fan Thresh 设置风扇的启动功率阈值。例如，如果设置为 100mW，则当功率设置为 100mW 且 Fan Thresh 设置为 Off 时，风扇会在短时间延迟后启动。

即使功率下降到阈值以下，风扇仍会继续运行一段时间。并非所有模块都有风扇接口可以从此设置中受益。默认风扇阈值为 250mW。

2.9.2 VTX Administrator

彩色遥控器的屏幕显示：

单色遥控器的屏幕显示：

VTX Administrator 允许您直接从遥控器更改 VTX 设置，并将这些设置应用到任何连接的接收机。每当建立新的连接时，或者按下 [Send VTX] 按钮时， VTX 设置 将被发送。

Band 设置 VTX 的频段，选项包括标准的模拟 FPV 频段：

Off：表示 VTX 管理器不会调整任何 VTX 设置。
A, B, E, F, R, L：标准的模拟 FPV 频段。

Channel 设置 VTX 的频道，选项包括上述频段中的标准频道：

1, 2, 3, 4, 5, 6, 7, 8：对应标准频道。

Pwr Lvl 设置 VTX 的功率，按索引选择，选项包括：

这些是您 VTX 支持的功率级别。请参考飞控上的 VTX 表格设置，了解准确的功率级别。例如，一个 VTX 可能具有：
选项为 -, 1, 2, 3, 4, 5, 6, 7, 8。

Pitmode 设置是否启用 Pit Mode，选项包括：

On 和 Off：允许您快速切换到或退出 Pit 模式。

最后，按下 [Send VTX] 按钮将配置的设置发送到接收机，并进一步传送到 VTX。这些设置也会在每次建立连接时自动发送。

VTX Administrator 会在 TX 模块检测到与 RX 的连接时，将当前的 VTX 设置发送到飞控。这意味着，在遥测丢失或恢复后，它将重新发送这些设置。因此，如果您使用其他方法更改了 VTX 的功率级别（例如通过 OSD），那么如果在飞行中丢失或恢复遥测，这些设置将被覆盖。

2.9.3 WiFi Connectivity

彩色遥控器的屏幕显示：

单色遥控器的屏幕显示：

本节包含所有与 WiFi 相关的功能。

Enable WiFi：激活 TX 模块的 WiFi 模式，以便通过 WiFi 进行更新（如果 TX 模块具备 WiFi 功能）。请访问该页面查看更新过程的详细说明。
Enable RX WiFi：将已绑定和连接的接收机设置为 WiFi 模式，以便通过 WiFi 进行更新（如果接收机具备 WiFi 功能）。
Enable Backpack WiFi：将 TX Backpack 设置为 WiFi 模式（仅适用于已连接并更新为新 Backpack 固件的 TX 模块）。
Enable VRX WiFi：将绑定并连接到机载 TX Backpack 的 VRX Backpack 设置为 WiFi 模式，以便通过 WiFi 进行更新。

2.9.4 Backpack Options

此文件夹中的参数允许您更改与 Backpack 相关的参数。

彩色遥控器的屏幕显示：

单色遥控器的屏幕显示：

Backpack：开启或关闭 Backpack 功能。
DVR Rec：设置哪个 Aux 通道 和哪个通道位置将触发 DVR 录像 开始，仅适用于具有 VRX Backpack 集成 的 FPV 显示器。
DVR Srt Delay：设置 Aux 开关激活 后多快开始录制 DVR。
DVR Stp Delay：设置 Aux 开关停用 后多快停止录制 DVR。
HT Enable：开启或关闭 头控（Headtracking） 功能，仅适用于具有 VRX Backpack 集成 的某些 FPV 显示器。
HT Start Channel：设置发送头控位置的起始频道。
Telemetry：允许 Backpack 通过 ESPNOW 发送遥测帧。有关遥测的更多信息，请参见 Backpack Telemetry。
Version：显示已刷写到 TX Backpack 的 Backpack 固件版本。

2.10 Bind

此命令仅适用于已经处于 Bind Mode 的接收机（通过两次闪烁的 LED 指示）。已刷写或设置了绑定短语的接收机（版本 3.3.2 及更早版本）将不会进入此绑定模式，因此此命令将不起作用。

具有相同绑定短语和兼容固件版本的设备应该在上电后自动同步/绑定。

按下 [Bind] 按钮将激活传统的绑定模式，可以进行连接接收机。对于已经配置了绑定短语的用户，这个操作没有任何作用，也不需要进行此操作。

彩色遥控器的屏幕显示：

单色遥控器的屏幕显示：

2.11 BLE 摇杆（仅限 ESP32 TXes）

按下选择将激活 BluetoothLE纵杆模式，该模式允许通过计算机的蓝牙连接到模拟器。重新启动或更改模型以退出此模式。

彩色遥控器的屏幕显示：

单色遥控器的屏幕显示：

2.12 Other Devices

Other Devices 文件夹（如果存在）允许更改其他已连接设备的配置，例如当前接收器。它还用于返回 TX Module 选项。

三、接收机选项

遥控器成功连接了接收机之后，点击 Other Devices， 再选择接收机设备，可以看到接收机相关选项

3.1 Protocol

该设置控制已连接接收机的输出。以下是可用的选项：

CRSF：常规 CRSF 协议输出，推荐用于大多数应用。
Inverted CRSF：反向的 CRSF 协议，用于没有其他 UART 可用的飞控，唯一的选择是将接收机的 TX 引脚 连接到 SBUS 引脚（反向 RX）。这是旧版选项。
SBUS：让接收机输出 SBUS 信号，供不支持 CRSF 协议 的设备使用，如稳定器、直升机控制器等。
Inverted SBUS：与上述相同，但为反向输出。
SUMD：让接收机输出 Graupner HoTT SUMD 信号，供不支持 CRSF 协议 的设备使用，如稳定器、直升机控制器等。
DJI RS2 Pro：主要用于 RS2 Pro 云台。
HoTT Telemetry：允许使用 Graupner HoTT 启用的遥测传感器（Graupner 和第三方传感器）。
MAVLINK：在 ExpressLRS 3.5.0 中引入，允许接收机输出原生 MAVLink 到飞控。

3.2 Protocol2

该设置仅适用于 ESP32 基础的接收机。这包括像 RP4TD、 Super D、 Super P 和 EP Dual 等 True Diversity 接收机。这些接收机具有第二个 UART，可用于与主 UART 相同的用途。

请注意，并非所有 ESP32 基础接收机 都暴露了额外的 UART 引脚 或接头，供便捷使用。

可用选项与上面的设置相同，并增加了以下选项：

Tramp：如果您想通过 ExpressLRS Lua 脚本中的 VTX Admin 直接控制使用 Tramp 协议 的 VTX。
SmartAudio：如果您想通过 ExpressLRS Lua 脚本中的 VTX Admin 直接控制使用 SmartAudio 协议 的 VTX。
Off：当辅助 UART 不被使用时设置。

3.3 SBUS failsafe

SBUS Failsafe 用于设置使用 SBUS 协议 输出的接收机的失效保护行为。以下是可用选项：

No Pulses：当发生失效保护时，接收机将停止发送任何信号。
Last Pos：当发生失效保护时，接收机会继续发送它接收到的最后一个通道位置。

3.4 Antenna Mode

该设置仅适用于具有 天线多样性 的接收机。以下是可用的选项：

Diversity：两个天线都将启用，接收机会切换到信号强度更好的天线（基于 RSSI）。
Ant1/Ant2：仅启用一个天线（用于 RC 命令接收和遥测发送）。

3.5 Receiver Mode

该设置仅适用于 True Diversity 接收机。以下是可用的选项：

Gemini：同时在两个接收天线上接收信号，频率相差 40MHz（适用于 2.4GHz）或约 10MHz（适用于 900MHz）。在使用支持 Gemini 的 TX 模块时效果最佳。
Diversity：两个天线都将启用，接收机会切换到信号强度更好的天线（基于 RSSI）。

3.6 Tlm Power

Telemetry Power 设置用于调整接收机的遥测传输功率。此选项仅适用于配备 功率放大器（Power Amplifier） 的接收机。

MatchTX 模式下，接收机会自动调整遥测输出功率，以匹配发射机报告的功率。在 MatchTX 模式下，接收机将在启动时使用默认功率输出（通常是最大功率），直到从发射机接收到功率更新。此功能仅在 Wide Switch Mode 或任何 FullRes 模式 中可用。

3.7 Init Rate

在 ExpressLRS 3.4 中已移除，参见 Init Rate。该设置控制接收机开始检查同步数据包的 数据包速率。在启动时，接收机将从最快的射频模式或数据包速率开始监听同步数据包，逐步降到最慢的速率，然后循环，直到最终同步并绑定。

将此参数设置为与您为 TX 模块 设置的 数据包速率 相同或接近，可以使接收机更快地完成绑定或连接。

3.8 Team Race

Team Racing 允许在多个连接的模型之间进行选择，并将所有未选择的模型设置为失控保护（failsafe）。

TeamRace Channel（默认 CH11 / AUX7）：此通道在接收机上检查，以确定当前选定的模型。如果 TeamRace Position 设置为 Disabled，则此设置无效。
TeamRace Position（默认 Disabled）：指定 TeamRace Channel 的哪个位置激活此模型。支持 6 位开关（位置 1-6），以及 Low/Mid/High 位置，用于 2 位或 3 位开关。

3.9 Loan Model/Return Model

这些命令允许用户借用/归还模型。有关更多信息，请参阅 Loan Model 指南。

该功能在 ExpressLRS 3.4.0 中已弃用并移除，取而代之的是新的绑定程序。有关详细信息，请参阅绑定页面或下方的 Bind Storage 部分。

3.10 Output Mapping

该文件夹仅适用于 PWM 接收机。它允许用户为 PWM 接收机 的每个输出引脚设置选项。

Output Ch：选择要更改设置的 PWM 接收机中的通道或引脚。
Input Ch：选择 Radio Mix 上的哪个通道将其输出发送到接收机的 PWM 通道。
Output Mode：选择输出引脚的命令速率。最好将此设置为伺服或设备的刷新率。
Invert：设置此选项为 On 或 Off 以切换输出通道的方向。

3.11 Bind Storage

Persistent：绑定信息在断电后仍然保持，不会丢失。
Volatile：绑定信息在断电后会丢失。

此选项在 ExpressLRS 3.4.0 及更高版本中可用。有关详细信息，请参见此处。

Returnable：在 ExpressLRS 3.5.0 中引入。此选项允许模型在未绑定的情况下通过 OTA 安全地从机队中借用。必须设置 Binding Phrase，才能确保此功能正常工作。

3.12 Enter Bind Mode command

此命令将使接收机进入 Bind Mode。即使接收机已经刷写了绑定短语或已通过传统方式绑定，它仍然有效。

此命令在 ExpressLRS 3.4.0 及更高版本中可用。

3.13 Model ID

此行显示启用 Model Matching 时接收机当前设置的 Model ID。该编号应与遥控器上当前激活模型设置的 Receiver ID 相匹配，否则将会出现 Model Mismatch（模型不匹配）

四、Q&A

Q1:ExpressLRS Lua 脚本卡在Loading...

A1:返回遥控器设置指南，确保您的无线电已为 ExpressLRS 做好准备。检查 ExpressLRS TX 模块是否已启用 - 否则无法加载脚本。

此外，请确保您的模块已使用 v3.0 固件刷写。V3 Lua 用于 V3.0 烧录的模块，V2 Lua 用于 v2.x 烧录的模块

Q2:不能更改Switch Mode

A2:Switch Mode要求 TX 模块和接收机之间没有连接（在 Lua 脚本的右上角没有显示 "C"）。首先关闭接收机，然后通过 Lua 脚本更改开关模式，再重新启动接收机。此时，新的开关模式将生效。

Q3:不能将数据包速率更改为F1000

A3:F1000 模式要求使用高于 400K 的波特率。首先在模型设置菜单或 System Menu - > Hardware****中更新您的波特率设置，重启遥控器以确保波特率设置已应用，然后再更改数据包速率。

请注意，并非所有遥控器都支持超过 400K 的波特率。

Q4:无法更改为全分辨率

A4:由于全分辨率模式（Full Resolution Rates）需要完全不同的 Switch Modes，因此您需要首先断开接收机和 TX 模块之间的连接，类似于更改 Switch Modes 的操作。

首先关闭接收机，然后将数据包速率更改为全分辨率模式，选择您的 Switch Mode 方案，然后重新启动接收机或飞行器。

Q5:VTX Admin 无法正常工作，但我可以通过 OSD 菜单更改 VTX 频道

A5:由于 VTX Admin 依赖于 MSP，而 MSP 又依赖于遥测，请确保在飞控配置中已启用遥测，并且在遥控器上接收到超过 10 个遥测传感器（可以在 Model Setup -> Telemetry page 查看；如果需要刷新传感器列表，删除并重新发现新的传感器）。此外，请确保 Telem Ratio 设置不是 Off。

Q6:右上角没有 C，我的遥控器中没有遥测

A6:确保 Telem Ratio 不设置为 Off。将其设置为 Std 或其他任何值，而不是 Off。

Q7:在 v1.x版本上，我可以在 TX power中选择 2W，但我更新了脚本后不能再这样做了

A7:这意味着您的模块无法达到如此高或如此低的功率级别。您可以在新的 Lua 脚本中选择的功率级别是基于您的模块支持的功率级别。这同样适用于其他选项，如 Enable Backpack WiFi、BLE 和 Joystick。如果您的模块不支持这些功能，它们将不会出现在 Lua 脚本中。