TomTom Software Development Kit
Version 5.0
(for the TomTom GO)

Compiling Applications for the TomTom GO

1. Introduction

TomTom GO runs on the Linux operating system. The TomTom Navigation SDK comes with a compiler toolchain that can be used to create applications that will run on the TomTom GO. Windows-users can install a useful tool called Cygwin to simulate a Linux-environment and from which the compiler can used.

This section explains how to set up Cygwin under Windows, how to install and use the TomTom GO specific compiler toolchain and how to install the libraries provided for developing applications for the TomTom GO.

2. Cygwin

If you want to compile applications for the TomTom GO and you do not use Linux on your development machine , you can install the easy-to-use program Cygwin under Windows. Cygwin is a Linux-like environment for Windows and the SDK comes with a compiler toolchain that works under Cygwin.

2.1. Installing Cygwin

The latest version of the free Cygwin-program is avialable from: 

Cygwin website

Cygwin works with any version of Windows since Windows 95. After downloading the setup, choose either to install the program directly from the Internet or to download it first and then run setup.exe. On the next few screens click "Next" as the default installation-options are correct for most users. Make sure to leave the option 'Default Text File Type' on UNIX. On the final screen, when the installation-options for the different packages are being shown, change the option 'default' to 'install'. This way all packages will be installed on your Windows system. See the Cygwin manual for more information on installation.

2.2. Using Cygwin

After installation, a useful batch-file 'cygwin.bat' is created which you can use to start Cygwin. The Cygwin directory structure can be reached from Windows explorer as well, which can be useful to move or copy files. With Cygwin installed, users have access to many standard Linux utilities. If you have never worked with Linux before, here are some useful commands (basically all the commands you need in order to compile your own TomTom GO applications). For more information on Linux, just type in "Linux basics" or something similar in any search engine.

2.3. Useful UNIX commands

The following basic commands can be used from the command-prompt in Cygwin:

ls: list files and directories
ls -l: list all files and directories, showing file details
mkdir 'mydir': make directory 'mydir'
rmdir 'mydir': remove directory 'mydir'
cd 'mydir: change to directory 'mydir
cd: change to home-directory
cd ..: change to parent directory
pwd : display the path of the current directory
rm 'filename' : remove 'filename'
mv 'filename1' 'filename2': move 'filename1' to 'filename2'
exit : end program execution

3. Compiler toolchain

You need to install the compiler toolchain to compile client applications for the TomTom GO, .

3.1. About cross-compilers

The compiler toolchain for the TomTom GO is based on the "GNU Compiler Collection" gcc. Cygwin has its own gcc-compiler. The two compilers that come with the TomTom Navigation SDK are so-called cross-compilers: They run on a Linux-system or under Cygwin, but produce object code for the TomTom GO. The programming languages they currently support are C and C++.

3.2. Installing the toolchain

The toolchain to install can be downloaded from the TomTom website: 

http://www.tomtom.com/gpl/

Here you will find two files, which names are both of the following format:

toolchain_[platform]_[gcc-version]_[date]a.tar.bz2

where

[platform] = Cygwin or Redhat; choose Cygwin if you are going to compile applications under Cygwin, Redhat otherwise. The latter should work under Linux on any Intel-based desktop.

Follow these steps to install the toolchain:

  • Start Cygwin or log in as root under Linux.
  • In the directory /usr/local/ make a directory called 'cross'.
  • Copy the file toolchain_[platform]_[gcc-version]_[date]a.tar.bz2 to that directory.
  • Unpack the toolchain by running the following command from the cross-directory:
tar xvfj toolchain_[platform]_[gcc-version]_[date]a.tar.bz2

This will install the /usr/local/cross/ directory structure which contains the toolchain.

In the directory /usr/local/cross/gcc-3.3.4_glibc-2.3.2/bin you will find various executables starting with arm-linux. Those are the compiler tools you should use in order to compile your TomTom GO applications.

It is a good idea to refer to this directory in the .bashrc from the developer's login directory by adding the following line: 

export PATH=$PATH:/usr/local/cross/gcc-3.3.4_glibc-2.3.2/bin

For more information on the gcc-compiler, see: 

GCC online documentation

4. Installing SDK files and libraries

You need to copy the header files and libraries to a place where the compiler can find it to make use of the SDK,

To install the header files, just copy the contents of the directory /TomTomGO-SDK/include/ to the /usr/local/include/ directory on your Linux-development machine or under Cygwin.

First time Cygwin-users will probably have to create the /usr/local/include/ directory.

The same holds for the library: Copy the contents of the directory /TomTomGO-SDK/lib/linux-arm/ to /usr/local/lib/.

Now you are ready to compile your applications for the TomTom GO.

4.1. More on the SDK libraries

The TomTom GO SDK contains a set of static libraries that can be linked into the add-on application. Libraries have a file name of the form “lib<name>.a”. To link in such a library, the command line flag to the linker takes on the form “–l<name>”. Usually the linker also has to be informed of the location of the libraries, through the command line flag –L<path>.

The libraries included in the SDK are:

  • libosal.a – this library is used by the other SDK libraries internally, and does not offer an explicit interface to the outside world (this library comes without header files). It is meant for internal use only, and contains some utility functions and classes.
  • libwmnone.a – this tiny library is part of the user interface toolkit being used, and contains the implementation of switching context on screen between the SDK-based application and the navigation application. It is dependent on the user interface toolkit being used (this one particular implementation is meant to be used with libttui.a). This library is for internal use. Users using the SDK probably don’t need to worry too much about this library, unless they want to implement their own user interface toolkit.
  • libswitch.a – this library comes with the header file switcher-share.h, and facilitates launching external add-on applications and controlling which process is allowed to draw to screen at any moment.
  • libfbts.a – this library abstracts away the screen. Other user interface libraries could be ported to run on the TomTom GO, using the interface defined in header files MFrameBuffer.h and MVirtualScreen.h and implemented in this library.
  • libsdk.a – This library implements everything related to communicating with the navigation application (explained elsewhere in this documentation).
  • libttui.a – This library is the user interface toolkit library that comes with the SDK by default. Usage of this library is explained elsewhere in the documentation.
  • libfreetype.a - A portable and highly efficient TrueType rendering engine. We acknowledge that this library is based on the work of the FreeType Team, and not our own.

The first version of the TomTom GO to fully support this set of libraries is version 5.00.

5. Compiling applications

Now that you have installed the SDK and set up the environment, you can compile your first application for the TomTom GO.

5.1. Example "hello world" application

Here is an example of an application which you can run on the TomTom GO, with no communication with the Navigation software and with no GUI defined. However, it will show you you have compiled an application for the TomTom GO!

Enter the following code into a text file on your computer and call the file 'hello.cpp' or use the corresponding file from the /TomTomGO-SDK/examples/compilation/ folder. 

#include <stdio.h>
int main(void)
{
  printf("Hello world!\n");
  return 0;
}

To run this program on the TomTom GO, it has to be compiled using the toolchain you have just installed.

5.2. Using the toolchain

To compile hello.cpp into an object-file run the following command: 

arm-linux-gcc -c hello.cpp -I/usr/local/include

where the option -I/usr/local/include is used to tell gcc where to find the include-files.

Now link the libraries, using the option -L/usr/local/lib/: 

arm-linux-gcc hello.o -o hello -L/usr/local/lib/  -lsdk -lwmnone
-lttui -lfbts -lswitch -losal -lfreetype -Wl,-Bstatic -lstdc++ -Wl,-Bdynamic

To reduce the size of the executable file, use arm-linux-strip: 

arm-linux-strip hello

Now you have a file called "hello", which is executable on the TomTom GO. All you have to do is transfer it to the SD card and then run it.

6. Transferring files to the TomTom GO

To transfer files to the TomTom GO you can use the USB cable provided with your TomTom GO or you can set up a serial connection through the COM port.

6.1. Accessing the contents of the SD card

To transfer files to the TomTom GO, you can use the USB cable that came with the TomTom GO. Just plug it in a USB port on your PC and you can browse the contents of your SD card from Windows explorer. If you have an SD card reader, refer to the manual of the reader for help on accessing files on the SD card.

Your applications can be copied to the root of the SD card or you can create a subdirectory for your applications.

6.2. Connecting to the TomTom GO through your COM port

To make a connection with your TomTom GO through your COM port, you can use the Windows program HyperTerminal (Start=>Programs=>Accessories=>Communications) or any program that allows you to set up a connection through your COM port. Just connect the TomTom GO to the COM port and start HyperTerminal. Set up a new connection and select the right COM port. On the second screen, make sure you set the following fields:

  • Bits per second = 115200
  • Databits = 8
  • Parity = none
  • Stop bits = 1
  • Flow control = none.

Then start the TomTom GO.

To browse the contents of the SD card from the terminal, change to the following directory: 

/mnt/sdcard/

Besides using the USB cable or a card reader, you can also transfer files to the TomTom GO through your COM port using HyperTerminal.

In that case, first configure the TomTom GO for receiving files, by entering the following command on the terminal command line: 

lrz

Then select transfer=>send file from the HyperTerminal menu and browse to the file 'hello' you have compiled.

Finally, you have to change the permissions of the file by entering: 

chmod 755 hello

Now you are ready to run your application on your TomTom GO!

7. Running applications from the terminal

Since there is no GUI defined and no communication set up in our example, make a connection with the TomTom GO via HyperTerminal(if you haven't already done so), so you can run the application and see the output.

On the terminal on your PC, change to the directory where your application resides (/mnt/sdcard/ if you have placed it in the root of the SD card).

Run your application by typing ./hello on the terminal on your PC. The terminal now shows the text "Hello World!".