Lua Graph Editor

Lua Graph Editor

The Lua Graph Editor is a visual scripting environment for ArduPilot. Instead of writing Lua code by hand, you connect nodes in a data-flow graph. The editor compiles your graph into a valid ArduPilot Lua script that you can upload to your flight controller's SD card.

How It Works

1. Add nodes from the palette on the left by clicking them
2. Connect ports by dragging from an output port to an input port
3. Configure properties by selecting a node and editing in the inspector panel
4. Export Lua to compile the graph into a .lua file

The Interface

Area	Purpose
Toolbar	File operations, undo/redo, export, templates, docs
Node Palette	All available nodes grouped by category
Canvas	The graph editor where you arrange and connect nodes
Inspector	Properties and details for the selected node
Lua Preview	Live preview of the compiled Lua output

Node Palette

The left sidebar lists all available nodes organized into categories: Sensors (16 nodes), Logic (7), Math (9), Actions (9), Timing (6), Variables (3), and Flow (1). Use the search bar at the top to filter by name. The status bar at the bottom shows the total node count, graph validity, and estimated memory usage.

Inspector

Selecting a node opens its details in the right-side inspector. It shows the node's category, name, and description, followed by editable Properties (e.g., LED Instance) and a Ports section listing each input with its expected data type (boolean, number, etc.). The Lua Preview panel at the bottom shows the compiled output in real time.

Toolbar Actions

• New -- Create a blank graph
• Open -- Load a .adgraph file
• Save -- Save to a .adgraph file
• Templates -- Load a pre-built example graph
• Export Lua -- Compile and save a .lua file
• Undo / Redo -- Standard undo/redo for all graph changes

Templates

The Templates dialog provides pre-built scripts grouped by category (Safety, Utility, etc.). Each template shows a description, node count, number of connections, and run interval so you can gauge complexity before loading. Safety templates include Low Battery Warning, Geofence Alert, Auto RTL on Low Battery, Speed Limit Warning, Wind Speed Failsafe, and GPS Satellite Monitor.

Below is the full editor with a loaded template -- the node palette on the left, the graph canvas in the center, and the inspector on the right.

Your First Script

1. Click Battery in the Sensors category to add a battery node
2. Click Compare in Logic to add a comparison node
3. Connect Voltage output to A input
4. Add a Constant node, set its value to 11.1
5. Connect the constant's Value output to B input
6. Set the Compare operator to < (less than)
7. Add a Send GCS Text node from Actions
8. Connect the Compare Result to the GCS text Trigger
9. Click Export Lua to generate your script

This script sends a GCS message whenever battery voltage drops below 11.1V.

Saving and Loading

Graphs are saved as .adgraph JSON files containing the full node layout, connections, properties, and viewport position. You can share .adgraph files with other ArduDeck users.

The Export Lua button compiles the graph and saves a standard .lua file. Copy it to your flight controller's scripts/ directory on the SD card and reboot.

Connections and Data Flow

Data flows left to right through the graph. During each update cycle, the compiler evaluates nodes in topological order (upstream before downstream).

Making Connections

1. Hover over an output port (right side of a node)
2. Click and drag to an input port (left side of another node)
3. Release to create the connection

Click a connection line and press Delete or Backspace to remove it.

Port Types

Ports are color-coded by data type:

Type	Color	Values
Number	Blue	Integers or floats (0, 3.14, -100)
Boolean	Purple	true or false
String	Yellow/Amber	Text values ("Hello")
Any	Gray	Accepts any type

Type Compatibility

• Exact match -- Number-to-Number, Boolean-to-Boolean always works
• Any port -- Accepts connections from any type
• Number to Boolean -- 0 = false, non-zero = true
• Boolean to Number -- true = 1, false = 0
• Incompatible -- String ports cannot connect to Number/Boolean ports (the editor prevents this)

Rules

• Each input port accepts only one connection
• Each output port can connect to multiple inputs (fan-out)
• Cycles are not allowed -- the compiler detects and reports them
• Unconnected input ports use their default value (shown in the inspector)

Compilation

The compiler transforms your visual graph into ArduPilot-compatible Lua code:

1. Topological sort -- Orders nodes so every node is evaluated after its inputs
2. Variable assignment -- Each output port gets a unique Lua variable
3. Code generation -- Each node emits its Lua code
4. State variables -- Timing and edge-detection nodes get persistent variables at the top
5. Wrapping -- Everything is wrapped in the ArduPilot function update() ... return update, interval end pattern

Generated Code Structure

-- Auto-generated by ArduDeck Lua Graph Editor

local prev_state_1 = false
local timer_2 = 0

function update()
  local voltage_3 = battery:voltage(0)
  local is_low_4 = voltage_3 < 11.1

  if is_low_4 then
    gcs:send_text(4, "LOW BATTERY")
  end

  return update, 1000
end

return update, 1000

Script Settings and Run Interval

The Script Settings panel (right sidebar, when no node is selected) lets you set a Name and Description for your graph. Below that, the Run Interval controls how often ArduPilot calls your script. Enter a value in milliseconds or use the preset buttons (200ms, 500ms, 1s, 2s). Lower values give faster response but use more CPU.

Interval	Use Case
50-100ms	Fast sensor polling, servo control
200ms	General purpose (default)
500-1000ms	Slow monitoring, battery checks
5000ms+	Periodic logging, status reports

ArduPilot enforces a minimum of ~50ms.

Error Detection

The compiler catches errors before generating code:

• Disconnected action nodes (no trigger connected)
• Circular dependencies
• Type mismatches
• Missing required properties

Tips

• Use Comment nodes to document sections of your graph. They have no effect on compiled code but make graphs easier to understand later
• Start with Templates -- Load a pre-built graph, study how it works, then modify it
• Check the Lua Preview -- It shows compiled output in real time so you can verify correctness before exporting
• Use Debounce for alerts -- Without debounce, a rapidly toggling condition spams GCS messages every cycle. Add a Debounce or Rising Edge node before action nodes
• Name your variables -- Use descriptive names like lowBatteryTriggered instead of x in Get/Set Variable nodes
• Organize left to right -- Sensors on the left, logic in the middle, actions on the right

Limitations

ArduPilot Scripting Constraints

• Memory limit -- Scripts are limited to ~50KB of Lua heap memory
• Instruction limit -- Each update() call has a maximum number of bytecode instructions
• No infinite loops -- Scripts that run too long are killed
• File I/O -- Writing to SD card is slow. Don't log faster than every 1-2 seconds
• No network -- Lua scripts cannot open TCP/UDP sockets

Graph Editor Limits

• Maximum ~100 nodes per graph for reasonable performance
• Very complex graphs may compile slowly
• Sub-graphs and nested graphs are not supported

Debugging

• Use Send GCS Text nodes to trace values during development (set severity to Debug)
• Use Log to File to record data for post-flight analysis
• Check /scripts/ on the SD card for error logs if a script fails to start
• Common issues: nil values (sensor not available), division by zero, exceeding memory limits