nav: Navigation

The Navigation API supports the implementation of advanced fleet management applications that integrate navigation, two-way messaging, driver identification, and Job dispatch capabilities.

The Job dispatch functionality includes advanced features such as support for routes with multiple stops, route optimization, and periodic Estimated Time of Arrival (ETA) notifications.

To use the Navigation interface, it is necessary to connect a supported Navigation device from Garmin or a PNM device from Logic IO.

The connection between the Garmin/PNM Navigation device is established through a serial port with a special interface cable available from Logic IO.

To enable a quick and easy overview of what functionality is supported by the navigation devices, the Navigation API is divided into levels.

Each level of the API is a group of functionality that is added to the functionality of the previous level(s). For example, a device with level 1 API support can only use the basic navigation functionality while a device with level 2 API support can use both the basic navigation functionality and the more advanced functionality that the level 2 API offers.

All devices supports level 2 of the navigation API, which includes the following functionality:

NX32 and NX32L execution architecture devices also have support for the following levels:

The specific API level supported depends on the specific Garmin device connected and only the latest devices supports all levels.

It is possible to determine the functionality available on a device by calling the navGetAPILevel function which returns the API level supported by the connected device.

Using a functionality not supported by the connected device will fail with an error code specifying that the feature is unsupported.

The illustration below shows the system architecture with the various components constituting a complete Fleet Management Solution:

For easy use and access, the Navigation API has been grouped into 12 logical categories:

Navigation Management

	•navOpen	Opens the navigation interface.
	•navClose	Closes the navigation interface.
	•navPresent	Queries whether a navigation device is present.
	•navVersion	Gets the version number of the software on the navigation device.
	•navGetAPILevel	Get the API level that a connected navigation device supports.
	•navDeviceSerial	Gets the serial number of a connected navigation device.
	•navWaitEvent	Waits for an event from the navigation interface.
	•navSetUIText	Customizes the text of the user interface in the navigation device.
	•navDeleteData	Deletes data from the navigation device.
	•navFix	Gets the current GPS position from the connected navigation device.
	•navRemoteReboot	Reboots the navigation device.
	•navSafeMode	Controls safe mode, where some menus are disabled while driving.

User Identification

This group is used for maintaining the user ID and status with the user being the person operating the navigation device.

	•navUserIDAuthenticate	Authenticates a received user ID.
	•navUserIDReceive	Reads a received user ID.
	•navUserIDReceiveX	Reads a received user ID with extra information.
	•navUserIDRequest	Requests the current user ID.
	•navUserIDSet	Sets the user ID in the navigation device.
	•navUserStatusDefine	Defines a user status item.
	•navUserStatusDelete	Deletes a user status item.
	•navUserStatusReceive	Reads a received user status.
	•navUserStatusRcvX	Reads a received user status with extra information.
	•navUserStatusRequest	Requests the current user status.
	•navUserStatusSet	Sets the user status in the navigation device.

Text messaging

This group is used for sending and receiving simple text messages to/from the navigation device.

Quick messages are predefined text messages in the navigation device so the user does not have to repeatedly type in common text messages.

User-defined replies allow the user to reply with something other than yes/no without sending a text message.

	•navMessageSend	Sends a text message to the navigation device.
	•navMessageDelete	Deletes a text message in the navigation device.
	•navMessageStatusReceive	Reads a received text message status.
	•navMessageStatusRequest	Requests the status of a text message.
	•navMessageReceive	Reads a received text message.
	•navMessageReceiveX	Reads a received text message with extra information.
	•navMessageQuickDefine	Defines a quick message in the navigation device.
	•navMessageQuickDelete	Deletes a quick message in the navigation device.
	•navMessageReplyDefine	Adds a user-defined reply in the navigation device.
	•navMessageReplyDelete	Removes a user-defined reply from the navigation device.
	•navMessageReplyReceive	Reads a received text message reply.
	•navPopupAlert	Shows an alert message on the navigation device.

Route Management

This group is used for maintaining the destinations and the order of the destinations in the route.

	•navStopSet	Adds a destination to the route.
	•navStopReceive	Reads a received destination status.
	•navStopRequest	Requests the status of a destination.
	•navStopSort	Sorts destinations by shortest path.
	•navStopIndexSet	Sets the position of a destination in the route.
	•navStopSetActive	Activates a destination.
	•navStopSetDone	Marks a destination as completed.
	•navStopDelete	Deletes a destination from the route.
	•navAutoArrival	Sets the criteria for the auto-arrival detection.
	•navStopRouteCreate	Begins the construction of a new route.
	•navStopRouteAbort	Cancels the construction of a route.
	•navStopRouteAddPoint	Adds a stop or a via point to a route.
	•navStopSetRoute	Sends the route to the navigation device.
	•navStopSetRouteFile	Sends a route from a file to the navigation device.

Estimated Time of Arrival (ETA)

	•navETAReceive	Reads a received ETA update.
	•navETARequest	Requests an ETA update.
	•navETAAutoSet	Enables or disables ETA events at regular intervals.
	•navETASetMode	Configure which ETA events to report.

File transfers

	•navGPITransfer	Starts to transfer a GPI file.
	•navGPIProgressReceive	Reads a transfer progress report.
	•navGPIRequestID	Requests the ID of the GPI file.
	•navGPIReceiveID	Reads a received GPI file ID.

Waypoint management

This group is used for maintaining waypoints with waypoints being user-defined points of interest.

	•navWaypointSet	Sets a waypoint in the navigation device.
	•navWaypointDelete	Deletes a waypoint from the navigation device.
	•navWaypointDeleteByCat	Deletes all waypoints that are part of the categories.

Sensor display

This group is used for displaying sensor data to the user. The sensor data can come from any source and does not necessarily have to be from an actual sensor.

Avoidance areas

	•navAvoidEnable	Enable or disable the support for avoidance areas.
	•navAvoidAreaCreate	Create or modify an avoidance area.
	•navAvoidAreaDelete	Delete an avoidance area.
	•navAvoidAreaEnable	Enable or disable an avoidance area.

Custom forms

This group is used for creating custom forms on the navigation device. These forms can then be filled out by the user on the navigation device and then be sent back to the RTCU. For more details, see Custom forms.

Speed Limit alerts

This group is used for configuring and reading Speed Limit Alerts, which are events that happens when the vehicle exceeds the speed limit.

Conversion

This group is used for converting data formats between the ones that are used in the navigation interface and the ones that are used in VPL.

Architecture of the Navigation API

The Navigation API is based on an asynchronous event-based model where solicited as well as unsolicited events from the Navigation device are automatically queued and delivered to the user application. The function navWaitEvent is used to return information about the various events that are arriving from the Navigation device. This model eliminates the requirement for the application to continuously poll for messages, and it also encourages the use of multithreading with the added benefits that come with this.

Events that are triggered by the application requesting various pieces of information from the Navigation device are therefore called solicited events. They can also be triggered by the Navigation itself, and if such is the case, they are instead called unsolicited events. A solicited event is for example when the application calls navStopRequest. navWaitEvent will then return with event# 5, and the application must use navStopReceive to read the actual stop status. An unsolicited event works exactly the same way as a solicited event, except that navStopRequest is not called by the application.

Please consult navWaitEvent for detailed information about the various events and how they are handled.

Using Unicode strings with the Navigation API

Support for Unicode strings are included in the navigation API, which means that text (messages, user IDs, etc.) can be in the local language rather than in English. For more information, please refer to navOpen.