c:\work
c:\work\central
c:\work\esim
c:\work\rmax
The GTMax software is in direct support of the flight-testing of SEC research products on the Yamaha R-Max Industrial helicopter, as instrumented at The Georgia Institute of Technology. Currently, the software project consists of the simulation (helicopter and sensor models), the Ground Control Station (GCS), and the baseline onboard routines. The entire software package runs under Windows and has also been used on Linux. The onboard components run under QNX. That is, those intended to run onboard the helicopter. The simulation can be run as a single executable, with all components (listed above) running. This configuration is referred to as the Software-in-the-Loop (SITL) simulation. Here, all hardware (including the helicopter itself, sensors, etc.) is simulated to level of its digital communication to other components, enabling rigorous software testing without requiring any actual flight hardware. Alternatively, the simulation, GCS, and onboard code can be run on separate machines as needed. For example, this can be done to support various Hardware-in-the-Loop (HITL) test configurations. In the flight configuration, the GCS runs on a laptop computer and the onboard code runs on the onboard computer under QNX. The onboard code routines can be operated within an Open Control Platform (OCP) implementation as multiple OCP components. This software is part of an ongoing research program, and is constantly being improved to support ongoing tests.
This document is intended to support GTMax software developers in development within the SITL simulation or other offline software testing. Once satisfied with performance in the SITL environment, transition to HITL testing and flight test is enabled.
To speed development, the previously-developed ESim simulation environment is used to produce a Graphical User Interface (GUI) for otherwise-basic C/C++-code. To accomplish this, a code generator (dbp.exe) is used to process *.db “database” files. Three files are created: (1) *_ref.h which contains c-structure definitions and external references to global data, (2) *_def.c which contains instances, and (3) *_db.c which contains comments and other information which allows esim.lib to act as simulation control, a debugger, plot routines, etc. Only (1) and (2) are used when operating onboard the helicopter or as OCP components. Developers of OCP components can use the ESim environment to make changes to the baseline system, or may chose not to use it at all – and instead make changes to the generated (readable) C/C++ code. Either way, it is intended that GTMax developers would not modify dbp.exe and esim.lib.
The GTMax onboard code supports the five onboard sensors (IMU, GPS, sonar altimeter, magnetometer, radar altimeter), two datalinks (wireless serial and wireless Ethernet), and three interfaces to the helicopter (receiver commands, attitude sensor, and miscellaneous vehicle health information). The GCS is also equipped to read differential correction data from a GPS reference system and send it to the helicopter. The onboard code also has baseline navigation and flight control subroutines (navigation.cpp, controller.cpp, network.cpp, planner.cpp) that are implemented as OCP components (low-level flight control). The onboard code is a subset of the included source tree, and includes:
controller.cpp, controller_ref.h,
controller_def.c,
controller.h
datalink.cpp, datalink.h
ether.cpp, ether.h
matrix.cpp, matrix.h
navigation.cpp, navigation_ref.h, navigation_def.c, navigation.h
network.cpp, network.h
onboard.cpp, onboard_ref.h, onboard_def.c, onboard.h
planner.cpp, planner.h
rmaxconfig.h
serial.cpp, serial.h
Navigation.cpp
The baseline navigation system fuses information from the five related sensors (GPS, IMU, sonar, radar, and magnetometer) to provide vehicle position, height above terrain, velocity, acceleration, attitude, and angular velocity data at 100Hz. It is an Extended Kalman Filter (EKF) with 17 states (position, velocity, attitude quaternion, gyro biases, accelerometer biases, and terrain height variation).
The system is still being tested, optimized, and improved – but some very preliminary accuracy figures for the system are included here for planning purposes only (standard deviations, steady state reached long after initial calibration for a typical flight):
1 ft position (error has little high frequency content)
0.1 ft/sec velocity
0.5 deg roll/pitch
2 deg heading
5 deg/sec angular velocity
1 ft/sec acceleration
No air data sensors or wind velocity estimation are currently included.
The navigation software also estimates whether the helicopter is on the ground or in the air by estimating the height of the helicopter above the ground and assuming it is on the ground if this height is below the threshold value.
The software supports replacement of the navigation system output with truth data from the simulation when operating in the SITL configuration, to support the development of flight controller software.
controller.cpp, network.cpp
The baseline flight controller determines actuator commands (three swash-plate servos, tail rotor servo, and throttle servo) based on the navigation system output, and a position/velocity/attitude command. It utilizes a neural network adaptive flight controller, described in [Johnson, Kannan, AIAA-2002-4439]. It can also be configured as a non-adaptive controller.
planner.cpp
The guidance system determines position/velocity/attitude commands for the flight controller as a function of time based on a prescribed flight plan (with special provisions for takeoff and landing).
serial.cpp, ether.cpp
The data communication routines are used to manage serial ports (e.g., sensors) and for communications over the wireless data links to the GCS. They are quite flexible, and any link can be configured to work over serial line, Ethernet, or within the same executable as a memory copy (utilized extensively for the software-in-the-loop SITL mode).
datalink.cpp
The datalink software provides the connection to the GCS to/from the onboard software. It is optimized to minimize bandwidth use (for example, by sending “float”s instead of “double”s where possible) and to support sending data over both wireless links to provide redundancy. A number of message types are supported. Currently, a 10Hz message sent to the GCS provides rapid-update status and current state information. A 1Hz message provides other significant onboard data.
Bring up the $GTUAVLAB/rmax.dsw workspace in developer studio. Select the "rmax" project. Execute. Note: If you do not already have glut32.dll, you will need to put the included glut32.dll file in your path
Three windows come up: (1) ESim: 0 (2) Panel (3) Scene Window 0
Simulation control happens from the “ESim” window. The buttons are (in order) Init, pause, start, step (execute simulation for 0.01 seconds), open a data browser window, open a plotting window, exit, open a scene window, open the panel window. Input files (<file>.inp) can be run by typing @<file>. config.inp is automatically run at start up. Simulation time in seconds is the number in the window title.
Panel is a status indicator for a number of subsystems.
The scene window is a 3-d graphic data-visualization system. The blue helicopter represents navigation/GCS data. The red helicopter is the truth (directly from the helicopter model). A maximum of 3 windows can be opened once.
Data browser windows (when one is opened) can be used to view all simulation data, edit it, or to specify any data for plotting. A maximum of 3 browser windows can be opened at once.
Plot windows are where real-time plotting is viewed. A maximum of 3 plot windows can be opened at once.
Right clicking in the various windows (except ESim) causes a pop-up menu.
Two items must be completed to operate the navigation system: (1) setting of a datum for navigation information and the location of the GPS reference station, and (2) triggering an initialization sequence of the navigation system prior to takeoff. When operating in the SITL simulation, the first step is normally not required because the default settings are satisfactory. The initialization triggering happens automatically when the simulation is initialized. However, the initialization of the navigation system must be allowed to finish before a takeoff is initiated. The initialization sequence length default setting is 5 seconds. The status of the navigation system (initializing or running) is indicated on the status panel. The system can be (re)initialized anytime the helicopter is on the ground by typing “navInit” at the ESim console. If truth data is used instead of processed navigation data, then the initialization is irrelevant.
The flight controller does not require any specific configuration or initialization. The controller is training the neural network at all times, even when the helicopter is flown manually. All internal states of the controller can be reset by typing “controlInit” at the ESim console.
A flight plan (typically waypoints) is entered at the GCS, or loaded from a script. This then uploaded to the helicopter with the “trajUpload” command or by a button on the ESim console. Once the trajectory is uploaded, the “trajGo” command intiates the execution of the trajectory. When the end of the trajectory is reached, the guidance system stops sending new position/velocity/attitude commands (and so the helicopter will hover). At any point, the “trajStop” command can be used to stop the execution of the flight plan and the helicopter will smoothly stop and hover.
To enter waypoints from the GCS, an input file can be used to set waypoint parameters (maneuver[0] through maneuver[9]). Alternatively, a scene window can be used. Pressing the “-“ and “=” keys scrolls through the waypoints (initially there is only one). To un-select waypoints and return to the normal scene generation, press the shift key and either the “-“ or “=” key at the same time. A new point is added by the insert key. The point is moved up, down, north, east, south, and west with the “U”, “D”, “N”, “E”, “S”, “W” keys respectively (note capitalization, and so the shift key must be pressed at the same time). The “R” and “L” key change the specified heading right and left – and the “A” key caused heading to be chosen automatically to point along the velocity vector. The “V” and “C” keys increase and decrease velocity to the waypoint respectively. The “T” key toggles through the transition possibilities. The “M” key changes the maneuver type, currently supporting waypoints and landing.
Input files are text files given the “.inp” extension, and are executed by including an @ before the file name at the ESim console (e.g. @flightplan executes the text file flightplan.inp). They can include any command that can be typed in at the ESim console. Most significantly, parameters can be set in an input file by including the directory global name followed by a dot and then the variable name (e.g. gcsSet.datumLat = 33.773030 in an input file sets the datum latitude). Input files can call other input files.
To plot a variable, locate the variable in a browser window. Then highlight the variable by left clicking on it (it will be highlighted in yellow). Then right click to get the pop-up menu. In the menu, select plot window to place the variable. If no x-axis variable is selected, simulation time is used (sim.time).
Right click in the plot window for a pop-up menu which contains several scaling functions, and the ability to save the plot data as a text file or Matlab file.
“Datalink” indicates the status of the two wireless datalinks.
“Navigation” indicates the mode of the navigation system
“GPS” indicates the mode of the GPS
“Sonar” indicates the status of the sonar
“Radar” indicates the status of the radar
“Compass” indicates if the magnetometer data is being read
“Autopilot” indicates if the autopilot is on (vs. the helicopter flown manually)
“Frames” indicates if IMU data is being thrown away, which indicates that the computer is being overloaded
“Battery” indicates if the onboard battery voltage is within selected limits
“Pilot Tx/Rx” indicates if the safety pilot radio is being properly received
“Fuel” indicates low fuel level
“YCS” indicates reception of Yamaha Control System data from the helicopter
“YRD” indicates reception of Yamaha Receiver Data from the helicopter
“Data Record” indicates status of the onboard data recording system
“Traj Upload” indicates if the GCS copy of the flight plan has been modified, and requires uploading
“Trajectory” indicates the mode of the guidance system, either executing the current flight plan or “stopped” (helicopter hovering)
The color scheme is dark green for normal, and bright green for an alternate normal situation. Yellow indicates a significant variation from normal operation that could affect safety of flight. Red indicates a failure condition.
Right click on a scene window to alter the view perspective (cockpit, 2-D nav, chase, etc.). The camera can be moved forward, backward, left, right, up, and down with the “f”, “b”, “l”, “r”, “u” and “d” keys. The “i” and “o” keys zoom in and out respectively. The pop-up menu also allows several visualizations to be added (body axes, velocity vector, etc.). The “lookat” submenu allows selection of viewing GCS data (received from the onboard systems), truth data (from the helicopter model), or both. Only GCS data is available during a flight test. GCS helicopter state data is used to draw a blue helicopter, and truth data is used to draw a red helicopter. Both helicopters are down for the “both” configuration, which is the default.
Contains is the root of all variables in the gtmax simulation. It includes variables regarding the graphical environment, vehicle model, scene generation, simulaton interface, and variables used in the primary flight computer, secondary flight computer and ground control station.
| esim | Simulation engine variables |
| vehicle | vehicle dynamics variables, aerodynamics, rigid body equations etc. |
| scenes | scene generator variables, to set textures on/off colours etc for scene window |
| si | contains models of sensors, imu, sonar, radar etc.. |
| onboard | contains navigation and controller components |
| onboard2 | contains variables used in onboard2.cpp for code that runs on secondary flight computer |
| gcs | ground control station variables including packets that are recevied at ground station |
| stresstest | stress test settings that taxes the network (for internal use at GIT) |
Contains vehicle model outputs in convenient format. Not all variables in this are available for feedback.
Contains estimated vehicle state and is essentially the output of the navigation filter. These variables are available for feedback.
| p_b_e_L[],v_b_e_L[],a_b_e_L[] | Position, velocity and acceleration of body with respect to earth expressed in local frame (north, east and down position) |
| w_b_e_L[] | Angular velocity of body with respect to earth expressed in local frame |
| q[] | Attitude quaternion |
| altitudeAGL | altitude above ground |
| rpm | main rotor rpm |
| dcm_bl[][] | 3,3 body to local rotation matrix (note in literature the convention is to write L_lb to represent body to local conversion, note reversal of subscripts) |
| dcm_lb[][] | 3,3 local to body rotation matrix (note in literature the convention is to write L_bl to represent local to body conversion, note reversal of subscripts) |
Contains the variables used by the sensor drivers that read the sensors from serial ports. Going deeper into each sensor driver tree will allow one to examin the actual packets coming through the serial port
<!--msthemelist-->
The main directory used by the trajectory generator. man[0...9] are the way point directories.
| delm[], delf[], delt[] | actuator commands that are actually
passed to vehicle.
If autopilot is on these are same as c_delm, c_delf,
c_delt |
| c_delm[], c_delf[], c_delt[] | controller output, if autopilot is on, the above variables will be same as delm,delf,delt |
UDP packet containing helicopter state and other information being sent to secondary computer.
The software may be downloaded from Boeing's CITIS website if
you are on the SEC
program. To get the latest distribution with sources email suresh_kannan@ae.gatech.edu
or eric.johnson@ae.gatech.edu.
All software code variables are held in a tree structure who's root looks like the above picture in the browser window. Any variables developed using Gatech's database files (or .db files) show up in this browser. For example /root/vehicle contains variables used for the vehicle model, root/onboard contains variables used in the primary flight computer and root/onboard2 contains variables used on the secondary flight computer.
During SITL all the code executes on the same computer as a single thread. For example look at the simTick() function in rmax/main.cpp and you will see calls such as updateOnboard(), updateOnboard2() which essentially execute the code that go on the two flight computers. updateOnboard() function exists in onboard.cpp and is only modified by gatech. The updateOnboard2() function resides in onboard2.cpp and usually contains calls to external code by external researchers. For flight, different main functions are used for example rmax/mainob.cpp is used to execute updateOnboard() on the primary flight comptuer and rmax/mainob2.cpp is used to execute updateOnboard2() on the secondary flight computer.
Hence, during simulation on your desktop, if you place your function call (to a trajectory planner or custom controller) in updateOnboard2() it will get executed, and the same code is compiled in for flight.
As a quick start to executing the sample external trajectory generator do the following
The first waypoint moves the vehicle 200 ft north and once there, switches to the second waypoint which is of type MAN_EXT (value shows up as 6), this will cause onboard1 to take commands from the second flight computer (onboard2) i.e., generated by the extTraj function in onboard2.cpp. After an indication to move to the next waypoint is received, the third waypoint is executed causing the vehicle to move south 200ft.
Path planning the gtmax happens after waypoints are specified, a kinematics based trajectory generator is used to generate a smooth trajectory. The waypoints are usually loaded using input files and are store in onboard2/trajectory/man[0],..man[i] upto 20 waypoints. The type of the waypoint dictates the type of trajectory that will be generated in order to get to the waypoint. For example onboard2/trajectory/man[0].type = 2, specifies that the vehicle should pass through the waypoint whereas type = 1 will cause it to cut corners with a certain acceleration. For example look in square.inp. Remember that you can have upto 20 waypoints and sometimes an input file can have upto 20 in them but the variable lastIndex = n specifies the actual number used.