-
Notifications
You must be signed in to change notification settings - Fork 4
fl2sitl
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 quietest 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 has been 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.
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.
Once executed, fl2sitl
- Creates the X-Plane protocol socket
- Invokes
INAV_SITL
with parameters from the configuration file. - Creates the
MSP-RX
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-RX with stick data
- Updates the MSP-RX with RSSI
Once the SITL is ready (MSP-RX 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'.
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 : Quitsfl2sitl
(and disarms if necessary), terminates the SITL.
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 connectedmwp
totcp://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 instructfl2sitl
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 indicatesfl2sitl
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.
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 isignore
; other options arenopulse
(recommended) or a throttle value (in us), e.g.800
. -
simip
: The name of the machine runningfl2sim
, 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.
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
set nav_extra_arming_safety = ALLOW_BYPASS
# 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 receiver_type = MSP
with a map of AERT
(MSP RX default). fl2sitl
assumes that ALLOW_BYPASS
is set and asserts full right rudder while arming.
fl2sitl
provides emulation for the following TX:
- MSP (default)
- SBUS
- IBUS
- CRSF
- JETIEXBUS
The TX 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 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).
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 +-------------+
| +-------+
| |
+------------------------------+
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
Executable SITL images for various OS (from INAV release_6.1.0
, 2023-05-08, INAV v6.1.0 SITL (572b223bc)
)
OS / Arch | Notes |
---|---|
FreeBSD / amd64 | Built on FreeBSD 13.2, gcc 13.0.1 |
Linux / arm64 | Built on Arch, gcc 12.2 |
Linux / amd64 | Built on Alpine 3.18, gcc 12.2, static |
Linux / ia32 | Built on Alpine 3.18, gcc 12.2, static |
Linux / riscv64 | Built on Arch, gcc 12.2 |
Windows / amd64 | Built on Windows 10, gcc 11.3 |
MacOSX / amd64 | Built on MacOSX 10.15.7, gcc 11.3 |
Executable SITL images for various OS (from INAV master
, 2023-05-25, INAV v7.0.0 SITL (69bd3e9d) API 2.5
)
OS / Arch | Notes |
---|---|
FreeBSD / amd64 | Built on FreeBSD 13.2, gcc 13.0.1 |
Linux / arm64 | Built on Arch, gcc 12.2 |
Linux / amd64 | Built on Alpine 3.18, gcc 12.2, static |
Linux / ia32 | Built on Alpine 3.18, gcc 12.2, static |
Linux / riscv64 | Built on Arch, gcc 12.2 |
Windows / amd64 | Built on Windows 10, gcc 11.3 |
MacOSX / amd64 | Built on MacOSX 10.15.7, gcc 11.3 |
Note:
-
The MacOSX version is experimental / unstable; it will not arm due to invalid settings.
-
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. For Linux ia32, it is necessary to use the binaries here above, as the official Configurator only ships 64bit SITLs. 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 -
ser2tcp{.exe}
: A serial to TCP bridge, suitable for using a real RX/TX with the SITL. The examples shipped here are the svelte 'C' versions.
Note that these files are "bug for bug" replacements for the perhaps older / less efficient inav_SITL{.exe}
and [sS]er2TCP{.exe}
distributed with the INAV Configurator.
e.g. (Configurator installed in /opt/inav/inav-configurator/
:
cp ser2tcp /opt/inav/inav-configurator/resources/sitl/linux/ser2TCP
-
cp inav_6.1.0_SITL /opt/inav/inav-configurator/resources/sitl/linux/inav_SITL
(or inav_7.0.0_SITL if required) cd /opt/inav/inav-configurator/resources/sitl/linux && rm -f Ser2TCP && ln ser2TCP Ser2TCP
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
Note that it may take the SITL a second or two to open the required "serial" socket and the Configurator supplies the device description rather than a device node, which ser2tcp
has to enumerate.
In this instance, ser2tcp
was invoked by the configurator as:
./resources/sitl/linux/ser2TCP --comport=CP2102 USB to UART Bridge Controller --baudrate=115200 --stopbits=One --parity=None --ip=localhost --tcpport=5762
i.e. it runs from the Configurator installed directory (as installed above), the updates ser2tcp
resolves the device description to a device node.
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.
[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
# 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>##
IP addresses obfuscated.
- Use
--nositl
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.
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 linker does not provide the same options as the GNU linker, and the SITL cannot save settings correctly.
-
fl2sitl
never reaches "Ready to Arm" : With-verbose 3
you will probably see that the arming flags are stuck on0x420
, 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.
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 wish to use a real TX/RX, then you need a serial to TCP bridge. At least on Linux, the supplied bridge may not work and may be replaced by the
ser2tcp
from this archive, following the instructions at the link. - 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.