Xplane Sitl

X-Plane SITL Testing

Test INAV firmware with X-Plane 12's realistic physics simulation for reproducing flight-related bugs.

Quick Start

Prerequisites Check

1. X-Plane 12 (or X-Plane 11 demo) installed
2. INAV-X-Plane-HITL plugin installed
3. FlyWithLua NG+ with SlewMode (for mid-air start)

Start Testing Session

1. Start SITL:

   cd inav/build_sitl
   ./bin/SITL.elf
   

2. Launch X-Plane 12:

   • Select INAV Surfwing aircraft
   • Choose location/airport

3. Connect plugin:

   • Plugins → INAV HITL → Link → Connect to Flight Controller

4. Position aircraft (optional):

   • Enable slew mode: flightwusel/SlewMode/Toggle
   • Position at desired altitude
   • Disable slew mode

5. Monitor via mspapi2:

   from mspapi2 import MSPApi
   with MSPApi(tcp_endpoint="localhost:5760") as api:
       info, status = api.get_inav_status()
       print(status)
   

Starting Mid-Air

X-Plane doesn't have built-in mid-air start. Options:

1. Slew Mode Plugin (recommended):

   • Install FlyWithLua NG+ for X-Plane 12
   • Install SlewMode plugin from GitHub
   • Toggle with flightwusel/SlewMode/Toggle

2. Save/Load Situation:

   • Fly to altitude, File → Save Situation
   • Load situation to resume at that position

3. Final Approach:

   • Select 3NM or 10NM final approach from airport menu

Configuration

SITL Command Line (Alternative to HITL plugin)

./bin/SITL.elf --sim=xp \
    --simip=127.0.0.1 \
    --simport=49000 \
    --chanmap=M01-01,S01-03,S03-02,S04-04

X-Plane Settings

• Settings → General → Flight models per frame: 10
• Settings → Network → Accept incoming connections: Enabled
• Note UDP port (default 49000)

Joystick Mapping

X-Plane REST API

Available at http://localhost:8086/api/v2/ (X-Plane 12.1.1+):

import requests

# Read aircraft position
r = requests.get('http://localhost:8086/api/v2/datarefs/sim/flightmodel/position/latitude')

# Set control surface
requests.put('http://localhost:8086/api/v2/datarefs/sim/cockpit2/controls/yoke_roll_ratio',
             json={'value': 0.5})

Critical: Stopping SITL Safely

IMPORTANT: Killing SITL while the HITL plugin is connected will freeze X-Plane!

Before killing/restarting SITL:

1. In X-Plane: Plugins → INAV-X-Plane-HITL → Disable
2. Wait for plugin to disconnect
3. Now safe to kill SITL
4. After SITL restarts, re-enable the plugin

Helper script: inav/build_sitl/disconnect_xplane_hitl.py

Virtual Joystick Daemon

For automated testing without a physical joystick, use the virtual joystick daemon.

IMPORTANT: Always use the safe wrapper script to prevent lockups from FIFO blocking.

Safe Wrapper Script

Location: inav/build_sitl/xplane_scripts/joystick_cmd.sh

# Start daemon
./joystick_cmd.sh start

# Check status (verify running before sending commands!)
./joystick_cmd.sh status

# Send commands safely (includes timeout protection)
./joystick_cmd.sh calibrate    # Full axis sweep for X-Plane calibration
./joystick_cmd.sh center       # Center all sticks
./joystick_cmd.sh axis 0 16000 # Set roll axis
./joystick_cmd.sh axis 2 -32768  # Throttle min
./joystick_cmd.sh axis 4 32767   # AUX1 (arm) high

# Stop daemon
./joystick_cmd.sh stop

Axis Mapping

FIFO Safety Warning

NEVER write directly to /tmp/inav_joystick_cmd - this can block forever!

• If daemon isn't running, writes block indefinitely
• If FIFO was deleted while daemon runs, daemon can't receive commands
• Always use joystick_cmd.sh which checks state and uses timeout

See inav/build_sitl/xplane_scripts/FIFO_NOTES.md for detailed lockup prevention.

Troubleshooting

Full Documentation

See: claude/developer/docs/testing/xplane-sitl-testing.md

Related Skills

• build-sitl - Build SITL firmware
• msp-protocol - MSP communication with SITL
• sitl-arm - Arm SITL for testing

Resources

• INAV-X-Plane-HITL Plugin
• X-Plane Web API
• SlewMode Plugin