|Top Previous Next|
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.
For each function in the navigation, their API level is documented.
For the latest list of devices that support the Garmin Navigation API, please visit this link: https://www8.garmin.com/solutions/mobile-resource-management/supported-devices/
All devices supports level 2 of the navigation API, which includes the following functionality:
•3 simultaneous users.
•Message formatting using HTML tags.
NX32 and NX32L execution architecture devices also have support for the following levels:
API Level 8:
•Speed Limit Alerts
API Level 9:
API Level 12:
API Level 13:
API Level 14:
API Level 16:
•Support for 57600 baud.
API Level 17:
API Level 21:
•Show custom forms.
API Level 23:
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:
•Estimated Time of Arrival.
•Garmin Point of Interest.
•Speed Limit Alerts
This group is used for managing the navigation interface.
This group is used for maintaining the user ID and status with the user being the person operating the navigation device.
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.
This group is used for maintaining the destinations and the order of the destinations in the route.
Estimated Time of Arrival (ETA)
This group is used for handling the ETA updates.
This group is used for handling file transfers.
This group is used for maintaining waypoints with waypoints being user-defined points of interest.
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.
This group is used for configuring areas to avoid while routing.
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.
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.
The navigation interface has the following limitations:
•The number of user statuses is limited to 16.
•The number of quick messages is limited to 120.
•The number of user-defined replies is limited to 200.
•The number of destinations is limited to 20.