HITL/SITL X-Plane improvements (merge of #11253)

[sensei-hacker]

Summary

Merges PR #11253 (Scavanger's HITL/SITL X-Plane improvements) into maintenance-9.x, with conflict resolution and several correctness fixes identified during review.

• MSP_SIMULATOR v3 protocol with 2-byte flags field and new HITL capabilities
• New HITL flags: HITL_RANGEFINDER, HITL_CURRENT_SENSOR, HITL_SIM_RC_INPUT, HITL_FAILSAFE_TRIGGERED, HITL_SITL_MODE
• Refactored MSP_SIMULATOR handler into readMspSimulatorValues() and mspProcessSimulatorCommand() for clarity
• battery.c: simulated current injection when HITL_CURRENT_SENSOR active
• displayport_msp_osd.c: OSD enabled in SITL mode via HITL_SITL_MODE flag
• runtime_config: SIMULATOR_MSP_VERSION_3 constant and new HITL flag bits
• common.h: USE_RX_SIM and USE_RANGEFINDER_FAKE promoted from SITL-only target.h to common (needed for HITL on hardware targets)
• xplane.h: stdbool.h include and simXPlaneClose() declaration
• xplane.c: INAV-XITL DataRef state machine with _Atomic connectionState_t thread safety and simXPlaneClose()

Conflict resolution

xplane.c was the only file with merge conflicts. The PR's XITL DataRef state machine was taken and the base's improvements were applied on top:

• _Atomic connectionState_t for safe cross-thread access
• simXPlaneClose() for clean resource release
• exit(0) replaced with return NULL so pthread_join in simXPlaneClose completes cleanly
• simXPlaneInit wait loop handles DISCONNECTED state reached during init

Fixes applied during review

Several issues were identified and corrected beyond the original PR:

• connectionState data race — declared _Atomic (xplane.c)
• exit(0) in listenWorker — replaced with return NULL for clean shutdown (xplane.c)
• simXPlaneInit disconnect handling — wait loop now exits on DISCONNECTED and returns false (xplane.c)
• Dead variables removed — initalized, shouldStopListenThread, initMutex, initCond were added from the base but never read by the new state machine; removed (xplane.c)
• GPS velNED for HITL — reverted to SITL-only exclusion; MSP HITL explicitly injects valid velNED data that should not be discarded (navigation_pos_estimator.c)
• HITL teardown on flags=0 — flags=0 stop packet now correctly clears SIMULATOR_MODE_HITL and calls disarm() instead of being a no-op (fc_msp.c)
• Packet size threshold — adjusted for header bytes consumed before readMspSimulatorValues is called, preserving compatibility with existing minimum-size payloads (fc_msp.c)
• isFailsafe volatile — USE_RX_SIM now compiles into all hardware HITL targets; added volatile to prevent register caching across scheduler tasks (rx/sim.c)
• Units comment — added // dA (deciamperes; * 10 = cA) to simulatorData.current to match documentation style of other fields (runtime_config.h)

Testing

• Built SITL target successfully (no warnings)
• Ran 14-test MSP sensor injection regression suite against both baseline (maintenance-9.x) and PR build
• Result: 14/14 passed on both, no regressions detected
• Tests cover: MSP_SIMULATOR v2 and v3 payloads, all new HITL flags, bad-version rejection, HITL_SITL_MODE bypass, GPS injection before and after HITL enable

Code review

Reviewed with inav-code-review agent before PR creation. All identified issues addressed above.

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

[Copilot]

Pull request overview

This PR merges and backports X-Plane HITL/SITL improvements into maintenance-9.x, introducing an updated MSP_SIMULATOR v3 protocol and adding INAV-XITL (DataRef-based) support to improve simulator integration and enable additional simulated sensors/RC features.

Changes:

• Adds MSP_SIMULATOR v3 support (2-byte flags + new HITL capability bits) and refactors simulator MSP handling for clarity.
• Extends HITL/SITL functionality (simulated current sensor, rangefinder, RC input/RSSI/failsafe, SITL-mode behavior toggles).
• Implements an INAV-XITL DataRef-based connection/state machine for X-Plane SITL, plus documentation updates for plugin usage.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/main/target/SITL/target.h	Removes SITL-only feature defines now promoted to common for hardware HITL use.
src/main/target/SITL/sim/xplane.h	Adds missing stdbool.h include and exposes simXPlaneClose().
src/main/target/SITL/sim/xplane.c	Adds INAV-XITL DataRef support, connection state machine, and simulator sensor/RC injection via DataRefs.
src/main/target/common.h	Promotes USE_RX_SIM / USE_RANGEFINDER_FAKE to common to support HITL on non-SITL targets.
src/main/sensors/battery.c	Injects simulated current into current meter when HITL current sensor flag is active.
src/main/rx/sim.h	Updates RX sim API (const correctness) and adds failsafe setter.
src/main/rx/sim.c	Adds failsafe reporting for simulated RX frames.
src/main/navigation/navigation_pos_estimator.c	Adjusts velNED handling so MSP HITL-provided velNED is not discarded while keeping SITL workaround.
src/main/io/displayport_msp_osd.c	Attempts to enable OSD behavior in SITL mode through a HITL flag.
src/main/fc/runtime_config.h	Adds MSP v3 constants and new HITL flags; extends simulatorData_t with RC/current/rangefinder fields.
src/main/fc/runtime_config.c	Initializes new simulator data fields.
src/main/fc/fc_msp.c	Refactors MSP_SIMULATOR handling into helpers and adds v3 parsing + new HITL feature handling.
docs/SITL/X-Plane.md	Documents INAV-XITL plugin option for advanced SITL features.
docs/SITL/SITL.md	Adds SITL docs link/reference for INAV-XITL plugin alongside HITL plugin.
docs/development/Hardware In The Loop (HITL) plugin for X-Plane.md	Mentions INAV-XITL as the newer plugin option for recent INAV versions.

Comments suppressed due to low confidence (2)

src/main/target/SITL/sim/xplane.c:364

• exchangeDataWithXPlane() treats only EWOULDBLOCK as the timeout case for recvfrom(), but SO_RCVTIMEO commonly yields EAGAIN. Consider accepting both EAGAIN and EWOULDBLOCK so a receive timeout doesn’t prematurely abort the exchange loop.

    recvLen = recvfrom(sockFd, buf, sizeof(buf), 0,
                       (struct sockaddr*)&remoteAddr, &slen);
    if (recvLen < 0 && errno != EWOULDBLOCK) {
        return;

src/main/io/displayport_msp_osd.c:251

• drawScreen() unconditionally overwrites vtxActive based on HITL_SITL_MODE. This fights with the existing heartbeat/timeout logic (checkVtxPresent/processMspCommand) and will force vtxActive=false in normal operation, preventing MSP displayport output. Gate this assignment to SITL-only behavior, or combine it with the existing vtxActive state instead of overwriting it each frame.

static int drawScreen(displayPort_t *displayPort) // 250Hz
{
    vtxActive = SIMULATOR_HAS_OPTION(HITL_SITL_MODE);
    
    static uint8_t counter = 0;

    if ((!cmsInMenu && IS_RC_MODE_ACTIVE(BOXOSD)) || (counter++ % DRAW_FREQ_DENOM)) { // 62.5Hz
        return 0;

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

Test firmware build ready — commit 5522945

Download firmware for PR #11566

234 targets built. Find your board's .hex file by name on that page (e.g. MATEKF405SE.hex). Files are individually downloadable — no GitHub login required.

Development build for testing only. Use Full Chip Erase when flashing.