2.1. Example flash at start-up
2.2. Starting daemons in the background

4.1. Example capability file
4.2. Capability Files

5.1. Example command handler
5.2. Command handlers

1. Introduction

Now that you are able to compile applications for the TomTom GO and to set up communication between an external application and the navigation application, you need to configure the TomTom GO for launching those applications and for allowing some form of interaction.

The TomTom GO can be configured to launch applications at start-up. This way they can run as daemons in the background, waiting for commands to be sent by the navigation application, or the other way around.

Furthermore, the TomTom GO main menu can be extended with commands that, when selected, send a message to the external application. This is done through so-called capability files, which describe the application and additional commands. Selecting the command from the main menu will start up the application, if it wasn't already running.

This section explains how to configure the TomTom GO for application interaction, as well as how to include a command handler in the client application.

2. Launching applications at start-up

Client applications can easily be launched at start-up, allowing them to run as daemons in the background.

2.1. Example flash at start-up

Copy the following text into a file called 'cleanup.txt' or use the corresponding file from the /TomTomGO-SDK/examples/configuration_and_commands/ folder.

daemon|flash|

Copy the file to the root of the SD card.

Also, make sure the application 'flash' as created in "2.2. Example Synchronous API Call" is available in the root of the SD card. Restart the TomTom GO and see how 'hello' is being flashed on the screen at start-up!

2.2. Starting daemons in the background

At start-up, the navigation application searches for the following file in the root of the SD card:

cleanup.txt

This file will be processed before the navigation application does anything else.

The file can contain several commands. The command for launching an application, is:

daemon|«app»|

where

• daemon is the command for starting an application
• «app» is the name of the application, excluding the path to the root of the SD card.

If your application 'flash' is located in the directory /mnt/sdcard/myapps/, the command to give is daemon|myapps/flash| Please note that no special characters are allowed in the 'cleanup.txt' file.

The daemons will be started as soon as the navigation application has initialized control of the frame buffer.

3. Preconfiguration settings

The file 'cleanup.txt' which is read at start-up and can be used to launch applications, can contain additional pre-configuration commands. To clean up and install configuration settings at start-up, the following file configuration instructions can be put in the file:

rm|file|
cp|file1|file2|
silent|

where

• rm = remove a file
• cp = copy a file from one location on the SD to another
• silent = stop all debug output from the application on the console. This is useful when you set up communication over a serial connection with other computers.

This way files can be deleted or moved at start-up. For example, default ov2 files can be restored, or default configuration files for a certain map can be loaded, resulting in removing other users' home addresses, favourites, etc.

4. Launching applications from the menu

To be able to launch an application from the TomTom GO menu, the navigation application needs to know of its existence. This is done through so-called capability files.

4.1. Example capability file

In order to show how applications can be launched from the TomTom GO main menu, copy the following text into a text file called 'flash.cap' or use the corresponding file from the /TomTomGO-SDK/examples/configuration_and_commands/ folder.

Version|100|
AppName|flash|
AppPath|/mnt/sdcard/|
AppMainTitle|example flash|
AppPort|2001|
COMMAND|CMD||none.bmp|Flash Hello!|

Please note that the full path to the root of the SD card is /mnt/sdcard/ and should be mentioned in the AppPath line.

On the TomTom GO, copy the file to directory SdkRegistry/ from the root of the SD card. Also, make sure the application 'flash' you have created in "2.2. Example Synchronous API Call" is available on the root of the SD card.

Restart the TomTom GO and browse through the main menu. An icon with description "Flash Hello" will have been added to the main menu and when selecting it, "Hello" will be flashed on the screen.

4.2. Capability Files

The SDK allows for the main menu to be extended with user-defined icons and descriptions that can send commands to an external application. This is achieved with capability files, which describe the application and additional commands.

The capability file is a text file with extension CAP that must be put in the following directory from the root of the SD card (first time SDK-users will probably have to create this directory):

SdkRegistry/

Please note that the full path to this directory is /mnt/sdcard/SdkRegistry/

The registry directory basically contains all the information about an application that the navigation application needs in order to communicate with it. Every external command can have an associated icon and description to be displayed in the menu.

The .CAP file has the following format:

Version|«version number»|
AppName|«app exe name»|
AppPath|«app path»|
AppMainTitle|«app main title»|
AppPort|«port»|
«cmd line 1»
«cmd line 2»
...
«cmd line n»

where:

• «version number» is the format version number of the capability file. Currently the version number is 100.
• «app exe name» is the name of the executable file of the external application
• «app path» is the default path to the executable, including the path to the root of the SD card
• «app main title» is the title of the main window of the external application. This title is there for historical reasons and will not show on the TomTom GO.
• «port» the TCP/IP port the external application will listen to when trying to receive commands from other applications(TCP/IP is not supported yet).
• «cmd line 1» through «cmd line n» contain the descriptions of the external commands

The line that describes an external command has the following format:

COMMAND|«cmd type»|«cmd name»|«cmd bmp file»|« menu title»|

where:

• «cmd type» is the command type. This can be either "CMD" or "GEO".
• «cmd name» is the name of the external command as stored in requests
• «cmd bmp file» is the name of the optional .BMP file that contains the icon for the external command. The file must be located in the directory /mnt/sdcard/SdkRegistry/. The format of this file should be 90x60 pixels, 8 or 24 bits per pixel for widescreen devices and 76x48 pixels, 8 bits per pixel for non-widescreen devices.
• «menu title» is the title of the external command to be displayed on the menu

Currently "CMD" and "GEO" are supported as a command type. The "CMD" type of command does not take any arguments and is added to the main menu. The "GEO" type of command takes 2 arguments, the map cursor's longitude and latitude respectively. These commands are added to the map cursor menu. More on handling commands is explained below.

Now that the navigation application knows of the existence of the external application it can send commands to it. This can be done by selecting the menu item which represents the command on the main menu.

When no commands are defined for the client application, «cmd name» must be empty:

COMMAND|CMD||"none.bmp"|Flash Hello!|

Selecting the menu item "Flash Hello!" from the main menu will run the application 'flash' as defined in «app exe name».

You can specify several capability files in \TomTom\SdkRegistry\ folder. Keep in mind that when the application will be looking for those files, the most recently created file would be found last. The modifications of an existing file (changing the name or editing the contents) would not affect this order.

5. Handling commands

Now that you know how to extend the main menu with commands to be sent to an external application, you need to include a command handler in your applications to handle those commands.

5.1. Example command handler

To demonstrate how to insert a command handler into the client application, copy the following code into a file called 'savecurrentposition.cpp' or use the corresponding file from the /TomTomGO-SDK/examples/configuration_and_commands/ folder.

#include <stdio.h>
#include <fstream>

#include "sdkconstants.h"
#include "TomTomAPI.h"
#include "MVirtualScreen.h"
#include "switcher-share.h"
#include "TomTomGoFileLayer.h"
using namespace std;
//Command Handler implementation class
class CExampleHandler : public MCommandHandlerInterface
{
public:
  virtual void HandleCommand(
         MTomTomCommunicationLayerInterface* aComms,MTomTomSession* aSession);
};
void CExampleHandler::HandleCommand(
         MTomTomCommunicationLayerInterface* aComms, MTomTomSession* aSession)
{
  //validate input
  if (aComms->NrReceiveFields() > 0 &&
          strcmp(aComms->ReceiveField(0),"SavePos") == 0)
  {
    //Give control back to the Navigation application
    MVirtualScreen::GetVirtualScreen().FlushFrameBuffer( false );
    if (CurrentForegroundPid() != 0)
      PushPidToForeground(0);
    //Get Current GPS coordinates from navigation app
    CTomTomAPI api(*aComms);
    CTomTomAPI::TError err;
    CTomTomAPI::TCurrentPositionInfo positionInfo;
    fstream f;
    f.open("/mnt/sdcard/Pos.txt", ios_base::app | ios_base::out);
    if(f.is_open())
    {
     f << "Current position:" << endl;
     if( !api.GetCurrentPosition(&err, &positionInfo) )
      if( !err.iError )
      {
       //Write results to file on sdcard
       f << positionInfo.iLongitude << "," << positionInfo.iLatitude << endl;
      }
      else
      {
       f << "GetCurrentPosition() error " << err.iError << endl;
      }
     else
     {
      f << "GetCurrentPosition() error" << endl;
     }
    f.flush();
    f.close();
   }
  }
}
int main()
{
  CExampleHandler myhandler;
  //poll the navigation application for commands
  for(;;)
  {
    usleep(100000);
    CTomTomFileLayer::ProcessEvents("savecurrentposition", myhandler);
  }
}

Compile it and copy it to the root of the SD card.

In addition, copy the following text into a file called 'savecurrentposition.cap' or use the corresponding file from the /TomTomGO-SDK/examples/configuration_and_commands/ folder.

Version|100|
AppName|savecurrentposition|
AppPath|/mnt/sdcard/|
AppIconFile|none.bmp|
AppMainTitle|Example save Position|
AppPort|2001|
COMMAND|CMD|SavePos|none.bmp|Save Position|

Copy it to the directory /mnt/sdcard/SdkRegistry/ on the SD card. Restart the TomTom GO and browse through the main menu. Selecting the newly added menu item "Save Position" will start the application 'savecurrentposition' and send the command "SavePos" to it. A user-defined command handler will then process the command and create a file called 'Pos.txt' in the root of the SD card with information on the current position.

5.2. Command handlers

When selecting "Save Position" from the menu, the command "SavePos" is being sent over to the application 'savecurrentposition'.

The client application 'savecurrentposition' will handle the command: the user-defined command handler will execute its code in response to the application command.

In the example, the main application keeps running in an endless for-loop, polling the navigation application for commands:

for(;;)
{
   usleep(100000);
   CTomTomFileLayer::ProcessEvents("savecurrentposition", handler);
}

where function 'usleep()' suspends execution of the calling process for 100.000 microseconds.

The method ProcessEvents, defined for the class CTomTomFileLayer, processes the event for the application 'savecurrentposition' and executes the handler "myhandler":

CTomTomFileLayer::ProcessEvents("savecurrentposition", myhandler);

Note that the first argument must match the application name, so if you named the example file differently, change the argument to the name of your application.

The command handler "myhandler" will actually take care of handling the command. It is declared as an instance of the user-defined class CExampleHandler:

CExampleHandler myhandler;

The class CExampleHandler defined for the handler object is inherited from the class MCommandHandlerInterface:

class CExampleHandler : public MCommandHandlerInterface
{
public:
  virtual void HandleCommand(
          MTomTomCommunicationLayerInterface* aComms,MTomTomSession* aSession);
};

When the command "SavPos" is being sent from the navigation application to the client application, the command handler will handle the command and execute its code in response to the command.

void CExampleHandler::HandleCommand(
          MTomTomCommunicationLayerInterface* aComms, MTomTomSession* aSession)
{
...
}

The communication object "aComms" can be processed and read out with a number of methods defined for its class MTomTomCommunicationLayerInterface. For more information on composing messages and reading out composed messages, see:

Format of the commands of the message files

First the input is validated by inspecting the argument list of the communication object with NrReceiveFields and ReceiveField:

   	  if (aComms->NrReceiveFields() > 0 &&
                           strcmp(aComms->ReceiveField(0),"SavePos") == 0)
  {
    ...
  }

If the first field equals "SavePos", the first action to take is forcing the daemon in the background and pushing the navigation application to the foreground:

ForceBackground();
if (CurrentForegroundPid() != 0)
    PushPidToForeground(0);

Then the communication object can be used for sending API calls to the navigation application:

    CTomTomAPI api(*aComms);
    CTomTomAPI::TError err;
    CTomTomAPI::TCurrentPositionInfo positionInfo;
    api.GetCurrentPosition(&err, &positionInfo);

For more information on API calls, see:

Supported API calls

The latitude and longitude of the current position can then be read out from the positionInfo struct. The result is written to the file 'Pos.txt' in the root of the SD card:

    //Write results to file on sdcard
    fstream f;
    f.open("/mnt/sdcard/Pos.txt", ios_base::app | ios_base::out);
    if(f.is_open())
    {
      printf("open worked\n");  // only works with the console version of the Navigator Application
      f << positionInfo.iLongitude << "," << positionInfo.iLatitude << endl;
      f.flush();
      f.close();
    }

The file 'Pos.txt' in the root of the SD card will contain the longitude and latitude of the current position.