HITL

2018-03-14T23:47:25Z

Podhrmic:

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Simulation</categorytree>
__TOC__

=Hardware In The Loop Simulation=

Hardware In The Loop (HITL) simulation is a way to test an embedded system (the real hardware and software) by simulating its environment, ie. sensor inputs, and comparing its output, ie. actuator outputs, to expected output values. It is the closest to an actual flight without actually flying. Using Paparazzi's [[Simulation|Software In The Loop]] (SITL) and HITL for validation of a flight dynamics of a fixed wing UAV is in detail described in a paper [http://digitalcommons.usu.edu/cgi/viewcontent.cgi?article=1109&context=mae_facpub "Software-and hardware-in-the-loop verification of flight dynamics model and flight control simulationof a fixed-wing unmanned aerial vehicle"] by Cal Coopmans and Michal Podhradsky. Refer to the paper for more details.

==Principle==
While the [[Simulation|SITL]] simulation executes the airborne code on the ground host, HITL is a way to run the autopilot code on the actual hardware in an environment where sensors and actuators are simulated. The difference is shown in diagrams below: SITL generates the physical behavior of the airplane from the Flight DynaMics (FDM) Block, then feeds the generated values into virtual sensors, the sensor inputs are processed in the autopilot and the autopilot control ouputs are captured and fed back into the FDM. HITL does the same, except it communicates with the autopilot over serial ports.

In HITL, two separate processes are involved:
* The real autopilot code on the control board with its own IO (for example battery voltage, etc);
* A flight model combined with a model of the actuators and the sensors.
Commands computed by the autopilot are sent to the flight model which sends back simulated values of the sensors output.

[[File:Sitl.png|550px|thumb|right|Software-in-the-loop (SITL) autopilot testing block diagram]]
[[File:Hitl.png|600px|thumb|right|Hardware-in-the-loop (HITL) autopilot testing block diagram]]

==Limitations==
'''Update March 2018: HITL currently works only with Pprzlink 1.0, please recompile paparazzi with PPRZLINK_LIB_VERSION=1.0. We are working on a fix.'''

For practical reasons (it is very difficult to simulate SPI/I2C devices such as accelerometer, gyroscope etc.), Paparazzi HITL simulates only sensors that connect to the autopilot via serial port (for example GPS unit, or an external AHRS/INS). Currently implemented is [https://wiki.paparazziuav.org/wiki/Sensors/IMU#Vectornav_VN-200 Vectornav VN-200] in [[Subsystem/ins|INS]] mode, but other sensors and modes can be added (i.e. VN-200 as [[Subsystem/imu|IMU]], [[Sensors/IMU#Xsens_MTi_and_MTi-G_.28with_GPS.29|Xsens INS]] etc.). Because the benefit of HITL is to test the autopilot code that is identical to the actual flight code, no other means of transporting sensor data to the autopilot are currently supported (such as sending them through uplink).

Another consideration is the bandwidth of the system - the sensor data and the actuator values have to be send/received at PERIODIC_FREQUENCY (between 40-512 Hz) for HITL to work correctly.

==When to use SITL and when HITL?==
The advantage of SITL is that it is easy to deploy and test, because no additional hardware is needed. This means that simulation is very self-contained. Ideally use for testing flight plans, or initial tuning of airframes. SITL can run faster than real time.

HITL is the simulation closest to real flight, because both the hardware and the code are identical to the set being used in real flight–the autopilot is really flying with artificial sensor data. HITL is used to test the flight hardware, once the flight plan and initial tuning has been configured. Usually HITL is the last thing to run before going flying.

==Prerequisites==
HITL currently (Ubuntu 16.04) needs the following two steps to run correctly:
* set rtpriority for the uart threads [https://stackoverflow.com/questions/8111302/why-does-pthread-setschedparam-produce-eperm-on-opensuse-11-4 detailes here] by adding these two lines to your ''/etc/security/limits.conf'' file:
<source>
domain type item value
$USER soft rtprio 100
$USER hard rtprio 100
</source>
where ''$USER'' is your username

* install ''pyserial'' package (needed for SBUS Fakerator), typically with ''sudo install pyserial''

==Configuration==
HITL can currently run on any [[Category:Autopilots|autopilot]] that has:
* Serial port for Vectornav INS input (provides position and orientation data, including GPS coordinates)
* Serial port for additional high-speed telemetry output (so not your regular 57600 telemetry)
* other serial/io for regular telemetry, RC input etc.

If you have high-speed telemetry (like over WiFi) it should be possible to use only one telemetry link and demux the messages on GCS, but it is not currently supported. Note that HITL is timig sensitive (at 512Hz you need to receive, process, and send data every ~2ms).

HITL has been tested on:
* Lisa M/MX (exampes for [https://github.com/paparazzi/paparazzi/blob/master/conf/airframes/AGGIEAIR/aggieair_minion_rp3_lia.xml fixedwing] and [https://github.com/paparazzi/paparazzi/blob/master/conf/airframes/AGGIEAIR/aggieair_ark_hexa_1-8.xml rotorcraft])
* Umarim v 2.0 (example for [https://github.com/paparazzi/paparazzi/blob/master/conf/airframes/AGGIEAIR/El_Captain.xml fixedwing])

We recommend a dedicated computer for HITL, with enough CPU power and memory, and a nice graphics card for [[FlightGear]] visualisation (see the test station in the picture). HITL can run on a regular laptop too (tested on both Lenovo Thinkpad and Toughbooks).

[[File:HITL_station.jpg|600px|thumb|right|Hardware-in-the-loop (HITL) test station in simulated flight]]

There are a few exaple airfames to choose from. Let's start with a fixed wing airplane and walk you through step by step. Get a [[Installation|fresh copy]] of the latest paparazzi and do:

<source>
# in prrz root dir
./start.py
</source>

and choose AggieAir's conf and control panel:

[[File:Aggieair conf.png|300px|frame|center|Select AggieAir's conf and control panel and then Launch]]

Choose '''Minion_RP3''' airframe:

[[File:Minion rp3 airfame.png|900px|thumb|center|Minion RP3 airfame]]

and click on Edit. The airframe file is on github: https://github.com/paparazzi/paparazzi/blob/master/conf/airframes/AGGIEAIR/aggieair_minion_rp3_lia.xml For HITL to work, there have to be 4 things:

# [https://github.com/paparazzi/paparazzi/blob/master/conf/modules/extra_dl.xml extra_dl] telemetry module
# specified COMMANDS (Fixedwing) or ACTUATORS (rotorcrafts) Extra telemetry message in the telemetry config file (an example [https://github.com/paparazzi/paparazzi/blob/master/conf/telemetry/AGGIEAIR/aggieair_fixedwing.xml#L108 here]
# HITL target
# Airframe configured to use external INS

=== Extra_DL module ===
This is the additiona high speed telemetry link that sends the actuators data back to the FDM.
<source>
# in your airfame config file
<module name="extra_dl">

<define name="REMAP_UART1" value="TRUE"/>
<configure name="EXTRA_DL_PORT" value="UART1"/>
<configure name="EXTRA_DL_BAUD" value="B921600"/>
</module>
</source>

If you have [[Umarim_Lite_v2|Umarim]] board or similar, you can also use a usb serial port:
<source>
# in your airfame config file
<module name="extra_dl">
<configure name="EXTRA_DL_PORT" value="usb_serial"/>
<configure name="EXTRA_DL_BAUD" value="B921600"/>
</module>
</source>

=== Telemetry config file ===
Just add this section to your telemetry config file:
<source>
# in your telemetry config file
<process name="Extra">
<mode name="default">
<message name="COMMANDS" period="0.01"/>
</mode>
</process>
</source>

The period has to be matching your '''PERIODIC_FREQUENCY''' - best if you explicitly define all the frequencies to avoid ambiguity:
<source>
# in your airfame config file

<configure name="PERIODIC_FREQUENCY" value="100"/>
<define name="CONTROL_FREQUENCY" value="100"/>
<configure name="TELEMETRY_FREQUENCY" value="100"/>
<define name="SERVO_HZ" value="100"/>
</source>

NOTE: the '''TELEMETRY_FREQUENCY''' has to match your '''PERIODIC_FREQUENCY'''

=== HITL target ===
Add the target in your airfame config file:
<source>
# in your airfame config file
<target name="hitl" board="pc">
<module name="fdm" type="jsbsim"/>
<configure name="INS_DEV" value="/dev/ttyUSB1"/>
<configure name="INS_BAUD" value="B921600"/>
<configure name="AP_DEV" value="/dev/ttyUSB2"/>
<configure name="AP_BAUD" value="B921600"/>
</target>
</source>

What does it mean? First, we have to specify the FDM for the HITL simulation. We recommend [[JSBSim]], but any FDM that [[NPS]] supports should work (because NPS is the backend for HITL).

Then we have to specify the serial ports to talk to the autopilot. '''INS_DEV''' is the port your external [[Subsystem/ins|INS]] (such as Vectornav) is using. '''AP_DEV''' is the port for the extra telemetry. Make sure your baud rates are matching too.

Note that you can either specify the devices in '''/dev/ttyUSB*''' format, which makes it universal across different USB-to-serial converters, but you have to remember to plug in the ports in the right order (since they enumerate sequentially).

The other option is to specify the ''' /dev/serial/by-id/usb-FTDI_*****''' format, in which case it doesn't matter in which order you plug the devices in, but you can use it only for a particular FTDI converter.

It might be handy to use a simple Lia breakout board for connecting all the serial ports - the breakout board files are available [https://github.com/paparazzi/paparazzi-hardware/tree/master/controller/lia/breakout_board here].

[[File:Liabreakoutboard.jpeg|500px|thumb|center|Lia breakout board]]

=== Airframe configuration for external INS ===
Indeed, HITL will work only if your aiframe is configured to use external INS of some sort. In our example, we specify using Vectornav:

<source>
# in your airfame config file
<module name="ins" type="vectornav">
<configure name="VN_PORT" value="UART2"/>
<configure name="VN_BAUD" value="B921600"/>
</module>
</source>

See the [https://github.com/paparazzi/paparazzi/blob/master/conf/airframes/AGGIEAIR/aggieair_minion_rp3_lia.xml Minion_RP3 airframe config] for more details.

== Running ==
Once you have your setup completed:

# Clean, compile and upload the ''AP'' target (HINT: use keyboard shorcuts '''Alt+C''' to '''Clean''', '''Alt+B''' to '''Build''' and '''Alt+U''' to '''Upload''')
# Clean and build ''HITL'' target
# Choose '''HITL USB-serial@57600''' session and Execute

NOTE: If you want to use your own session, you have to pass ''-t hitl'' flag into ''sw/simulator/pprzsim-launch'' to start in HITL mode. Have a look at the [https://github.com/paparazzi/paparazzi/blob/master/conf/airframes/AGGIEAIR/aggieair_control_panel.xml#L126 HITL USB-serual@57600] session for example, or add this to your own:

<source>
# in your control_panel.xml file
<session>
...
<program name="Simulator">
<arg flag="-a" constant="@AIRCRAFT"/>
<arg flag="-f" constant="127.0.0.1"/>
<arg flag="-b" constant="127.255.255.255"/>
<arg flag="--fg_fdm" constant=""/>
<arg flag="-t" constant="hitl"/>
</program>
...
</session>
</source>

Messages will pop up and you can verify that you are getting data by looking at the VECTORNAV_INFO message:
[[File:Hitl messages.png|thumb|center|VECTORNAV_INFO message]]

And once you take-off you will see something like this:
[[File:Hitl flight.png|1000px|thumb|center|HITL Flight with fixedwing airplane]]

Similar steps work for rotorcraft.

=== SBUS fakerator ===
A simple tool simulating SBUS radio inputs is available. It is useful if you don't have a radio around, and want to test flight in manual mode. It has to be used with a [https://github.com/paparazzi/paparazzi/blob/master/conf/radios/AGGIEAIR/aggieair_sbus_fakerator.xml Sbus_fakerator radio config file] and it requires an additional serial port (for example ''/dev/ttyUSB3''). It can be launched as a tool from the Paparazzi center.

Source code is available at: https://github.com/paparazzi/paparazzi/tree/master/sw/tools/sbus_fakerator

[[File:Sbus fakerator.png|thumb|center|SBUS fakerator tool]]

=== Flight Gear ===
We strongly recommned running HITL with [[FlightGear]] for visualisation. The steps are the same as when running [[NPS]] targets, please refer for documentation there.

== Issues ==
If you find a problem, please contact out gitter channel or file an issue on github ([https://github.com/paparazzi/paparazzi/issues here])

<big>Happy flying!</big>

[[File:Minion_HITL.png|600px|center|Minion in the air]]

[[Category:Simulation]] [[Category:Software]] [[Category:Hardware]] [[Category:Developer_Documentation]]

HITL

HITL

2017-07-19T16:00:21Z

2017-07-19T14:59:00Z

Podhrmic: