Advanced Rotorcraft Technology, Inc
Last updated: Thursday 08 August 2002, 14:29
The following are the minimum system requirements for running PilotStation on a PC:
On the SGI platform, the recommended configuration is:
If a multicomputer configuration is to be used, an ethernet hub is required. Each computer must also have an ethernet card, even for single-host configurations, as the FlexLM license manager used by PilotStation uses the Ethernet MAC address to determine a host ID.
Full PilotStation releases are distributed with several installation options:
Installation from the tar file is appropriate if you wish to keep several versions of PilotStation installed. It may also be convenient in a multi-host environment to extract the tar file onto a single computer and export the directory via NFS or Samba to other hosts on the local area network.
The Demonstration CD-ROM has a 30 day demonstration license included in the license key file. Production versions will be issued a node-locked license key.
To register PilotStation, run the following command on each of the computers for which PilotStation is to be licensed:
# On Windows: %PWS_DIR%\bin\win32\flmreg register # On Unix: $PWS_DIR/bin/hosttype/flmreg register
This will create a file named hosts.dat. E-mail this file to ART at license@flightlab.com; ART will send back a license file, which should be saved as license.dat in the PilotStation installation directory. ART will keep a record of all registered hosts, so it is only necessary to perform this step once.
To drive the PilotStation display from a FLIGHTLAB math model, the following options should be specified in the configuration file:
[MAIN] ownship=flcomms
First start PilotStation. Next, from within X/Analysis, load a model and select the [Simulation|Run] menu item. Note that PilotStation must be running on the local host before activating the Simulation dialog box.
In a networked environment, a copy of PilotStation must be running on the same host as the math model, even if that host does not have a graphics display.
For FLIGHTLAB versions prior to 2.9, specify ownship=cdb, instead of ownship=flcomms.
To drive the PilotStation display from a code generated model, the following options should be specified in the configuration file.
[MAIN] ownship=local
Before starting PilotStation, set the environment variable $SSM_MODEL_DIR to the directory containing the object code for the desired model (Shared Object Libraries (.so) for Unix and Linux versions and Dynamically Linked Libraries (.dll) for Windows versions.)
The PilotStation distribution contains several different executables for each platform, each targeting a different GVS rendering API. Depending on the operating system, these may include:
To start the program, run
$PWS_DIR/bin/platform/vis-gfxtype -c filename.cfgwhere:
The configuration file is structured as a Windows-style .INI file. It is divided into sections. Each section begins with a line containing the section name in square brackets, followed by a list of option=value pairs.
A pound sign (#) or semicolon (;) at the beginning of a line indicates a comment.
Some of the PilotStation facilities require additional auxilliary configuration files; these are referenced from the main configuration file. Options which specify a file name may include environment variable references, prefixed with a dollar sign ($).
The GVS initialization file (default: gvsinit.gvc) specifies the terrain to be loaded and other graphical models. An example is shown below.
#
# $Id: gvsinit.gvc,v 1.7 2001/12/12 19:47:35 joe Exp $
#
echo [ OpenGVS executing command procedure $0 ]
if !defined PWS_DIR setenv PWS_DIR .
#--------------------------------------------------------------
# OWNSHIP configuration
#--------------------------------------------------------------
setenv GVM $PWS_DIR/gvm/misc
setenv TXTPATH $GVM
import file=$GVM/ah64.gvm name=OWNSHIP
#--------------------------------------------------------------
# TERRAIN configuration
#--------------------------------------------------------------
setenv TERRAIN_DIR $PWS_DIR/gvm/misc
setenv TXTPATH $TERRAIN_DIR
setenv TERRAIN $TERRAIN_DIR/new_terrain.gvm
setenv POSITION "(0,-700,0)"
echo "Importing terrain database $TERRAIN"
import file=$TERRAIN \
geometry=on name=TERRAIN surface=TERRAIN \
position=$POSITION
echo "Loaded terrain database $TERRAIN"
#*EOF*#
The main purpose of the GVS initialization file is to load model files to be displayed at runtime with import commands:
import file="filename" name=name [ other options... ]
filename specifies the object file to load. Supported file formats include MultiGen OpenFlight (.flt), and OpenGVS encrypted models (.gvm).
name is the internal name by which PilotStation refers to the object. The following object names must be defined:
position tells PilotStation to bias the terrain coordinates by the values assigned to this field. If the bias is set to (0,0,0) the terrain coordinate frame is collocated with FLIGHTLAB's inertial coordinate frame so the bias moves the terrain reference frame relative to FLIGHTLAB's inertial frame as desired. The coordinates are given in the visual system reference frame. In this frame x is positive right, y is positive up, and z is positive out of the screen.
PilotStation has five prinicipal operating states:
The following keyboard commands are available:
The overall simulation may be controlled from buttons or switches on certain pilot input devices. Individual buttons may be bound to PilotStation commands in the [CONTROLBOX.BUTTONS], [JOYSTICK.BUTTONS], or [NEXTMOVE.BUTTONS] configuration sections, depending on the selected input device.
The syntax of entries in this section is:
+button-number = action -button-number = action button-number = simvar
button-number is the number of a digital input. Buttons are numbered starting from 0. + indicates a leading-edge transition, and - is a trailing-edge transition. ``action'' is any PilotStation command; see below for a partial list. If neither + nor - is specified, the button value (1 or 0) will be written to the specified simulation variable.
For example,
[MAIN] pilotin=controlbox [CONTROLBOX.BUTTONS] +0 = fly -0 = pause +6 = reset
makes button 0 (the pushbutton in the upper-left corner) a fly/pause toggle, and button 6 (the momentary switch in the lower-left corner) a reset switch.
The available actions are:
A simulation may be distributed over several hosts by using the PilotStation network facility. Set network=on in the [MAIN] configuration section to enable networked operations.
A station is a collection of PilotStation processes driven by a common math model (OWNSHIP) and pilot input source (PILOTIN). It is possible for multiple stations to coexist on the same local area network, by setting the station parameter in the [NETWORK] configuration file section.
PilotStation supports a variety of pilot input devices for proportional control. The device to use is specified by the pilotin parameter in the [MAIN] configuration section. The following devices are available:
If the pilot input source has any discretes (switches, pushbuttons, or toggle switches), then the simulation variables BTN0 through BTNn will be set, where n is the highest-numbered discrete input supported by the device. Each variable will be set to 1.0 if the switch is on, 0.0 if it is off. Buttons may be bound to variables other than BTNn in the corresponding [.BUTTONS] section.
The PilotStation control box is a special-purpose hardware device supplied by ART for providing pilot inputs to a Unix or Linux host. It is a 3-axis controller (lateral, longitudinal, and directional) with two auxilliary analog channels and 9 digital inputs. The left lever is used as the collective; the right lever is currently unused in PilotStation but may be configured to work as a throttle or a brake lever in a future release.
The control box communicates with the host through a serial port. The port configuration option in the [CONTROLBOX] section specifies the serial port to use. On Linux this is typically /dev/ttyS0 or /dev/ttyS1; on IRIX it is usually /dev/ttydN. If port is not specified in the configuration file, the $FBPORT environment variable will be used instead.
Additional functions may be bound to the digital inputs in the [CONTROLBOX.BUTTONS] configuration section as explained in 3.2. ``Controlling PilotStation actions from external discretes''. Discrete inputs BTN0 through BTN8 may be passed to a FLIGHTLAB model as described in 9. ``Simulation variables''.
To test if the control box is working properly, use the command:
readstick -v -F /dev/ttyNNN
This will run readstick, an application that stores Control Box outputs in the SGIO CDB (common data block), a shared memory block formerly used by FLIGHTLAB. The -v option enables verbose mode, so the user can see digital readouts of the analog and discrete channels.
You will need to make sure that the serial port device file is world-readable and -writable, and that the operating system is not running a login process on that port. This step requires root permissions, but it only needs to be done once.
Examine the file /etc/inittab and look for a line like one of the following:
NNN:123:respawn:/sbin/getty ttyNNN
(Depending on the system configuration, mingetty, mgetty, agetty, uugetty, or some other variant may appear instead of getty.) If such a line is present, change the third field from respawn to off, and send a HANGUP signal to the init(1) process to cause it to re-read the inittab file:
kill -HUP 1
Next make sure that the device is world-readable and world-writable:
chmod 666 /dev/ttyXXX
Normally this change will persist after a reboot, but some versions of Unix re-create the device special files whenever the system starts up. If this is the case, consult a local guru.
This option is only available on PC hardware. with a NextMove [tm] PCI card. On Linux, NextMove PCI support requires an additional device driver which is available from ART under the GNU Library General Public License.
Configuration options are specified in the [NEXTMOVE] configuration section. The following are available:
The specification of the card's location depends on the card type:
The following additional options are available for either card type:
If the NEXTMOVE driver is active, the simulation variables ADC0 through ADC7 will be set to the values of the NextMove ADC channels 0 through 7.
Note that the collective and pedals may not support force feedback on all hardware platforms. In this case, these parameters will be ignored.
PilotStation will set the following MINT COMMS array values:
The MINT program file should backdrive the controls to the trim positions when the simulation is in reset mode (COMMS[10] = 2). Trim positions are in scaled units (default range [-1.0 .. 1.0]).
NOTE --This function should be performed by PilotStation directly, but at present this is the responsibility of the MINT program file.
Standard PC joystick support is available on Windows and Linux platforms. On Linux, the device parameter in the [JOYSTICK] configuration section specifies the joystick device to use (default /dev/js0). There are no further configuration options on Windows.
A 4-axis joystick such as the Microsoft Sidewinder [reg] Precision Pro is recommended.
To configure the joystick under Windows, select [Start|Settings|Control Panel] and select the [Game Controllers] option.
PilotStation can display any combination of the following channels:
The primary channel to display is specified by the view option in the [MAIN] configuration section; it must be one of OTW, OSV, or IPANEL.
There are two ways to specify the configuration of the the Out-The-Window ([OTW]) pilot's-eye channel and outside view ([OSV]) channels. The configuration mode is selected by the configmode option. If configmode is set to channel, then you must also specify the shear, twist and angle-of-view directly. If configmode is set to monitor, then you must specify the location and dimensions of the monitor in real-world coordinates, as well as the position of the eyepoint.
The following options are used if configmode is set to channel:
The aov parameter should be specified as the field-of-view when viewing the monitor straight on, not accounting for shear. The xshear and yshear factors should be set to the tangent of the angle between the eyepoint-to-monitor vector projected into the monitor X-Z (resp. Y-Z) plane and the monitor normal.
Note that the visual system graphics frame is used.
The following options are used if configmode is set to monitor:
You must also specify the eyepoint parameter in the [MAIN] configuration section.
Note that the visual system graphics frame is used.
For example, the following configuration file specifies that the monitor is 24" by 17" and located 32" directly in front of the viewer:
[MAIN] view = OTW eyepoint = 0 0 0 [OTW] configmode=monitor position= 0 0 -32.0 top = 0 17 0 right = 24 0 0
The following options may be used for either configuration mode:
For [OSV] section only:
The ownship configuration option specifies the source of the aircraft dynamics:
In a multi-head networked configuration, at most one node may set ownship=local or ownship=cdb; all other nodes must set ownship=flcomms or ownship=network. In typical configurations, all nodes should use ownship=flcomms.
Other options available in the [OWNSHIP] section:
NOTE --With ownship=local, the math model is propagated forward one time step per frame; PilotStation does not attempt to ensure real-time synchronization. In this mode, the simulation DT should be tuned to match the average PilotStation frame rate to achieve approximate real-time performance.
Main option: mbplatform=on.
Config file section: [MBPLATFORM]
Available options:
Please consult the MotionBase documentation for the meaning of the the above options.
PilotStation uses simulation variables to drive the instrument panel and for customized communication with a FLIGHTLAB model.
The following simulation variables are set internally by PilotStation; they are typically used to drive the instrument panel.
Customized data communications between PilotStation and FLIGHTLAB is possible through the flcomms mechanism. The [SIMVARS] configuration section specifies a list of flcomms data blocks which PilotStation will read from or write to.
[SIMVARS] BLOCKNAME = [ read | write ]
Each BLOCKNAME corresponds to a Scope variable list named @blockname. If the mode is set to read then this data block will be used to pass data from Scope to PilotStation; if it is write then data will pass from PilotStation to Scope. This facility may also be used to pass data between different PilotStation nodes in the same station; in this case at most one node in the station may set BLOCKNAME=write.
For each data block `BLOCKNAME' the [SIMVARS.BLOCKNAME] specifies the mapping between PilotStation simulation variables and Scope model variables:
[SIMVARS.blockname] scope-variable0 = pilotstation-variable0 ... scope-variableN = pilotstation-variableN
The scope-variables must appear in order. Scope and PilotStation variable names are both case-sensitive; Scope variable names must be all uppercase.
For example, to connect the control box buttons to control system input switches:
//
// In Scope:
//
varlist @switches "Control system switches" = ..
psas "Pitch SAS enable", ..
rsas "Roll SAS enable", ..
ysas "Yaw SAS enable";
# In the PilotStation configuraition file: [MAIN] pilotin=controlbox [SIMVARS] SWITCHES = write [SIMVARS.SWITCHES] PSAS = BTN0 RSAS = BTN1 YSAS = BTN2
The instrument panel display is activated by specifying ipanel=filename.cnf in the [MAIN] configuration file section, where filename.cnf is the instrument panel configuration file. The following panel configuration files are provided in the PilotStation distribution:
These files may be tailored as necessary to suit individual applications.
The layout and behaviour of the instrument panel is fully specified in the 'ipanel' configuration file. The essential configuration parameters are:
instrument=xxx
This specifies the name of a MultiGen object, which has been loaded into GVS with an
import ... name=xxx structure=ondirective in the GVS initialization file.
Subsequent node=yyy directives specify how to configure the moving parts of the instrument; yyy is the MultiGen node name. The dof parameter is one of ROTX, ROTY, ROTZ, TRX, TRY,TRZ, or ONOFF; this specifies the axis of motion. (rotational, translational, or an on/off behaviour). The var parameter specifies the simulation variable which will be used to drive this degree of freedom.
Finally, dom and ran specify a piecewise linear mapping from the input value to the DOF output value. For onoff degrees of freedom, values <= 0.0 are off, values > 0 are on.
The head-up display is overlaid on the out-the-window scene. The HUD displays pitch, roll, and heading angles, airspeed in knots, radar alititude in feet, and the rate of climb.
A ``hover box'' displays the velocity vector relative to the aircraft body axes and is useful for hovering and as a sideslip indicator.
This display is not modifiable by the user.
Configuration section RUNWAY0, if present, adds a runway to the scene. If the instrument panel (see 10.1. ``Instrument panels'') is active, the runway position will be used to drive the glide slope and localizer bars on the horizontal situation indicator.
Available configuration options:
If the runway is active, the following simulation variables are available: