Renaming the executable or creating a shell.ini file

This page was last updated on 16 February, 2012.

Programs this applies to

This information applies to the Windows Mobile versions of both XCSoar and LK8000. LK8000 is a branch of the XCSoar project which provides an alternative look and feel to standard XCSoar. At this point you should have the program on an SD card. Its name relative to the SD card's root directory will be:

Program	Relative name
XCSoar	XCSoar\XCSoar.exe
LK8000	LK8000\LK8000-PNA.exe

What is known

Like many embedded operating systems, Windows Mobile/Windows CE must be configured to match the hardware it controls. However, many vendors make other customisations too. Here we are concerned with the vendor's approach to booting off the SD card. Some PNA models are designed to keep additional maps on the SD card and so they boot their navigation software off the card. Others expect an update program on the SD card which, when booted, will update the maps and software in the PNA's built-in memory. This is reflected in the name of the executable on the SD card and this in turn affects us, since Windows Mobile will only boot a program with the name it was customised to use when it is in the expected place on the SD card. We fool the PNA into running the soaring program by renaming it or making other changes, e.g. using a shell.ini file. There is more on this in the notes about each type of PNA and in Creating a shell.ini file.

XCSoar

XCSoar executables can be put anywhere provided only that the PNA's operating system can find them. The data files (turnpoints, airspace, maps and polars), on the other hand, must be in the XCSoarData directory. This must be in the root directory of the SD card or, in the case of the Navman EZY 40, in the root directory of the PNA's built-in flash memory.

Devices

If you have another type of PNA... see Other things to try.

LK8000

LK8000 keeps its data files in subdirectories of the same directory, called LK8000, that contains the programs. This directory must be placed in the root directory of the SD card. It cannot be renamed or LK8000 will be unable to find the data files.

Devices

If you have another type of PNA... see Other things to try.

Creating a shell.ini file

16/02/12

This section contains a short tutorial on what this mysterious file is and how to create it.

Many of the PNAs we use for navigation are based on the Windows Mobile operating system and all are designed to run a built-in car satnav program. The shell.ini file provides a way that we can make it run some other program, namely XCSoar or LK8000, from an SD card. The file contains the detail Windows Mobile needs to find and run the program installed on the SD card. When a PNA that understands shell.ini files (not all do) is ready to run its navigation program, it starts by looking on the SD card for a copy of this file. If there is one and it contains the correct name of a program, the PNA runs that. If there is no SD card in the PNA's card slot, it doesn't have a shell.ini file in its outermost directory, or the program reference in the file is wrong, the PNA will start its built-in program instead.

shell.ini is a plain text file that must contain a single line that gives the name of the program and says where to find it. The line must be exactly the same as shown for your PNA in the previous XCSoar or LK8000 section. It must not use special fonts, bolding, etc. and must have only one newline at the line's end. The following programs can be used to create the file:

Operating system	Suitable editors
Windows	Wordpad
Linux	gedit, vi or emacs

Typical SD card installations for XCSoar and LK8000 are:

Program	Installation method	shell.ini content
XCSoar	Create an 'XCSoar' directory and put XCSoar.exe in it. Create an 'XCSoarData' directory to hold the maps, turnpoints, etc. Both directories are in the outermost directory of the SD card. Copy your data files into the 'XCSoarData' directory.	`\SDMMC\XCSoar\XCSoar.exe`
LK8000	Unzip the full LK8000 package onto an empty SD card.	`\SDMMC\LK8000\LK8000-PNA.EXE`

Copy the shell.ini file into the outermost directory in the SD card.

Once you've done that, you should be able to put the card in the PNA, start its main application as usual, see splash screen of your program appear and prompt you to run it in Fly or Simulator mode using the default scenery it was supplied with. Choosing Simulator mode lets you explore and configure your setup indoors without being pestered about a lack of GPS signal, though you'll need to be in Fly mode to set the COM port and baud rate (see below).

Once you've run your flight navi this way (it will run on the default demo scenery), you can add the various UK data files and then use the setup pages to tell it to use them instead of the demo files.

Setting the COM port and baud rate

08/02/12

If XCsoar or LK8000 can't find and read the GPS receiver, you'll need to go to the Devices page of System Configuration and experiment with changing the COM port and baud rate.

Be sure to start the program in Fly mode. After making changes you need to save the configuration and exit back to the map display. At this point the program will display "Restarting the COM ports" and you'll have to wait a few seconds until it gets some data from the GPS receiver and responds to it. The response will be one of the following:

No messages appear and the glider symbol is at your current location.: The program is getting a signal and your location is being correctly shown. This is easier to see if you are somewhere that has a good GPS signal, i.e. outside where houses, trees etc. are not preventing the GPS from seeing the sky within the 45 degree cone above you, and have set your usual gliderport as 'HOME' in your XCSoar/LK8000 configuration. When you start your PNA it will come up with the glider symbol on the HOME location until it gets a valid GPS fix and then jump to your current location.
"GPS: NO VALID FIX" (LK8000 2.3p) or "GPS waiting for fix" (XCSoar 6.2.5) is displayed.: Your program is correctly connected to the GPS receiver but it isn't receiving a valid set of satellite signals and your program can't display your position.
"No Data received" (LK8000 2.3p) or "GPS not connected" (XCSOAR 6.2.5) is displayed.: The COM port number is wrong. Try a different port. Many PNAs have their GPS receiver on COM1 or COM7, so try these first.

I expect that there should be a different error message if the COM port is correct but the baud rate etc. is wrong, i.e. a message is received but is unreadable due to a baud rate mismatch between the program and GPS receiver but I have been unable to force this condition with my Binatone B.350 PNA, which works correctly at both 4800 and 19200 baud. However, other PNA's may require a specific baud rate to be set. This depends on the internal PNA design and on the GPS receiver and baud rate generator used. Commonly used baud rates are are 4800 (the NMEA_[*] default speed), 9600, 19200 or 57600 baud.

I've never needed to change the data format: it 'just works' for me at the default 8bit setting, but then again I use a Binatone B.350, so your experience may be different. I suggest leaving the data format on 8bit until you've tried all combinations of COM port and baud rate.

[*] The NMEA protocol describes how a GPS receiver sends position, height and time data to the devices that use this information.

Other things to try

Some PNAs are starting to appear with a 'settings' tool that allows you to add XCSoar and/or LK8000 to an application launcher menu. If yours has one, use it!
Download the MioPocket package. It is a front end for Windows CE-based devices, mainly GPS navigation devices. It is an installable package of programs, scripts, registry files and skins to "unlock" PNA/GPS devices. I discovered how to install LK8000 on Binatone B350 PNAs running Windows Mobile 6 merely by reading the installation notes for MioPocket. That told me how to set up the shell.ini file and so I didn't need to install MioPocket on my PNA. The GpsPasSion forum provides support for MioPocket.
You can always try the names shown above with another PNA. You can't harm your satnav: the worst that can happen is that the name isn't one its looking for and XCSoar and/or LK8000 will be ignored.
An internet search with the name and model of your PNA is worthwhile. There are user forums for many of them and lots of their owners are interested in running all manner of unusual programs on their machine. One of them may have posted the information you need.
If you're stuck and there's a firmware or map upgrade or an inexpensive add-on map available on an SD card, it may be worth getting it. Several PNAs use extra maps direct from the SD card rather than installing them. These all appear to work by launching a program on the card, so its worth finding out what name the program(s) and directory containing them have on the SD card. Its a safe bet that renaming the XCSoar executable to match will cause it to boot. There's often a clue in the names of files on the card: just look at the names, shown above, used by the Navigon 8110 and the Viamichelin X-970.

After its working

16/02/12

There are a couple of precautions that are worthwhile considering because they'll make life easier when you upgrade to a later versiion of the program or are unlucky to lose or break your PNA or the SD card.

Saving your profile(s)

Keep copies of your .prf file(s) because that is where all the configuration details are held. Its not hard to configure either XCSoar or LK8000 from scratch but it is a bit time-consuming and can be frustrating if you can't remember how to set one annoying detail. However, if you've saved copies of these files you can simply drop them back into place in a new or upgraded installation and all your usual settings will be there.

Saving task files

Depending on how you set tasks for yourself, it may be worth keeping the task files too.

My approach

Each time I set up an SD card with a new version of LK8000 I keep a copy of the complete card contents in a suitably named directory on my hard drive as both protection against losing the satnav and/or SD card and as a reference for what I did last time.

Finally...

If any of these approaches work for you please let me know what worked so I can add your experience to this page for the benefit of other glider pilots.