ardupilot/libraries/AP_Scripting/applets/repl.md

# Lua REPL

This script implements an interactive REPL (read-evaluate-print-loop) for the
Lua scripting engine accessible over serial, with line editing, history, and
output formatting.

The script can also act as a client for QGroundControl's MAVLink Console
functionality (within the Analyze view), subject to limitations detailed
below.

### Basic Usage

* Configure a serial port (e.g. `SERIALn_PROTOCOL`) to protocol 28 (Scripting).
  * By default the first such port is used; this can be adjusted in the script

      text.

  * `SERIAL6` is the alternate USB serial port on Cube Orange, and convenient

      for bench testing. CAN and network serial ports will also work.

* Load the `repl.lua` script onto the autopilot.
* Connect a terminal emulator to the port and enter Lua statements/expressions

  at the `>` prompt, then press Enter to execute. Results and errors will be
  printed back.

  * A `>>` prompt indicates that more input is needed to complete the

      statement.

  * You can use the arrow keys to edit the current and previous inputs.
  * Press ESC twice to clear the input and any incomplete statement then

      return to an empty prompt.

### Autopilot Connection

* On Linux a convenient command is e.g. `minicom -w -D /dev/ttyACM1 -b 115200`,

  assuming you have the minicom terminal emulator installed.

* Any terminal emulator on any platform should work; see notes below about

  control codes and other configuration.

### SITL Connection

* Start SITL with a command like `Tools/autotest/sim_vehicle.py -A --serialN=tcp:9995:wait` to allow connection to the selected serial port.
* Connect a terminal emulator to localhost TCP port 9995
  * On Linux a convenient command is `stty -icanon -echo -icrnl && netcat localhost 9995`.
  * Note that you must execute `reset` to turn echo back on once disconnected.
  * Scripting must be restarted after a TCP reconnection.

### MAVLink Connection

* Requires at least Ardupilot 4.6.
* Set the port in the script text to `nil` to enable.
* In addition to `repl.lua`, copy the `mavport.lua` file and `MAVLink` directory

  from `AP_Scripting/modules` to `APM/SCRIPTS/MODULES` on your autopilot.

* The ESC key is not supported; cause a syntax error to reset the prompt.
* The experience over a radio link might be sub-par due to lack of any sort of

  packet loss tracking or retransmission.

### Notes and Limitations

* Statements like `local x = 3` create a variable which immediately goes out of

  scope once evaluated. Names must be global to survive to the next prompt.

* There is currently no facility for installing periodic update callbacks.
* While theoretically impossible to accidentally crash the autopilot software,

  certain scripting APIs can cause damage to you or your vehicle if used
  improperly. Use extreme caution with an armed vehicle!

* The script expects Enter to be `\r`, `\r\n`, or `\n`. It prints `\r\n` for a

  new line, and uses ANSI cursor control codes for line editing and history.
  Check your terminal configuration if Enter doesn't work or you see garbage
  characters. Lines longer than the terminal width likely won't edit properly.

* Evaluating complex statements or printing complex results can cause an

  `exceeded time limit` error, stopping the script and losing variables and
  history. Increasing the vehicle's `SCR_VM_I_COUNT` parameter reduces the
  chance of this occurring.