Protocol.def

The following is an actual Protocol.def file. Note that text proceeded by an apostrophe is NOT processed by TileLogic, and is considered a comment. Comments are used for explainations and for user notes.

This section explains and defines the format for definitions required by TileLogic. Definitions contain initialization messages, data formats, and most importantly - message formats and key data placement (shown by inserting equates).

A definition must start with #DEFINE, YOURNAME and end with #ENDDEF. Whatever you replace "YOURNAME" with, will be loaded into the protocol dropdown box, of the COMMUNICATIONS PORT SETTINGS window.

'TILELOGIC PROTOCOL.DEF

'PROTOCOL DEFINITION SCRIPTS

'##### BASIC FORMAT #####

' NOTE TEXT PRECEEDED BY AN APOSTROPHE IS CONSIDERED A REMARK AND IS IGNORED.

' All directives begin with a "#".

' All FIELD equates begin with a "%"

' Each protocol definition must fall within a block structure which begins with "#DEFINE, ANYNAME "

' (ANYNAME is the name of the definition, and will be shown in the "PORT SET" dialog.

' This file is parsed at startup for definition names)

'#DEFINE, ANYNAME

'....YOUR DIRECTIVES....

'#ENDDEF

FAILURE TO PROPERLY STRUCTURE THESE DIRECTIVES WILL PRODUCE AN ERROR ON PROGRAM START, AND FAILING DEFINITIONS WILL NOT BE LOADED INTO THE PROTOCOL CHOICES IN THE protocol dropdown box, of the COMMUNICATIONS PORT SETTINGS window.

This section explains and defines the equates required by TileLogic.

Equates are simply "place markers" which tell TileLogic what type and where information is located within a GPS message.

'##### FIELD EQUATES #####

' EQUATES are the values that TileLogic "picks" from the GPS messages being sent by hardware.

' Equates are always preceeded by a percent (%) sign.

' REQUIRED EQUATES must all be defined, or the protocol definition will fail.

' OPTIONAL EQUATES will not cause a definition to fail, but the user may not have important information displayed.

' REQUIRED EQUATES:

''%ELAPSED.....SOME MESSAGES RETURN THE TIME ELAPSED SINCE THE BEGINNING OF THE WEEK

' OR

'%UTC.........NMEA TYPE FORMAT HR:MIN:SECS. 1 OF THESE MUST BE SPECIFIED!

'%LATITUDE

'%LONGITUDE

'%ELEVATION

'%DGPSAGE.....Differential data correction age. Basically the seconds since last update.

'%PDOP........Positional Dillution of Precision (3D) Highly important to monitor.

'%FIXTYPE.....Fix type

'-----!! REQUIRED IF USING #LLFORM "NMEA" !!------------------------------------------------------------

'%EW

'%NS

'----- OPTIONAL, BUT RECOMMENDED------------------------------------------------------------------------

'%BASEID

'%SATELITES...Number of satelites being tracked

'%HDOP........Horizontal dilution of precision

'%VDOP........Vertical dilotion of precision

'%FIXTYPE.....

'%HEADING.....Heading deg from North

'%MPHKPH......Speed in mph or kph, depends on #UNITS specified (see below)

'%FPSMPS......Speed in Feet/sec or Mtrs/sec, depends on #UNITS specified (see below)

This section explains and defines the directives use by TileLogic. Directives tell TileLogic what to do, or how to process data. Think of directives as commands.

'##### DIRECTIVE DEFINITIONS #####

' DIRECTIVES command

' Note: in the explainations below, replace "<text>" with corresponding valid parameters. Do not user "<" or ">".

'#INITRESPONSE, <expected response to recieved command>

' The response FROM the receiver that should be returned upon success.

' NOTE: THE RESPONSE MUST PRECEED THE #INIT!

' Example:

' #INITRESPONSE, OK

'#INIT, <user initialization command>

'Initialization string to be sent when initializing port. This is where you can specify anything

'to the receiver, but most important, specify the messages required.

' Example:

'#INIT, UNLOGALL

'#UNITS, <type>

' The UNITS the RECEIVER outputs.

' METRIC

' ENGLISH [default]

'Example:

'#UNITS, METRIC

'#LLFORM, <type>

' Latitude / Longitude format.

' NMEA = NMEA format (3959.422, 08848.0916)

' DEC = Decimal format (40.1234523, -88.353545) [default]

' DMS = Deg mins secs (40 39 24, 88 34 23)

'Example:

'#LLFORM, NMEA

'#MSGID, <CHAR>

' Character that designates a message identifyer typically "$" OR "#" See receiver documentation!

'Example:

'MSGID, $

'#CRCID

' Character that designates a CRC value. Typically "*", See receiver documentation!

'Example:

'#CRCID, *

'#CRC

' Cyclic Redundacy CHECK. A METHOD FOR insuring DATA IS NOT corrupt. No DEFAULT assumed.

' 32 = 32 Bit CRC

' 8 = 8 Bit CRC (typical NMEA)

'Example:

'#CRC, 32

'#MSG, <message from hardware with field equates inserted>

' The core directive. The first FIELD IS the MESSAGE NAME, followed by each DATA FIELD

' Outputted by that message.

' This is where the equates must be positioned to express the field location for that data type.

' NOTE: Unused field positions must be held with a 0 or a space.

' The number of messages required will vary, however all REQUIRED equates must be allocated.

' Note that it is not required to fill unused fields in a message with zeros ONLY when the last

' equate for that message as been allocated.

'#HDRCHAR

' Character which designates END OF HEADER. Some messages provide a "header" generally

' that is the same for each message, generally proceeded by a special character. To

' allow FOR this specify this char >> PRIOR << to defining the 1st #MSG. Then define the

' WHOLE message, HEADER AND ALL, include the header character (ex. ";") in the appropriate

' place. FILL unused fields WITH zeros but do make sure to account for all positions.

' Once defined all messages are assumed to use the same. (otherwise it wouldn't be a header)

' Special note, there may be information that you pick out of the header (SEE OEMV below). ONLY

' Define that field for 1 message. Usually your main message. If you define this field in all your

' messages, TileLogic will ONLY use the last definition.

'Example:

'#MSG, GNGGA, %UTC, %LATITUDE, %NS, %LONGITUDE, %EW, %FIXMODE, %SATELITES, %HDOP, %ELEVATION, 0, 0, %DGPSAGE, %BASEID

'#CLSCMD

' Command to send to reciever prior to closing the comm port.

'Example:

'#CLSCMD, UNLOGALL

'BEGIN CHANNEL SETTING DEFINITION - (OPTIONAL)

' --- Directives for defining channel changes (Changing Rover channel to match Base)

' The following commands allow a drop down box to be populated, and selected by the user, when it is

' necessary to change the base channel.

' These commands MUST be in the sequence show below, however there may be more or less of the

' "CHANNELSEND" commands depending on the hardware. Just note that the commands identified will

' be sent in the order given.

'#CHANNEL?, <values list (separated by commas) that will be used to replace "?" below>

'This is the actual value to use to set the channel of the rover in the #CHANNELSEND directive below.

'Example:

'#CHANNEL?, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9

'#CHANNELSHOW, <value list corresponds to #CHANNEL? list separated by commas>

'The values to load into the channel drop down box, shown to the user, and which

'correspond to the values in #CHANNEL?.

'The number of values in the lists for CHANNELSHOW and CHANNEL? must be equal.

'Example:

#CHANNELSHOW, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19

'[If the user chooses "12" from the Channel drop down box, ? will be replaced by

' "2" where identified in a CHANNELSEND directive.]

'Note: This scheme allows a RF freq identifed as "10" to correspond to the same freq that the

'rover calls channel "0". i.e. the Base channel is set to "10", the user selects "10" which sets the

'rover '0" - the same freq, different id.

'#CHANNELUSE, <default list index of channel>

'Example:

'#CHANNELUSE, 1

'[Will default to (if previously unspecified) first list value of #CHANNEL? and #CHANNELSHOW]

'#CHANNELSEND, <command string to send to com port>

'The command(s) to send to com port for changing channels.

'use "?" wherever the value from the list is to be replaced.

'Example:

'#CHANNELSEND, sendHEX com2 3 2B2B2B

'#CHANNELSEND, SEND COM2 ATHP?

'#CHANNELSEND, sendHEX com2 6 41544850330A

'#CHANNELSEND, SEND COM2 ATCN

' ---- SPECIAL [WAIT] PSUEDO DIRECTIVE

'[WAIT]<ms>

'When supplied to a #INIT or #CHANNELSEND directive, pauses the specified milliseconds before

'sending further commands to the com port

'Example:

'#INIT, [WAIT]100

'[Note: "(Pausing 100ms)" will be displayed in the "RAW COMMUNICATIONS DATA" window.]

'################################################################################################################

The following are actual definitions, which can be used as it, or modified.

'##### SUPPLIED DEFINITIONS FOR USE, AND EXAMPLE: #####

' Error checking: Some error checking is performed, but the user should follow the format below for best results.

CAUTION: Please carefully verify that all data is correct when you've built a new protocol. For example, it is easy to get HDOP, VDOP, PDOP switched around, and they return similar values. PDOP is of highest value to a RTK setup when identifying precision of instruments.

TIP: Receiver documentation is usually available online. It's easiest to get the document in electronic format, then cut and past the messages into this document, insert the equates in the proper fields, and zero out the rest. This is much easier than trying to manually enter the messages, and count the field offsets!

Please note the #MSG directive is where the data location is defined, using EQUATES. Note how the equates are specified and placed, using zeros as place holders for insignificant information.

#DEFINE, NMEA2 'SAME AS TILELOGIC'S BUILT IN GENERIC NMEA DEFINITION.

#INIT, [WAIT]1000

#UNITS, METRIC

#LLFORM, NMEA

#MSGID, $

#CRCID, *

#CRC, 8

#MSG, GPGGA, %UTC, %LATITUDE, %NS, %LONGITUDE, %EW, %FIXMODE, %SATELITES, %HDOP, %ELEVATION, 0, 0, %DGPSAGE, %BASEID

#MSG, GPGSA, %FIXTYPE,0,0,0,0,0,0,0,0,0,0,0,0,0,0,%PDOP, %HDOP, %VDOP

#MSG, GPVTG, %HEADING,0,0,0,0,0,%MPHKPH

#ENDDEF

#DEFINE, NMEA GLONASS 'DEFINITION FOR NMEA OUTPUT IN GLONASS MESSAGE MODE.

#INIT, [WAIT]500

#LLFORM, NMEA

#UNITS, METRIC

#MSGID, $

#CRCID, *

#CRC, 8

#MSG, GNGGA, %UTC, %LATITUDE, %NS, %LONGITUDE, %EW, %FIXMODE, %SATELITES, %HDOP, %ELEVATION, 0, 0, %DGPSAGE, %BASEID

#MSG, GNGSA, %FIXTYPE,0,0,0,0,0,0,0,0,0,0,0,0,0,0,%PDOP, %HDOP, %VDOP

#MSG, GNVTG, %HEADING,0,0,0,0,0,%MPHKPH

#ENDDEF

#DEFINE, OEM6_BESTPOS

#INITRESPONSE, NONE

#INIT, UNLOGALL

#INIT, [WAIT]20

'#INIT, FRESET

#INIT, [WAIT]20

#INITRESPONSE,<OK

'#INIT, SERIALCONFIG COM1 57600 N 8 1 N ON

#INIT, SERIALCONFIG COM2 9600 N 8 1 N OFF

#INIT, [WAIT]100

#INIT, INTERFACEMODE COM2 RTCMV3 NOVATEL OFF

#INIT, [WAIT]20

#INIT, INTERFACEMODE COM1 NOVATEL NOVATEL ON

#CHANNEL?, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9

#CHANNELSHOW, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19

#CHANNELUSE, 1

'begin list of commands - keep in sequence to be sent!

#CHANNELSEND, SENDHEX COM2 3 2B2B2B

#CHANNELSEND, [WAIT]100

#CHANNELSEND, SEND COM2 ATHP?

#CHANNELSEND, SENDHEX COM2 6 41544850330A

#CHANNELSEND, [WAIT]200

#CHANNELSEND, SEND COM2 ATCN

'------END CHANNEL SETTING DEFINITION------------

#INITRESPONSE,<OK

#INIT, [WAIT]20

#INIT, POSAVE OFF

#INIT, FIX NONE

#INIT, UNDULATION USER 0

#INIT, MOVINGBASESTATION DISABLE

#INIT, SETBASERECEIVERTYPE LEICA

#INIT, SBASCONTROL DISABLE

#INIT, RTKSOURCE RTCMV3 ANY

#INIT, RTKTIMEOUT 15

#INIT, ECUTOFF 10

#INIT, GLOECUTOFF 10

#INIT, RTKDYNAMICS DYNAMIC

#INIT, RTKQUALITYLEVEL EXTRA_SAFE

#INIT, RTKTIMEOUT 30

#INIT, LOG BESTPOSA ONTIME .1 0 NOHOLD

#INIT, LOG PSRVELA ONTIME 1 0 NOHOLD

#INIT, SAVECONFIG

#CLSCMD, UNLOGALL

#LLFORM, DEC

#UNITS, METRIC

#MSGID, #

#CRCID, *

#CRC, 32

#HDRCHAR, ;

#MSG, BESTPOSA,0, 0, 0, 0, 0,%ELAPSED, 0, 0, 0; 0, %FIXMODE, %LATITUDE, %LONGITUDE, %ELEVATION,0,0,%HDOP, %VDOP, %PDOP,%BASEID, %DGPSAGE,0,%SATELITES

#MSG, PSRVELA, 0, 0, 0, 0, 0, 0, 0, 0, 0; 0,,0,0,%FPSMPS,%HEADING

#ENDDEF