GTMax and OCP integration tutorial

It is assumed that the GTMAX simulation environment is setup and compiled in the $GTUAVLAB directory, which on our systems at the UAV Lab normally corresponds to the c:\work directory. Although it could really be placed anywhere. It is also assumed that the OCP is installed in $OCP_ROOT directory.

gtmaxocp.zip gtmaxocp.zip with the workspaces already generated

The above file contains the latest version of the GTMax-OCP interface example and the GtmaxLink component. Unzip this file into the $GTUAVLAB directory.

We will now use the provided GtmaxLink OCP component to talk to the helicopter in a software in the loop simulation and develop a very simple trajectory generator component that provides commands to the helicopter.

Overview and the GtmaxLink component

cd $GTUAVLAB/gtmaxocp. Open and examine the ComponentInfo.txt file. The file describes a system of the form shown in the block diagram below.

The primary flight computer is represented by the "onboard1" box and the secondary flight computer where all SEC research algorithms run is represented by "onboard2". A custom UDP link is used to talk between onboard1 and onboard2. However, SEC researchers do not need to be concerned with this link. Instead, an OCP component called GtmaxLink is provided which encapsulates the communication to onboard1 (the primary flight computer). Users need only to use the GtmaxLink component description and associated data strucutres, GtmaxState and GtmaxCommand, the descriptions of which are given in the sample ComponentInfo.txt file. The GtmaxLink component has 2 inputs, the (a) S/W trigger called tirggerIn, (b) CommandInput called commandIn and one output the GtmaxState called stateOut. The GtmaxLink component is time triggered periodically using a software trigger (triggerIn port) to check for packets from the onboard computer. When a new packet is received from onboard1 via UDP, the GtmaxState (stateOut port) is sent out to all OCP components in the system that have registered for it. Additionally, when the GtmaxLink component receives a GtmaxCommand (commandIn port), a corresponding UDP packet is sent to the primary flight computer (onboard1).

GtmaxState structure description

A description of the elements in the GtmaxState data structure is given below. This is the the primary source of information for all OCP based algorithms. Many status and other flags are also present. The variables marked as (internal) are subject to removal or change. The variables marked as (sec) are expected to remain unchanged and is intended for use by the SEC community.

char navStatus

char gpsStatus

char sonarStatus

char radarStatus

char magnetStatus

char overrun

char wow

char autopilot

char lavoid

double time

double x

double y

double z

double vx

double vy

double vz

double q1

double q2

double q3

double q4

double p

double q

double r

double rpm

double altitudeAGL

GtmaxCommand Description

The primary method of commanding the GTMax is by populating the GtmaxCommand structure and indicating what kind of command it is. This command should be sent to the GtmaxLink component, which in turn relays it to the primary flight computer.

type

double x

double y

double z

double vx

double vy

double vz

double q1

double q2

double q3

double q4

double p

double q

double r

double delm1

double delm2

double delm3

double delf

GTMAX_TRAJ_COMMAND configuration:

This implies that your algorithm produces a trajectory which the helicopter is required to follow. In this case the default trajectory generator built into the primary flight computer will be bypassed and only the baseline autopilot will be used. The expected inputs to the autopilot are the commanded positions (x,y,z), velocity (vx,vy,vz), attitude (q1,q2,q3,q4), and angular rate (p,q,r). These essentially correspond to [pc, vc, qc, wc] in the publications that describe the baseline flight control system.

GTMAX_ACTUATOR_COMMAND configuration:

This is where actuator commands are sent the helicopter via the primary flight computer. Most aspects of the primary flight computer are bypassed apart from checks and limits imposed on the command.

SimpleTrajectoryGenerator Example

The use of the GtmaxLink to control and interact with the helicopter is illustrated using an example that commands a desired trajectory. A component called SimpleTrajectoryGenerator will be developed and hooked up using the GtmaxLink to the GTMax simulation environment in the Windows environment. Once tested using the GTMax simulation environment little or no integration apart from compiling for QNX is required to execute on actual flight computers.

Prerequisites :

	You must have already successfully built and run the GTMax SITL environment. See Here. This will make sure you have the correct directories and include paths setup in your VC++ environment.
	You must have already successfully installed and built the OCP 2.2. See OCP Documentation
	Extract the gtmaxocp example into the $GTUAVLAB directory
	Make sure you have Perl and Java installed as per the OCP installation directions.
	Also verify that $GTUAVLAB/central is in your operating system path.

For the following steps we assume that the GTMax simulation environment is installed in $GTUAVLAB, which in our case corresponds to c:\work. Hence our directory looks like.

$GTUAVLAB/central
$GTUAVLAB/esim
$GTUAVLAB/rmax
$GTUAVLAB/gtmaxocp

The final form of what we are planning to achieve is provided in the gtmaxocp directory which contains the datalink as well as the completed version of the Simple Trajectory Generator example.

Note if you do not wish to go through the tutorial but rather just build and run the integration example quickly. Download the zip file with work spaces already generated. Just load up the gtmaxocp.dsw project workspace instead and build the OCP executable. Then, go to the following step, with the caveat that in the instructions regard anything involving "stg" as "gtmaxocp".

Step 1) We will create our OCP interface and simple trajectory generator in a directory called "stg" which stands for simple trajectory generator. Hence,

mkdir $GTUAVLAB/stg
cd $GTUAVLAB/stg
copy $GTUAVLAB/gtmaxocp/ComponentInfo.txt $GTUAVLAB/stg
copy $GTUAVLAB/gtmaxocp/RateGroupInfo.txt $GTUAVLAB/stg

Step 2) The component info file contains essentially the wire-up diagram and the rategroup file contains information that describes the rates that different threads are running at. Links to these two file are provided here for convenience (ComponentInfo.txt, RateGroupInfo.txt). Note the GtmaxState, GtmaxCommand data structure descriptions, and the description of the GtmaxLink component. Verify that the component info file describes a wire up as shown below.

Step 3) Now the component info and rategroup files will be used to generate XML descriptions. Using the OCP back end tool: translate the files generated in step 1 to XML using compinfo2xml.pl and rategroupinfo2xml.pl, as shown below. Note that for the first tool compinfo2xml one must provide a project name which in our case was stg.

perl %OCP_ROOT%/Tools/ControlsAPI_BackEnd_XML/release/compinfo2xml.pl stg ComponentInfo.txt ComponentInfo.xml
perl %OCP_ROOT%/Tools/ControlsAPI_BackEnd_XML/release/rategroupinfo2xml.pl RateGroupInfo.txt RateGroupInfo.xml

Note due to a bug in the conversion script the componentinfo.xml file is not generated correctly. A fix for this is available but must be obtained from Boeing.A fix for this is available but must be obtained from Boeing.

Step 4) OCP code may be generated using xml2ocp.pl as explained in the OCP documentation.

perl %OCP_ROOT%/Tools/ControlsAPI/release/compinfo2xml.pl gtmaxocp ComponentInfo.txt ComponentInfo.xml

Step 5) At this point the two components SimpleTrajectoryGenerator and GtmaxLink are generated as empty shell code that has to be populated. The GtmaxLink.[h,cpp] is already coded and provided by the georgia tech uavlab to facilitate integration with the GTMax. So just copy over the the existing GtmaxLink.h and GtmaxLink.cpp from the gtmax directory into the ComponentDatabase directory, thus overwriting the empty shell code just generated.

perl %OCP_ROOT%/Tools/ControlsAPI/release/rategroupinfo2xml.pl RateGroupInfo.txt RateGroupInfo.xml
perl %OCP_ROOT%/Tools/ControlsAPI/release/xml2ocp.pl ComponentInfo.xml RateGroupInfo.xml

This copying process need only be done once for the first time. Any subsequent regenerations of OCP code from the xml files, will not destory the GtmaxLink code since all relevant code is within the user preserved regions. Links to this code are provide here GtmaxLink.h and GtmaxLink.cpp.

Step 6) Now open $GTUAVLAB/stg/stg.dsw workspace in Microsoft Visual Studio.We will now populate the trajectory generator with the simple equations that generate an open loop circular trajectory.

In the above equations the position of the helicopter when the maneuver is started (by running the ocp executable) is denoted by x0,y0,z0. The equations are written in terms of the speed during the maneuver V, and angular rate \omega around x0,y0,z0. Since this is an open loop maneuver, it is parameterized using time t, that is available from the GtmaxState structure. The trajectory is bounded and oscillatory.These equations are implemented in the SimpleTrajectoryGenrator.[h, cpp] files. Copy them from the

copy $GTUAVLAB/gtmaxocp/ComponentDatabase/SimpleTrajectoryGenerator.h $GTUAVLAB/stg/ComponentDatabase/SimpleTrajectoryGeneratorh
copy $GTUAVLAB/gtmaxocp/ComponentDatabase/SimpleTrajectoryGenerator.cpp $GTUAVLAB/stg/ComponentDatabase/SimpleTrajectoryGenerator.cpp

Step 7) Now in the ProcessP1Main.cpp file that contains the main function. Add the following code to enable command line arguments that makes it easier to change the parameters of the trajectory and also most importantly allows one to point the ocp executable to the computer that contains the simulation.

// User specified arguments - Preserve Region
else if ( ( currentArg = argShifter.get_the_parameter("-gtmax") ) )
{
GtmaxLink::SetFlightComputerName(CORBA::string_dup(currentArg));
argShifter.consume_arg();
}
else if ( ( currentArg = argShifter.get_the_parameter("-V") ) )
{
SimpleTrajectoryGenerator::V = atof(CORBA::string_dup(currentArg));
argShifter.consume_arg();
}
else if ( ( currentArg = argShifter.get_the_parameter("-omega") ) )
{
SimpleTrajectoryGenerator::omega = atof(CORBA::string_dup(currentArg));
argShifter.consume_arg();
}
// User specified arguments - End Preserve Region

Hence the executable may be run as for example

stg_process1 -gtmax javelin -V 10 -omega .5

This starts up the trajectory generator with a maneuver speed of 10 ft/s and revolution rate of 0.5 rad/s. Additionally, the -gtmax command line option points the executable to communicate with the host name "javelin". On the GTMax this is the name of the primary flight computer (onboard1). However this may also point to the computer that runs the simulation environment. In order to setup the software environment to listen to the ocp generated trajectory one must point its communications port to the right computer and setup a few flags and will be explained below.

Note in the following instructions the hostnames javelin, pointer etc., correspond to our computers at the UAV Lab and must be replaced with yours hostnames. If both the simulation environment and OCP are running on the same host they can be the same hostnames.

Step 8) Go to stg_Process1 project settings and in Link/ObjectLibrary Modules add the following two libraries for linking

esimd.lib rmaxlibd.lib

esimd.lib comes in compiled form and rmaxlibd.lib is built when the GTMax simulation environment is built. Both libraries reside in $GTUAVLAB/central. Now, build the OCP trajectory generator executable.

Step 9) Startup the simulation environment type in the following commands or run it from an input file.

onboardPortIPC.dataSource = 1
onboardPortIPC.connectTo=pointer
onboardPortIPC.init = 1

In the above script the simulation is told to treat the host name "pointer" as the secondary flight computer (onboard2), where the ocp executable will run. If you wish to run from an input file...just save these commands in a file like $GTUAVLAB/rmax/teststg.inp. From the simulation environment you may just type in @teststg before initializing and hitting play.

Type in the following to get the helicopter into hover.

init
trajUpload
trajGo
<Hit the Play button>

The helicopter should after some time be in hover at around 30 ft of altitude. Now startup the trajectoryGenerator executable from

cd $GTUAVLAB/stg/Process1/Debug_CXX
stg_process1 -gtmax javelin -V 10 -omega .5

At this point everything is ready to go...but the simulation has to be told to start sending state packets to the secondary flight computer and we must also indicate to the primary flight computer to use the commands sent from the secondary computer.

1) Type in trajGo2 in the simulation environment to enable the primary flight computer to accept trajectory commands
2) Using the variable browser, set the onboard/datalink/set/sendIPC0 flag to 1. This sends state commands to the secondary flight computer

At this point the helicopter should start performing the trajectory commands generated by the OCP executable.