5.1_ XSquawkBox User's Guide


5.1.1_ Introduction

XSquawkBox connects X-Plane to an online flight network. This flight network is made up of users flying in a virtual world with X-Plane, Microft Flight Simulator(MSFS), and other flight simulators. The network also has users acting as air traffic controllers, watching your plane on radar scope and control tower software and providing for the safe and expeditious movement of aircraft.

Please read the installation and using XSquawkBox sections completely; they contain the minimum information you need to use XSquawkBox.

5.1.2_ If You Are New To Online Flight

5.1.2.1_ Where do I begin?

Before you can fly online, you must join an online flight network, like VATSIM or IVAO. Each network has a homepage that allows you to sign up, receive a free pilots ID and password, and get IP addresses for the network's servers. The networks also have information for beginners.
The XSquawkBox web page also has a forum for new users of XSquawkBox.

5.1.2.2_ Which Version of this plugin do I need?

XSquawkBox comes in two versions - the IVAO and VATSIM variant. Download and install the appropriate plugin for the network you will participate in. For a network other than VATSIM or IVAO, use the IVAO version of the plugin.

5.1.2.3_ What Happens in Online Flight

The online flight environment is a virtual world that simulates all aviation activities. You will see other aircraft in the sky and on the ground and be able to hear/see text from the other pilots. ATC will monitor you on radar-scope simulation software, issue vectors to you, and provide separation services. XSquawkBox will set X-Plane's weather to match real world weather.

While online, you are expected to follow basic real-world aviation procedures. You will need to file an IFR flight plan when flying in controlled airspace under instrument weather conditions.

5.1.2.4_ Basic Etiquette of Online Flight

Here are a few basic suggestions for successful online flight:

5.1.3_ If You Are New to X-Plane

X-Plane is an amazing simulator, but it also takes some getting used to. A few notes about X-Plane:

5.1.3
.1_ X-Plane Releases and Upgrades

X-Plane is updated on a continuous basis. When buying a version of X-Plane, you receive access to all future upgrades in that major version. In other words, if you buy X-Plane 7.20, you may upgrade to the highest X-Plane 7.xx product. Typically a major version of X-Plane comes out every two years; version 7.15 is just about to be released as of this writing.

The X-Plane demo download is exactly the same as the real X-Plane application; having a CD'unlocks' X-Plane, allowing you to leave the Southern California area and fly for more than 6 minutes with the joystick. All of X-Plane's features are in the demo; frame rates you see in the demo will by typical of the full version; bugs in the demo are in the full version too. The demo does not hide anything (except the rest of the world).

Before you use XSquawkBox you may need to update to a newer version of X-Plane (for example, if you have X-Plane 6.25 you'd need to upgrade to 6.70). However, you may not want to take the latest X-Plane upgrade until you are sure that it will work; sometimes the latest upgrade ships with bugs. The latest version of X-Plane is provided in the form of the X-Plane demo; you must merge these with any custom files you have (for example, the XSquawkBox plugin).

For example, if you have X-Plane version 7.00 and you want to upgrade to X-Plane 7.10, you would download the X-Plane 7.10 demo and merge the X-Plane 7.10 demo files with your files from X-Plane 7.00.

You do not need to install the old version of X-Plane that came on your X-Plane CD; you can simply download the latest X-Plane from the web and run it using the CD in the drive to unlock the joystick.

X-Plane betas are released publicly. If you are not an experienced X-Plane user, I do not recommend participating in the beta program, as X-Plane betas are often unstable. The purpose of the beta program is to find bugs in X-Plane; if the beta builds were not buggy, they would be releases.

When upgrading X-Plane, I recommend caution. Download the new X-Plane first and try it, then move your airplanes and plugins to the new version and delete the old only when you're sure the new version works with your system.

5.1.3.2_ Global Scenery

Laminar Research and the Global Scenery project (GLoS) provide scenery for the entire planet Earth. This scenery can be obtained by purchasing a set of CDs from Laminar Research (X-Plane 7 comes with the latest scenery CDs), or scenery may be downloaded for free as sets of 10x10 degree areas from the GLoS website at http://www.glos.webhop.org/.

This scenery is not photorealistic and has limited accuracy. It is generated from government GIS data and is reasaonably accurate to real-world topology and coastlines. The Southern California scenery that ships with X-Plane (not counting San Bernardino) is an excerpt of the global scenery.

If you are considering purchasing the global scenery, especially to upgrade from previous global scenery CDs, download an area you know well from the GLoS server first so you can evaluate the quality of the scenery and understand what you are buying.

5.1.3.3_ Custom scenery and Add-ons

Custom scenery is also available for X-Plane. Simply drag a custom scenery package into the "Custom Scenery" folder.

X-Plane features many add-on planes, scenery, and other content, most for free. The X-Plane home page (http://www.x-plane.com/) contains links to many portals and other sites that contain free content.


5.1.4_ Installation and Setup

5.1.4.1_ Installing XSquawkBox

There are two versions of XSquawkBox: one for VATSIM, and one for IVAO (and other networks). XSquawkBox comes as a .zip archive for Windows or a .sit archive for Macintosh. Make sure to download the correct version of XSquawkBox for your platform and your network. Once unstuffed or unzipped, the XSquawkBox files for Mac and Windows are almost impossible to tell apart.

To install XSquawkBox, simply decompress the archive and copy the contents of the "for plugins folder" folder into the "X-System/Resources/plugins" folder.

Important: The XSquawkBox.xpl file should be directly inside the X-System/Resources/plugins folder. The "XSquawkBox Resources" folder will sit inside the plugins folder, too.

When XSquawkBox is installed correctly, there will be an "XSquawkBox" menu item in X-Plane's "plugins menu". If you do not have a plugin menu, your X-Plane is incapable of running plugins.

5.1.4.2_ Installation for Flying on Both VATSIM and IVAO

If you wish to fly on two networks, you will need to install both XSquawkBox for IVAO and for VATSIM. Download both installations, but keep only one XSquawkBox plugin (.xpl) file in your plugins folder at a time. You may use one "XSquawkBox Resources" folder for both networks, but you will have to quit X-Plane, remove one XSquawkBox plugin from the plugins folder, and replace it with the other, before restarting X-Plane.

5.1.4.3_ What You Need To Do Before You Fly

Most of XSquawkBox configures automatically, however, there are three important things you must do:
Once you've installed XSquawkBox and done these things, you're ready to fly. Read the next section to learn how to use XSquawkBox; if you're not used to online flight, see the section for new users.

5.1.4.4_ Important X-Plane Settings (for X-Plane 7)

A few things you must set in X-Plane for normal operation:
  1. In the rendering settings dialog box, set the number of planes to at least 8.
  2. In the rendering settings dialog box, enable loading fixes (version 7.00 only).
  3. In the rendering settings dialog box, turn off "draw aircraft on the ground" (7.10 and higher).
  4. If you are using VATSIM with voice or another voice-over-IP system, you may want to turn off "background radio chatter" in the Sound dialog box.

5.1.5_ Using XSquawkBox

Please read this section completely before connecting to the network.

5.1.5.1_ Connecting to the Network

To connect to the network, please pick'Connect...' from the XSquawkBox submenu of the plugins menu in X-Plane. A dialog box will come up asking for the following fields:
Click the connect button; you will see the prompt "connecting..."at the top of your screen. If the login is successful, you will then see the welcome message for your flight simulation network. If you cannot login, you will receive an error message. If the server cannot be reached at all, you will simply see "You have been disconnected."

5.1.5.2_ Disconnecting

To disconnect from the network, pick "Disconnect" from the XSquawkBox submenu of the Plugins menu. After a few seconds, the message "Disconnected" will appear on the screen.

You may also be disconnected inadvertently due to internet problems or if a supervisor removes you from the network.

5.1.5.3_ Operating the Transponder

A transponder is a radio transmitter and receiver on your airplane that helps air traffic controllers see you on their radar screens. The transponder transmits a four-digit code (often called a "squawk code") that identifies your aircraft.

The X-Plane transponder on your airplane's panel controls your squawk code as seen by air traffic control on the network. If you do not have a transponder on your plane's panel, you will not be able to change your transponder settings and may not be allowed on your network. You can add a transponder to your aircraft's panel using PlaneMaker.

Use the keyboard or mouse to change transponder codes as assigned by ATC. Do not ever let the transponder read 7500, 7600, or 7700; as in real life this will trigger alerts for ATC.

To put your transponder into ident mode, click the'ident' button on your transponder on the x-plane panel with the mouse.

Before X-Plane version 7.10, X-Plane transponders did not have a working standby/Mode C switch. For these older versions of X-Plane, you cannot put your transponder into standby or normal mode-C operation using the X-Plane panel; you must do this using the "Standby" item on the XSquawkBox menu. When you connect, your transponder will be in standby mode; pick the menu item to toggle between normal and standby mode. The menu item will have a light next to it when you are in standby, indicating that you are in standby mode.

For X-Plane 7.10 and more recent versions, simply set the transponder to standby or mode C by clicking on the panel. The light on the transponder will blink when you are squawking mode C.

5.1.5.4_ Talking on the Radio

X-Plane allows you to talk on the radio using either text with the keyboard or voice, where available.

You will receive and send text and voice radio messages only on the frequency specified by your com1 radio. You must tune your com1 radio to the frequency you want to listen to. No other facilities except your com radio exist for changing frequencies in XSquawkBox; your com radio matters!

When someone sends a radio message to you via text, it appears on your windshield with tinting. The messages are color coded based on the origins of the message.

To broadcast, press return; a text entry field will appear. You can type messages or use the mouse to edit. Press return again to send the message, press escape to cancel sending. When you are typing, you cannot use keyboard shortcuts to control the sim. Keyboard focus will return to the sim when you press return or escape. Also, you cannot access X-Plane's built-in "AI ATC" functions while on XSquawkBox.

You can also send messages privately directly to a user by using the syntax
.msg <callsign> <message>
Use the tab key to bring up the last radio transmissions if they have disappeared and you must review one. You can use the page up/page down/end/home keys to scroll through a history of the last 1000 radio messages.

Note: X-Plane only provides 2 decimal places of tuning on the com radios, e.g. 134.12. XSquawkBox works to 25 khz intervals, so this will be treated as 134.125 mhz and tune correctly. Air Traffic Controllers should tune to the full 3 decimal-place frequency, e.g. 134.125. XSquawkBox cannot tune to 8 khz intervals.

5.1.5.5_ Filing a Flight Plan

You can file a flight plan from XSquawkBox. Pick the "Send Flightplan..." menu item from the XSquawkBox menu. A flight plan dialog box will appear. From this dialog box you can enter your flight plan and then press Send to send it to the network.

On VATSIM if ATC has edited your flight plan, sending a new one may have no effect. If you resend a flight plan and the controller does not receive it, notify the controller that he or she must refile the flight plan for you.

Tip: even if you have already filed a flight plan online via the VATSIM web page, or even if you are flying VFR and do not intend to request ATC services, you may still want to fill out the flight plan dialog box with a departure and destination airport; XSquawkBox will use this information to correctly set up weather from your departure and destination airports, rather than airports nearby your departure and destination.

5.1.5.6_ A Few Gotchas

Do not use X-Plane's ATC functions to check the local weather; the results will not be accurate. XSquawkBox does not download a metar.rwx file. Use the .metar command (listed below) to check weather online or use ServInfo.

Do not pause the sim or open modal dialog boxes; this will both freeze you in space and cause you to stop hearing voice transmissions (if on VATSIM).

5.1.5.7_ Using Voice on VATSIM

This section is for VATSIM users only. Other users should refer to their network's documentation on voice.

Before you can use voice online, you must choose and calibrate your audio hardware. Pick "Setup Audio..." from the XSquawkBox menu. Two popups will let you choose devices using either Wave or DirectSound input. Try DirectSound first, but try Wave if DirectSound does not work. You may use any audio device; if a device is not compatible with XSquawkBox, an error message will show below.

The volume slider reduces the volume of just voice transmissions; use it to balance volumes with the rest of X-Plane's sound. You may want to turn off X-Plane's built in radio chatter, etc.

Once you have picked hardware, pick'Test Mic'. This will take you through a wizard that sets up your squelch and mic levels and helps you diagnose problems. The squelch level is the level at which your mic does not transmit, and is important for reducing engine noise over the network.

Note: You must go through the mic wizard every time you pick a new input device!

Warning: Your push-to-talk keyboard key will block out any previously mapped X-Plane keystroke. But your push-to-talk joystick button will activate both push-to-talk and any other mapped X-Plane function!

Once your audio settings are set up, fly normally. When you tune into a controller with a voice room (using the com1 radio), you will see messages first that you are joining the voice room and then that you have joined. When you are connected to a voice room, hold down the ` key to talk. You will hear other controllers and pilots.

5.1.5.8_ Using Voice on Other Networks

While XSquawkBox does not have built-in support for voice on networks other than VATSIM, various developers are writing plugins that add voice capability to XSquawkBox. To find these plugins, visit the XSquawkBox home page or your network's home page.


5.1.6_ Troubleshooting

The online flight environment is a complex one with lots of interoperating software; here are a few tips for trouble-shooting XSquawkBox problems.

5.1.6.1_ An aircraft does not look right, or another aircraft looks like my aircraft or my control surfaces move wildly.

This can be caused by not having enough airplanes enabled in X-plane 7. Make sure all 10 airplanes enabled are enabled.

An airplane may also not look right if the user simply has not signed on as the right kind of airplane. The text files that configure online aircraft are not always correct. The XSB_Aircraft.txt file maps ICAO codes of aircraft to one of seven models. If the mapping isn't ideal or there is a typo or missing aircraft, please email me. But please remember, with only seven aircraft a lot of the matches are going to be poor.

If you want to trouble-shoot plane models, you can type:
.debug models=1
.debug csl
The first command will cause XSquawkBox to show the ICAO code it has for incoming aircraft. If an incoming aircraft has the wrong ICAO code, that can cause its model to be wrong. The second command dumps a list of every plane's ICAO code and X-Plane model to the Error.out text file. If, upon inspecting this list, you are not happy with the matches, edit the XSB_Aircraft.txt file.

5.1.6.2_ Distorted audio while using integrated VATSIM voice

Sometimes this is caused by the sum of VATSIM voice and X-Plane sounds overloading your sound card. For X-Planes versions older than 7.10, try using the'wear headsets' option in the sound configuration dialog box to turn down X-Plane's sound effects. For X-Plane 7.10 and on, turn down the master volume slider for X-Plane (and for XSquawkBox in the Audio Setup dialog). If you have two sound output devices, put XSquawkBox on the sound output device X-Plane does not use to improve audio a lot.

5.1.6.3_ Macintosh Crashes while using integrated VATSIM voice

This is a known and unfortunate problem that often happens after 3-4 hours of flight. If you would like to use XSquawkBox for VATSIM without integrated voice support, open the XSquawkBox preferences file. Under the [debug[ section, change the line disable_audio=false to disable_audio=true. Restart X-Plane; XSquawkBox will not initialize voice support.

5.1.6.4_ Weather appears wrong

First let me clarify a few things:
XSquawkBox will load the nearest weather station it can find (based on X-Plane's list of airports) every few minutes; this time can be set in the preferences. If you have filed a flight plan, your departure and arrival airports are preferred to the nearest one so you do not pick up the weather of a satelite airport you fly over on final approach. If X-Plane cannot find weather for an airport, it picks the next one and keeps trying.

You can view this process by using the .debug command to enable weather viewing:
.debug weather=1
to enable weather loading. You will see weather messages show up on the screen as XSquawkBox loads new weather.

If XSquawkBox ever says it loads a METAR but the weather does not reflect this (e.g. the METAR says rain but it is sunny out), email me the METAR and I wil investigate. There is a known bug right now (fixed on VATSIM, unknown for other networks). If a METAR is in the form:
EGNS 170620Z 09007KT 060V120 CAVOK 16/13 Q1015
You may see an outside air temperature of zero degrees Celsius.

If XSquawkBox does not find the weather for your favorite airport, but rather a nearby one, this is due to the network's set of reported weather, not an XSquawkBox issue. You can ask your favorite network administrator to try to find weather for this airport, but this is not an easy task and they may not be able to help you immediately. Some smaller airports do not have weather available online for networks to use.

In summary: what XSquawkBox says it loads in red is what you should see; if what it says it is loading is wrong, this is a network problem; if the loading doesn't match what it says it will load, this is either an XSquawkBox or network bug, but either way report it to me. You will see the latest weather in the weather setup dialog box, but no METAR.rwx will be created.


5.1.7_ Reference

5.1.7.1_ Commands In the Text Radio

From the text radio you can use the following commands:

.msg <callsign> <msg>
This sends a private message to the specified callsign. Note: you do not get a warning if the message did not go through. You can message someone anywhere in the world even if you cannot see them (because they are out of range).
.msg N1975 Hey George, haven't seen you in a while!
.atis <controller>
This retrieves the "ATIS" of a controller. The "ATIS" is a personal message that each controller sets in his or her radar client. It is automatically displayed when you tune that controller's frequency.
.atis BOS_V_APP
.metar <ICAO>
This fetches a weather report for an airport.
.metar KBOS
//<frequency>

This lets you tune your com1 radio to any radio frequency, including a 25 khz frequency like 134.125. Note: once you tune to a 25 khz frequency, X-Plane will jump from 25 to 75 khz instead of 0 to 50 khz. Tune to a 50 khz frequency using the // command to restore X-Plane to its normal operation mode.

//134.125
//120.6
//135.05
.debug <function>
This command allows you to debug various functions in XSquawkBox. For advanced users only.

.debug weather=0
.debug weather=1
.debug models=0
.debug models=1
.debug csl
5.1.7.2_ Menus 5.1.7.3_ Connection Dialog 5.1.7.4_ Flight Plan Dialog 5.1.7.5_ Setup Audio Dialog 5.1.7.6_ Preferences Dialog 5.1.7.7_ Keystrokes

XSquawkBox 1.0 © Copyright 2003-2005 Ben Supnik, Chris Serio. http://www.xsquawkbox.net/