Introduction to iSuiteTM Software Development Kit Version 3
About iSuite SDK
The iSuite 3 SDK is a tool for GPS application developers
implementing iTrax based end user products. iSuite 3 SDK now
supports two development platform: iTrax03 Development
Kit and iTrax130 Development Kit.
This inctroduction gives some idea what can be accomplished
with iSuite SDK. For more information or if you have any
question, please contact support@fastrax.fi.
iSuite Architecture
The iSuite Software is portable excluding the completely
hardware dependent parts. Portability is based on independent
software task layout where tasks communicate using the iTalk
message passing protocol. The iTalk protocol supports routing,
for example over a serial port, enabling distributed
architectures and porting of the software tasks across
different processor environments. The message routing is
configurable and transparent to applications.
Schematic representation of the general task distribution is shown in this picture.
iSuite SW Stack and Custom Applications
The iSuite SDK contains a sample User Task, which traps certain iTalk messages offering easy intervention to message based events. This is an easy starting point to most customer specific applications.
To enable user interactions at specific moments of the execution, the iSuite offers predefined event hooks. Modifications in the User Task and event hook functions together with the versatile access to the iSuite libraries are in most cases sufficient to implement the required custom features.
For more demanding customization the iSuite SDK can be
installed to reveal more source code such as the main function
and the task bodies (including the message handlers). These
entry points enable modifications in the GPS processing and
messaging chain itself.
The SDK Professional Toolkits extend the programmability
even further. They include reference open source code for
modifying device drivers, supporting additional peripherals
such as LCD displays, modems, external sensors, AGPS etc.
User Task
The User Task is linked to the message passing chain so that it receives all the messages with final destination Monitor Task (outgoing iTalk messages). Monitro task is usually the GPS Workbench, but also custom monitor tasks can be implemented.
The default message handler in the User Task includes a switch case statement for all messages. By default there are no user actions. It is up to the user to fill in the functionality in desired way. Because the User Task is in the message passing chain it is responsible to finally pass the income message further to Monitor Task (default implementation).
It is not recommended to route the messages back into the
message chain in such a manner which would handicap the GPS
processing chain. For example modifying the pseudorange message
and sending it to back Navigation Task would result in
chaos.
There are actually three predefined User Task ID's, but only TASK_USER_1 is created by default and linked into the message chain.
User Task stack reservation and task priority modifications can be done through taskconf.h if necessary.
void FAR_CODE USER_NavFixMsgHandler(NAV_FIX_MSG *pMsg)
{
// Perform user navfix events here.
// Forward the message to the monitor task.
ITK_SendMsg(pMsg, TASK_MONITOR);
}
/// PSEUDO message handler function
void FAR_CODE USER_PseudoMsgHandler(PSEUDO_MSG *pMsg)
{
// Perform user pseudomsg events here.
// Example of ISYS_Signal
ISYS_Signal(TASK_USER_1, SIGF_USER_1);
// Forward the message to the monitor task.
ITK_SendMsg(pMsg, TASK_MONITOR);
}
Event Hooks
Immediate access to significant events is arranged through event hooks (callback functions). The empty default implementations can beare provided with SDK. The event hooks are called from the standard iSuite software, the call points are found in the open source code if so desired.Because the event hooks are in the context of the caller they use the stack of the calling task. Therefore the user is responsible of increasing the callers stack if necessary.
void FAR_CODE USER_EarlyStartup()
{
// User code
}
Flash File System
Flash file system is designed to enable easy access to extra persistent storage space. The usage and management of flash device is completely automated freeing user from worrying about flash device details.
Flash file system includes functions for:
1.Initializing and formatting the file system
2.Opening, closing, securing and deleting files
3.Reading, writing and seeking files
4.Reclaiming new space
5.Checking the amount of free space
This programming example should give an overview to power of the system:
FSH_File __y file;
WORD wResult;
// Create a new file (erases the earlier one)
wResult = FSH_Open(&file, FILE_PREVSTR,
FSH_OPEN_MODE_CREATE_ALWAYS);
if (wResult != FSH_SUCCESS)
{
// show an error message
_OutputFshErrMsg("OutPrev:", wResult);
}
else
{
// file opened.
WORD wLen;
wLen = strlen(str);
// save data.
FSH_Write(&file, (WORD*)str, wLen,
NULL);
// close the file
FSH_Close(&file);
}
Intervening the GPS processing
Figure below illustrates at the conceptual level the main tasks of the iSuite03 software, including the most important processing steps related to the navigation. The white boxes in the figure show the different navigation-related tasks in the system and the grey boxes show the main library calls. The arrows indicate the major data flows between the library calls. The functionality included in the while boxes (i.e. the top level code of each task) is available as source code in the SDK. Thus, it is possible to do very advanced modifications of the processing by modifying the data between the library calls - or even by entirely replacing some parts of the processing. As an example, adding application-specific RAIM functions would be possibly by modifying the flags associated with the pseudorange data just after the standard iSuite03 RAIM has been called.
Creating new tasks
New user tasks are easily created using existimg USER_1 task
as a template. SDK Provides walkthough style descriptions of
most common programming tasks .
Defining new messages
The iTalk messages are defined as C structures in a set of include files. New messages can be created easily by defining new messages structures and message identifiers. The necessary conventions to follow when defining new messages will be described in the user documentation.
Device drivers
Typically, device drivers consist of a set of library calls
to initialise and control the hardware, and possibly a number
of interrupt handlers. The iSuite03 SDK contains libraries for
controlling the interfaces of the iTrax03 (the SPI, UART, pulse
measurement interfaces, timers, and GPIO's). New devices
drivers can be built using these services. A number of device
drivers will be provided as source code for example purposes.
Implementing Custom Protocols
The easiest way to implement custom protocols is in the user task. By default, the serial ports are initialised to handle the NMEA and iTalk protocols. The application SW can replace the default initialisation and do the conversion between iTalk and custom protocols in the user task.Distributed Architectures
The iTalk subsystem allows the rerouting of messages to different nodes. This routing is transparent to the software, so the software operates normally in a distributed context, as long as some constraints are followed. In figure 1 the tasks which have to be routed together are grouped in boxes.
GPS Workbench is an example of a programs that natively
communicates with other iSuite tasks on iTrax receiver, but is
located on a different processor node.
