navOpen (Function)

Top  Previous  Next

Architecture:

X32 / NX32 / NX32L

Device support:

MX2, AX9, CX1 pro/flex/warp, SX1, MX2 turbo/encore/warp, AX9 turbo, NX-200, NX-400, NX-900

Firmware version:

1.40 (2.80: Baud rate) / 1.00.00

Nav. API level:

1


This function will open the navigation interface. Calling this function is required before the navigation interface can be used.

When calling this function, it is possible to specify the serial port (0/1) used for communication with the Navigation device.

Support for Navigation must be enabled in the RTCU device. Otherwise an error code will be returned when navOpen is called.

By using boardGetProfileX, it can be checked whether Navigation is supported.

Also see navClose for closing the navigation interface after having finished the operations.

 

When using the NMP, please also see nmpPower.

 

 

Using Unicode strings

 

Support for Unicode strings are included in the Navigation API so that text (messages, user IDs, etc.) can be in the local language rather than in English.

The problem with Unicode strings is that no other API in the RTCU supports Unicode directly.

This means that any function that takes a STRING parameter, outside of the navigation functions, cannot use a string received from the navigation device - except strFromMemory and strToMemory.

This limits handling of text from the navigation device in the RTCU to being sent to a server. Sending (and receiving) Unicode must be done as binary data - for example by using gsmSendPDU or gwSendPacket.

While it is not possible to enter Unicode text directly into a string variable, it can be done as a string of special characters (see STRING).

This approach requires 3 steps for each character:

1. Find the character at the Unicode homepage (www.unicode.org).

2. Encode the character into UTF-8 (Wikipedia gives a good description of this here: en.wikipedia.org/wiki/Utf-8).

3. Type in the special characters from step 2 (e.g. "$CF$86" for the Greek character "phi").

 

Unicode is controlled by the "Unicode" parameter specified with the call to navOpen.

 

 

Input:

port : SINT (0/1, Default: 1)

The serial port where the navigation device is connected (see serial port enumeration).

 

unicode : BOOL (Default: OFF)

ON:

Enables Unicode strings.

OFF:

Disable Unicode strings.

 

baud : DINT (0,9600,19200,38400,57600, Default: 9600)

The baud rate to communicate with. A value of 0 will be changed to 9600 baud.

Garmin devices that support API Level 16 can use both 9600 and 57600 baud, otherwise only 9600 baud is supported. If 57600 baud has been used on a Garmin device, it must be disconnected from power to restore the baud rate to 9600, e.g by removing it from the mount.

 

 

Returns: INT

0

- Success.

-1

- Navigation interface is already open.

-6

- Error opening serial port.

-11

- Navigation interface not enabled in device.

 

Declaration:

FUNCTION navOpen : INT;
VAR_INPUT
  port   : SINT := 1;
  unicode : BOOL := OFF;
  baud   : DINT := 9600;
END_VAR;

 

Example:

INCLUDE rtcu.inc
 
PROGRAM NavigationExample;
VAR
  rc : INT;
END_VAR;
 
  DebugMsg(message := "Initializing navigation...");
  rc := navOpen();
  IF rc <> 0 THEN
    DebugFmt(message := "Error: navOpen=\1", v1 := rc);
  END_IF;
 
  ...
 
  // Close the navigation interface
  navClose();
  ...
END_PROGRAM;