# HITL Simulation Hardware-in-the-Loop (HITL or HIL) is a simulation mode in which normal PX4 firmware is run on real flight controller hardware. This approach has the benefit of testing most of the actual flight code on the real hardware. PX4 supports HITL for multicopters (using jMAVSim or Gazebo Classic) and VTOL (using Gazebo Classic). ## HITL-Compatible Airframes The current set of compatible airframes vs Simulators is: Airframe | `SYS_AUTOSTART` | Gazebo Classic | jMAVSim --- | --- | --- | --- | --- [HIL Quadcopter X](https://px4.gitbook.io/px4-user-guide/airframes/airframe_reference#copter_simulation_hil_quadcopter_x) | 1001 | Y | Y [HIL Standard VTOL QuadPlane](https://px4.gitbook.io/px4-user-guide/airframes/airframe_reference#vtol_standard_vtol_hil_standard_vtol_quadplane) | 1002 | Y | [Generic Quadrotor x](https://px4.gitbook.io/px4-user-guide/airframes/airframe_reference#copter_quadrotor_x_generic_quadcopter) copter | 4001 | Y | Y ## HITL Simulation Environment With Hardware-in-the-Loop (HITL) simulation the normal PX4 firmware is run on real hardware. JMAVSim or Gazebo Classic (running on a development computer) are connected to the flight controller hardware via USB/UART. The simulator acts as gateway to share MAVLink data between PX4 and *QGroundControl*. :::note The simulator can also be connected via UDP if the flight controller has networking support and uses a stable, low-latency connection (e.g. a wired Ethernet connection - WiFi is usually not sufficiently reliable). For example, this configuration has been tested with PX4 running on a Raspberry Pi connected via Ethernet to the computer (a startup configuration that includes the command for running jMAVSim can be found [here](https://github.com/PX4/PX4-Autopilot/blob/main/posix-configs/rpi/px4_hil.config)). ::: The diagram below shows the simulation environment: * A HITL configuration is selected (via *QGroundControl*) that doesn't start any real sensors. * *jMAVSim* or *Gazebo Classic* are connected to the flight controller via USB. * The simulator is connected to *QGroundControl* via UDP and bridges its MAVLink messages to PX4. * *Gazebo Classic* and *jMAVSim* can also connect to an offboard API and bridge MAVLink messages to PX4. * (Optional) A serial connection can be used to connect Joystick/Gamepad hardware via *QGroundControl*. ![HITL Setup - jMAVSim and Gazebo Classic](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-3eed6a1ddd67654f465773a025db53442e2a16b8%2Fpx4_hitl_overview_jmavsim_gazebo.svg?alt=media) ## HITL vs SITL SITL runs on a development computer in a simulated environment, and uses firmware specifically generated for that environment. Other than simulation drivers to provide fake environmental data from the simulator the system behaves normally. By contrast, HITL runs normal PX4 firmware in "HITL mode", on normal hardware. The simulation data enters the system at a different point than for SITL. Core modules like commander and sensors have HITL modes at startup that bypass some of the normal functionality. In summary, HITL runs PX4 on the actual hardware using standard firmware, but SITL actually executes more of the standard system code. ## Setting up HITL ### PX4 Configuration 1. Connect the autopilot directly to *QGroundControl* via USB. 2. Enable HITL Mode 1. Open **Setup > Safety** section. 2. Enable HITL mode by selecting **Enabled** from the *HITL Enabled* list: ![QGroundControl HITL configuration](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-9e05cb6a436df7e37ef09917e16c13acb8d5227c%2Fqgc_hitl_config.png?alt=media) 3. Select Airframe 1. Open **Setup > Airframes** 2. Select a [compatible airframe](#compatible_airframe) you want to test. Then click **Apply and Restart** on top-right of the *Airframe Setup* page. ![Select Airframe](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-8a8ba45eb066944b12cf1168edef93f53dd98b7c%2Fqgc_hil_config.png?alt=media) 4. Calibrate your RC or Joystick, if needed. 5. Setup UDP 1. Under the *General* tab of the settings menu, uncheck all *AutoConnect* boxes except for **UDP**. ![QGC Auto-connect settings for HITL](https://4155462212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LArEa7z2SPawfl3HpCD%2Fuploads%2Fgit-blob-ba03c3ce822ce228db4a24cf3ac25312391efca6%2Fqgc_hitl_autoconnect.png?alt=media) 6. (Optional) Configure Joystick and Failsafe. Set the following [parameters](https://px4.gitbook.io/px4-user-guide/advanced_config/parameters) in order to use a joystick instead of an RC remote control transmitter: * [COM\_RC\_IN\_MODE](https://px4.gitbook.io/px4-user-guide/advanced_config/parameter_reference#COM_RC_IN_MODE) to "Joystick/No RC Checks". This allows joystick input and disables RC input checks. * [NAV\_RCL\_ACT](https://px4.gitbook.io/px4-user-guide/advanced_config/parameter_reference#NAV_RCL_ACT) to "Disabled". This ensures that no RC failsafe actions interfere when not running HITL with a radio control. :::tip The *QGroundControl User Guide* also has instructions on [Joystick](https://docs.qgroundcontrol.com/master/en/SetupView/Joystick.html) and [Virtual Joystick](https://docs.qgroundcontrol.com/master/en/SettingsView/VirtualJoystick.html) setup. ::: Once configuration is complete, **close** *QGroundControl* and disconnect the flight controller hardware from the computer. ### Simulator-Specific Setup Follow the appropriate setup steps for the specific simulator in the following sections. #### Gazebo Classic :::note Make sure *QGroundControl* is not running! ::: 1. Build PX4 with [Gazebo Classic](https://px4.gitbook.io/px4-user-guide/development/simulation/sim_gazebo_classic) (in order to build the Gazebo Classic plugins). ```sh cd DONT_RUN=1 make px4_sitl_default gazebo-classic ``` 2. Open the vehicle model's sdf file (e.g. **Tools/simulation/gazebo/sitl\_gazebo/models/iris\_hitl/iris\_hitl.sdf**). 3. Replace the `serialDevice` parameter (`/dev/ttyACM0`) if necessary. :::note The serial device depends on what port is used to connect the vehicle to the computer (this is usually `/dev/ttyACM0`). An easy way to check on Ubuntu is to plug in the autopilot, open up a terminal, and type `dmesg | grep "tty"`. The correct device will be the last one shown. ::: 4. Set up the environment variables: ```sh source Tools/simulation/gazebo/setup_gazebo.bash $(pwd) $(pwd)/build/px4_sitl_default ``` and run Gazebo Classic in HITL mode: ```sh gazebo Tools/simulation/gazebo/sitl_gazebo/worlds/hitl_iris.world ``` 5. Start *QGroundControl*. It should autoconnect to PX4 and Gazebo Classic. #### jMAVSim (Quadrotor only) :::note Make sure *QGroundControl* is not running! ::: 1. Connect the flight controller to the computer and wait for it to boot. 2. Run jMAVSim in HITL mode: ```sh ./Tools/simulation/jmavsim/jmavsim_run.sh -q -s -d /dev/ttyACM0 -b 921600 -r 250 ``` :::note Replace the serial port name `/dev/ttyACM0` as appropriate. On macOS this port would be `/dev/tty.usbmodem1`. On Windows (including Cygwin) it would be the COM1 or another port - check the connection in the Windows Device Manager. ::: 3. Start *QGroundControl*. It should autoconnect to PX4 and jMAVSim. ## Fly an Autonomous Mission in HITL You should be able to use *QGroundControl* to [run missions](https://docs.qgroundcontrol.com/master/en/FlyView/FlyView.html#missions) and otherwise control the vehicle. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://px4.gitbook.io/px4-user-guide/development/simulation/hitl.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.