Skip to content

Instantly share code, notes, and snippets.

@mrpollo

mrpollo/px4-jmavsim-sih-report.md

Created March 5, 2026 17:51
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save mrpollo/50f305128d9e57c3d6fe924180a0585d to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save mrpollo/50f305128d9e57c3d6fe924180a0585d to your computer and use it in GitHub Desktop.
Download ZIP
PX4 jMAVSim & SIH Simulation Report - Build variants, targets, limitations, and hardware usage
Raw
px4-jmavsim-sih-report.md

PX4 jMAVSim & SIH Simulation Report

1. Build Targets Overview

Target Autostart Simulator What it does
jmavsim / jmavsim_iris 10017 jMAVSim (physics + viz) Builds jMAVSim jar, launches PX4 + jMAVSim together
none (none, uses saved params) None Launches bare PX4, no simulator
none_iris 10016 None Launches PX4 with Iris airframe, no simulator
sihsim_quadx (env-based) SIH PX4 with built-in quad physics
sihsim_airplane (env-based) SIH PX4 with fixed-wing physics
sihsim_xvert (env-based) SIH PX4 with tailsitter physics
sihsim_standard_vtol (env-based) SIH PX4 with standard VTOL physics
sihsim_hex (env-based) SIH PX4 with hexacopter physics
sihsim_rover_ackermann (env-based) SIH PX4 with rover physics

2. jMAVSim

CMake Targets (from sitl_targets_jmavsim.cmake)

  • build_jmavsim: Builds the jMAVSim JAR via ant create_run_jar copy_res

    • Depends on: git_jmavsim, jmavsim_run_symlink
    • Output: Tools/simulation/jmavsim/jMAVSim/out/production/jmavsim_run.jar

  • jmavsim_run_symlink: Creates symlink to jmavsim_run.sh in rootfs

  • jmavsim_iris: Launch helper, sets PX4_SYS_AUTOSTART=10017

    • Depends on: px4, git_jmavsim, build_jmavsim, jmavsim_run_symlink

  • jmavsim: Alias for jmavsim_iris

Build requirements: Java ANT, javac, java (all must be the same Java version)

Airframe

Single airframe: 10017_jmavsim_iris (3DR Iris Quadrotor, Quadrotor Wide, 4 rotors in X config)

Vehicle Physics (Java Classes)

Class Rotors Notes
Quadcopter 4 Supports "x" and "+" layouts, "default" and "cw_fr" rotor positions
Hexacopter 6 Supports "x" and "+" orientations

Inheritance: AbstractVehicle -> AbstractMulticopter -> Quadcopter / Hexacopter

No fixed-wing, VTOL, or rover physics exist in jMAVSim.

3D Display Models (Cosmetic Only)

Flag (script) Flag (java) Model file Vehicle shown
(default) -mc models/3dr_arducopter_quad_x.obj Quadcopter
-a -fw models/cessna.obj Fixed-wing
-t -ts models/x_vert.obj Tailsitter

These only change the rendered 3D model. They do not change physics.

jmavsim_run.sh Options

Flag Java arg Description
-l -lockstep Lockstep mode
-r <Hz> -r <Hz> Update rate
-p <port> port in device string Connection port
-u -udp Use UDP instead of TCP
-i <ip> ip in device string IP address
-o -disponly Display only (no physics, just rendering)
-a -fw Show fixed-wing model
-t -ts Show tailsitter model
-q -qgc QGC forwarding
-s -sdk SDK mode
HEADLESS=1 -no-gui No GUI window
-b <baud> serial baudrate For serial connections
-d <dev> serial device Serial device path

Keyboard Shortcuts (in GUI window)

Views:

  • F - First-person view (follows vehicle)
  • S - Stationary ground camera
  • G - Gimbal camera
  • Z - Toggle auto-zoom for stationary camera
  • +/- - Zoom in/out
  • 0/ENTER - Reset zoom

Actions:

  • Q - Disable sim on MAV
  • I - Enable sim on MAV
  • H - Toggle HUD overlay
  • C - Clear HUD messages
  • R - Toggle data report sidebar
  • T - Toggle data report updates
  • D - Toggle sensor parameter control sidebar
  • F1 - Key commands reference
  • P - Pause simulation
  • ESC - Exit jMAVSim
  • SPACE - Reset vehicle and view

Vehicle Manipulation:

  • Arrow keys - Rotate pitch/roll
  • END/PG-DN - Rotate yaw
  • SHIFT + arrows - Move N/S/E/W
  • SHIFT + INS/DEL - Move up/down
  • Numpad 8/2/4/6 - Rotation rate around pitch/roll
  • Numpad 1/3 - Rotation rate around yaw
  • Numpad 5 - Stop all rotation
  • CTRL + Numpad 5 - Reset attitude/velocity/acceleration

MAVLink Interface (simulator_mavlink)

Incoming (Simulator to PX4):

  • HIL_SENSOR (ID 107) - IMU, mag, baro, differential pressure with timestamp
  • HIL_GPS (ID 113) - GPS position, velocity, heading
  • HIL_OPTICAL_FLOW (ID 100) - Optical flow data

Outgoing (PX4 to Simulator):

  • HIL_ACTUATOR_CONTROLS (ID 93) - Motor PWM and control surface outputs

Limitations

  • Only multicopter physics (Quad/Hex). No fixed-wing, VTOL, or rover.
  • Single airframe (10017 Iris quad)
  • Java version mismatch issues on macOS (ant vs java may use different JDKs)
  • Stale jar cache if compiled with wrong Java version (must rm -rf Tools/simulation/jmavsim/jMAVSim/out)
  • 3D model swap (-fw, -ts) is cosmetic only, does not change physics
  • Slow startup (JVM + ant build)
  • Community supported, may be removed in future releases

macOS JAVA_HOME Gotcha

On macOS with multiple Java versions via Homebrew, ant and java may resolve to different JDKs:

  • ant defaults to /opt/homebrew/opt/openjdk (could be Java 25)
  • java via /usr/bin/java resolves to openjdk@17

Fix: always set JAVA_HOME before running:

export JAVA_HOME=$(/usr/libexec/java_home -v 17)

3. SIH (Simulator in Hardware)

Overview

SIH is a built-in C++ simulator that runs inside PX4 itself. Originally designed for real flight controllers ("Simulator in Hardware"), it now also works as a SITL simulator with zero external dependencies.

Vehicle Types

Controlled by SIH_VEHICLE_TYPE parameter:

Type Enum Physics Model Supported Since
Quadcopter 0 4 rotors, rigid body dynamics v1.9
Fixed-wing 1 Aerodynamic segments (Khan 2016 PhD thesis), 1 motor + 3 control surfaces v1.13
Tailsitter VTOL 2 11 aerodynamic segments (Chiappinelli 2018), 2 rotors + 2 surfaces v1.13
Standard VTOL 3 Blended quad + FW dynamics, 5 rotors + 3 surfaces v1.16
Hexacopter 4 6 rotors, symmetric X v1.17
Rover Ackermann 5 Bicycle model, steering + throttle v1.17

SITL Airframes

Airframe ID File Vehicle
10040 10040_sihsim_quadx Quadcopter X
10041 10041_sihsim_airplane Fixed-wing
10042 10042_sihsim_xvert Tailsitter
10043 10043_sihsim_standard_vtol Standard VTOL
10044 10044_sihsim_hex Hexacopter
10045 10045_sihsim_rover_ackermann Rover Ackermann

SITL Init Flow

rcS-posix
  -> PX4_SIM_MODEL env var selects SYS_AUTOSTART
    -> airframe file sets PX4_SIMULATOR=sihsim
      -> px4-rc.simulator dispatches to px4-rc.sihsim
        -> simulator_sih start
        -> conditional sensor_*_sim starts (based on SENS_EN_*SIM params)

Dispatcher logic (px4-rc.simulator):

if PX4_SIMULATOR=sihsim OR SYS_AUTOSTART=0  -->  px4-rc.sihsim
elif PX4_SIMULATOR=gz OR SIM_GZ_EN=1        -->  px4-rc.gzsim
elif PX4_SIM_MODEL=jmavsim_iris OR AUTOSTART=10017  -->  px4-rc.jmavsim
else                                         -->  px4-rc.mavlinksim

SIH Parameters

Physical model:

  • SIH_MASS - Vehicle mass (kg), default 1.0
  • SIH_IXX/IYY/IZZ - Diagonal inertia (kg m^2)
  • SIH_IXY/IXZ/IYZ - Off-diagonal inertia
  • SIH_T_MAX - Max propeller thrust (N), default 5.0
  • SIH_Q_MAX - Max propeller torque (Nm), default 0.1
  • SIH_L_ROLL/L_PITCH - Arm lengths (m), default 0.2

Aerodynamics:

  • SIH_KDV - First-order drag coefficient, default 1.0
  • SIH_KDW - Angular damper coefficient, default 0.025
  • SIH_T_TAU - Thruster time constant (s), default 0.05

Geographic/environmental:

  • SIH_LOC_LAT0 - Initial latitude (deg), default 47.397742
  • SIH_LOC_LON0 - Initial longitude (deg), default 8.545594
  • SIH_LOC_H0 - Initial AMSL altitude (m), default 489.4

Sensors:

  • SIH_DISTSNSR_MIN/MAX - Distance sensor range limits
  • SIH_DISTSNSR_OVR - Distance sensor override (-1 = disabled)

Simulated Sensors

Sensor Rate Module Parameter
IMU (accel + gyro) 250 Hz Built into SIH Always on
Barometer Configurable sensor_baro_sim SENS_EN_BAROSIM
GPS Configurable sensor_gps_sim SENS_EN_GPSSIM
Magnetometer Configurable sensor_mag_sim SENS_EN_MAGSIM
Airspeed 50 Hz Built into SIH For FW/VTOL types
Distance sensor 50 Hz Built into SIH SIH_DISTSNSR_* params

Ground truth publications (for logging/analysis):

  • vehicle_angular_velocity_groundtruth
  • vehicle_attitude_groundtruth
  • vehicle_local_position_groundtruth
  • vehicle_global_position_groundtruth

Speed Control (SITL only)

PX4_SIM_SPEED_FACTOR=10 make px4_sitl sihsim_quadx

Uses lockstep scheduler for deterministic, faster-than-realtime simulation.

4. SIH on Hardware (Flight Controller)

How It Works

SIH runs on the flight controller itself. The FC runs the full PX4 stack with simulated sensors instead of real ones. You can connect an RC transmitter and fly without a real vehicle.

Trigger: SYS_HITL=2 (0 = normal, 1 = external HITL, 2 = SIH)

Hardware Startup Flow

rcS -> SYS_HITL=2 check
  -> sensors start -h (HITL mode, disables real sensors)
  -> param set GPS_1_CONFIG 0 (disable real GPS)
  -> simulator_sih start
  -> sensor_baro_sim start
  -> sensor_mag_sim start
  -> sensor_gps_sim start
  -> sensor_agp_sim start

Hardware Airframes (NuttX)

Airframe ID File Vehicle SIH Type
1100 1100_rc_quad_x_sih.hil Quadcopter X 0
1101 1101_rc_plane_sih.hil Fixed-wing 1
1102 1102_tailsitter_duo_sih.hil Tailsitter 2
1103 1103_standard_vtol_sih.hil Standard VTOL 3
1104 1104_standard_ackermann_sih.hil Rover Ackermann 5

Note: No hexacopter hardware airframe (type 4), though the SIH engine supports it.

Hardware vs SITL Differences

Aspect Hardware (FC) SITL
Trigger SYS_HITL=2 PX4_SIMULATOR=sihsim env var
Actuator params HIL_ACT_FUNC* PWM_MAIN_FUNC*
Sensor startup Auto-enabled by rcS Manual via SENS_EN_*SIM params
Timing Real-time 250 Hz loop Lockstep (supports speed factor)
Speed control None (real-time only) PX4_SIM_SPEED_FACTOR
GPS delay Default (realistic) 0 (instant)
Airframes dir init.d/airframes/ init.d-posix/airframes/

Boards with SIH Enabled

Config symbol: CONFIG_MODULES_SIMULATION_SIMULATOR_SIH=y

53 hardware boards have SIH enabled by default. Notable ones:

Board Config File
px4/fmu-v5 boards/px4/fmu-v5/default.px4board
px4/fmu-v5x boards/px4/fmu-v5x/default.px4board
px4/fmu-v6x boards/px4/fmu-v6x/default.px4board
px4/fmu-v6c boards/px4/fmu-v6c/default.px4board
holybro/durandal-v1 boards/holybro/durandal-v1/default.px4board
cuav/x7pro boards/cuav/x7pro/default.px4board
ark/fmu-v6x boards/ark/fmu-v6x/default.px4board
emlid/navio2 boards/emlid/navio2/default.px4board
beaglebone/blue boards/beaglebone/blue/default.px4board

Not supported: FMUv2 (too resource-constrained)

Enabling SIH in Kconfig auto-selects:

  • pwm_out_sim - simulated PWM output
  • sensor_baro_sim - simulated barometer
  • sensor_gps_sim - simulated GPS
  • sensor_mag_sim - simulated magnetometer

Visualization on Hardware

jMAVSim via serial USB (display-only):

# Linux
./Tools/simulation/jmavsim/jmavsim_run.sh -q -d /dev/ttyACM0 -b 2000000 -o

# macOS
./Tools/simulation/jmavsim/jmavsim_run.sh -q -d /dev/tty.usbmodem1 -b 2000000 -o

# Add -a for fixed-wing model, -t for tailsitter model

Or just use QGroundControl directly. No visualizer required.

5. Simulator Comparison

Aspect jMAVSim (standalone) SIH (SITL) SIH (on hardware)
Dependencies Java, ANT None Flight controller
Vehicle types Quad, Hex (physics). FW/TS (display only) 6 types with full physics 5 types (no hex airframe)
Physics engine Java, rotor-only C++, full aero models Same C++ engine
Startup time Slow (JVM + ant) Fast (built-in module) Instant (on boot)
CPU usage Moderate (GUI), low (headless) Very low Runs on FC MCU
Data path MAVLink HIL_SENSOR/HIL_ACTUATOR Direct uORB topics Direct uORB topics
Lockstep Via MAVLink Built-in scheduler N/A (real-time)
Speed factor No Yes (PX4_SIM_SPEED_FACTOR) No (real-time only)
Visualization Built-in 3D GUI Optional (jMAVSim -o or QGC) Optional (jMAVSim -o or QGC)
RC input Via QGC/joystick Via QGC/joystick Real RC transmitter
Sensor fidelity Basic noise Comprehensive (noise, delay, all types) Same as SITL
Ground truth No Yes (uORB topics) Yes (uORB topics)
Use case Quick quad testing Development, CI, rapid prototyping Pilot training, HW validation

Combined Mode: SIH + jMAVSim Display

SIH handles all physics internally. jMAVSim provides optional 3D visualization in display-only mode (-o). This gives the best of both worlds: accurate multi-vehicle-type physics from SIH with visual feedback from jMAVSim.

SITL:

# Terminal 1: jMAVSim display-only
./Tools/simulation/jmavsim/jmavsim_run.sh -p 19410 -u -q -o      # quad
./Tools/simulation/jmavsim/jmavsim_run.sh -p 19410 -u -q -o -a   # fixed-wing model
./Tools/simulation/jmavsim/jmavsim_run.sh -p 19410 -u -q -o -t   # tailsitter model

# Terminal 2: PX4 with SIH
make px4_sitl sihsim_quadx
make px4_sitl sihsim_airplane
make px4_sitl sihsim_xvert

On hardware:

# On desktop, connected to FC via USB
./Tools/simulation/jmavsim/jmavsim_run.sh -q -d /dev/ttyACM0 -b 2000000 -o

Limitation: jMAVSim always shows the same 3D model regardless of SIH vehicle type unless you manually pass -a (fixed-wing) or -t (tailsitter). There is no automatic model switching.

6. Key Files Reference

jMAVSim:

  • Tools/simulation/jmavsim/jmavsim_run.sh - Launch script
  • Tools/simulation/jmavsim/jMAVSim/src/me/drton/jmavsim/Simulator.java - Main entry
  • Tools/simulation/jmavsim/jMAVSim/src/me/drton/jmavsim/vehicle/ - Vehicle classes
  • src/modules/simulation/simulator_mavlink/sitl_targets_jmavsim.cmake - CMake targets
  • src/modules/simulation/simulator_mavlink/SimulatorMavlink.cpp - MAVLink bridge
  • ROMFS/px4fmu_common/init.d-posix/px4-rc.jmavsim - SITL init script
  • ROMFS/px4fmu_common/init.d-posix/airframes/10017_jmavsim_iris - Airframe

SIH:

  • src/modules/simulation/simulator_sih/sih.cpp - Main implementation
  • src/modules/simulation/simulator_sih/sih.hpp - Class definition
  • src/modules/simulation/simulator_sih/aero.hpp - Aerodynamic models
  • src/modules/simulation/simulator_sih/sih_params.c - Parameters
  • src/modules/simulation/simulator_sih/Kconfig - Config symbol
  • ROMFS/px4fmu_common/init.d-posix/px4-rc.sihsim - SITL init script
  • ROMFS/px4fmu_common/init.d-posix/airframes/1004[0-5]_sihsim_* - SITL airframes
  • ROMFS/px4fmu_common/init.d/airframes/110[0-4]_*_sih.hil - Hardware airframes

Init scripts:

  • ROMFS/px4fmu_common/init.d-posix/px4-rc.simulator - SITL simulator dispatcher
  • ROMFS/px4fmu_common/init.d/rcS - Hardware main startup (SYS_HITL logic at line 324)

Board configs:

  • boards/px4/sitl/default.px4board - Default SITL (includes Gazebo)
  • boards/px4/sitl/sih.px4board - SIH-only SITL (no Gazebo dependencies)

7. The none Target Gotcha

The none cmake target (platforms/posix/CMakeLists.txt line 149) launches PX4 with no PX4_SYS_AUTOSTART override. It uses whatever SYS_AUTOSTART value is saved in parameters.bson from a previous run.

If a previous run used jmavsim_iris (autostart 10017), then make px4_sitl_sih none will auto-launch jMAVSim from the init scripts because the saved param matches the jMAVSim condition in px4-rc.simulator.

Fix: Use none_iris (explicitly sets autostart 10016) or delete stale params:

rm build/px4_sitl_sih/rootfs/parameters.bson build/px4_sitl_sih/rootfs/parameters_backup.bson
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment