docs/SITL/SITL.md

   1 # SITL
   2
   3 ![INAV-SIM-OSD](assets/INAV-SIM-OSD.png)
   4
   5 ## ATTENTION!
   6 SITL is currently still under development.
   7
   8 SITL (Software in the loop) allows to run INAV completely in software on the PC without using a flight controller and simulate complete FPV flights.
   9 For this, INAV is compiled with a normal PC compiler.
  10
  11 The sensors are replaced by data provided by a simulator.
  12 Currently supported are
  13 - RealFlight  https://www.realflight.com/
  14 - X-Plane https://www.x-plane.com/
  15 - fl2sim [replay Blackbox Log via SITL](https://github.com/stronnag/bbl2kml/wiki/fl2sitl), uses the X-Plane protocol.
  16
  17 INAV SITL communicates for sensor data and control directly with the corresponding simulator, see the documentation of the individual simulators and the Configurator or the command line options.
  18
  19 AS SITL is still an inav software, but running on PC, it is possible to use HITL interface for communication.
  20
  21 INAV-X-Plane-HITL plugin https://github.com/RomanLut/INAV-X-Plane-HITL can be used with SITL.
  22
  23 ## Sensors
  24 The following sensors are emulated:
  25 - IMU (Gyro, Accelerometer)
  26 - GPS
  27 - Pitot
  28 - Magnetometer (Compass)
  29 - Rangefinder
  30 - Barometer
  31 - Battery (current and voltage), depending on simulator
  32
  33 ![SITL-Fake-Sensors](assets/SITL-Fake-Sensors.png)
  34
  35 Select "FAKE" as type for all mentioned, so that they receive the data from the simulator.
  36
  37 ## Serial ports
  38 UARTs are replaced by TCP starting with port 5760 ascending. UART1 is mapped to port 5760, UART2 to 5761, etc.
  39
  40 By default, UART1 and UART2 are configured for MSP connections. Other UARTs will have TCP listeners if they have an INAV function assigned.
  41
  42 To connect the Configurator to SITL, select "SITL".
  43
  44 Alternativelly, select "TCP" and connect to ```localhost:5760``` (or ```127.0.0.1:5760``` if your OS doesn't understand `localhost`) (if SITL is running on the same machine).
  45
  46 IPv4 and IPv6 are supported, either raw addresses or host-name lookup.
  47
  48 The assignment and status of used UART/TCP connections is displayed on the console.
  49
  50 ```
  51 INAV 6.1.0 SITL
  52 [SYSTEM] Init...
  53 [SIM] No interface specified. Configurator only.
  54 [EEPROM] Loaded 'eeprom.bin' (32768 of 32768 bytes)
  55 [SOCKET] Bind TCP :: port 5760 to UART1
  56 [SOCKET] Bind TCP :: port 5761 to UART2
  57 [SOCKET] ::1 connected to UART1
  58 ```
  59
  60 All other interfaces (I2C, SPI, etc.) are not emulated.
  61
  62 ## Remote control
  63 Multiple methods for connecting RC Controllers are available:
  64 - MSP_RX (TCP/IP)
  65 - joystick (via simulator)
  66 - serial receiver via USB to serial converter
  67 - any receiver with proxy flight controller
  68
  69
  70 ### MSP_RX
  71
  72 MSP_RX is the default, 18 channels are supported over TCP/IP connection.
  73
  74 ### Joystick interface
  75 Only 8 channels are supported.
  76
  77 Select "SIM (SITL)" as the receiver and set up a joystick in the simulator.
  78
  79 *Not available with INAV-X-Plane-HITL plugin.*
  80
  81 ### Serial Receiver via USB
  82
  83 - Connect a serial receiver to the PC via a USB-to-serial adapter
  84 - Configure the receiver in the SITL as usual
  85 - While starting SITL from configurator, enable "Serial receiver" option
  86
  87 The SITL offers a built-in option for forwarding the host's serial port to the SITL UART.
  88
  89 Please note that 100000(SBUS) and 420000(CRSF) are non-standart baud rates which may not be supported by some USB-to-serial adapters. FDTI and CH340 should work. CP2102/9 does not work.
  90
  91
  92 #### Example SBUS:
  93 For this you need a USB-to-serial adapter, receiver with inverter, or receiver which can output inverted SBUS (normal UART).
  94
  95 SBUS protocol is inverted UART.
  96
  97 Receiver's SBUS output should be connected to the USB-to-serial adapter's RX pin (via inverter).
  98
  99 With FT-Prog (https://ftdichip.com/utilities/) the signal can be inverted by adapter: Devices->Scan and Parse, then Hardware Specific -> Invert RS232 Signals -> Invert RXD.
 100
 101 ![SITL-SBUS-FT232](assets/SITL-SBUS-FT232.png)
 102
 103 ![SITL-SBUS](assets/serial_receiver_sbus.png)
 104
 105 ### Telemetry
 106 In the SITL configuration, enable serial receiver on some port and configure receiver type "Serial", "SBUS".
 107
 108 #### Example CRSF:
 109
 110 On receiver side, CRSF is normal UART.
 111
 112 Connect receiver's RX/TX pins (and GND, 5V of course) to USB-To-Serial adapter's TX/RX pins (RX to TX, TX to RX).
 113
 114 ![SITL-SBUS](assets/serial_receiver_crsf.png)
 115
 116 In the SITL configuration, enable serial receiver on some port and configure receiver type "Serial", "CRSF".
 117
 118 ### Proxy Flight controller
 119
 120 The last, but probably the most easiest way to connect receiver to the SITL, is to use any inav/betaflight Flight controler as proxy.
 121
 122 Connect receiver of any type to FC and configure FC to the point where channels are correctly updated in the "Receiver" tab. Inav and Betaflight are supported.
 123
 124 You also can use your plane/quad ( if receiver is powered from USB).
 125
 126 ![SITL-SBUS](assets/serial_receiver_proxy.png)
 127
 128 In the SITL configuration, select "Receiver type: SIM" regardles of the kind of receiver used.
 129
 130
 131 ## OSD
 132 For the OSD the program INAV-Sim-OSD is available: https://github.com/Scavanger/INAV-SIM-OSD.
 133 For this, activate MSP-Displayport on a UART/TCP port and connect to the corresponding port.
 134
 135 Note: INAV-Sim-OSD only works if the simulator is in window mode.
 136
 137 *With INAV-X-Plane-HITL plugin, OSD is supported natively.*
 138
 139 ## Command line
 140
 141 The command line options are only necessary if the SITL executable is started by hand.
 142
 143 There is also a SITL tab in the  INAV Configurator (6.1.0 and later).
 144
 145 The following SITL specific command line options are available:
 146
 147 If SITL is started without command line options, only a serial MSP / CLI connection can be used (e.g. Configurator or other application) can be used.
 148
 149 ```--path``` Path and file name to config file. If not present, eeprom.bin in the current directory is used. Example: ```C:\INAV_SITL\flying-wing.bin```, ```/home/user/sitl-eeproms/test-eeprom.bin```.
 150
 151 ```--sim=[sim]``` Select the simulator. xp = X-Plane, rf = RealFlight. Example: ```--sim=xp```. If not specified, configurator-only mode is started. Omit for usage with INAV-X-Plane-HITL plugin.
 152
 153 ```--simip=[ip]``` Hostname or IP address of the simulator, if you specify a simulator with "--sim" and omit this option IPv4 localhost (`127.0.0.1`) will be used. Example: ```--simip=172.65.21.15```, ```--simip acme-sims.org```, ```--sim ::1```.
 154
 155 ```--simport=[port]``` Port number of the simulator, not necessary for all simulators. Example: ```--simport=4900```. For the X-Plane protocol, the default port is `49000`.
 156
 157 ```--useimu``` Use IMU sensor data from the simulator instead of using attitude data directly from the simulator. Not recommended, use only for debugging.
 158
 159 ```--chanmap=[chanmap]``` The channelmap to map the motor and servo outputs from INAV to the virtual receiver channel or control surfaces around simulator.
 160 Syntax: (M(otor)|S(ervo)<INAV-OUT>-<RECEIVER_OUT>),..., all numbers must have two digits.
 161 Example:
 162 To assign motor1 to virtual receiver channel 1, servo 1 to channel 2, and servo2 to channel 3:
 163 ```--chanmap:M01-01,S01-02,S02-03```
 164 Please also read the documentation of the individual simulators.
 165
 166 ```--serialport``` Use serial receiver or proxy FC connected to host's serial port, f.e. ```--serialportCOM5``` or ```--serialportdev/ttyACM3```
 167
 168 ```--serialuart``` Map serial receiver to SITL UART, f.e. ```--serialuart=3``` for UART3. Omit if using ```--fcproxy```.
 169
 170 ```--baudrate``` Serial receiver baudrate (default: 115200)
 171
 172 ```--stopbits=[None|One|Two]``` Serial receiver stopbits (default: One)
 173
 174 ```--parity=[Even|None|Odd]``` Serial receiver parity (default: None)
 175
 176 ```--fcproxy``` Use inav/betaflight FC as a proxy for serial receiver.
 177
 178 ```--help``` Displays help for the command line options.
 179
 180 For options that take an argument, either form `--flag=value` or `--flag value` may be used.
 181
 182 ## Running SITL
 183 It is recommended to start the tools in the following order:
 184 1. Simulator, aircraft should be ready for take-off
 185 2. SITL
 186 3. OSD
 187
 188 For INav-X-Plane-HITL plugin:
 189 1. SITL (Run in configurator-only mode)
 190 2. X-Plane
 191
 192 # #Forwarding serial data for other UART
 193
 194 Other UARTs can then be mapped to host's serial port using external tool, which can be found in directories ```inav-configurator\resources\sitl\linux\Ser2TCP```, ```inav-configurator\resources\sitl\windows\Ser2TCP.exe```