fl2sitl

Overview

fl2sitl is a simple simulator that can be used with the INAV SITL (Software in the loop) and other tools (INAV Configurator, mwp etc.).

fl2sitl may be used as a minimal quiescent simulator to unlock the full potential of the SITL (fl2sitl --minimal), e.g. to use a physical RX/TX.
fl2sitl is also a "shim" that can sit between a blackbox file / blackbox_decode and the INAV SITL (Software In The Loop) desktop application. This allows blackbox logs to be replayed into the INAV SITL for visualisation or investigation.

When used with a blackbox log, tools such as:

mwp (Somewhat pointless as mwp provides somewhat better BBL visualisation directly)
INAV Configurator
Any other visualisation / analysis tool that understands MSP or LTM or MAVLink (the latter as generated by INAV).

may be used for visualisation.

The INAV SITL was merged for INAV 6.1 and is well documented.

Note also that as the BBL visualisation is driven by the SITL, it is necessary for the SITL to be provided with all the information it needs to 'fly' the vehicle effectively. For example, if the BBL contains a WP mission, the mission must be loaded into the SITL before the 'vehicle' is armed. This is described in some more detail later.

Important : As the SITL is being driven from a Blackbox log (with predetermined outcome), the need for a mission file for WP flights is significant; otherwise, once WP mode is commanded, the SITL FC will enter "missing mission" procedure (RTH), and then get confused as the sensors indicate a different outcome. It is possible to generate a reasonable representation of a missing mission file from a log via log2mission.

Usage

fl2sitl is a terminal / command line application. It must be run from a shell terminal (*sh on POSIX platforms, cmd or powershell on Windows). It requires:

A configuration file
The name of a BBL file, unless invoked with --minimal

$ fl2sitl
Usage of fl2sitl [options] file...
  -auto-arm
    	Arm as soon as ready (vice manaully)
  -eeprom string
    	EEprom name
  -index int
    	Log index
  -interval int
    	Sampling Interval (ms) (default 100)
  -listen string
    	Listening port (default ":49000")
  -minimal
    	Don't read a BBL
  -mission string
    	Optional mission file name
  -mission-index int
    	Optional mission file index
  -nostart
    	Don't start the SITL
  -rebase string
    	rebase all positions on lat,lon[,alt]
  -sitl-config string
    	SITL specific config file
  -txport int
    	host:port for serial TX (default 5761)
  -verbose int
    	Verbosity
  -version
    	Just show version

fl2sitl 1.0.11 commit:df26c7f

Please note that:

All options are optional
- -eeprom may to used to override the default set in the configuration file.
- -index is required for BBL files containing multiple logs
- -verbose sets the amount of status / logging / debug information provided. Unless you're investigating a problem the default of 0 will suffice, otherwise 3 is useful.
- -mission and -mission-index will load a (multi) mission into the SITL.
- -auto-arm arms the SITL FC as soon as it is ready (vice waiting for user interaction).
- The IP settings are the SITL defaults.
- --minimal just prepares the X-Plane socket and, on connection, returns quiescent data. The SITL is not started, and no TX is emulated. It is intended for use with the INAV Configurator "SITL" option.

fl2sitl opens the X-Plane protocol UDP port [::]:49000 and starts the INAV_SITL, with default SITL settings from the configuration file.

Runtime behaviours

`fl2sitl`

Once executed, fl2sitl

Creates the X-Plane protocol socket
Invokes INAV_SITL with parameters from the configuration file.
Creates the MSP-RC TCP socket (UART2)
Starts the BBL reader
Obtains switch settings from the SITL FC
Waits the SITL FC to be ready to arm
Prompts the user to arm the SITL FC, unless -auto-arm is specified, in which case the FC is armed with user intervention.
Once the SITL FC is armed:
- Updates the SITL with sensor data from the BBL
- Updates the MSP-RC with stick data
- Updates the MSP-RC with RSSI

Visualisation or analysis tool

Once the SITL is ready (MSP-RC is running), but prior to arming the user should ensure the SITL has any additional data necessary to 'fly' the log. In particular, if the log includes waypoints, the relevant mission is loaded into the 'SITL' via the SITL's UART1 MSP port, either with -mission or externally with mwp / impload / INAVConfigurator etc. It is also possible to save missions to the SITL EEPROM and 'Load Mission from EEPROM'.

Command Keys

The user controls the behaviour via key-presses in fl2sitl.

A, a : Arm the SITL FC
U : Disarm the SITL FC
Q, q, Ctrl-C : Quits fl2sitl (and disarms if necessary), terminates the SITL.

Sample Session

The following sequence illustrates a sample session. Note that:

After ******** Opened RX **************, fl2sitl will interrogate the SITL (via UART2) to get the switch settings and other necessary settings.
At ** Ready to arm (Press 'A' to arm) **, the user connected mwp to tcp://localhost:5760 (SITL UART1). Note that at this stage,
- The user restored the previously saved mission from EEPROM (or loaded the mission if not stored)
- The user noted that the altitude had settled; this often takes c 10 seconds.
The user pressed A to instruct fl2sitl to "arm" the SITL via the arming switch.
The SITL "flys" the flight, using sensor and stick data supplied by fl2sitl from the Blackbox log.
At the end of log, the SITL FC is disarmed and the SITL closed down.
fl2sitl exits

$ fl2sitl  ~/LOG00022.TXT
Log      : LOG00022.TXT / 1
Flight   :  on 2020-11-08 14:08:22
Firmware : INAV 2.3.0 (063ba5a) MATEKF722 of Jan 19 2020 20:20:56
Size     : 13.50 MB
INAV 6.1.0 SITL
[SYSTEM] Init...
[SIM] Waiting for connection...
[SOCKET] xplane address = [::1]:49000, fd=0
[fl2sitm] 16:03:44.565116 Failed to open RX dial tcp [::1]:5761: connect: connection refused
[fl2sitm] 16:03:44.667118 Failed to open RX dial tcp [::1]:5761: connect: connection refused
[SIM] Connection with X-Plane successfully established.
[EEPROM] Loaded '/home/jrh/sitl-eeproms/fw-eeprom.bin' (32768 of 32768 bytes)
[SOCKET] Bind TCP :: port 5760 to UART1
[SOCKET] Bind TCP :: port 5761 to UART2
[SOCKET] ::1 connected to UART2
[fl2sitm] 16:03:44.768109 ******** Opened RX **************
[fl2sitm] 16:03:46.396847 INAV v6.1.0 SITL (3949da89) API 2.5
[fl2sitm] 16:03:46.528840 "BenchyMcTesty"
[fl2sitm] 16:03:46.616873 ARM;PREARM;ANGLE;HORIZON;TURN ASSIST;HEADING HOLD;CAMSTAB;NAV POSHOLD;LOITER CHANGE;NAV RTH;NAV WP;HOME RESET;GCS NAV;WP PLANNER;MISSION CHANGE;NAV CRUISE;NAV COURSE HOLD;SOARING;NAV ALTHOLD;MANUAL;NAV LAUNCH;SERVO AUTOTRIM;AUTO TUNE;AUTO LEVEL;BEEPER;OSD OFF;BLACKBOX;KILLSWITCH;FAILSAFE;CAMERA CONTROL 1;CAMERA CONTROL 2;CAMERA CONTROL 3;OSD ALT 1;OSD ALT 2;OSD ALT 3;
[fl2sitm] 16:03:46.616947 RC init done
[fl2sitm] 16:03:50.288850 ** Ready to arm (Press 'A' to arm) **
[SOCKET] 127.0.0.1 connected to UART1
[fl2sitm] 14:47:05 Armed
[fl2sitm] 15:01:14 Disarming ...
[fl2sitm] 15:01:15 Cleanup ...
[fl2sitm] 15:01:17 Done
[fl2sitm] 15:01:17 Serial Read EOF

[fl2sitl] prefix indicates fl2sitl specific messages.
INAV 6.0.0 SITL, [SYSTEM], [SIM] [EEPROM] and other capitalised / bracketed messages are from the SITL.
Other, non-prefixed message are from generic fl2x log reading

Example images from the visualisation are provided.

Configuration

`fl2sitl` Configuration File

The configuration file should be in the OS specific canonical directory for user configuration files in a fl2x subdirectory (so $HOME/.config/fl2x for POSIX platforms and $LOCALAPPDATA/fl2x on Windows). The default file name is fl2sitl.conf. An alternate path may be passed using --sitl-config.

The following keys (inter-alia) are recognised. Blank lines and lines starting with ; or # are ignored.

sitl : The SITL to run. If no path component is given, fl2sitl assumes it may be found on $PATH.
eeprom-path : The path to find eeproms.
default-eeprom : The default eeprom to use (if --eeprom is not given)
simport : The UDP port for the emulated X-Plane protocol. The default is 49000, which is what the SITL expects.
failmode : How to treat failsafe, default is ignore; other options are nopulse (recommended) or a throttle value (in us), e.g. 800.
simip : The name of the machine running fl2sim, e.g. localhost, eeyore.daria.co.uk, ::1, fe80::18b0:85ff:fe48:a70f, 127.0.0.1, i.e. a known host name, an IPv6 address or an IPv4 address.

For example:

$ cat $HOME/.config/fl2x/fl2sitl.conf
# SITL-sim settings

sitl = inav_6.1.0_SITL
eeprom-path = $HOME/sitl-eeproms
default-eeprom = fw-eeprom.bin

# failmode = nopulse / ignore / Throttle value (default is ignore)
# failmode = 800
# failmode = ignore

failmode = nopulse

simip = localhost

Environment variables will be expanded for sitl and eeprom-path as required.

SITL Configuration

The SITL "eeprom" must be configured to support the replay requirement. As you can have multiple EEPROMS, you may wish to have a specific EEPROM for use with fl2sitl, as it requires specific settings that may not the compatible with other use cases (e.g. with a real TX or joystick).

The following settings are known to work:

# features
feature GPS
feature VBAT

# Ports
serial 0 1 115200 115200 0 115200
serial 1 1 115200 115200 0 115200

# Modes [aux]
## As needed for the modes used by your BBL ###

set acc_hardware = FAKE
set mag_hardware = NONE
set baro_hardware = FAKE
set gps_provider = FAKE
set vbat_meter_type = FAKE
set current_meter_type = FAKE
set receiver_type = MSP
set rssi_source = MSP
set align_mag = CW270FLIP

# After the first usage, this saves startup time (c. 15 seconds)
set init_gyro_cal = OFF

## In order for recovery from FAILSAFE to be recognised reliably
set failsafe_stick_threshold = 0

You can configure the SITL eeprom with the INAV Configurator, or via the CLI using mwp's cliterm or other any IP "telnet" like tool, e.g.:

# In one shell terminal (tab)
$ inav_6.1.0_SITL --path $HOME/sitl-eeproms/fw-eeprom.bin
# In a second shell terminal (tab)
# cliterm -d tcp://localhost:5760
# Or, if you don't use mwptools
### netcat
# nc localhost 5760
### or even telnet
$ telnet localhost 5760
Trying ::1...
Connected to localhost.
Escape character is '^]'.

In the case of (nc, telnet) or similar, you will need to type # and Enter to get to the SITL CLI, cliterm does this automagically.

Note that fl2sitl uses the receiver type and map as set in the SITL FC. If ALLOW_BYPASS is set , fl2sitl asserts full right rudder while arming.

fl2sitl provides emulation for the following RC control protocols:

MSP (default)
SBUS
IBUS
CRSF
JETIEXBUS

The RX type is read from the SITL eeprom, as is the channel map. Please note that RX telemetry is not possible, as the SITL cannot by itself provide it (interaction with the RX is typically necesary). If you recompile the SITL with RX telemetry enabled, you may see the data from the FC on the UDP port equivalent to the RX serial port (e.g. UDP localhost:5762 for UART3).

Having the required modes set in the SITL is important, as fl2sitl needs to send switch settings to the inav_SITL as flight modes (from the BBL) are transposed into switch settings (with are then sent to the SITL as MSP RC TX values), according to the modes defined for the SITL FC.

Architecture

The following diagram shows the relationship between the Blackbox log file, blackbox_decode, fl2sitl, inav_SITL and the visualisation.

+------------------+
|   Blackbox Log   |
+--------+---------+     +------------------------------+
         |               |                              |
 +-------v-------+       |            fl2sitl           |
 |               |  CSV  |                              |
 |blackbox_decode+------>|                              |
 |               |(pipe) |                              |
 +---------------+       |  +------+        +-------+   |
                         |  |  UDP |        |  TCP  |   |   +-------------------+
                         +--+---+--+--------+-+---^-+---+   |   Visualisation   |
                                |             |   |         |                   |
                   X-Plane      |        MSP  |   |  MSP    |        MWP        |
               Sensor Procotcol |       Status|   | TX/RX   | INAV Configurator |
                                |             |   |         |Some other MSP tool|
                         +--+---v--+--------+-v---+-+---+   |                   |
                         |  |  UDP |        |  TCP  |   |   +---------^---------+
                         |  +------+        | UART2 |   |             |
                         |                  +-------+   |             |
                         |                              |             |
                         |                      +-------+             |
                         |         INAV_SITL    |  TCP  |             |
                         |                      | UART1 +-------------+
                         |                      +-------+
                         |                              |
                         +------------------------------+

Installation

From version 1.0.7, fl2sitl is released as part of the bbl2kml project. Prior to that, it was necessary to install from source.

Clone the bbl2kml repository
cd bbl2kml
Follow the build instructions

Sample Visualisation Images

Soon after start of mission

Start

Near the end of log (after WP, Failsafe, PH, RTH and Cruise Modes)

End

Images

INAV 8.0.0 (master)

Executable SITL images for various OS (from INAV master, 2024-04-27, INAV 8.0.0 SITL (e92337a5). This does NOT include a standalone ser2tcp as this SITL includes this function.

OS / Arch	Notes
FreeBSD / amd64	Built on FreeBSD 14.0, gcc 13.2.1
Linux / arm64	Built on Arch, gcc 12.1
Linux / amd64	Built on Alpine 3.19, gcc 13.2.1, static
Linux / ia32	Built on Alpine 3.19, gcc 13.2.1, static
Linux / riscv64	Built on Arch, gcc 13.2.1
Windows / amd64	Built on Windows 10, gcc 11.4
MacOSX / amd64	Built on MacOSX 10.15.7, gcc 11

INAV 7.1.0

Executable SITL images for various OS (from INAV release_7.1.0, 2024-03-11, INAV 7.1.0 SITL (bc45aa74). Not the final release, but close enough. This includes a standalone ser2tcp.

OS / Arch	Notes
FreeBSD / amd64	Built on FreeBSD 14.0, gcc 13.2.1
Linux / arm64	Built on Arch, gcc 12.1
Linux / amd64	Built on Alpine 3.19, gcc 13.2.1, static
Linux / ia32	Built on Alpine 3.19, gcc 13.2.1, static
Linux / riscv64	Built on Arch, gcc 13.2.1
Windows / amd64	Built on Windows 10, gcc 11.4
MacOSX / amd64	Built on MacOSX 10.15.7, gcc 11.3

INAV_SITL Notes:

The MacOSX INAV_SITL is will not arm due to invalid settings. This is due to my ancient MacOS VM / compiler.
Linux ia32/x86_64 builds are statically linked and thus have no dependencies and should run on any distro.
The Configurator only supports SITL on Linux and Windows on AMD64 (x86_64). For Linux IA32 (i586), it is necessary to use the binaries here above, as the official Configurator only ships 64bit SITLs. See below for installation. No solution is available for Windows IA32, as Cygwin32 is EOL / discontinued).

Each archive contains, inter-alia:

inav_X.Y.0_SITL{.exe} : The SITL executable

Note that these files are "bug for bug" replacements for the perhaps older / less efficient inav_SITL{.exe} distributed with the INAV Configurator. e.g. (Configurator installed in /opt/inav/inav-configurator/:

cp inav_x.y.z_SITL /opt/inav/inav-configurator/resources/sitl/linux/inav_SITL

Then run fl2sitl --minimal to provide a minimal simulator, in the Configurator, set the UDP port to 49000 (or add -listen :49001 to the fl2sitl invocation). Once you have the eeprom (e.g. $HOME/.config/inav-configurator/Default/standard-x-plane.bin configured correctly (required port, serialrx and provider), you can run the SITL via the Configurator with a real RX/TX.

For example, real IBUS RX connected to a USB-TTL device ("CP2102 USB to UART Bridge Controller" on /dev/ttyUSB0.

INAV 6.1.0 SITL
[SYSTEM] Init...
[SIM] Waiting for connection...
[SOCKET] xplane address = [::1]:49001, fd=6
[SIM] Connection with X-Plane successfully established.
[EEPROM] Loaded '/home/jrh/.config/inav-configurator/Default/standard-x-plane.bin' (32768 of 32768 bytes)
[SOCKET] Bind TCP :: port 5760 to UART1
[SOCKET] Bind TCP :: port 5761 to UART2
[SOCKET] Bind TCP :: port 5762 to UART3
[Serial2TCP] Connect /dev/ttyUSB0 to [::1]:5762
[SOCKET] ::1 connected to UART3

Remote operation

It is not necessary to run fl2sitm and inav_6.1.0_SITL on the same machine. In the example below we run fl2sitm on host eeyore and inav_6.1.0_SITL on host wol. ##<n>## indicates a note expanded later.

`fl2sitl` host

[jrh@eeyore]$ fl2sitl --verbose 3  --nostart /t/inav-contrib/logfs.TXT                ##<1>##
Flight   :  on 2019-02-08 15:21:13
Firmware : INAV 2.1.0 (7bdd5967e) OMNIBUSF4V3 of Jan 22 2019 09:39:17
Size     : 32.03 MB
Log      : logfs.TXT / 1
[fl2sitm] 11:34:19.594859 Conf = {sitl:inav_6.1.0_SITL ip:localhost port: path:$HOME/sitl-eeproms eeprom:fw-eeprom.bin mintime:100 failmode:53456}
...
[fl2sitm] 11:35:49.596537 Got connection [aaaa:bbbb:cccc:0:eeee:ffff:cccc:eeee]:49469 ##<2>##
...
[fl2sitm] 11:35:51.763916 RC init done                                                ##<3>##
...
[fl2sitm] 11:35:55.388629 ** Ready to arm (Press 'A' to arm) **
...
[fl2sitm] 11:36:01.777696 Armed
[fl2sitm] 11:36:01.777765 Mode change <> => <Angle>
...
[fl2sitm] 11:36:11.781475 Stats 20s: Tx: 173 RSSI 37 Stats 172 (0)
[fl2sitm] 11:36:11.804217 Quit                                                        ##<4>##
[fl2sitm] 11:36:11.804238 Disarming ...
[fl2sitm] 11:36:11.804253 DisArming on chan 10 at 1002
[fl2sitm] 11:36:16.805048 Cleanup ...
[fl2sitm] 11:36:19.305644 Done

`inav_6.1.0_SITL` host

#  Starting the SITL on "wol" .... with "sim" running on "eeyore"                     ##<5>##
jrh@wol]$ inav_6.1.0_SITL --path ~/sitl-eeproms/fw-eeprom.bin --simip eeyore --sim xp
INAV 6.1.0 SITL
[SYSTEM] Init...
[SIM] Waiting for connection...
[SOCKET] xplane address = [aaaa:bbbb:cccc:dddd:eeee:ffff:aaaa:bbbb]:49000, fd=3
[SIM] Connection with X-Plane successfully established.
[EEPROM] Loaded '/home/jrh/sitl-eeproms/fw-eeprom.bin' (32768 of 32768 bytes)
[SOCKET] Bind TCP :: port 5760 to UART1
[SOCKET] Bind TCP :: port 5761 to UART2
[SOCKET] aaaa:bbbb:cccc:dddd:eeee:ffff:aaaa:bbbb connected to UART2                   ##<6>##
[SOCKET] aaaa:bbbb:cccc:dddd:eeee:ffff:aaaa:bbbb disconnected from UART2              ##<7>##

Notes

IP addresses obfuscated.

Use --nostart so no local SITL is started
A connection (X-Plane UDP) is instigated from the remote SITL
Initialised, user ready to "Arm"
RX/TX stats confirm normal operation
Start the remote SITL with the sim xp (X-Plane protocol) and the name (or IP) for the "simulator" (fl2sitl) host (eeyore).
fl2sitl has connected its TX to UART2
(some time later). fl2sitl disconnected the TX from UART2 as part of its shutdown.

Other Notes

The INAV SITL runs out of the box on Linux (at least x86_64, ia-32, aarch64, riscv64) as well as FreeBSD and Windows (only tested on amd64).

fl2sitl will run on any OS / hardware for which there is a Golang (cross) compiler.

The INAV SITL prefers gcc / GNU linker for compilation and a libc that provides a POSIX / BSD Socket API. Cygwin is used on Windows. On MacOS, the Apple provided "gcc" (which is really "clang") is used; however the MacOS linker does not provide the same options as the GNU linker, and the SITL cannot save settings correctly.

FAQs

fl2sitl never reaches "Ready to Arm" : With -verbose 3 you will probably see that the arming flags are stuck on 0x420, which means "Overload". Your CPU is too weak to run the SITL. This should not happen with the SITLs provided above (release_6.1.0 from 2023-03-28), now working on 2009 vintage ia32 Intel Atom N270 1.6GHz
Running a BBL with a mission, WP mode is never reported: Most likely you have failed to upload the mission into the SITL.
Running a BBL that includes FAILSAFE, the SITL never reports recovery. : Most likely you have not set failsafe_stick_threshold = 0. The BBL does not include the recovery stick movement.

Use with the INAV Configurator

For INAV 6.1.0 and later, the INAV Configurator provides a SITL tab and SITL connection option.

If no "Simulator" is chosen, runtime calibration will not complete.
If you use a 32bit OS (Linux, Windows), then the INAV Configurator supplied 64bit binaries will not work. For Linux 32bit, they may be replaced by the binaries from this archive, following the instructions at the link.

If you want to have the full SITL experience, and do not have the 'X-Plane' or 'RealFlight' applications, you can use fl2sitl to provide quiescent sensors without a BBL.

Use the --listen 49001 and --minimal options. If you wish to fake a location, --rebase lat,lon; for example:

fl2sitl -listen 49001 -minimal -rebase 35.76100,140.378945

Note it is necessary to use a "point" decimal separator, even in locales where "comma" is customary (Golang lack of numeric localisation, alas). It may also be necessary to use Arabic numerals, even in locales where Hindi numerals are customary.

Configurator SITL Usage

Configurator SITL

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fl2sitl

fl2sitl

Overview

Usage

Runtime behaviours

`fl2sitl`

Visualisation or analysis tool

Command Keys

Sample Session

Configuration

`fl2sitl` Configuration File

SITL Configuration

Architecture

Installation

Sample Visualisation Images

Soon after start of mission

Near the end of log (after WP, Failsafe, PH, RTH and Cruise Modes)

Images

INAV 8.0.0 (master)

INAV 7.1.0

Remote operation

`fl2sitl` host

`inav_6.1.0_SITL` host

Notes

Other Notes

FAQs

Use with the INAV Configurator

Configurator SITL Usage

Clone this wiki locally

fl2sitl

fl2sitl

Overview

Usage

Runtime behaviours

fl2sitl

Visualisation or analysis tool

Command Keys

Sample Session

Configuration

fl2sitl Configuration File

SITL Configuration

Architecture

Installation

Sample Visualisation Images

Soon after start of mission

Near the end of log (after WP, Failsafe, PH, RTH and Cruise Modes)

Images

INAV 8.0.0 (master)

INAV 7.1.0

Remote operation

fl2sitl host

inav_6.1.0_SITL host

Notes

Other Notes

FAQs

Use with the INAV Configurator

Configurator SITL Usage

Clone this wiki locally

`fl2sitl`

`fl2sitl` Configuration File

`fl2sitl` host

`inav_6.1.0_SITL` host