FileInterface
From OpenTom
Contents |
Interfacing TomTom Go through files
Compatibility
All tests have been done with TTGO version 5.202. Previous versions might not work.
Summary
TTGO includes a communication protocol based on files, where the communication between TTGO and an external application can be based on messages written to appropriate files with responses written back in other ones. This method is in addition to the standard C++ API described in the TTGO SDK5 and allows communication between TTGO and programs written in any language. Chapter 3.3 of TTGO SDK describes the "File transportation layer". This wiki page describes how to easily implement Linux shell scripts exploiting the File transportation layer.
It is necessary to analyze the GOSDK documentation in order to understand the specifications of the File transportation layer. In summary, the external program must create two files in sequence: first
/var/run/SDK.TomTomNavigationServer.<PID>.<REQUEST>.message
including the query; then
/var/run/SDK.TomTomNavigationServer.<PID>.<REQUEST>.finish
including the word "finish" (without double quotes and with all letters lowercase).
Both files must be saved to /var/run. The string SDK is the name of the external program (and can be substituted with any other string, provided that the same is used for queries and responses by the same external program).
As soon as TTGO verifies existence of the “finish” file, it processes the query command included in the “message” file, then deletes both request files and generates in sequence the following two ones: first
/var/run/TomTomNavigationServer.SDK.<PID>.<REQUEST>.message
including the related response message, then
/var/run/TomTomNavigationServer.SDK.<PID>.<REQUEST>.finished
including the word “finish”.
Notice the swap of the “SDK.” substring in the pathname of the request and response files.
<PID> and <REQUEST> should be small unsigned integers unequivocally identifying the request/response. For example, <PID> can be the process identifier of the program performing the query, while <REQUEST> can be an ordinal number identifying the specific request inside the external application.
The external program should wait for the generation of the “finished” file produced by TTGO, then read the content of the related “message” file, then delete both of them.
Messages should be ASCII strings with fields separated by “|” and terminated by “|” followed by the null ascii character; in other terms, they are composed in the following way:
query verb|optional argument 1| optional argument 2|optional argument n|<0x00 ascii>
Numeric arguments are represented in ascii. No <CR> or <LF> is needed at the end.
The word "finish" should simply be terminated by a linefeed (e.g., <0x00 ascii> is not needed in this case).
Also the generated response message contains one or more fields separated by “|”. The first value is a digit indicating the API status: 0 is OK, while a negative number (e.g., -4 or -5) is an error (ref. to the GOSDK documentation for the related description); all other arguments are related to the specific query.
Notice that, after a reset (pressure of the hard reset button, activation of of the USB link, management of the SD card), no SDK is processed until the first valid information is retrieved from the GPS device. Simply the query files are left unprocessed in the /var/run directory.
In general, the queries are processed if TTGO can calculate a route. If it freezes a route calculation waiting for a fix, it will not process any SDK request too.
As soon as the first valid GPS information is registered by TTGO, the SDK file processing starts and any subsequent query works, independently from the quality of the GPS signal. Suspend, resume events and soft boots (e.g., inserting the SD card or unplugging the USB connector) are generally not affected by any freezing.
Following this, asynchronous methods are strongly suggested. This means that any loop waiting for a response file should be either controlled by a timeout or possibly avoided (might be fast or can take long periods).
Basic examples
For example,
echo –e "FlashMessageV01|<message content>|<duration in milliseconds>|\0\c"
produces a valid message (\0 is the ASCII 0 terminator, while \c avoids the newline generation).
The following example retrieves the current position fetched by TTGO from the GPS device or cached by TTGO:
echo –e " GetCurrentPositionV01|\0\c" >/var/run/SDK.TomTomNavigationServer.1.1. message
(the content in hex is: 47657443757272656E74506F736974696F6E5630317C00)
Remember to generate the “finish” file after the query file (the string finish in hex should be: 66696E6973680A). In our example:
echo finish>/var/run/SDK.TomTomNavigationServer.1.1.finished
will work.
The produced files are
/var/run/SDK.TomTomNavigationServer.1.1.finished
including the word “finish”,and
/var/run/SDK.TomTomNavigationServer.1.1.message
with content
"0|1|1075553|4584492|0|222|."
where 0 means correctly executed command, 1 means valid position, then the following fields follow: latitude, longitude, speed and direction in degrees.
The query GetApplicationVersionV01|\0x00 will generate the response 0|5.202|5302|\0x00.
Other examples:
ShowCoordinatesOnMap|longitude|latitude|\0x00 NavigateToFavorite|nr|\0x00 NavigateToCoordinates|latitude|longitude|title|\0x00
In order to start SDK applications from menu buttons, TTGO generates the following files:
/var/run/TomTomNavigationServer.<program name and arguments>.<PID>.1.message
including the program name and arguments and
/var/run/TomTomNavigationServer.<program name>.<pid>.1.finished
including the word finish.
At least the following API are expected to be processed:
GetRouteCoordinatesV01 StopApplicationV01 GetApplicationVersionV01 FlashMessageV01 GetDataSetInfoV01 GetUniqueDeviceIdV01 NavigateToCoordinatesV01 NavigateToFavoriteV01 NavigateToAddressV01 ShowAddressOnMapV01 ShowCoordinatesOnMapV01 ShowRectangleOnMapV01 GetLocationInfoV01 GetLocationInfoExV01 GetRouteInfoV01 ChangeSettingV01 SwitchMapV01 SetNavigatorPropertyV01 GetCurrentPositionV01 GeocodeV01 GeocodeExtendedV01 ClearFavoriteV01 SetFavoriteV01 GetFavoriteV01 MakePoiVisibleV01 AddPoiV01 DeleteClosestPoiV01 DeleteAllPoiV01 MakeUserPoiVisibleV01 MoveClosestPoiV01 BringNavigatorToForegroundV01 SwitchToNavigatorViewV01 EnableExternalGPSInputV01 DisableExternalGPSInputV01
For the list of valid API, check the GOSDK5 documentation.
Check also this file for a description of the API: http://www.tomtom.com/lib/doc/ttnavsdk3_manual.pdf
Check also this file http://www.pocketnavigation.de/board/attachment.php?attachmentid=19753 for a list of the TTGO5 SDK Functions.
Further Examples
The following script displays the date (flash message) for eight seconds:
#!/bin/sh echo -e "FlashMessageV01|`date`|8000|\0\c" >"/var/run/SDK.TomTomNavigationServer.$$.1.message" echo finish>"/var/run/SDK.TomTomNavigationServer.$$.1.finished"
The following script queries the current coordinates and displays them on the TTGO screen for 7 seconds:
#!/bin/sh echo -e "GetCurrentPositionV01|\0\c">"/var/run/SDK.TomTomNavigationServer.$$.1.message" echo finish>"/var/run/SDK.TomTomNavigationServer.$$.1.finished" for i in 1 2 3 4 5 6 7 8 END do test –s /var/run/TomTomNavigationServer.SDK.$$.1.finished && break sleep 1 done Message=`sed 's/|/-/g' "/var/run/TomTomNavigationServer.SDK.$$.1.message" 2>/dev/null` test $i = END –o ! “$Message” && Message=”Timeout expired or error occurred” echo -e "FlashMessageV01|$i_$Message|7000|\0\c">"/var/run/SDK.TomTomNavigationServer.$$.2.message" echo finish>"/var/run/SDK.TomTomNavigationServer.$$.2.finished"
# this shows a method to fetch the generated data into a shell script for further processing
SdkRetCode= SdkGCPUpdate= SdkGCPLongitude= SdkGCPLatitude= SdkGCPSpeed= SdkGCPDirection= SdkGCPOther=
{ # Fetch data from the SDK response
OIFS="$IFS"
IFS='|'
read SdkRetCode SdkGCPUpdate SdkGCPLongitude SdkGCPLatitude SdkGCPSpeed SdkGCPDirection SdkGCPOther
IFS="$OIFS"
} >/dev/null 2>&1 <"/var/run/TomTomNavigationServer.SDK.$$.1.message"
echo "SdkRetCode=$SdkRetCode SdkGCPUpdate=$SdkGCPUpdate SdkGCPLongitude=$SdkGCPLongitude SdkGCPLatitude=$SdkGCPLatitude SdkGCPSpeed=$SdkGCPSpeed SdkGCPDirection=$SdkGCPDirection SdkGCPOther=$SdkGCPOther">/mnt/sdcard/sample.txt
The examples can be executed with a CAP file placed in the SdkRegistry directory, referenced by the tomtom.mnu file in the same directory. Notice that this only complies with TTGO version 5.202. Previous versions will not work.
Example of CAP file:
Version|100| AppName|<shell script>| AppPath|<shell script pathname>/| AppIconFile|<shell bitmap icon>.bmp| AppMainTitle|<not used>| AppPort|2001| COMMAND|CMD|<shell script>|<shell bitmap icon>.bmp|<shell description shown by TTGO>|
tomtom.mnu should then include the related SDK reference:
MENUITEM|TASK_SDK1|
