Application Program Interface (API)
Contents
1. OEMStar Firmware Reference Manual 1 3 1 Firmware Compatibility Firmware support for the API has been designed for backwards compatibility For example if the firmware loaded on to the receiver supports version 15 of the API an application built using version 14 of the API will execute correctly However if the application uses a newer version of the API than OEMStar Application Program Interface API User Guide Rev 1 9 1 4 10 the firmware supports the additional or updated functionality provided by the API may not be available A description of the changes made to the API since the last version can be found at the beginning of the API header file To determine what version of the API your firmware supports log the APPLICATIONSTATUS message which is described further in Section 4 2 on page 23 Compiler compatibility has been tested successfully up to Green Hills Multi V4 2 4 You must run OEMStar firmware version 1 100 or higher lt The API library and header files are named with the firmware version For example L6X010100RN0000 apia Materials Provided As part of the OEMStar API Development Kit the following is provided An OEMStar API library file OEMStar_api a An OEMStar API header file OEMStar_api h One sample project for the Greenhills Multi e Two Windows command line utility programs TOSREC and DATABLK which format the executable for use with a NovAtel receiver e NovAtel s WinLoad utility2. Hex 4 H 72 11 CR LF Sentence terminator ASCII only Recommended Input ASCII Example LOG APPLICATIONSTATUSA APPLICATIONSTATUSA COM1 0 75 0 UNKNOWN 0 1 814 004c0000 33 14 6576 1 FALSE 0000 0000 00000000 datalogdisplay 1 000 2012 Feb 01 13 50 42 3eb207 8 OEMStar Family Application Program Interface API User Guide Rev 1 4 3 DATABLK Parameters Used in Logs Many of the fields captured in the APPLICATIONSTATUS log and the DB_US ERAPP or DB_USERAPPAUTO entry of the VERSION log are set to the values entered for parameters used by the DATABLK utility The table below provides a list of these parameters and the matching log fields For more information about the DATABLK utility see Section 2 2 3 1 on page 15 Table 5 DATABLK Parameters Used in Logs Matching Log Field DATABLK parameter VERSION APPLICATIONSTATUS lt Name gt model name lt SNKey gt psn N A lt Version gt sw version version lt Compile Date gt comp date compile date lt Compile Time gt comp time compile time a Only valid for the DB_USERAPP or DB_USERAPPAUTO entry in the log 4 4 Determining the Version of WinLoad To load an application on to the receiver release 102 or higher of WinLoad must be used To determine the version of WinLoad you currently have run the application and select About from the Help menu fe WinLoad File Settings cla The v
3. A log has been created to capture the details of any application loaded on to the receiver The details of this log follow All formats and standard fields such as the header are explained further in the OEMStar Firmware Reference Manual Many of the fields are set to values entered for use by the DATABLK utility as described in Section 4 3 on page 25 lt The time indicated in the log header is the time when the application status was last changed for example the time when the application was started or stopped OEMStar Family Application Program Interface API User Guide Rev 1 23 24 APPLICATIONSTATUS Log Type Asynch API Application Status Information Message ID 520 Field Field Type Data Description Format eyes Beat 1 header Log header H 0 2 api version The version of the API that the Ulong 4 H currently loaded firmware supports Flag indicating whether the application 3 running 1s io zos where Enim 4 H 4 1 TRUE The base address in RAM the running The number of bytes in RAM the 2 size ol ga tic application is Ulong 4 Melz running 6 name The name of the application Char 16 16 H 16 7 version The version of the application Char 16 16 H 32 The date the application was compiled 8 compile date rm is tree eters for the month eg Char 12 12 48 JAN 9 compile time Phe time the application was compiled Chart12 12 H 60 10 XXXX 32 bit CRC ASCII and Binary only
4. TN NovAtel OEMSTAR Application Program Interface API OM 20000131 Rev 1 Proprietary Notice OEMSTAR Application Program Interface API User Guide Publication Number OM 20000131 Revision Level 1 Revision Date 2012 2 2 Proprietary Notice The software described in this document is furnished under a licence agreement or non disclosure agreement The software may be used or copied only in accordance with the terms of the agreement It is against the law to copy the software on any medium except as specifically allowed in the license or non disclosure agreement No part of this manual may be reproduced or transmitted in any form or by any means electronic or mechanical including photocopying and recording for any purpose without the express written permission of a duly authorized representative of NovAtel Inc The information contained within this manual is believed to be true and correct at the time of publication OEMStar and FlexPak are trademarks of NovAtel Inc NovAtel is a registered trademark of NovAtel Inc All other brand names are trademarks of their respective holders Copyright 2012 NovAtel Inc All rights reserved Unpublished rights reserved under International copyright laws Printed in Canada on recycled paper Recyclable XY eo amp 2 OEMStar Application Program Interface API User Guide Rev 1 Table of Contents Software License 5 Warranty Policy 7 Foreword 8 SCOPE id il
5. Software or that it will be error free The Software is furnished AS IS and without warranty as to the performance or results you may obtain by using the Software The entire risk as to the results and performance of the Software is assumed by you See product enclosure if any for any additional warranty 7 Indemnification NovAtel shall be under no obligation or liability of any kind in contract tort or oth erwise and whether directly or indirectly or by way of indemnity contribution or otherwise howsoever to the Licensee and the Licensee will indemnify and hold NovAtel harmless against all or any loss dam age actions costs claims demands and other liabilities or any kind whatsoever direct consequential special or otherwise arising directly or indirectly out of or by reason of the use by the Licensee of the Software whether the same shall arise in consequence of any such infringement deficiency inaccu racy error or other defect therein and whether or not involving negligence on the part of any person 8 Disclaimer and Limitation of Liability a THE WARRANTIES IN THIS AGREEMENT REPLACE ALL OTHER WARRANTIES EXPRESS OR IMPLIED INCLUDING ANY WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE NovAtel DISCLAIMS AND EXCLUDES ALL OTHER WARRANTIES IN NO EVENT WILL NovAtel s LIABILITY OF ANY KIND INCLUDE ANY SPECIAL INCIDENTAL OR CONSEQUENTIAL DAMAGES INCLUDING LOST PROFITS EVEN IF NovAtel HAS KNOWLEDGE OF THE
6. To determine the current model and firmware version of the receiver read the VERSION log To do so send the following command to the receiver LOG VERSION Read the output provided specifically the 1st and 4th fields after the word GPSCARD The first field provides the model and the fourth field indicates the version of firmware loaded on the receiver In the example below the model is LXGMTSA and the firmware version field shows L6X010101RNO0000 lt VERSION COM 0 68 0 UNKNOWN 0 5 263 004c0000 3681 6576 lt 2 lt GPSCARD LXGMTSA BHD09320088 M6XV1G 4 00 TT L6X010101RN0000 L6XD10004DBG004 2011 Mpr 02 12 15 96 lt DB_USERAPP datalogdisplay 0 1 000 2012 Feb 01113 50 42 GPS card field Model field Firmware version field In this example the model field ends with an A and the firmware version field reads L6X010101RN0000 therefore an application can be loaded on to the receiver If an update to the firmware and or model is needed instructions are provided in Section 3 1 2 and Section 3 1 3 OEMStar Family Application Program Interface API User Guide Rev 1 19 3 1 2 Updating the Firmware To update the firmware to a version that supports the API obtain the following from NovAtel Customer Support The firmware update file with version 1 100 or higher An update authorization code WinLoad is also required to load the firmware on to the receiver and is included with the A
7. and Accessories Ninety 90 Days Software Support One 1 Year Date of sale shall mean the date of the invoice to the original customer for the product NovAtel s responsibility respecting this warranty is solely to product replacement or product repair at an authorized NovAtel location only Determination of replacement or repair will be made by NovAtel personnel or by technical personnel expressly authorized by NovAtel for this purpose THE FOREGOING WARRANTIES DO NOT EXTEND TO I NONCONFORMITIES DEFECTS OR ERRORS IN THE PRODUCTS DUE TO ACCIDENT ABUSE MISUSE OR NEGLIGENT USE OF THE PRODUCTS OR USE IN OTHER THAN A NORMAL AND CUSTOMARY MANNER ENVI RONMENTAL CONDITIONS NOT CONFORMING TO NOVATEL S SPECIFICATIONS OR FAIL URE TO FOLLOW PRESCRIBED INSTALLATION OPERATING AND MAINTENANCE PROCEDURES II DEFECTS ERRORS OR NONCONFORMITIES IN THE PRODUCTS DUE TO MODIFICATIONS ALTERATIONS ADDITIONS OR CHANGES NOT MADE IN ACCORDANCE WITH NOVATEL S SPECIFICATIONS OR AUTHORIZED BY NOVATEL III NORMAL WEAR AND TEAR IV DAMAGE CAUSED BY FORCE OF NATURE OR ACT OF ANY THIRD PERSON V SHIPPING DAMAGE OR VI SERVICE OR REPAIR OF PRODUCT BY THE DEALER WITH OUT PRIOR WRITTEN CONSENT FROM NOVATEL IN ADDITION THE FOREGOING WAR RANTIES SHALL NOT APPLY TO PRODUCTS DESIGNATED BY NOVATEL AS BETA SITE TEST SAMPLES EXPERIMENTAL DEVELOPMENTAL PREPRODUCTION SAMPLE INCOMPLETE OR OUT OF SPECIFICATION PRODUCTS OR TO RETURNED PRODUCTS IF THE OR
8. for loading the application on to the receiver OEMStar Application Program Interface API User Guide Rev 1 Chapter 2 Designing and Building the Application 2 1 Designing the Application When designing an application for an OEMStar receiver it is important to have an understanding of some of the key features of the API which are explained in the sections below lt Review the sample application provided with the API for more information on how to design your application to work with the receiver firmware 2 1 1 Working with the Virtual Ports When communicating through one of the physical or virtual ports the application must be designed to either Read all data sent to the port or e Configure the port to not transmit data and disable response generation This is necessary because any incoming data will remain in a buffer until it is read and will not be automatically discarded if more data arrives resulting in a build up of waiting data To disable transmission and response generation at the port use the INTERFACEMODE command with the NONE mode for the txtype field and OFF for the responses field Refer to the OEMStar Firmware Reference Manual for more information on this command 2 1 2 Using the GPIOs The OEMStar receiver provides LV TTL general purpose input output GPIO signals that can be used by your application The API header file provides more details on the functions available to control an
9. in the record S ERIEN 2 excluding the lt type gt and lt length gt fields The 2 3 or 4 byte address at which to load the AREAS AGr Or8 contents of the data field in memory lt data gt variable Executable code or memory loadable data The least significant byte of the one s complement lt checksum gt 2 of the sum of the values represented by the length the address and the data fields There are 3 types of S records used for OEMStar applications as shown in Table 2 below Table 2 S Record Types Type Description so Header record Used by WinLoad to determine how to load the application as described in Section 2 2 3 2 on page 17 S3 Data record S7 End of file record Typically each S record file consists of one or more header records followed by one or more data records concluded with a single end of file record 2 2 2 2 Using TOSREC The TOSREC utility is a Windows command line program To run the application enter the following in a command window tosrec lt infile gt where lt infile gt is the name of the file to be converted The name of the S record file to be generated can be specified using the following option trigger o lt outfile gt where lt out file gt is the name of the output file Examples of command strings to run the utility are given below tosrec input elf tosrec input elf o output hex 14 OEMStar Family Application Program Interface API User G
10. the commands and logs already provided by the OEMStar a wide variety of applications can be created 1 2 Features The OEMStar API provides the following features e The ability to open physical ports on the receiver to interface with external devices e Support for three virtual ports allowing you to directly send commands to and receive logs from the receiver firmware e Support for multiple tasks with varying priority levels e Message queuing functionality Support for semaphores and mutexes e The ability to control many of the receiver s general purpose input output GPIO lines e Access to receiver time e Pulse width modulation control for receivers that support it Refer to the API header file for more information on the features provided by the API 1 3 Requirements to Build and Run an Application In addition to the items listed in the API Development Kit see Section 1 4 the following is required to develop and run an application on an OEMStar receiver e A NovAtel supported compiler Currently Green Hills Software C C compilers are supported The Green Hills Software C C compiler is available in the Green Hills Multi 2000 Integrated Development Environment e OEMStar receiver loaded with an API enabled software model See Section 3 1 on page 19 for more information about setting up the receiver for loading an application PC with a serial port and a serial cable to load the application on to the receiver
11. IGINAL IDENTIFICATION MARKS HAVE BEEN REMOVED OR ALTERED THE WARRANTIES AND REMEDIES ARE EXCLUSIVE AND ALL OTHER WARRANTIES EXPRESS OR IMPLIED WRIT TEN OR ORAL INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT NESS FOR ANY PARTICULAR PURPOSE ARE EXCLUDED NOVATEL SHALL NOT BE LIABLE FOR ANY LOSS DAMAGE EXPENSE OR INJURY ARISING DIRECTLY OR INDIRECTLY OUT OF THE PURCHASE INSTALLATION OPERATION USE OR LICENSING OR PRODUCTS OR SERVICES IN NO EVENT SHALL NOVATEL BE LIABLE FOR SPECIAL INDIRECT INCIDEN TAL OR CONSEQUENTIAL DAMAGES OF ANY KIND OR NATURE DUE TO ANY CAUSE There are no user serviceable parts in the GPS receiver and no maintenance is required When the status code indicates that a unit is faulty replace with another unit and return the faulty unit to NovAtel Inc Before shipping any material to NovAtel or Dealer please obtain a Return Material Authorization RMA number by calling NovAtel Customer Support at 1 800 NOVATEL in North America or 1 403 295 4900 elsewhere Once you have obtained an RMA number you will be advised of proper shipping procedures to return any defective product When returning any product to NovAtel please return the defective product in the original packaging to avoid shipping damage OEMStar Family Application Program Interface API User Guide Rev 1 Foreword Scope This document contains sufficient information on working with the Applicat
12. O Printed in Canada on recycled paper OM 20000131 Rev 1 2012 02 02
13. PI package Follow the procedure given in the HowTo txt file provided with the update file to upgrade the firmware 3 1 3 Authorizing a Model with the API Option 3 2 20 To authorize a model with the API option enabled contact NovAtel Customer Support to obtain the necessary authorization code and use the AUTH command to add the code to the receiver Refer to the OEMsStar Firmware Reference Manual for more information on this command Loading the Application Once the receiver is set up with the necessary model and firmware version the application can be loaded in to non volatile memory on the receiver using release 102 or higher of the WinLoad utility This utility is provided as part of the API package or can be obtained from NovAtel Customer Support By reading the S records added using the DATABLK utility WinLoad automatically knows where and how to place the application in memory so it does not interfere with the operation of the main receiver firmware Therefore loading the application can be done using the same method as that used when loading GPS firmware with the following exceptions The application HEX file should be selected rather than a standard firmware HEX file e An authorization code is not needed and therefore you will not be prompted for one For more information on using WinLoad to load the application follow the procedure given in the OEMStar Installation and Operation User Manual making adjustme
14. POTENTIAL LOSS OR DAMAGE b NovAtel will not be liable for any loss or damage caused by delay in furnishing the Software or any other performance under this Agreement c NovAtel s entire liability and your exclusive remedies for our liability of any kind including lia bility for negligence for the Software covered by this Agreement and all other performance or non performance by NovAtel under or related to this Agreement are to the remedies specified by this Agreement 9 Governing Law This Agreement is governed by the laws of the Province of Alberta Canada Each of the parties hereto irrevocably attorns to the jurisdiction of the courts of the Province of Alberta 10 Customer Support For Software UPDATES and UPGRADES and regular customer support con tact the NovAtel GPS Hotline at 1 800 NOVATEL U S or Canada only or 1 403 295 4900 Fax 1 403 295 4901 e mail to support novatel ca Web site http www novatel com or write to NovAtel Inc Customer Support Department 1120 68 Avenue NE Calgary Alberta Canada T2E 8S5 6 OEMStar Family Application Program Interface API User Guide Rev 1 Warranty NovAtel Inc warrants that its Global Positioning System GPS products are free from defects in materials and workmanship subject to the conditions set forth below for the following periods of time OEMStar Receiver Cards One 1 Year OEMStar Based Receivers One 1 Year NovAtel Antennas One 1 Year Cables
15. a hs golden dare 8 CONVENTIONS e seana A A a e cido as ae 8 CUSIOMER SUPDOM es E E E 8 1 Introduction 9 WT II a o e Selene uals tad ad ge 9 U2 RETON E 13 sees A ad 9 1 3 Requirements to Build and Run an Application ccccceeecceecececeeeeeeeseeeeentecaeeeeeeeeeenees 9 1 3 1 Firmware Compatibility eyrna aT A ATA 9 1 4 Materials Provided a a A Ee e aa Aaaa 10 2 Designing and Building the Application 11 2 1 Designing the Application oooooooooccccncncccncccconoononcnnncnnnnnncnnnnnnnno nn nnnnnnnnn cnn cnn nnnnnnn nn nnnnnnnnnnnnns 11 2 1 1 Working with the Virtual PortS oooooonincnnconocncncccccccocnnonnonnnnnnncnnnnnnnnnnnnnnnnnnnncnnnnnnnnnn 11 2 1 2 Using the GPIOS nisasie ii dd a NE did 11 2c IANPUL P rameterS aiii ii dd Sage es ae ded ded eee ea id 12 2 1 4 Auto Start Applications oooooooncccnnnccncocconconcconnnncnnnnnncnnnnnnnnnnnnnnnnnnnnnnnnnnnnn nananet entent 12 2 2 Building the AppliCation ooooooocococccnncnccccnnocononnoononnonnnnnnnnnnnnnnnnnnn nn nn n cnn cnn nn nr nn ara nn n nn eared 13 2 2 1 Building the Application Using a Supported Compiler ooooooococococnccncccccccocconcncccnnnnnnn 13 2 2 2 Converting Binary to S RecordS ocoocccccconooccccccononncncnnnnnnnnnconnno nc cnc nana nana rnnnn rra 13 2 2 3 Adding Information for Loading the Application oooooonnnccccnnnnoccccconaanccncnnanancncncnnns 15 2 2 4 Automating Utility Execution ooooonnonccccnnnooccccnnnnoonncccnnnonccnnnnnnnnn
16. ating the name of the application lt Version gt 14 non null characters or less A string indicating the version of the application lt SNKey gt 14 non null characters or less A string indicating the serial number or key for the application Can also be used to set an application parameter See Section 2 1 3 2 on page 12 for more details lt Platform gt 14non null characters or less A string of comma separated platforms the application is targeting For OEMStar valid options are M6XV1G and M6XV1 OEMStar Family Application Program Interface API User Guide Rev 1 15 Parameter Valid Values Description Any valid date in the format Optional field to specify the date the yyyy mmm dd wheremmmis application was compiled If no value is three letters for the month eg provided the PC s current date will be JAN used Compile Date Optional field to specify the time the Any valid time in the format application was compiled If no value is hh mm ss provided the PC s current time will be used Compile Time An example command string to run the utility is given below datablk input hex output hex raw 2 1 SampleApp 1 00 1234 M6XV1G See Section 4 3 on page 25 for more information about how the values entered for the DATABLK parameters are used in the receiver logs 16 OEMStar Family Application Program Interface API User Guide Rev 1 2 2 3 2 Records Use
17. cnc canon ncnnnnnnnnnnccnnnnnns 17 3 Loading and Controlling the Application 19 3 1 Setting Up the Receiver onean ii nc 19 3 1 1 Determining the Current Model and Firmware VersiON ooonncccnnnnnnnccccnnnnccccccnnnnnncnnnns 19 3 1 2 Updating the Firmwatre 2cc c c cccceneeccdecsteeeedegsnneesedeesneneseeseseneneddebaneeeeeesbaanecdeevianees 20 3 1 3 Authorizing a Model with the API Option oooooooccccnnnoccccccnnnocccccnonononc conan nrrnnnnnnnnn nn 20 3 2 Loading the Application S aerei enen nadas sides alasaced i n alias salaadintedsdendt radiata 20 3 3 Controlling the Application ccceececeeececcecceeeeeeeeeeeseeeecaeaaecaeeeeeeseeeeseeeececscacnaeaeeeeeeeeeess 21 3 321 Starting the Application A 21 3 3 2 Stopping the Application ccccccccceeeeeeeeeeeeecneeeeeeeeeeeeeeeesececceeeeeeeeeeeeeeeeteeesecaeeas 22 3 3 3 Removing the Application c ectooiicoon dilata tinto lacas ceectadadlageute dads aaae 22 4 Additional Information 23 4 1 Determining the Version of the Loaded Application cecceceeeeeeeeeeeeeeesenneeeeeeeeees 23 4 2 Logging the Application StatUS ooooonnnnnccnnnnnnnccccnnnnoncccnnnn corn c cinco nao ana EAA RERE i aatia 23 4 3 DATABLK Parameters Used in LOS 0ooccccconnocccccnonconcccnnnanonccnnnnon ono nn nn nan nc cnn nn rca 25 4 4 Determining the Version Of WinL02d oooooninoncccnonncocccccnononncccnnnnnr nc cnn non rn cnn nan rnrnnrnnnnnn 25 A Technical Specification
18. d By WinLoad DATABLK adds three header records that are required by the WinLoad utility when loading the application The records provide the following information to WinLoad The target platform of the OEMStar receiver M6XV1 and or M6V1G e The version of the application e In which data block to load the application block 0 2 2 4 Automating Utility Execution The Greenhills Multi development environment supports execution of specified programs after compilation This feature can be used to automate execution of TOSREC and DATABLK By doing so the binary executable will automatically be converted to S records and the necessary records for loading will be added The resultant executable can be loaded directly on to the receiver without further manipulation Please see below if you are developing with Greenhills Multi To automate this with the project open in Multi select Set Options from the Edit menu F CASrcAM6_UtiN OEMStarAPIDevKit example_code datalogdisplay d File Build Connect Debug Tools Windows Help 3 Edit Ctrl E E E Create Subproject Create File Add File Into datalogdisplay gp Remove datalogdisplay gpj Search in datalogdisplay gp 4 LL Show Full Paths Highlight Selections Set Build Target Set Build Macros Advanced OEMStar Family Application Program Interface API User Guide Rev 1 17 Expand the Advance option under the Option Categories on the left side of the wi
19. d read these GPIOs The sections below indicate which GPIOs are provided and Section A 1 on page 26 gives the electrical specifications for those GPIOs 2 1 2 1 OEMStar The following GPIO pins available on the OEMStar e GPIOO e GPIO1 e GPIO3 e PV output only See Pin Outs on page 27 for additional information OEMStar Family Application Program Interface API User Guide Rev 1 11 2 1 2 2 FlexPak G2 with OEMStar There are two GPIO pins available on the FlexPak G2 with OEMStar e PV GPIO1 The OEMStar Installation and Operation User Manual provides the location of this pin and details of internal pull up or pull down resistors The electrical specifications for this pin are given in Table 7 on page 26 Note For OEMStar Pin 5 PV line and Pin 6 GPIO1 line 2 1 3 Input Parameters There are two methods that can be used to pass parameters to an application as discussed in the following sections 2 1 3 1 Command Line Entry The application can be designed to accept a single unsigned 32 bit parameter which is then entered as part of the command string for starting the application This parameter could be used for example to set the output serial port used by the application For more information about entering a parameter when starting the application see Section 3 3 1 on page 21 See Section 2 1 4 for a note about the use of command line entry input parameters with auto start applications 2 1 3 2 DATABLK Ent
20. eep confidential and use your best efforts to prevent and protect the contents of the Soft ware from unauthorized disclosure or use OEMStar Family Application Program Interface API User Guide Rev 1 5 Software License 5 Term and Termination This Agreement and the rights and licences hereby granted shall continue in force in perpetuity unless terminated by NovAtel or Licensee in accordance herewith In the event that the Licensee shall at any time during the term of this Agreement i be in breach of its obligations hereunder where such breach is irremediable or if capable of remedy is not remedied within 30 days of notice from NovAtel requiring its remedy then and in any event NovAtel may forthwith by notice in writ ing terminate this Agreement together with the rights and licences hereby granted by NovAtel Licensee may terminate this Agreement by providing written notice to NovAtel Upon termination for any reasons the Licensee shall promptly on NovAtel s request return to NovAtel or at the election of NovAtel destroy all copies of any documents and extracts comprising or containing the Software The Licensee shall also erase any copies of the Software residing on Licensee s computer equipment Ter mination shall be without prejudice to the accrued rights of either party including payments due to NovAtel This provision shall survive termination of this Agreement howsoever arising 6 Warranty NovAtel does not warrant the contents of the
21. ersion is shown in the Loader Version field in the About dialog box 3 WinLoad Release 58 NovAtel Loader Version 1 0 0 0 58 Library Version 1 0 0 3 Nov 13 2006 11 40 52 Copyright c 2000 2006 NovAtel Inc OEMStar Family Application Program Interface API User Guide Rev 1 25 INTO Technical Specifications A 1 A 1 1 Input Output A 1 2 OEMStar Table 6 OEMStar GPIO Electrical Specifications Voltage 0 lt Vir lt 0 8 VDC GPIO Electrical Specifications Current LL 0 1 mA Voltage 2 0 lt Viy lt 3 6VDC High Current If gt 0 mA Vor lt 0 4 VDC loLmax 8 mA Vog gt 2 7 VDC Ionmax 8 mA FlexPak G2 with OEMStar Table 7 FlexPak G2 with OEMStar GPIO Electrical Specifications 26 Voltage 0 lt Vir lt 0 8 VDC Current LL 0 1 mA High Voltage 2 0 lt Viy lt 3 6VDC Current Tip 0 mA Vor lt 0 4 VDC loLmax 8 mA Von gt 2 7 VDC Tonmax 8 mA OEMStar Application Program Interface API User Guide Rev 1 A 1 3 Pin Outs Pin 19 Pin 1 CT COLOCO Pin 20 Pin 2 Figure 1 Top view of 20 Pin Connector on the OEMStar Signal Behavior Descriptions Pin GPIOO Input Output User configurable I O pin 7 GPIO1 Input Output User configurable I O pin 8 GPIO3 Input Output User configurable I O pin 17 PV Output Output shows a good so
22. ild file provided with the sample application as a template This build file has the necessary settings for a variety of options including the application format and target which should not be altered However the following can be changed to customize the project either by directly editing the file or using the interface provided by the compiler The name of the output file The files included in the project 2 2 2 Converting Binary to S Records When loading the application on to the receiver the S record format which is described in Section 2 2 2 1 is used Therefore once the application has been built the resulting binary ELF file must be converted to S record format The TOSREC utility is provided to complete this conversion 2 2 2 1 S Records The S record format is an industry standard for encoding programs or data files in a printable form that allows for ease of transfer between devices An S record is an ASCII character string consisting of five fields in the format shown below lt type gt lt length gt lt address gt lt data gt lt checksum gt The S record fields all use hexadecimal format except for the lt t ype gt field The fields are described in Table 1 below OEMStar Family Application Program Interface API User Guide Rev 1 13 Table 1 S Record Fields Length Field Characters Description lt type gt 2 The type of S record as described by Table 2 The number of character pairs
23. ion Program Interface API to be able to develop applications for NovAtel s OEMStar receivers It does not provide specific details of the functions offered by the API but rather information on building and loading applications Details of the API functions can be found in the API header file Conventions The conventions used throughout this document are lt gt Text displayed between lt and gt indicates a variable parameter Text displayed between and indicates an optional parameter lt This is a notebox that contains important additional information In tables where no values are given such fields should be assumed to be reserved for future use Customer Support If you have any questions or concerns regarding the OEMStar API use one of the following methods to contact NovAtel Customer Support Call the NovAtel Hotline at 1 800 NOVATEL U S amp Canada or 1 403 295 4900 international Fax 1 403 295 4901 Write NovAtel Inc E mail support novatel com Customer Support Department Web site http www novatel com 1120 68 Avenue NE Calgary AB Canada T2E 8S5 8 OEMStar Family Application Program Interface API User Guide Rev 1 Chapter 1 Introduction 1 1 Overview The Application Program Interface API allows you to develop specialized C C applications to further extend the functionality of your OEMStar receiver By using the functions provided by the API along with
24. lution or valid GPS position 20 when high a The VIN and LNA_PWR inputs are protected against damage or latch up due to ESD by bi directional Transient Voltage Suppressor TVS devices GPIO lines are protected by undi rectional TVS devices and series resistors OEMStar Application Program Interface API User Guide Rev 1 27 A antenna warranty 7 API building 13 designing 11 Features 9 loading 13 Project configuration 13 Requirements 9 API Development Kit Contents 10 Application Auto start 21 controlling 20 loading 20 removing 22 starting 20 status 23 stopping 22 Application Program Interface API Description 9 APPLICATIONSTATUS log 23 Automating utility 17 Auto Start Applications 12 C cables warranty 7 Command Line Entry 12 Compiler compatibility 10 conventions document 8 Converting binary 13 Customer Service 8 Customer service contact information 8 D DATABLK 15 DATABLK Entry 12 DATABLK utility 25 e mail 8 F Firmware updating 19 version 19 G GPIO 11 Specs 26 Green Hills Software 9 Greenhills automating 17 I Input Parameters 12 R Receiver set up 19 rollover GPS week 8 S scope 8 S Record 14 support 8 T TOSREC 14 V Version log 23 Virtual ports 11 W warranty 7 Web site 8 WinLoad 15 records 17 version 25 28 OEMStar Application Program Interface API User Guide Rev 1 NovAtel Recyclable D
25. mands to Execute After Associated Command via Shell Additional Output Files Select One Project Extension List Pass Through Arguments In the Commands to Execute After Associated Command box enter the command strings to run the utilities Press OK to save the changes Commands to Execute After Associated Command via Shell Value Set In Utilities tosrec exe o out hex exe datal datalogdisplay gpj Utilities datablk exe out hex datalogdisp datalogdisplay gpj x datalogd ay g datalogdisplay gpj cmd exe e del out hex x OK Cancel The next time the application is built the utilities will automatically be executed as specified 18 OEMStar Family Application Program Interface API User Guide Rev 1 Chapter 3 Loading and Controlling the Application Once the application has been built and converted to S record format with the necessary S records added the application can be loaded on to the receiver A Windows based utility named WinLoad has been created to assist with loading the firmware 3 1 Setting up the Receiver In order to load and run an application the receiver must have e A model with the API option enabled and e Version L6X010101RN0000 or higher of firmware loaded The following sections provide information on how to determine if your receiver meets these criteria and how to update it if it does not 3 1 1 Determining the Current Model and Firmware Version
26. n in bytes Coe In order to specify the stack size a value must be lt stack gt 2004 entered for both the lt parameter gt and o 20000 e priority gt fields as well If a value is not specified the default of 10000 is used 3 3 1 1 Auto Start Applications If 5 was entered for the lt ComponentEnum gt field when running the DATABLK utility the application will be set to auto start Therefore when the receiver is first powered the application will begin running An alternate method for setting an application to automatically start is by using the SAVECONFIG command after the application has been started When this is done the application will automatically start whenever the receiver is powered up as long as the saved receiver configuration is present in memory However as soon as the FRESET command is issued the configuration will be lost and the application will not automatically start When an application is configured to auto start using the method described in Section 2 1 4 on page 12 it will not be affected by the state of the receiver configuration OEMStar Family Application Program Interface API User Guide Rev 1 21 3 3 2 Stopping the Application To stop the application enter the following command application stop This command can be used to stop either standard or auto start applications 3 3 3 Removing the Application To remove the application from non volatile memory enter the f
27. ndow Click on Advanced Project Options under the Option Categories on the left side of the window On the right side of the window under Build Options in Category double click on Commands to Execute After Associated Command Basic Options All Options Modified Options Option Categories Project Binary Code Generation El Optimization Temporary Output Directory ic 1 DANKL Debugging Temporary Output Delete Preprocessor Input Languages c cxx El C C Compiler Non Standard Output Suffix Not Accepted Assembler Source Directories Relative to Top Level Project El Linker Intermediate Output Directory Relative to This File El Compiler Diagnostics Binary Output Directory Relative to Top Level Project exe HTML Compiler Binary Output Directory Relative to This File O Advanced nn Dependencies Relative to Source Directory Advanced Target Options Dependencies Relative to This File anced Proje options Dependencies Relative to Top Level Project Advanced Optimization Options Self Dependency Advanced Debugging Options Suppress Dependencies El Advanced Preprocessor Options Output Filename for Generic Types El Advanced C C Compiler Options Append Default Extension to Output Filename Advanced Assembler Options Commands to Execute Before Associated Command El Advanced Linker Options Commands to Execute Before Associated Command via Shell Advanced Support Diagnostics Options Commands to Execute After Associated Command Com
28. nts for the selection of the application file rather than the firmware file and the absent authorization code prompt lt Only one application can be loaded on to the receiver at any one time However functions are provided to allow for multiple tasks running within the application Please see the provided library files for more information OEMStar Family Application Program Interface API User Guide Rev 1 3 3 Controlling the Application The operation of the application can be controlled by using the APPLICATION command as discussed below 3 3 1 Starting the Application Once the application has been loaded on to the receiver enter the following command string to start the application application start lt parameter gt lt priority gt lt stack gt The values that can be entered when starting an application are described in the table below Table 4 APPLICATION START Parameters Parameter VEUC AETI Description ds Any ulong ee arr ane to specify an input parameter for the value pp we f If a value is not specified the default of O is used Optional field to specify the priority of the application in relation to system tasks See the API a ties at eee header file for details p Y 0 to 16 In order to specify the priority a value must be entered for the lt parameter gt field as well If a value is not specified the default of 1 is used Optional field to specify the size of the stack to be used by the applicatio
29. ollowing command application remove lt The application is not recoverable when removed from non volatile memory so be sure to use this command with care 22 OEMStar Family Application Program Interface API User Guide Rev 1 Chapter 4 Additional Information 4 1 4 2 The following sections provide additional information that may be useful when working with OEMStar applications Determining the Version of the Loaded Application When an application is loaded on to the receiver the VERSION log provides information about the application When an application is loaded an additional entry is displayed in the VERSTON log with the type field showing DB_USERAPP for a standard application or DB_USERAPPAUTO for an auto start application All the parameters given in that entry apply to the application loaded on to the receiver An example of the log with a DB_ USERAPP entry is shown below lt VERSION COM1 0 68 0 UNKNOWN 0 5 263 004c0000 3681 6576 lt 2 lt GPSCARD LXGMTSA BHD09320088 M6XV1G 4 00 TT L6X010101RN0000 L6XD10004DBG004 2011 Mar 02 12 15 06 lt DB_USERAPP datalogdisplay 0 1 000 2012 Feb 01 13 50 42 For information on how to capture the VERSION log or the fields 1t contains refer to the OEMStar Firmware Reference Manual Section 4 3 on page 25 provides information on how some of the VERSION log fields are set by the DATABLK utility Logging the Application Status
30. rights and licences hereby agreed to be granted to you 2 Copyright NovAtel owns or has the right to sublicense all copyright trade secret patent and other proprietary rights in the Software and the Software is protected by national copyright laws international treaty provisions and all other applicable national laws You must treat the Software like any other copy righted material except that you may make one copy of the Software solely for backup or archival pur poses one copy may be made for each piece of NovAtel hardware on which it is installed or where used in conjunction with other NovAtel supplied software the media of said copy shall bear labels showing all trademark and copyright notices that appear on the original copy You may not copy the product manual or written materials accompanying the Software No right is conveyed by this Agree ment for the use directly indirectly by implication or otherwise by Licensee of the name of NovAtel or of any trade names or nomenclature used by NovAtel or any other words or combinations of words proprietary to NovAtel in connection with this Agreement without the prior written consent of NovAtel 3 Patent Infringement NovAtel shall not be liable to indemnify the Licensee against any loss sus tained by it as the result of any claim made or action brought by any third party for infringement of any letters patent registered design or like instrument of privilege by reason of the use or applica
31. ry Alternately the lt SNKey gt field set when the DATABLK utility is run on the executable can be used to store an input parameter which would then be read from the VERSION log by the application For more information about the lt SNKey gt field see Section 2 2 3 1 on page 15 Section 4 3 on page 25 provides more information about where the field is stored in the VERSION log 2 1 4 Auto Start Applications An application loaded on to an OEMStar receiver can be set to automatically start whenever the receiver is powered up This option is set using the lt ComponentEnum gt field of the DATABLK utility which is described in Section 2 2 3 on page 15 12 OEMStar Family Application Program Interface API User Guide Rev 1 lt When an application is configured to automatically start the input parameter is fixed as 0 the priority is set to 1 and the stack size is 10 000 See Section 3 3 on page 21 for more information 2 2 Building the Application Building the application in a format that can be loaded on to a receiver is a three step process 1 Build the application using one of the supported compilers 2 Convert the binary executable to S records 3 Add the S records necessary for loading the application Each of these steps is discussed in the sections that follow 2 2 1 Building the Application Using a Supported Compiler 2 2 1 1 Project Configuration With the Greenhills version 4 2 4 compiler use the bu
32. s 26 OEMStar Application Program Interface API User Guide Rev 1 3 Tables A a ON TE 14 O den stied id a E E EE A AE chededdel seetectas AEAN 14 DATABLEK PaM OIE S a a a e aa A a aa a aia sade dives ERN 15 APPLICATION START Parameters iga a e Ea a a araea aar 21 DATABLK Parameters Used in LO9S ooooocccccinnoccccccnononncccnnnanancncnonanon cnc cnn nan n cnn cnn nana nccnnnns 25 OEMStar GPIO Electrical Specifications oooooooocooncnnnncnccnnnnoconcoononccnncnnnnnnnnnnnnann nino nncnnnn 26 FlexPak G2 with OEMStar GPIO Electrical Specifications ccccesceeeceeceeeeeeeeeeees 26 4 OEMStar Family Application Program Interface API User Guide Rev 1 Software License BY INSTALLING COPYING OR OTHERWISE USING THE SOFTWARE PRODUCT YOU AGREE TO BE BOUND BY THE TERMS OF THIS AGREEMENT IF YOU DO NOT AGREE WITH THESE TERMS OF USE DO NOT INSTALL COPY OR USE THIS ELECTRONIC PRODUCT SOFTWARE FIRMWARE SCRIPT FILES OR OTHER ELECTRONIC PRODUCT WHETHER EMBEDDED IN THE HARDWARE ON A CD OR AVAILABLE ON THE COMPANY WEB SITE hereinafter referred to as Software 1 License NovAtel Inc NovAtel grants you a non exclusive non transferable license not a sale to where the Software will be used on NovAtel supplied hardware or in conjunction with other NovAtel supplied software use the Software with the product s as supplied by NovAtel You agree not to use the Software for any purpose other than the due exercise of the
33. tion of the Software by the Licensee or any other information supplied or to be supplied to the Licensee pursuant to the terms of this Agreement NovAtel shall not be bound to take legal proceedings against any third party in respect of any infringement of letters patent registered design or like instrument of privilege which may now or at any future time be owned by it However should NovAtel elect to take such legal proceedings at NovAtel s request Licensee shall co operate reasonably with NovAtel in all legal actions concerning this license of the Software under this Agreement taken against any third party by NovAtel to protect its rights in the Software NovAtel shall bear all reasonable costs and expenses incurred by Licensee in the course of co operating with NovAtel in such legal action 4 Restrictions You may not a copy other than as provided for in paragraph 2 distribute transfer rent lease lend sell or sublicense all or any portion of the Software except in the case of sale of the hardware to a third party b modify or prepare derivative works of the Software c use the Software in connection with computer based services business or publicly display visual output of the Software d transmit the Software over a network by telephone or electronically using any means except when downloading a purchased up grade from the NovAtel Web site or e reverse engineer decompile or disassemble the Software You agree to k
34. uide Rev 1 2 2 3 Adding Information for Loading the Application The WinLoad utility which is used to load the application on to the receiver reads information from the input file in order to determine how the application should be loaded This information is included in a special set of S records placed at the beginning of the file Once the application data has been converted to an S record format the DATABLK utility is used to add these necessary records 2 2 3 1 Using DATABLK The DATABLK utility is a Windows command line program To run the application enter the following string in a command window datablk lt In SREC File gt lt Out SREC File gt lt Compress gt lt Block gt lt ComponentEnum gt lt Name gt lt Version gt lt SNKey gt lt Platform gt Compile Date Compile Time Each of the parameters are described in the table below Table 3 DATABLK Parameters Parameter VENA VENTO Description lt In SREC File gt Any File name of input file lt Out SREC File gt Any File name of output file lt Compress gt Compress or Specifies whether or not the data will be Raw compressed The data block in memory in which the A F a application will be loaded into The type of application where 1 specifies lt ComponentEnum gt 1or5 a standard user application and 5 specifies an auto starting user application lt Name gt 14 non null characters or less A string indic
Download Pdf Manuals
Related Search