2.1. Example synchronous API call
2.2. Starting a session
2.3. Sending commands
2.4. Example asynchronous API call
2.5. Synchronous versus asynchronous calls
2.6. Supported API calls

3.1. Example composing messages
3.2. Format of the commands of the message files
3.3. File transportation layer

1. Introduction

The TomTom SDK allows developers to create applications for the TomTom GO and to integrate their applications with the navigation application.

The communication between the two applications functions through a client/server model, where the navigation application acts as a server receiving commands from the client application and sending back results when possible. The commands are written in message files and sent to the navigation application, which will send back responses written in other files.

For C++ developers, the SDK offers a way to facilitate this communication, as well as an API with many calls which can perform the communication request.

For developers who want to communicate using other languages than C++ or who just want to know more about the format of the message files and the file transportation layer, see

A deeper look at application interaction

2. Communicating with the TomTom GO from C++

A client application can communicate with the TomTom navigation application by setting up a communication object and using various API calls. These calls can be made synchronously as well as asynchronously.

2.1. Example synchronous API call

To demonstrate how to communicate with the TomTom GO, copy the following code to a file called 'flash.cpp' or use the corresponding file from the /TomTomGO-SDK/examples/communication/ folder.

#include "sdkconstants.h"
#include "TomTomAPI.h"
#include "TomTomGoFileLayer.h"
#define CLIENT_NAME "client"
int main()
{
 int res;
 MTomTomCommunicationLayerInterface *mycomms =
               DEFAULT_TRANSPORTATION_LAYER(CLIENT_NAME,2005,TOMTOM_TCPIP_PORT);
 CTomTomAPI api(*mycomms);
 CTomTomAPI::TError err;
 res = api.FlashMessage(&err, "Hello!", 3000);
 delete mycomms;
 return 0;
}

Compile it and run it from a terminal. The message "Hello!" will flash on the TomTom GO screen for 3000 milliseconds.

2.2. Starting a session

To communicate with the TomTom GO, a communication object has to be set up first. This is done through :

MTomTomCommunicationLayerInterface *mycomms =
              DEFAULT_TRANSPORTATION_LAYER(CLIENT_NAME,2005,TOMTOM_TCPIP_PORT);

where

• CLIENT_NAME is defined in the example as "client"
• 2005 is the port to listen to when using the TCP/IP layer. Currently TCP/IP is not supported.
• TOMTOM_TCPIP_PORT is defined in sdkconstant.h. Currently TCP/IP is not supported.
• DEFAULT_TRANSPORTATION_LAYER is defined in sdkconstants.h as:

#define DEFAULT_TRANSPORTATION_LAYER(appname,thisport,otherport)
                                                      CTomTomFileLayer::New(appname)

So communication object "mycomms" is defined as an instance of the class MTomTomCommunicationLayerInterface. This class provides the means to send information to and receive information from the navigation application.

The method New, which is defined for the class CTomTomFileLayer, creates the communication object for use on the TomTom GO, and establishes a connection with the application.

2.3. Sending commands

The library offers an API with several function calls which can be sent over to the navigation application. The navigation application will return a result in the same format, which will then be parsed with the same library.

To make programming life easier define the variable "api" for the communication object you have created as an instance of the class CTomTomAPI:

CTomTomAPI api(*mycomms);

The class CTomTomAPI has methods which can perform the communication request. Using them in the client application is like calling a function, but the navigation application will execute the function.

After you have set up your communication object, you call the method FlashMessage with its arguments.

res = api.FlashMessage(&err, "Hello!", 3000);

The navigation application will then process this request and send back a result, which is zero on success, some other integer otherwise.

In the example CTomTomAPI::TError err is also defined. TError is a struct which is defined in the API. More on the API structures and enumerations can be found at:

Structures and enumerations from the API

2.4. Example asynchronous API call

To demonstrate how an asynchronous call can be made, copy the following code in a file called 'getapplicationversion.cpp' or use the corresponding file from the /TomTomGO-SDK/examples/communication/ folder.

#include <stdio.h>
#include "sdkconstants.h"
#include "TomTomAPI.h"
#include "TomTomGoFileLayer.h"
#define CLIENT_NAME "client"
int main()
{
  int res;
  CTomTomAPI::TError err;
  CTomTomAPI::TVersion version;
  MTomTomCommunicationLayerInterface *mycomms =
              DEFAULT_TRANSPORTATION_LAYER(CLIENT_NAME,2005,TOMTOM_TCPIP_PORT);
  CTomTomAPI api(*mycomms);
  MTomTomSession *mysession;
  mysession = api.GetApplicationVersionAsync(true);
  printf("called  GetApplicationVersion async, res=%d\n",res);
  int sum = 0;
  while(!(mycomms -> ReturnAvailable(mysession)))
  {
    sum++;
    printf("sum = %d\n", sum);
  }
  res = api.GetApplicationVersionAsyncRetrieve(mysession, &err , &version);
  printf("GetApplicationVersion async finished, res=%d\n",res);
  printf("counted to =%d\n", sum);
  printf("buildnumber:%d, version:%s\n",version.iBuildNumber, version.iVersion);
  delete mycomms;
  return 0;
}

Compile it and run it on the TomTom GO. The asynchronous API call GetApplicationVersionAsync will be made, while your application keeps on running (shown by the output of 'sum' to the screen). When the result is returned from the navigation application, the client application stops and the result will be written to the screen.

2.5. Synchronous versus asynchronous calls

For every synchronous API call in the SDK, two asynchronous calls exist: one for sending the command to the navigation application and one for reading the result, when available.

First a session has been set up by defining "mysession" as an instance of the class MTomTomSession:

MTomTomSession *mysession;

Then the method GetApplicationVersionAsync is called, which is defined in the API:

mysession = api. GetApplicationVersionAsync( true );

Note that only 'true' is currently supported as a first argument of asynchronous calls.

As your application continues running, you keep checking for a return result, through:

mycomms->ReturnAvailable(mysession);

When the result has been sent back from the navigation application, the result can be read in the same manner as with synchronous calls:

res = api.GetApplicationVersionAsyncRetrieve(mysession, &err , &version) ;

As before, result is zero on success, "&err" is some additional error information and "&version" should give you the version information you requested.

Note that '-AsyncRetrieve' calls will block the application until a result is available, so be sure to use the check for a result through the ReturnAvailable command somewhere in your code. Otherwise you might as well use the synchronous API call.

2.6. Supported API calls

For a overview of API calls supported, see:

Supported API calls

3. A deeper look at application interaction

So how is does the communication work?

3.1. Example composing messages

To understand the way the communication functions at a deeper level, copy the following code to a file called 'getdeviceid.cpp' or use the corresponding file from the /TomTomGO-SDK/examples/communication/ folder.

#include <stdio.h>
#include "TomTomGoFileLayer.h"
#define CLIENT_NAME "client"
int main()
{
  MTomTomCommunicationLayerInterface *mycomms =
                DEFAULT_TRANSPORTATION_LAYER(CLIENT_NAME,2005,TOMTOM_TCPIP_PORT);
  mycomms->StartSendCommand();
  mycomms->AppendArgument("GetUniqueDeviceIdV01");
  MTomTomSession* session = mycomms->SendCommand();
  int i = 1, sum = 0;
  while(!(mycomms ->ReturnAvailable(session)))
  {
    sum++;
    printf("sum = %d\n", sum);
  }
  mycomms->StartReceiveCommand(session);
  int  nfields;
  nfields = mycomms->NrReceiveFields();
  printf("Number of Fields =%d\n", nfields);
  int index;
  for (index=0;index  {
    printf("%d\t:%s\n", index, mycomms->ReceiveField(index));
  }
  delete mycomms;
  return 0;
}

Compile it and run it on the TomTom GO. Note that "TomTomAPI.h" is not included in the source. No API call is done, instead a message is composed requesting the current device ID from the navigation application. The client application keeps running until the navigation application returns a result in the form of a composed message in a message file. The result is then inspected and printed to the screen.

3.2. Format of the commands of the message files

The communication between the client application and the navigation application works via commands and responses written in files: The client application sends a command written in a message file to the navigation application, which sends back responses written in other files.

The string representation of the command is called the "protocol". The format of the commands should be simple pipe-separated ASCII, where the first parameter is the same as the name of the API call , but with the version number of the function appended to it. Currently, only V01 is defined as a version number for each call.

The other parameters are the same as the input arguments of the API call in ASCII.

After the communication object has been set up, a message is composed and sent to the navigation application.

mycomms->StartSendCommand();
mycomms->AppendArgument("GetUniqueDeviceIdV01");
MTomTomSession* session = mycomms->SendCommand();

The navigation application will then process this request, and send back a result. One can handle this asynchronously by checking if there is a return result, through:

mycomms->ReturnAvailable(session);

And if a result is pending, it can be read through StartReceiveCommand:

mycomms-> StartReceiveCommand(session);

The asynchronous calls can be converted into synchronous calls by simply waiting for the answer. The check through ReturnAvailable is not necessary, as StartReceiveCommand will check for a return result itself. So, if you call StartReceiveCommand directly, the calls are handled synchronously.

The session object does not have to be deleted, as StartReceiveCommand cleans it up.

After the result has been retrieved, it can be read through the same object.

mycomms-> NrReceiveFields();

returns the number of text fields returned, and

mycomms-> ReceiveField(index);

returns a pointer to the string representing the field with index "index" (which is zero-base). The fields of a structure are each dumped into a separate field.

In this case 3 fields are returned: The first field with index 0 contains the error information, the second field(index=1) contains the unique ID of the TomTom GO and the third field (index=2) is the length of the device ID.

3.3. File transportation layer

The communication works via message files with responses written back in other files, where the string representation of the command is the protocol.

The means of getting the string transported to the navigation application is called the “transportation layer”.

The file transportation layer works as follows:

There is a "client" and a "server" application for each call. For the TomTom GO navigation application, the name of the application is defined in sdkconstants.h by

#define TOMTOM_FILE_SERVER_NAME "TomTomNavigationServer"

External applications have to choose their own name (which has to be ASCII readable characters only).

The directory where the SDK communication files are located on the TomTom GO, is:

/var/run

A call sequence from the client to the server contains the following steps:

1) The client creates a text file with name

SenderName.ReceiverName.ClientProcessId.ClientOrdinal.message

where in this case:

2) After this file has been created, another file is created:

SenderName.ReceiverName.ClientProcessId.ClientOrdinal.finished

This indicates to the server that the file with extension "message" is ready to be read.

The server processes the command when it is suitable, and then returns the result in the same manner the request was sent.

Basically, the "SenderName" and "ReceiverName" swap places in the names of these files, because this time the server is sending a message and becomes the sender. The process ID and ordinal are those taken from the incoming call, so they are the same as the process ID of the client that made the request, and the ordinal decided upon by the client.