Scripting Debug Options (SCR_DEBUG_OPTS)

Description

This parameter is a bitmask used to control various debugging and maintenance features of the Lua scripting engine. It allows developers to monitor performance, manage security checksums, and suppress or enable specific status messages.

The Mathematics

The value is treated as a set of individual binary flags:

• Bit 0 (1): Suppress "No Scripts" message. Disables the GCS notification if the system finds zero scripts to run.
• Bit 1 (2): Runtime telemetry messages. Periodically sends GCS text messages showing current RAM usage and execution time for each running script.
• Bit 2 (4): Suppress Log Writing. Prevents scripts from being written to the .BIN log file (saves SD card space).
• Bit 3 (8): Continuous Data Logging. Enables high-frequency logging of script performance metrics to the DataFlash log.
• Bit 4 (16): Disable Pre-Arm Check. Allows the vehicle to arm even if a script has an error or is missing. (Caution: Safety Risk).
• Bit 5 (32): Auto-save Checksums. A "one-shot" command. When set, the system calculates the current script CRCs, saves them to SCR_LD_CHECKSUM and SCR_RUN_CHECKSUM, and then automatically clears this bit.
• Bit 6 (64): Disable Heap Expansion. Prevents the Lua VM from trying to grow its memory pool if a script runs out of space.

The Engineer's View

In AP_Scripting.cpp:

• Checkpoints: The arming_checks() function respects Bit 4.
• One-Shot Logic: The save_checksum() function checks Bit 5 at 1Hz. If active, it performs the XOR-CRC calculations and immediately calls option_clear(DebugOption::SAVE_CHECKSUM) to prevent accidental overwrites.
• Performance Tracking: Bit 1 and 3 are handled inside the Lua executor loop (lua_scripts.cpp) to inject timing probes around the VM execution window.

Tuning & Behavior

• Development Stage: Set to 2 (Bit 1) to get constant feedback on your script's memory footprint and efficiency.
• Production Stage: Set to 0 for a clean GCS experience.
• Security Stage: Use 32 (Bit 5) to "lock in" your verified script set, ensuring that any unauthorized modification to the scripts on the SD card prevents the vehicle from arming.

Scripting Directory Disable (SCR_DIR_DISABLE)

Description

SCR_DIR_DISABLE is a security and performance setting for the Lua engine.

It prevents the flight controller from searching certain directories on the SD card for scripts.

• 0: Scan all standard locations.
• 1: Disable advanced directory scanning.

Tuning & Behavior

• Recommendation: Leave at 0 for standard users.

Scripting Enable (SCR_ENABLE)

Description

SCR_ENABLE activates the internal Lua interpreter.

Lua scripting allows you to add custom features to ArduPilot without needing to recompile the C++ source code. You can write simple scripts to control LEDs, automate complex flight patterns, or interface with unique hardware.

• 0: Disabled.
• 1: Enabled.

Tuning & Behavior

• Default Value: 0.
• Reboot Required: Yes.
• Requirement: Scripts must be placed in the /scripts folder on the SD card.

Scripting Heap Size (SCR_HEAP_SIZE)

Description

SCR_HEAP_SIZE defines the memory limit for your Lua scripts.

If your scripts are large or use many complex variables, they may run out of memory. This parameter allows you to allocate more of the flight controller's RAM to the scripting engine.

Tuning & Behavior

• Default Value: Usually 40,960 bytes (40 KB).
• Constraint: On memory-constrained boards (like those with only 1MB flash), you may not be able to increase this significantly. High-end boards (Cube Orange) can support much larger values.

Loaded script checksum (SCR_LD_CHECKSUM)

Description

This parameter is a security and safety feature that ensures the set of Lua scripts on your SD card matches a "Known Good" configuration. It stores an aggregate CRC32 checksum of every script the autopilot has successfully found and compiled during boot.

If you enable this check, ArduPilot will prevent the vehicle from arming if even a single character in any script has been changed, or if a script has been added or removed from the APM/scripts folder. This is vital for commercial or industrial operations where script integrity is a requirement for flight certification.

The Mathematics

The system calculates a standard CRC32 for each individual script file. The total checksum ($C\_{total}$) is the bitwise XOR accumulation of all individual script checksums ($C\_n$):

$$ C\_{total} = C\_1 \oplus C\_2 \oplus \dots \oplus C\_n $$

The resulting 32-bit value is then masked by 0x7FFFFFFF to fit within the signed integer parameter range.

The Engineer's View

In AP_Scripting::arming_checks() (libraries/AP_Scripting/AP_Scripting.cpp):

1. The code checks if _required_loaded_checksum is not -1.
2. It retrieves the current session's checksum from the Lua compiler backend.
3. If they do not match, it returns a false status with the message: "Scripting: loaded CRC incorrect".
4. This check ensures that the scripts on the disk haven't been tampered with since the last time the "Master" checksum was saved.

Tuning & Behavior

• Default Value: -1 (Check disabled).
• How to Set: Use SCR_DEBUG_OPTS Bit 5 (Value 32) to automatically calculate and save the current checksum to this parameter.
• Usage: Once your scripts are fully tested and frozen, save the checksum. From that point on, any change to the scripts will block arming until you explicitly update the parameter again.

Running script checksum (SCR_RUN_CHECKSUM)

Description

This parameter provides a dynamic layer of safety for Lua scripting by verifying that the correct set of scripts is not only present but is actually running.

While SCR_LD_CHECKSUM verifies that scripts exist and compiled correctly, SCR_RUN_CHECKSUM ensures that every intended script has successfully entered its execution loop and hasn't crashed or been manually stopped. If the "Running Checksum" calculated by the autopilot doesn't match this parameter, the vehicle will refuse to arm.

The Mathematics

The system calculates a bitwise XOR accumulation of the CRC32 values ($C\_n$) for all scripts that are currently in the running state within the Lua VM.

$$ C\_{running} = C\_1 \oplus C\_2 \oplus \dots \oplus C\_{running\_n} $$

The value is masked with 0x7FFFFFFF to ensure compatibility with standard GCS parameter displays.

The Engineer's View

In AP_Scripting::arming_checks() (libraries/AP_Scripting/AP_Scripting.cpp):

1. The system identifies which scripts are active in the Lua scheduler.
2. It calculates the current aggregate CRC.
3. If this fails to match _required_running_checksum (and it's not -1), the pre-arm check fails with the message: "Scripting: running CRC incorrect".
4. This is a critical distinction from the "Loaded" check: a script that has a syntax error will fail the "Loaded" check, but a script that compiles but then crashes (e.g., due to an infinite loop or memory limit) will fail the "Running" check.

Tuning & Behavior

• Default Value: -1 (Check disabled).
• How to Set: Set SCR_DEBUG_OPTS Bit 5 (Value 32) while all your desired scripts are running healthy. ArduPilot will save the current running CRC to this parameter automatically.
• Reliability: This parameter is essential for missions that depend on Lua scripts for safety (e.g., custom fail-safes or terrain-following logic). It guarantees that the vehicle won't arm if the safety-critical script is not active.

Scripting serial protocol 1 (SCR_SDEV1_PROTO)

Description

This parameter defines the logical protocol for the first virtual serial device (SDEV1). When using Lua scripting to interact with serial hardware, you must first tell the system what kind of data is being handled.

Setting this to a specific protocol (like MAVLink, GPS, or NMEA) allows the virtual port to benefit from ArduPilot's internal parsing and buffer management before the data is handed off to your Lua script.

The Mathematics

This is a standard protocol index ($P$):

• -1: None/Disabled.
• 1: MAVLink 1.
• 2: MAVLink 2.
• 5: GPS.
• (Refer to the SERIALx_PROTOCOL list for all available options).

The Engineer's View

In AP_Scripting.cpp, this parameter is part of the _serialdevice subgroup.

• Mapping: It maps to ports[0].state.protocol.
• Serial Manager Integration: When AP_SerialManager scans for devices, it includes these virtual SDEV instances.
• Lua Access: A script then uses serial:find_serial(0) to obtain a handle to this port. The internal driver will then automatically handle the baud rate and framing required by the chosen protocol.

Tuning & Behavior

• Default Value: -1 (Disabled).
• Reboot Required: Yes. Virtual device registration is a boot-time operation.
• Dependencies: SCR_SDEV_EN must be set to 1.

Scripting serial protocol 2 (SCR_SDEV2_PROTO)

Description

This parameter defines the logical protocol for the second virtual serial device (SDEV2). It functions exactly like SCR_SDEV1_PROTO, allowing for a second independent serial integration via Lua.

The Mathematics

This is a standard protocol index ($P$):

• -1: None/Disabled.
• GPS (5): If you are synthesizing a second GPS source in Lua, set this to 5.
• MAVLink (2): If your script needs to speak MAVLink to a companion device.

The Engineer's View

In AP_Scripting.cpp, this maps to ports[1].state.protocol.

• Port Mapping: Internally, this virtual port is assigned the index AP_SERIALMANAGER_SCR_PORT_1 + 1.
• Lua Access: Obtained via serial:find_serial(1).

Tuning & Behavior

• Default Value: -1 (Disabled).
• Reboot Required: Yes.
• Dependencies: SCR_SDEV_EN must be 1.

Scripting serial protocol 3 (SCR_SDEV3_PROTO)

Description

This parameter defines the logical protocol for the third virtual serial device (SDEV3). It allows for a third independent serial integration via Lua, following the same logic as SCR_SDEV1_PROTO.

The Mathematics

This is a standard protocol index ($P$):

• -1: None/Disabled.
• Range: Any valid ArduPilot SERIALx_PROTOCOL value.

The Engineer's View

In AP_Scripting.cpp, this maps to ports[2].state.protocol.

• Port Mapping: Internally, this virtual port is assigned the index AP_SERIALMANAGER_SCR_PORT_1 + 2.
• Lua Access: Obtained via serial:find_serial(2).

Tuning & Behavior

• Default Value: -1 (Disabled).
• Reboot Required: Yes.
• Dependencies: SCR_SDEV_EN must be 1.

Scripting serial device enable (SCR_SDEV_EN)

Description

This parameter enables the use of "Scripting Serial Devices." These are virtual serial ports that allow Lua scripts running on the autopilot to communicate directly with external hardware or sensors connected via a physical UART, without requiring a C++ driver.

When enabled, it allocates resources for up to three virtual serial instances (SDEV1, SDEV2, SDEV3) which can be bound to Lua serial objects. This is a powerful feature for rapid prototyping of custom hardware integrations.

The Mathematics

This parameter acts as a memory allocation gate ($G\_{mem}$):

$$ \text{IF } SCR\_SDEV\_EN == 1 \rightarrow \text{Allocate } [N \times \text{SerialPortState}] $$

Where $N$ is defined by AP_SCRIPTING_SERIALDEVICE_NUM_PORTS (typically 3). Each port then maps to a virtual index in the AP_SerialManager device list.

The Engineer's View

In AP_Scripting.cpp, this maps to the _serialdevice.enable flag.

• Initialization: During boot, AP_Scripting::init_serialdevice_ports() checks this parameter. If active, it registers virtual ports with the Serial Manager.
• Lua Binding: In a Lua script, these ports are accessed using serial:find_serial(instance), where instance corresponds to the SDEV number.
• Data Integrity: Enabling this also activates internal buffers for script-to-UART communication, which are cleared during script restarts to prevent stale data from being sent.

Tuning & Behavior

• Default Value: 0 (Disabled).
• 0: No virtual ports are created; saves a small amount of RAM.
• 1: Enables the SCR_SDEVx_PROTO parameters for configuration.
• Reboot Required: Yes. Virtual port registration happens only during the early boot phase.
• Dependencies: SCR_ENABLE must be 1. You must also set the physical UART protocol (e.g., SERIAL2_PROTOCOL) to Scripting (28) and then configure the corresponding SCR_SDEVx_PROTO.

Scripting thread priority (SCR_THD_PRIORITY)

Description

This parameter determines how much "CPU Importance" is given to the Lua scripting engine relative to other autopilot tasks (like reading sensors, calculating motors, or handling radio telemetry).

By default, scripting runs at a low priority to ensure that even if a script is poorly written or very complex, it cannot "choke" the critical flight control logic. However, for specialized applications where a script needs to handle high-speed data or tight control loops, this priority can be raised.

WARNING: Raising this priority unnecessarily can lead to system instability, watchdog resets, or loss of control if your scripts consume too much CPU time.

The Mathematics

The priority levels are mapped to the underlying RTOS (Real-Time Operating System) thread scheduler:

• 0: Normal. Standard background priority.
• 1: IO. Matches Input/Output tasks.
• 3: UART. Matches Serial communication priority.
• 7: Main. Matches the main flight control loop. (Extremely Dangerous).
• 8: Boost. Highest possible priority.

The Engineer's View

In AP_Scripting::init() (libraries/AP_Scripting/AP_Scripting.cpp), the value of _thd_priority is translated into a hal_priority via an internal priority_map.
This priority is then passed to the hal.scheduler->thread_create() call.

Note that all Lua scripts run within the same single thread. If you raise the priority, you are raising it for every script on your SD card simultaneously. You must audit your scripts for "busy-waits" or long execution times before increasing this setting.

Tuning & Behavior

• Default Value: 0 (Normal).
• When to Increase: Only if your script is failing to meet timing requirements (e.g., missing high-speed serial data or failing to update a custom LED driver at the desired rate).
• When to Decrease: Never; 0 is already the safest background level.
• Reboot Required: Yes. Thread creation happens only during the boot sequence.

Scripting User Parameter (SCR_USER)

Description

SCR_USER1 through SCR_USER6 are "Input Boxes" for your custom Lua scripts.

Instead of hard-coding values like "Speed" or "Distance" inside your script, you can write the script to look at these parameters. This allows you to change how your script behaves using your Ground Station (Mission Planner/QGC) while in the field.

Tuning & Behavior

• Usage: These parameters do nothing by themselves. Their meaning is entirely defined by the specific Lua script you are running.

Scripting User Parameter2

Note: This parameter configures instance 2. It functions identically to SCR_USER1.

Scripting User Parameter3

Note: This parameter configures instance 3. It functions identically to SCR_USER1.

Scripting User Parameter4

Note: This parameter configures instance 4. It functions identically to SCR_USER1.

Scripting User Parameter5

Note: This parameter configures instance 5. It functions identically to SCR_USER1.

Scripting User Parameter6

Note: This parameter configures instance 6. It functions identically to SCR_USER1.

Scripting User Parameter (SCR_USER_FLOAT)

Description

SCR_USER_FLOAT (and its INT8/INT16 cousins) provides a way for Lua Scripts to have their own configurable settings in the standard parameter list.

Since ArduPilot supports custom user-written scripts, those scripts often need variables that the user can change (like a timer duration or a sensitivity factor). These "User Parameters" are placeholders that the scripts can read and write.

Tuning & Behavior

• Usage: Only relevant if you have a Lua script installed on your drone that is designed to use these parameters. Consult the documentation for your specific script to see what value to enter here.

Scripting User Parameter (SCR_USER_INT16)

Description

Provides 16-bit integer storage for custom Lua scripts.

Scripting User Parameter (SCR_USER_INT8)

Description

Provides 8-bit integer storage for custom Lua scripts.

Scripting Instruction Count (SCR_VM_I_COUNT)

Description

SCR_VM_I_COUNT acts as a "Speed Governor" for scripts to ensure they don't slow down the flight control loops.

If a script enters an infinite loop or tries to do too much math at once, the autopilot will pause the script after it reaches this many instructions, allowing the main flight stabilization code to run.

• Default: 10,000 instructions.
• Recommendation: Leave at default unless you have a very complex script that is triggering "Scripting: slow" warnings.