Telnet usage

From FlightGear wiki
Revision as of 20:01, 4 November 2010 by Hooray (talk | contribs)
Jump to navigation Jump to search

Flightgear comes with an internal command server. This so called "telnet" server provides a "remote shell" (like a command prompt) into the running FlightGear process. Using a telnet client it is possible to connect to a running FlightGear process and issue commands that FlightGear then runs internally. The telnet client can be running on the same machine as FlightGear itself, or on other machines that are in some way connected to the same network (LAN, WAN/internet).

This can for example be used to read and set values within the Property Tree structure, but it can also be used for running fgcommands. The telnet server can be activated with the --telnet=port command line option, where port is the number of the listening port that will be opened locally by the FlightGear fgfs process.

This makes it possible to "remote control" FlightGear by using the telnet protocol. This can for example be used to change environment settings (weather, time, visibility etc).

A connection to the running server can be established using a conventional telnet client or by opening a simple TCP socket from a custom program. Multiple connections are possible at the same time. For an example in Java please refer to $FG_SRC/scripts/FGClient: http://gitorious.org/fg/flightgear/blobs/next/scripts/java/FGClient/src/FGFSDemo.java For shell scripting purposes, netcat also works well.

Starting Flightgear with Telnet Server

For example, to start FG and open the port 5401 as available telnet server use this command:

fgfs --telnet=5401


Connect with Telnet Client

Once connected to the server using a telnet client, you will be given a prompt such as if you where connected to a unix telnet server, example:

francesco@francesco-desktop:~$ telnet 127.0.0.1 5401
Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.

Where 127.0.0.1 is the ip address (127.0.0.1=localhhost) of the running Flightgear server and 5401 is the local server port (incoming) set when Flightgear started.

Now that you are inside a telnet session, you can start issuing commands (see below) to Flightgear. Generally commands are used to get, change and navigate the values of the property tree, similar to navigating with directories and files.

Prompt

Since we are simulating navigation through a file system, you will be given a prompt which consists of two parts:

  1. current tree position
  2. (the characters >(space))

so you will typically see something like the following:

/>
/autopilot[0]>
/autopilot[0]/settings[0]>


Commands

The following command are available:

  • cd - change directory
  • data - switch to data mode
  • dump - dump to xml
  • get - show a property value
  • help - show available commands
  • ls - list directories and paramaters
  • prompt - switch to interactive mode
  • pwd - display current path
  • quit - terminate connection
  • run - run a built in command
  • set - set value of property
  • ? - shortcut to help


cd

Change the current working directory; it needs a parameter which is the destination directory. Example session.

/> cd gear
/gear[0]>
/gear[0]> cd launchbar
/gear[0]/launchbar[0]> cd ..
/gear[0]> cd ..
/> cd gear/launchbar
/gear[0]/launchbar[0]> cd /
/>

data

Switch to data mode. This removes the prompt/>. This is mostly useful when communicating from code, eg a socket.

To switch back on see prompt below.

dump

dumps the current state in xml. This requires at least a directory argument.

/> dump postion/
-ERR "node 'postion/' not found"

/> dump /position 
<?xml version="1.0"?>
<PropertyList>
  <longitude-deg type="double">-122.3577761</longitude-deg>
  <latitude-deg type="double">37.61378776</latitude-deg>
  <altitude-ft type="double">28.25613943</altitude-ft>
  <ground-elev-m type="double">-0.131186098</ground-elev-m>
  <ground-elev-ft type="double">-0.4304005839</ground-elev-ft>
</PropertyList>

get

Shows the value of a given parameter, for example, to get the magnetos status inside the controls/engines/engine directory:

/> cd controls/engines/engine
/controls[0]/engines[0]/engine[0]>  get magnetos
magnetos = '3' (int)
/controls[0]/engines[0]/engine[0]> 

or from the root simply:

/> get controls/engines/engine/magnetos
controls/engines/engine/magnetos = '3' (int)
/>

help

Show all the available commands, same as just ?

ls

List all the directories and properties within and under the current directory, for example:

/> cd orientation
/orientation[0]> ls
heading-deg =	'70.62909768'	(double)
alpha-deg =	'-176.8560635'	(double)
pitch-rate-degps =	'3.347789774e-07'	(double)
/orientation[0]> 

or with a directory argument

/> ls /orientation
heading-deg =	'104.6032849'	(double)
alpha-deg =	'-176.864208'	(double)
pitch-rate-degps =	'-0.003761442232'	(double)
/>

prompt

Switch on interactive mode prompt/>. One by default. See data above to switch off.

pwd

Display the current directory ie print working directory

quit

Terminate the client connection to server.

run

Run a built in command, the command name is required as an argument.

set

Sets the value of a given property, for example, to set the aileron position inside the /controls/flight directory:

/> cd controls/flight
/controls[0]/flight[0]> set aileron 0.2
aileron = '0.2' (double)
/controls[0]/flight[0]> 

or simply:

/> set /controls/flight/aileron -0.1
/controls/flight/aileron = '-0.1' (double)
/>